From dbe796d5423d732efe6d062629dbc6c120d83650 Mon Sep 17 00:00:00 2001 From: github-actions <41898282+github-actions[bot]@users.noreply.github.com> Date: Tue, 19 Sep 2023 19:19:10 +0000 Subject: [PATCH] Update docs --- .changeset/afraid-walls-smell.md | 5 + .changeset/angry-ties-switch.md | 5 + .changeset/big-plums-cover.md | 4 + .changeset/blue-horses-do.md | 5 + .changeset/blue-scissors-design.md | 5 + .changeset/brave-lobsters-punch.md | 5 + .changeset/bright-tomatoes-sing.md | 5 + .changeset/chilled-spiders-attack.md | 5 + .changeset/clever-bats-kick.md | 5 + .changeset/clever-pumas-beg.md | 5 + .changeset/config.json | 12 + .changeset/eight-peaches-guess.md | 5 + .changeset/eighty-crabs-listen.md | 5 + .changeset/eighty-lemons-shake.md | 5 + .changeset/empty-cheetahs-hunt.md | 5 + .changeset/empty-taxis-kiss.md | 5 + .changeset/fair-humans-peel.md | 5 + .changeset/fifty-owls-retire.md | 5 + .changeset/flat-bottles-wonder.md | 7 + .changeset/fluffy-countries-buy.md | 5 + .changeset/four-adults-knock.md | 5 + .changeset/fresh-birds-kiss.md | 5 + .changeset/green-pumpkins-end.md | 5 + .changeset/grumpy-bulldogs-call.md | 5 + .changeset/grumpy-worms-tease.md | 5 + .changeset/happy-falcons-walk.md | 5 + .changeset/healthy-gorillas-applaud.md | 5 + .changeset/heavy-drinks-fail.md | 5 + .changeset/hip-beds-provide.md | 5 + .changeset/hip-goats-fail.md | 5 + .changeset/hot-coins-judge.md | 5 + .changeset/hot-dingos-kiss.md | 5 + .changeset/hot-plums-approve.md | 5 + .changeset/large-humans-remain.md | 5 + .changeset/lazy-rice-joke.md | 5 + .changeset/little-falcons-build.md | 5 + .changeset/loud-shrimps-play.md | 5 + .changeset/lovely-geckos-hide.md | 5 + .changeset/mean-walls-watch.md | 5 + .changeset/mighty-donuts-smile.md | 6 + .changeset/orange-apes-draw.md | 5 + .changeset/pink-suns-mix.md | 5 + .changeset/popular-deers-raise.md | 5 + .changeset/pre.json | 85 + .changeset/proud-seals-complain.md | 5 + .changeset/proud-spiders-attend.md | 5 + .changeset/purple-cats-cheer.md | 5 + .changeset/quiet-trainers-kick.md | 5 + .changeset/red-dots-fold.md | 5 + .changeset/rotten-insects-wash.md | 5 + .changeset/serious-books-lie.md | 5 + .changeset/short-eels-enjoy.md | 5 + .changeset/silly-bees-beam.md | 7 + .changeset/six-frogs-turn.md | 5 + .changeset/sixty-numbers-reply.md | 5 + .changeset/slimy-penguins-attack.md | 5 + .changeset/smooth-books-wink.md | 5 + .changeset/smooth-cougars-jump.md | 5 + .changeset/spicy-sheep-eat.md | 5 + .changeset/spotty-hotels-type.md | 5 + .changeset/strong-poems-thank.md | 5 + .changeset/swift-bags-divide.md | 5 + .changeset/swift-numbers-cry.md | 5 + .changeset/tasty-tomatoes-turn.md | 5 + .changeset/tender-shirts-turn.md | 5 + .changeset/thick-pumpkins-exercise.md | 5 + .changeset/thin-camels-matter.md | 5 + .changeset/tough-drinks-hammer.md | 5 + .changeset/two-wasps-punch.md | 5 + .changeset/unlucky-beans-obey.md | 5 + .changeset/violet-dancers-cough.md | 5 + .changeset/violet-melons-press.md | 5 + .changeset/warm-guests-rule.md | 5 + .changeset/wet-bears-heal.md | 5 + .changeset/wild-beds-visit.md | 5 + .changeset/wild-peas-remain.md | 5 + .changeset/wild-rockets-rush.md | 5 + .changeset/wild-windows-trade.md | 5 + .codecov.yml | 12 + .editorconfig | 21 + .eslintrc | 20 + .github/ISSUE_TEMPLATE/bug_report.md | 21 + .github/ISSUE_TEMPLATE/config.yml | 4 + .github/ISSUE_TEMPLATE/feature_request.md | 14 + .github/PULL_REQUEST_TEMPLATE.md | 20 + .github/actions/gas-compare/action.yml | 49 + .github/actions/setup/action.yml | 19 + .github/actions/storage-layout/action.yml | 55 + .github/workflows/actionlint.yml | 18 + .github/workflows/changeset.yml | 28 + .github/workflows/checks.yml | 116 + .github/workflows/docs.yml | 19 + .github/workflows/formal-verification.yml | 68 + .github/workflows/release-cycle.yml | 218 + .github/workflows/upgradeable.yml | 30 + .gitignore | 71 + .gitmodules | 7 + .mocharc.js | 4 + .prettierrc | 15 + .solcover.js | 13 + CHANGELOG.md | 884 + CODE_OF_CONDUCT.md | 73 + CONTRIBUTING.md | 36 + GUIDELINES.md | 148 + LICENSE | 22 + README.md | 107 + RELEASING.md | 47 + SECURITY.md | 42 + audits/2017-03.md | 292 + audits/2018-10.pdf | Bin 0 -> 1000527 bytes audits/2022-10-Checkpoints.pdf | Bin 0 -> 155606 bytes audits/2022-10-ERC4626.pdf | Bin 0 -> 204184 bytes audits/2023-05-v4.9.pdf | Bin 0 -> 485395 bytes audits/README.md | 16 + certora/.gitignore | 1 + certora/Makefile | 54 + certora/README.md | 60 + .../AccessControlDefaultAdminRulesHarness.sol | 46 + certora/harnesses/AccessControlHarness.sol | 6 + certora/harnesses/DoubleEndedQueueHarness.sol | 58 + certora/harnesses/ERC20FlashMintHarness.sol | 36 + certora/harnesses/ERC20PermitHarness.sol | 16 + certora/harnesses/ERC20WrapperHarness.sol | 34 + .../harnesses/ERC3156FlashBorrowerHarness.sol | 13 + certora/harnesses/ERC721Harness.sol | 33 + certora/harnesses/ERC721ReceiverHarness.sol | 11 + certora/harnesses/EnumerableMapHarness.sol | 55 + certora/harnesses/EnumerableSetHarness.sol | 35 + certora/harnesses/InitializableHarness.sol | 23 + certora/harnesses/Ownable2StepHarness.sol | 10 + certora/harnesses/OwnableHarness.sol | 10 + certora/harnesses/PausableHarness.sol | 18 + .../harnesses/TimelockControllerHarness.sol | 13 + certora/reports/2021-10.pdf | Bin 0 -> 92882 bytes certora/reports/2022-03.pdf | Bin 0 -> 199401 bytes certora/reports/2022-05.pdf | Bin 0 -> 132223 bytes certora/run.js | 160 + certora/specs.json | 86 + certora/specs/AccessControl.spec | 119 + .../specs/AccessControlDefaultAdminRules.spec | 464 + certora/specs/DoubleEndedQueue.spec | 300 + certora/specs/ERC20.spec | 352 + certora/specs/ERC20FlashMint.spec | 55 + certora/specs/ERC20Wrapper.spec | 198 + certora/specs/ERC721.spec | 679 + certora/specs/EnumerableMap.spec | 333 + certora/specs/EnumerableSet.spec | 246 + certora/specs/Initializable.spec | 165 + certora/specs/Ownable.spec | 77 + certora/specs/Ownable2Step.spec | 108 + certora/specs/Pausable.spec | 96 + certora/specs/TimelockController.spec | 274 + certora/specs/helpers/helpers.spec | 7 + certora/specs/methods/IAccessControl.spec | 8 + .../IAccessControlDefaultAdminRules.spec | 36 + certora/specs/methods/IERC20.spec | 11 + certora/specs/methods/IERC2612.spec | 5 + .../specs/methods/IERC3156FlashBorrower.spec | 3 + .../specs/methods/IERC3156FlashLender.spec | 5 + certora/specs/methods/IERC5313.spec | 3 + certora/specs/methods/IERC721.spec | 17 + certora/specs/methods/IERC721Receiver.spec | 3 + certora/specs/methods/IOwnable.spec | 5 + certora/specs/methods/IOwnable2Step.spec | 7 + contracts/access/AccessControl.sol | 209 + contracts/access/IAccessControl.sol | 98 + contracts/access/Ownable.sol | 100 + contracts/access/Ownable2Step.sol | 59 + contracts/access/README.adoc | 39 + .../AccessControlDefaultAdminRules.sol | 396 + .../extensions/AccessControlEnumerable.sol | 70 + .../IAccessControlDefaultAdminRules.sol | 192 + .../extensions/IAccessControlEnumerable.sol | 31 + contracts/access/manager/AccessManaged.sol | 122 + contracts/access/manager/AccessManager.sol | 882 + contracts/access/manager/AuthorityUtils.sol | 32 + contracts/access/manager/IAccessManaged.sol | 18 + contracts/access/manager/IAccessManager.sol | 114 + contracts/access/manager/IAuthority.sol | 14 + contracts/finance/README.adoc | 14 + contracts/finance/VestingWallet.sol | 154 + contracts/governance/Governor.sol | 850 + contracts/governance/IGovernor.sol | 427 + contracts/governance/README.adoc | 167 + contracts/governance/TimelockController.sol | 472 + .../extensions/GovernorCountingSimple.sol | 100 + .../extensions/GovernorPreventLateQuorum.sol | 102 + .../extensions/GovernorSettings.sol | 112 + .../governance/extensions/GovernorStorage.sol | 115 + .../extensions/GovernorTimelockAccess.sol | 343 + .../extensions/GovernorTimelockCompound.sol | 167 + .../extensions/GovernorTimelockControl.sol | 173 + .../governance/extensions/GovernorVotes.sol | 64 + .../GovernorVotesQuorumFraction.sol | 110 + contracts/governance/utils/IVotes.sol | 59 + contracts/governance/utils/Votes.sol | 251 + contracts/interfaces/IERC1155.sol | 6 + contracts/interfaces/IERC1155MetadataURI.sol | 6 + contracts/interfaces/IERC1155Receiver.sol | 6 + contracts/interfaces/IERC1271.sol | 17 + contracts/interfaces/IERC1363.sol | 80 + contracts/interfaces/IERC1363Receiver.sol | 35 + contracts/interfaces/IERC1363Spender.sol | 29 + contracts/interfaces/IERC165.sol | 6 + contracts/interfaces/IERC1820Implementer.sol | 20 + contracts/interfaces/IERC1820Registry.sol | 112 + contracts/interfaces/IERC1967.sol | 24 + contracts/interfaces/IERC20.sol | 6 + contracts/interfaces/IERC20Metadata.sol | 6 + contracts/interfaces/IERC2309.sol | 19 + contracts/interfaces/IERC2612.sol | 8 + contracts/interfaces/IERC2981.sol | 23 + contracts/interfaces/IERC3156.sol | 7 + .../interfaces/IERC3156FlashBorrower.sol | 27 + contracts/interfaces/IERC3156FlashLender.sol | 41 + contracts/interfaces/IERC4626.sol | 230 + contracts/interfaces/IERC4906.sol | 20 + contracts/interfaces/IERC5267.sol | 28 + contracts/interfaces/IERC5313.sol | 16 + contracts/interfaces/IERC5805.sol | 9 + contracts/interfaces/IERC6372.sol | 17 + contracts/interfaces/IERC721.sol | 6 + contracts/interfaces/IERC721Enumerable.sol | 6 + contracts/interfaces/IERC721Metadata.sol | 6 + contracts/interfaces/IERC721Receiver.sol | 6 + contracts/interfaces/IERC777.sol | 200 + contracts/interfaces/IERC777Recipient.sol | 35 + contracts/interfaces/IERC777Sender.sol | 35 + contracts/interfaces/README.adoc | 82 + contracts/interfaces/draft-IERC1822.sol | 20 + contracts/interfaces/draft-IERC6093.sol | 161 + contracts/metatx/ERC2771Context.sol | 75 + contracts/metatx/ERC2771Forwarder.sol | 370 + contracts/metatx/README.adoc | 12 + contracts/mocks/AccessManagedTarget.sol | 18 + contracts/mocks/ArraysMock.sol | 51 + contracts/mocks/CallReceiverMock.sol | 73 + contracts/mocks/ContextMock.sol | 35 + contracts/mocks/DummyImplementation.sol | 65 + contracts/mocks/EIP712Verifier.sol | 16 + contracts/mocks/ERC1271WalletMock.sol | 24 + .../ERC165/ERC165InterfacesSupported.sol | 58 + .../mocks/ERC165/ERC165MaliciousData.sol | 12 + contracts/mocks/ERC165/ERC165MissingData.sol | 7 + contracts/mocks/ERC165/ERC165NotSupported.sol | 5 + contracts/mocks/ERC165/ERC165ReturnBomb.sol | 18 + contracts/mocks/ERC2771ContextMock.sol | 23 + contracts/mocks/ERC3156FlashBorrowerMock.sol | 53 + contracts/mocks/EtherReceiverMock.sol | 17 + contracts/mocks/InitializableMock.sol | 130 + contracts/mocks/MulticallTest.sol | 23 + .../MultipleInheritanceInitializableMocks.sol | 131 + contracts/mocks/PausableMock.sol | 31 + contracts/mocks/ReentrancyAttack.sol | 12 + contracts/mocks/ReentrancyMock.sol | 50 + contracts/mocks/RegressionImplementation.sol | 61 + .../SingleInheritanceInitializableMocks.sol | 49 + contracts/mocks/StorageSlotMock.sol | 77 + contracts/mocks/TimelockReentrant.sol | 26 + contracts/mocks/UpgradeableBeaconMock.sol | 27 + contracts/mocks/VotesMock.sol | 42 + contracts/mocks/compound/CompTimelock.sol | 174 + contracts/mocks/docs/ERC4626Fees.sol | 103 + .../mocks/docs/governance/MyGovernor.sol | 81 + contracts/mocks/docs/governance/MyToken.sol | 21 + .../docs/governance/MyTokenTimestampBased.sol | 32 + .../mocks/docs/governance/MyTokenWrapped.sol | 28 + contracts/mocks/governance/GovernorMock.sol | 14 + .../GovernorPreventLateQuorumMock.sol | 46 + .../mocks/governance/GovernorStorageMock.sol | 79 + .../governance/GovernorTimelockAccessMock.sol | 70 + .../GovernorTimelockCompoundMock.sol | 69 + .../GovernorTimelockControlMock.sol | 69 + .../mocks/governance/GovernorVoteMock.sol | 20 + .../governance/GovernorWithParamsMock.sol | 51 + contracts/mocks/proxy/BadBeacon.sol | 11 + .../mocks/proxy/ClashingImplementation.sol | 19 + contracts/mocks/proxy/UUPSUpgradeableMock.sol | 35 + contracts/mocks/token/ERC1155ReceiverMock.sol | 74 + contracts/mocks/token/ERC20ApprovalMock.sol | 10 + contracts/mocks/token/ERC20DecimalsMock.sol | 17 + .../mocks/token/ERC20ExcessDecimalsMock.sol | 9 + contracts/mocks/token/ERC20FlashMintMock.sol | 26 + .../mocks/token/ERC20ForceApproveMock.sol | 13 + contracts/mocks/token/ERC20Mock.sol | 16 + contracts/mocks/token/ERC20MulticallMock.sol | 8 + contracts/mocks/token/ERC20NoReturnMock.sol | 28 + contracts/mocks/token/ERC20Reentrant.sol | 39 + .../mocks/token/ERC20ReturnFalseMock.sol | 19 + .../mocks/token/ERC20VotesLegacyMock.sol | 253 + contracts/mocks/token/ERC4626LimitsMock.sol | 23 + contracts/mocks/token/ERC4626Mock.sol | 17 + contracts/mocks/token/ERC4626OffsetMock.sol | 17 + contracts/mocks/token/ERC4646FeesMock.sol | 40 + .../token/ERC721ConsecutiveEnumerableMock.sol | 42 + .../mocks/token/ERC721ConsecutiveMock.sol | 61 + contracts/mocks/token/ERC721ReceiverMock.sol | 47 + .../mocks/token/ERC721URIStorageMock.sol | 17 + contracts/mocks/token/VotesTimestamp.sol | 29 + contracts/package.json | 32 + contracts/proxy/Clones.sol | 95 + contracts/proxy/ERC1967/ERC1967Proxy.sol | 40 + contracts/proxy/ERC1967/ERC1967Utils.sol | 193 + contracts/proxy/Proxy.sol | 69 + contracts/proxy/README.adoc | 87 + contracts/proxy/beacon/BeaconProxy.sol | 57 + contracts/proxy/beacon/IBeacon.sol | 16 + contracts/proxy/beacon/UpgradeableBeacon.sol | 70 + contracts/proxy/transparent/ProxyAdmin.sol | 45 + .../TransparentUpgradeableProxy.sol | 116 + contracts/proxy/utils/Initializable.sol | 228 + contracts/proxy/utils/UUPSUpgradeable.sol | 147 + contracts/token/ERC1155/ERC1155.sol | 468 + contracts/token/ERC1155/IERC1155.sol | 128 + contracts/token/ERC1155/IERC1155Receiver.sol | 59 + contracts/token/ERC1155/README.adoc | 41 + .../ERC1155/extensions/ERC1155Burnable.sol | 28 + .../ERC1155/extensions/ERC1155Pausable.sol | 38 + .../ERC1155/extensions/ERC1155Supply.sol | 87 + .../ERC1155/extensions/ERC1155URIStorage.sol | 61 + .../extensions/IERC1155MetadataURI.sol | 20 + .../token/ERC1155/utils/ERC1155Holder.sol | 42 + contracts/token/ERC20/ERC20.sol | 316 + contracts/token/ERC20/IERC20.sol | 79 + contracts/token/ERC20/README.adoc | 67 + .../token/ERC20/extensions/ERC20Burnable.sol | 39 + .../token/ERC20/extensions/ERC20Capped.sol | 56 + .../token/ERC20/extensions/ERC20FlashMint.sol | 134 + .../token/ERC20/extensions/ERC20Pausable.sol | 33 + .../token/ERC20/extensions/ERC20Permit.sol | 83 + .../token/ERC20/extensions/ERC20Votes.sol | 83 + .../token/ERC20/extensions/ERC20Wrapper.sol | 86 + contracts/token/ERC20/extensions/ERC4626.sol | 286 + .../token/ERC20/extensions/IERC20Metadata.sol | 26 + .../token/ERC20/extensions/IERC20Permit.sol | 90 + contracts/token/ERC20/utils/SafeERC20.sol | 118 + contracts/token/ERC721/ERC721.sol | 483 + contracts/token/ERC721/IERC721.sol | 135 + contracts/token/ERC721/IERC721Receiver.sol | 28 + contracts/token/ERC721/README.adoc | 67 + .../ERC721/extensions/ERC721Burnable.sol | 26 + .../ERC721/extensions/ERC721Consecutive.sol | 176 + .../ERC721/extensions/ERC721Enumerable.sol | 172 + .../ERC721/extensions/ERC721Pausable.sol | 37 + .../token/ERC721/extensions/ERC721Royalty.sol | 27 + .../ERC721/extensions/ERC721URIStorage.sol | 61 + .../token/ERC721/extensions/ERC721Votes.sol | 47 + .../token/ERC721/extensions/ERC721Wrapper.sol | 102 + .../ERC721/extensions/IERC721Enumerable.sol | 29 + .../ERC721/extensions/IERC721Metadata.sol | 27 + contracts/token/ERC721/utils/ERC721Holder.sol | 24 + contracts/token/common/ERC2981.sol | 137 + contracts/token/common/README.adoc | 10 + contracts/utils/Address.sol | 159 + contracts/utils/Arrays.sol | 127 + contracts/utils/Base64.sol | 90 + contracts/utils/Context.sol | 24 + contracts/utils/Create2.sol | 96 + contracts/utils/Multicall.sol | 23 + contracts/utils/Nonces.sol | 46 + contracts/utils/Pausable.sol | 119 + contracts/utils/README.adoc | 88 + contracts/utils/ReentrancyGuard.sol | 84 + contracts/utils/ShortStrings.sol | 123 + contracts/utils/StorageSlot.sol | 135 + contracts/utils/Strings.sol | 94 + contracts/utils/cryptography/ECDSA.sol | 174 + contracts/utils/cryptography/EIP712.sol | 160 + contracts/utils/cryptography/MerkleProof.sol | 232 + .../utils/cryptography/MessageHashUtils.sol | 86 + .../utils/cryptography/SignatureChecker.sol | 48 + contracts/utils/introspection/ERC165.sol | 27 + .../utils/introspection/ERC165Checker.sol | 124 + contracts/utils/introspection/IERC165.sol | 25 + contracts/utils/math/Math.sol | 415 + contracts/utils/math/SafeCast.sol | 1153 + contracts/utils/math/SignedMath.sol | 43 + contracts/utils/structs/BitMaps.sol | 60 + contracts/utils/structs/Checkpoints.sol | 603 + contracts/utils/structs/DoubleEndedQueue.sol | 169 + contracts/utils/structs/EnumerableMap.sol | 533 + contracts/utils/structs/EnumerableSet.sol | 378 + contracts/utils/types/Time.sol | 126 + .../vendor/compound/ICompoundTimelock.sol | 86 + contracts/vendor/compound/LICENSE | 11 + docs/README.md | 16 + docs/antora.yml | 7 + docs/config.js | 21 + .../modules/ROOT/images/erc4626-attack-3a.png | Bin 0 -> 60433 bytes .../modules/ROOT/images/erc4626-attack-3b.png | Bin 0 -> 66184 bytes docs/modules/ROOT/images/erc4626-attack-6.png | Bin 0 -> 56290 bytes docs/modules/ROOT/images/erc4626-attack.png | Bin 0 -> 58886 bytes docs/modules/ROOT/images/erc4626-deposit.png | Bin 0 -> 115497 bytes docs/modules/ROOT/images/erc4626-mint.png | Bin 0 -> 112787 bytes .../ROOT/images/erc4626-rate-linear.png | Bin 0 -> 50813 bytes .../ROOT/images/erc4626-rate-loglog.png | Bin 0 -> 72818 bytes .../ROOT/images/erc4626-rate-loglogext.png | Bin 0 -> 109923 bytes docs/modules/ROOT/images/tally-exec.png | Bin 0 -> 231859 bytes docs/modules/ROOT/images/tally-vote.png | Bin 0 -> 40507 bytes docs/modules/ROOT/nav.adoc | 23 + docs/modules/ROOT/pages/access-control.adoc | 219 + docs/modules/ROOT/pages/crowdsales.adoc | 11 + docs/modules/ROOT/pages/drafts.adoc | 19 + docs/modules/ROOT/pages/erc1155.adoc | 145 + docs/modules/ROOT/pages/erc20-supply.adoc | 85 + docs/modules/ROOT/pages/erc20.adoc | 77 + docs/modules/ROOT/pages/erc4626.adoc | 214 + docs/modules/ROOT/pages/erc721.adoc | 79 + .../ROOT/pages/extending-contracts.adoc | 131 + docs/modules/ROOT/pages/faq.adoc | 13 + docs/modules/ROOT/pages/governance.adoc | 240 + docs/modules/ROOT/pages/index.adoc | 79 + .../ROOT/pages/releases-stability.adoc | 85 + docs/modules/ROOT/pages/tokens.adoc | 31 + docs/modules/ROOT/pages/upgradeable.adoc | 73 + docs/modules/ROOT/pages/utilities.adoc | 185 + docs/modules/ROOT/pages/wizard.adoc | 15 + docs/modules/api/examples/ERC4626Fees.sol | 103 + .../api/examples/governance/MyGovernor.sol | 81 + .../api/examples/governance/MyToken.sol | 21 + .../governance/MyTokenTimestampBased.sol | 32 + .../examples/governance/MyTokenWrapped.sol | 28 + docs/modules/api/nav.adoc | 12 + docs/modules/api/pages/access.adoc | 2582 ++ docs/modules/api/pages/finance.adoc | 234 + docs/modules/api/pages/governance.adoc | 5226 +++ docs/modules/api/pages/interfaces.adoc | 1410 + docs/modules/api/pages/metatx.adoc | 359 + docs/modules/api/pages/proxy.adoc | 1251 + docs/modules/api/pages/token/ERC1155.adoc | 1496 + docs/modules/api/pages/token/ERC20.adoc | 2670 ++ docs/modules/api/pages/token/ERC721.adoc | 2991 ++ docs/modules/api/pages/token/common.adoc | 178 + docs/modules/api/pages/utils.adoc | 4497 +++ docs/templates/contract.hbs | 111 + docs/templates/helpers.js | 46 + docs/templates/page.hbs | 4 + docs/templates/properties.js | 49 + foundry.toml | 3 + hardhat.config.js | 115 + hardhat/env-artifacts.js | 24 + hardhat/env-contract.js | 10 + hardhat/ignore-unreachable-warnings.js | 45 + hardhat/skip-foundry-tests.js | 6 + hardhat/task-test-get-files.js | 25 + lib/erc4626-tests | 1 + lib/forge-std | 1 + logo.svg | 15 + netlify.toml | 3 + package-lock.json | 27465 ++++++++++++++++ package.json | 95 + remappings.txt | 1 + renovate.json | 4 + requirements.txt | 1 + scripts/checks/compare-layout.js | 20 + scripts/checks/compareGasReports.js | 243 + scripts/checks/extract-layout.js | 40 + scripts/checks/generation.sh | 6 + scripts/checks/inheritance-ordering.js | 54 + scripts/gen-nav.js | 41 + scripts/generate/format-lines.js | 16 + scripts/generate/run.js | 49 + scripts/generate/templates/Checkpoints.js | 247 + .../generate/templates/Checkpoints.opts.js | 17 + scripts/generate/templates/Checkpoints.t.js | 146 + scripts/generate/templates/EnumerableMap.js | 283 + scripts/generate/templates/EnumerableSet.js | 250 + scripts/generate/templates/SafeCast.js | 126 + scripts/generate/templates/StorageSlot.js | 78 + scripts/generate/templates/conversion.js | 30 + scripts/git-user-config.sh | 6 + scripts/helpers.js | 37 + scripts/prepack.sh | 12 + scripts/prepare-contracts-package.sh | 15 + scripts/prepare-docs.sh | 26 + scripts/prepare.sh | 10 + scripts/release/format-changelog.js | 33 + scripts/release/synchronize-versions.js | 15 + scripts/release/update-comment.js | 34 + scripts/release/version.sh | 11 + scripts/release/workflow/exit-prerelease.sh | 8 + scripts/release/workflow/github-release.js | 47 + scripts/release/workflow/integrity-check.sh | 20 + scripts/release/workflow/pack.sh | 26 + scripts/release/workflow/publish.sh | 26 + scripts/release/workflow/rerun.js | 7 + .../workflow/set-changesets-pr-title.js | 17 + scripts/release/workflow/start.sh | 35 + scripts/release/workflow/state.js | 112 + scripts/remove-ignored-artifacts.js | 45 + scripts/solhint-custom/index.js | 84 + scripts/solhint-custom/package.json | 4 + scripts/update-docs-branch.js | 58 + scripts/upgradeable/README.md | 21 + scripts/upgradeable/patch-apply.sh | 19 + scripts/upgradeable/patch-save.sh | 18 + scripts/upgradeable/transpile-onto.sh | 44 + scripts/upgradeable/transpile.sh | 42 + scripts/upgradeable/upgradeable.patch | 342 + slither.config.json | 5 + solhint.config.js | 20 + test/TESTING.md | 3 + test/access/AccessControl.behavior.js | 909 + test/access/AccessControl.test.js | 12 + test/access/Ownable.test.js | 72 + test/access/Ownable2Step.test.js | 70 + .../AccessControlDefaultAdminRules.test.js | 26 + .../AccessControlEnumerable.test.js | 17 + test/access/manager/AccessManager.test.js | 1161 + test/finance/VestingWallet.behavior.js | 59 + test/finance/VestingWallet.test.js | 69 + test/governance/Governor.t.sol | 55 + test/governance/Governor.test.js | 1024 + test/governance/TimelockController.test.js | 1286 + .../extensions/GovernorERC721.test.js | 116 + .../GovernorPreventLateQuorum.test.js | 195 + .../extensions/GovernorStorage.test.js | 150 + .../extensions/GovernorTimelockAccess.test.js | 407 + .../GovernorTimelockCompound.test.js | 441 + .../GovernorTimelockControl.test.js | 515 + .../GovernorVotesQuorumFraction.test.js | 167 + .../extensions/GovernorWithParams.test.js | 277 + test/governance/utils/EIP6372.behavior.js | 23 + test/governance/utils/Votes.behavior.js | 360 + test/governance/utils/Votes.test.js | 92 + test/helpers/account.js | 14 + test/helpers/chainid.js | 10 + test/helpers/constants.js | 7 + test/helpers/create.js | 22 + test/helpers/customError.js | 43 + test/helpers/eip712.js | 67 + test/helpers/enums.js | 11 + test/helpers/erc1967.js | 43 + test/helpers/governance.js | 253 + test/helpers/iterate.js | 16 + test/helpers/math.js | 11 + test/helpers/methods.js | 5 + test/helpers/sign.js | 63 + test/helpers/time.js | 17 + test/helpers/txpool.js | 38 + test/metatx/ERC2771Context.test.js | 134 + test/metatx/ERC2771Forwarder.t.sol | 165 + test/metatx/ERC2771Forwarder.test.js | 542 + test/proxy/Clones.behaviour.js | 136 + test/proxy/Clones.test.js | 62 + test/proxy/ERC1967/ERC1967Proxy.test.js | 12 + test/proxy/ERC1967/ERC1967Utils.test.js | 172 + test/proxy/Proxy.behaviour.js | 182 + test/proxy/beacon/BeaconProxy.test.js | 152 + test/proxy/beacon/UpgradeableBeacon.test.js | 54 + test/proxy/transparent/ProxyAdmin.test.js | 103 + .../TransparentUpgradeableProxy.behaviour.js | 413 + .../TransparentUpgradeableProxy.test.js | 24 + test/proxy/utils/Initializable.test.js | 220 + test/proxy/utils/UUPSUpgradeable.test.js | 131 + test/token/ERC1155/ERC1155.behavior.js | 905 + test/token/ERC1155/ERC1155.test.js | 252 + .../extensions/ERC1155Burnable.test.js | 71 + .../extensions/ERC1155Pausable.test.js | 113 + .../ERC1155/extensions/ERC1155Supply.test.js | 116 + .../extensions/ERC1155URIStorage.test.js | 66 + .../token/ERC1155/utils/ERC1155Holder.test.js | 64 + test/token/ERC20/ERC20.behavior.js | 340 + test/token/ERC20/ERC20.test.js | 202 + .../extensions/ERC20Burnable.behavior.js | 116 + .../ERC20/extensions/ERC20Burnable.test.js | 20 + .../ERC20/extensions/ERC20Capped.behavior.js | 31 + .../ERC20/extensions/ERC20Capped.test.js | 24 + .../ERC20/extensions/ERC20FlashMint.test.js | 210 + .../ERC20/extensions/ERC20Pausable.test.js | 136 + .../ERC20/extensions/ERC20Permit.test.js | 118 + .../token/ERC20/extensions/ERC20Votes.test.js | 593 + .../ERC20/extensions/ERC20Wrapper.test.js | 211 + test/token/ERC20/extensions/ERC4626.t.sol | 41 + test/token/ERC20/extensions/ERC4626.test.js | 1109 + test/token/ERC20/utils/SafeERC20.test.js | 240 + test/token/ERC721/ERC721.behavior.js | 978 + test/token/ERC721/ERC721.test.js | 15 + test/token/ERC721/ERC721Enumerable.test.js | 20 + .../ERC721/extensions/ERC721Burnable.test.js | 82 + .../ERC721/extensions/ERC721Consecutive.t.sol | 181 + .../extensions/ERC721Consecutive.test.js | 221 + .../ERC721/extensions/ERC721Pausable.test.js | 90 + .../ERC721/extensions/ERC721Royalty.test.js | 47 + .../extensions/ERC721URIStorage.test.js | 114 + .../ERC721/extensions/ERC721Votes.test.js | 183 + .../ERC721/extensions/ERC721Wrapper.test.js | 289 + test/token/ERC721/utils/ERC721Holder.test.js | 22 + test/token/common/ERC2981.behavior.js | 169 + test/utils/Address.test.js | 340 + test/utils/Arrays.test.js | 123 + test/utils/Base64.test.js | 33 + test/utils/Context.behavior.js | 42 + test/utils/Context.test.js | 17 + test/utils/Create2.test.js | 102 + test/utils/Multicall.test.js | 69 + test/utils/Nonces.test.js | 71 + test/utils/Pausable.test.js | 86 + test/utils/ReentrancyGuard.test.js | 44 + test/utils/ShortStrings.t.sol | 55 + test/utils/ShortStrings.test.js | 55 + test/utils/StorageSlot.test.js | 210 + test/utils/Strings.test.js | 153 + test/utils/cryptography/ECDSA.test.js | 245 + test/utils/cryptography/EIP712.test.js | 111 + test/utils/cryptography/MerkleProof.test.js | 207 + .../cryptography/MessageHashUtils.test.js | 55 + .../cryptography/SignatureChecker.test.js | 87 + test/utils/introspection/ERC165.test.js | 11 + .../utils/introspection/ERC165Checker.test.js | 300 + .../SupportsInterface.behavior.js | 144 + test/utils/math/Math.t.sol | 216 + test/utils/math/Math.test.js | 469 + test/utils/math/SafeCast.test.js | 161 + test/utils/math/SignedMath.test.js | 95 + test/utils/structs/BitMap.test.js | 145 + test/utils/structs/Checkpoints.t.sol | 332 + test/utils/structs/Checkpoints.test.js | 158 + test/utils/structs/DoubleEndedQueue.test.js | 99 + test/utils/structs/EnumerableMap.behavior.js | 178 + test/utils/structs/EnumerableMap.test.js | 149 + test/utils/structs/EnumerableSet.behavior.js | 129 + test/utils/structs/EnumerableSet.test.js | 79 + test/utils/types/Time.test.js | 140 + 624 files changed, 107720 insertions(+) create mode 100644 .changeset/afraid-walls-smell.md create mode 100644 .changeset/angry-ties-switch.md create mode 100644 .changeset/big-plums-cover.md create mode 100644 .changeset/blue-horses-do.md create mode 100644 .changeset/blue-scissors-design.md create mode 100644 .changeset/brave-lobsters-punch.md create mode 100644 .changeset/bright-tomatoes-sing.md create mode 100644 .changeset/chilled-spiders-attack.md create mode 100644 .changeset/clever-bats-kick.md create mode 100644 .changeset/clever-pumas-beg.md create mode 100644 .changeset/config.json create mode 100644 .changeset/eight-peaches-guess.md create mode 100644 .changeset/eighty-crabs-listen.md create mode 100644 .changeset/eighty-lemons-shake.md create mode 100644 .changeset/empty-cheetahs-hunt.md create mode 100644 .changeset/empty-taxis-kiss.md create mode 100644 .changeset/fair-humans-peel.md create mode 100644 .changeset/fifty-owls-retire.md create mode 100644 .changeset/flat-bottles-wonder.md create mode 100644 .changeset/fluffy-countries-buy.md create mode 100644 .changeset/four-adults-knock.md create mode 100644 .changeset/fresh-birds-kiss.md create mode 100644 .changeset/green-pumpkins-end.md create mode 100644 .changeset/grumpy-bulldogs-call.md create mode 100644 .changeset/grumpy-worms-tease.md create mode 100644 .changeset/happy-falcons-walk.md create mode 100644 .changeset/healthy-gorillas-applaud.md create mode 100644 .changeset/heavy-drinks-fail.md create mode 100644 .changeset/hip-beds-provide.md create mode 100644 .changeset/hip-goats-fail.md create mode 100644 .changeset/hot-coins-judge.md create mode 100644 .changeset/hot-dingos-kiss.md create mode 100644 .changeset/hot-plums-approve.md create mode 100644 .changeset/large-humans-remain.md create mode 100644 .changeset/lazy-rice-joke.md create mode 100644 .changeset/little-falcons-build.md create mode 100644 .changeset/loud-shrimps-play.md create mode 100644 .changeset/lovely-geckos-hide.md create mode 100644 .changeset/mean-walls-watch.md create mode 100644 .changeset/mighty-donuts-smile.md create mode 100644 .changeset/orange-apes-draw.md create mode 100644 .changeset/pink-suns-mix.md create mode 100644 .changeset/popular-deers-raise.md create mode 100644 .changeset/pre.json create mode 100644 .changeset/proud-seals-complain.md create mode 100644 .changeset/proud-spiders-attend.md create mode 100644 .changeset/purple-cats-cheer.md create mode 100644 .changeset/quiet-trainers-kick.md create mode 100644 .changeset/red-dots-fold.md create mode 100644 .changeset/rotten-insects-wash.md create mode 100644 .changeset/serious-books-lie.md create mode 100644 .changeset/short-eels-enjoy.md create mode 100644 .changeset/silly-bees-beam.md create mode 100644 .changeset/six-frogs-turn.md create mode 100644 .changeset/sixty-numbers-reply.md create mode 100644 .changeset/slimy-penguins-attack.md create mode 100644 .changeset/smooth-books-wink.md create mode 100644 .changeset/smooth-cougars-jump.md create mode 100644 .changeset/spicy-sheep-eat.md create mode 100644 .changeset/spotty-hotels-type.md create mode 100644 .changeset/strong-poems-thank.md create mode 100644 .changeset/swift-bags-divide.md create mode 100644 .changeset/swift-numbers-cry.md create mode 100644 .changeset/tasty-tomatoes-turn.md create mode 100644 .changeset/tender-shirts-turn.md create mode 100644 .changeset/thick-pumpkins-exercise.md create mode 100644 .changeset/thin-camels-matter.md create mode 100644 .changeset/tough-drinks-hammer.md create mode 100644 .changeset/two-wasps-punch.md create mode 100644 .changeset/unlucky-beans-obey.md create mode 100644 .changeset/violet-dancers-cough.md create mode 100644 .changeset/violet-melons-press.md create mode 100644 .changeset/warm-guests-rule.md create mode 100644 .changeset/wet-bears-heal.md create mode 100644 .changeset/wild-beds-visit.md create mode 100644 .changeset/wild-peas-remain.md create mode 100644 .changeset/wild-rockets-rush.md create mode 100644 .changeset/wild-windows-trade.md create mode 100644 .codecov.yml create mode 100644 .editorconfig create mode 100644 .eslintrc create mode 100644 .github/ISSUE_TEMPLATE/bug_report.md create mode 100644 .github/ISSUE_TEMPLATE/config.yml create mode 100644 .github/ISSUE_TEMPLATE/feature_request.md create mode 100644 .github/PULL_REQUEST_TEMPLATE.md create mode 100644 .github/actions/gas-compare/action.yml create mode 100644 .github/actions/setup/action.yml create mode 100644 .github/actions/storage-layout/action.yml create mode 100644 .github/workflows/actionlint.yml create mode 100644 .github/workflows/changeset.yml create mode 100644 .github/workflows/checks.yml create mode 100644 .github/workflows/docs.yml create mode 100644 .github/workflows/formal-verification.yml create mode 100644 .github/workflows/release-cycle.yml create mode 100644 .github/workflows/upgradeable.yml create mode 100644 .gitignore create mode 100644 .gitmodules create mode 100644 .mocharc.js create mode 100644 .prettierrc create mode 100644 .solcover.js create mode 100644 CHANGELOG.md create mode 100644 CODE_OF_CONDUCT.md create mode 100644 CONTRIBUTING.md create mode 100644 GUIDELINES.md create mode 100644 LICENSE create mode 100644 README.md create mode 100644 RELEASING.md create mode 100644 SECURITY.md create mode 100644 audits/2017-03.md create mode 100644 audits/2018-10.pdf create mode 100644 audits/2022-10-Checkpoints.pdf create mode 100644 audits/2022-10-ERC4626.pdf create mode 100644 audits/2023-05-v4.9.pdf create mode 100644 audits/README.md create mode 100644 certora/.gitignore create mode 100644 certora/Makefile create mode 100644 certora/README.md create mode 100644 certora/harnesses/AccessControlDefaultAdminRulesHarness.sol create mode 100644 certora/harnesses/AccessControlHarness.sol create mode 100644 certora/harnesses/DoubleEndedQueueHarness.sol create mode 100644 certora/harnesses/ERC20FlashMintHarness.sol create mode 100644 certora/harnesses/ERC20PermitHarness.sol create mode 100644 certora/harnesses/ERC20WrapperHarness.sol create mode 100644 certora/harnesses/ERC3156FlashBorrowerHarness.sol create mode 100644 certora/harnesses/ERC721Harness.sol create mode 100644 certora/harnesses/ERC721ReceiverHarness.sol create mode 100644 certora/harnesses/EnumerableMapHarness.sol create mode 100644 certora/harnesses/EnumerableSetHarness.sol create mode 100644 certora/harnesses/InitializableHarness.sol create mode 100644 certora/harnesses/Ownable2StepHarness.sol create mode 100644 certora/harnesses/OwnableHarness.sol create mode 100644 certora/harnesses/PausableHarness.sol create mode 100644 certora/harnesses/TimelockControllerHarness.sol create mode 100644 certora/reports/2021-10.pdf create mode 100644 certora/reports/2022-03.pdf create mode 100644 certora/reports/2022-05.pdf create mode 100755 certora/run.js create mode 100644 certora/specs.json create mode 100644 certora/specs/AccessControl.spec create mode 100644 certora/specs/AccessControlDefaultAdminRules.spec create mode 100644 certora/specs/DoubleEndedQueue.spec create mode 100644 certora/specs/ERC20.spec create mode 100644 certora/specs/ERC20FlashMint.spec create mode 100644 certora/specs/ERC20Wrapper.spec create mode 100644 certora/specs/ERC721.spec create mode 100644 certora/specs/EnumerableMap.spec create mode 100644 certora/specs/EnumerableSet.spec create mode 100644 certora/specs/Initializable.spec create mode 100644 certora/specs/Ownable.spec create mode 100644 certora/specs/Ownable2Step.spec create mode 100644 certora/specs/Pausable.spec create mode 100644 certora/specs/TimelockController.spec create mode 100644 certora/specs/helpers/helpers.spec create mode 100644 certora/specs/methods/IAccessControl.spec create mode 100644 certora/specs/methods/IAccessControlDefaultAdminRules.spec create mode 100644 certora/specs/methods/IERC20.spec create mode 100644 certora/specs/methods/IERC2612.spec create mode 100644 certora/specs/methods/IERC3156FlashBorrower.spec create mode 100644 certora/specs/methods/IERC3156FlashLender.spec create mode 100644 certora/specs/methods/IERC5313.spec create mode 100644 certora/specs/methods/IERC721.spec create mode 100644 certora/specs/methods/IERC721Receiver.spec create mode 100644 certora/specs/methods/IOwnable.spec create mode 100644 certora/specs/methods/IOwnable2Step.spec create mode 100644 contracts/access/AccessControl.sol create mode 100644 contracts/access/IAccessControl.sol create mode 100644 contracts/access/Ownable.sol create mode 100644 contracts/access/Ownable2Step.sol create mode 100644 contracts/access/README.adoc create mode 100644 contracts/access/extensions/AccessControlDefaultAdminRules.sol create mode 100644 contracts/access/extensions/AccessControlEnumerable.sol create mode 100644 contracts/access/extensions/IAccessControlDefaultAdminRules.sol create mode 100644 contracts/access/extensions/IAccessControlEnumerable.sol create mode 100644 contracts/access/manager/AccessManaged.sol create mode 100644 contracts/access/manager/AccessManager.sol create mode 100644 contracts/access/manager/AuthorityUtils.sol create mode 100644 contracts/access/manager/IAccessManaged.sol create mode 100644 contracts/access/manager/IAccessManager.sol create mode 100644 contracts/access/manager/IAuthority.sol create mode 100644 contracts/finance/README.adoc create mode 100644 contracts/finance/VestingWallet.sol create mode 100644 contracts/governance/Governor.sol create mode 100644 contracts/governance/IGovernor.sol create mode 100644 contracts/governance/README.adoc create mode 100644 contracts/governance/TimelockController.sol create mode 100644 contracts/governance/extensions/GovernorCountingSimple.sol create mode 100644 contracts/governance/extensions/GovernorPreventLateQuorum.sol create mode 100644 contracts/governance/extensions/GovernorSettings.sol create mode 100644 contracts/governance/extensions/GovernorStorage.sol create mode 100644 contracts/governance/extensions/GovernorTimelockAccess.sol create mode 100644 contracts/governance/extensions/GovernorTimelockCompound.sol create mode 100644 contracts/governance/extensions/GovernorTimelockControl.sol create mode 100644 contracts/governance/extensions/GovernorVotes.sol create mode 100644 contracts/governance/extensions/GovernorVotesQuorumFraction.sol create mode 100644 contracts/governance/utils/IVotes.sol create mode 100644 contracts/governance/utils/Votes.sol create mode 100644 contracts/interfaces/IERC1155.sol create mode 100644 contracts/interfaces/IERC1155MetadataURI.sol create mode 100644 contracts/interfaces/IERC1155Receiver.sol create mode 100644 contracts/interfaces/IERC1271.sol create mode 100644 contracts/interfaces/IERC1363.sol create mode 100644 contracts/interfaces/IERC1363Receiver.sol create mode 100644 contracts/interfaces/IERC1363Spender.sol create mode 100644 contracts/interfaces/IERC165.sol create mode 100644 contracts/interfaces/IERC1820Implementer.sol create mode 100644 contracts/interfaces/IERC1820Registry.sol create mode 100644 contracts/interfaces/IERC1967.sol create mode 100644 contracts/interfaces/IERC20.sol create mode 100644 contracts/interfaces/IERC20Metadata.sol create mode 100644 contracts/interfaces/IERC2309.sol create mode 100644 contracts/interfaces/IERC2612.sol create mode 100644 contracts/interfaces/IERC2981.sol create mode 100644 contracts/interfaces/IERC3156.sol create mode 100644 contracts/interfaces/IERC3156FlashBorrower.sol create mode 100644 contracts/interfaces/IERC3156FlashLender.sol create mode 100644 contracts/interfaces/IERC4626.sol create mode 100644 contracts/interfaces/IERC4906.sol create mode 100644 contracts/interfaces/IERC5267.sol create mode 100644 contracts/interfaces/IERC5313.sol create mode 100644 contracts/interfaces/IERC5805.sol create mode 100644 contracts/interfaces/IERC6372.sol create mode 100644 contracts/interfaces/IERC721.sol create mode 100644 contracts/interfaces/IERC721Enumerable.sol create mode 100644 contracts/interfaces/IERC721Metadata.sol create mode 100644 contracts/interfaces/IERC721Receiver.sol create mode 100644 contracts/interfaces/IERC777.sol create mode 100644 contracts/interfaces/IERC777Recipient.sol create mode 100644 contracts/interfaces/IERC777Sender.sol create mode 100644 contracts/interfaces/README.adoc create mode 100644 contracts/interfaces/draft-IERC1822.sol create mode 100644 contracts/interfaces/draft-IERC6093.sol create mode 100644 contracts/metatx/ERC2771Context.sol create mode 100644 contracts/metatx/ERC2771Forwarder.sol create mode 100644 contracts/metatx/README.adoc create mode 100644 contracts/mocks/AccessManagedTarget.sol create mode 100644 contracts/mocks/ArraysMock.sol create mode 100644 contracts/mocks/CallReceiverMock.sol create mode 100644 contracts/mocks/ContextMock.sol create mode 100644 contracts/mocks/DummyImplementation.sol create mode 100644 contracts/mocks/EIP712Verifier.sol create mode 100644 contracts/mocks/ERC1271WalletMock.sol create mode 100644 contracts/mocks/ERC165/ERC165InterfacesSupported.sol create mode 100644 contracts/mocks/ERC165/ERC165MaliciousData.sol create mode 100644 contracts/mocks/ERC165/ERC165MissingData.sol create mode 100644 contracts/mocks/ERC165/ERC165NotSupported.sol create mode 100644 contracts/mocks/ERC165/ERC165ReturnBomb.sol create mode 100644 contracts/mocks/ERC2771ContextMock.sol create mode 100644 contracts/mocks/ERC3156FlashBorrowerMock.sol create mode 100644 contracts/mocks/EtherReceiverMock.sol create mode 100644 contracts/mocks/InitializableMock.sol create mode 100644 contracts/mocks/MulticallTest.sol create mode 100644 contracts/mocks/MultipleInheritanceInitializableMocks.sol create mode 100644 contracts/mocks/PausableMock.sol create mode 100644 contracts/mocks/ReentrancyAttack.sol create mode 100644 contracts/mocks/ReentrancyMock.sol create mode 100644 contracts/mocks/RegressionImplementation.sol create mode 100644 contracts/mocks/SingleInheritanceInitializableMocks.sol create mode 100644 contracts/mocks/StorageSlotMock.sol create mode 100644 contracts/mocks/TimelockReentrant.sol create mode 100644 contracts/mocks/UpgradeableBeaconMock.sol create mode 100644 contracts/mocks/VotesMock.sol create mode 100644 contracts/mocks/compound/CompTimelock.sol create mode 100644 contracts/mocks/docs/ERC4626Fees.sol create mode 100644 contracts/mocks/docs/governance/MyGovernor.sol create mode 100644 contracts/mocks/docs/governance/MyToken.sol create mode 100644 contracts/mocks/docs/governance/MyTokenTimestampBased.sol create mode 100644 contracts/mocks/docs/governance/MyTokenWrapped.sol create mode 100644 contracts/mocks/governance/GovernorMock.sol create mode 100644 contracts/mocks/governance/GovernorPreventLateQuorumMock.sol create mode 100644 contracts/mocks/governance/GovernorStorageMock.sol create mode 100644 contracts/mocks/governance/GovernorTimelockAccessMock.sol create mode 100644 contracts/mocks/governance/GovernorTimelockCompoundMock.sol create mode 100644 contracts/mocks/governance/GovernorTimelockControlMock.sol create mode 100644 contracts/mocks/governance/GovernorVoteMock.sol create mode 100644 contracts/mocks/governance/GovernorWithParamsMock.sol create mode 100644 contracts/mocks/proxy/BadBeacon.sol create mode 100644 contracts/mocks/proxy/ClashingImplementation.sol create mode 100644 contracts/mocks/proxy/UUPSUpgradeableMock.sol create mode 100644 contracts/mocks/token/ERC1155ReceiverMock.sol create mode 100644 contracts/mocks/token/ERC20ApprovalMock.sol create mode 100644 contracts/mocks/token/ERC20DecimalsMock.sol create mode 100644 contracts/mocks/token/ERC20ExcessDecimalsMock.sol create mode 100644 contracts/mocks/token/ERC20FlashMintMock.sol create mode 100644 contracts/mocks/token/ERC20ForceApproveMock.sol create mode 100644 contracts/mocks/token/ERC20Mock.sol create mode 100644 contracts/mocks/token/ERC20MulticallMock.sol create mode 100644 contracts/mocks/token/ERC20NoReturnMock.sol create mode 100644 contracts/mocks/token/ERC20Reentrant.sol create mode 100644 contracts/mocks/token/ERC20ReturnFalseMock.sol create mode 100644 contracts/mocks/token/ERC20VotesLegacyMock.sol create mode 100644 contracts/mocks/token/ERC4626LimitsMock.sol create mode 100644 contracts/mocks/token/ERC4626Mock.sol create mode 100644 contracts/mocks/token/ERC4626OffsetMock.sol create mode 100644 contracts/mocks/token/ERC4646FeesMock.sol create mode 100644 contracts/mocks/token/ERC721ConsecutiveEnumerableMock.sol create mode 100644 contracts/mocks/token/ERC721ConsecutiveMock.sol create mode 100644 contracts/mocks/token/ERC721ReceiverMock.sol create mode 100644 contracts/mocks/token/ERC721URIStorageMock.sol create mode 100644 contracts/mocks/token/VotesTimestamp.sol create mode 100644 contracts/package.json create mode 100644 contracts/proxy/Clones.sol create mode 100644 contracts/proxy/ERC1967/ERC1967Proxy.sol create mode 100644 contracts/proxy/ERC1967/ERC1967Utils.sol create mode 100644 contracts/proxy/Proxy.sol create mode 100644 contracts/proxy/README.adoc create mode 100644 contracts/proxy/beacon/BeaconProxy.sol create mode 100644 contracts/proxy/beacon/IBeacon.sol create mode 100644 contracts/proxy/beacon/UpgradeableBeacon.sol create mode 100644 contracts/proxy/transparent/ProxyAdmin.sol create mode 100644 contracts/proxy/transparent/TransparentUpgradeableProxy.sol create mode 100644 contracts/proxy/utils/Initializable.sol create mode 100644 contracts/proxy/utils/UUPSUpgradeable.sol create mode 100644 contracts/token/ERC1155/ERC1155.sol create mode 100644 contracts/token/ERC1155/IERC1155.sol create mode 100644 contracts/token/ERC1155/IERC1155Receiver.sol create mode 100644 contracts/token/ERC1155/README.adoc create mode 100644 contracts/token/ERC1155/extensions/ERC1155Burnable.sol create mode 100644 contracts/token/ERC1155/extensions/ERC1155Pausable.sol create mode 100644 contracts/token/ERC1155/extensions/ERC1155Supply.sol create mode 100644 contracts/token/ERC1155/extensions/ERC1155URIStorage.sol create mode 100644 contracts/token/ERC1155/extensions/IERC1155MetadataURI.sol create mode 100644 contracts/token/ERC1155/utils/ERC1155Holder.sol create mode 100644 contracts/token/ERC20/ERC20.sol create mode 100644 contracts/token/ERC20/IERC20.sol create mode 100644 contracts/token/ERC20/README.adoc create mode 100644 contracts/token/ERC20/extensions/ERC20Burnable.sol create mode 100644 contracts/token/ERC20/extensions/ERC20Capped.sol create mode 100644 contracts/token/ERC20/extensions/ERC20FlashMint.sol create mode 100644 contracts/token/ERC20/extensions/ERC20Pausable.sol create mode 100644 contracts/token/ERC20/extensions/ERC20Permit.sol create mode 100644 contracts/token/ERC20/extensions/ERC20Votes.sol create mode 100644 contracts/token/ERC20/extensions/ERC20Wrapper.sol create mode 100644 contracts/token/ERC20/extensions/ERC4626.sol create mode 100644 contracts/token/ERC20/extensions/IERC20Metadata.sol create mode 100644 contracts/token/ERC20/extensions/IERC20Permit.sol create mode 100644 contracts/token/ERC20/utils/SafeERC20.sol create mode 100644 contracts/token/ERC721/ERC721.sol create mode 100644 contracts/token/ERC721/IERC721.sol create mode 100644 contracts/token/ERC721/IERC721Receiver.sol create mode 100644 contracts/token/ERC721/README.adoc create mode 100644 contracts/token/ERC721/extensions/ERC721Burnable.sol create mode 100644 contracts/token/ERC721/extensions/ERC721Consecutive.sol create mode 100644 contracts/token/ERC721/extensions/ERC721Enumerable.sol create mode 100644 contracts/token/ERC721/extensions/ERC721Pausable.sol create mode 100644 contracts/token/ERC721/extensions/ERC721Royalty.sol create mode 100644 contracts/token/ERC721/extensions/ERC721URIStorage.sol create mode 100644 contracts/token/ERC721/extensions/ERC721Votes.sol create mode 100644 contracts/token/ERC721/extensions/ERC721Wrapper.sol create mode 100644 contracts/token/ERC721/extensions/IERC721Enumerable.sol create mode 100644 contracts/token/ERC721/extensions/IERC721Metadata.sol create mode 100644 contracts/token/ERC721/utils/ERC721Holder.sol create mode 100644 contracts/token/common/ERC2981.sol create mode 100644 contracts/token/common/README.adoc create mode 100644 contracts/utils/Address.sol create mode 100644 contracts/utils/Arrays.sol create mode 100644 contracts/utils/Base64.sol create mode 100644 contracts/utils/Context.sol create mode 100644 contracts/utils/Create2.sol create mode 100644 contracts/utils/Multicall.sol create mode 100644 contracts/utils/Nonces.sol create mode 100644 contracts/utils/Pausable.sol create mode 100644 contracts/utils/README.adoc create mode 100644 contracts/utils/ReentrancyGuard.sol create mode 100644 contracts/utils/ShortStrings.sol create mode 100644 contracts/utils/StorageSlot.sol create mode 100644 contracts/utils/Strings.sol create mode 100644 contracts/utils/cryptography/ECDSA.sol create mode 100644 contracts/utils/cryptography/EIP712.sol create mode 100644 contracts/utils/cryptography/MerkleProof.sol create mode 100644 contracts/utils/cryptography/MessageHashUtils.sol create mode 100644 contracts/utils/cryptography/SignatureChecker.sol create mode 100644 contracts/utils/introspection/ERC165.sol create mode 100644 contracts/utils/introspection/ERC165Checker.sol create mode 100644 contracts/utils/introspection/IERC165.sol create mode 100644 contracts/utils/math/Math.sol create mode 100644 contracts/utils/math/SafeCast.sol create mode 100644 contracts/utils/math/SignedMath.sol create mode 100644 contracts/utils/structs/BitMaps.sol create mode 100644 contracts/utils/structs/Checkpoints.sol create mode 100644 contracts/utils/structs/DoubleEndedQueue.sol create mode 100644 contracts/utils/structs/EnumerableMap.sol create mode 100644 contracts/utils/structs/EnumerableSet.sol create mode 100644 contracts/utils/types/Time.sol create mode 100644 contracts/vendor/compound/ICompoundTimelock.sol create mode 100644 contracts/vendor/compound/LICENSE create mode 100644 docs/README.md create mode 100644 docs/antora.yml create mode 100644 docs/config.js create mode 100644 docs/modules/ROOT/images/erc4626-attack-3a.png create mode 100644 docs/modules/ROOT/images/erc4626-attack-3b.png create mode 100644 docs/modules/ROOT/images/erc4626-attack-6.png create mode 100644 docs/modules/ROOT/images/erc4626-attack.png create mode 100644 docs/modules/ROOT/images/erc4626-deposit.png create mode 100644 docs/modules/ROOT/images/erc4626-mint.png create mode 100644 docs/modules/ROOT/images/erc4626-rate-linear.png create mode 100644 docs/modules/ROOT/images/erc4626-rate-loglog.png create mode 100644 docs/modules/ROOT/images/erc4626-rate-loglogext.png create mode 100644 docs/modules/ROOT/images/tally-exec.png create mode 100644 docs/modules/ROOT/images/tally-vote.png create mode 100644 docs/modules/ROOT/nav.adoc create mode 100644 docs/modules/ROOT/pages/access-control.adoc create mode 100644 docs/modules/ROOT/pages/crowdsales.adoc create mode 100644 docs/modules/ROOT/pages/drafts.adoc create mode 100644 docs/modules/ROOT/pages/erc1155.adoc create mode 100644 docs/modules/ROOT/pages/erc20-supply.adoc create mode 100644 docs/modules/ROOT/pages/erc20.adoc create mode 100644 docs/modules/ROOT/pages/erc4626.adoc create mode 100644 docs/modules/ROOT/pages/erc721.adoc create mode 100644 docs/modules/ROOT/pages/extending-contracts.adoc create mode 100644 docs/modules/ROOT/pages/faq.adoc create mode 100644 docs/modules/ROOT/pages/governance.adoc create mode 100644 docs/modules/ROOT/pages/index.adoc create mode 100644 docs/modules/ROOT/pages/releases-stability.adoc create mode 100644 docs/modules/ROOT/pages/tokens.adoc create mode 100644 docs/modules/ROOT/pages/upgradeable.adoc create mode 100644 docs/modules/ROOT/pages/utilities.adoc create mode 100644 docs/modules/ROOT/pages/wizard.adoc create mode 100644 docs/modules/api/examples/ERC4626Fees.sol create mode 100644 docs/modules/api/examples/governance/MyGovernor.sol create mode 100644 docs/modules/api/examples/governance/MyToken.sol create mode 100644 docs/modules/api/examples/governance/MyTokenTimestampBased.sol create mode 100644 docs/modules/api/examples/governance/MyTokenWrapped.sol create mode 100644 docs/modules/api/nav.adoc create mode 100644 docs/modules/api/pages/access.adoc create mode 100644 docs/modules/api/pages/finance.adoc create mode 100644 docs/modules/api/pages/governance.adoc create mode 100644 docs/modules/api/pages/interfaces.adoc create mode 100644 docs/modules/api/pages/metatx.adoc create mode 100644 docs/modules/api/pages/proxy.adoc create mode 100644 docs/modules/api/pages/token/ERC1155.adoc create mode 100644 docs/modules/api/pages/token/ERC20.adoc create mode 100644 docs/modules/api/pages/token/ERC721.adoc create mode 100644 docs/modules/api/pages/token/common.adoc create mode 100644 docs/modules/api/pages/utils.adoc create mode 100644 docs/templates/contract.hbs create mode 100644 docs/templates/helpers.js create mode 100644 docs/templates/page.hbs create mode 100644 docs/templates/properties.js create mode 100644 foundry.toml create mode 100644 hardhat.config.js create mode 100644 hardhat/env-artifacts.js create mode 100644 hardhat/env-contract.js create mode 100644 hardhat/ignore-unreachable-warnings.js create mode 100644 hardhat/skip-foundry-tests.js create mode 100644 hardhat/task-test-get-files.js create mode 160000 lib/erc4626-tests create mode 160000 lib/forge-std create mode 100644 logo.svg create mode 100644 netlify.toml create mode 100644 package-lock.json create mode 100644 package.json create mode 100644 remappings.txt create mode 100644 renovate.json create mode 100644 requirements.txt create mode 100644 scripts/checks/compare-layout.js create mode 100755 scripts/checks/compareGasReports.js create mode 100644 scripts/checks/extract-layout.js create mode 100755 scripts/checks/generation.sh create mode 100755 scripts/checks/inheritance-ordering.js create mode 100644 scripts/gen-nav.js create mode 100644 scripts/generate/format-lines.js create mode 100755 scripts/generate/run.js create mode 100644 scripts/generate/templates/Checkpoints.js create mode 100644 scripts/generate/templates/Checkpoints.opts.js create mode 100644 scripts/generate/templates/Checkpoints.t.js create mode 100644 scripts/generate/templates/EnumerableMap.js create mode 100644 scripts/generate/templates/EnumerableSet.js create mode 100644 scripts/generate/templates/SafeCast.js create mode 100644 scripts/generate/templates/StorageSlot.js create mode 100644 scripts/generate/templates/conversion.js create mode 100644 scripts/git-user-config.sh create mode 100644 scripts/helpers.js create mode 100755 scripts/prepack.sh create mode 100755 scripts/prepare-contracts-package.sh create mode 100755 scripts/prepare-docs.sh create mode 100755 scripts/prepare.sh create mode 100755 scripts/release/format-changelog.js create mode 100755 scripts/release/synchronize-versions.js create mode 100755 scripts/release/update-comment.js create mode 100755 scripts/release/version.sh create mode 100644 scripts/release/workflow/exit-prerelease.sh create mode 100644 scripts/release/workflow/github-release.js create mode 100644 scripts/release/workflow/integrity-check.sh create mode 100644 scripts/release/workflow/pack.sh create mode 100644 scripts/release/workflow/publish.sh create mode 100644 scripts/release/workflow/rerun.js create mode 100644 scripts/release/workflow/set-changesets-pr-title.js create mode 100644 scripts/release/workflow/start.sh create mode 100644 scripts/release/workflow/state.js create mode 100644 scripts/remove-ignored-artifacts.js create mode 100644 scripts/solhint-custom/index.js create mode 100644 scripts/solhint-custom/package.json create mode 100644 scripts/update-docs-branch.js create mode 100644 scripts/upgradeable/README.md create mode 100755 scripts/upgradeable/patch-apply.sh create mode 100755 scripts/upgradeable/patch-save.sh create mode 100644 scripts/upgradeable/transpile-onto.sh create mode 100644 scripts/upgradeable/transpile.sh create mode 100644 scripts/upgradeable/upgradeable.patch create mode 100644 slither.config.json create mode 100644 solhint.config.js create mode 100644 test/TESTING.md create mode 100644 test/access/AccessControl.behavior.js create mode 100644 test/access/AccessControl.test.js create mode 100644 test/access/Ownable.test.js create mode 100644 test/access/Ownable2Step.test.js create mode 100644 test/access/extensions/AccessControlDefaultAdminRules.test.js create mode 100644 test/access/extensions/AccessControlEnumerable.test.js create mode 100644 test/access/manager/AccessManager.test.js create mode 100644 test/finance/VestingWallet.behavior.js create mode 100644 test/finance/VestingWallet.test.js create mode 100644 test/governance/Governor.t.sol create mode 100644 test/governance/Governor.test.js create mode 100644 test/governance/TimelockController.test.js create mode 100644 test/governance/extensions/GovernorERC721.test.js create mode 100644 test/governance/extensions/GovernorPreventLateQuorum.test.js create mode 100644 test/governance/extensions/GovernorStorage.test.js create mode 100644 test/governance/extensions/GovernorTimelockAccess.test.js create mode 100644 test/governance/extensions/GovernorTimelockCompound.test.js create mode 100644 test/governance/extensions/GovernorTimelockControl.test.js create mode 100644 test/governance/extensions/GovernorVotesQuorumFraction.test.js create mode 100644 test/governance/extensions/GovernorWithParams.test.js create mode 100644 test/governance/utils/EIP6372.behavior.js create mode 100644 test/governance/utils/Votes.behavior.js create mode 100644 test/governance/utils/Votes.test.js create mode 100644 test/helpers/account.js create mode 100644 test/helpers/chainid.js create mode 100644 test/helpers/constants.js create mode 100644 test/helpers/create.js create mode 100644 test/helpers/customError.js create mode 100644 test/helpers/eip712.js create mode 100644 test/helpers/enums.js create mode 100644 test/helpers/erc1967.js create mode 100644 test/helpers/governance.js create mode 100644 test/helpers/iterate.js create mode 100644 test/helpers/math.js create mode 100644 test/helpers/methods.js create mode 100644 test/helpers/sign.js create mode 100644 test/helpers/time.js create mode 100644 test/helpers/txpool.js create mode 100644 test/metatx/ERC2771Context.test.js create mode 100644 test/metatx/ERC2771Forwarder.t.sol create mode 100644 test/metatx/ERC2771Forwarder.test.js create mode 100644 test/proxy/Clones.behaviour.js create mode 100644 test/proxy/Clones.test.js create mode 100644 test/proxy/ERC1967/ERC1967Proxy.test.js create mode 100644 test/proxy/ERC1967/ERC1967Utils.test.js create mode 100644 test/proxy/Proxy.behaviour.js create mode 100644 test/proxy/beacon/BeaconProxy.test.js create mode 100644 test/proxy/beacon/UpgradeableBeacon.test.js create mode 100644 test/proxy/transparent/ProxyAdmin.test.js create mode 100644 test/proxy/transparent/TransparentUpgradeableProxy.behaviour.js create mode 100644 test/proxy/transparent/TransparentUpgradeableProxy.test.js create mode 100644 test/proxy/utils/Initializable.test.js create mode 100644 test/proxy/utils/UUPSUpgradeable.test.js create mode 100644 test/token/ERC1155/ERC1155.behavior.js create mode 100644 test/token/ERC1155/ERC1155.test.js create mode 100644 test/token/ERC1155/extensions/ERC1155Burnable.test.js create mode 100644 test/token/ERC1155/extensions/ERC1155Pausable.test.js create mode 100644 test/token/ERC1155/extensions/ERC1155Supply.test.js create mode 100644 test/token/ERC1155/extensions/ERC1155URIStorage.test.js create mode 100644 test/token/ERC1155/utils/ERC1155Holder.test.js create mode 100644 test/token/ERC20/ERC20.behavior.js create mode 100644 test/token/ERC20/ERC20.test.js create mode 100644 test/token/ERC20/extensions/ERC20Burnable.behavior.js create mode 100644 test/token/ERC20/extensions/ERC20Burnable.test.js create mode 100644 test/token/ERC20/extensions/ERC20Capped.behavior.js create mode 100644 test/token/ERC20/extensions/ERC20Capped.test.js create mode 100644 test/token/ERC20/extensions/ERC20FlashMint.test.js create mode 100644 test/token/ERC20/extensions/ERC20Pausable.test.js create mode 100644 test/token/ERC20/extensions/ERC20Permit.test.js create mode 100644 test/token/ERC20/extensions/ERC20Votes.test.js create mode 100644 test/token/ERC20/extensions/ERC20Wrapper.test.js create mode 100644 test/token/ERC20/extensions/ERC4626.t.sol create mode 100644 test/token/ERC20/extensions/ERC4626.test.js create mode 100644 test/token/ERC20/utils/SafeERC20.test.js create mode 100644 test/token/ERC721/ERC721.behavior.js create mode 100644 test/token/ERC721/ERC721.test.js create mode 100644 test/token/ERC721/ERC721Enumerable.test.js create mode 100644 test/token/ERC721/extensions/ERC721Burnable.test.js create mode 100644 test/token/ERC721/extensions/ERC721Consecutive.t.sol create mode 100644 test/token/ERC721/extensions/ERC721Consecutive.test.js create mode 100644 test/token/ERC721/extensions/ERC721Pausable.test.js create mode 100644 test/token/ERC721/extensions/ERC721Royalty.test.js create mode 100644 test/token/ERC721/extensions/ERC721URIStorage.test.js create mode 100644 test/token/ERC721/extensions/ERC721Votes.test.js create mode 100644 test/token/ERC721/extensions/ERC721Wrapper.test.js create mode 100644 test/token/ERC721/utils/ERC721Holder.test.js create mode 100644 test/token/common/ERC2981.behavior.js create mode 100644 test/utils/Address.test.js create mode 100644 test/utils/Arrays.test.js create mode 100644 test/utils/Base64.test.js create mode 100644 test/utils/Context.behavior.js create mode 100644 test/utils/Context.test.js create mode 100644 test/utils/Create2.test.js create mode 100644 test/utils/Multicall.test.js create mode 100644 test/utils/Nonces.test.js create mode 100644 test/utils/Pausable.test.js create mode 100644 test/utils/ReentrancyGuard.test.js create mode 100644 test/utils/ShortStrings.t.sol create mode 100644 test/utils/ShortStrings.test.js create mode 100644 test/utils/StorageSlot.test.js create mode 100644 test/utils/Strings.test.js create mode 100644 test/utils/cryptography/ECDSA.test.js create mode 100644 test/utils/cryptography/EIP712.test.js create mode 100644 test/utils/cryptography/MerkleProof.test.js create mode 100644 test/utils/cryptography/MessageHashUtils.test.js create mode 100644 test/utils/cryptography/SignatureChecker.test.js create mode 100644 test/utils/introspection/ERC165.test.js create mode 100644 test/utils/introspection/ERC165Checker.test.js create mode 100644 test/utils/introspection/SupportsInterface.behavior.js create mode 100644 test/utils/math/Math.t.sol create mode 100644 test/utils/math/Math.test.js create mode 100644 test/utils/math/SafeCast.test.js create mode 100644 test/utils/math/SignedMath.test.js create mode 100644 test/utils/structs/BitMap.test.js create mode 100644 test/utils/structs/Checkpoints.t.sol create mode 100644 test/utils/structs/Checkpoints.test.js create mode 100644 test/utils/structs/DoubleEndedQueue.test.js create mode 100644 test/utils/structs/EnumerableMap.behavior.js create mode 100644 test/utils/structs/EnumerableMap.test.js create mode 100644 test/utils/structs/EnumerableSet.behavior.js create mode 100644 test/utils/structs/EnumerableSet.test.js create mode 100644 test/utils/types/Time.test.js diff --git a/.changeset/afraid-walls-smell.md b/.changeset/afraid-walls-smell.md new file mode 100644 index 000000000..682fdde5e --- /dev/null +++ b/.changeset/afraid-walls-smell.md @@ -0,0 +1,5 @@ +--- +'openzeppelin-solidity': major +--- + +`ERC1155Receiver`: Removed in favor of `ERC1155Holder`. diff --git a/.changeset/angry-ties-switch.md b/.changeset/angry-ties-switch.md new file mode 100644 index 000000000..f3ec7db38 --- /dev/null +++ b/.changeset/angry-ties-switch.md @@ -0,0 +1,5 @@ +--- +'openzeppelin-solidity': major +--- + +`TimelockController`: Changed the role architecture to use `DEFAULT_ADMIN_ROLE` as the admin for all roles, instead of the bespoke `TIMELOCK_ADMIN_ROLE` that was used previously. This aligns with the general recommendation for `AccessControl` and makes the addition of new roles easier. Accordingly, the `admin` parameter and timelock will now be granted `DEFAULT_ADMIN_ROLE` instead of `TIMELOCK_ADMIN_ROLE`. ([#3799](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3799)) diff --git a/.changeset/big-plums-cover.md b/.changeset/big-plums-cover.md new file mode 100644 index 000000000..411156253 --- /dev/null +++ b/.changeset/big-plums-cover.md @@ -0,0 +1,4 @@ +--- +'openzeppelin-solidity': major +--- +Use `abi.encodeCall` in place of `abi.encodeWithSelector` and `abi.encodeWithSignature` for improved type-checking of parameters diff --git a/.changeset/blue-horses-do.md b/.changeset/blue-horses-do.md new file mode 100644 index 000000000..9df604fe4 --- /dev/null +++ b/.changeset/blue-horses-do.md @@ -0,0 +1,5 @@ +--- +'openzeppelin-solidity': major +--- + +`ERC2771Forwarder`: Added `deadline` for expiring transactions, batching, and more secure handling of `msg.value`. diff --git a/.changeset/blue-scissors-design.md b/.changeset/blue-scissors-design.md new file mode 100644 index 000000000..c2f815aae --- /dev/null +++ b/.changeset/blue-scissors-design.md @@ -0,0 +1,5 @@ +--- +'openzeppelin-solidity': minor +--- + +`Math`: Make `ceilDiv` to revert on 0 division even if the numerator is 0 diff --git a/.changeset/brave-lobsters-punch.md b/.changeset/brave-lobsters-punch.md new file mode 100644 index 000000000..60f04e430 --- /dev/null +++ b/.changeset/brave-lobsters-punch.md @@ -0,0 +1,5 @@ +--- +'openzeppelin-solidity': major +--- + +`Governor`: Refactored internals to implement common queuing logic in the core module of the Governor. Added `queue` and `_queueOperations` functions that act at different levels. Modules that implement queuing via timelocks are expected to override `_queueOperations` to implement the timelock-specific logic. Added `_executeOperations` as the equivalent for execution. diff --git a/.changeset/bright-tomatoes-sing.md b/.changeset/bright-tomatoes-sing.md new file mode 100644 index 000000000..7ef6d929a --- /dev/null +++ b/.changeset/bright-tomatoes-sing.md @@ -0,0 +1,5 @@ +--- +'openzeppelin-solidity': major +--- + +`ERC20`, `ERC721`, `ERC1155`: Deleted `_beforeTokenTransfer` and `_afterTokenTransfer` hooks, added a new internal `_update` function for customizations, and refactored all extensions using those hooks to use `_update` instead. ([#3838](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3838), [#3876](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3876), [#4377](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/4377)) diff --git a/.changeset/chilled-spiders-attack.md b/.changeset/chilled-spiders-attack.md new file mode 100644 index 000000000..ef3fc4f55 --- /dev/null +++ b/.changeset/chilled-spiders-attack.md @@ -0,0 +1,5 @@ +--- +'openzeppelin-solidity': major +--- + +`ERC1155Supply`: add a `totalSupply()` function that returns the total amount of token circulating, this change will restrict the total tokens minted across all ids to 2\*\*256-1 . diff --git a/.changeset/clever-bats-kick.md b/.changeset/clever-bats-kick.md new file mode 100644 index 000000000..b35301b73 --- /dev/null +++ b/.changeset/clever-bats-kick.md @@ -0,0 +1,5 @@ +--- +'openzeppelin-solidity': patch +--- + +`Ownable`: Prevent using address(0) as the initial owner. diff --git a/.changeset/clever-pumas-beg.md b/.changeset/clever-pumas-beg.md new file mode 100644 index 000000000..5f1f4b13b --- /dev/null +++ b/.changeset/clever-pumas-beg.md @@ -0,0 +1,5 @@ +--- +'openzeppelin-solidity': major +--- + +`Ownable`: Add an `initialOwner` parameter to the constructor, making the ownership initialization explicit. diff --git a/.changeset/config.json b/.changeset/config.json new file mode 100644 index 000000000..66794faef --- /dev/null +++ b/.changeset/config.json @@ -0,0 +1,12 @@ +{ + "$schema": "https://unpkg.com/@changesets/config@2.3.0/schema.json", + "changelog": [ + "@changesets/changelog-github", + { + "repo": "OpenZeppelin/openzeppelin-contracts" + } + ], + "commit": false, + "access": "public", + "baseBranch": "master" +} diff --git a/.changeset/eight-peaches-guess.md b/.changeset/eight-peaches-guess.md new file mode 100644 index 000000000..ba4e87c17 --- /dev/null +++ b/.changeset/eight-peaches-guess.md @@ -0,0 +1,5 @@ +--- +'openzeppelin-solidity': minor +--- + +`Proxy`: Removed redundant `receive` function. diff --git a/.changeset/eighty-crabs-listen.md b/.changeset/eighty-crabs-listen.md new file mode 100644 index 000000000..7de904db8 --- /dev/null +++ b/.changeset/eighty-crabs-listen.md @@ -0,0 +1,5 @@ +--- +'openzeppelin-solidity': patch +--- + +Optimize `Strings.equal` diff --git a/.changeset/eighty-lemons-shake.md b/.changeset/eighty-lemons-shake.md new file mode 100644 index 000000000..4e53893f5 --- /dev/null +++ b/.changeset/eighty-lemons-shake.md @@ -0,0 +1,5 @@ +--- +'openzeppelin-solidity': major +--- + +`ERC721`: `_approve` no longer allows approving the owner of the tokenId. `_setApprovalForAll` no longer allows setting address(0) as an operator. diff --git a/.changeset/empty-cheetahs-hunt.md b/.changeset/empty-cheetahs-hunt.md new file mode 100644 index 000000000..eb20381a6 --- /dev/null +++ b/.changeset/empty-cheetahs-hunt.md @@ -0,0 +1,5 @@ +--- +'openzeppelin-solidity': major +--- + +`ERC721URIStorage`: Allow setting the token URI prior to minting. diff --git a/.changeset/empty-taxis-kiss.md b/.changeset/empty-taxis-kiss.md new file mode 100644 index 000000000..b01c92bd0 --- /dev/null +++ b/.changeset/empty-taxis-kiss.md @@ -0,0 +1,5 @@ +--- +'openzeppelin-solidity': major +--- + +`UUPSUpgradeable`, `TransparentUpgradeableProxy` and `ProxyAdmin`: Removed `upgradeTo` and `upgrade` functions, and made `upgradeToAndCall` and `upgradeAndCall` ignore the data argument if it is empty. It is no longer possible to invoke the receive function (or send value with empty data) along with an upgrade. diff --git a/.changeset/fair-humans-peel.md b/.changeset/fair-humans-peel.md new file mode 100644 index 000000000..3c0dc3c06 --- /dev/null +++ b/.changeset/fair-humans-peel.md @@ -0,0 +1,5 @@ +--- +'openzeppelin-solidity': major +--- + +`ERC721URIStorage`, `ERC721Royalty`: Stop resetting token-specific URI and royalties when burning. diff --git a/.changeset/fifty-owls-retire.md b/.changeset/fifty-owls-retire.md new file mode 100644 index 000000000..118fad421 --- /dev/null +++ b/.changeset/fifty-owls-retire.md @@ -0,0 +1,5 @@ +--- +'openzeppelin-solidity': major +--- + +`Address`: Removed the ability to customize error messages. A common custom error is always used if the underlying revert reason cannot be bubbled up. diff --git a/.changeset/flat-bottles-wonder.md b/.changeset/flat-bottles-wonder.md new file mode 100644 index 000000000..f7ee7dd5d --- /dev/null +++ b/.changeset/flat-bottles-wonder.md @@ -0,0 +1,7 @@ +--- +'openzeppelin-solidity': minor +--- + +Replace some uses of `abi.encodePacked` with clearer alternatives (e.g. `bytes.concat`, `string.concat`). (#4504)[https://github.com/OpenZeppelin/openzeppelin-contracts/pull/4504] + +pr: #4296 diff --git a/.changeset/fluffy-countries-buy.md b/.changeset/fluffy-countries-buy.md new file mode 100644 index 000000000..0cc7de370 --- /dev/null +++ b/.changeset/fluffy-countries-buy.md @@ -0,0 +1,5 @@ +--- +'openzeppelin-solidity': minor +--- + +`Arrays`: Optimize `findUpperBound` by removing redundant SLOAD. diff --git a/.changeset/four-adults-knock.md b/.changeset/four-adults-knock.md new file mode 100644 index 000000000..f6f566d7a --- /dev/null +++ b/.changeset/four-adults-knock.md @@ -0,0 +1,5 @@ +--- +'openzeppelin-solidity': patch +--- + +`ECDSA`: Use unchecked arithmetic for the `tryRecover` function that receives the `r` and `vs` short-signature fields separately. diff --git a/.changeset/fresh-birds-kiss.md b/.changeset/fresh-birds-kiss.md new file mode 100644 index 000000000..221f54cdf --- /dev/null +++ b/.changeset/fresh-birds-kiss.md @@ -0,0 +1,5 @@ +--- +'openzeppelin-solidity': major +--- + +`Checkpoints`: library moved from `utils` to `utils/structs` diff --git a/.changeset/green-pumpkins-end.md b/.changeset/green-pumpkins-end.md new file mode 100644 index 000000000..03cfe023f --- /dev/null +++ b/.changeset/green-pumpkins-end.md @@ -0,0 +1,5 @@ +--- +'openzeppelin-solidity': major +--- + +`SafeERC20`: Removed `safePermit` in favor of documentation-only `permit` recommendations. diff --git a/.changeset/grumpy-bulldogs-call.md b/.changeset/grumpy-bulldogs-call.md new file mode 100644 index 000000000..c034587f3 --- /dev/null +++ b/.changeset/grumpy-bulldogs-call.md @@ -0,0 +1,5 @@ +--- +'openzeppelin-solidity': major +--- + +`Governor`: Optimized use of storage for proposal data diff --git a/.changeset/grumpy-worms-tease.md b/.changeset/grumpy-worms-tease.md new file mode 100644 index 000000000..910b996c6 --- /dev/null +++ b/.changeset/grumpy-worms-tease.md @@ -0,0 +1,5 @@ +--- +'openzeppelin-solidity': major +--- + +`ERC1967Utils`: Refactor the `ERC1967Upgrade` abstract contract as a library. diff --git a/.changeset/happy-falcons-walk.md b/.changeset/happy-falcons-walk.md new file mode 100644 index 000000000..bba9642aa --- /dev/null +++ b/.changeset/happy-falcons-walk.md @@ -0,0 +1,5 @@ +--- +'openzeppelin-solidity': major +--- + +`TransparentUpgradeableProxy`: Admin is now stored in an immutable variable (set during construction) to avoid unnecessary storage reads on every proxy call. This removed the ability to ever change the admin. Transfer of the upgrade capability is exclusively handled through the ownership of the `ProxyAdmin`. diff --git a/.changeset/healthy-gorillas-applaud.md b/.changeset/healthy-gorillas-applaud.md new file mode 100644 index 000000000..1d4156ebf --- /dev/null +++ b/.changeset/healthy-gorillas-applaud.md @@ -0,0 +1,5 @@ +--- +'openzeppelin-solidity': major +--- + +`VestingWallet`: Use `Ownable` instead of an immutable `beneficiary`. diff --git a/.changeset/heavy-drinks-fail.md b/.changeset/heavy-drinks-fail.md new file mode 100644 index 000000000..bbe93ca90 --- /dev/null +++ b/.changeset/heavy-drinks-fail.md @@ -0,0 +1,5 @@ +--- +'openzeppelin-solidity': major +--- + +`ERC20`: Remove `Approval` event previously emitted in `transferFrom` to indicate that part of the allowance was consumed. With this change, allowances are no longer reconstructible from events. See the code for guidelines on how to re-enable this event if needed. diff --git a/.changeset/hip-beds-provide.md b/.changeset/hip-beds-provide.md new file mode 100644 index 000000000..c67283813 --- /dev/null +++ b/.changeset/hip-beds-provide.md @@ -0,0 +1,5 @@ +--- +'openzeppelin-solidity': major +--- + +Move the logic to validate ERC-1822 during an upgrade from `ERC1967Utils` to `UUPSUpgradeable`. diff --git a/.changeset/hip-goats-fail.md b/.changeset/hip-goats-fail.md new file mode 100644 index 000000000..5cfe2ef79 --- /dev/null +++ b/.changeset/hip-goats-fail.md @@ -0,0 +1,5 @@ +--- +'openzeppelin-solidity': patch +--- + +`VestingWallet`: Fix revert during 1 second time window when duration is 0. diff --git a/.changeset/hot-coins-judge.md b/.changeset/hot-coins-judge.md new file mode 100644 index 000000000..e544af467 --- /dev/null +++ b/.changeset/hot-coins-judge.md @@ -0,0 +1,5 @@ +--- +'openzeppelin-solidity': minor +--- + +`Arrays`: Add `unsafeMemoryAccess` helpers to read from a memory array without checking the length. diff --git a/.changeset/hot-dingos-kiss.md b/.changeset/hot-dingos-kiss.md new file mode 100644 index 000000000..fb213cd64 --- /dev/null +++ b/.changeset/hot-dingos-kiss.md @@ -0,0 +1,5 @@ +--- +'openzeppelin-solidity': major +--- + +`MessageHashUtils`: Add a new library for creating message digest to be used along with signing or recovery such as ECDSA or ERC-1271. These functions are moved from the `ECDSA` library. diff --git a/.changeset/hot-plums-approve.md b/.changeset/hot-plums-approve.md new file mode 100644 index 000000000..131559027 --- /dev/null +++ b/.changeset/hot-plums-approve.md @@ -0,0 +1,5 @@ +--- +'openzeppelin-solidity': minor +--- + +`GovernorTimelockControl`: Clean up timelock id on execution for gas refund. diff --git a/.changeset/large-humans-remain.md b/.changeset/large-humans-remain.md new file mode 100644 index 000000000..95b72aea4 --- /dev/null +++ b/.changeset/large-humans-remain.md @@ -0,0 +1,5 @@ +--- +'openzeppelin-solidity': patch +--- + +`MerkleProof`: Use custom error to report invalid multiproof instead of reverting with overflow panic. diff --git a/.changeset/lazy-rice-joke.md b/.changeset/lazy-rice-joke.md new file mode 100644 index 000000000..6e1243002 --- /dev/null +++ b/.changeset/lazy-rice-joke.md @@ -0,0 +1,5 @@ +--- +'openzeppelin-solidity': minor +--- + +`Initializable`: Use intermediate variables to improve readability. diff --git a/.changeset/little-falcons-build.md b/.changeset/little-falcons-build.md new file mode 100644 index 000000000..b310a8ae6 --- /dev/null +++ b/.changeset/little-falcons-build.md @@ -0,0 +1,5 @@ +--- +'openzeppelin-solidity': minor +--- + +`EIP712`: Add internal getters for the name and version strings diff --git a/.changeset/loud-shrimps-play.md b/.changeset/loud-shrimps-play.md new file mode 100644 index 000000000..3de2da080 --- /dev/null +++ b/.changeset/loud-shrimps-play.md @@ -0,0 +1,5 @@ +--- +'openzeppelin-solidity': minor +--- + +`TimelockController`: Add a state getter that returns an `OperationState` enum. diff --git a/.changeset/lovely-geckos-hide.md b/.changeset/lovely-geckos-hide.md new file mode 100644 index 000000000..1fbcb2077 --- /dev/null +++ b/.changeset/lovely-geckos-hide.md @@ -0,0 +1,5 @@ +--- +'openzeppelin-solidity': major +--- + +Replace revert strings and require statements with custom errors. diff --git a/.changeset/mean-walls-watch.md b/.changeset/mean-walls-watch.md new file mode 100644 index 000000000..6bcf609b8 --- /dev/null +++ b/.changeset/mean-walls-watch.md @@ -0,0 +1,5 @@ +--- +'openzeppelin-solidity': major +--- + +`Nonces`: Added a new contract to keep track of user nonces. Used for signatures in `ERC20Permit`, `ERC20Votes`, and `ERC721Votes`. ([#3816](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3816)) diff --git a/.changeset/mighty-donuts-smile.md b/.changeset/mighty-donuts-smile.md new file mode 100644 index 000000000..5885a7370 --- /dev/null +++ b/.changeset/mighty-donuts-smile.md @@ -0,0 +1,6 @@ +--- +'openzeppelin-solidity': patch +--- + +`Governor`: Add validation in ERC1155 and ERC721 receiver hooks to ensure Governor is the executor. + diff --git a/.changeset/orange-apes-draw.md b/.changeset/orange-apes-draw.md new file mode 100644 index 000000000..5f2b7d928 --- /dev/null +++ b/.changeset/orange-apes-draw.md @@ -0,0 +1,5 @@ +--- +'openzeppelin-solidity': major +--- + +Switched to using explicit Solidity import statements. Some previously available symbols may now have to be separately imported. diff --git a/.changeset/pink-suns-mix.md b/.changeset/pink-suns-mix.md new file mode 100644 index 000000000..eb7aaac46 --- /dev/null +++ b/.changeset/pink-suns-mix.md @@ -0,0 +1,5 @@ +--- +'openzeppelin-solidity': patch +--- + +`Math`: Optimized stack operations in `mulDiv`. diff --git a/.changeset/popular-deers-raise.md b/.changeset/popular-deers-raise.md new file mode 100644 index 000000000..ec1fb7466 --- /dev/null +++ b/.changeset/popular-deers-raise.md @@ -0,0 +1,5 @@ +--- +'openzeppelin-solidity': major +--- + +`Governor`: Add support for casting votes with ERC-1271 signatures by using a `bytes memory signature` instead of `r`, `s` and `v` arguments in the `castVoteBySig` and `castVoteWithReasonAndParamsBySig` functions. diff --git a/.changeset/pre.json b/.changeset/pre.json new file mode 100644 index 000000000..66e5164bf --- /dev/null +++ b/.changeset/pre.json @@ -0,0 +1,85 @@ +{ + "mode": "pre", + "tag": "rc", + "initialVersions": { + "openzeppelin-solidity": "4.9.2" + }, + "changesets": [ + "afraid-walls-smell", + "angry-ties-switch", + "big-plums-cover", + "blue-horses-do", + "blue-scissors-design", + "brave-lobsters-punch", + "bright-tomatoes-sing", + "chilled-spiders-attack", + "clever-bats-kick", + "clever-pumas-beg", + "eight-peaches-guess", + "eighty-crabs-listen", + "eighty-lemons-shake", + "empty-cheetahs-hunt", + "empty-taxis-kiss", + "fair-humans-peel", + "fifty-owls-retire", + "flat-bottles-wonder", + "fluffy-countries-buy", + "four-adults-knock", + "fresh-birds-kiss", + "green-pumpkins-end", + "grumpy-bulldogs-call", + "grumpy-worms-tease", + "happy-falcons-walk", + "healthy-gorillas-applaud", + "heavy-drinks-fail", + "hip-beds-provide", + "hip-goats-fail", + "hot-coins-judge", + "hot-dingos-kiss", + "hot-plums-approve", + "large-humans-remain", + "lazy-rice-joke", + "little-falcons-build", + "loud-shrimps-play", + "lovely-geckos-hide", + "mean-walls-watch", + "mighty-donuts-smile", + "orange-apes-draw", + "pink-suns-mix", + "popular-deers-raise", + "proud-seals-complain", + "proud-spiders-attend", + "purple-cats-cheer", + "quiet-trainers-kick", + "red-dots-fold", + "rotten-insects-wash", + "serious-books-lie", + "short-eels-enjoy", + "silly-bees-beam", + "six-frogs-turn", + "sixty-numbers-reply", + "slimy-penguins-attack", + "smooth-books-wink", + "smooth-cougars-jump", + "spicy-sheep-eat", + "spotty-hotels-type", + "strong-poems-thank", + "swift-bags-divide", + "swift-numbers-cry", + "tasty-tomatoes-turn", + "tender-shirts-turn", + "thick-pumpkins-exercise", + "thin-camels-matter", + "tough-drinks-hammer", + "two-wasps-punch", + "unlucky-beans-obey", + "violet-dancers-cough", + "violet-melons-press", + "warm-guests-rule", + "wet-bears-heal", + "wild-beds-visit", + "wild-peas-remain", + "wild-rockets-rush", + "wild-windows-trade" + ] +} diff --git a/.changeset/proud-seals-complain.md b/.changeset/proud-seals-complain.md new file mode 100644 index 000000000..35df4777e --- /dev/null +++ b/.changeset/proud-seals-complain.md @@ -0,0 +1,5 @@ +--- +'openzeppelin-solidity': patch +--- + +`BeaconProxy`: Use an immutable variable to store the address of the beacon. It is no longer possible for a `BeaconProxy` to upgrade by changing to another beacon. diff --git a/.changeset/proud-spiders-attend.md b/.changeset/proud-spiders-attend.md new file mode 100644 index 000000000..a8f7694c7 --- /dev/null +++ b/.changeset/proud-spiders-attend.md @@ -0,0 +1,5 @@ +--- +'openzeppelin-solidity': major +--- + +`ERC721`: Renamed `_requireMinted` to `_requireOwned` and added a return value with the current owner. Implemented `ownerOf` in terms of `_requireOwned`. diff --git a/.changeset/purple-cats-cheer.md b/.changeset/purple-cats-cheer.md new file mode 100644 index 000000000..7e9dc1c4d --- /dev/null +++ b/.changeset/purple-cats-cheer.md @@ -0,0 +1,5 @@ +--- +'openzeppelin-solidity': major +--- + +`GovernorTimelockControl`: Add the Governor instance address as part of the TimelockController operation `salt` to avoid operation id collisions between governors using the same TimelockController. diff --git a/.changeset/quiet-trainers-kick.md b/.changeset/quiet-trainers-kick.md new file mode 100644 index 000000000..5de96467d --- /dev/null +++ b/.changeset/quiet-trainers-kick.md @@ -0,0 +1,5 @@ +--- +'openzeppelin-solidity': minor +--- + +`AccessManager`: Added a new contract for managing access control of complex systems in a consolidated location. diff --git a/.changeset/red-dots-fold.md b/.changeset/red-dots-fold.md new file mode 100644 index 000000000..08cc77843 --- /dev/null +++ b/.changeset/red-dots-fold.md @@ -0,0 +1,5 @@ +--- +'openzeppelin-solidity': major +--- + +Overrides are now used internally for a number of functions that were previously hardcoded to their default implementation in certain locations: `ERC1155Supply.totalSupply`, `ERC721.ownerOf`, `ERC721.balanceOf` and `ERC721.totalSupply` in `ERC721Enumerable`, `ERC20.totalSupply` in `ERC20FlashMint`, and `ERC1967._getImplementation` in `ERC1967Proxy`. diff --git a/.changeset/rotten-insects-wash.md b/.changeset/rotten-insects-wash.md new file mode 100644 index 000000000..9b2f11706 --- /dev/null +++ b/.changeset/rotten-insects-wash.md @@ -0,0 +1,5 @@ +--- +'openzeppelin-solidity': major +--- + +`ProxyAdmin`: Removed `getProxyAdmin` and `getProxyImplementation` getters. ([#3820](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3820)) diff --git a/.changeset/serious-books-lie.md b/.changeset/serious-books-lie.md new file mode 100644 index 000000000..6f0a0a732 --- /dev/null +++ b/.changeset/serious-books-lie.md @@ -0,0 +1,5 @@ +--- +'openzeppelin-solidity': patch +--- + +`ERC1155`: Optimize array allocation. diff --git a/.changeset/short-eels-enjoy.md b/.changeset/short-eels-enjoy.md new file mode 100644 index 000000000..e826c6d19 --- /dev/null +++ b/.changeset/short-eels-enjoy.md @@ -0,0 +1,5 @@ +--- +'openzeppelin-solidity': major +--- + +Bump minimum compiler version required to 0.8.20 diff --git a/.changeset/silly-bees-beam.md b/.changeset/silly-bees-beam.md new file mode 100644 index 000000000..0f4f40507 --- /dev/null +++ b/.changeset/silly-bees-beam.md @@ -0,0 +1,7 @@ +--- +'openzeppelin-solidity': major +--- + +`ERC20Votes`: Changed internal vote accounting to reusable `Votes` module previously used by `ERC721Votes`. Removed implicit `ERC20Permit` inheritance. Note that the `DOMAIN_SEPARATOR` getter was previously guaranteed to be available for `ERC20Votes` contracts, but is no longer available unless `ERC20Permit` is explicitly used; ERC-5267 support is included in `ERC20Votes` with `EIP712` and is recommended as an alternative. + +pr: #3816 diff --git a/.changeset/six-frogs-turn.md b/.changeset/six-frogs-turn.md new file mode 100644 index 000000000..9c5668b6d --- /dev/null +++ b/.changeset/six-frogs-turn.md @@ -0,0 +1,5 @@ +--- +'openzeppelin-solidity': major +--- + +`ERC20`: Remove the non-standard `increaseAllowance` and `decreaseAllowance` functions. diff --git a/.changeset/sixty-numbers-reply.md b/.changeset/sixty-numbers-reply.md new file mode 100644 index 000000000..4e6faa837 --- /dev/null +++ b/.changeset/sixty-numbers-reply.md @@ -0,0 +1,5 @@ +--- +'openzeppelin-solidity': major +--- + +`Governor`: Add `voter` and `nonce` parameters in signed ballots, to avoid forging signatures for random addresses, prevent signature replay, and allow invalidating signatures. Add `voter` as a new parameter in the `castVoteBySig` and `castVoteWithReasonAndParamsBySig` functions. diff --git a/.changeset/slimy-penguins-attack.md b/.changeset/slimy-penguins-attack.md new file mode 100644 index 000000000..dcf91e90b --- /dev/null +++ b/.changeset/slimy-penguins-attack.md @@ -0,0 +1,5 @@ +--- +'openzeppelin-solidity': major +--- + +`TransparentUpgradeableProxy`: Removed `admin` and `implementation` getters, which were only callable by the proxy owner and thus not very useful. ([#3820](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3820)) diff --git a/.changeset/smooth-books-wink.md b/.changeset/smooth-books-wink.md new file mode 100644 index 000000000..e5eb3fbeb --- /dev/null +++ b/.changeset/smooth-books-wink.md @@ -0,0 +1,5 @@ +--- +'openzeppelin-solidity': major +--- + +`ERC1155`: Remove check for address zero in `balanceOf`. diff --git a/.changeset/smooth-cougars-jump.md b/.changeset/smooth-cougars-jump.md new file mode 100644 index 000000000..337101cd0 --- /dev/null +++ b/.changeset/smooth-cougars-jump.md @@ -0,0 +1,5 @@ +--- +'openzeppelin-solidity': major +--- + +`ReentrancyGuard`, `Pausable`: Moved to `utils` directory. diff --git a/.changeset/spicy-sheep-eat.md b/.changeset/spicy-sheep-eat.md new file mode 100644 index 000000000..17b6d5585 --- /dev/null +++ b/.changeset/spicy-sheep-eat.md @@ -0,0 +1,5 @@ +--- +'openzeppelin-solidity': major +--- + +`access`: Move `AccessControl` extensions to a dedicated directory. diff --git a/.changeset/spotty-hotels-type.md b/.changeset/spotty-hotels-type.md new file mode 100644 index 000000000..866d8fc02 --- /dev/null +++ b/.changeset/spotty-hotels-type.md @@ -0,0 +1,5 @@ +--- +'openzeppelin-solidity': patch +--- + +`ERC721Consecutive`: Add a `_firstConsecutiveId` internal function that can be overridden to change the id of the first token minted through `_mintConsecutive`. diff --git a/.changeset/strong-poems-thank.md b/.changeset/strong-poems-thank.md new file mode 100644 index 000000000..5f496de7f --- /dev/null +++ b/.changeset/strong-poems-thank.md @@ -0,0 +1,5 @@ +--- +'openzeppelin-solidity': major +--- + +`DoubleEndedQueue`: refactor internal structure to use `uint128` instead of `int128`. This has no effect on the library interface. diff --git a/.changeset/swift-bags-divide.md b/.changeset/swift-bags-divide.md new file mode 100644 index 000000000..9af63e98e --- /dev/null +++ b/.changeset/swift-bags-divide.md @@ -0,0 +1,5 @@ +--- +'openzeppelin-solidity': patch +--- + +`Governor`: Add a mechanism to restrict the address of the proposer using a suffix in the description. diff --git a/.changeset/swift-numbers-cry.md b/.changeset/swift-numbers-cry.md new file mode 100644 index 000000000..48afbd245 --- /dev/null +++ b/.changeset/swift-numbers-cry.md @@ -0,0 +1,5 @@ +--- +'openzeppelin-solidity': minor +--- + +`Governor`, `Initializable`, and `UUPSUpgradeable`: Use internal functions in modifiers to optimize bytecode size. diff --git a/.changeset/tasty-tomatoes-turn.md b/.changeset/tasty-tomatoes-turn.md new file mode 100644 index 000000000..3fe46a9b1 --- /dev/null +++ b/.changeset/tasty-tomatoes-turn.md @@ -0,0 +1,5 @@ +--- +'openzeppelin-solidity': major +--- + +`Strings`: Rename `toString(int256)` to `toStringSigned(int256)`. diff --git a/.changeset/tender-shirts-turn.md b/.changeset/tender-shirts-turn.md new file mode 100644 index 000000000..9c98e6e2b --- /dev/null +++ b/.changeset/tender-shirts-turn.md @@ -0,0 +1,5 @@ +--- +'openzeppelin-solidity': major +--- + +`BeaconProxy`: Reject value in initialization unless a payable function is explicitly invoked. diff --git a/.changeset/thick-pumpkins-exercise.md b/.changeset/thick-pumpkins-exercise.md new file mode 100644 index 000000000..8df8b51cc --- /dev/null +++ b/.changeset/thick-pumpkins-exercise.md @@ -0,0 +1,5 @@ +--- +'openzeppelin-solidity': major +--- + +`Initializable`: Use the namespaced storage pattern to avoid putting critical variables in slot 0. Allow reinitializer versions greater than 256. diff --git a/.changeset/thin-camels-matter.md b/.changeset/thin-camels-matter.md new file mode 100644 index 000000000..c832b1163 --- /dev/null +++ b/.changeset/thin-camels-matter.md @@ -0,0 +1,5 @@ +--- +'openzeppelin-solidity': minor +--- + +`ERC1155`: Bubble errors triggered in the `onERC1155Received` and `onERC1155BatchReceived` hooks. diff --git a/.changeset/tough-drinks-hammer.md b/.changeset/tough-drinks-hammer.md new file mode 100644 index 000000000..51b3836e4 --- /dev/null +++ b/.changeset/tough-drinks-hammer.md @@ -0,0 +1,5 @@ +--- +'openzeppelin-solidity': patch +--- + +`ERC1155`: Optimize array accesses by skipping bounds checking when unnecessary. diff --git a/.changeset/two-wasps-punch.md b/.changeset/two-wasps-punch.md new file mode 100644 index 000000000..d382ab6e9 --- /dev/null +++ b/.changeset/two-wasps-punch.md @@ -0,0 +1,5 @@ +--- +'openzeppelin-solidity': minor +--- + +`AccessControl`: Add a boolean return value to the internal `_grantRole` and `_revokeRole` functions indicating whether the role was granted or revoked. diff --git a/.changeset/unlucky-beans-obey.md b/.changeset/unlucky-beans-obey.md new file mode 100644 index 000000000..e472d3c6c --- /dev/null +++ b/.changeset/unlucky-beans-obey.md @@ -0,0 +1,5 @@ +--- +'openzeppelin-solidity': patch +--- + +`ERC2771Context`: Return the forwarder address whenever the `msg.data` of a call originating from a trusted forwarder is not long enough to contain the request signer address (i.e. `msg.data.length` is less than 20 bytes), as specified by ERC-2771. diff --git a/.changeset/violet-dancers-cough.md b/.changeset/violet-dancers-cough.md new file mode 100644 index 000000000..c6160d287 --- /dev/null +++ b/.changeset/violet-dancers-cough.md @@ -0,0 +1,5 @@ +--- +'openzeppelin-solidity': minor +--- + +Remove the `override` specifier from functions that only override a single interface function. diff --git a/.changeset/violet-melons-press.md b/.changeset/violet-melons-press.md new file mode 100644 index 000000000..18fd70b58 --- /dev/null +++ b/.changeset/violet-melons-press.md @@ -0,0 +1,5 @@ +--- +'openzeppelin-solidity': major +--- + +`GovernorTimelockAccess`: Added a module to connect a governor with an instance of `AccessManager`, allowing the governor to make calls that are delay-restricted by the manager using the normal `queue` workflow. diff --git a/.changeset/warm-guests-rule.md b/.changeset/warm-guests-rule.md new file mode 100644 index 000000000..049da4dd5 --- /dev/null +++ b/.changeset/warm-guests-rule.md @@ -0,0 +1,5 @@ +--- +'openzeppelin-solidity': patch +--- + +`ERC2771Context`: Prevent revert in `_msgData()` when a call originating from a trusted forwarder is not long enough to contain the request signer address (i.e. `msg.data.length` is less than 20 bytes). Return the full calldata in that case. diff --git a/.changeset/wet-bears-heal.md b/.changeset/wet-bears-heal.md new file mode 100644 index 000000000..2df32f39a --- /dev/null +++ b/.changeset/wet-bears-heal.md @@ -0,0 +1,5 @@ +--- +'openzeppelin-solidity': major +--- + +Upgradeable contracts now use namespaced storage (EIP-7201). diff --git a/.changeset/wild-beds-visit.md b/.changeset/wild-beds-visit.md new file mode 100644 index 000000000..e97dee284 --- /dev/null +++ b/.changeset/wild-beds-visit.md @@ -0,0 +1,5 @@ +--- +'openzeppelin-solidity': major +--- + +`GovernorStorage`: Added a new governor extension that stores the proposal details in storage, with an interface that operates on `proposalId`, as well as proposal enumerability. This replaces the old `GovernorCompatibilityBravo` module. diff --git a/.changeset/wild-peas-remain.md b/.changeset/wild-peas-remain.md new file mode 100644 index 000000000..83b4bb307 --- /dev/null +++ b/.changeset/wild-peas-remain.md @@ -0,0 +1,5 @@ +--- +'openzeppelin-solidity': major +--- + +`Votes`: Use Trace208 for checkpoints. This enables EIP-6372 clock support for keys but reduces the max supported voting power to uint208. diff --git a/.changeset/wild-rockets-rush.md b/.changeset/wild-rockets-rush.md new file mode 100644 index 000000000..7fc6f598d --- /dev/null +++ b/.changeset/wild-rockets-rush.md @@ -0,0 +1,5 @@ +--- +'openzeppelin-solidity': major +--- + +`Math`: Renamed members of `Rounding` enum, and added a new rounding mode for "away from zero". diff --git a/.changeset/wild-windows-trade.md b/.changeset/wild-windows-trade.md new file mode 100644 index 000000000..f599d0fcb --- /dev/null +++ b/.changeset/wild-windows-trade.md @@ -0,0 +1,5 @@ +--- +'openzeppelin-solidity': major +--- + +`SafeERC20`: Refactor `safeDecreaseAllowance` and `safeIncreaseAllowance` to support USDT-like tokens. diff --git a/.codecov.yml b/.codecov.yml new file mode 100644 index 000000000..9455306a4 --- /dev/null +++ b/.codecov.yml @@ -0,0 +1,12 @@ +comment: off +github_checks: + annotations: false +coverage: + status: + patch: + default: + target: 95% + only_pulls: true + project: + default: + threshold: 1% diff --git a/.editorconfig b/.editorconfig new file mode 100644 index 000000000..f162e8d20 --- /dev/null +++ b/.editorconfig @@ -0,0 +1,21 @@ +# EditorConfig is awesome: https://EditorConfig.org + +# top-most EditorConfig file +root = true + +[*] +charset = utf-8 +end_of_line = lf +indent_style = space +insert_final_newline = true +trim_trailing_whitespace = false +max_line_length = 120 + +[*.sol] +indent_size = 4 + +[*.js] +indent_size = 2 + +[*.{adoc,md}] +max_line_length = 0 diff --git a/.eslintrc b/.eslintrc new file mode 100644 index 000000000..a5418c5e4 --- /dev/null +++ b/.eslintrc @@ -0,0 +1,20 @@ +{ + "root": true, + "extends" : [ + "eslint:recommended", + "prettier", + ], + "env": { + "es2022": true, + "browser": true, + "node": true, + "mocha": true, + }, + "globals" : { + "artifacts": "readonly", + "contract": "readonly", + "web3": "readonly", + "extendEnvironment": "readonly", + "expect": "readonly", + } +} diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md new file mode 100644 index 000000000..2797a0889 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -0,0 +1,21 @@ +--- +name: Bug report +about: Report a bug in OpenZeppelin Contracts + +--- + + + + + +**💻 Environment** + + + +**📝 Details** + + + +**🔢 Code to reproduce bug** + + diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 000000000..4018cef29 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,4 @@ +contact_links: + - name: Questions & Support Requests + url: https://forum.openzeppelin.com/c/support/contracts/18 + about: Ask in the OpenZeppelin Forum diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md new file mode 100644 index 000000000..ff596b0c3 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -0,0 +1,14 @@ +--- +name: Feature request +about: Suggest an idea for OpenZeppelin Contracts + +--- + +**🧐 Motivation** + + +**📝 Details** + + + + diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 000000000..239451830 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,20 @@ + + + + + +Fixes #???? + + + + + +#### PR Checklist + + + + + +- [ ] Tests +- [ ] Documentation +- [ ] Changeset entry (run `npx changeset add`) diff --git a/.github/actions/gas-compare/action.yml b/.github/actions/gas-compare/action.yml new file mode 100644 index 000000000..e38c48e89 --- /dev/null +++ b/.github/actions/gas-compare/action.yml @@ -0,0 +1,49 @@ +name: Compare gas costs +inputs: + token: + description: github token + required: true + report: + description: report to read from + required: false + default: gasReporterOutput.json + out_report: + description: report to read + required: false + default: ${{ github.ref_name }}.gasreport.json + ref_report: + description: report to read from + required: false + default: ${{ github.base_ref }}.gasreport.json + +runs: + using: composite + steps: + - name: Download reference report + if: github.event_name == 'pull_request' + run: | + RUN_ID=`gh run list --repo ${{ github.repository }} --branch ${{ github.base_ref }} --workflow ${{ github.workflow }} --limit 100 --json 'conclusion,databaseId,event' --jq 'map(select(.conclusion=="success" and .event!="pull_request"))[0].databaseId'` + gh run download ${RUN_ID} --repo ${{ github.repository }} -n gasreport + env: + GITHUB_TOKEN: ${{ inputs.token }} + shell: bash + continue-on-error: true + id: reference + - name: Compare reports + if: steps.reference.outcome == 'success' && github.event_name == 'pull_request' + run: | + node scripts/checks/compareGasReports.js ${{ inputs.report }} ${{ inputs.ref_report }} >> $GITHUB_STEP_SUMMARY + env: + STYLE: markdown + shell: bash + - name: Rename report for upload + if: github.event_name != 'pull_request' + run: | + mv ${{ inputs.report }} ${{ inputs.out_report }} + shell: bash + - name: Save report + if: github.event_name != 'pull_request' + uses: actions/upload-artifact@v3 + with: + name: gasreport + path: ${{ inputs.out_report }} diff --git a/.github/actions/setup/action.yml b/.github/actions/setup/action.yml new file mode 100644 index 000000000..84ebe823a --- /dev/null +++ b/.github/actions/setup/action.yml @@ -0,0 +1,19 @@ +name: Setup + +runs: + using: composite + steps: + - uses: actions/setup-node@v3 + with: + node-version: 16.x + - uses: actions/cache@v3 + id: cache + with: + path: '**/node_modules' + key: npm-v3-${{ hashFiles('**/package-lock.json') }} + - name: Install dependencies + run: npm ci + shell: bash + if: steps.cache.outputs.cache-hit != 'true' + env: + SKIP_COMPILE: true diff --git a/.github/actions/storage-layout/action.yml b/.github/actions/storage-layout/action.yml new file mode 100644 index 000000000..fdfd5a25b --- /dev/null +++ b/.github/actions/storage-layout/action.yml @@ -0,0 +1,55 @@ +name: Compare storage layouts +inputs: + token: + description: github token + required: true + buildinfo: + description: compilation artifacts + required: false + default: artifacts/build-info/*.json + layout: + description: extracted storage layout + required: false + default: HEAD.layout.json + out_layout: + description: storage layout to upload + required: false + default: ${{ github.ref_name }}.layout.json + ref_layout: + description: storage layout for the reference branch + required: false + default: ${{ github.base_ref }}.layout.json + +runs: + using: composite + steps: + - name: Extract layout + run: | + node scripts/checks/extract-layout.js ${{ inputs.buildinfo }} > ${{ inputs.layout }} + shell: bash + - name: Download reference + if: github.event_name == 'pull_request' + run: | + RUN_ID=`gh run list --repo ${{ github.repository }} --branch ${{ github.base_ref }} --workflow ${{ github.workflow }} --limit 100 --json 'conclusion,databaseId,event' --jq 'map(select(.conclusion=="success" and .event!="pull_request"))[0].databaseId'` + gh run download ${RUN_ID} --repo ${{ github.repository }} -n layout + env: + GITHUB_TOKEN: ${{ inputs.token }} + shell: bash + continue-on-error: true + id: reference + - name: Compare layouts + if: steps.reference.outcome == 'success' && github.event_name == 'pull_request' + run: | + node scripts/checks/compare-layout.js --head ${{ inputs.layout }} --ref ${{ inputs.ref_layout }} + shell: bash + - name: Rename artifacts for upload + if: github.event_name != 'pull_request' + run: | + mv ${{ inputs.layout }} ${{ inputs.out_layout }} + shell: bash + - name: Save artifacts + if: github.event_name != 'pull_request' + uses: actions/upload-artifact@v3 + with: + name: layout + path: ${{ inputs.out_layout }} diff --git a/.github/workflows/actionlint.yml b/.github/workflows/actionlint.yml new file mode 100644 index 000000000..3e42c8a26 --- /dev/null +++ b/.github/workflows/actionlint.yml @@ -0,0 +1,18 @@ +name: lint workflows + +on: + pull_request: + paths: + - '.github/**/*.ya?ml' + +jobs: + lint: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: Add problem matchers + run: | + # https://github.com/rhysd/actionlint/blob/3a2f2c7/docs/usage.md#problem-matchers + curl -LO https://raw.githubusercontent.com/rhysd/actionlint/main/.github/actionlint-matcher.json + echo "::add-matcher::actionlint-matcher.json" + - uses: docker://rhysd/actionlint:latest diff --git a/.github/workflows/changeset.yml b/.github/workflows/changeset.yml new file mode 100644 index 000000000..efc5c5347 --- /dev/null +++ b/.github/workflows/changeset.yml @@ -0,0 +1,28 @@ +name: changeset + +on: + pull_request: + branches: + - master + types: + - opened + - synchronize + - labeled + - unlabeled + +concurrency: + group: changeset-${{ github.ref }} + cancel-in-progress: true + +jobs: + check: + runs-on: ubuntu-latest + if: ${{ !contains(github.event.pull_request.labels.*.name, 'ignore-changeset') }} + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 # Include history so Changesets finds merge-base + - name: Set up environment + uses: ./.github/actions/setup + - name: Check changeset + run: npx changeset status --since=origin/${{ github.base_ref }} diff --git a/.github/workflows/checks.yml b/.github/workflows/checks.yml new file mode 100644 index 000000000..3d9b199fb --- /dev/null +++ b/.github/workflows/checks.yml @@ -0,0 +1,116 @@ +name: checks + +on: + push: + branches: + - master + - next-v* + - release-v* + pull_request: {} + workflow_dispatch: {} + +concurrency: + group: checks-${{ github.ref }} + cancel-in-progress: true + +env: + NODE_OPTIONS: --max_old_space_size=5120 + +jobs: + lint: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: Set up environment + uses: ./.github/actions/setup + - run: npm run lint + + tests: + runs-on: ubuntu-latest + env: + FORCE_COLOR: 1 + GAS: true + steps: + - uses: actions/checkout@v4 + - name: Set up environment + uses: ./.github/actions/setup + - name: Run tests and generate gas report + run: npm run test + - name: Check linearisation of the inheritance graph + run: npm run test:inheritance + - name: Check proceduraly generated contracts are up-to-date + run: npm run test:generation + - name: Compare gas costs + uses: ./.github/actions/gas-compare + if: github.base_ref == 'master' + with: + token: ${{ github.token }} + + tests-upgradeable: + runs-on: ubuntu-latest + env: + FORCE_COLOR: 1 + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 # Include history so patch conflicts are resolved automatically + - name: Set up environment + uses: ./.github/actions/setup + - name: Transpile to upgradeable + run: bash scripts/upgradeable/transpile.sh + - name: Run tests + run: npm run test + - name: Check linearisation of the inheritance graph + run: npm run test:inheritance + - name: Check storage layout + uses: ./.github/actions/storage-layout + if: github.base_ref == 'master' + continue-on-error: ${{ contains(github.event.pull_request.labels.*.name, 'breaking change') }} + with: + token: ${{ github.token }} + + tests-foundry: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + with: + submodules: recursive + - name: Install Foundry + uses: foundry-rs/foundry-toolchain@v1 + with: + version: nightly + - name: Run tests + run: forge test -vv + + coverage: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: Set up environment + uses: ./.github/actions/setup + - run: npm run coverage + - uses: codecov/codecov-action@v3 + with: + token: ${{ secrets.CODECOV_TOKEN }} + + slither: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: Set up environment + uses: ./.github/actions/setup + - run: rm foundry.toml + - uses: crytic/slither-action@v0.3.0 + with: + node-version: 18.15 + + codespell: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: Run CodeSpell + uses: codespell-project/actions-codespell@v2.0 + with: + check_hidden: true + check_filenames: true + skip: package-lock.json,*.pdf diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 000000000..04b8131cb --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,19 @@ +name: Build Docs + +on: + push: + branches: [release-v*] + +permissions: + contents: write + +jobs: + build: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: Set up environment + uses: ./.github/actions/setup + - run: bash scripts/git-user-config.sh + - run: node scripts/update-docs-branch.js + - run: git push --all origin diff --git a/.github/workflows/formal-verification.yml b/.github/workflows/formal-verification.yml new file mode 100644 index 000000000..6b4ca2cad --- /dev/null +++ b/.github/workflows/formal-verification.yml @@ -0,0 +1,68 @@ +name: formal verification + +on: + pull_request: + types: + - opened + - reopened + - synchronize + - labeled + workflow_dispatch: {} + +env: + PIP_VERSION: '3.10' + JAVA_VERSION: '11' + SOLC_VERSION: '0.8.20' + +concurrency: ${{ github.workflow }}-${{ github.ref }} + +jobs: + apply-diff: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: Apply patches + run: make -C certora apply + + verify: + runs-on: ubuntu-latest + if: github.event_name != 'pull_request' || contains(github.event.pull_request.labels.*.name, 'formal-verification') + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 + - name: Set up environment + uses: ./.github/actions/setup + - name: identify specs that need to be run + id: arguments + run: | + if [[ ${{ github.event_name }} = 'pull_request' ]]; + then + RESULT=$(git diff ${{ github.event.pull_request.head.sha }}..${{ github.event.pull_request.base.sha }} --name-only certora/specs/*.spec | while IFS= read -r file; do [[ -f $file ]] && basename "${file%.spec}"; done | tr "\n" " ") + else + RESULT='--all' + fi + echo "result=$RESULT" >> "$GITHUB_OUTPUT" + - name: Install python + uses: actions/setup-python@v4 + with: + python-version: ${{ env.PIP_VERSION }} + cache: 'pip' + - name: Install python packages + run: pip install -r requirements.txt + - name: Install java + uses: actions/setup-java@v3 + with: + distribution: temurin + java-version: ${{ env.JAVA_VERSION }} + - name: Install solc + run: | + wget https://github.com/ethereum/solidity/releases/download/v${{ env.SOLC_VERSION }}/solc-static-linux + sudo mv solc-static-linux /usr/local/bin/solc + chmod +x /usr/local/bin/solc + - name: Verify specification + run: | + make -C certora apply + node certora/run.js ${{ steps.arguments.outputs.result }} >> "$GITHUB_STEP_SUMMARY" + env: + CERTORAKEY: ${{ secrets.CERTORAKEY }} diff --git a/.github/workflows/release-cycle.yml b/.github/workflows/release-cycle.yml new file mode 100644 index 000000000..21d77abb9 --- /dev/null +++ b/.github/workflows/release-cycle.yml @@ -0,0 +1,218 @@ +# D: Manual Dispatch +# M: Merge release PR +# C: Commit +# ┌───────────┐ ┌─────────────┐ ┌────────────────┐ +# │Development├──D──►RC-Unreleased│ ┌──►Final-Unreleased│ +# └───────────┘ └─┬─────────▲─┘ │ └─┬────────────▲─┘ +# │ │ │ │ │ +# M C D M C +# │ │ │ │ │ +# ┌▼─────────┴┐ │ ┌▼────────────┴┐ +# │RC-Released├───┘ │Final-Released│ +# └───────────┘ └──────────────┘ +name: Release Cycle + +on: + push: + branches: + - release-v* + workflow_dispatch: {} + +concurrency: ${{ github.workflow }}-${{ github.ref }} + +jobs: + state: + name: Check state + permissions: + pull-requests: read + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: Set up environment + uses: ./.github/actions/setup + - id: state + name: Get state + uses: actions/github-script@v6 + env: + TRIGGERING_ACTOR: ${{ github.triggering_actor }} + with: + result-encoding: string + script: await require('./scripts/release/workflow/state.js')({ github, context, core }) + outputs: + # Job Flags + start: ${{ steps.state.outputs.start }} + changesets: ${{ steps.state.outputs.changesets }} + promote: ${{ steps.state.outputs.promote }} + publish: ${{ steps.state.outputs.publish }} + merge: ${{ steps.state.outputs.merge }} + + # Global variables + is_prerelease: ${{ steps.state.outputs.is_prerelease }} + + start: + needs: state + name: Start new release candidate + permissions: + contents: write + actions: write + if: needs.state.outputs.start == 'true' + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: Set up environment + uses: ./.github/actions/setup + - run: bash scripts/git-user-config.sh + - id: start + name: Create branch with release candidate + run: bash scripts/release/workflow/start.sh + - name: Re-run workflow + uses: actions/github-script@v6 + env: + REF: ${{ steps.start.outputs.branch }} + with: + script: await require('./scripts/release/workflow/rerun.js')({ github, context }) + + promote: + needs: state + name: Promote to final release + permissions: + contents: write + actions: write + if: needs.state.outputs.promote == 'true' + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: Set up environment + uses: ./.github/actions/setup + - run: bash scripts/git-user-config.sh + - name: Exit prerelease state + if: needs.state.outputs.is_prerelease == 'true' + run: bash scripts/release/workflow/exit-prerelease.sh + - name: Re-run workflow + uses: actions/github-script@v6 + with: + script: await require('./scripts/release/workflow/rerun.js')({ github, context }) + + changesets: + needs: state + name: Update PR to release + permissions: + contents: write + pull-requests: write + if: needs.state.outputs.changesets == 'true' + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 # To get all tags + - name: Set up environment + uses: ./.github/actions/setup + - name: Set release title + uses: actions/github-script@v6 + with: + result-encoding: string + script: await require('./scripts/release/workflow/set-changesets-pr-title.js')({ core }) + - name: Create PR + uses: changesets/action@v1 + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + PRERELEASE: ${{ needs.state.outputs.is_prerelease }} + with: + version: npm run version + title: ${{ env.TITLE }} + commit: ${{ env.TITLE }} + body: | # Wait for support on this https://github.com/changesets/action/pull/250 + This is an automated PR for releasing ${{ github.repository }} + Check [CHANGELOG.md](${{ github.repository }}/CHANGELOG.md) + + publish: + needs: state + name: Publish to npm + environment: npm + permissions: + contents: write + if: needs.state.outputs.publish == 'true' + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: Set up environment + uses: ./.github/actions/setup + - id: pack + name: Pack + run: bash scripts/release/workflow/pack.sh + env: + PRERELEASE: ${{ needs.state.outputs.is_prerelease }} + - name: Upload tarball artifact + uses: actions/upload-artifact@v3 + with: + name: ${{ github.ref_name }} + path: ${{ steps.pack.outputs.tarball }} + - name: Tag + run: npx changeset tag + - name: Publish + run: bash scripts/release/workflow/publish.sh + env: + NPM_TOKEN: ${{ secrets.NPM_TOKEN }} + TARBALL: ${{ steps.pack.outputs.tarball }} + TAG: ${{ steps.pack.outputs.tag }} + - name: Push tags + run: git push --tags + - name: Create Github Release + uses: actions/github-script@v6 + env: + PRERELEASE: ${{ needs.state.outputs.is_prerelease }} + with: + script: await require('./scripts/release/workflow/github-release.js')({ github, context }) + outputs: + tarball_name: ${{ steps.pack.outputs.tarball_name }} + + integrity_check: + needs: publish + name: Tarball Integrity Check + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: Download tarball artifact + id: artifact + # Replace with actions/upload-artifact@v3 when + # https://github.com/actions/download-artifact/pull/194 gets released + uses: actions/download-artifact@e9ef242655d12993efdcda9058dee2db83a2cb9b + with: + name: ${{ github.ref_name }} + - name: Check integrity + run: bash scripts/release/workflow/integrity-check.sh + env: + TARBALL: ${{ steps.artifact.outputs.download-path }}/${{ needs.publish.outputs.tarball_name }} + + merge: + needs: state + name: Create PR back to master + permissions: + contents: write + pull-requests: write + if: needs.state.outputs.merge == 'true' + runs-on: ubuntu-latest + env: + MERGE_BRANCH: merge/${{ github.ref_name }} + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 # All branches + - name: Set up environment + uses: ./.github/actions/setup + - run: bash scripts/git-user-config.sh + - name: Create branch to merge + run: | + git checkout -B "$MERGE_BRANCH" "$GITHUB_REF_NAME" + git push -f origin "$MERGE_BRANCH" + - name: Create PR back to master + uses: actions/github-script@v6 + with: + script: | + await github.rest.pulls.create({ + owner: context.repo.owner, + repo: context.repo.repo, + head: process.env.MERGE_BRANCH, + base: 'master', + title: '${{ format('Merge {0} branch', github.ref_name) }}' + }); diff --git a/.github/workflows/upgradeable.yml b/.github/workflows/upgradeable.yml new file mode 100644 index 000000000..ed63a6dbe --- /dev/null +++ b/.github/workflows/upgradeable.yml @@ -0,0 +1,30 @@ +name: transpile upgradeable + +on: + push: + branches: + - master + - release-v* + +jobs: + transpile: + environment: push-upgradeable + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + with: + repository: OpenZeppelin/openzeppelin-contracts-upgradeable + fetch-depth: 0 + token: ${{ secrets.GH_TOKEN_UPGRADEABLE }} + - name: Fetch current non-upgradeable branch + run: | + git fetch "https://github.com/${{ github.repository }}.git" "$REF" + git checkout FETCH_HEAD + env: + REF: ${{ github.ref }} + - name: Set up environment + uses: ./.github/actions/setup + - run: bash scripts/git-user-config.sh + - name: Transpile to upgradeable + run: bash scripts/upgradeable/transpile-onto.sh ${{ github.ref_name }} origin/${{ github.ref_name }} + - run: git push origin ${{ github.ref_name }} diff --git a/.gitignore b/.gitignore new file mode 100644 index 000000000..2aac74485 --- /dev/null +++ b/.gitignore @@ -0,0 +1,71 @@ +*.swp +*.swo + +# Logs +logs +*.log + +# Runtime data +pids +*.pid +*.seed +allFiredEvents +scTopics + +# Coverage directory used by tools like istanbul +coverage +coverage.json +coverageEnv + +# node-waf configuration +.lock-wscript + +# Dependency directory +node_modules + +# Debug log from npm +npm-debug.log + +# local env variables +.env + +# truffle build directory +build/ + +# macOS +.DS_Store + +# truffle +.node-xmlhttprequest-* + +# IntelliJ IDE +.idea + +# docs artifacts +docs/modules/api + +# only used to package @openzeppelin/contracts +contracts/build/ +contracts/README.md + +# temporary artifact from solidity-coverage +allFiredEvents +.coverage_artifacts +.coverage_cache +.coverage_contracts + +# hardat-exposed +contracts-exposed + +# Hardhat +/cache +/artifacts + +# Foundry +/out + +# Certora +.certora* +.last_confs +certora_* +.zip-output-url.txt diff --git a/.gitmodules b/.gitmodules new file mode 100644 index 000000000..08a09bbcf --- /dev/null +++ b/.gitmodules @@ -0,0 +1,7 @@ +[submodule "lib/forge-std"] + branch = v1 + path = lib/forge-std + url = https://github.com/foundry-rs/forge-std +[submodule "lib/erc4626-tests"] + path = lib/erc4626-tests + url = https://github.com/a16z/erc4626-tests.git diff --git a/.mocharc.js b/.mocharc.js new file mode 100644 index 000000000..920662dbc --- /dev/null +++ b/.mocharc.js @@ -0,0 +1,4 @@ +module.exports = { + require: 'hardhat/register', + timeout: 4000, +}; diff --git a/.prettierrc b/.prettierrc new file mode 100644 index 000000000..39c004c70 --- /dev/null +++ b/.prettierrc @@ -0,0 +1,15 @@ +{ + "printWidth": 120, + "singleQuote": true, + "trailingComma": "all", + "arrowParens": "avoid", + "overrides": [ + { + "files": "*.sol", + "options": { + "singleQuote": false + } + } + ], + "plugins": ["prettier-plugin-solidity"] +} diff --git a/.solcover.js b/.solcover.js new file mode 100644 index 000000000..e0dea5e2c --- /dev/null +++ b/.solcover.js @@ -0,0 +1,13 @@ +module.exports = { + norpc: true, + testCommand: 'npm test', + compileCommand: 'npm run compile', + skipFiles: ['mocks'], + providerOptions: { + default_balance_ether: '10000000000000000000000000', + }, + mocha: { + fgrep: '[skip-on-coverage]', + invert: true, + }, +}; diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 000000000..b500d334f --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,884 @@ +# Changelog + + +## 5.0.0-rc.0 (2023-09-19) + +- `ERC1155Receiver`: Removed in favor of `ERC1155Holder`. ([#4450](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/4450)) +- `TimelockController`: Changed the role architecture to use `DEFAULT_ADMIN_ROLE` as the admin for all roles, instead of the bespoke `TIMELOCK_ADMIN_ROLE` that was used previously. This aligns with the general recommendation for `AccessControl` and makes the addition of new roles easier. Accordingly, the `admin` parameter and timelock will now be granted `DEFAULT_ADMIN_ROLE` instead of `TIMELOCK_ADMIN_ROLE`. ([#3799](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3799)) + +- Use `abi.encodeCall` in place of `abi.encodeWithSelector` and `abi.encodeWithSignature` for improved type-checking of parameters ([#4293](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/4293)) +- `ERC2771Forwarder`: Added `deadline` for expiring transactions, batching, and more secure handling of `msg.value`. ([#4346](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/4346)) +- `Governor`: Refactored internals to implement common queuing logic in the core module of the Governor. Added `queue` and `_queueOperations` functions that act at different levels. Modules that implement queuing via timelocks are expected to override `_queueOperations` to implement the timelock-specific logic. Added `_executeOperations` as the equivalent for execution. ([#4360](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/4360)) +- `ERC20`, `ERC721`, `ERC1155`: Deleted `_beforeTokenTransfer` and `_afterTokenTransfer` hooks, added a new internal `_update` function for customizations, and refactored all extensions using those hooks to use `_update` instead. ([#3838](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3838), [#3876](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3876), [#4377](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/4377)) + +- `ERC1155Supply`: add a `totalSupply()` function that returns the total amount of token circulating, this change will restrict the total tokens minted across all ids to 2\*\*256-1 . ([#3962](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3962)) +- `Ownable`: Add an `initialOwner` parameter to the constructor, making the ownership initialization explicit. ([#4267](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/4267)) +- `ERC721`: `_approve` no longer allows approving the owner of the tokenId. `_setApprovalForAll` no longer allows setting address(0) as an operator. ([#4377](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/4377)) +- `ERC721URIStorage`: Allow setting the token URI prior to minting. ([#4559](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/4559)) +- `UUPSUpgradeable`, `TransparentUpgradeableProxy` and `ProxyAdmin`: Removed `upgradeTo` and `upgrade` functions, and made `upgradeToAndCall` and `upgradeAndCall` ignore the data argument if it is empty. It is no longer possible to invoke the receive function (or send value with empty data) along with an upgrade. ([#4382](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/4382)) +- `ERC721URIStorage`, `ERC721Royalty`: Stop resetting token-specific URI and royalties when burning. ([#4561](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/4561)) +- `Address`: Removed the ability to customize error messages. A common custom error is always used if the underlying revert reason cannot be bubbled up. ([#4502](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/4502)) +- `Checkpoints`: library moved from `utils` to `utils/structs` ([#4275](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/4275)) +- `SafeERC20`: Removed `safePermit` in favor of documentation-only `permit` recommendations. ([#4582](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/4582)) +- `Governor`: Optimized use of storage for proposal data ([#4268](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/4268)) +- `ERC1967Utils`: Refactor the `ERC1967Upgrade` abstract contract as a library. ([#4325](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/4325)) +- `TransparentUpgradeableProxy`: Admin is now stored in an immutable variable (set during construction) to avoid unnecessary storage reads on every proxy call. This removed the ability to ever change the admin. Transfer of the upgrade capability is exclusively handled through the ownership of the `ProxyAdmin`. ([#4354](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/4354)) +- `VestingWallet`: Use `Ownable` instead of an immutable `beneficiary`. ([#4508](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/4508)) +- `ERC20`: Remove `Approval` event previously emitted in `transferFrom` to indicate that part of the allowance was consumed. With this change, allowances are no longer reconstructible from events. See the code for guidelines on how to re-enable this event if needed. ([#4370](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/4370)) +- Move the logic to validate ERC-1822 during an upgrade from `ERC1967Utils` to `UUPSUpgradeable`. ([#4356](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/4356)) +- `MessageHashUtils`: Add a new library for creating message digest to be used along with signing or recovery such as ECDSA or ERC-1271. These functions are moved from the `ECDSA` library. ([#4430](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/4430)) +- Replace revert strings and require statements with custom errors. ([#4261](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/4261)) +- `Nonces`: Added a new contract to keep track of user nonces. Used for signatures in `ERC20Permit`, `ERC20Votes`, and `ERC721Votes`. ([#3816](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3816)) + +- Switched to using explicit Solidity import statements. Some previously available symbols may now have to be separately imported. ([#4399](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/4399)) +- `Governor`: Add support for casting votes with ERC-1271 signatures by using a `bytes memory signature` instead of `r`, `s` and `v` arguments in the `castVoteBySig` and `castVoteWithReasonAndParamsBySig` functions. ([#4418](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/4418)) +- `ERC721`: Renamed `_requireMinted` to `_requireOwned` and added a return value with the current owner. Implemented `ownerOf` in terms of `_requireOwned`. ([#4566](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/4566)) +- `GovernorTimelockControl`: Add the Governor instance address as part of the TimelockController operation `salt` to avoid operation id collisions between governors using the same TimelockController. +- Overrides are now used internally for a number of functions that were previously hardcoded to their default implementation in certain locations: `ERC1155Supply.totalSupply`, `ERC721.ownerOf`, `ERC721.balanceOf` and `ERC721.totalSupply` in `ERC721Enumerable`, `ERC20.totalSupply` in `ERC20FlashMint`, and `ERC1967._getImplementation` in `ERC1967Proxy`. ([#4299](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/4299)) +- `ProxyAdmin`: Removed `getProxyAdmin` and `getProxyImplementation` getters. ([#3820](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3820)) + +- Bump minimum compiler version required to 0.8.20 ([#4288](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/4288)) +- `ERC20Votes`: Changed internal vote accounting to reusable `Votes` module previously used by `ERC721Votes`. Removed implicit `ERC20Permit` inheritance. Note that the `DOMAIN_SEPARATOR` getter was previously guaranteed to be available for `ERC20Votes` contracts, but is no longer available unless `ERC20Permit` is explicitly used; ERC-5267 support is included in `ERC20Votes` with `EIP712` and is recommended as an alternative. ([#3816](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3816)) +- `ERC20`: Remove the non-standard `increaseAllowance` and `decreaseAllowance` functions. ([#4585](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/4585)) +- `Governor`: Add `voter` and `nonce` parameters in signed ballots, to avoid forging signatures for random addresses, prevent signature replay, and allow invalidating signatures. Add `voter` as a new parameter in the `castVoteBySig` and `castVoteWithReasonAndParamsBySig` functions. ([#4378](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/4378)) +- `TransparentUpgradeableProxy`: Removed `admin` and `implementation` getters, which were only callable by the proxy owner and thus not very useful. ([#3820](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3820)) + +- `ERC1155`: Remove check for address zero in `balanceOf`. ([#4263](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/4263)) +- `ReentrancyGuard`, `Pausable`: Moved to `utils` directory. ([#4551](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/4551)) +- `access`: Move `AccessControl` extensions to a dedicated directory. ([#4359](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/4359)) +- `DoubleEndedQueue`: refactor internal structure to use `uint128` instead of `int128`. This has no effect on the library interface. ([#4150](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/4150)) +- `Strings`: Rename `toString(int256)` to `toStringSigned(int256)`. ([#4330](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/4330)) +- `BeaconProxy`: Reject value in initialization unless a payable function is explicitly invoked. ([#4382](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/4382)) +- `Initializable`: Use the namespaced storage pattern to avoid putting critical variables in slot 0. Allow reinitializer versions greater than 256. ([#4460](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/4460)) +- `GovernorTimelockAccess`: Added a module to connect a governor with an instance of `AccessManager`, allowing the governor to make calls that are delay-restricted by the manager using the normal `queue` workflow. ([#4523](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/4523)) +- Upgradeable contracts now use namespaced storage (EIP-7201). ([#4534](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/4534)) +- `GovernorStorage`: Added a new governor extension that stores the proposal details in storage, with an interface that operates on `proposalId`, as well as proposal enumerability. This replaces the old `GovernorCompatibilityBravo` module. ([#4360](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/4360)) +- `Votes`: Use Trace208 for checkpoints. This enables EIP-6372 clock support for keys but reduces the max supported voting power to uint208. ([#4539](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/4539)) +- `Math`: Renamed members of `Rounding` enum, and added a new rounding mode for "away from zero". ([#4455](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/4455)) +- `SafeERC20`: Refactor `safeDecreaseAllowance` and `safeIncreaseAllowance` to support USDT-like tokens. ([#4260](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/4260)) +- `Math`: Make `ceilDiv` to revert on 0 division even if the numerator is 0 ([#4348](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/4348)) +- `Proxy`: Removed redundant `receive` function. ([#4434](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/4434)) +- Replace some uses of `abi.encodePacked` with clearer alternatives (e.g. `bytes.concat`, `string.concat`). (#4504)[https://github.com/OpenZeppelin/openzeppelin-contracts/pull/4504] ([#4296](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/4296)) +- `Arrays`: Optimize `findUpperBound` by removing redundant SLOAD. ([#4442](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/4442)) +- `Arrays`: Add `unsafeMemoryAccess` helpers to read from a memory array without checking the length. ([#4300](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/4300)) +- `GovernorTimelockControl`: Clean up timelock id on execution for gas refund. ([#4118](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/4118)) +- `Initializable`: Use intermediate variables to improve readability. ([#4576](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/4576)) +- `EIP712`: Add internal getters for the name and version strings ([#4303](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/4303)) +- `TimelockController`: Add a state getter that returns an `OperationState` enum. ([#4358](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/4358)) +- `AccessManager`: Added a new contract for managing access control of complex systems in a consolidated location. ([#4121](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/4121)) +- `Governor`, `Initializable`, and `UUPSUpgradeable`: Use internal functions in modifiers to optimize bytecode size. ([#4472](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/4472)) +- `ERC1155`: Bubble errors triggered in the `onERC1155Received` and `onERC1155BatchReceived` hooks. ([#4314](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/4314)) +- `AccessControl`: Add a boolean return value to the internal `_grantRole` and `_revokeRole` functions indicating whether the role was granted or revoked. ([#4241](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/4241)) +- Remove the `override` specifier from functions that only override a single interface function. ([#4315](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/4315)) +- `Ownable`: Prevent using address(0) as the initial owner. ([#4531](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/4531)) +- Optimize `Strings.equal` ([#4262](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/4262)) +- `ECDSA`: Use unchecked arithmetic for the `tryRecover` function that receives the `r` and `vs` short-signature fields separately. ([#4301](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/4301)) +- `VestingWallet`: Fix revert during 1 second time window when duration is 0. ([#4502](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/4502)) +- `MerkleProof`: Use custom error to report invalid multiproof instead of reverting with overflow panic. ([#4564](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/4564)) +- `Governor`: Add validation in ERC1155 and ERC721 receiver hooks to ensure Governor is the executor. ([#4314](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/4314)) +- `Math`: Optimized stack operations in `mulDiv`. ([#4494](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/4494)) +- `BeaconProxy`: Use an immutable variable to store the address of the beacon. It is no longer possible for a `BeaconProxy` to upgrade by changing to another beacon. ([#4435](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/4435)) +- `ERC1155`: Optimize array allocation. ([#4196](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/4196)) +- `ERC721Consecutive`: Add a `_firstConsecutiveId` internal function that can be overridden to change the id of the first token minted through `_mintConsecutive`. ([#4097](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/4097)) +- `Governor`: Add a mechanism to restrict the address of the proposer using a suffix in the description. +- `ERC1155`: Optimize array accesses by skipping bounds checking when unnecessary. ([#4300](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/4300)) +- `ERC2771Context`: Return the forwarder address whenever the `msg.data` of a call originating from a trusted forwarder is not long enough to contain the request signer address (i.e. `msg.data.length` is less than 20 bytes), as specified by ERC-2771. ([#4481](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/4481)) +- `ERC2771Context`: Prevent revert in `_msgData()` when a call originating from a trusted forwarder is not long enough to contain the request signer address (i.e. `msg.data.length` is less than 20 bytes). Return the full calldata in that case. ([#4484](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/4484)) + +## Unreleased + +> **Warning** Version 5.0 is under active development and should not be used. Install the releases from npm or use the version tags in the repository. + +### Removals + +The following contracts, libraries and functions were removed: + +- `Address.isContract` (because of its ambiguous nature and potential for misuse) +- `Checkpoints.History` +- `Counters` +- `ERC20Snapshot` +- `ERC20VotesComp` +- `ERC165Storage` (in favor of inheritance based approach) +- `ERC777` +- `ERC1820Implementer` +- `GovernorVotesComp` +- `GovernorProposalThreshold` (deprecated since 4.4) +- `PaymentSplitter` +- `PullPayment` +- `SafeMath` +- `SignedSafeMath` +- `Timers` +- `TokenTimelock` (in favor of `VestingWallet`) +- All escrow contracts (`Escrow`, `ConditionalEscrow` and `RefundEscrow`) +- All cross-chain contracts, including `AccessControlCrossChain` and all the vendored bridge interfaces +- All presets in favor of [OpenZeppelin Contracts Wizard](https://wizard.openzeppelin.com/) + +These removals were implemented in the following PRs: [#3637](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3637), [#3880](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3880), [#3945](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3945), [#4258](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/4258), [#4276](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/4276), [#4289](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/4289) + +### How to upgrade from 4.x + +#### ERC20, ERC721, and ERC1155 + +These breaking changes will require modifications to ERC20, ERC721, and ERC1155 contracts, since the `_afterTokenTransfer` and `_beforeTokenTransfer` functions were removed. Any customization made through those hooks should now be done overriding the new `_update` function instead. + +Minting and burning are implemented by `_update` and customizations should be done by overriding this function as well. `_transfer`, `_mint` and `_burn` are no longer virtual (meaning they are not overridable) to guard against possible inconsistencies. + +For example, a contract using `ERC20`'s `_beforeTokenTransfer` hook would have to be changed in the following way. + +```diff +- function _beforeTokenTransfer( ++ function _update( + address from, + address to, + uint256 amount + ) internal virtual override { +- super._beforeTokenTransfer(from, to, amount); + require(!condition(), "ERC20: wrong condition"); ++ super._update(from, to, amount); + } +``` + +### More about ERC721 + +In the case of `ERC721`, the `_update` function does not include a `from` parameter, as the sender is implicitly the previous owner of the `tokenId`. The address of +this previous owner is returned by the `_update` function, so it can be used for a posteriori checks. In addition to `to` and `tokenId`, a third parameter (`auth`) is +present in this function. This parameter enabled an optional check that the caller/spender is approved to do the transfer. This check cannot be performed after the transfer (because the transfer resets the approval), and doing it before `_update` would require a duplicate call to `_ownerOf`. + +In this logic of removing hidden SLOADs, the `_isApprovedOrOwner` function was removed in favor of a new `_isAuthorized` function. Overrides that used to target the +`_isApprovedOrOwner` should now be performed on the `_isAuthorized` function. Calls to `_isApprovedOrOwner` that preceded a call to `_transfer`, `_burn` or `_approve` +should be removed in favor of using the `auth` argument in `_update` and `_approve`. This is showcased in `ERC721Burnable.burn` and in `ERC721Wrapper.withdrawTo`. + +The `_exists` function was removed. Calls to this function can be replaced by `_ownerOf(tokenId) != address(0)`. + +#### ERC165Storage + +Users that were registering EIP-165 interfaces with `_registerInterface` from `ERC165Storage` should instead do so so by overriding the `supportsInterface` function as seen below: + +```solidity +function supportsInterface(bytes4 interfaceId) public view virtual override returns (bool) { + return interfaceId == type(MyInterface).interfaceId || super.supportsInterface(interfaceId); +} +``` + +## 4.9.2 (2023-06-16) + +- `MerkleProof`: Fix a bug in `processMultiProof` and `processMultiProofCalldata` that allows proving arbitrary leaves if the tree contains a node with value 0 at depth 1. + +## 4.9.1 (2023-06-07) + +- `Governor`: Add a mechanism to restrict the address of the proposer using a suffix in the description. + +## 4.9.0 (2023-05-23) + +- `ReentrancyGuard`: Add a `_reentrancyGuardEntered` function to expose the guard status. ([#3714](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3714)) +- `ERC721Wrapper`: add a new extension of the `ERC721` token which wraps an underlying token. Deposit and withdraw guarantee that the ownership of each token is backed by a corresponding underlying token with the same identifier. ([#3863](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3863)) +- `EnumerableMap`: add a `keys()` function that returns an array containing all the keys. ([#3920](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3920)) +- `Governor`: add a public `cancel(uint256)` function. ([#3983](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3983)) +- `Governor`: Enable timestamp operation for blockchains without a stable block time. This is achieved by connecting a Governor's internal clock to match a voting token's EIP-6372 interface. ([#3934](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3934)) +- `Strings`: add `equal` method. ([#3774](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3774)) +- `IERC5313`: Add an interface for EIP-5313 that is now final. ([#4013](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/4013)) +- `IERC4906`: Add an interface for ERC-4906 that is now Final. ([#4012](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/4012)) +- `StorageSlot`: Add support for `string` and `bytes`. ([#4008](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/4008)) +- `Votes`, `ERC20Votes`, `ERC721Votes`: support timestamp checkpointing using EIP-6372. ([#3934](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3934)) +- `ERC4626`: Add mitigation to the inflation attack through virtual shares and assets. ([#3979](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3979)) +- `Strings`: add `toString` method for signed integers. ([#3773](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3773)) +- `ERC20Wrapper`: Make the `underlying` variable private and add a public accessor. ([#4029](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/4029)) +- `EIP712`: add EIP-5267 support for better domain discovery. ([#3969](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3969)) +- `AccessControlDefaultAdminRules`: Add an extension of `AccessControl` with additional security rules for the `DEFAULT_ADMIN_ROLE`. ([#4009](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/4009)) +- `SignatureChecker`: Add `isValidERC1271SignatureNow` for checking a signature directly against a smart contract using ERC-1271. ([#3932](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3932)) +- `SafeERC20`: Add a `forceApprove` function to improve compatibility with tokens behaving like USDT. ([#4067](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/4067)) +- `ERC1967Upgrade`: removed contract-wide `oz-upgrades-unsafe-allow delegatecall` annotation, replaced by granular annotation in `UUPSUpgradeable`. ([#3971](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3971)) +- `ERC20Wrapper`: self wrapping and deposit by the wrapper itself are now explicitly forbidden. ([#4100](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/4100)) +- `ECDSA`: optimize bytes32 computation by using assembly instead of `abi.encodePacked`. ([#3853](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3853)) +- `ERC721URIStorage`: Emit ERC-4906 `MetadataUpdate` in `_setTokenURI`. ([#4012](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/4012)) +- `ShortStrings`: Added a library for handling short strings in a gas efficient way, with fallback to storage for longer strings. ([#4023](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/4023)) +- `SignatureChecker`: Allow return data length greater than 32 from EIP-1271 signers. ([#4038](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/4038)) +- `UUPSUpgradeable`: added granular `oz-upgrades-unsafe-allow-reachable` annotation to improve upgrade safety checks on latest version of the Upgrades Plugins (starting with `@openzeppelin/upgrades-core@1.21.0`). ([#3971](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3971)) +- `Initializable`: optimize `_disableInitializers` by using `!=` instead of `<`. ([#3787](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3787)) +- `Ownable2Step`: make `acceptOwnership` public virtual to enable usecases that require overriding it. ([#3960](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3960)) +- `UUPSUpgradeable.sol`: Change visibility to the functions `upgradeTo ` and `upgradeToAndCall ` from `external` to `public`. ([#3959](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3959)) +- `TimelockController`: Add the `CallSalt` event to emit on operation schedule. ([#4001](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/4001)) +- Reformatted codebase with latest version of Prettier Solidity. ([#3898](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3898)) +- `Math`: optimize `log256` rounding check. ([#3745](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3745)) +- `ERC20Votes`: optimize by using unchecked arithmetic. ([#3748](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3748)) +- `Multicall`: annotate `multicall` function as upgrade safe to not raise a flag for its delegatecall. ([#3961](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3961)) +- `ERC20Pausable`, `ERC721Pausable`, `ERC1155Pausable`: Add note regarding missing public pausing functionality ([#4007](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/4007)) +- `ECDSA`: Add a function `toDataWithIntendedValidatorHash` that encodes data with version 0x00 following EIP-191. ([#4063](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/4063)) +- `MerkleProof`: optimize by using unchecked arithmetic. ([#3745](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3745)) + +### Breaking changes + +- `EIP712`: Addition of ERC5267 support requires support for user defined value types, which was released in Solidity version 0.8.8. This requires a pragma change from `^0.8.0` to `^0.8.8`. +- `EIP712`: Optimization of the cache for the upgradeable version affects the way `name` and `version` are set. This is no longer done through an initializer, and is instead part of the implementation's constructor. As a consequence, all proxies using the same implementation will necessarily share the same `name` and `version`. Additionally, an implementation upgrade risks changing the EIP712 domain unless the same `name` and `version` are used when deploying the new implementation contract. + +### Deprecations + +- `ERC20Permit`: Added the file `IERC20Permit.sol` and `ERC20Permit.sol` and deprecated `draft-IERC20Permit.sol` and `draft-ERC20Permit.sol` since [EIP-2612](https://eips.ethereum.org/EIPS/eip-2612) is no longer a Draft. Developers are encouraged to update their imports. ([#3793](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3793)) +- `Timers`: The `Timers` library is now deprecated and will be removed in the next major release. ([#4062](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/4062)) +- `ERC777`: The `ERC777` token standard is no longer supported by OpenZeppelin. Our implementation is now deprecated and will be removed in the next major release. The corresponding standard interfaces remain available. ([#4066](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/4066)) +- `ERC1820Implementer`: The `ERC1820` pseudo-introspection mechanism is no longer supported by OpenZeppelin. Our implementation is now deprecated and will be removed in the next major release. The corresponding standard interfaces remain available. ([#4066](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/4066)) + +## 4.8.3 (2023-04-13) + +- `GovernorCompatibilityBravo`: Fix encoding of proposal data when signatures are missing. +- `TransparentUpgradeableProxy`: Fix transparency in case of selector clash with non-decodable calldata or payable mutability. ([#4154](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/4154)) + +## 4.8.2 (2023-03-02) + +- `ERC721Consecutive`: Fixed a bug when `_mintConsecutive` is used for batches of size 1 that could lead to balance overflow. Refer to the breaking changes section in the changelog for a note on the behavior of `ERC721._beforeTokenTransfer`. + +### Breaking changes + +- `ERC721`: The internal function `_beforeTokenTransfer` no longer updates balances, which it previously did when `batchSize` was greater than 1. This change has no consequence unless a custom ERC721 extension is explicitly invoking `_beforeTokenTransfer`. Balance updates in extensions must now be done explicitly using `__unsafe_increaseBalance`, with a name that indicates that there is an invariant that has to be manually verified. + +## 4.8.1 (2023-01-12) + +- `ERC4626`: Use staticcall instead of call when fetching underlying ERC-20 decimals. ([#3943](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3943)) + +## 4.8.0 (2022-11-08) + +- `TimelockController`: Added a new `admin` constructor parameter that is assigned the admin role instead of the deployer account. ([#3722](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3722)) +- `Initializable`: add internal functions `_getInitializedVersion` and `_isInitializing` ([#3598](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3598)) +- `ERC165Checker`: add `supportsERC165InterfaceUnchecked` for consulting individual interfaces without the full ERC165 protocol. ([#3339](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3339)) +- `Address`: optimize `functionCall` by calling `functionCallWithValue` directly. ([#3468](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3468)) +- `Address`: optimize `functionCall` functions by checking contract size only if there is no returned data. ([#3469](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3469)) +- `Governor`: make the `relay` function payable, and add support for EOA payments. ([#3730](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3730)) +- `GovernorCompatibilityBravo`: remove unused `using` statements. ([#3506](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3506)) +- `ERC20`: optimize `_transfer`, `_mint` and `_burn` by using `unchecked` arithmetic when possible. ([#3513](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3513)) +- `ERC20Votes`, `ERC721Votes`: optimize `getPastVotes` for looking up recent checkpoints. ([#3673](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3673)) +- `ERC20FlashMint`: add an internal `_flashFee` function for overriding. ([#3551](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3551)) +- `ERC4626`: use the same `decimals()` as the underlying asset by default (if available). ([#3639](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3639)) +- `ERC4626`: add internal `_initialConvertToShares` and `_initialConvertToAssets` functions to customize empty vaults behavior. ([#3639](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3639)) +- `ERC721`: optimize transfers by making approval clearing implicit instead of emitting an event. ([#3481](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3481)) +- `ERC721`: optimize burn by making approval clearing implicit instead of emitting an event. ([#3538](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3538)) +- `ERC721`: Fix balance accounting when a custom `_beforeTokenTransfer` hook results in a transfer of the token under consideration. ([#3611](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3611)) +- `ERC721`: use unchecked arithmetic for balance updates. ([#3524](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3524)) +- `ERC721Consecutive`: Implementation of EIP-2309 that allows batch minting of ERC721 tokens during construction. ([#3311](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3311)) +- `ReentrancyGuard`: Reduce code size impact of the modifier by using internal functions. ([#3515](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3515)) +- `SafeCast`: optimize downcasting of signed integers. ([#3565](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3565)) +- `ECDSA`: Remove redundant check on the `v` value. ([#3591](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3591)) +- `VestingWallet`: add `releasable` getters. ([#3580](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3580)) +- `VestingWallet`: remove unused library `Math.sol`. ([#3605](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3605)) +- `VestingWallet`: make constructor payable. ([#3665](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3665)) +- `Create2`: optimize address computation by using assembly instead of `abi.encodePacked`. ([#3600](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3600)) +- `Clones`: optimized the assembly to use only the scratch space during deployments, and optimized `predictDeterministicAddress` to use fewer operations. ([#3640](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3640)) +- `Checkpoints`: Use procedural generation to support multiple key/value lengths. ([#3589](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3589)) +- `Checkpoints`: Add new lookup mechanisms. ([#3589](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3589)) +- `Arrays`: Add `unsafeAccess` functions that allow reading and writing to an element in a storage array bypassing Solidity's "out-of-bounds" check. ([#3589](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3589)) +- `Strings`: optimize `toString`. ([#3573](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3573)) +- `Ownable2Step`: extension of `Ownable` that makes the ownership transfers a two step process. ([#3620](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3620)) +- `Math` and `SignedMath`: optimize function `max` by using `>` instead of `>=`. ([#3679](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3679)) +- `Math`: Add `log2`, `log10` and `log256`. ([#3670](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3670)) +- Arbitrum: Update the vendored arbitrum contracts to match the nitro upgrade. ([#3692](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3692)) + +### Breaking changes + +- `ERC721`: In order to add support for batch minting via `ERC721Consecutive` it was necessary to make a minor breaking change in the internal interface of `ERC721`. Namely, the hooks `_beforeTokenTransfer` and `_afterTokenTransfer` have one additional argument that may need to be added to overrides: + +```diff + function _beforeTokenTransfer( + address from, + address to, + uint256 tokenId, ++ uint256 batchSize + ) internal virtual override +``` + +- `ERC4626`: Conversion from shares to assets (and vice-versa) in an empty vault used to consider the possible mismatch between the underlying asset's and the vault's decimals. This initial conversion rate is now set to 1-to-1 irrespective of decimals, which are meant for usability purposes only. The vault now uses the assets decimals by default, so off-chain the numbers should appear the same. Developers overriding the vault decimals to a value that does not match the underlying asset may want to override the `_initialConvertToShares` and `_initialConvertToAssets` to replicate the previous behavior. + +- `TimelockController`: During deployment, the TimelockController used to grant the `TIMELOCK_ADMIN_ROLE` to the deployer and to the timelock itself. The deployer was then expected to renounce this role once configuration of the timelock is over. Failing to renounce that role allows the deployer to change the timelock permissions (but not to bypass the delay for any time-locked actions). The role is no longer given to the deployer by default. A new parameter `admin` can be set to a non-zero address to grant the admin role during construction (to the deployer or any other address). Just like previously, this admin role should be renounced after configuration. If this param is given `address(0)`, the role is not allocated and doesn't need to be revoked. In any case, the timelock itself continues to have this role. + +### Deprecations + +- `EIP712`: Added the file `EIP712.sol` and deprecated `draft-EIP712.sol` since the EIP is no longer a Draft. Developers are encouraged to update their imports. ([#3621](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3621)) + +```diff +-import "@openzeppelin/contracts/utils/cryptography/draft-EIP712.sol"; ++import "@openzeppelin/contracts/utils/cryptography/EIP712.sol"; +``` + +- `ERC721Votes`: Added the file `ERC721Votes.sol` and deprecated `draft-ERC721Votes.sol` since it no longer depends on a Draft EIP (EIP-712). Developers are encouraged to update their imports. ([#3699](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3699)) + +```diff +-import "@openzeppelin/contracts/token/ERC721/extensions/draft-ERC721Votes.sol"; ++import "@openzeppelin/contracts/token/ERC721/extensions/ERC721Votes.sol"; +``` + +### ERC-721 Compatibility Note + +ERC-721 integrators that interpret contract state from events should make sure that they implement the clearing of approval that is implicit in every transfer according to the EIP. Previous versions of OpenZeppelin Contracts emitted an explicit `Approval` event even though it was not required by the specification, and this is no longer the case. + +With the new `ERC721Consecutive` extension, the internal workings of `ERC721` are slightly changed. Custom extensions to ERC721 should be reviewed to ensure they remain correct. The internal functions that should be considered are `_ownerOf` (new), `_beforeTokenTransfer`, and `_afterTokenTransfer`. + +### ERC-4626 Upgrade Note + +Existing `ERC4626` contracts that are upgraded to 4.8 must initialize a new variable that holds the vault token decimals. The recommended way to do this is to use a [reinitializer]: + +[reinitializer]: https://docs.openzeppelin.com/contracts/4.x/api/proxy#Initializable-reinitializer-uint8- + +```solidity +function migrateToV48() public reinitializer(2) { + __ERC4626_init(IERC20Upgradeable(asset())); +} +``` + +## 4.7.3 (2022-08-10) + +### Breaking changes + +- `ECDSA`: `recover(bytes32,bytes)` and `tryRecover(bytes32,bytes)` no longer accept compact signatures to prevent malleability. Compact signature support remains available using `recover(bytes32,bytes32,bytes32)` and `tryRecover(bytes32,bytes32,bytes32)`. + +## 4.7.2 (2022-07-25) + +- `LibArbitrumL2`, `CrossChainEnabledArbitrumL2`: Fixed detection of cross-chain calls for EOAs. Previously, calls from EOAs would be classified as cross-chain calls. ([#3578](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3578)) +- `GovernorVotesQuorumFraction`: Fixed quorum updates so they do not affect past proposals that failed due to lack of quorum. ([#3561](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3561)) +- `ERC165Checker`: Added protection against large returndata. ([#3587](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3587)) + +## 4.7.1 (2022-07-18) + +- `SignatureChecker`: Fix an issue that causes `isValidSignatureNow` to revert when the target contract returns ill-encoded data. ([#3552](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3552)) +- `ERC165Checker`: Fix an issue that causes `supportsInterface` to revert when the target contract returns ill-encoded data. ([#3552](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3552)) + +## 4.7.0 (2022-06-29) + +- `TimelockController`: Migrate `_call` to `_execute` and allow inheritance and overriding similar to `Governor`. ([#3317](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3317)) +- `CrossChainEnabledPolygonChild`: replace the `require` statement with the custom error `NotCrossChainCall`. ([#3380](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3380)) +- `ERC20FlashMint`: Add customizable flash fee receiver. ([#3327](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3327)) +- `ERC4626`: add an extension of `ERC20` that implements the ERC4626 Tokenized Vault Standard. ([#3171](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3171)) +- `SafeERC20`: add `safePermit` as mitigation against phantom permit functions. ([#3280](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3280)) +- `Math`: add a `mulDiv` function that can round the result either up or down. ([#3171](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3171)) +- `Math`: Add a `sqrt` function to compute square roots of integers, rounding either up or down. ([#3242](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3242)) +- `Strings`: add a new overloaded function `toHexString` that converts an `address` with fixed length of 20 bytes to its not checksummed ASCII `string` hexadecimal representation. ([#3403](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3403)) +- `EnumerableMap`: add new `UintToUintMap` map type. ([#3338](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3338)) +- `EnumerableMap`: add new `Bytes32ToUintMap` map type. ([#3416](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3416)) +- `SafeCast`: add support for many more types, using procedural code generation. ([#3245](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3245)) +- `MerkleProof`: add `multiProofVerify` to prove multiple values are part of a Merkle tree. ([#3276](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3276)) +- `MerkleProof`: add calldata versions of the functions to avoid copying input arrays to memory and save gas. ([#3200](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3200)) +- `ERC721`, `ERC1155`: simplified revert reasons. ([#3254](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3254), ([#3438](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3438))) +- `ERC721`: removed redundant require statement. ([#3434](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3434)) +- `PaymentSplitter`: add `releasable` getters. ([#3350](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3350)) +- `Initializable`: refactored implementation of modifiers for easier understanding. ([#3450](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3450)) +- `Proxies`: remove runtime check of ERC1967 storage slots. ([#3455](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3455)) + +### Breaking changes + +- `Initializable`: functions decorated with the modifier `reinitializer(1)` may no longer invoke each other. + +## 4.6.0 (2022-04-26) + +- `crosschain`: Add a new set of contracts for cross-chain applications. `CrossChainEnabled` is a base contract with instantiations for several chains and bridges, and `AccessControlCrossChain` is an extension of access control that allows cross-chain operation. ([#3183](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3183)) +- `AccessControl`: add a virtual `_checkRole(bytes32)` function that can be overridden to alter the `onlyRole` modifier behavior. ([#3137](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3137)) +- `EnumerableMap`: add new `AddressToUintMap` map type. ([#3150](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3150)) +- `EnumerableMap`: add new `Bytes32ToBytes32Map` map type. ([#3192](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3192)) +- `ERC20FlashMint`: support infinite allowance when paying back a flash loan. ([#3226](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3226)) +- `ERC20Wrapper`: the `decimals()` function now tries to fetch the value from the underlying token instance. If that calls revert, then the default value is used. ([#3259](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3259)) +- `draft-ERC20Permit`: replace `immutable` with `constant` for `_PERMIT_TYPEHASH` since the `keccak256` of string literals is treated specially and the hash is evaluated at compile time. ([#3196](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3196)) +- `ERC1155`: Add a `_afterTokenTransfer` hook for improved extensibility. ([#3166](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3166)) +- `ERC1155URIStorage`: add a new extension that implements a `_setURI` behavior similar to ERC721's `_setTokenURI`. ([#3210](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3210)) +- `DoubleEndedQueue`: a new data structure that supports efficient push and pop to both front and back, useful for FIFO and LIFO queues. ([#3153](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3153)) +- `Governor`: improved security of `onlyGovernance` modifier when using an external executor contract (e.g. a timelock) that can operate without necessarily going through the governance protocol. ([#3147](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3147)) +- `Governor`: Add a way to parameterize votes. This can be used to implement voting systems such as fractionalized voting, ERC721 based voting, or any number of other systems. The `params` argument added to `_countVote` method, and included in the newly added `_getVotes` method, can be used by counting and voting modules respectively for such purposes. ([#3043](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3043)) +- `Governor`: rewording of revert reason for consistency. ([#3275](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3275)) +- `Governor`: fix an inconsistency in data locations that could lead to invalid bytecode being produced. ([#3295](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3295)) +- `Governor`: Implement `IERC721Receiver` and `IERC1155Receiver` to improve token custody by governors. ([#3230](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3230)) +- `TimelockController`: Implement `IERC721Receiver` and `IERC1155Receiver` to improve token custody by timelocks. ([#3230](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3230)) +- `TimelockController`: Add a separate canceller role for the ability to cancel. ([#3165](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3165)) +- `Initializable`: add a reinitializer modifier that enables the initialization of new modules, added to already initialized contracts through upgradeability. ([#3232](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3232)) +- `Initializable`: add an Initialized event that tracks initialized version numbers. ([#3294](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3294)) +- `ERC2981`: make `royaltyInfo` public to allow super call in overrides. ([#3305](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3305)) + +### Upgradeability notice + +- `TimelockController`: **(Action needed)** The upgrade from <4.6 to >=4.6 introduces a new `CANCELLER_ROLE` that requires set up to be assignable. After the upgrade, only addresses with this role will have the ability to cancel. Proposers will no longer be able to cancel. Assigning cancellers can be done by an admin (including the timelock itself) once the role admin is set up. To do this, we recommend upgrading to the `TimelockControllerWith46MigrationUpgradeable` contract and then calling the `migrateTo46` function. + +### Breaking changes + +- `Governor`: Adds internal virtual `_getVotes` method that must be implemented; this is a breaking change for existing concrete extensions to `Governor`. To fix this on an existing voting module extension, rename `getVotes` to `_getVotes` and add a `bytes memory` argument. ([#3043](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3043)) +- `Governor`: Adds `params` parameter to internal virtual `_countVote` method; this is a breaking change for existing concrete extensions to `Governor`. To fix this on an existing counting module extension, add a `bytes memory` argument to `_countVote`. ([#3043](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3043)) +- `Governor`: Does not emit `VoteCast` event when params data is non-empty; instead emits `VoteCastWithParams` event. To fix this on an integration that consumes the `VoteCast` event, also fetch/monitor `VoteCastWithParams` events. ([#3043](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3043)) +- `Votes`: The internal virtual function `_getVotingUnits` was made `view` (which was accidentally missing). Any overrides should now be updated so they are `view` as well. + +## 4.5.0 (2022-02-09) + +- `ERC2981`: add implementation of the royalty standard, and the respective extensions for `ERC721` and `ERC1155`. ([#3012](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3012)) +- `GovernorTimelockControl`: improve the `state()` function to have it reflect cases where a proposal has been canceled directly on the timelock. ([#2977](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2977)) +- Preset contracts are now deprecated in favor of [Contracts Wizard](https://wizard.openzeppelin.com). ([#2986](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2986)) +- `Governor`: add a relay function to help recover assets sent to a governor that is not its own executor (e.g. when using a timelock). ([#2926](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2926)) +- `GovernorPreventLateQuorum`: add new module to ensure a minimum voting duration is available after the quorum is reached. ([#2973](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2973)) +- `ERC721`: improved revert reason when transferring from wrong owner. ([#2975](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2975)) +- `Votes`: Added a base contract for vote tracking with delegation. ([#2944](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2944)) +- `ERC721Votes`: Added an extension of ERC721 enabled with vote tracking and delegation. ([#2944](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2944)) +- `ERC2771Context`: use immutable storage to store the forwarder address, no longer an issue since Solidity >=0.8.8 allows reading immutable variables in the constructor. ([#2917](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2917)) +- `Base64`: add a library to parse bytes into base64 strings using `encode(bytes memory)` function, and provide examples to show how to use to build URL-safe `tokenURIs`. ([#2884](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2884)) +- `ERC20`: reduce allowance before triggering transfer. ([#3056](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3056)) +- `ERC20`: do not update allowance on `transferFrom` when allowance is `type(uint256).max`. ([#3085](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3085)) +- `ERC20`: add a `_spendAllowance` internal function. ([#3170](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3170)) +- `ERC20Burnable`: do not update allowance on `burnFrom` when allowance is `type(uint256).max`. ([#3170](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3170)) +- `ERC777`: do not update allowance on `transferFrom` when allowance is `type(uint256).max`. ([#3085](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3085)) +- `ERC777`: add a `_spendAllowance` internal function. ([#3170](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3170)) +- `SignedMath`: a new signed version of the Math library with `max`, `min`, and `average`. ([#2686](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2686)) +- `SignedMath`: add an `abs(int256)` method that returns the unsigned absolute value of a signed value. ([#2984](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2984)) +- `ERC1967Upgrade`: Refactor the secure upgrade to use `ERC1822` instead of the previous rollback mechanism. This reduces code complexity and attack surface with similar security guarantees. ([#3021](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3021)) +- `UUPSUpgradeable`: Add `ERC1822` compliance to support the updated secure upgrade mechanism. ([#3021](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3021)) +- Some more functions have been made virtual to customize them via overrides. In many cases this will not imply that other functions in the contract will automatically adapt to the overridden definitions. People who wish to override should consult the source code to understand the impact and if they need to override any additional functions to achieve the desired behavior. + +### Breaking changes + +- `ERC1967Upgrade`: The function `_upgradeToAndCallSecure` was renamed to `_upgradeToAndCallUUPS`, along with the change in security mechanism described above. +- `Address`: The Solidity pragma is increased from `^0.8.0` to `^0.8.1`. This is required by the `account.code.length` syntax that replaces inline assembly. This may require users to bump their compiler version from `0.8.0` to `0.8.1` or later. Note that other parts of the code already include stricter requirements. + +## 4.4.2 (2022-01-11) + +### Bugfixes + +- `GovernorCompatibilityBravo`: Fix error in the encoding of calldata for proposals submitted through the compatibility interface with explicit signatures. ([#3100](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3100)) + +## 4.4.1 (2021-12-14) + +- `Initializable`: change the existing `initializer` modifier and add a new `onlyInitializing` modifier to prevent reentrancy risk. ([#3006](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3006)) + +### Breaking change + +It is no longer possible to call an `initializer`-protected function from within another `initializer` function outside the context of a constructor. Projects using OpenZeppelin upgradeable proxies should continue to work as is, since in the common case the initializer is invoked in the constructor directly. If this is not the case for you, the suggested change is to use the new `onlyInitializing` modifier in the following way: + +```diff + contract A { +- function initialize() public initializer { ... } ++ function initialize() internal onlyInitializing { ... } + } + contract B is A { + function initialize() public initializer { + A.initialize(); + } + } +``` + +## 4.4.0 (2021-11-25) + +- `Ownable`: add an internal `_transferOwnership(address)`. ([#2568](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2568)) +- `AccessControl`: add internal `_grantRole(bytes32,address)` and `_revokeRole(bytes32,address)`. ([#2568](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2568)) +- `AccessControl`: mark `_setupRole(bytes32,address)` as deprecated in favor of `_grantRole(bytes32,address)`. ([#2568](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2568)) +- `AccessControlEnumerable`: hook into `_grantRole(bytes32,address)` and `_revokeRole(bytes32,address)`. ([#2946](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2946)) +- `EIP712`: cache `address(this)` to immutable storage to avoid potential issues if a vanilla contract is used in a delegatecall context. ([#2852](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2852)) +- Add internal `_setApprovalForAll` to `ERC721` and `ERC1155`. ([#2834](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2834)) +- `Governor`: shift vote start and end by one block to better match Compound's GovernorBravo and prevent voting at the Governor level if the voting snapshot is not ready. ([#2892](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2892)) +- `GovernorCompatibilityBravo`: consider quorum an inclusive rather than exclusive minimum to match Compound's GovernorBravo. ([#2974](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2974)) +- `GovernorSettings`: a new governor module that manages voting settings updatable through governance actions. ([#2904](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2904)) +- `PaymentSplitter`: now supports ERC20 assets in addition to Ether. ([#2858](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2858)) +- `ECDSA`: add a variant of `toEthSignedMessageHash` for arbitrary length message hashing. ([#2865](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2865)) +- `MerkleProof`: add a `processProof` function that returns the rebuilt root hash given a leaf and a proof. ([#2841](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2841)) +- `VestingWallet`: new contract that handles the vesting of Ether and ERC20 tokens following a customizable vesting schedule. ([#2748](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2748)) +- `Governor`: enable receiving Ether when a Timelock contract is not used. ([#2849](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2849)) +- `GovernorTimelockCompound`: fix ability to use Ether stored in the Timelock contract. ([#2849](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2849)) + +## 4.3.3 (2021-11-08) + +- `ERC1155Supply`: Handle `totalSupply` changes by hooking into `_beforeTokenTransfer` to ensure consistency of balances and supply during `IERC1155Receiver.onERC1155Received` calls. + +## 4.3.2 (2021-09-14) + +- `UUPSUpgradeable`: Add modifiers to prevent `upgradeTo` and `upgradeToAndCall` being executed on any contract that is not the active ERC1967 proxy. This prevents these functions being called on implementation contracts or minimal ERC1167 clones, in particular. + +## 4.3.1 (2021-08-26) + +- `TimelockController`: Add additional isOperationReady check. + +## 4.3.0 (2021-08-17) + +- `ERC2771Context`: use private variable from storage to store the forwarder address. Fixes issues where `_msgSender()` was not callable from constructors. ([#2754](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2754)) +- `EnumerableSet`: add `values()` functions that returns an array containing all values in a single call. ([#2768](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2768)) +- `Governor`: added a modular system of `Governor` contracts based on `GovernorAlpha` and `GovernorBravo`. ([#2672](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2672)) +- Add an `interfaces` folder containing solidity interfaces to final ERCs. ([#2517](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2517)) +- `ECDSA`: add `tryRecover` functions that will not throw if the signature is invalid, and will return an error flag instead. ([#2661](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2661)) +- `SignatureChecker`: Reduce gas usage of the `isValidSignatureNow` function for the "signature by EOA" case. ([#2661](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2661)) + +## 4.2.0 (2021-06-30) + +- `ERC20Votes`: add a new extension of the `ERC20` token with support for voting snapshots and delegation. ([#2632](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2632)) +- `ERC20VotesComp`: Variant of `ERC20Votes` that is compatible with Compound's `Comp` token interface but restricts supply to `uint96`. ([#2706](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2706)) +- `ERC20Wrapper`: add a new extension of the `ERC20` token which wraps an underlying token. Deposit and withdraw guarantee that the total supply is backed by a corresponding amount of underlying token. ([#2633](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2633)) +- Enumerables: Improve gas cost of removal in `EnumerableSet` and `EnumerableMap`. +- Enumerables: Improve gas cost of lookup in `EnumerableSet` and `EnumerableMap`. +- `Counter`: add a reset method. ([#2678](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2678)) +- Tokens: Wrap definitely safe subtractions in `unchecked` blocks. +- `Math`: Add a `ceilDiv` method for performing ceiling division. +- `ERC1155Supply`: add a new `ERC1155` extension that keeps track of the totalSupply of each tokenId. ([#2593](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2593)) +- `BitMaps`: add a new `BitMaps` library that provides a storage efficient datastructure for `uint256` to `bool` mapping with contiguous keys. ([#2710](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2710)) + +### Breaking Changes + +- `ERC20FlashMint` is no longer a Draft ERC. ([#2673](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2673))) + +**How to update:** Change your import paths by removing the `draft-` prefix from `@openzeppelin/contracts/token/ERC20/extensions/draft-ERC20FlashMint.sol`. + +> See [Releases and Stability: Drafts](https://docs.openzeppelin.com/contracts/4.x/releases-stability#drafts). + +## 4.1.0 (2021-04-29) + +- `IERC20Metadata`: add a new extended interface that includes the optional `name()`, `symbol()` and `decimals()` functions. ([#2561](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2561)) +- `ERC777`: make reception acquirement optional in `_mint`. ([#2552](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2552)) +- `ERC20Permit`: add a `_useNonce` to enable further usage of ERC712 signatures. ([#2565](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2565)) +- `ERC20FlashMint`: add an implementation of the ERC3156 extension for flash-minting ERC20 tokens. ([#2543](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2543)) +- `SignatureChecker`: add a signature verification library that supports both EOA and ERC1271 compliant contracts as signers. ([#2532](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2532)) +- `Multicall`: add abstract contract with `multicall(bytes[] calldata data)` function to bundle multiple calls together ([#2608](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2608)) +- `ECDSA`: add support for ERC2098 short-signatures. ([#2582](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2582)) +- `AccessControl`: add an `onlyRole` modifier to restrict specific function to callers bearing a specific role. ([#2609](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2609)) +- `StorageSlot`: add a library for reading and writing primitive types to specific storage slots. ([#2542](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2542)) +- UUPS Proxies: add `UUPSUpgradeable` to implement the UUPS proxy pattern together with `EIP1967Proxy`. ([#2542](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2542)) + +### Breaking changes + +This release includes two small breaking changes in `TimelockController`. + +1. The `onlyRole` modifier in this contract was designed to let anyone through if the role was granted to `address(0)`, + allowing the possibility to to make a role "open", which can be used for `EXECUTOR_ROLE`. This modifier is now + replaced by `AccessControl.onlyRole`, which does not have this ability. The previous behavior was moved to the + modifier `TimelockController.onlyRoleOrOpenRole`. +2. It was possible to make `PROPOSER_ROLE` an open role (as described in the previous item) if it was granted to + `address(0)`. This would affect the `schedule`, `scheduleBatch`, and `cancel` operations in `TimelockController`. + This ability was removed as it does not make sense to open up the `PROPOSER_ROLE` in the same way that it does for + `EXECUTOR_ROLE`. + +## 4.0.0 (2021-03-23) + +- Now targeting the 0.8.x line of Solidity compilers. For 0.6.x (resp 0.7.x) support, use version 3.4.0 (resp 3.4.0-solc-0.7) of OpenZeppelin. +- `Context`: making `_msgData` return `bytes calldata` instead of `bytes memory` ([#2492](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2492)) +- `ERC20`: removed the `_setDecimals` function and the storage slot associated to decimals. ([#2502](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2502)) +- `Strings`: addition of a `toHexString` function. ([#2504](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2504)) +- `EnumerableMap`: change implementation to optimize for `key → value` lookups instead of enumeration. ([#2518](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2518)) +- `GSN`: deprecate GSNv1 support in favor of upcoming support for GSNv2. ([#2521](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2521)) +- `ERC165`: remove uses of storage in the base ERC165 implementation. ERC165 based contracts now use storage-less virtual functions. Old behavior remains available in the `ERC165Storage` extension. ([#2505](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2505)) +- `Initializable`: make initializer check stricter during construction. ([#2531](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2531)) +- `ERC721`: remove enumerability of tokens from the base implementation. This feature is now provided separately through the `ERC721Enumerable` extension. ([#2511](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2511)) +- `AccessControl`: removed enumerability by default for a more lightweight contract. It is now opt-in through `AccessControlEnumerable`. ([#2512](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2512)) +- Meta Transactions: add `ERC2771Context` and a `MinimalForwarder` for meta-transactions. ([#2508](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2508)) +- Overall reorganization of the contract folder to improve clarity and discoverability. ([#2503](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2503)) +- `ERC20Capped`: optimize gas usage by enforcing the check directly in `_mint`. ([#2524](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2524)) +- Rename `UpgradeableProxy` to `ERC1967Proxy`. ([#2547](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2547)) +- `ERC777`: optimize the gas costs of the constructor. ([#2551](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2551)) +- `ERC721URIStorage`: add a new extension that implements the `_setTokenURI` behavior as it was available in 3.4.0. ([#2555](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2555)) +- `AccessControl`: added ERC165 interface detection. ([#2562](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2562)) +- `ERC1155`: make `uri` public so overloading function can call it using super. ([#2576](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2576)) + +### Bug fixes for beta releases + +- `AccessControlEnumerable`: Fixed `renounceRole` not updating enumerable set of addresses for a role. ([#2572](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2572)) + +### How to upgrade from 3.x + +Since this version has moved a few contracts to different directories, users upgrading from a previous version will need to adjust their import statements. To make this easier, the package includes a script that will migrate import statements automatically. After upgrading to the latest version of the package, run: + +``` +npx openzeppelin-contracts-migrate-imports +``` + +Make sure you're using git or another version control system to be able to recover from any potential error in our script. + +### How to upgrade from 4.0-beta.x + +Some further changes have been done between the different beta iterations. Transitions made during this period are configured in the `migrate-imports` script. Consequently, you can upgrade from any previous 4.0-beta.x version using the same script as described in the _How to upgrade from 3.x_ section. + +## 3.4.2 (2021-07-24) + +- `TimelockController`: Add additional isOperationReady check. + +## 3.4.1 (2021-03-03) + +- `ERC721`: made `_approve` an internal function (was private). + +## 3.4.0 (2021-02-02) + +- `BeaconProxy`: added new kind of proxy that allows simultaneous atomic upgrades. ([#2411](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2411)) +- `EIP712`: added helpers to verify EIP712 typed data signatures on chain. ([#2418](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2418)) +- `ERC20Permit`: added an implementation of the ERC20 permit extension for gasless token approvals. ([#2237](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2237)) +- Presets: added token presets with preminted fixed supply `ERC20PresetFixedSupply` and `ERC777PresetFixedSupply`. ([#2399](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2399)) +- `Address`: added `functionDelegateCall`, similar to the existing `functionCall`. ([#2333](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2333)) +- `Clones`: added a library for deploying EIP 1167 minimal proxies. ([#2449](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2449)) +- `Context`: moved from `contracts/GSN` to `contracts/utils`. ([#2453](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2453)) +- `PaymentSplitter`: replace usage of `.transfer()` with `Address.sendValue` for improved compatibility with smart wallets. ([#2455](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2455)) +- `UpgradeableProxy`: bubble revert reasons from initialization calls. ([#2454](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2454)) +- `SafeMath`: fix a memory allocation issue by adding new `SafeMath.tryOp(uint,uint)→(bool,uint)` functions. `SafeMath.op(uint,uint,string)→uint` are now deprecated. ([#2462](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2462)) +- `EnumerableMap`: fix a memory allocation issue by adding new `EnumerableMap.tryGet(uint)→(bool,address)` functions. `EnumerableMap.get(uint)→string` is now deprecated. ([#2462](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2462)) +- `ERC165Checker`: added batch `getSupportedInterfaces`. ([#2469](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2469)) +- `RefundEscrow`: `beneficiaryWithdraw` will forward all available gas to the beneficiary. ([#2480](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2480)) +- Many view and pure functions have been made virtual to customize them via overrides. In many cases this will not imply that other functions in the contract will automatically adapt to the overridden definitions. People who wish to override should consult the source code to understand the impact and if they need to override any additional functions to achieve the desired behavior. + +### Security Fixes + +- `ERC777`: fix potential reentrancy issues for custom extensions to `ERC777`. ([#2483](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2483)) + +If you're using our implementation of ERC777 from version 3.3.0 or earlier, and you define a custom `_beforeTokenTransfer` function that writes to a storage variable, you may be vulnerable to a reentrancy attack. If you're affected and would like assistance please write to security@openzeppelin.com. [Read more in the pull request.](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2483) + +## 3.3.0 (2020-11-26) + +- Now supports both Solidity 0.6 and 0.7. Compiling with solc 0.7 will result in warnings. Install the `solc-0.7` tag to compile without warnings. +- `Address`: added `functionStaticCall`, similar to the existing `functionCall`. ([#2333](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2333)) +- `TimelockController`: added a contract to augment access control schemes with a delay. ([#2354](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2354)) +- `EnumerableSet`: added `Bytes32Set`, for sets of `bytes32`. ([#2395](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2395)) + +## 3.2.2-solc-0.7 (2020-10-28) + +- Resolve warnings introduced by Solidity 0.7.4. ([#2396](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2396)) + +## 3.2.1-solc-0.7 (2020-09-15) + +- `ERC777`: Remove a warning about function state visibility in Solidity 0.7. ([#2327](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2327)) + +## 3.2.0 (2020-09-10) + +### New features + +- Proxies: added the proxy contracts from OpenZeppelin SDK. ([#2335](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2335)) + +#### Proxy changes with respect to OpenZeppelin SDK + +Aside from upgrading them from Solidity 0.5 to 0.6, we've changed a few minor things from the proxy contracts as they were found in OpenZeppelin SDK. + +- `UpgradeabilityProxy` was renamed to `UpgradeableProxy`. +- `AdminUpgradeabilityProxy` was renamed to `TransparentUpgradeableProxy`. +- `Proxy._willFallback` was renamed to `Proxy._beforeFallback`. +- `UpgradeabilityProxy._setImplementation` and `AdminUpgradeabilityProxy._setAdmin` were made private. + +### Improvements + +- `Address.isContract`: switched from `extcodehash` to `extcodesize` for less gas usage. ([#2311](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2311)) + +### Breaking changes + +- `ERC20Snapshot`: switched to using `_beforeTokenTransfer` hook instead of overriding ERC20 operations. ([#2312](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2312)) + +This small change in the way we implemented `ERC20Snapshot` may affect users who are combining this contract with +other ERC20 flavors, since it no longer overrides `_transfer`, `_mint`, and `_burn`. This can result in having to remove Solidity `override(...)` specifiers in derived contracts for these functions, and to instead have to add it for `_beforeTokenTransfer`. See [Using Hooks](https://docs.openzeppelin.com/contracts/3.x/extending-contracts#using-hooks) in the documentation. + +## 3.1.0 (2020-06-23) + +### New features + +- `SafeCast`: added functions to downcast signed integers (e.g. `toInt32`), improving usability of `SignedSafeMath`. ([#2243](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2243)) +- `functionCall`: new helpers that replicate Solidity's function call semantics, reducing the need to rely on `call`. ([#2264](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2264)) +- `ERC1155`: added support for a base implementation, non-standard extensions and a preset contract. ([#2014](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2014), [#2230](https://github.com/OpenZeppelin/openzeppelin-contracts/issues/2230)) + +### Improvements + +- `ReentrancyGuard`: reduced overhead of using the `nonReentrant` modifier. ([#2171](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2171)) +- `AccessControl`: added a `RoleAdminChanged` event to `_setAdminRole`. ([#2214](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2214)) +- Made all `public` functions in the token preset contracts `virtual`. ([#2257](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2257)) + +### Deprecations + +- `SafeERC20`: deprecated `safeApprove`. ([#2268](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2268)) + +## 3.0.2 (2020-06-08) + +### Improvements + +- Added SPX license identifier to all contracts. ([#2235](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2235)) + +## 3.0.1 (2020-04-27) + +### Bugfixes + +- `ERC777`: fixed the `_approve` internal function not validating some of their arguments for non-zero addresses. ([#2213](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2213)) + +## 3.0.0 (2020-04-20) + +### New features + +- `AccessControl`: new contract for managing permissions in a system, replacement for `Ownable` and `Roles`. ([#2112](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2112)) +- `SafeCast`: new functions to convert to and from signed and unsigned values: `toUint256` and `toInt256`. ([#2123](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2123)) +- `EnumerableMap`: a new data structure for key-value pairs (like `mapping`) that can be iterated over. ([#2160](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2160)) + +### Breaking changes + +- `ERC721`: `burn(owner, tokenId)` was removed, use `burn(tokenId)` instead. ([#2125](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2125)) +- `ERC721`: `_checkOnERC721Received` was removed. ([#2125](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2125)) +- `ERC721`: `_transferFrom` and `_safeTransferFrom` were renamed to `_transfer` and `_safeTransfer`. ([#2162](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2162)) +- `Ownable`: removed `_transferOwnership`. ([#2162](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2162)) +- `PullPayment`, `Escrow`: `withdrawWithGas` was removed. The old `withdraw` function now forwards all gas. ([#2125](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2125)) +- `Roles` was removed, use `AccessControl` as a replacement. ([#2112](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2112)) +- `ECDSA`: when receiving an invalid signature, `recover` now reverts instead of returning the zero address. ([#2114](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2114)) +- `Create2`: added an `amount` argument to `deploy` for contracts with `payable` constructors. ([#2117](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2117)) +- `Pausable`: moved to the `utils` directory. ([#2122](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2122)) +- `Strings`: moved to the `utils` directory. ([#2122](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2122)) +- `Counters`: moved to the `utils` directory. ([#2122](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2122)) +- `SignedSafeMath`: moved to the `math` directory. ([#2122](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2122)) +- `ERC20Snapshot`: moved to the `token/ERC20` directory. `snapshot` was changed into an `internal` function. ([#2122](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2122)) +- `Ownable`: moved to the `access` directory. ([#2120](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2120)) +- `Ownable`: removed `isOwner`. ([#2120](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2120)) +- `Secondary`: removed from the library, use `Ownable` instead. ([#2120](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2120)) +- `Escrow`, `ConditionalEscrow`, `RefundEscrow`: these now use `Ownable` instead of `Secondary`, their external API changed accordingly. ([#2120](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2120)) +- `ERC20`: removed `_burnFrom`. ([#2119](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2119)) +- `Address`: removed `toPayable`, use `payable(address)` instead. ([#2133](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2133)) +- `ERC777`: `_send`, `_mint` and `_burn` now use the caller as the operator. ([#2134](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2134)) +- `ERC777`: removed `_callsTokensToSend` and `_callTokensReceived`. ([#2134](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2134)) +- `EnumerableSet`: renamed `get` to `at`. ([#2151](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2151)) +- `ERC165Checker`: functions no longer have a leading underscore. ([#2150](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2150)) +- `ERC721Metadata`, `ERC721Enumerable`: these contracts were removed, and their functionality merged into `ERC721`. ([#2160](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2160)) +- `ERC721`: added a constructor for `name` and `symbol`. ([#2160](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2160)) +- `ERC20Detailed`: this contract was removed and its functionality merged into `ERC20`. ([#2161](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2161)) +- `ERC20`: added a constructor for `name` and `symbol`. `decimals` now defaults to 18. ([#2161](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2161)) +- `Strings`: renamed `fromUint256` to `toString` ([#2188](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2188)) + +## 2.5.1 (2020-04-24) + +### Bugfixes + +- `ERC777`: fixed the `_send` and `_approve` internal functions not validating some of their arguments for non-zero addresses. ([#2212](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2212)) + +## 2.5.0 (2020-02-04) + +### New features + +- `SafeCast.toUintXX`: new library for integer downcasting, which allows for safe operation on smaller types (e.g. `uint32`) when combined with `SafeMath`. ([#1926](https://github.com/OpenZeppelin/openzeppelin-solidity/pull/1926)) +- `ERC721Metadata`: added `baseURI`, which can be used for dramatic gas savings when all token URIs share a prefix (e.g. `http://api.myapp.com/tokens/`). ([#1970](https://github.com/OpenZeppelin/openzeppelin-solidity/pull/1970)) +- `EnumerableSet`: new library for storing enumerable sets of values. Only `AddressSet` is supported in this release. ([#2061](https://github.com/OpenZeppelin/openzeppelin-solidity/pull/2061)) +- `Create2`: simple library to make usage of the `CREATE2` opcode easier. ([#1744](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/1744)) + +### Improvements + +- `ERC777`: `_burn` is now internal, providing more flexibility and making it easier to create tokens that deflate. ([#1908](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/1908)) +- `ReentrancyGuard`: greatly improved gas efficiency by using the net gas metering mechanism introduced in the Istanbul hardfork. ([#1992](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/1992), [#1996](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/1996)) +- `ERC777`: improve extensibility by making `_send` and related functions `internal`. ([#2027](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2027)) +- `ERC721`: improved revert reason when transferring tokens to a non-recipient contract. ([#2018](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/2018)) + +### Breaking changes + +- `ERC165Checker` now requires a minimum Solidity compiler version of 0.5.10. ([#1829](https://github.com/OpenZeppelin/openzeppelin-solidity/pull/1829)) + +## 2.4.0 (2019-10-29) + +### New features + +- `Address.toPayable`: added a helper to convert between address types without having to resort to low-level casting. ([#1773](https://github.com/OpenZeppelin/openzeppelin-solidity/pull/1773)) +- Facilities to make metatransaction-enabled contracts through the Gas Station Network. ([#1844](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/1844)) +- `Address.sendValue`: added a replacement to Solidity's `transfer`, removing the fixed gas stipend. ([#1962](https://github.com/OpenZeppelin/openzeppelin-solidity/pull/1962)) +- Added replacement for functions that don't forward all gas (which have been deprecated): ([#1976](https://github.com/OpenZeppelin/openzeppelin-solidity/pull/1976)) + - `PullPayment.withdrawPaymentsWithGas(address payable payee)` + - `Escrow.withdrawWithGas(address payable payee)` +- `SafeMath`: added support for custom error messages to `sub`, `div` and `mod` functions. ([#1828](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/1828)) + +### Improvements + +- `Address.isContract`: switched from `extcodesize` to `extcodehash` for less gas usage. ([#1802](https://github.com/OpenZeppelin/openzeppelin-solidity/pull/1802)) +- `ERC20` and `ERC777` updated to throw custom errors on subtraction overflows. ([#1828](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/1828)) + +### Deprecations + +- Deprecated functions that don't forward all gas: ([#1976](https://github.com/OpenZeppelin/openzeppelin-solidity/pull/1976)) + - `PullPayment.withdrawPayments(address payable payee)` + - `Escrow.withdraw(address payable payee)` + +### Breaking changes + +- `Address` now requires a minimum Solidity compiler version of 0.5.5. ([#1802](https://github.com/OpenZeppelin/openzeppelin-solidity/pull/1802)) +- `SignatureBouncer` has been removed from drafts, both to avoid confusions with the GSN and `GSNRecipientSignature` (previously called `GSNBouncerSignature`) and because the API was not very clear. ([#1879](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/1879)) + +### How to upgrade from 2.4.0-beta + +The final 2.4.0 release includes a refactor of the GSN contracts that will be a breaking change for 2.4.0-beta users. + +- The default empty implementations of `_preRelayedCall` and `_postRelayedCall` were removed and must now be explicitly implemented always in custom recipients. If your custom recipient didn't include an implementation, you can provide an empty one. +- `GSNRecipient`, `GSNBouncerBase`, and `GSNContext` were all merged into `GSNRecipient`. +- `GSNBouncerSignature` and `GSNBouncerERC20Fee` were renamed to `GSNRecipientSignature` and `GSNRecipientERC20Fee`. +- It is no longer necessary to inherit from `GSNRecipient` when using `GSNRecipientSignature` and `GSNRecipientERC20Fee`. + +For example, a contract using `GSNBouncerSignature` would have to be changed in the following way. + +```diff +-contract MyDapp is GSNRecipient, GSNBouncerSignature { ++contract MyDapp is GSNRecipientSignature { +``` + +Refer to the table below to adjust your inheritance list. + +| 2.4.0-beta | 2.4.0 | +| ----------------------------------- | ----------------------- | +| `GSNRecipient, GSNBouncerSignature` | `GSNRecipientSignature` | +| `GSNRecipient, GSNBouncerERC20Fee` | `GSNRecipientERC20Fee` | +| `GSNBouncerBase` | `GSNRecipient` | + +## 2.3.0 (2019-05-27) + +### New features + +- `ERC1820`: added support for interacting with the [ERC1820](https://eips.ethereum.org/EIPS/eip-1820) registry contract (`IERC1820Registry`), as well as base contracts that can be registered as implementers there. ([#1677](https://github.com/OpenZeppelin/openzeppelin-solidity/pull/1677)) +- `ERC777`: support for the [ERC777 token](https://eips.ethereum.org/EIPS/eip-777), which has multiple improvements over `ERC20` (but is backwards compatible with it) such as built-in burning, a more straightforward permission system, and optional sender and receiver hooks on transfer (mandatory for contracts!). ([#1684](https://github.com/OpenZeppelin/openzeppelin-solidity/pull/1684)) +- All contracts now have revert reason strings, which give insight into error conditions, and help debug failing transactions. ([#1704](https://github.com/OpenZeppelin/openzeppelin-solidity/pull/1704)) + +### Improvements + +- Reverted the Solidity version bump done in v2.2.0, setting the minimum compiler version to v0.5.0, to prevent unexpected build breakage. Users are encouraged however to stay on top of new compiler releases, which usually include bugfixes. ([#1729](https://github.com/OpenZeppelin/openzeppelin-solidity/pull/1729)) + +### Bugfixes + +- `PostDeliveryCrowdsale`: some validations where skipped when paired with other crowdsale flavors, such as `AllowanceCrowdsale`, or `MintableCrowdsale` and `ERC20Capped`, which could cause buyers to not be able to claim their purchased tokens. ([#1721](https://github.com/OpenZeppelin/openzeppelin-solidity/pull/1721)) +- `ERC20._transfer`: the `from` argument was allowed to be the zero address, so it was possible to internally trigger a transfer of 0 tokens from the zero address. This address is not a valid destinatary of transfers, nor can it give or receive allowance, so this behavior was inconsistent. It now reverts. ([#1752](https://github.com/OpenZeppelin/openzeppelin-solidity/pull/1752)) + +## 2.2.0 (2019-03-14) + +### New features + +- `ERC20Snapshot`: create snapshots on demand of the token balances and total supply, to later retrieve and e.g. calculate dividends at a past time. ([#1617](https://github.com/OpenZeppelin/openzeppelin-solidity/pull/1617)) +- `SafeERC20`: `ERC20` contracts with no return value (i.e. that revert on failure) are now supported. ([#1655](https://github.com/OpenZeppelin/openzeppelin-solidity/pull/1655)) +- `ERC20`: added internal `_approve(address owner, address spender, uint256 value)`, allowing derived contracts to set the allowance of arbitrary accounts. ([#1609](https://github.com/OpenZeppelin/openzeppelin-solidity/pull/1609)) +- `ERC20Metadata`: added internal `_setTokenURI(string memory tokenURI)`. ([#1618](https://github.com/OpenZeppelin/openzeppelin-solidity/pull/1618)) +- `TimedCrowdsale`: added internal `_extendTime(uint256 newClosingTime)` as well as `TimedCrowdsaleExtended(uint256 prevClosingTime, uint256 newClosingTime)` event allowing to extend the crowdsale, as long as it hasn't already closed. + +### Improvements + +- Upgraded the minimum compiler version to v0.5.2: this removes many Solidity warnings that were false positives. ([#1606](https://github.com/OpenZeppelin/openzeppelin-solidity/pull/1606)) +- `ECDSA`: `recover` no longer accepts malleable signatures (those using upper-range values for `s`, or 0/1 for `v`). ([#1622](https://github.com/OpenZeppelin/openzeppelin-solidity/pull/1622)) +- `ERC721`'s transfers are now more gas efficient due to removal of unnecessary `SafeMath` calls. ([#1610](https://github.com/OpenZeppelin/openzeppelin-solidity/pull/1610)) +- Fixed variable shadowing issues. ([#1606](https://github.com/OpenZeppelin/openzeppelin-solidity/pull/1606)) + +### Bugfixes + +- (minor) `SafeERC20`: `safeApprove` wasn't properly checking for a zero allowance when attempting to set a non-zero allowance. ([#1647](https://github.com/OpenZeppelin/openzeppelin-solidity/pull/1647)) + +### Breaking changes in drafts + +- `TokenMetadata` has been renamed to `ERC20Metadata`. ([#1618](https://github.com/OpenZeppelin/openzeppelin-solidity/pull/1618)) +- The library `Counter` has been renamed to `Counters` and its API has been improved. See an example in `ERC721`, lines [17](https://github.com/OpenZeppelin/openzeppelin-solidity/blob/3cb4a00fce1da76196ac0ac3a0ae9702b99642b5/contracts/token/ERC721/ERC721.sol#L17) and [204](https://github.com/OpenZeppelin/openzeppelin-solidity/blob/3cb4a00fce1da76196ac0ac3a0ae9702b99642b5/contracts/token/ERC721/ERC721.sol#L204). ([#1610](https://github.com/OpenZeppelin/openzeppelin-solidity/pull/1610)) + +## 2.1.3 (2019-02-26) + +- Backported `SafeERC20.safeApprove` bugfix. ([#1647](https://github.com/OpenZeppelin/openzeppelin-solidity/pull/1647)) + +## 2.1.2 (2019-01-17) + +- Removed most of the test suite from the npm package, except `PublicRole.behavior.js`, which may be useful to users testing their own `Roles`. + +## 2.1.1 (2019-01-04) + +- Version bump to avoid conflict in the npm registry. + +## 2.1.0 (2019-01-04) + +### New features + +- Now targeting the 0.5.x line of Solidity compilers. For 0.4.24 support, use version 2.0 of OpenZeppelin. +- `WhitelistCrowdsale`: a crowdsale where only whitelisted accounts (`WhitelistedRole`) can purchase tokens. Adding or removing accounts from the whitelist is done by whitelist admins (`WhitelistAdminRole`). Similar to the pre-2.0 `WhitelistedCrowdsale`. ([#1525](https://github.com/OpenZeppelin/openzeppelin-solidity/pull/1525), [#1589](https://github.com/OpenZeppelin/openzeppelin-solidity/pull/1589)) +- `RefundablePostDeliveryCrowdsale`: replacement for `RefundableCrowdsale` (deprecated, see below) where tokens are only granted once the crowdsale ends (if it meets its goal). ([#1543](https://github.com/OpenZeppelin/openzeppelin-solidity/pull/1543)) +- `PausableCrowdsale`: allows for pausers (`PauserRole`) to pause token purchases. Other crowdsale operations (e.g. withdrawals and refunds, if applicable) are not affected. ([#832](https://github.com/OpenZeppelin/openzeppelin-solidity/pull/832)) +- `ERC20`: `transferFrom` and `_burnFrom ` now emit `Approval` events, to represent the token's state comprehensively through events. ([#1524](https://github.com/OpenZeppelin/openzeppelin-solidity/pull/1524)) +- `ERC721`: added `_burn(uint256 tokenId)`, replacing the similar deprecated function (see below). ([#1550](https://github.com/OpenZeppelin/openzeppelin-solidity/pull/1550)) +- `ERC721`: added `_tokensOfOwner(address owner)`, allowing to internally retrieve the array of an account's owned tokens. ([#1522](https://github.com/OpenZeppelin/openzeppelin-solidity/pull/1522)) +- Crowdsales: all constructors are now `public`, meaning it is not necessary to extend these contracts in order to deploy them. The exception is `FinalizableCrowdsale`, since it is meaningless unless extended. ([#1564](https://github.com/OpenZeppelin/openzeppelin-solidity/pull/1564)) +- `SignedSafeMath`: added overflow-safe operations for signed integers (`int256`). ([#1559](https://github.com/OpenZeppelin/openzeppelin-solidity/pull/1559), [#1588](https://github.com/OpenZeppelin/openzeppelin-solidity/pull/1588)) + +### Improvements + +- The compiler version required by `Array` was behind the rest of the library so it was updated to `v0.4.24`. ([#1553](https://github.com/OpenZeppelin/openzeppelin-solidity/pull/1553)) +- Now conforming to a 4-space indentation code style. ([1508](https://github.com/OpenZeppelin/openzeppelin-solidity/pull/1508)) +- `ERC20`: more gas efficient due to removed redundant `require`s. ([#1409](https://github.com/OpenZeppelin/openzeppelin-solidity/pull/1409)) +- `ERC721`: fixed a bug that prevented internal data structures from being properly cleaned, missing potential gas refunds. ([#1539](https://github.com/OpenZeppelin/openzeppelin-solidity/pull/1539) and [#1549](https://github.com/OpenZeppelin/openzeppelin-solidity/pull/1549)) +- `ERC721`: general gas savings on `transferFrom`, `_mint` and `_burn`, due to redundant `require`s and `SSTORE`s. ([#1549](https://github.com/OpenZeppelin/openzeppelin-solidity/pull/1549)) + +### Bugfixes + +### Breaking changes + +### Deprecations + +- `ERC721._burn(address owner, uint256 tokenId)`: due to the `owner` parameter being unnecessary. ([#1550](https://github.com/OpenZeppelin/openzeppelin-solidity/pull/1550)) +- `RefundableCrowdsale`: due to trading abuse potential on crowdsales that miss their goal. ([#1543](https://github.com/OpenZeppelin/openzeppelin-solidity/pull/1543)) diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 000000000..cd7770dac --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,73 @@ +# Contributor Covenant Code of Conduct + +## Our Pledge + +In the interest of fostering an open and welcoming environment, we as +contributors and maintainers pledge to making participation in our project and +our community a harassment-free experience for everyone, regardless of age, body +size, disability, ethnicity, sex characteristics, gender identity and expression, +level of experience, education, socio-economic status, nationality, personal +appearance, race, religion, or sexual identity and orientation. + +## Our Standards + +Examples of behavior that contributes to creating a positive environment +include: + +* Using welcoming and inclusive language +* Being respectful of differing viewpoints and experiences +* Gracefully accepting constructive criticism +* Focusing on what is best for the community +* Showing empathy towards other community members + +Examples of unacceptable behavior by participants include: + +* The use of sexualized language or imagery and unwelcome sexual attention or + advances +* Trolling, insulting/derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or electronic + address, without explicit permission +* Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Our Responsibilities + +Project maintainers are responsible for clarifying the standards of acceptable +behavior and are expected to take appropriate and fair corrective action in +response to any instances of unacceptable behavior. + +Project maintainers have the right and responsibility to remove, edit, or +reject comments, commits, code, wiki edits, issues, and other contributions +that are not aligned to this Code of Conduct, or to ban temporarily or +permanently any contributor for other behaviors that they deem inappropriate, +threatening, offensive, or harmful. + +## Scope + +This Code of Conduct applies both within project spaces and in public spaces +when an individual is representing the project or its community. Examples of +representing a project or community include using an official project e-mail +address, posting via an official social media account, or acting as an appointed +representative at an online or offline event. Representation of a project may be +further defined and clarified by project maintainers. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported by contacting the project team at contact@openzeppelin.com. All +complaints will be reviewed and investigated and will result in a response that +is deemed necessary and appropriate to the circumstances. The project team is +obligated to maintain confidentiality with regard to the reporter of an incident. +Further details of specific enforcement policies may be posted separately. + +Project maintainers who do not follow or enforce the Code of Conduct in good +faith may face temporary or permanent repercussions as determined by other +members of the project's leadership. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, +available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html + +[homepage]: https://www.contributor-covenant.org diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 000000000..1a44cc27d --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,36 @@ +# Contributing Guidelines + +There are many ways to contribute to OpenZeppelin Contracts. + +## Troubleshooting + +You can help other users in the community to solve their smart contract issues in the [OpenZeppelin Forum]. + +[OpenZeppelin Forum]: https://forum.openzeppelin.com/ + +## Opening an issue + +You can [open an issue] to suggest a feature or report a minor bug. For serious bugs please do not open an issue, instead refer to our [security policy] for appropriate steps. + +If you believe your issue may be due to user error and not a problem in the library, consider instead posting a question on the [OpenZeppelin Forum]. + +Before opening an issue, be sure to search through the existing open and closed issues, and consider posting a comment in one of those instead. + +When requesting a new feature, include as many details as you can, especially around the use cases that motivate it. Features are prioritized according to the impact they may have on the ecosystem, so we appreciate information showing that the impact could be high. + +[security policy]: https://github.com/OpenZeppelin/openzeppelin-contracts/security +[open an issue]: https://github.com/OpenZeppelin/openzeppelin-contracts/issues/new/choose + +## Submitting a pull request + +If you would like to contribute code or documentation you may do so by forking the repository and submitting a pull request. + +Any non-trivial code contribution must be first discussed with the maintainers in an issue (see [Opening an issue](#opening-an-issue)). Only very minor changes are accepted without prior discussion. + +Make sure to read and follow the [engineering guidelines](./GUIDELINES.md). Run linter and tests to make sure your pull request is good before submitting it. + +Changelog entries should be added to each pull request by using [Changesets](https://github.com/changesets/changesets/). + +When opening the pull request you will be presented with a template and a series of instructions. Read through it carefully and follow all the steps. Expect a review and feedback from the maintainers afterwards. + +If you're looking for a good place to start, look for issues labelled ["good first issue"](https://github.com/OpenZeppelin/openzeppelin-contracts/labels/good%20first%20issue)! diff --git a/GUIDELINES.md b/GUIDELINES.md new file mode 100644 index 000000000..4b7f5e76e --- /dev/null +++ b/GUIDELINES.md @@ -0,0 +1,148 @@ +# Engineering Guidelines + +## Testing + +Code must be thoroughly tested with quality unit tests. + +We defer to the [Moloch Testing Guide](https://github.com/MolochVentures/moloch/tree/master/test#readme) for specific recommendations, though not all of it is relevant here. Note the introduction: + +> Tests should be written, not only to verify correctness of the target code, but to be comprehensively reviewed by other programmers. Therefore, for mission critical Solidity code, the quality of the tests are just as important (if not more so) than the code itself, and should be written with the highest standards of clarity and elegance. + +Every addition or change to the code must come with relevant and comprehensive tests. + +Refactors should avoid simultaneous changes to tests. + +Flaky tests are not acceptable. + +The test suite should run automatically for every change in the repository, and in pull requests tests must pass before merging. + +The test suite coverage must be kept as close to 100% as possible, enforced in pull requests. + +In some cases unit tests may be insufficient and complementary techniques should be used: + +1. Property-based tests (aka. fuzzing) for math-heavy code. +2. Formal verification for state machines. + +## Code style + +Solidity code should be written in a consistent format enforced by a linter, following the official [Solidity Style Guide](https://docs.soliditylang.org/en/latest/style-guide.html). See below for further [Solidity Conventions](#solidity-conventions). + +The code should be simple and straightforward, prioritizing readability and understandability. Consistency and predictability should be maintained across the codebase. In particular, this applies to naming, which should be systematic, clear, and concise. + +Sometimes these guidelines may be broken if doing so brings significant efficiency gains, but explanatory comments should be added. + +Modularity should be pursued, but not at the cost of the above priorities. + +## Documentation + +For contributors, project guidelines and processes must be documented publicly. + +For users, features must be abundantly documented. Documentation should include answers to common questions, solutions to common problems, and recommendations for critical decisions that the user may face. + +All changes to the core codebase (excluding tests, auxiliary scripts, etc.) must be documented in a changelog, except for purely cosmetic or documentation changes. + +## Peer review + +All changes must be submitted through pull requests and go through peer code review. + +The review must be approached by the reviewer in a similar way as if it was an audit of the code in question (but importantly it is not a substitute for and should not be considered an audit). + +Reviewers should enforce code and project guidelines. + +External contributions must be reviewed separately by multiple maintainers. + +## Automation + +Automation should be used as much as possible to reduce the possibility of human error and forgetfulness. + +Automations that make use of sensitive credentials must use secure secret management, and must be strengthened against attacks such as [those on GitHub Actions worklows](https://github.com/nikitastupin/pwnhub). + +Some other examples of automation are: + +- Looking for common security vulnerabilities or errors in our code (eg. reentrancy analysis). +- Keeping dependencies up to date and monitoring for vulnerable dependencies. + +## Pull requests + +Pull requests are squash-merged to keep the `master` branch history clean. The title of the pull request becomes the commit message, so it should be written in a consistent format: + +1) Begin with a capital letter. +2) Do not end with a period. +3) Write in the imperative: "Add feature X" and not "Adds feature X" or "Added feature X". + +This repository does not follow conventional commits, so do not prefix the title with "fix:" or "feat:". + +Work in progress pull requests should be submitted as Drafts and should not be prefixed with "WIP:". + +Branch names don't matter, and commit messages within a pull request mostly don't matter either, although they can help the review process. + +# Solidity Conventions + +In addition to the official Solidity Style Guide we have a number of other conventions that must be followed. + +* All state variables should be private. + + Changes to state should be accompanied by events, and in some cases it is not correct to arbitrarily set state. Encapsulating variables as private and only allowing modification via setters enables us to ensure that events and other rules are followed reliably and prevents this kind of user error. + +* Internal or private state variables or functions should have an underscore prefix. + + ```solidity + contract TestContract { + uint256 private _privateVar; + uint256 internal _internalVar; + function _testInternal() internal { ... } + function _testPrivate() private { ... } + } + ``` + +* Functions should be declared virtual, with few exceptions listed below. The + contract logic should be written considering that these functions may be + overridden by developers, e.g. getting a value using an internal getter rather + than reading directly from a state variable. + + If function A is an "alias" of function B, i.e. it invokes function B without + significant additional logic, then function A should not be virtual so that + any user overrides are implemented on B, preventing inconsistencies. + +* Events should generally be emitted immediately after the state change that they + represent, and should be named in the past tense. Some exceptions may be made for gas + efficiency if the result doesn't affect observable ordering of events. + + ```solidity + function _burn(address who, uint256 value) internal { + super._burn(who, value); + emit TokensBurned(who, value); + } + ``` + + Some standards (e.g. ERC20) use present tense, and in those cases the + standard specification is used. + +* Interface names should have a capital I prefix. + + ```solidity + interface IERC777 { + ``` + +* Contracts not intended to be used standalone should be marked abstract + so they are required to be inherited to other contracts. + + ```solidity + abstract contract AccessControl is ..., { + ``` + +* Unchecked arithmetic blocks should contain comments explaining why overflow is guaranteed not to happen. If the reason is immediately apparent from the line above the unchecked block, the comment may be omitted. + +* Custom errors should be declared following the [EIP-6093](https://eips.ethereum.org/EIPS/eip-6093) rationale whenever reasonable. Also, consider the following: + + * The domain prefix should be picked in the following order: + 1. Use `ERC` if the error is a violation of an ERC specification. + 2. Use the name of the underlying component where it belongs (eg. `Governor`, `ECDSA`, or `Timelock`). + + * The location of custom errors should be decided in the following order: + 1. Take the errors from their underlying ERCs if they're already defined. + 2. Declare the errors in the underlying interface/library if the error makes sense in its context. + 3. Declare the error in the implementation if the underlying interface/library is not suitable to do so (eg. interface/library already specified in an ERC). + 4. Declare the error in an extension if the error only happens in such extension or child contracts. + + * Custom error names should not be declared twice along the library to avoid duplicated identifier declarations when inheriting from multiple contracts. diff --git a/LICENSE b/LICENSE new file mode 100644 index 000000000..817249a0c --- /dev/null +++ b/LICENSE @@ -0,0 +1,22 @@ +The MIT License (MIT) + +Copyright (c) 2016-2023 zOS Global Limited and contributors + +Permission is hereby granted, free of charge, to any person obtaining +a copy of this software and associated documentation files (the +"Software"), to deal in the Software without restriction, including +without limitation the rights to use, copy, modify, merge, publish, +distribute, sublicense, and/or sell copies of the Software, and to +permit persons to whom the Software is furnished to do so, subject to +the following conditions: + +The above copyright notice and this permission notice shall be included +in all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS +OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY +CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, +TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE +SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. diff --git a/README.md b/README.md new file mode 100644 index 000000000..11ee615bb --- /dev/null +++ b/README.md @@ -0,0 +1,107 @@ +> **Warning** +> Version 5.0 is under active development. The code in this branch is not recommended for use. + +# OpenZeppelin + +[![NPM Package](https://img.shields.io/npm/v/@openzeppelin/contracts.svg)](https://www.npmjs.org/package/@openzeppelin/contracts) +[![Coverage Status](https://codecov.io/gh/OpenZeppelin/openzeppelin-contracts/graph/badge.svg)](https://codecov.io/gh/OpenZeppelin/openzeppelin-contracts) +[![GitPOAPs](https://public-api.gitpoap.io/v1/repo/OpenZeppelin/openzeppelin-contracts/badge)](https://www.gitpoap.io/gh/OpenZeppelin/openzeppelin-contracts) +[![Docs](https://img.shields.io/badge/docs-%F0%9F%93%84-yellow)](https://docs.openzeppelin.com/contracts) +[![Forum](https://img.shields.io/badge/forum-%F0%9F%92%AC-yellow)](https://docs.openzeppelin.com/contracts) + +**A library for secure smart contract development.** Build on a solid foundation of community-vetted code. + + * Implementations of standards like [ERC20](https://docs.openzeppelin.com/contracts/erc20) and [ERC721](https://docs.openzeppelin.com/contracts/erc721). + * Flexible [role-based permissioning](https://docs.openzeppelin.com/contracts/access-control) scheme. + * Reusable [Solidity components](https://docs.openzeppelin.com/contracts/utilities) to build custom contracts and complex decentralized systems. + +:mage: **Not sure how to get started?** Check out [Contracts Wizard](https://wizard.openzeppelin.com/) — an interactive smart contract generator. + +:building_construction: **Want to scale your decentralized application?** Check out [OpenZeppelin Defender](https://openzeppelin.com/defender) — a secure platform for automating and monitoring your operations. + +## Overview + +### Installation + +#### Hardhat, Truffle (npm) + +``` +$ npm install @openzeppelin/contracts +``` + +OpenZeppelin Contracts features a [stable API](https://docs.openzeppelin.com/contracts/releases-stability#api-stability), which means that your contracts won't break unexpectedly when upgrading to a newer minor version. + +#### Foundry (git) + +> **Warning** When installing via git, it is a common error to use the `master` branch. This is a development branch that should be avoided in favor of tagged releases. The release process involves security measures that the `master` branch does not guarantee. + +> **Warning** Foundry installs the latest version initially, but subsequent `forge update` commands will use the `master` branch. + +``` +$ forge install OpenZeppelin/openzeppelin-contracts +``` + +Add `@openzeppelin/contracts/=lib/openzeppelin-contracts/contracts/` in `remappings.txt.` + +### Usage + +Once installed, you can use the contracts in the library by importing them: + +```solidity +pragma solidity ^0.8.20; + +import {ERC721} from "@openzeppelin/contracts/token/ERC721/ERC721.sol"; + +contract MyCollectible is ERC721 { + constructor() ERC721("MyCollectible", "MCO") { + } +} +``` + +_If you're new to smart contract development, head to [Developing Smart Contracts](https://docs.openzeppelin.com/learn/developing-smart-contracts) to learn about creating a new project and compiling your contracts._ + +To keep your system secure, you should **always** use the installed code as-is, and neither copy-paste it from online sources nor modify it yourself. The library is designed so that only the contracts and functions you use are deployed, so you don't need to worry about it needlessly increasing gas costs. + +## Learn More + +The guides in the [documentation site](https://docs.openzeppelin.com/contracts) will teach about different concepts, and how to use the related contracts that OpenZeppelin Contracts provides: + +* [Access Control](https://docs.openzeppelin.com/contracts/access-control): decide who can perform each of the actions on your system. +* [Tokens](https://docs.openzeppelin.com/contracts/tokens): create tradeable assets or collectives, and distribute them via [Crowdsales](https://docs.openzeppelin.com/contracts/crowdsales). +* [Utilities](https://docs.openzeppelin.com/contracts/utilities): generic useful tools including non-overflowing math, signature verification, and trustless paying systems. + +The [full API](https://docs.openzeppelin.com/contracts/api/token/ERC20) is also thoroughly documented, and serves as a great reference when developing your smart contract application. You can also ask for help or follow Contracts's development in the [community forum](https://forum.openzeppelin.com). + +Finally, you may want to take a look at the [guides on our blog](https://blog.openzeppelin.com/), which cover several common use cases and good practices. The following articles provide great background reading, though please note that some of the referenced tools have changed, as the tooling in the ecosystem continues to rapidly evolve. + +* [The Hitchhiker’s Guide to Smart Contracts in Ethereum](https://blog.openzeppelin.com/the-hitchhikers-guide-to-smart-contracts-in-ethereum-848f08001f05) will help you get an overview of the various tools available for smart contract development, and help you set up your environment. +* [A Gentle Introduction to Ethereum Programming, Part 1](https://blog.openzeppelin.com/a-gentle-introduction-to-ethereum-programming-part-1-783cc7796094) provides very useful information on an introductory level, including many basic concepts from the Ethereum platform. +* For a more in-depth dive, you may read the guide [Designing the Architecture for Your Ethereum Application](https://blog.openzeppelin.com/designing-the-architecture-for-your-ethereum-application-9cec086f8317), which discusses how to better structure your application and its relationship to the real world. + +## Security + +This project is maintained by [OpenZeppelin](https://openzeppelin.com) with the goal of providing a secure and reliable library of smart contract components for the ecosystem. We address security through risk management in various areas such as engineering and open source best practices, scoping and API design, multi-layered review processes, and incident response preparedness. + +The [OpenZeppelin Contracts Security Center](https://contracts.openzeppelin.com/security) contains more details about the secure development process. + +The security policy is detailed in [`SECURITY.md`](./SECURITY.md) as well, and specifies how you can report security vulnerabilities, which versions will receive security patches, and how to stay informed about them. We run a [bug bounty program on Immunefi](https://immunefi.com/bounty/openzeppelin) to reward the responsible disclosure of vulnerabilities. + +The engineering guidelines we follow to promote project quality can be found in [`GUIDELINES.md`](./GUIDELINES.md). + +Past audits can be found in [`audits/`](./audits). + +Smart contracts are a nascent technology and carry a high level of technical risk and uncertainty. Although OpenZeppelin is well known for its security audits, using OpenZeppelin Contracts is not a substitute for a security audit. + +OpenZeppelin Contracts is made available under the MIT License, which disclaims all warranties in relation to the project and which limits the liability of those that contribute and maintain the project, including OpenZeppelin. As set out further in the Terms, you acknowledge that you are solely responsible for any use of OpenZeppelin Contracts and you assume all risks associated with any such use. + +## Contribute + +OpenZeppelin Contracts exists thanks to its contributors. There are many ways you can participate and help build high quality software. Check out the [contribution guide](CONTRIBUTING.md)! + +## License + +OpenZeppelin Contracts is released under the [MIT License](LICENSE). + +## Legal + +Your use of this Project is governed by the terms found at www.openzeppelin.com/tos (the "Terms"). diff --git a/RELEASING.md b/RELEASING.md new file mode 100644 index 000000000..0318f6338 --- /dev/null +++ b/RELEASING.md @@ -0,0 +1,47 @@ +# Releasing + +> Visit the documentation for [details about release schedule](https://docs.openzeppelin.com/contracts/releases-stability). + +OpenZeppelin Contracts uses a fully automated release process that takes care of compiling, packaging, and publishing the library, all of which is carried out in a clean CI environment (GitHub Actions), implemented in the ([`release-cycle`](.github/workflows/release-cycle.yml)) workflow. This helps to reduce the potential for human error and inconsistencies, and ensures that the release process is ongoing and reliable. + +## Changesets + +[Changesets](https://github.com/changesets/changesets/) is used as part of our release process for `CHANGELOG.md` management. Each change that is relevant for the codebase is expected to include a changeset. + +## Branching model + +The release cycle happens on release branches called `release-vX.Y`. Each of these branches starts as a release candidate (rc) and is eventually promoted to final. + +A release branch can be updated with cherry-picked patches from `master`, or may sometimes be committed to directly in the case of old releases. These commits will lead to a new release candidate or a patch increment depending on the state of the release branch. + +```mermaid + %%{init: {'gitGraph': {'mainBranchName': 'master'}} }%% + gitGraph + commit id: "Feature A" + commit id: "Feature B" + branch release-vX.Y + commit id: "Start release" + commit id: "Release vX.Y.0-rc.0" + + checkout master + commit id: "Feature C" + commit id: "Fix A" + + checkout release-vX.Y + cherry-pick id: "Fix A" tag: "" + commit id: "Release vX.Y.0-rc.1" + commit id: "Release vX.Y.0" + + checkout master + merge release-vX.Y + commit id: "Feature D" + commit id: "Patch B" + + checkout release-vX.Y + cherry-pick id: "Patch B" tag: "" + commit id: "Release vX.Y.1" + + checkout master + merge release-vX.Y + commit id: "Feature E" +``` diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 000000000..4d6ff96ed --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,42 @@ +# Security Policy + +Security vulnerabilities should be disclosed to the project maintainers through [Immunefi], or alternatively by email to security@openzeppelin.com. + +[Immunefi]: https://immunefi.com/bounty/openzeppelin + +## Bug Bounty + +Responsible disclosure of security vulnerabilities is rewarded through a bug bounty program on [Immunefi]. + +There is a bonus reward for issues introduced in release candidates that are reported before making it into a stable release. + +## Security Patches + +Security vulnerabilities will be patched as soon as responsibly possible, and published as an advisory on this repository (see [advisories]) and on the affected npm packages. + +[advisories]: https://github.com/OpenZeppelin/openzeppelin-contracts/security/advisories + +Projects that build on OpenZeppelin Contracts are encouraged to clearly state, in their source code and websites, how to be contacted about security issues in the event that a direct notification is considered necessary. We recommend including it in the NatSpec for the contract as `/// @custom:security-contact security@example.com`. + +Additionally, we recommend installing the library through npm and setting up vulnerability alerts such as [Dependabot]. + +[Dependabot]: https://docs.github.com/en/code-security/supply-chain-security/understanding-your-software-supply-chain/about-supply-chain-security#what-is-dependabot + +### Supported Versions + +Security patches will be released for the latest minor of a given major release. For example, if an issue is found in versions >=4.6.0 and the latest is 4.8.0, the patch will be released only in version 4.8.1. + +Only critical severity bug fixes will be backported to past major releases. + +| Version | Critical security fixes | Other security fixes | +| ------- | ----------------------- | -------------------- | +| 4.x | :white_check_mark: | :white_check_mark: | +| 3.4 | :white_check_mark: | :x: | +| 2.5 | :white_check_mark: | :x: | +| < 2.0 | :x: | :x: | + +Note as well that the Solidity language itself only guarantees security updates for the latest release. + +## Legal + +Smart contracts are a nascent techology and carry a high level of technical risk and uncertainty. OpenZeppelin Contracts is made available under the MIT License, which disclaims all warranties in relation to the project and which limits the liability of those that contribute and maintain the project, including OpenZeppelin. Your use of the project is also governed by the terms found at www.openzeppelin.com/tos (the "Terms"). As set out in the Terms, you are solely responsible for any use of OpenZeppelin Contracts and you assume all risks associated with any such use. This Security Policy in no way evidences or represents an on-going duty by any contributor, including OpenZeppelin, to correct any flaws or alert you to all or any of the potential risks of utilizing the project. diff --git a/audits/2017-03.md b/audits/2017-03.md new file mode 100644 index 000000000..4cd6dbfd3 --- /dev/null +++ b/audits/2017-03.md @@ -0,0 +1,292 @@ +# OpenZeppelin Audit + +NOTE ON 2021-07-19: This report makes reference to Zeppelin, OpenZeppelin, OpenZeppelin Contracts, the OpenZeppelin team, and OpenZeppelin library. Many of these things have since been renamed and know that this audit applies to what is currently called the OpenZeppelin Contracts which are maintained by the OpenZeppelin Contracts Community. + +March, 2017 +Authored by Dennis Peterson and Peter Vessenes + +# Introduction + +Zeppelin requested that New Alchemy perform an audit of the contracts in their OpenZeppelin library. The OpenZeppelin contracts are a set of contracts intended to be a safe building block for a variety of uses by parties that may not be as sophisticated as the OpenZeppelin team. It is a design goal that the contracts be deployable safely and "as-is". + +The contracts are hosted at: + +https://github.com/OpenZeppelin/zeppelin-solidity + +All the contracts in the "contracts" folder are in scope. + +The git commit hash we evaluated is: +9c5975a706b076b7000e8179f8101e0c61024c87 + +# Disclaimer + +The audit makes no statements or warrantees about utility of the code, safety of the code, suitability of the business model, regulatory regime for the business model, or any other statements about fitness of the contracts to purpose, or their bugfree status. The audit documentation is for discussion purposes only. + +# Executive Summary + +Overall the OpenZeppelin codebase is of reasonably high quality -- it is clean, modular and follows best practices throughout. + +It is still in flux as a codebase, and needs better documentation per file as to expected behavior and future plans. It probably needs more comprehensive and aggressive tests written by people less nice than the current OpenZeppelin team. + +We identified two critical errors and one moderate issue, and would not recommend this commit hash for public use until these bugs are remedied. + +The repository includes a set of Truffle unit tests, a requirement and best practice for smart contracts like these; we recommend these be bulked up. + +# Discussion + +## Big Picture: Is This A Worthwhile Project? + +As soon as a developer touches OpenZeppelin contracts, they will modify something, leaving them in an un-audited state. We do not recommend developers deploy any unaudited code to the Blockchain if it will handle money, information or other things of value. + +> "In accordance with Unix philosophy, Perl gives you enough rope to hang yourself" +> --Larry Wall + +We think this is an incredibly worthwhile project -- aided by the high code quality. Creating a framework that can be easily extended helps increase the average code quality on the Blockchain by charting a course for developers and encouraging containment of modifications to certain sections. + +> "Rust: The language that makes you take the safety off before shooting yourself in the foot" +> -- (@mbrubeck) + +We think much more could be done here, and recommend the OpenZeppelin team keep at this and keep focusing on the design goal of removing rope and adding safety. + +## Solidity Version Updates Recommended + +Most of the code uses Solidity 0.4.11, but some files under `Ownership` are marked 0.4.0. These should be updated. + +Solidity 0.4.10 will add several features which could be useful in these contracts: + +- `assert(condition)`, which throws if the condition is false + +- `revert()`, which rolls back without consuming all remaining gas. + +- `address.transfer(value)`, which is like `send` but automatically propagates exceptions, and supports `.gas()`. See https://github.com/ethereum/solidity/issues/610 for more on this. + +## Error Handling: Throw vs Return False +Solidity standards allow two ways to handle an error -- either calling `throw` or returning `false`. Both have benefits. In particular, a `throw` guarantees a complete wipe of the call stack (up to the preceding external call), whereas `false` allows a function to continue. + +In general we prefer `throw` in our code audits, because it is simpler -- it's less for an engineer to keep track of. Returning `false` and using logic to check results can quickly become a poorly-tracked state machine, and this sort of complexity can cause errors. + +In the OpenZeppelin contracts, both styles are used in different parts of the codebase. `SimpleToken` transfers throw upon failure, while the full ERC20 token returns `false`. Some modifiers `throw`, others just wrap the function body in a conditional, effectively allowing the function to return false if the condition is not met. + +We don't love this, and would usually recommend you stick with one style or the other throughout the codebase. + +In at least one case, these different techniques are combined cleverly (see the Multisig comments, line 65). As a set of contracts intended for general use, we recommend you either strive for more consistency or document explicit design criteria that govern which techniques are used where. + +Note that it may be impossible to use either one in all situations. For example, SafeMath functions pretty much have to throw upon failure, but ERC20 specifies returning booleans. Therefore we make no particular recommendations, but simply point out inconsistencies to consider. + +# Critical Issues + +## Stuck Ether in Crowdsale contract +CrowdsaleToken.sol has no provision for withdrawing the raised ether. We *strongly* recommend a standard `withdraw` function be added. There is no scenario in which someone should deploy this contract as is, whether for testing or live. + +## Recursive Call in MultisigWallet +Line 45 of `MultisigWallet.sol` checks if the amount being sent by `execute` is under a daily limit. + +This function can only be called by the "Owner". As a first angle of attack, it's worth asking what will happen if the multisig wallet owners reset the daily limit by approving a call to `resetSpentToday`. + +If a chain of calls can be constructed in which the owner confirms the `resetSpentToday` function and then withdraws through `execute` in a recursive call, the contract can be drained. In fact, this could be done without a recursive call, just through repeated `execute` calls alternating with the `confirm` calls. + +We are still working through the confirmation protocol in `Shareable.sol`, but we are not convinced that this is impossible, in fact it looks possible. The flexibility any shared owner has in being able to revoke confirmation later is another worrisome angle of approach even if some simple patches are included. + +This bug has a number of causes that need to be addressed: + +1. `resetSpentToday` and `confirm` together do not limit the days on which the function can be called or (it appears) the number of times it can be called. +1. Once a call has been confirmed and `execute`d it appears that it can be re-executed. This is not good. +3. `confirmandCheck` doesn't seem to have logic about whether or not the function in question has been called. +4. Even if it did, `revoke` would need updates and logic to deal with revocation requests after a function call had been completed. + +We do not recommend using the MultisigWallet until these issues are fixed. + +# Moderate to Minor Issues + +## PullPayment +PullPayment.sol needs some work. It has no explicit provision for cancelling a payment. This would be desirable in a number of scenarios; consider a payee losing their wallet, or giving a griefing address, or just an address that requires more than the default gas offered by `send`. + +`asyncSend` has no overflow checking. This is a bad plan. We recommend overflow and underflow checking at the layer closest to the data manipulation. + +`asyncSend` allows more balance to be queued up for sending than the contract holds. This is probably a bad idea, or at the very least should be called something different. If the intent is to allow this, it should have provisions for dealing with race conditions between competing `withdrawPayments` calls. + +It would be nice to see how many payments are pending. This would imply a bit of a rewrite; we recommend this contract get some design time, and that developers don't rely on it in its current state. + +## Shareable Contract + +We do not believe the `Shareable.sol` contract is ready for primetime. It is missing functions, and as written may be vulnerable to a reordering attack -- an attack in which a miner or other party "racing" with a smart contract participant inserts their own information into a list or mapping. + +The confirmation and revocation code needs to be looked over with a very careful eye imagining extraordinarily bad behavior by shared owners before this contract can be called safe. + +No sanity checks on the initial constructor's `required` argument are worrisome as well. + +# Line by Line Comments + +## Lifecycle + +### Killable + +Very simple, allows owner to call selfdestruct, sending funds to owner. No issues. However, note that `selfdestruct` should typically not be used; it is common that a developer may want to access data in a former contract, and they may not understand that `selfdestruct` limits access to the contract. We recommend better documentation about this dynamic, and an alternate function name for `kill` like `completelyDestroy` while `kill` would perhaps merely send funds to the owner. + +Also note that a killable function allows the owner to take funds regardless of other logic. This may be desirable or undesirable depending on the circumstances. Perhaps `Killable` should have a different name as well. + +### Migrations + +I presume that the goal of this contract is to allow and annotate a migration to a new smart contract address. We are not clear here how this would be accomplished by the code; we'd like to review with the OpenZeppelin team. + +### Pausable + +We like these pauses! Note that these allow significant griefing potential by owners, and that this might not be obvious to participants in smart contracts using the OpenZeppelin framework. We would recommend that additional sample logic be added to for instance the TokenContract showing safer use of the pause and resume functions. In particular, we would recommend a timelock after which anyone could unpause the contract. + +The modifiers use the pattern `if(bool){_;}`. This is fine for functions that return false upon failure, but could be problematic for functions expected to throw upon failure. See our comments above on standardizing on `throw` or `return(false)`. + +## Ownership + +### Ownable + +Line 19: Modifier throws if doesn't meet condition, in contrast to some other inheritable modifiers (e.g. in Pausable) that use `if(bool){_;}`. + +### Claimable + +Inherits from Ownable but the existing owner sets a pendingOwner who has to claim ownership. + +Line 17: Another modifier that throws. + +### DelayedClaimable + +Is there any reason to descend from Ownable directly, instead of just Claimable, which descends from Ownable? If not, descending from both just adds confusion. + +### Contactable + +Allows owner to set a public string of contract information. No issues. + +### Shareable + +This needs some work. Doesn't check if `_required <= len(_owners)` for instance, that would be a bummer. What if _required were like `MAX - 1`? + +I have a general concern about the difference between `owners`, `_owners`, and `owner` in `Ownable.sol`. I recommend "Owners" be renamed. In general we do not recomment single character differences in variable names, although a preceding underscore is not uncommon in Solidity code. + +Line 34: "this contract only has six types of events"...actually only two. + +Line 61: Why is `ownerIndex` keyed by addresses hashed to `uint`s? Why not use the addresses directly, so `ownerIndex` is less obscure, and so there's stronger typing? + +Line 62: Do not love `++i) ... owners[2+ i]`. Makes me do math, which is not what I want to do. I want to not have to do math. + +There should probably be a function for adding a new operation, so the developer doesn't have to work directly with the internal data. (This would make the multisig contract even shorter.) + +There's a `revoke` function but not a `propose` function that we can see. + +Beware reordering. If `propose` allows the user to choose a bytes string for their proposal, bad things(TM) will happen as currently written. + + +### Multisig + +Just an interface. Note it allows changing an owner address, but not changing the number of owners. This is somewhat limiting but also simplifies implementation. + +## Payment + +### PullPayment + +Safe from reentrance attack since ether send is at the end, plus it uses `.send()` rather than `.call.value()`. + +There's an argument to be made that `.call.value()` is a better option *if* you're sure that it will be done after all state updates, since `.send` will fail if the recipient has an expensive fallback function. However, in the context of a function meant to be embedded in other contracts, it's probably better to use `.send`. One possible compromise is to add a function which allows only the owner to send ether via `.call.value`. + +If you don't use `call.value` you should implement a `cancel` function in case some value is pending here. + +Line 14: +Doesn't use safeAdd. Although it appears that payout amounts can only be increased, in fact the payer could lower the payout as much as desired via overflow. Also, the payer could add a large non-overflowing amount, causing the payment to exceed the contract balance and therefore fail when withdraw is attempted. + +Recommendation: track the sum of non-withdrawn asyncSends, and don't allow a new one which exceeds the leftover balance. If it's ever desirable to make payments revocable, it should be done explicitly. + +## Tokens + +### ERC20 + +Standard ERC20 interface only. + +There's a security hole in the standard, reported at Edcon: `approve` does not protect against race conditions and simply replaces the current value. An approved spender could wait for the owner to call `approve` again, then attempt to spend the old limit before the new limit is applied. If successful, this attacker could successfully spend the sum of both limits. + +This could be fixed by either (1) including the old limit as a parameter, so the update will fail if some gets spent, or (2) using the value parameter as a delta instead of replacement value. + +This is not fixable while adhering to the current full ERC20 standard, though it would be possible to add a "secureApprove" function. The impact isn't extreme since at least you can only be attacked by addresses you approved. Also, users could mitigate this by always setting spending limits to zero and checking for spends, before setting the new limit. + +Edcon slides: +https://drive.google.com/file/d/0ByMtMw2hul0EN3NCaVFHSFdxRzA/view + +### ERC20Basic + +Simpler interface skipping the Approve function. Note this departs from ERC20 in another way: transfer throws instead of returning false. + +### BasicToken + +Uses `SafeSub` and `SafeMath`, so transfer `throw`s instead of returning false. This complies with ERC20Basic but not the actual ERC20 standard. + +### StandardToken + +Implementation of full ERC20 token. + +Transfer() and transferFrom() use SafeMath functions, which will cause them to throw instead of returning false. Not a security issue but departs from standard. + +### SimpleToken + +Sample instantiation of StandardToken. Note that in this sample, decimals is 18 and supply only 10,000, so the supply is a small fraction of a single nominal token. + +### CrowdsaleToken + +StandardToken which mints tokens at a fixed price when sent ether. + +There's no provision for owner withdrawing the ether. As a sample for crowdsales it should be Ownable and allow the owner to withdraw ether, rather than stranding the ether in the contract. + +Note: an alternative pattern is a mint() function which is only callable from a separate crowdsale contract, so any sort of rules can be added without modifying the token itself. + +### VestedToken + +Lines 23, 27: +Functions `transfer()` and `transferFrom()` have a modifier canTransfer which throws if not enough tokens are available. However, transfer() returns a boolean success. Inconsistent treatment of failure conditions may cause problems for other contracts using the token. (Note that transferableTokens() relies on safeSub(), so will also throw if there's insufficient balance.) + +Line 64: +Delete not actually necessary since the value is overwritten in the next line anyway. + +## Root level + +### Bounty + +Avoids potential race condition by having each researcher deploy a separate contract for attack; if a research manages to break his associated contract, other researchers can't immediately claim the reward, they have to reproduce the attack in their own contracts. + +A developer could subvert this intent by implementing `deployContract()` to always return the same address. However, this would break the `researchers` mapping, updating the researcher address associated with the contract. This could be prevented by blocking rewrites in `researchers`. + +### DayLimit + +The modifier `limitedDaily` calls `underLimit`, which both checks that the spend is below the daily limit, and adds the input value to the daily spend. This is fine if all functions throw upon failure. However, not all OpenZeppelin functions do this; there are functions that returns false, and modifiers that wrap the function body in `if (bool) {_;}`. In these cases, `_value` will be added to `spentToday`, but ether may not actually be sent because other preconditions were not met. (However in the OpenZeppelin multisig this is not a problem.) + +Lines 4, 11: +Comment claims that `DayLimit` is multiowned, and Shareable is imported, but DayLimit does not actually inherit from Shareable. The intent may be for child contracts to inherit from Shareable (as Multisig does); in this case the import should be removed and the comment altered. + +Line 46: +Manual overflow check instead of using safeAdd. Since this is called from a function that throws upon failure anyway, there's no real downside to using safeAdd. + +### LimitBalance + +No issues. + +### MultisigWallet + +Lines 28, 76, 80: +`kill`, `setDailyLimit`, and `resetSpentToday` only happen with multisig approval, and hashes for these actions are logged by Shareable. However, they should probably post their own events for easy reading. + +Line 45: +This call to underLimit will reduce the daily limit, and then either throw or return 0. So in this case there's no danger that the limit will be reduced without the operation going through. + +Line 65: +Shareable's onlyManyOwners will take the user's confirmation, and execute the function body if and only if enough users have confirmed. Whole thing throws if the send fails, which will roll back the confirmation. Confirm returns false if not enough have confirmed yet, true if the whole thing succeeds, and throws only in the exceptional circumstance that the designated transaction unexpectedly fails. Elegant design. + +Line 68: +Throw here is good but note this function can fail either by returning false or by throwing. + +Line 92: +A bit odd to split `clearPending()` between this contract and Shareable. However this does allow contracts inheriting from Shareable to use custom structs for pending transactions. + + +### SafeMath + +Another interesting comment from the same Edcon presentation was that the overflow behavior of Solidity is undocumented, so in theory, source code that relies on it could break with a future revision. + +However, compiled code should be fine, and in the unlikely event that the compiler is revised in this way, there should be plenty of warning. (But this is an argument for keeping overflow checks isolated in SafeMath.) + +Aside from that small caveat, these are fine. + diff --git a/audits/2018-10.pdf b/audits/2018-10.pdf new file mode 100644 index 0000000000000000000000000000000000000000..d5bf12741c8a6d44ed597de7204fde72d91dec35 GIT binary patch literal 1000527 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%0AXGSxD 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%0Ds@WxhHVsCq?&%C$272odl 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

{23QAMhgmDFwY9!) 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

%X-{jq)zF)pGEGKPHkt7x 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

@!c9KnY4NvNgEvnPA? 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

QsKH{N_IQtXo9hrt1|lnPuADU$b1Mf#WXL540@w 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%0DQ_tNgAAku*dN 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

fwy2<7q zDUf=Nh}CM0fE@!qOXtsLFjQ>$FZ2yw)|OeY5B{dg9ZVSOX9Cpw#z`7!j7aa6(6{a$4FhsBu72G5Gt3ar2e+Aijb6l&EFnK zgbkye>R;w7rO=AxuAv~#+b(Q)j+Y#7Nn#15O)!WjhFJ*}vDBRwPW>2EYH(nfeo!Zs zP>e)wKb@f2;oB4uV%v|fqUSmpTAMbtW&7L?cX91cn|dOtrX8qUXNP$Ynz=hWo;#yF zeTFVdpOqs}-XfM|7RKBO^#dvUB!<69j0Pv*DFGL^*?2Xg4WcIZ81Ze(rMDXv=B5gr z<9w|<*ww7#S7KM{6vkIj!s}wu^RAU+} z_+K98!d36qresKVe%TT&ENQq3Sg+fC`0q?GZUKkR?AYGfa}DTY*=Qf_l#vck<3kiw z)H!4f1H7PuBOsy~O!MjSBzK9$Qk%vRJ3`)gI9gz7WnCOjxn86hH5G zgD2-V=1O-9F}V6$>;W)YiiN_{+hFUvN-Wr1Z;}-~3CYu48b8G4sV%T5_<6e;?41i< zjxjYG61gXMT!-zH)h1a@ zzc@*6>iAi^b8nC5UC}~_MsyT}^^(~wsL=@x7|M-zzxr9lm%+QP@EdH+{C$fX`+;Q( z6QV%O;N3e8@LmWGzhK^LA0Q5QC4-Bno^1V-xPGwh2!?h-RL=3UU`*a$N(Myz9YXbe zGV-Jy;QRF*wM$$KEGL|k|4~5yvx}Jma+ZO|rC!)gkGV|_;9cFr$DKk)>BWN~(;Eu9o zomyAR7ZTY?Mw9i78#mq71J%i>vEvcO@L4c;SS7$}G0MR95G$TbzhB=wK7TeZ^v?q7 ziLHMk4zvAQPw@rFW*L67mPFv?af}v=)9%L|y^|wk-!-aR|Llg~K39@`R9^xSxPBM= z%b2T` zPo$0~?@P|iQG+?;Gs3Zeo zXbX#;hntIv%fKX0ES1%mVtNWu);V)bS{0CYn#r{ph#h?w# z6aK&5lWm|BG){A;kL3ay6mvhXy9Cy3k{vbYCUbt;C6TYg5`sON*TKz6$DWUL*^*E{x;lj@bJ z`4&lWklridPA3CY5l%c%$^n1Pm&%PAQplvCa{3Hib?3gz27P1s91=R+^1+6H6s zX}R-IsHye2ggRzPgJVhe%bq-+OzFo;e9%7PGPj1Aleg=h9i%k;OnTRh-aB0J;p<7I zw8+$Jd~qD@_#kGO7hC21FO8qv#;DYxlStWbP@_fqy&$j#>utVouc?l14i?Wu0^zp8s}gvot|7hnFNC zNiTi`YloFI@S9Z0z=e9|Zi9c5kfAEH;n^;ShS75#=|_e?dpF__yh8mH z@lHAhs3jbuCqTWS2G)ou-vDLCDK&o^B(jY&xUPFgnaQZU-r>t&d!_}x_}*z9Py%dJ zo~*7^s3fb$Hh);$S4u^*)^*L&3AJx#kqJWrpA%fu8vwaoV>(@ZVbbi9->7^y3+t`j zOdyK|8R>PHS>NTy{V24#@~TB{Ai*l~%)=y%p0F5LwJi!m{hd_H>zP%|P&@OPnn{(p z)I&0*F`{<3ibJlFcSRyTh*HXKypRwbS9wdOry13AL+CQ-QzNa5dJR*(3EzXU-09Q2 z$F+?M%r#y(sagSlaDIZ#Eb7m`f~_?_>%~Z)9B&#@`Qs7Z=aw|SF4b$MV9zTjxm^UQ&3@=GE<<&7(JLN9}mZ)$p_t0B4G1_N`E7X0ysF_!kS!O6?rx z)DQcdDb-YS_Km5JRCsx{yrWTQgN%2B{gCK!8Y`28OY9u+Ko1@@IW}nN?#MruYBeF; vmz$7%8{kQOm<9x(L!%4$|Fbnt&IXRo?v5s=upAsL9Bk~cBqSnoqOku9foUHh literal 0 HcmV?d00001 diff --git a/audits/2022-10-Checkpoints.pdf b/audits/2022-10-Checkpoints.pdf new file mode 100644 index 0000000000000000000000000000000000000000..7e0d08387ad3be0a3e74201566eca3167aead1c2 GIT binary patch literal 155606 zcmcFr2V4}%(iagF6c8myMiCTn7j~CjSjiwDIp-`nrzJ-NK@m8KN|Y=a$r%wzB1!Th zK{ApgXZ!~6PVS!Gd%W-7@8>$rbamCgs=8~sr>lov=8iB30%pgh{~8ybgbSf%rM0?e zip#}?%c9_HZ9vN+qibYfhsz>vqHjm5PKyBQRDOpncLf$SXtUJ0;cJ4M27%U6g?Z z!0*>g*dXj+7=i!A4$yw@;eRm{ z9LWYovi{J~(h6l@2h!CCx-y`pt~ubaBYS_>`R54!irxws7cSq&1xU}>K+nwD3b39X z$lT(@(#TE^;CN{Aqapkk zCH^Yj&fdZTkaF1IXz2f&1}NQo<^~`uLlDr-4*J+(r#^}u|E8tArM(?sY-?K+2cSQJ z4DBuT{^%Y@0p>3ZU`Pa@8WM^;7^<4Ing^r%=->A+bD-hxV_e7yB_e;&Q4dG1E(FYa zSkTj@g&Z_u;s5=PApg;wgPSVS_e_DFen@Eof&-%$!O9AUK_O5!Bn*aN<)DSI9mRnp=^wFZON+bt`1d4;!PZ#keEsozv=+hj z(EIrK<7sT`*kLL}NfZg)7_`m~>>06;Wy9R4i>)VY zH(4oeIP}!Dj4X@Gzp?txb4)&KtBtD#N>J(HH1 zMJb~O&;1_Tp4Tg!W0*J8y;GE*=wQt772`w8^S1dCX&p~3YI>N?Q=>mizv5o?MW7?2fpRQ_nRMMuN+Uc>+eV4mg>VCb_LU3q!TI zlnM=?j9EJ!Et>h(vln(Bf7#uTD4WKJh8y2ho2{F!jbnO?c%RstfH80G5~*Qd%dc@M zc%3$Oufwc^gm{lk?4p&ed}q!F{sjNB>iAHB`#EQBTD*mKu+tK)RY=rkZ-xIxbJ~p! zl~f6x^?le*$ajz6Om=pDhIDgK1nI-R37Ydl&h)|}j}c#3aKf)^E9;^gg?fn#@n5Lr zbkA>>*B523F?)WRRUTW##qt)?8`!4!Agd={q?unoZsCgPZZh9+v$J=1T++)mGVU=S zEtusAwDeG4eDVJBEctR|2dwm45BEFr_mve6^E6+CAzlaL;d|%)J~9r%@$Vz!#}wsY z$k_rh=J#i{q=CMPu7H&j5TXx;790r&L)qbQAU<%gLBJdwNOlAp5GH^L$x&#cJ)EiF zvd9_OS=rm_0Z;YAmXN~RgVyibCnlq8^d*LPGeuZQ0uSM_Vi5RfLD_Dw<;PK%t>3x(0%+x2b;@n ze=^@1KU%W!3HQuR%DFa{#67Ffl7QD6O0m^$uG<6heJ*(G!!v#vG*a5%I`(6~Jp%P0 z)I1z$HfFJHX>GBp!lsHnn`&yyz-`-LcX4Xb;~P

2ojH?x0tMLX1p#1!i~6c>Ik8Oj z%qxS4m=ed7GA$OUIx5ZcN7xCb^iXC>%iMvFrpwfu)aSfAn#5xD%>2LxvvlunUyLaa zt7ss>ve8QJ@0fKvVIo9sv;?yu#ONncir#>IAf0vw1un zk%GEuEU3Wet*Lk(iJE+4W>HeVz{YPf6d5)}?IhRA&1%$)Th=4#Q2kln=mFSEwA^~X zz(5rsML3pz_^hd3acZ0gfhHg1YKmUj-QK^ld;-XMk$dUg5PlDyhFUkME%e*aJFc zJ&Q-*EBqi9>mp+D!Lm5aZ4qyMYMP)oXII>VCN=rdOJvd-JfxGB|slUCL(((|@ zR4+~CyhZYju6m%t9NK$117uRv-qF81pf#wpjPBnp_pJ!HG%$$#YG(Vu-ES-AX^i>3 zL5Irs?9v$ePpEk{_R+t!)jy5*@VL>bvJlD2{diG_^CWi41kBe%56i=Za(>w}4y!)48P^Z@42>8zR zKjUWGB{29(7l1O>Il|>@M^Me#o zo&!n4VngJ>^;EA|?BU;@6j#|0-vZr>+K2jfInl-}leXG#o$qFE=bmDlNZ&Ar2WOb4 zm#k5grfYC**H| z0gSC;cs?tjr8?%#y3LF!uKC*7Y4xT7k1(rkN}^K{ymkAt;$9k+oA2J!%Pg!Aa%?Q* zx2fk9-ENR(H`kp8^@{B|iXx`Hztd?J59 z=9Y5BIJkWP?i}ck;xBQQG?=iwAyhk*yTLJ^oJ8QyDlg{JrZth2RAsfKCicbXh4FjQ zEhP@f7R$fg+S<~{>e!uqM0HDLr@p1N_YnMU*J@O|-pnn9M1NBea zpqqug9P$WX#+ctRZu-4=#`p#Wq1xfyzZ3yw{zkxet_Na|6gR8Abu$K)V!OzmqQgupt*RBV;(Dqpjkxf>-M~( z^b*qCf}n#TQMVZ}EtM)c>$x&0(v^GfvDKV(Y*qCm*1#3ScxrAvVk5VDH>%CHzsY-T zK}w_N@=pEM*>SufMfRoeGP=)#f-Ww0q?^pj{uN;>XH`T#e&H=O*vFi>#Bc9) z$Cx5KS*ous65(ua#h5K3YFg7`Q=YJsdTPv3pauoM~@(^uof5kbALbwx`zliuiQF zJ5Ii0cmKp_HWh(h3+b8Fglnigo?EdgQ(oCSh>We)*o_&iL1wdI`DMyIu2W}G{lyN? zsBi`|gQT&F7K7QNEbaTMEP^>d_UY~veReJUf;-^Ys*Ydyc0Hz++1f1(-VYRp}K4!E4s3YLzbd&JQqfJ2Y^b59^lIVY+!r->+zS zcFtwU9v@r&;o_ocE!frj?S^Av{5Un#&9k?o*pTY7*|7bUkB*!B*>vD%gq^~=X2UT{Pn^^_rX3+%)O*EjxDeeC zKC)AeKI7_upX*LaK}Uf(P%PPIVM#DN3?I0HR06n`W_x1@44fJ8am{s4Ek)A+^eLu# zbr=9e{}pEhbiE=m;MtUgUK?jmXA()#qOsn1b1?SHhXK#jy%rbABLj%f0^)V_^vlhA zs+y~;3OlzP`z@YQ&g>2tK2v{%+SjbFBGEf%p*MbKYS`|x6+V~B4!E|y@qTOdRGuyi zP(S&g@#V_m$HO+|Y!r0Lx4(fwR(4<7(2gbu;Z}gcbogHCiq-5#1Ra1*fr5?{ph&iI zZr^f5g6KN792s>f0$QuZiy*cDqswyByXE60lJVz?7WMVU?*dYv_1Bw!-P4r&^igVR zm>zuv*}1i$Q0JPuvUrbXp8L%3Fn!;ZQh*zdK|U#~n`eX$&E*)+ftxm<+n3OXNaw#= zD3SD3O}+J)MeWC=1_Ih~2C+$&f8C4O>8l5rmIBrUfGjlCKRF_p-sNOJ1lkI+um@Pj z-nLCxS=6w2ssS|ZEg*5h&@_J<4U{7g5fdXjt_$@Suf=#ynd^;M-%BHOmo(zavdZK&2aDZmv@dz@=k0(^jv z^egsb$^xD(Z5P|09|-KNmd}SA&~z60_f~gy9o!#$ZP740oK~Opd2P|8iwS5NRwh)j z&uyWFnd6yie!#&Zzr#>;9~MX_G;$x_vOzyFh^RUD6Yw3!{v zj?3ecXd8*nErjQb@h4?-q{z;@dM3JyL_Qp)&=Ln1E+Fo!_%AQ_rg+r*ivIta z$A1NPfcQqi5$Zo9ruxn!sMCXVf1iZrmA?vA-~PJm zc9UtM5XPY`lP=F#Vs7Tj&NLC1yOk*+uo%7XEow~eX^l%jIODf<3&`X-HQNh{wSV=_M=LfrRjhh8L9!@kDHiAfl5Kzps= z!W}OM>}vwehZLvgFWh+)en^CYCi6Q7IwU$>06T005S=kLI&AZw5&?@cioa)buKfty zfvlG?NBC}of0R#%6iuvN=e zF*=C*mJ!Rz4$Y4~b6A z&(S{$KO{PZK57FHVHD&aw)szqmO19<|DMfh<0Ei@tTXMcNBF2Bew0s$l}pO?XWINT zD*poOxD9&X(5Qbl(9ft(sLik41N4di#DP8gY>$ASm%~oyMYW^fDfGOwpfT{9F2Mul z!Fh+XYDuP|r{8DNj$#PmdSLR~oi(~a?nFW^V0y4V6!{`q?Wc1#z<)y}MTMR0ZgIenQ4% zug`(#NM6Pe`nN;x5vmE_;^U+vi8nZ;@Ny8oCD43GbZY*o%A@c@A|QSpwgHHM_;uLk zKP3WQv;_P;8!Y1^aDc4y?X5@ns3LxpPly#5%sh@U?BUEJNY^=K0fNF9x3;D`qe2B?(-azNlAi8d* zFysz}-@u#ng|$}Ixzl>o#WX{$AIW+r{`;;O3Ne;3hL=CyX67dXVXD;SY;ZY@VzYaz1Q1i zEz;~=^u&x`1@xozqewcQn2Li;oUu>E7@g0G&qW7kdP}JjWPt1tBnLZBQ5g^R@|N+Z zt<|vb3A@Ad)X&F!q)rDJ#DNOtIRVD*vntitD69N&R}qWMf_{OWAz2GXyGQ0>z)sD* zq_ADC^H``CAk-XIcX+VT`NAr~!q?CSm%~jbg&sAgmt#M+oEGnQhqH!N=AP}UPjS%# zGY5N7=X;}BNxQ?jfK4*53}9<$>b50S&s)Mlv|2A_K?~hZtgw*9tzKY{OjgFCDV4Yh z0Zj+Vcg#g}L-=l(#Urf64tLNjDtyr@v1VqjWPpVBUh>QF01_}+cX&Y?iD|$EVEaq? zvDz1^LP$BVQM4k42UH(!G)*QsOYO;8h~5}>n+EWwMNrOCJ&I+LpTQ}7t)Ivp^BUfz#DyU08{q463*BS$o z2`n`dmQ0qFl+ntBpOOcwF|}j&x5ved76Zo;=3|p>Z*WglS<0F-J0@!p%QU%XE;9}* z?N+{yo68QgXP%qt>b$RtJyFuYy!6HSrgQk5t)7O*KGTBM%8ca)8SiFxcV63Xlb!al zInvHn?7Zr62;SAPTApT)QoK4TH~q_j<;tVCpIxfvlDwf&h3sL7iV)9dZf1WBnJc5` z;m(n3bz|`@NtgM!8c`)t$o1CrT-ELQoh67GZ*Wjo_5eCaZPQ>VjB`di=i|KLRG7!! zMWt=+I5CY4D=k?r>NZr{TGVQ=JxVRBI~6^sMlhVLUK*&B`E)98X6elri_r?jtxf(W zyCSD?w0+_NX-#UX8&|mrn|iS{spE#yhuaztsUI%RzklWUQG8%8tGPJMF1s>Yc191L z_hP9-LRr#2`Dq*D|Z<`m0gy+XSP4l6k=WXWoYOJR#J(6_!U_8Q#;f zJK5KI=*dmqq(U`>Nk~$cXO@+knGTYeg*_PKXich;`G)8&4 zCQ8ShOUG`?`HRLZGS4U_S>JHiUd#4Y6hc+cW{Z?u%IfLA3mc@&*fD6K{d8S;jYE64 z#a?=0mRTCL{t@PLd&q5No{9UcqG(1-1DRU)Y|RZ)`eO3lfRZ?kGORYg#V&w>=CyheS6vCii1rY-CD1zF!KMEpU}|{AdxJy>Hwt6!(SGA|hML z)zEFc==MEj++mXq_fHH#C6ST0Eh3z{O?FVjNJol<)$$n^JD z9uO*03A;(nt=-+M%WmT7+)k~;n|U=)yn_7N4hrvCgB!VvwF8L*tOtr)HA8w-1VgSzxG4JPRLQ_&Rfl^9-0Q~%lhpW4 zt8af$PJ=?d0v1J*R?m#rp=IY7zIQZmW%bRJ1V) zO!sye%1AHk?M^O#c)jCQdfB_#kTR5F_nr%)O3Z#S-AFN}%AYf6G0I&R);++Ix!6Ob z_3%N4J}=W(ZDSSd_q)OgUk#SR*s*6ZErB6C9mb|%Ru#;c2er}OU>SAeN&x% z5Z5$$q0Y*i#<3oAwxtOE{!@=>osHMSfmE3nXXEEB)2)k*Q{~#!oH%id)6?}MImseTK`hl*$m1t7KJTYLDBbGVH(j&|Utjmn z>DAs`+Gj4FoSn%o>^3N}Z?7=1R}@NC|6)qot?4Bm5P4yHRc^3@*=TLGic&1bc@-YC zF0!$9Z5_$HRz?XP3{ykyFjqM8wytH|mK{&`m^uILQqXIb&kKdCq(L(aWUWD>oqMD= zdP$XUh+dl065km0PA*pd2=_Hvp(;U}I)l}BpuaHbEr4K2CymtXHb}VSA*23vM-Az9)jCK0eq-upt*Wp>Z z`nkG}V0&h6??sDHc}{+`h*MiZE-bjz?1zQzvMWt$8`@Xuf5TOpl=3YNkIw0x(?;&C zeMWWcKNM*TaOx~Hy0^!{ZN1~neu<(a3{)7MCFkjAbYrNW&#cR`e5-A$4Q7$-nWOE= z<2WNZ(aAElYDrnX(fTHmg_L2suhX(};w`1~cyo@t^pxl9RP)A6v{B_8wi|9&=^QQ> z!HaK`+fCG;bK1Usm{!Pj*k4ACdT72Oo{_h|UnL__57BlOlJeZAiTom{@~`=K2MN6Y zgZ#ULd^jM-{$KL%_$`6t>4T#OM|r=8xyy32ki%44TF6lzGUVud0puu+8FF;!0CJQ^ z4mo5@3pvU=h8%H$9;VyULXWr{=HAQELXWsWkGMdOxImA%0NK+A8P(7uF3=+`up=(8 zBQCHbEU+Ukup=(8BQCHbF0dmmup=(8BQ8g&zqCim!?eJWfCE8C`NFhpM_kyBxUd~@ zVLRf&cEpA4hztA(3y{(Hze-phRQrgo&lufd_#sX&^EFk0TDp zjvc^Z2N~#41Uox$!hi$FOFukI0Du;dKTMTYrajDcJUmT7d-GrO$B!jQA9jQj;DNw_ zvkPo6;N%4D{|L}QH#i9(1dxXcMMBvTe*y$$2eMNkPz2=vZ=r*(bOJ!fJjRCn{fNnN zkHH|nA0PRZ$9_K|aNJJ^RcdKsW$D9D{Mp zJO7x%a6b6PIjhEv-VTJ$hsbBi!@RY}Kj~s-N6JUU_Lcs_&HZ}y57C5Q& zPk}fHVkZIt3||;41P=cbh-3cvZ!B>TLQeqVhd1EBc@y@3@dlh7`MY_3<&8g`b~^5q z6NXm^6bVMcVQ}CH@sDFUd^(=MED#tQFjkOI;PG}G%MaiDKkRb&h&}<9V=e-U-ybl? z1`Hey{oQfDa?u}0@Q%6XaEfpO7!U|BW?&FjU>X4bM{)cY(G&_numcm9<2a7F=D)PZ z3B&0zx3Ix}e~KJ;3vk%(-^>R7bmH&0Yfcza4|*#U2qeH!5cofi<)on%m=CdY0Nw$* z$uTU)-1Gmi%LyYa5&~v}K-t-0wD2E7kGlxy(lFM)ov{7OQPksZI$^AZz+qqnf)x%N zu>9ZPIcdQC1s(t;l9d&Sq=o~px7I6;It=B^)tkGYEt$pMBQ9W4G;p!?M+%VSs{?*ia}03_LiH>`>bOJ+>1@a3~ZG=3s>)fK$`QvHggeZ2zF$P8iXVP%sBO z3<}H_j)6GtQeYX%&i1!1{nfGjFn$2WC_MQ&=aB@xOreV_5z();eLR zKjy<9@{juvcvK^fK7;V9(E4{@MmXlj!*@R?39mp{s)YZ$7eArbZe>~0AraKjlb(rIw zR=m>M6%YHPJ@$uJw>?fj4@vY?gbkDM?nGaW2wAg4RQ*=6Gd1JCSmnIa#{P|`W@g`H zyNy{-qXd)HiE!vM>C>g9g@(?(-p(l30!)Dqgx<~GlGN(Ys3N-5Z{}lB0LSKR0k2R}t>5bEn_w9*TF_bt&J+TMQ+O_+*nz8XP6)S2KmlqQFeugt2L%#Jz`u zFKXg5T}hzld)@X8)%7QjRVATUNcmFvcKo#;a`X|8%~nLZgptvIs4Fa4P1DI%5Opdw ziHS`9O2VwIhbrZ>d4bsk0AIh2Zvl2|N4fawe z!k({h4y)N#i!fD*VBHyt3dQzs>XsO+O0H2%8D|rb+85fH^6Q*%DY&psa$|FLbo|X{ z87>J&byM?KmqG{X>-yQw4k&nLmvG$8FJ<-E2ixFSIt;0v8!O>@@}+J=Hl-k{?nX-g zfZ_1XPysz)zwpNoIK7P8du z$~H*FwbSH=&L;|tKC$EO*6G|6&6BaP{-}w3JSCR81-6@{F_Gpz@}(zutA& zsZn+Q-4S2XPL{LPr^n$84d?blo1bzwH^q6lao4}a+Rw+j65=(^lcFw0)*@Jj!wR@5o3x=8-ED>lPjy;-=oTZ)N zrnst@SQ0y{!EDRxZjZXAaGF0$2!7PraEtA9+2ZOaV$*pTBW~f-oLC`vzO{a~yEbX$ zxsmcf3hThyr3PI^QS=~*+wZ=L;}H(#55A!LFbO(+MOA$# z((TFJ4fjqts`y0t)8?W0IWe)MfF!Zf4zuBQpG)`x4p>72`U7n;URFGYx&FRy^i}Pj z2B*40=2k}WG@xDTcaududrGE}(i{Kq^%ZO|L^`gC{xK)0Ox2eg*VR z8&zPd!_y6Zo!#2;`+FkX4@jsZLpt#{q}0@@v&e<4Y`zi)Iuy#@dhptbogjgj^EZtN zbikWzzpm?nG(1 z_vce{i68PW&8(_ll=l*glF)3Vmyxn`q|*yeda9K|?=YEPZ+{imi|9 z#%ufdLIRDnhE!0=ax>=rx4JqGw0G;A+glZ%anjrgO-HQ?HTpa$tdDsX`p(>v{N8Uf z{IyymSG=eoKJJ&yE`7xFBn;#dO}Hpgq_l2*$Cq&7X~7N15`p!6)N7+gBSzC`r0Qw35BZ}AR>8cA}}dj{TMblN!g(^;C>g%V@tTxK+RZyoZgkf@->BvV={ z<84t|YW&A471=$EJF@ww%Op~vObz;J9d@h{Gf%sJ^ELz-NC(x|Bth@)naZIGrRp{e zBG2?vFm{R>TBp59x@F0adT;^18^N0Y4EW5( z99nLB&N#(NTZb$Kv%qernNtwg+N<2mJI(nd(9WDmBx?-_UEqgF)n?idgGn z#Nafw?QRZr_!oFG)0M*NL`IBD?^vC@3f05E3gF&W$v?fvXIyj5tyn1DqNC|Nw%Hqe z5u?V?&~D>}BF5-*vIJ~6eCqnhB4^rr-L}n*Hx)1QlE(NFM2j7@5lZ&f#2pU9i{$`%?|B(L3^sf zDI%0?zB~0IU(W(f^v>DHMVgYy3MY_l)6-9W(IgziSR$bfLNZh`HyiKCjPbncxuwcf zStKYE{LG0eOZ`TyU!gv~D<@HQCP`D7FP&%R7I9a~-3aYvKIzd{UhE5jUnQUWkoT}Q z*?J~wP@}{$&HJc6yR4jEa`I{>XZT3js0UBe4}YJw0e^#C`6i_J>{~>pnj<8=7{N9) zuX`%SpWMO{MX;rIUZ)wK7f#NMGAdExoO#UzVOB)-Ds+<^=HaTv9%^4J<% zJ(jClU&e;C2&GL2nS`ErhRz7+s7cw(J|}({=AEvlPBE^eWlO2qgdy>s`~B&fwzJ_` ztu{z?(&=%G{nuD5(;uuKG!J?}7B&(-7%7T#lx~+3?0xp7v>>Mus(6LOFe19;ZwIcB z?W42`VG4ZP8SFL9-G-7JSs`j+b$fe-4Xs*WV|@!-Z1>z*?Ff%z^KPEiFNh8;SiA0% zmh(Fg*|$iCK3EB@<;)RyOxlnTfSsnc9oNr(*_n*n{nZdGhgT zlScAeV~E>lo!wk|3ob9t5|VAmbGx3#RX$r2fyueQKwqI2bOqctQ_>~47x1j8*(S}U zZ)(%e)!kD01wTzl#+2TxCYM{{h0Y2hPNC5~ByNtvhFiP%?<9O5{%c0i;fFx~JRv^# zYUuy}lU#?1H9yG-`d_8Ez>lxv|8_c!gdBdu^pDT(wWx^)Q5F+c0n_PxjN&biQ*Ws+ za7a=Fz#RIfcJQR zqS=aM#`>g!mC-aFI|f@{Vl-POBEH>{zRuyV zwQQ<)6M{GAuByq{?~~RTx8Euvgx}54V;PWky^UbCcj9rQkJF;wc+JGcEHZ4*JqH|< ztk`cBW*L%-r7aFw*(LYDR&fzIRo}K#t*XDx)@cp#fWA5DNfZzuDx7m|)(XfGO8M@% zYs6nx9Ji@g_Nr#jFNQf1Xrn!~hCGVqqWDo(?lJTJF`#_)Wau|8j1r4zUTg{6EhLU0w*2TAb>**RsdP`*a zw}>k7S7djK`qb_g#s{}ySTd8jqGdmGyu3DS&#y6MM`81V+g3rcWzBui-RkA_%Ge7@ zX!57Yy}czbwv4`3F4zvelcTiXBFYn8m1&%}K$d;d%&!v-01hV6RPF2#cw&|taIWe5 zdhZ3H7dMP@oSYIC?PrU*_PH)O53s5UrGyvkKqN~S zo34%qPQrU(YQ60s;w2)b!~%>UGbRfzTZvM2w)d&i#Hop2Ez)d2hUfip1v3>K&OI?# zzFW&0HgKxB;{J3RF z7{)uvn5XU&x3RcTJvsBayQxx14NVPtp6gm%mpeJf|HAs^G?Hhb>>ZyiK7JH9%4@OM zDp4N6uO5BN_c7NzMxzyf>SvpfTAl|U+E8RqjwVb&AN}as^Yld>=58T*aaW5j54_ap zCX!798iCaHXt{XlR2Q4 zVT3EBW)<358`tqCbozWxd2o(Cqij@r z8}uk?tbygG!H40z0#z72efonYIW+`Mw7_IVL&t^E3i@bei?Z0NzSO5(P4SY3388gv zsV1=ba=)PKTmvNST9Z~qG3z-{<6$>>QB_lPuZOWY#m2hda(}ZY&R$^EH?_ADEFgK0 zeVc(P`BywFL>$W5VtA4)L{dAun-wLLgw_ho-R{rD&5-fYdBr!-(>J4Et$%8mEGe6R z#`G+P-flzWYnc-bC;W=IF6?|a>a^@>pO7aM8#P*YywY0W)|x!GXsPJ;c}zZ%Ehb5o zY^W;ehsY?SF3Nn?xWkhib^42s^rJ=`A>uBF{YYN=^n@5?=?rLh>p{#;%>) z*Tqp`QAIhn=#$Hh>C2VzxjAC+jD*Q+ zw5>*=oSc}kuR@~IA6RgZYhpijh<}GeEhp5y1v3qhJ6quw0{Og;`to~!g(5bPi0?x zz4qn9!(MC9W`H$=+SfH631yS2lnON0JU9{~!Y{Js)C~tI1}&^WC6vN-W=Na$nWi%w z1twn-)E-QS4n^X0K80dQiUYHXcaYzNnd%vqNOZD$h#c%x5-rN^puajwrDSlB5nv$g zoiEdnMc13A-yFSpswd$pfljRD%r*L1w#}iMfJJP?h~gZW3_{rLm|6Ddba1z9@{E+8 zqV_oU_uBfibl1P2N5W+n5bQqh`Y@{}r z&q5>kgW0P9lWJZ@8u5+}H43^X-i#w^6qvf8N|h&<@1D8mGuPFCoy;_W=aqQQ%go{f z>gq)Y5_!d3A?1DDi;^!e*m}r6W>RC6^qb>twTH81AT;y@$|b%~>C_fR+L=#u>ZZX_ zA!nv_>I8iwAt5{i7W9ZI%+r^yPwHN|@-hOHTUR}# z#~}8z`N;oTz4)sd(FIl|tiE^yemala34E&UPFe9+tlx@~MF!(KtyoKZ4m*d^A>_-O zc9?6A*VipK=n}uW6!O(Tj(~M6G<7V$hd_<>Vsrt=>Z>!7f`UzaR9{ThU~B@TY6dA| zg5B+toXiw{3e>Yc!n+C_?GnwUwtRsqw|}EvDRrQ|s^7t6PMneePwU5RQ)Csju;|`C zXR3sr^D8Tm5$>Z8C-_aL;7O6p!{OR2YF=v2CrYn8Zf?|_aer&7y*rp!Fcmn^cYkf4 zs{2!9Pw=A;*B`2w$V$lC2-LA$lQ<=l5yk&b@KJ|=DjoOx_?w-Lc|r9Zs+S;gN~lmw z>)+HE$1WIc_sucCjc?S^M&B2WzS3AT$i15@A&)-*opJc~MuQWZL5g5*;j@zyzf;-6 zS!xCwd?M`@oe$*5C5_rLKMJnBHNFhIvpZn^C1cE`&lhTo21sdU-*n>5wU6PIYi^_8 zHCOUrOWZ5!u2yLJRXP$( zG&vvoR0@kpW$@M8A+(GIaaX-)Se_SI7v`m#9_4iXDU{kzR-P^1Y^Nz643WG#5Rtl9 z=Qb3edh??AyOR1I-=)Yq!s%0*Rs04WO1F8x~jlxl|jC|;A4*76{-O%hC;{N0UnpT0+esY3>Z^e3ER;Se6Frq ziTPCWMQD7r>HJkSp8(>@vqxl|IEtcU?K3c(+K~wmB;bjvA(- z8g1$%tf<9!?#--rCu((VrGAU9^02ejZ3_REmH57QjwB*jYAZ8QD^HXmZ6#_WHD`Z$ zEogXuBFD(xW5sQ|fjL>it$m^U;krLwy>VRkcF3#wERXi}m-EXD!cnfdU+x-md4Rpg zif*`$l?HXes<|!8lW+7-i0`$nL@i38LHEDam3`UE=o{`UP_cRluiN+B9_#hoT&H+l zP0wQe!UGfeQ0YDAwnX(DWx)uQt=1-*=?abK0NZCQ_Ks@`0l%`LxL~r*sU68 zB-Z^`c$n-E^tw@8Q5_(20 zk|)=zqCGhF$}_R=e#ugMK|eJu$w5)L3GecBSB}*^`;_g{mZ-#1W+BA9_BXB#nIwHB zALkqFV(~>f*W};Bp0$~M(F>Dqk_o{Zx4O@hG*=*{jz*$fqr0Xzc=z|qtE=~^oqYFJ zL3=6Pq=V(%#oSxD<(XBB{ZoP)9RmeU;-J;kfzK*$Crt3jjFiK~RFJY{T+t4i~yye$(x-yn>(+&J`I6Fu|>b}#y<+#eky>oH&guR zBM&Srlh_p7Ewj@(TYj0qacY21F+!H%M$Z%C&!NhuS&`TL<)q;;DJ>(f@%zwbxL`3s z-1+5C?=fQEhisbGsm?5aV@i}5f4yF}M8mHImzuGACigO6F;X_6QO+fC#V)KHZ3{2K zMz*bOO)2I;rGjna!-y7~wZWl0Bw_&!8=`nCD_Og*ie%b0ShSY?MTtIFfnsC2kx`MU zAOYFac%u!XBiF)iGiGg8fz<~5Zxk(>!aXSLXx+raJbEC;xKDngcwEVg6uN#dIA!y6 zbfY98J#v1zeVFlDac+V_K~%0tOK?J4XuTf?hBV<_vL%Vnn%iT3svxkE!s_K!=m!z& z^k&M-Q81HftH)<;)nv(R_!6&QerLebOSqWdKv*Yd=gR(8MD!#1=%ssXX!jJiAUpB| zowf}t<{V|^4fy2l#O1F$BRmhuVIC1wIN`kEDYJ@VmY4BD{Q^ERY)i7q$Vo?@2H|z^ zJr*7y_BQ4tO2qhjmHc9au@~W0az5Ut*wF;S4`I$W2$!6*j6T9$%(!&da67y>gloN; z=XCGnc6AL^?qZ03{L-C(y1ua`k%%#c;v_fE9M^0@CrcAzO(R%D?uT4oFw3)awTh!< zFLkbB#8Q|4Cc504o0C)8>|Gv`rfBlGl1I;Aphkc!*E?t6y0`=iKNKY+$&_}6JURqA=rWHO2fa%RmQ{Sd9-!{MQ{S z?=b0aPBDGC8MV;C_oCS6`iPQQKL&n@>f17-2ZUKg+|M3+cxhSlcy;3cc9(A8<8({tgG1LYlEv}whrEp=`ezSy;(jaRRJa^O;QxYA~? ztn^T;7dKKgVKZNQuV+X4jqbF3qG@Lgdfg3JE)HqGQE%qlpIa#Q3G6rGpjW~Wz;yGA?@9D>DRXl3MA?At$2DXFgTJ|_`vhm>ZnJ-GL4U( z$h~cHWn)Q;3q55?6?)arS15T+;*9Y1x388SZR5C*P112RF&HS`GP#o6{$4~|mW)vL z?8M~}XxyydA1->wFIu^l&tlU)c?Hh-+feW>Z)1NWl@-lH;imV)V zTDtR!N{s_Y@>A!=!{8euSq{0M*L?{z@nu8^)WPY z!8T4Y(FNJoxW8b1Ayd_gFX(5`*S`$p9(td| zNm6HLWOey09jDC`1Tye>ypvT&hsw*CqCsi))}1;$t+GUlzNJuYCs5f6T0KYgVdn0< zawcC(vD~|sL|Vz~*^0Ivuv#j(nViUuqJ<>Ww1#57Oy(zJ1VVJ`*)ni*y=!9Hiu^chYi zj4)^IGpnZ)+=oaIQW~ZClqEDDoz7FCbTwoX0(;k_f<+6O0=jBq3-cU0h!SFh#74pi zM|wdEk4+0EcL*u?D?j_Pykd&uO_ooh!ln_8yG-`hg$~*y>mE z!ZT74RHEk!WOF4MlKah#qpMQe4U*TK_w`FZuZb@zu(&f0ae9-p)kdtnRoU{}Ho2y5 zzaQxF&E9s3H=?C6by3+W-rY;#{iXLTA84MWOkG;c+#K7v9G8NrQ=w`*Z)luRBnVrC zHm5e@jJ#o~?X8*!t#Z2_o+h|F?Qnj%oMAYLUt8?nYjHfzi*Owdzp^TaB2BF4=uf93 zI@@lv2bL5{Mw-`?QaEr}6+}HYW~XqRe);lEC{3itHFk~yyx}`Zv~wvh7k7JV95J%{ zOCHv`ocj=|SnI_VU59F|BZm~_+@56E;~s_L4`ZD#Uu+5`cwm*iiR|Pj5jWNVSS8jriiO`^&G}0)fo$yf@|q{|Hs{12i3Li_rnkZ zB)GdE_m-kJ8DY5!pl4|`zoUC&wz zK1$8Ak*gA}k2qq}x8(oG?Mgv6^NO~&tR-cRA~34Nx3W<0EX_|cw3DB&i+?Bn19WkW zl($oBz?7p|r0C{s3RH%BK-Cs{`m87u+#T>!>|FQ!2}U8>0c26MUIIkZMY(zECL5u{ zw?GVKp;ImqSC#N;kdXR(1g;UJUZTfUjV0B=1^kd+W&{Qtms&dAM z8`UV-m2)8)q_kpdE5e_&r@*?TH#VGDdvKiPYC{#R8&Yi##A3h2)Bu)pLhhJWC=bW= zyP(;YjIA;2)gsDk&|{r%jQyv_Bp(W&iLynPe4)*1Hpt458BG0haUGVrYu^tK%i~yl z!OV!Gc5sRWLlrdb6E4hPlyM4!1$HR$7CFdRkADEBnA`Oirx`4Y=^0a&=~lOiOBaWq!SS)9;>__L563JqhQXJRs_}Oi?n{El&i-7C#Uo5t`--Fx)g< z5EIYe>@JO!UK1~#tJW4LLNhmD8N+LbW1H(pCG}fk3*@QDV#$Af%k`8LbCG&%4p5aVGeDfmp3@d@N{AX9I$x1fpqf@B>l71q%RVnVG3y2kzE z##YT@@92Goac^)9{6QjrHkc=yN!`9O57cp8kYy|gZi}la0;}<)NBb!A$eXV(%B9@_ z1RS~b$hGxIkoCyj;`ThKh>O)R$XhCylOhgQZx>uptaD*y=E#XY13$Ecw`X8VPgcl{VbP6 zYRPE#PeY9Q>mml{3&;%OXpS>rwiD_kKvdyQ^>w&AYhXiX%2zDSCgmRK6=a=y+VPuH zvSD*OrY2Spe*_MY)cg%Auyq*0BeOx?sYY&$bfvkLXGQkIX0&j}n0I%ymE^eA`aReN z@n?}LdM@}DU@s8#W4pg%k0_;o8ZpoOhN838p1P85n|Zqv0yeoBVPJ~Et=lwm0_xIM zm)e^6RQXFq^GluCF7*yRiPoo)<)SrCl0sdh94HS9p}GWQd{$*NdVe=Qu+9p|l(N1m z3e4k27Rc9e!?t`;jj2K#ndk7wmSJ65&_u_5toBzfZE}ixqJl(xo2U_=8F_B;#8I~| zYXq~Jykvn`c?G1PgYM;t79VtE_@xqMD1p#IBnt$b+93{4N5_5Rdcn!8_rt8!PK_}o zs^vmUC9i9o&-Unx^321~+XjP(+KR?`Den3rJ`At(`$FO!zAflrL?Y9ZO6rNe7fTk3 zwKYShI(NHY4``T=qQx?RANC;*tDFSu{vyvi@9aGe%X=^Ixw@~E(Ij!ILEfi$VSVKtOKl=xFP}K}Tm|=4k4qPitUfMfc~*N4kI8a|bMFvez?kbf5!PoEgzE zFdMV88S3i;k4_K3!~!rdVlt*T0MP3jvH|FgnAzD4003rVR>nX29sjj$3Ginj>p#L* znAzx={w=wVkrneH+H8p+ug4o|K%C` zyO1!>UY=qsz;_kAu2`BepfjXfmp+!%gZbu3_plx5L{WT{0!Ky%P6yt2XmX;xvG+o+ z?FISuCK2FN%@Cgy)%#eKVj9lvjcIE@rXwJE>&l~goWEu1XpOJJzTbV`&i=AKCRLR} z!EW-EX9{;R#c=hqLWWbTAB#*yyk5^z3RaT3caqHuYLUcU!Mw5_=lvBS2yY^o(7&)jlXm`8DYWa6NCJUAx*=yAQb>FIkDeBOe5G|O^P(^eR}_nZC0-L#9( z!{)S2^xebb<3&MqpR3P)cRwe#7`{kA`Q8lDZsl^=ksW!2|xenF6 z$`j`*c#Y3``G~?oyE1(KKVq@>M6|gFdY7U?IZyRzYGY0g z?dXnX5PIq;&+6={#9nCapvQd1`B0Rgy`aL~^SB^4wt|=-s@JwXfi+`Eh-5QZ^`vBO zQ=}0?Hfn0xBJS5H5Azg-Mi&3p<^d0nM7)zT(ygI#zW02IXY+V3K>2E2#b%w|BIo%% z22om_p7;yhFH>rKznWetGE9}>lg;&)ewX&QO^*`|E2{Hsf&t-f_a6)6o{~_@A5i*LS4@9lL$X)J;QQq z)%_&Ym=u+?WZ7V-!R_*@>2$E@{u$7Aes@$4{p!_HyJ>NqGJ1~w7ScEvlFm5FTUOB+ zsl?r-aQv<}DRQ5#@K`fW84+&uIM?<|?eX<&E|l->XSM`D?BWbJY(ha{Eh6ZsFI;Fj z=j%M`itSfc*E#PAwi-Eq4uSpsQ;u<~XTd`+6x)Tk*xc=sHaw-oaLFXunV`aS7!$#G z@x?89duD}$_rZ9SIH4EGhJurVA6SSo6jPoSh3VO9Io{Q^hSST_ptd$w@k%Tk3HJ4k z+&7|nMnm;k+4z}XaNsxg1xf=OcH}Xa`co(Zn=_ZTeZ#y9z&7YJu0w_ovP5cU@>^ws z*A;@Eo#J!vcPMsG9?+P2CCJ3YsMfotzx{X(B~OADvO31es{hKo&OkNl1~5YMzXD1z>$bo`>U=FS&d+ZIr|H56rmSpSYj5B{anXkH`nf}k^6A1 z4BP0k`c$`orG?}~J?K}Mib14j}(Fu%IJa z-qkaT6dgG>#yF;0RX3l|Jgx?{gB+}a{^i{!1}ZH&h!_BIE$BW2+W38{aPv&W+PK>&wWwo>xlb0)_VISqk$#y0Az!-V`tOOZO5#=MjaXhUxsKLz-qG z^QGx&NTcN1qB-{#$`^;cNLxojLcH*FO-s`h(E}(NtS^Wa)|5opcJ}s7J-P=~eRzX% zyh1YFt|(s?nTsT7Cl~m|iHr;c>O=&Ecz={NMD25Jakw8KQrDT;sBy~1Y8o9)kJ0z| zOw}1wvX2eSF6j+(mLh^l1)V9IJ#NRI?ntYrN=Oqgo2{l=Is^K?pT=JzE5%ZQUmAWm zho&uj@Zj@14Iy5J)NBamrj(Iu_dBJ}@H;g`x5f)vM1+1EWL8{^BCp210KSWAIZH(M zIlndVl>AU9_|)|J*wV)pvL2q<4R<*%GOjGcc+dYdV@0y$D;#va2bmC@v0<~x2f$yx z0p~%mW&b6?a@;Ml5g`gIB*mN*EkMyj5M?2Xt=g-@>1Kjh)qHv_{WO52afsA%iHhxA zX6UYSZ+=nQEU4_f(=~SpHez0rv(&lI@F3p8Is7E3h0U%kM3QL?gh)IxUM0f2EL72^ z&>loC4b&H&3B+!f_~z3J_-ha*$Tp@iA6#6Plr!#9fux0)Y2jT6`4~t?Fs5%q6rTG> z39BUyV-WGD`D9SwFULgCrVzv=yZZ#=+U8b+V(E*t*HYGdR5qRdx<{6Mj`F;>gXnB$ zyh44OonmS0K51dmk3LdN&T=Nco`rCR+~~Wwho-EWh?>EdUJsgauOlNHEKzK&;?#`y z@RWU@X*QGX!W?M)*=~a9O#-DgIHP>Yye`WnTs^Pd0TZA0q4o9PE8I!zw(NRq`Y{h3 z)QC-yB}|}xfl}fE6-9J-mp>TNN@|uOGo4gLQYnff<7XH>mRB2}>qDQmcVaF|bJAe9 ze6dwQrm(a5h{ z%s#dEKSH~}zYmS?9POB3M%vw76b>k7>Jpw*8)=m|^pv*;GUmuSiZ&=j;%_dk62r z;Mo#xmd##P@hB(T1cXriG1Xl*4~?tkjww{Itzs9aP5{TKGsHD*X0_d1*m$>IA35oE zZ|rWbG%XXB8?9nd*GKn&MFAeXbv3Br7Lp4dKK4{&ZC`npXgoj3+FoA2Kx(ARN$E}oD80LAXQZDm& zByhgFHq24RUDqxEaBEyyv{)r%uX`Y4P-cr(<)}oQukW>=52k|}p$E>3Migqg0wBWi zxF($Pd3U_s6hVc3LC+4I;NaaTf6O@$!<{46Mwpl3%;={he8lzOr3^kb3Nd3SkOOiY zdeR_hh_24!=GexK5)shSZY#U#GdAMZTA(4^te{Kqg5)V`X${NW*bwoOyb7UzT{G-uHXn z8qT$ORV2MVZRWF*`<(i!w&g?EKa@4ICuK57R*}TL-hwF&Lz;WVP2Oj`UWlm1M_aGd zW_@Lzw%j!+)`6>^uwr>IMASK5Y?Bw@ZHz%aJ%}yf!?GL;lHmYn{jNBLcFDBqP1y&| zTU(&%S$*aY!6c{O_Ek(Xzw>$f(3hcuoAqAadGDa*nkLIC> zIY&<3>OiUO^W(Ur9RPMDmXUG7N9l{F(4ZT}1v18td661!9ecXA;o~X9KyBRhOYH_a z)j3VmgUFBvwA{J!+OgGh{xv@B{bTRk%`9n?wy`_CJm!H{!#(@=pPb-OR_#PIb__OH zb@1RWTk@zDq>0+!v7KKJU~D^zedTK%0|ZW=9c1=4Z_)3jc0pX>)6b-6=NvO;tXr%X1v3#c0VElr>_i*n12c0YazEO? zTAU?>PlIkKlC3XY1?&tj$G9i1H0$`+?q60(1k^LQSc#ge`xSzAi_J!sRiUHmnl7WU z;d=A6oS5v!%4ma5VDPzM1h_VQ7mK60?TPF-17oNG-clvr6euUUc#=`Y86zY=<|>rEmgTW+ zai+|cHr8D9C@*%51Ch=<|7dB1m;LUSS~U^FW)J^3%nz;?OG|^6Lh+@fV~}a^T#hv% zx=?GY{w(GEED7iMD0^V^TIR|ERwcd-*Q+j_9g;JhRw@4MIFU`DIa=g)VDLrRhc8%l z!g*lYhOt!}JW_!`ptCxKWz2#N0#on18yo@lVED(5GQm0~SUL+3j0++{K8bNZ$yKmq z`1GezN42b(FGBH=b7LjVJ&}k<%VXUGe+Z|NZPC;(?$#t*YflyKSm2vWjCI8YwK_ox z&eC97pm53-3I~dNyn;wYQ8p&>CD3<~JgrN7mgJ4ejG&sRLmAo$qWt1zlx%u5eAzV= z7Oc9ltfm>1>9~`vw+y*H?#$duX)0;d&E{nf2!d9k!McH5+e)Z}Mr#G3+sY4GZYa4X zM#u`Dj_SbGNL<)kFO@A7x0+%lp_&4=(k2=<8n2^7*u@KE0gE6y#AlK6u?s66qH>9l z-vYWQ)ERnMaH`GYC{{nIY?6cL=|XJ#ygG@bADhB*nGMHtLR3=wfTg}t6l;dbG2Bx!P!j7G9!sCJ@x$r~ew0U@jLcIoA{ zuK`?(?dP37(!qwHm8838>_Y>JC3Ob_K?VkJO$P&n(js(=st;m(Bb6Mt_569_?qC~* zA2w33YcxN7YYmrDpwFT5$%8B!0g0^(s!fOn;c}=CYI&d@F12sy`_>}K!RZSWPB~fb z4rT6OHHm$2)V;LjHyg>GZz-D@ZQ|n#>)~Ps`#>4#w!&Ra7`ez}@xrwsI)4VaVIx(k z1o<|niBMRXqq0R5Rtl;aI*gPMICIW7i$$6%Kuj}9t^|t139ec6TQ+4{2Qbes2FR{= z#`_}mG}!s+|FYf$P+;heKwbFfgV$Urg?@12zf$jxuAMI{p%nu+zLw3up!`Uyi^SJ- z;B0Bf-`nLpd_Wx-_%ogk`w_$??aKJM^f7=8=HnMBIBqQd#4JLiOlXc-W|JiF!5K;o z7Hvb=Yu8^>5J(CAEqZ8e;y9+cM(OOj(McRJxYrym1f)G?sP#~(#iQy>(DQ2aWL`?y(uE`8pTIz7j*Jm55whw;=R~93$%h!LPjaf9egtBWQgIxC zvYD2}+I`cwYq+5LDrdNnsNEry#u3xCiq~d4Z48gjdg$yk*{F@dVW(cX++78PIF~w| z;Nx6j;~P`_fXb<=ay_jc*bE--3Cr%zHVIj3D*~PwdQ)>V^0ijqS=g4$UD&Tq0WpNt z9HN8?5@Vk&D(lo`Byd9D08yJ=1HMwMOkmcY=D%(=kDO#G*kq2nie+Mz z=p=tmpx>_GV;MwSr1$w^ar?uh)t)+29uyA^-oiQ8VEdJ!H-)*UVY`DyrqUm(sh^AI zj=U^B#{$nPX-JOSX0VR~IstGLUwA}y$s?L~UdQaPGBO`r0$u{}D3M#XTaR> zNVPwv#Kgux%ft>0GXn-<0b|7ew@(Sc`qwG_li4Hxnux%}!URk$VrK--ixHT8%f`&W z2Fw^{VrBu3?vK@fpNR0kWGgYSGyHW*e>PJ6oeB7zA8x0hi7`@^UC*-%;|gyc9348-w0S3ku@x zVa{CN93Kud^AAv8RNNhP#IHRbta#OT#XJ%{+1!!IOyoz-9>liBg2hH3b~EdeV<*>= zq%pnFWMXb_B<# z&mBID1{D zQQ$kx@R4G=K6Dp!qo21uU9+BhyUg^%j|aDV7sYdPo8IpR+;#l$Ycv78lbCu$z%NWsy3qH#_4li1)6v3m>m!3Qn(oas8=zmjMI^bJncGy_-)R-5)gH zPaig$HBNdkINi<}lh_wNrv!y^=2vyg*Tb`{7|2_Td_3YoZ28VntU4J$Zm<6HT7_^9 zhwS1re=?b}svRbI$zT$>_e9L?v~rxge`rrx{eEyQKjIJJ-P>dM4V7AW3SY#F;4RZI z9Z;8QcKidL#x%*B@Xuv0pD{+~Q24B|EsJYcKc*~LE_p+(j3^@)zD5;v#IPjuuJ&${ z@hdKoU02rM43mOOSi}j{Eq;VPhO;|iJ`M2}kzWL0&sjq~=#;X9d+pvrNLziF9_vKE zei^N3f4WPp5NZg(={9nYxvpofp|xc_cp$VDJJw0gCN{r#yd(k zMq`u76oFxx!hbQ}^_$|Dr1pNyOPZI_L{ld<6YDsnRj1&M=Xi`mYdb&yjJ44$D1CyH z^X0mt?YaB;d=V~PjvnL1`~h6Uu^bpk&^LOg<~_Y~7En2hEA8_>x*4vcD9ve&BlwcW zC)Fy(FdxgLBT&UKgFD|K}Mso!-MU%+>_NQGF&nLNik-J`lw4m0v#d?vTj(K*x5ax`F!Bov z9#OQ;9w0?$7uJezYnNTdbM*w)>*MaCF2!?9+*M?j?3dXj38(DzniFt23?0fWhE+1l zlFYONgCh*7BtLNZc-N+}esR!nJLo&PiO&_fT;n+O)`*^Wm9Un3YeE^wOafou+1_IV zd6dQpXegmTMTeQ4w(_A~dgAEf*sMNjPuwWU#lqVZ+m9q^Bf758$6EwlFzRt!;L@^f zYhL2EKaVy8&6Vhg)7{i%WP$lCudYTPPp1sO+HYi_36!o*1LX1iYp(f^NsDaSyzYl9 z)wxQkBG%7saC%4t0DVXB3hFVoDTbi@Or@9;1#v1!|XK?Br5^0DwDb2xQ zu$cvn@Lj>K;` zT1t5k8NVEm=I4B6VJ(pY0$!_g8ftcIH-CPH9^v=MKYs6FGV7emhs4k2{goi?K~}it z1*NTA#iuSh`$5gu(Mkr)?6b>~zjNG;xB)clnp)RLqRW9>#<#m=&ldIOZI%LarNDP% zqk?4sq_x>p<#o7u5<^3iF;AGBFvYAw&21zMe=eXc&wZF#BGf7GvBn+E+OR^lNo8VV zV@n}JUwrMb?CHR3Hl=L!VBb5l0o2W5~(*R&Vn2R6_p(rr&H2Y1eUFy1qvQCyGF1P zv0o~eS^j84AWa(;@G72@q*VO-ReU)N>J=8qMdS2ZCxiTOh?$2-I`jf+<#+8#%Pn1# zNL-!Uca>lLJy)=dP?}IUXZ77;R&=C@by9A&&~VdgTQiOX|GW@xP!8F2kn9-k$M8d{ zVsI|*Iqhg_iNNbsi%+5+;~5P1!;D3#);Ot7d5ZN7vryzU_^c{AneEV;NobBa(SoCN zML~*n?r||g_{mwQ3#FFu{0y0kNDfEzh#tC8Xmv7-Q{3X!&6l;TNr(D*u;kHf$FIG0 zef`&?MxQ4p3~TNsap_I_a2uZrm9b-txPy;q13oN^`|1fyI7!7bzdAl+ zC?+n+_Q->_W>$O}>*ex;pthX%7%USfQ9SbX0UQ;eBF3zi7)5WPlo*gByESzs$+%Zz z9Xyg6P#O5Bty1PPyKTn~8xjx|9NdX0E@{mZSyOzfPf&5rnCeRH452)*cag}mQ&CAt zKD>atCREpJ$>Cm!^-*IM^pXv9sc7=-^(ZwbqSF>+rK0_cm0jw>KTY=VBVpeB-s#F} z`3EBR_;n{?k_;e_^YmTw&`OE>wxppn1j}3-;g^1oLgR^|YmNPre#lP+X`L8#^`g-l zC2Q2?*=*fYb>4nxN7|xx;iV)lbvEA3lg-3`T%joAU5{MPbEdf@^w=5hkPWG4>ZmXQq zE?Ox|?Trp1Rg{4qN8ui`9nHl$oZ!RrKOpQ~J#eA9x;|>at~^Jkl`MX?`;|6ver5_; zu-{!%gAoUu_2OSv1tqdN7${-^#?92FrEK>kvg;bGUL< z(F{lRIi)6i#}AR7R8~V`PS$nrJ~7KoPW4yQW2{g#&aed& zR4u^m-c$kxCJDCW5U7NTx=g3}P5K8N@RpyMIjLMHw?yQFd{h2b(0*EVa!>pisQTzR{w>A&Ff@c#O`hAotNWaM+mIqa--Vp?2vNaceHZDL2x$( zx{Coq>EdY6Ul2e0ZVO4oRR~b<)xA(Ohjb|<^2hZxn9185=h0H0t?zMqdw)#sVyaow z$io)5r`*T7{RCPwx(1+YV>%OkzkujW)!JS+cAeHgDLadyEC$|fty#}iCghZ+383s!V_bN>cK!mDnu?1iQ1X}= zTCx`f_ZXLfyj)7{pp#e$n4ZB3Snx*x#NUJV%N%}$W)IBN3;t1n(iu<7YS-+-)I1(I1IKwdFAYb-72ElIw6;K>XG3>ubSCRyhsX zJ)njfk@>}hAZC}OOieZTw5c3 zq*W#e8>**++1`B@22^MEQH!oDm>)}!O^FR^<1igT5~YT)b~FK5~^hr*h*=iewYqF0pZ~K4!yBd3?|1a0$~=S zpFa&1$k3Ss;~o$ts+B8D2i4FQmdrVPmU02TA<8`1ufaMurCLyEmF8?96-v6v?*ADl zh>7`9vT~jzM^Nr_zoP_#B#0JvFsZIaRfs>#Wnyp9BHaz``0{xfXv@+0KUqxqL&O#b7XVMBj0zHFr8{ z4d%i$ke5g!zR+>$gGoW;H*A1?k3aNbt%0-!o0+=#NiFySyH%*fJ`SN!s6d(l>hm-P zH8uiGaEMyV%^X9c+^^ES)V`F>C0ybH@jhMq>CY{Mh*Ggb9Nbt`$g2cnC34@_u--K# z_w&EozIIu2*nc#Ej|d1P{q%LCm+;Ab$a29f+U=_~^2g)71Va{T+r#v@VM8s0hTNXP zl3o{qXu15f7Xk|DNoVI|K2f(t3aYE_G$QCqiSMLi6!u@OD!1fo17cvhgXPH5TXtp3 z)O5mBN(Un4*eqVAHW?wc3k7%jC?;B(R@g|nMe!B3*3z&g6v^^G?60UI?9D(os`~MD zh#;n`>+~y9v?A(``**Oj3O98j))NM0^M#L*-R4L5GS8iKk>exUR;h7OAGRwb8DWp{ zh&IEtaD0PJq})O3OTpR2Y7s*+HR;s?OJ#`FUbYI-n*;v!TX3(!gLQWAJLfY5%XDO4%_jqT91jo*ht- zdbXnC`T!Rrs9{0D0Lc%&=xb3lSV^To5wmt4(FNGGSq%I}2O-?E$QVAG9tfMQy=fi- z8;lbL81sevc3Kufc3y%oBM{*?YRjqR-=5S?WJTF3=>auPnM)49k;{i8=x-Rq_5Ccb zj;0YvXc1^p+vS7?qiK=O&WprOW$7%cnMN+L@Nq|mK-vziObD(m(1Mni78}W=uwLSR z@S|1CB2Sr1KF~a;&EAh6i`|&W?e>LivPUws zuR6)6LTaObv=W2sizQEH!23a$Cs(I!isIFHxyhj%o`ho?A_RjL+Wrcpn_~ zn9^5iStKaIuJ#+o#(F28EN%l;U?d7O)ac?>ZYZ`DJ+uoI$kvL?u{fa7Ei|t6#g;i0 z-j}E2Z0+JIlAJ`N3MOZ&OC_%ieOEKwMrIWeX99-g|Mw5-qA% zgB0&PuY;FtyA^vOR=Ab-biD7HHlUHj^E0N(`)U81xn$!3Q%g?`r~QnfT$AP4;3dS^ zUZEtVJqnZrjQobAZPn*mFpou_&sgD$asU z+Rk~}2%Xri$Q^bxd&t(ByNQ*LaXW+O`saVW+%~Vt>AUy_>~+l=8r9KQC@4s8xL-u` zE_X?Y*LJ4OoS1fBeL!@MWj_6TJ^+Yl|Fs6^zl9HA`3-OVV?N-w=o&}_{7nJP@&|uF z!19}(kOvls{q5y%TmdkL{*T4~d9L8!>%jl3Tmd~ZE%V91Eh~Tt*qKBCU}FIm zdi^JnxBp83UM3dyzXH7fq@w&!j0!zHEjtsi^^6VJ$@ixz0qczZw)(#o-~A7!^k>!i ze+33-0M_F%vC#uN3z^t}ol3wWxZh)90b<|m0AN!b5FBR#=D+{3`oDHejO;9b-Aw4972cikNG-&X(s zo56oG> zUKJglEvl(8-jS3tUpoTA4Zl;Pl{C%sU_3qN<@tzLN>Bg_E^OaypLPv@;K06`(d5&e zUPa$9y{RjpV+({H5@Odh=tnrg<0Hth)3DF-k+qZwZMlX10Z=g`F zA=#H4fFGlqOc8W>c|FWLRt1xzSqy5dQ)>y$V~d?Gh>^;M&x5cS?p}X)emaWO8tGnt zyT5sZMp{N#RgCrVg{OriVyS!GD~N-Y*y3%ZQfpJk{~;SjbK9xjOmZIQ0?+Hk=5-tF z^SF1v?)9vT@9pmMG+q&TnR_dH_~rZ6>9!B|%gyWI@=w)W3R*y}`Ky2wiNbApOrI7B zD3}EFMc_t5ydkWY+(K{5Lbbn}m@(K~FMDFF2is4O`nj5Pm@eOb(v&&8rW%&XLMKI6 zu$zc%5b3#?uC3PSUIObloru#yAf3{MKaHl@+bCHX0{2=J>wN3U^O_8El^7bKNrGHM z5zN=bEOGM^EERFC%QP@cXSmWBgQ>bd@X3PG4$vhoaJsN~L{HuHL({n1T_*p2yEVvt z`ayOz?(+5aXZ!m-{(Ej8`q~8iqb`ZJ*1>xXe_O%0HDKuCqp({*Gf;nfGkebAf(*Gc zL)vR-vJL+7)llKnZ_P_`L?PPucNNIYqJsTh6E%T%oO!$b^KPCL?J4)js`9r`iut#`^!lqDLf#8BDRt{g(N2m&Jh4s^D5dxUb2mpxb^}d< zFc8`iw9(8p)eR9>3Yrw#v!g!k(H#9?-oo1Aq0=@4(BO`IdBRR`zj;aXt?;td~~lA9LTsOJBrP*U8!*bVV=v zyb}F#3^Zm=IUx6TAb;D&_kI}u^$rR>H8YC>sD<^YxA_Te692$4ue_zQYB@c&FFM(> zCl%H*k|O4H|BU~3xQy?+-2?}Nt&0=%Tn;~{aWo`=aSFx@VfFFpp&q+3*zJ67#nWMp z$@z09XGXeBjrDrjogQb&NVV17)s;~HOvyf~Qf7XFz&Y42 zc{`OqdZ{O87^^uF(cq?9i5~L2XGOPibjU|TJL}iHANDHNfo_V6Vb2G0xWh% zH?2rlV_y!+f89OE^RyX8Ewb%h2IHMcB}SmH?SuxzxRnIB@xH`)(?Hoce+2b78D*j?{Wptqtxz_3UxE2Xc$&gUC|S_F8bVS$&*GsI ze@9-1Qv~&E(X#2dqXwCD^+KgF>70)s1x91mhPhXkUW%0ZWxD)DMF!p%fwse6*YZb0 ztgTexbj;&(i>ws8>c3rVi>zjCI*hQ^6d}QUWM&+cbL?3gsUbNw(haUqcZJ%4FIhI( zTnDM~BGiVfgOY70TDd#bIaAx;{B4M$+SoUVfEJUKrTP1d(av?K#{atA)Z2T*c2z`tTAG=XLs%Z33v3S^@rT@wV0V*vlBf zLa!+lHP)#M@jG@Vk71vJq6#L*2FS!jagS8{-pd zcE{TU9USP@Mc0rYy-k3CR0PmqXpuE9)9t`x@1ov3BBLCA5lC+0p`Ot}-x8jk)@ocX z#N$t3{^;0j#!F3C`(c#k3&=X5h1LL0_Gr!d#8;~Ea!-5Wa256Eq7K|Vu$17<(wM3Zw^**GAy?vCm#2- zG8Z_3{?}?OIyQLrjLWz>kai$&Ym(3V2vp_pE0%YsdeJA14OQs)Bzql%IXS2udMlU= zedF_Tw3A?X{v0cgL2L;h*saP1xBadfs*YZ5vq!>4>eHLSU+lLGN?L4Wp|>a$E?97P zk#5lPHt~2u8!DQ@M7Syiem`(*yIsEX3XR8cg(08DpeM$bxn(0QCAXu_;(;o?CDm_H zjvMtU{V~y!bHoBNar*>icAk9m6Dn8*^68zo(_W~ARAW+s%rCNcpRQS> zqE4gx?cWhZ|z_57{99twc=W8AAd)EhubMlH3($>wp27_AZ>e zxQy86fPoy|U2+5W*jyrM36jVCy9$aYirfW8&!hpF<~I1vrz#_r^=<<)abfg0iJ`^C zd3DII$<`i{eB+|RV^rRfQm#h;Gbs!jfy;3@&V05(aMM8l&43HB~*-^U3dJ3qoqfEM9Xr>NsJc zY4lfE=yqXrp=m5`KWVlY0!e>F^~vESPvrIz_S6Jg;@Yu_0~QS6kZAn=w(}J{84M!; zR|5FH4x{Y*QR30a=9{Ka8^5>yznt3SQ{buH-46(-AbXz2YT+v!l)4L0(fQnS8EVV?tb#uL{?0sO#1~)^f7MLDdi@)lNm1 z7$ZVKmmf8^8Yq2_{wW+kTO@d8n14STpY?&HQfx&?C&yTZe($$+(B?9o=fnSB(<-gzTZ7Bdp zHbLSGWE@xLDCQ=DItyTHg5M(GzWJ20H2Vvs?t5(03f204nxpr!2hT3gz9H?nNB`_# z!5)Rd^8VXvm7&`?*zvRrO8dOg^{}%va=UhLJnB(+#);Qk(VDEOk?IGjc@?dem!dV% zAWTz$ZiSc@Z^?o1DUM5m$D}>i;_}TLuZH%ahbd>qOW6yT>TY@VTcoAhem|Ysu*f*< z@>@%#&$2_b!#j^N?6_8Nz0a7h4z~l&b9d_%g#X)9;DSW8efpaV8uhCIeo!54xLQn& z3RGy`2``TopPKymVIK0jLJ_Sym0OFJ&za&0w!;g7^Wl5D#`W?Y!rdd@kQK(&)4?w; ziIZTH@*sx6>0sHQ4?#>BfbKQhVF3=7i1kqcfE|zg)GuMyd}7fR0AjyDKjNOka^Kk0 z!DS7aW2CTKOV;_ejN`Ed8&2MBe}(qowcRlOvyS&MKCcuG)8GjO?sdG1s}50nKh)YK z=)*2nv|+)I^>ZgFQQF%3x6^eaH#j$jnC%o=ZydXEvHE*JmSj zJN2vMURxUCx@;)6Mz#E3x1spzw zLKA-Y!qZn@KWb-p+G9*rEv0FR$SLM)%1guXza?%h=VQfi{ew3er$LzM&fa#@UA4&lQ9X3}H9 z2PW5)V`K))pA4*mn@Dh~2+E%ezwV}`R>|ACso@>E&3KALw-T5a(q3rBa zj_M*U$@5GJQHhm`^LuX=76R>+nvAQLWS{`>p*pl0{>E>#QNDXUd53;Wosgf)%tyPS z8Wl5~FNVMUj-|gQ`1E#NgiEXvdV-O$(IWt|p97jxhioGhUrQPQ&(<#NP$=|C;Q|kf zgqDS%WGI>r>bY34hSK~ecuzXM0XmFpHq@^YsQOJ)M-2Ls1o3`6UA=4E@1rxNNAT1AZlXT(;}5I( zi)6ycIm^r<3>yqFh+B%f-D0?0Vdwp)DLIqwtoa+fn5X5I@D=c^&^#)QJ4my~bbS?E zq(4@C5TW9rWTdkDxrwzS^$fEPwu>ZK5Mkpn!kizU(Bj%FVSt9jPKHt+}<=2dD zVEHxHIKsvv&9G-$#g7OF-0{eaSY-{m3zClfkxu^=^>`^*LtHbv@#$=bWiVc1MJ!C> zE=~)L7E6n@Sa_>4e*i?9f^jQ_2pta=m+i>eL_Gg&TANHOd%kGt$QAQebs$oWUE_su zGYL!w_P5P4R8zrP^7u9VrV7QXtdSu*Dd|IbBLl+ROnBphuONYOQo8VRrXp!8sI4)m z?Pz2&?Z>Xk-g3%?Y^wHCoWJMOYx8`tty#pnnsrGwo(-~imO{}_6l(>uY*4O=EYmDa z&=f!y^OaWS(voE|p3-OrIxXw@_#%3^0AOH>Ova5Oh5}5+ua=j?-*OtG>_DE&KL0q< zZ3m!#q%1v{wM7&v0o8;}q$oy}Z;vaQBPYbgG7A-!LhWc&=$KVJZoxt?zsogNsDn7- zOhS_N$8e#QJ((kIAp`&axO)qry0UItI0Q>@3-0dj?gR<$?k>UIf;$NWCj@tQcXxMp zcei(vbbnvc-BzWfsT8G}OWLB*QE4?$)g z_U;SnB@g?|f*J{=1P2J`;BRRYgw%RkBi`q4cJD(9G05{|-s^tg)~TX-vW%ZU^y_y6 zI)4P7RR1xfKJ4E!>R-Lcne4<}!{awgE%=CiD;;g3uOgziPl@<#M*SA>`xRBPbYIsy z<->2CmSr@JUQw*}xPJ8n52kSruF3(TvG+>J`+m8I*`W0Vm?0>>*}&@4v_advr;|`! z1s@Uj(PKPo2eV3aG{ykEmUTaREhlMvDjAV*G+Xw-G)K*K(I%NAtH{OF#00Lg-CJK8qxI zGT=Bqt`_gLSl}VW%^TUI2sb3JC)>|bJ0qVM=jU}jOKBYUDUkw+bk)zRQ?|!n9ljko zs!d7cGNM2>m|s(WX*Fgp*_RQS-cyl*YeMt3E{m3DuYtoYfex45+AdR@n@?dJ63H#) z*1b=$Mkl3qN+S1zloG}jIL9rE!&b5ApxPC9^=Y~1X!puvgOTURw)h=}B009on30TF~+}Ng=QlfsB6MbCGQ>IBQw!;rY z$lG^liTW2x?=R&N7cwfHm*-JgRi}0nImb;Hy@oFKB~}JGEjdp>B4i_$!%LmT3QotQ ze6e=9)%uTB9KG}H9$LV{+Fb|>8cUljC9@uGo>i(}6#iL)!ScT(!C?6>B^WF}Bp3iI z>hJoB9}*0f9}*1K9}*1K9}*1K9}*1K9}*1K@2`vt=#l*PJk}qt!usP?Sbw|<>yK9f z_}+ed2%zun+aCZg^1n6a?)yjipRrzm&NBe(^`p-d(2K?lV3g?@aRCwz0PFP+*KRQU zksJJ*(v6?EK^A~-IU~yt?Z!8MZr1M|dn^Ec^tYq`SkjB(Pg(k#(hYh*vnwqtJtKfR z{?;@68*1pkNjF&87y+lwx1M3v|G%;H8;i`W%cKvWiJ1*)Y3XPU^z;mAbr=i)ou@2% zY;-y-wDgPspKL=tJ%c|Yw?4j8`KUo!$GMglVPe=!Gi1_pF= zOpH2oI)*xW40KF%h6XJ93`~Z)It;Y>^vs4VjC%SE2D*RjWc^+O|5i<51qhkw01_Qs zCT4nSI{NQo9YB5okYJ((R9Pm*ZyJMtwuA>DPWl5>zJEph57Pu7)d6+nn}p|=G_m}C z^q*T){+y=2**#7V01GWEGb0mV5bM9u#J~W65MUC)H;ny1fF^o++CQS{Z|X9BPSd~9 z^h=ul`Dpr!H2tj0`0vOI*;oMuiIEoI*ZLD~=$Qec7DhH^z*ygJ6C2q6;kAkWPo?S4 zTkHQ+4@UQMmH=AS-%8WZSpsNPe;obCmZm>v>2J!O836fU1ZY(O8-GSdz%b|^s9^+r z&(YJ-eG`u{(zE>Iu>=@P@yE*aH#g6}q>1i#*!-L(hJQiq9}A|xNYmflJ+rY)YVC{ZC+q_k7Rlu zeO%CNT0U*jxy0r;dUf*taUrVN(v@=B;&PnA<*AoDvf=t_`TWuGn~=4+!Bx?6vTG=| zQzWH9&EnzOis$Jtv3RoUXf|$gb}CMK_nvpTOoO4zV)Xb>r`|9D)ls$WL;CT!Y34NbBx7#a8wH<$VDszr4gn@4eOB+@Rz!_wkMGa`sz~K^%v> zl1jhfd&lj@K5KHlOy?(r25BYl_;>E(LfUM4_S1&_+5AV7vKr5@83u;k?!XZx;wZ`CAi zI;rX8I__rCk5TsBgA6?4ar?h{bC1sHQmu*zkDavF?>3`I&3;0WlP%Mswx=VG#oSuv z*6KORMYD;|U5=AYSw7SdK8o&oXP8x9*>qYFUq;@0I`9ZSwp0XUw0#<7=Krh^c$H!G zb~@qeU~$nLvCAdsZuZvG*F$9aSwiQj`=TN5UTOTWd<5madwfGs2-AM3p@7Pn!!13) z@$UU7l|6~A2^mSn7LmD91Y%1N!hvMs`dXEE!jZ#A%0-;k?%w;E8X${-cNl94lDMWV z?`7@RB@cu^cjjhZMvT)S8XGm5Boimr(zY}X>*6Q+)~6+ZfY`>rBh$*`;$>IDXMEL( zWOrO<76I=wVos^O4RGf!U!-k;b)`EvHw{agFC472_T*FFTp-pO-)*Y7#IFwNt2;J) zMOafxH|WwDj0=iG(&zV1^lMnEeVEIZ)K?~jcOPm{sN#<$U#9Y^IM9(qJE5YzLY1tn z5*K&wU}4Nxu?=Yxsp@;tY|n}|54ps_ccPW0-RZGFFu#D96bjekqhv~w{zj%Oh85@i zSbmtUfkbb;N@NAAw>kN;CDN5bts&EdGJpfMYJvn4PIIs{h6rCZo`8-!6>VO6wGk`WuFgm6Z!=~g!CMOTD>3Y8%wF!C;FEcc>5JFu z@5S`E8K(}5#UhH)lchuD^op!eTkFZ=9S9yepClB4Hp34|KyokjOo;2HlvUTxzheRx zz~6%cV-2z$J0*W#p_`6hj?fP!63Oo+mnf+rFAkS7b|l$OuAY_|6RI8e$8>g&I+Oz?fN+ZPg*#LQnm=s0?WBSb#bA#y4|r0d)Wgp3UYA zjf(~opYJpP7&8m6QW=+Ji9mD#g z@VMO+nmPk5q_{|A=vNS=5X9L^Ht zn+V`S*1b(3{rtjtB59_Cux3F}+Dd>Kvqax#%)UL)79&12kq3Bl+vip7(WDc6_t8QF zAZ@AzJocM6_eFkwm`NiKDUP^|X<->RiQFk)6d z;HIz^S6WA?*gJ$&7F52H9f-)cZ>=hTH%Fjs+U>Llm`>FYM9Glswwor zv9>5Ls4ga>^bvsfLiPep*BoO!?3REe+m~cKsLMgeL-MPsks%Ct5z*2NedABQs?bYwv6; z*owLLB}WKI)y#0mSG2~)Cge@#EsN0RBZq(qv)++-#@w6H(%CQH6j00SSXks#L7=bei&<-f zoqK@=FHE7g9> zTB4KO4|~k#nhc*IxUn>6v>JLnHwPa+Dm?c+t(EeYJ6+H@EjO1p!!1WW&&FO^@h}O| zO(esARFk^%6I-9PUPVTZZKyVI$_fA{#Q`@F;e5z`3=IQ)$mI!MZCiA`=ZnxQ*ml9b zHiAk@4sto_WWx5~*G z?P0Xv>DF(1Rs&1@Zx;gJAO5c^f**m(>*xaFwKBvN01Su)Jk9psG5sKIzsL0ND<~Gg z4QA#awAD``(f;dQzb69_grtEJAinP(>*ol5xvTUe0y%pN3qVHx{l0+Pk>7~n|MnZ( z7&!bZ6Tf}-U!(X=LjN4aFE?#|i$V|JGWJspKiKTQ7sHQF`+NR>jp4`I{InLo+!6T^ zgD7A`ua&<2cZ;;2Liq_B|DARCo{k?M`L9Fy6D)qA^?rmRY+|WzVrldf8kqhv3`Qn8 z07Abr;(vg{_b`4%w9Qgx2C9E8A-*PXur!3{&nvBRy6(!KXkO;6%M~d`b$sokCch%*y5U48Wiw6| zGP5uNdiVb-b-$m#KN9rgRHCE(5#hfP^yA1M(xqT&Z)>2B``*UHLC4Mj*U;Ybk7)YK z%rUSr1D5go)ZxEa#((ANUzO$0OZQ7L|B(<$D?32(CC25`2b4M!D@z@7Tv1CyD;o=) zZ~y%p;NQoM{5Q{cKDPqqEK zw(3uK1GH{av(f&?nfj57-z(~0)r7yO=zuR(J#%|o0Nj77q~A9_e|rD__>1*h@%sJ! zet-YpO6ku_^K%vdZKJ^SuZ_abr^lb4`+a}$`?AW}>)JWLH^BYw!TF6v{PrT|b_O=M zG{S&X8VDNbS?L1~N*Gug*%{*kd_jL5MP11b?j)};wcW&W+$cd$!|N}ouT30;$Ll38 z03q}?^%a5(E-u_Byr2x;x36%!UMg!F@agmPiNW)MW-3P_i0zc^m3{RZi!Lhh+HoOX zxEc0bO6K)n%f3H;I`%kTbQ$8hz8HAd)#8n&?Y+(GPo2A12U?Bwu&weUi}=MmLkB7G z<1L1HBWm9A>K7}1NA3(@4|SJQ*)ImwfQ-TGVNs*YcBisZfZBHa0z-jhN&%$Ufv~n~0UN>p^79S&*h_wKs9Hwm z8ZuMFgS0v{#teAKLuASQ^&q+25iA#euw?2G+IJ51eiH4eRHM2B4(YQ?72+{`5%Yr& zDyW4sM@zfhJ5O`&syV#^nhE0_;_m4Dk*Ij$+D!v6){!8+8B&jd5$!?U!>#8h_ydIQ zE?CGdx=x81&DhK>B+}6JI7YHjaqD)z9`xpxXjuxHCJuX%Dc_oBFbb#+m8fO%Q2;=^lF-`5kcwiC-7U2?3#SY?9G3Mk!!{YMJgLhXjYW>Wmhvu*xJx%%~Gb#@8 z8b(Y9fZlCWLZ*+HvNcEqL}Dgm>#|y8a_Gbc;?A7}Bu5ny|3NgU9BxWURMdPII5$*{q97F8xk9Zk|Bx3Rrx zawdLe?%dQMuSrxK#nQ*I;cgQqdc>w z%25P8y|v}^N*A_%v`J})4Gh~CEgW1Y&YEq3{q^OfDMN8uQc`^SI--)REl-UQoGqZ( z+SVsEzS&1_MB8Q>WV6d_XzN+4akHhRm3N4~Oz_WTD?_2U24y#vvle$G1`vH26zlAh zr8y;(fD=GGLXeV08&%&Tie(*k602nyvVk2ss{=;0$%X47--DI0R-=By4;8g%Hx z_ENhK%kZ6bOpIVm7@qG1RX**U!EMKjyzc1eSagL}!E}~X?N6sf{wQ*Xls)}4>2)={ zFVH81vk9H^l%?Lp&ha!R`6{cb%F1wuckRTzPE#^{;R=S($!jSpRGOVac;`1nXMcVu zC*JiAdEY0Xx({uMot2rLn9k{9W96XigEi5|Rt-oH&PvO}AOwyhj?M)B*{K2p6| zSaS^N9Kw{rDquJAQYH2ddc{G~t&+tTyS%G`ob;f)XNTrEEqGm5z|PJNUVM&S zFk(n(v)fSE;9u>|13R81Z}Ce6LeD@P;$$WWjbNl+aFDl~y>Lgp7xvc^mIdoJa7aKi znGpRtB61411hO+cQ;h%xBAj}JRB{frB?ks}kS5U!niMk&ORrDw@XkLq^d)}%Ya}Ez z1HX1J8ERMTndTRy@Wfjz^yONV(W=rCnY^GBFVJ5Y1ZnF?k`naDQKm=xok5_TTy^yq)OD zYJot|v3)5dL4a2JqTrIxwU z0~`~=081oq*AcpyHhN{rP*or+nF9@>HRk}E*2#?cBo`-b-@iCyx)Ap;Uy-5gnFYHA>YFn<+IpRKOtjqJw0!@x z;@Wwgcg*8ne5-lAzooQu%_2@A9=_?dDc8@}zf75;!d>mAb6dX|xrr0g9zzgAL#3q> zt{ScquGUoLrpKnkX2NE`W?`*jN?A?0AZvCzdB%gx@>tq#CmL%XRkV{=w98$may|KY zA^ix?C1I5suupZV=wimjZIlueSB^tZ1dnaP=)WwyHPii9SLch^xN#;1iaSCU= zen;aHiAzCheEibV#j!D9NzPOKIP-ccW#oPb?TI-1Im`gD6wiN!UqT1cl)V@7LrLQu zJhS}!_&d7ny!1Y!i3^3BSN56~*Dd8W(#{%>;WY9Ojo6s7K^7XlGcoRgL1p=UqWi>JE*O-P?HNIpLXqZ-_JYIMXb=dF%Gv* zaiWW3K3#M91Ws)lw>wpo3ZPQpK(r~N$3-x6r+~41Eo2tB?Ed(924WD^chL%QBK#G) zlux1c7G$_;JoxI1N+pB66-DMH+FJx>-u~W@nUjNT0{SI8?Yv+r2q)YGCo7*EW_v*) zC&W%z>O|%7>NS`*OzzGFd+$uERZ!RF++DpXpapKor;j*7-Y;6*R22cu47H3-z2Q>o zys8|9P*s3(1f{Sw^C`vB!A?8dm_sn|@4K%RL;4~rV(x;`fTif%GGFV0cr!M)1d#J+t&c^r(b0!MM&!(_Th zI}&($^6ot-2D3)<)}a)SniB1SltZXO=_C}4h;vO?w}^;MxsT_D?oPW;LihmH;jGSv zNWEs&IWswI;;kHrLzQ!to58H$w1@dn3DUYgC3G9>9!%?2rJ9rNz(vxdI#HDaR*rVc zn94S4e-R>HL~1aE!~2>sXLXB&7)DcL-L)JGlEbv+ck8`5aDEyG*ZX)};)Xg5N=g-= z<{c!bI+!M)`(a^xMfNkHT1nY!&PpHn2`RUkIoaQ>8<`>cHa2iT7S=!%nqzgXh|ef? zU6TV3d&pMme$>+h6RulYlR+Dws3w7(k2YRUEo6KBg+y!Jiwe_>j+K_kY&thep*{k0 ziJLWb{G>^v@wPb=!KYT?E3B}QP|G%|-#BfT>gHKyxxa=$i@roS@8$C3Svu(H zGtx=+%W0I7WW&Na9;w8Vou~raDz~|u{S$Ysl-a8DlaF~oy`n0>a#&B0uNuAQzN&W# z_?C4Jme1@I!^rL)^o#J0poL z;BdI+cwA$LL-;tgT*ZT!w8OSjv!<{pOUF`uniw=QL(gpEiXX`HUxcO9_v zREzzG*(PBSEy^|6ON}{7jY&$4NlT5t1_=3|`f8)T_CkXg$4cKA4zgP)I+{BXy&Sr> z1)sge-g_=cjlP0r$%Y;tPBc#OKR$iiUiRv)FxaX@uLZ^}$&qmP@%%I&n9W`IvRL#5Gqd^U(Eq{cw^Z`SGA3;qL90x9ql_ z`aW9)rCF$ZU7d;fR-R?m1g=Q`KLti5Ejy;_q+ zU)j9Y;nWW)d6zeuz@cRZo0cp*w-745W!(f43UOT|5ak6sl+0Qd!J|{`xeO&2sHa*p1iFg?DPgUwA`D9_y zwxRfnlhSgd5JA3KH)m#}y^8YA(RPfL zb9|RO%q8z&dS$V^F6!=>Kv86{myi8k#p`W(Fzlr&%R||AHp#sJDrna=g$ya+Ghrxn zPKS1Cj-%9%DNNK@yMbGGD+=6@uIC`_Q!kP0^9t7A6K;x-Us*S1o`Cqg2+~r>%2jX6 zhlt2V(z~TR5cz0vQ4s9KV)n!bF8Zo%sACo9G>2ZPu{DBxqEj1~Tl3v^?5i3gO<7Xz zYNTYlbj0J*OMIOT^N(if4WxneeHf_44Z^HzZw@lf?9_u^vr4UEO(UFV(umbU`wxJB@uyx;w!mAANmXTQ}rwP=o;?MVN5Q=3|G$nSF9a&Tcl{B%Qax z!;nfjKh-@yJHRyNMLm;%g)1P<N^m%S$jZtZfEPJwkdqF?=H205py0WX7TO^>iwS zL>ri+iW%CzXnwzCcWw!Kzv@sqMWjimZpunRlbFny6w3-T!82D|*;1PdwhgtfRW-+i z&3VCa+fZWUfn>04t4Q7)z67@28M5q?Q)ngjGR_8h>(;{wr~T%KOtaW|x|?Vlm-#7o zrGzxA3D}0PuZo<|OOhZy0t372Y6-2tH!`lQ)Oo^@RUH43X98KKh? zz{ds==rKH5&nwwe9%sQmJ==4y`@GT)o}vq7KVcs1skAzLBq`IW2(9Gn=l~0#V-34t zObD>X*h~>Ek{8(F%&bajOI*<$^xP|tb_~#dOUj&1ij1&gD*43-@rZbAPW?6>KSOJw z*$H>nUD2b{R*FMYep@f+0|jjc^M?gtYYP!jf(fB>CCdArs^`bicK^+7IQL_B{w?5g`3cTL+gk%SRyAUt>2{KqqsPgq$6*f2 zC=OU`d0O3BoS2U;+Uvux4W~yi^_7naZg=+s_W1AH$4-U(h9$5Sj^Z8~=%13aV~Z^7 zTsr$I9roLHE7`ms%a@lMbb5pB`!S<8e94BxDZXgxo_iXmnq8SnDA!n)_Qg_89rPnC zAfHo);P~I_BDrs?P@*#3GlhirW7J!MO)dH>?@<#ImdGxXUUXBq`*b#HiIYRE<18`mcL>bHy#{P&b+%8+S78h3cxr@$$3MmtqRZeY1Br` zw%KiZGmP*kFzz&1!=Ogk4}NQ3cSvc$V+(?^Q~EWzvF|1YAJ5bx6xMYUtj)8!(lWv_ z&T&G$S*G{yklq7~J+ub`qXxL2gMzVCZ~JS$D12l3)(Clh_RB%`yFiCD%{LA7@ZjM6 zO=7tf@a$~!_gHwG-yV*79(8bC$9_mCw}kkoEymE z)X2)Fw_5Fvq_h#iP{ndG+CXnSl_fd}-GZA>$ePxkCULk^(;^KOPw{TOB5$+*K5D(UN&VAEy<1XYz6G1CN_;n$`&g5c`nalA(AerX&iJP<9m-_Zu z=4`RvmkDI4)ui4cRq#CGn#yQoW4VbYw&xfXE-w})haWsH7KW4`oG=x*Yy>E(CHEDU zv>!~4Ci~adSSRr8+Q{rH6b=`N?Aq|`D zHqglrE}>UZ&c!c~hp!@rRFm^7jNg+qRF1#$I(L>dJW)hcp9JBtN*P|sR&?y+85*81 z@nKBv3m5QBaR7YMQuLMo3!gAIYACpmzL_EE?ZfZ zKU+t*!+u%qQrJ8`m;^@e)7yW7>~n2^WQ@E+pU(3<_-K=g$N`d^sX4-j4v{+s8HsCv z8e90x18a7%@|=Fhv+g=n^W_ABmD#M`ZXoN@Oi*Q+J7;>sbHgYxO)g|<(h_yyMjM&dpvCnmn1{;<910lP0urZIVgZQsW%Y|?z=t7 znz)}~j2GMS$?+zM=_n)_jc4)sET`}5{GQ!nW2b;mr_x?dyUIg5i044sN%^B zDaoa3*huktXsa(pPk#E<=PYoWyi_>z=+XN+OfS_i8Pv=%^LKdfg1!8%uv9nu1bx#Z z=Dx@XCo&m|Mh#DPJtm+LYo*+nqptLTo>0Z!(+qc9#>GdklG_5rcA`h<#x4>NioLv zouW(nXGF8pjM2J4ebOy5#TyxLy`5E8E<O-Ki7gHef4dw-~O32)io8 zN@h9D3G7r~6f#_LYm=Ht@WYzzGVpzr<~;Snk_kCbTBIrR9B{zQz@gSM4-aZ{mIbV) z*XD|f;DUMHekAQ!l{IVDWzvM5#d5E^Z)f#iUdbp7E8I6pyykcZmxYV}u@l>>(pI)9 zyNq0Wu-gGjup4H#M#~-wa^9lK4)fRz_d&Nwv>)uqfMw+XZizq>BQ%k0$O739wL_PX zm{uMw&bwAZgsezkxk2KYNjXBThO2s&k29F01ZOxc46G?s=@e$EyPGvc(oWP@P&8DX z^pswexL3aS6K5@d@TO^QG`dNQ;w?$7f(NnMhQ};XM85|cZonp}^E(fc<6iKyc)Px7 zHz2V5RdUTR#a?o`L7DSOeub4d@gZKZzHAvciFgvjCMISa>Oqc<_a6@G^=+oF4*0pniQ6EtM`*# zs+Y21_tNVaC@J$7jxFtsCRsI}RJ9Z>3<`%ek`L{eKo(}HNknJgR03u9Z(f0J&78As z*n-&{SW6D8N=kE+kn&7V&90mi5@lx$9P0E@INqJBV>jog8h)N$X+kPBWndpy?(KL?= z);NNQh)p8QA~Y%!ABz7Z$1fo65PS5=m!Ns`diD;|~XU)e}uX2BmqH8O@+fLz_oOji;N;S9^Dvd;SkxWz-k z!e@DpGi<70Y217f?LCfbwLO37wX->2|6Inb9H4)sBr!=Ndc1}3?y>S6w0*|tAe8G? zwXct_M546J{08Ju_Ka<@tHQO5i-X0YY9f!$t@8Al^=mTG-uTy>W{62ZQW_Sz{4vvs z+BDN7BWBgjqZ%KLQ&L~IGDK&u!M3zZTE4`VvnkiE)&_nb)C0B(Pg?D@&2r@ZAV`bu zguqW*rbNkl#;6~q9omBhvHnUDWZm0c>j|Kc!zRwM1OoagT}Z9)uP!nD z9uO!U`8h{nZr{*ia8_)-c(2~e*BbItHIeEpsbs3>oEPQ<&WVr!g>zw(^gVwD7U$Mx zoOV$UB*Zx`&Fd}TM6W0@O|T`eB)F;f&I-yT&I#)fJs9ZKz@YfgS=N0YByI|0#&x}u zs$YDl5Ndhk{n%3vK@`c*G9S4Nc|^$lp`lpi%38HQ0NnsT#gy_*12`LGlD8Yo6fxf1 z1J{PQHbKh@>=A`$kbXRyH**%&#aNcPNxC z1qyasBwlL5VXk!Jz7_B(F;9Q(%cE$o37tkJAEFSSUtp2O`o64;Uj_rnmhIJt!1PkY z8BlZZHIRa;j<#6D+Lu()tMCPtl=UD?g1FlJLB1@AMK6`$)l`{O#%tb}iJYXmk48)h zkHwSTF~0Jl0~rOuq62Y8(PpLYc%^t8audzkG2Z=gp*|L_NwY7R4NR~0b+_&CyA4h8 z4g+R+u~z+~4925mDE>6ExITCKWbZgp45QKUS>Hh08Z4V2kh8e6TL~-faaAw=EF1V% zb-F0UKFrVXH|!6XiX;t5tw}SkWbY0+G}5|$`Am? zvtLxuQcbV1SFE{scrEav*29pTK(H){HVAuNfL)JR5vj=Pmt}}0WQhCg_aW(qn$T+) z_DIyK8^T*LiXmEeshWH=+fc0y4_tS-O0{T8xI81M4LUxHxP`HbR=e3-BIo%$ ze^a$Y?FbjU(Cc_fU7J|E!_`5mwy8NwJbZ4?iZ3#W%A^=3w>}BNB=eafHc#5JQjF^@ z$XVoECbnWkj>x2*AVEa_qA4t0Z zNZRKq_E6)_R02DkMWyTUNBa!yujv=O_;IZ+f#FjE_E4n*pe{8{(h(!2f=np;tXRc} z7jGYd-Gi_*X^4i<(!2MpT^hc8B|$hR-0QddBsoPU$dk+dE_)v;Srn5IK#DM2Zn_}D zkD4bJZtq|w=Wiom4UV5*zDzDI9sv~;gS^Do$Oy52O*gKqkrlg>=@Q>0OGEOZPPKT1 z!d~y)#B#lbmBoIKS(HF`<*BM!D7@i{FZ?OZDQGxa7(=XnM*{HJlRgwZSklu>pv(2d zCp3<=2#(Oex{o9SC(5>;&@8W55C;VX5+B1dZm=^QE344Nzc4`LT>FLRXql}~%VS+W z1w}Y^ZgZTyoTZ@G8}ulb#8_qNc0}S_qwSKS$21IP8-o(3%}x;YWWGliwcgTQe+4~v zakQV(;c;sCW%jx1=2+Rv!$V82dy1IgE*;Oxld+Hsee_wU!%n#4V9sM%fFrT$elHu6VtzBq;jy>GVV$l!+rr8n`C7lepRTaLZkOqF zp9hw_-->I(FLt>h8&dSq&~6n4C5(gA3WvE0YqCr64(qmF52qU=e~@MHmEJ+1&+rkO z^Im+PUv)Q@wOfhhoh_oS$PlGy2#XSWcIYbx3&E#P!4tWe^;#+@)jf2(S4vwLz`FH? z@s+32B6~n|T@_~QBPHtr$ZTh(U!2I6oJQYrX=kA$1`osq?pvxmx-U!+r6ka>31ewI zWV5Q-$eF37zsbZinhVoA9K8?YDx}Mf;Ih>gc_0?Cv#ooBbpAPT=dst>mbyRA^PrJ+ z-7fX^7(UB`t1~e8em_S(k;)<&GC|+5JM50CoM_9Wn?s7rUe~C>T4a0Vgfk%id@}gt z5{98#Pw0j-K<06BDWShTmZ`XiBKY!)=gu$zTla9lu1WdB0y>>P=2RD4Ip@|%Et61q z&OWoF`J%bRVuNc)`$82F{!vqCQBM;F!F~0m+3_+m+AKEP*YnI&ESxU8=WV#z$J88U zG0PPL?>OiNoGl_j;11w|$ATwLW2rOC-V42;IAA6cmSzwcO{13XGu`LUtu!jPTUOAn z1A9t`SNCvl8XS3|a5CLAajx8Flx7|VYa%iSP6r*$re~L2jrZ?PIHHH^?rEN!D5r2QTbkBB zHqSlR)wR+$iSGYUM#sd+O#92VQYV`kul(fH z{eaFD8!pTc8aUNu59X_$g*D5kQn{8l)wX#xj+K@hmme>a;~TH%02fJDs(@eD+zbR= zp=f+Bd+^&3MND1l($BZv_`)@t^UrBwG1>^mxZXQUM`dqeKLPRB11_v*2^qqE80!;@MLjo;lW6NTx(dG~^xh z*ZTM_iRb4cKsj=d10Ta@%>3VVv}IPeaPAIDj{R$e_xrZltgCNOIR_r5B%0Sl?A6OI{ zY4$536b$=tx)_nV^|&FGKpb$i$N7d#VH%uyw~R0I{E6NcsiPDEed^I`EsEKbsq_Mt zU+9cr+REXS1P!&hpmMix)%{i9tUK9-Wbgz0JiwkYH$v&`#toRwq{XmBT*XRL0*Ja# zLW;(5%svG*c9-tB@O+R?Z9Nr<<~mKESJF3T54aGf=}LvQhrPz>(YOz*_Cz8 z2p_Y%aV=JSnpQjN}Z>dZ{dk#*^5u282`G!iF$`2hSEjMYGKNwMHIcDAV; zL`>kb;H+(qvM;1m{V5uIsGKC#ITlRJW<@Lx*SvY2rg>mXYj` zqSRJcFmh_?`u@hOtZ*Stf+FLL_ztZ)w)KQsIpgh*97uteSbNPF7q zsv==zgMh=wBnkEQZ^gT(?3kiss5K<}E_ovf664&V}xU z>4jl+-K&u$M!&06=Zk_C$U{GHUvNJV9q*H@9TFG>h7R{9u7~cs=9TBPXXxj|rzNki zUd%vKFUVSu;jrQ0ONtc&6hRB~fc0L6y!13p9&wS_FD+E6T(UH=K(kaax^F_W+dFoPcJj4J_$j5ntQ7#`pH~Yt(O{9{4nEc z40y~(7Cbk7Li7`nkj>lVOt{>TjcEQ%+T463YN59uWm(9?f@5T7B_Tb+wjcPXOWvJa zzbhFbYTVS=@+Oqxn7>zr@|`yd$9dj?Q;-*~^j`<}3v+|acW)L zjKDu${<4}kDX8{R` zgtKfCz#aBs%6gJ$2_997iV_sLzE+?lf(Inzuq2`mv?}5Wk)jUL$!Df)BvYZj#$A(j zXY;xhiz7s%JBu#}ifCUOy@MR?8c9Nrh@QeZ_?@10uw(7xl1-17G#Y`wc{!zz zUmxX#O3#gGX-;AV=p?53>B(0n$r9MqbF9}9LV0VrK>jkzVyyyHdE)mSomeL=Fm@># ziMqun2lbO*gNveOACZ{wZOI`qaUHO}u&$9YYV~JQw~FlCVc3IPVZ&QtHadub=D#{5 z7%F9^50OX2%8!>5d!kv^% zD3UjuqT~js{t(EDDX%0Ie8IhVVDV7p*(SMIf+;}MRzDVkhv$$88BaelAQP6uF)_K2 z?c=)aoaHMR?aQAod|Ut$Yu0hjJ>$1ez1!ZzSA|KXhH0`sSEZ?NgEK&JW82aP;?6Fp zUdb9!yMeLT6`q~dRtDjTQ&`AXr@2}(zOgazw%uvsaB5imci!9KHX^t6X|uBHH9 zjU&@}H;y(6!H^xXOGT1L5JCM2QRx|8`IyQBl6uvv#OKQkijW)|PbekZO+}hSMy;l^ z1Ux=a61yjtWY1S8K4%N=;50VEaIIZzSh?(BrTt-y!c{wT!Tlf}qi--`c&fk3NBV`v zp(l{e3d(@io7w1(=ByaSC4tqmsBw4%`(O1&R*PO9y0Dal+wj;6${fMDS8aQ{Lc8$h zkk7R>%foIo(8^y2DQ<7!W_+1eOx0-0WfU3_?88^)L{uJqStVGIZI%jhsRgNlo8gS5 zQNHXY8!NwwwdQBk&@QvA`pUoeib4ysmbktdby8}VL03O5iS|G*Lf4D~gnE85Re^wq z;*EvX1z7^U;2}}jh%2ms2-@7E(`$CJy|7&p#Ojc$8@>6w@Z4;{<3Ke^;i^gl^&9D} z;+ZaIiUT8_Svjg{%sx+L(d5V|yljKRJOw+0G5cjvE7yBh?Pq(tB;>+3bFK!NUH!f3 zLzCoM$F*)EMb9~&u$@=P=cNQ!Oap7ZzKS*EkHZ2a%2_SMT`2~Kqt*p-)y7kzIxvoe ztefbU6JJ;&LMUS5W6M$j4pk!-Z+s>S8l|QK2Wug49=Nr`P z7K#&9XOv~eVUmkl6~=OA&oN#S)|wsYBSWY8cm@7&Toha4)T;& z4unP!AH!u^h|31(lr%`}e{^GPwAspipZPq&DXhB+S`BktPu#41>d z%M!vHu8Z7qSElZ_38W)>*A6E@@ zh?QA*JVT0k&CCo3v0;|yxGfVKh|H3&pb%tg;@xbL1uDCRyl1kGgcn@4{(&a4%^KuX zU7CgIs$ipN;#}$faP|&Nny|t5-n(Ple#W+K?%1|%&+OQ?cWm3XZQFXr$|k8) zs9U9ztmqPSk8-1BHF?p!RtUSxbsprhT~i>TSvZLNStdMJSbYwlW|5wFkb8tD#lnq z-^sWQfte=+Zs`(a&?Ak@p&&Md-!O58vf)g?8bb1VUqHA!wK$r+;~>pDw~-(_&(+`m zoEe{UyU*0}`Rv}m=ehWrP9kcq;wYbyP(ye)gD=74!3_){V7_rirXZ45 z?C-ZgFWeN>W=Cyd>QL(jthDR9PwrMOE3XDedTm+9w6)TgpBhFGFk$?{xI|W}4tqE_ zDYCXv9nYy<-7wm5{r6zv3VOytk|0VO1v8||*@&n%O!BdLaN0z%$VJ|_y~Y%1F=8%$ zVTAt@XX?}YKJIsGY4(_14XIOrt2SL?j~O<0;G()T1ZIGGC!mFXucA4FhL}V%ZaI1x zHnE-M`}_-}kZ`nW@=V(!tjJwf$Q5k-`(Rjvai4eq&z`@fSje)4+0vYbBpUIa}U@grkZY_Rz$yq9nCTM(@oho4RK(%rFUBVM(j z0vW*v-v11t9EC0SlZh1$o1#&Nh;A4$wZhs%P=8wJLkZ1G#5i+Ng=lI-4|M1olZTJ? zDKfOP2a-Pjje3{MPL4)1*=T*5=;mt$Nb(mFOzHC+<+<)0hgikcJX*JvMI_q}(as9o zD;#s0#N18>YNQVg&@(}!95r5GYP<`f8_?V8~c071%hS%iXgzBQK@9yCH2`Wrs z1opNoX!t1bwi=#w-_TtL8`M)HPeZ_ICUdp_Ms8F5zAgr$dd+})x-`aMXthaq^x=rTfym=EM30H;gQSFf&n9!lQrzJ=}aj`So@rk>Z++WF}s`Wj465Q z@W6k^;y7mY1+>lb)r}1L$C~Z=sk@h*)cAB*y)%Yvi>Zs?69BoIJ?3$05PYgE+6XW= zfo%r*B>s-3+i^NEVYTzRbqMnW>3?L_#d=M(&CcGu|0_`!)+$yBqNzSNiKlCu%>u-9 zn?VR`GU+ghAVjmWNUsyKuT~X*QtJw!YndD}{gLD}DU0S8iNUaAj^l|llo->QaApOkl*`-2MV>D^zA{*{)t3vPW?wYge_PC6bBWNQkv zgAsk|^HxZlO7yBzqm{mg2y(fZl6^aAXCH7OFJmH7GG z``amRF)fHHcKqX(WozX-`exNXvxtnwcf)#vTSt2H8u%lk)gXI@oTohbz3ZHqQlO98 z-AG-GO6m6kyZCe!VxpYAZe4@ZkmLd#t5Xf{YST!i-H?T5F6)$fbdphqJrFN^j*X4leE%$W|(b@!@&_6u>+cI{C$3y9o7k`r+cGTl7 z9ng7Zp%$io=IeXkz1QV+6{DMX`JpM!+>@c%5Uq2tVj0q<7Q1zy?D|}MA)!^4Y86|+ zIMO=f1IuC%`A(Pp20c6Y6vHwf6(djN2x3~mASQr_$Wl<8-nmFGp7v%;fusKs|APBo zh!Iq}&!-=~E<^X`A*c4rxGleZI$mks{*Z>Lng&FBp=7gRxI+V?NrslXrN&X#O7*q-AhrJf$g39sj~$u_>4Z^P!> z%`|ZJKcy)&jB}`KT0C27JT~^<@&RB-8KTHFjHNaR$T7R-Qp(DYy=aXOGA?+QZ?gll zucm1ta1z3B6M_qI(SSuMrZ<*yA_*yc%RS+?XB{XdFk)GC6x+{=tt8R}A=0R5iggoW zrlee1Z7C&XeC*vN!G`+ZLjy@GvhAc$GLnl@S8R*fLrkqq?0BQ0hiiUI1r!SuhV?{# z==H30L-ndfps7elIN{fW8VmK&Lx~}6Olz@&?6{i|8lMTy0#4TwH4sM?BJ>VrR} zf5MzqS=lmo$TLbBi#F}s{MH~B;2kr{2G4fy6iJi(gQG=19g;$wRpNhx);_AoD;%-x zuOZ=&+7G3Cr!b^_&M4jJO|F3sS>lK(X=|14IPH@nnQ}Syd>>Iuv7CX~AfJpTesk|& zt-i&F;mW-i@P^0$zTdG1FcxQrtO|w*4HF(e{l5KQ{?5XDle~MA9tz|f{yZ|7CawKI z7-^or{!fbS|Gw}3|5LI32R&!{UliMFPD>3Hi5Azio*31&1y*?JxNW){n7}fkHt=7L zB1n!TWleK16XY@^b^z=c=5VQK$B`kdE!nMJi={H`QFyVW^r7%fQAdzi3-Smvt~B*8 z->yYW^26WEkKKf~J2l>NIo%aA)y|bkO3F!4Way&A&udJ^SNbMPHx#0JGT|@s(Bo3d zH(l#%X-J3C!ebdlRQdahK9SeKQ2cANV^hv((xtAyf+f@HdPz3V#}?Y7^d)=!U3FfbF%lM={0Op<*ha-9`s)|S^8NJX>NG!%3e zyt0FhdE3WYQTs`x#~K;f_&7=z@A7;|&wnY6CETQG@!j2&ynSeEYe7ooA7HMfgiCJF zFCkxQ8H3rEIM@=#EuQbK|#Oev4_*?q=(y-d@9R$ZHWHf zI`g2Lz=>#fqxdL3JgQ{hEh|R7yb>CF6fL5#ETbC3k6)K>Jm?2sfc3U*lY|p?;-OEl zFm&UgPvRfQ+i=9krq8wvUa{9%J?nYt2T? zMJ&{~t=B_2H|s%5n-!q*2**`H(#&6(S@PqDGl**a$_Sf{piGJLfEHH`|BQE&Y0ta` zlNBIj6KP)KW#1&GBroR7HM%l4bhdarh&XR0i69cW%P1Sp49fJ}fI1;btvp8%?Pg?# z;~PnsCnc!Y*Ukv`D96}ebo;J#k|Irso?j`NR%WgV!mqD$lg8?S9&A#jUr;NL;r_3D zUkfDi8vFco90q>k$dr!cI^5HM0VU>s^uUWep*%eV0jMK6;h<-&rTrsjL_712CQFQJ z%wUyd(fy)tH(I+>uCIT6D|0#j9R72S5>AUEgfwNG(@t+LC0Amc*tmq9cs4abHT}r= zUM^ms1@`1#u%W61dQ=l^<6C_wePhA3s`R(=!UY>zx{$$!2}KHty~mffnxoKZPq^hMt&>3pSYH+5-fTn*Wtu>~Q|fu7G1TyNlH$00LFXcNt&q-*$Zn)%>j z&;MX)I^3hQV-EwVP&Q7(Pg8OZhxAzfltV`>dC zHWWN#at%>e&5T}j9D>1mB_<$Ae(WD0} z4saTFF$zhdw!lD!kPIm9^X;eKwcjOCMkZ1ovKNPo&#SXW_!VdZF+qnI9shEQZPDJK zAj$|WKv79ar;^K9E+C&bs4&1bP)ba)9K%1zy+zJQm@lory+C|guC5%*meV(f!R}Z| z<`>81-x@EXEQ)h(qFC^^Q1I}X+Ube+*v|J?1>HjCZvD(CS~q%!aP_j-ka+2}=BBykNuSpxn;OV@;N^ z1ctFlDYCIoFBIZnZv6)mHW7Sj5Uh>hwN1DW-!^Rjr{0vE<3Z#T1Mfh5xGo;%$siep zSJ6bt-xV8ar-J{!ZZC!!>NtS@iBwdsI1g00@=wNsz>CC{Nwd)gq~%Rg2L((~Ifd); zO;X<+&?2O?WA>aHonM)+^w2SKUy=F?4T}{t>7d*YuGt!N2S>*DC7_;R#1$)Ah-|6J zn3wI}Dj#D44#ra35``d`#{S>h3i+u$CxKrii4%X?>?uRRRbH{!aPgbeH-YGiyS5kV zCDtV0Oj(AkkpmzKzi%Ox7uTSd(B_jeFFF7`ezfQaq>4{;uOpwd$Ne!nh{$utGp9%z z#xkYjOYyRZw54;HdQ1YGpLeIVv*Zq@1|xrReNTM0EmVV4Mo}g>)TvJ!ja%bd9q`i% zJWvq3r+I{rmMeMadu#{WBcdP+IEDlY+b@LRKc&IH+NCTAqKyw@A@1w~2`?nr-Y^u_ zVubvl!?LFOop0H;c;-I8T5rWe5S>Dw8#285Xf7z7x!HWN)ysS1^SWTao(QJ8+hbnd z(m(pjaO!vXHD;e*5RL_Xjf@5`e3t zOy}>jcK2yP+m|Sd5P%zUSA&xMospU>W5ztCNLeA9=l*emvCb{UGNuZFQ{bJxbuUqF zmV;@Y=pMC?&IiNy$siZJoC3yf3*?!fXy<%)PU8MX!J zbI|iD7iFvD%wj?^Ri{bOR8xj^?dODRCq%B_vB_bRg~v=z4cX*8CZ*XVr{l*?Azk7% zsjHK?$J0(RT_QUqy)?ZHKbrg$`iTO`0!j9h?nk{7FUPkgsuC`dvE}@amW15N;!4`` z*upgqu(uPPa)L+;aT{xE^IzvdGOMk4Ja)3Xb@u1blc_%+*_ws?&)EI7N1UX8wpw22>kC} z@9%%@gPJ3rS>jTP07a(Sgpdf}VB${Z`_q~Ceda`J1e;>YdGfd5^0mE0>ii1o9|c)rP8 zPS}1uRl46)ZJGXRxx5JyVNWk6SauA>&J}7OPWmezLRVlAP&4-g6NuCTu*zum7emD4 zfPC)YNh;4VXyS4kD#*w<)c@(5cm;{=@qow@n(g-SIYpm@X1Ccd+8grxxY6E6t*LuG zmPPuMYKI-+s2`(CsLh4t^*dkoEsbNyde1~p2YEmKigRrYb`W7-1@}#HZ{2b;zt2gz zOzcWr<$Dwk4Oz~ssQ$6AcXMe*hb;j43t8KyMNdI$-sp+z`I->vs>i~9e8rFdy8e_2 z`$B&j++ze@2;$p*&we{O-Sw!k!*^l;hlQb`iL(87M7G2{naTytRH6<_-VdsIuDl|; z9Cuk(gKfq@%fvwdYuxb}<3Hl~ekIBh5EjHKm}>&=>lH+z+>Yi zDssL#rwD-KuQh5=pTV^#}X2gWvcoN+RblmBM1ikHYuD=nT8G>gwvvU{?C>ZfwoQr$A z8TRzCA02UT>DFt1ccqCc1gWHcG=23Q{PS9X9s<2c*$5o8WK;!K9q(Z9GY8^&U>%N4 zmMZ+h*tIr*HP8U+SlE)MTx4t#a#)5EN=>1yPzEt)Q-_|b3NBHYI#X(2QJMBk5f)q5 zH>0JmHyq1Q%^{Rgtu!eA z2=$MKW-v4y^B zJzt$ArE^JR0@q?3}nU4YgPYP5P_ZmGXryVw4?18|7Z?%^utzZuF-$&gTG! zR{bXq^F886p7%ax1q0qM@^sDr)K_{W|7J-4on&0JJUd##E3oXll6PcFHv4y1Jmw1x z4?W5q;TL3U47#B^6DqE-A=deymX5;S{UavqrzpmQ1zzSY5eYxU1gP{O9Ltue|nSvmO>R1@26v1qNK&Tld<0ELHMInBpnvf1M zhL1r7h5uqD0z*#_3JwoMctFNvEjR>Ikc|9UxkM24%lQ#F{h586d6QE=Ua7p^?r^=W z?r7E9k%1x$USmX-(((JQ3vk}GdJl*%c-FvOE_K)QTj))~O7%AOl*NO9H%*R$cf)2<23Y+d6-s6r!}^J4?~diAO@A6hqKqQmtmW$MqYkAB@MM{2S% zzX7jDHe(JjaZ1>QIO0|fF3A6?LJbL5a6(vuHNQKAm!3C@4rIcW!$dLl&}5T{1;X1i zj&Uo92_g9&ZsYq%D(V65<2lunZOq*|6sbzmMp3=)pT%~lbIFypy^X#FAc_ni2hO}N zV32F}y2YT1p;nREiK>9Bs;`%mNT~qYw^?H(%mMbDAN38j9cBJ7#;rK-Z$8^D`X`Q& zH6V>^wYuD;Hk1T1#@oI{)+K>|uXwOku#rDso_+PLbm?L9j)4A-+8V@86?-s)hz`jp4#Z@d- z6p8X2%Y2=#4F<;Dn*a~{<)-X4IratZkXCxjj@iV0F0d_gvo$Oljigwyv$$+~Psu%s z{a9R6(!tyL#yQn3_7-?nDophpSfK7 z4@o{<)^OU9MC3QHCBX%zW$RZLEryhIM%AXSs;7jeuCnDIH4+Q9C6>rv#&Zo=nb=!K z4lMY7{7?dPp}4D)#kg>Gco?<%xMaEvVV7hF%_XAe8x@yX$QP>wG%s&Me|}L?{h7g5@ztLg3Q> z3*v(&zoeiP$Q|VCvF?tlC!*tx-K7QP4YPkszGfSw3#Vt8i}8vZlmn;N(vJYaV9O!J zP(0{{+SN8q-MvQ8qPbtItz6VgA6iXyhY6vL^_d~`bmCCnfyCZxkiZ@`2#fKWM8MAE zK>+EQ+do27wlODFVN{oo>fz{PPo~1}u25lehj+2!47uNq;`r4_Z~29#af`gl^hy%c ztfA+PlvlOeHV?z|Hy@Cdr z!sWJ{NXsLJ6vIj929wFtrKU1^STWJY2JEtEm;{Ev^^2E9E-FZi%b)#eX5>t&k< zdxj0Sv!`Do6B^%9264fe&Eil`*92=0Ul(hN)PoxxP8&nQ0OX-WjCewJdL;C=K=E4KYH5*iHz(;mF4gg4_^MhgcumyAnQ2!~nRSBj#Y6 z6t5N2LS%gH`?&|Z`1_Cb$^5h7uF_|S;IkHq`|y92r^~nsQs|Z~of8$gz@;i(#Ve8A z8S-dVDUBMOjg42M@ob$Yax=CedheVDn&ej|PyOW!B87-Ba|k(+uHm&XhoA@oYt)oB zKq5>d9%cw_Lkqt~Wa4y!3$lPv9NVOXNT5s^a|ky;n(6B&f@2Ck7O{|wM9YK)xJ98Q zg1Etg8TT6StljzHg3`=vWx`_M^&5dl#krd$DKcmEUmfO9Nit+a8$8_8LwRBrg%KTX z>&=&elB`zG6a)kim=~D;g#}**fdR!*#i^F83m=xMp;dBsX(#AF-1`+#@(HIeLQ|noM{P20oF4bFrb8hZ{id8pA0_X}Pg2cTNBnhZGvi$47P#{txUW9u1yOb= z^*PuL8H9LaNkoyy${3-`ao3?Hku!QU!(QWXTatCjv;;3^byAB7>~_*+SbU^Qz3c0@ z2$Lig2HU;QKI?8EXbTbw-RhXza75#t&!+h9U&{d^Cx}~p(a?Si4>bBYrFkm;U+R(} zf(E=9a&l5n4LK^5a!LTqdGG@dI{Jf0)Lf*|Mf@X}gKQ`PLoNcU&7x_nFRgumWjt%R zzv&;>tfr=cvJw^T!11SJ-g4_rc`&$@V^WYs9GJ@IT-AQ}jJ1}Bhwa(x6SZtdoVQ_srL zQBE7YW@|Vj3V8I>Hc!{@u+g+^cK`CKwXrrp^mzlnd_Pw80zO7H)ga%;ig!s>d!Wav z=R>4$ie~+~XXhx{9nM0wf~|**WSLC$>=l%-=Bz~Sw6QkXrq?st#_27w*SGs?@9YJ8 zE=GxwicGZPTcm|Vg-mCDiL|IWghq%W4-2k432(TrcI6#{v=5sZ>Pz=Ah7lnC*b`$( znu2KMxS@F}3 z<(<0ILyHjaM+AW)o~?2l@u&B~W(TWqRS{cxnVytfDV8Du`Xv2z&5cub$hbW+9Vhe7 z>$zg{QIT4zxLlaJD6(9sBD3{DJbu_`lr-)vRW3eI6I{!!Lvccex$vU2%Fmr9RYxHY0#9SA1hwd~;Ym?a^yH#>4 z?{w(|cEW{?0lXwR!NP__765PYPLg~@JVgQ~V?T68pCbL7j@hho1f|i+qvx-Ey&+}W zSlppIc_|45I7VqX&=LL6fy+jdlC7F_!ilNe%{X4325M=5pvF!hgRZVxi3HiR&DL{nV9h+5fZHV7sblv+3^rA$wiN#gDkz!rxnbkY7=CAxbnG3k|4L87u zUs_Hch0pCSGEiMBAE{Q(b%N=S6VqR)%S^WXQjUD2ts0NYbVtL6pw`DnIoK}8jhgi{?tjP(aN-ATt*4$c^6A|fz+RY zSHwZf)CqQ4$gsq^yw)wJUK7@w`?~++lb}ZdbJ%FJ^amCs$l4r^rf3(qXlNe4Ma=`N zOw0hiqDN`OlP*1X(vP1(O9`6ky){P(?x(*!%?H4(uvFKI{YGQ)M=eSTV7r4bYsasj z{IuRvI7SI`S082MZl#xoXC&>t7a-5!pF__kT{Z)|oNP3=S}1E9m1xTchQb_tge#X?A;{{=chW1-cG8ivH;Jdui{n>N&m-#%Ynf>pzd%6iH4v9cuOovpkIdfe`Y zAvp?eZVasH%-o)`#GgfUw#I=?+u9W`Z8~EyEBGTq8vs{1GWM;?xF;@ie zN-DLwFq{;ew89Z34&LPfuB@|2p?#jvLr>jb#%jvx_#x4rJI(-~M%R&jV$%Ebd{!ZZ z`VZ)kC@yOV0>8~})|GBdOt%P3xMdv)yb+-N`wdU(SXi=a>SF1gvJ`}>u`>`((99AZkR!e~x z@3BTp^_Wh--B9Cmhs;|pZ>Q13-siJ3YuCEXr|X?F=k-Wgp0B;mglhGRjI+?kR{VMl zG&k5F!$U;B1uO-7Rig{Kfun*se*&ErG)8uA7z=fd|wU3k^S#^ z?lkow!c>f_cy^2o4?q#C#buit?f5}PXJJ&Sz3Aslp89)?-*^|J3X@uUc&!0NO!m;y zV;`=<{vC6hISD>DcPK<$0|h*dlp3l*CQ&p87Dx@^dM-4( z+XOOq=%v=>!tu|gEv0UFc1n?xUdE-(V}HP>Y}OWWHoi1cW3yH85wLZlwi+VjuhOs-dfhYD+Cts$y`x(2`}O@5M99j&%aRFFN=TU4-FYwU zJN$2#n%WdMc@z=UdMgC2N6>f0^A8Ts3wLj8d<;KccE26h7oMsJ`R<10CsV7v6Lif5 z8h!RXCe5SNejJMxhPf^Zz3}D?> zTgLYn)cMrJoZFHMChlMq*Ebk{a1O*PkE2O?&)*y3lwswd{--$=zwk|64_HT(b z^V8776Bb;~xZ7j+pNp)8hogD0;A_}|?8nqjCs2hSB2ej0(vQa!{pNu*F`z%>=P8bbTMuMN5l{!|)Qn zkbo+GxrP3=dx`y50J3f^*esHh1Z3X zGv>V}Rjq|BM1WGp?-0#|i?C{-k1`WU-4HWpronppgP`ERn@N;SV`r>(>HuU0+X7BO zu0K(`UH>Pih3?m}E+lRBjSy(>cd*OUj#x-CoJ$Gr4SNQ2Z~IW^^fpp)JXy(3FW_8QeEc3`=CV*b2ZGbzV^Z6Q^GpU`3T^|S z5t_9F*Oimeh|oX$*gumxLd?Ap67M&07##9`rcu2$EcbOji23nSlGJ!^y17+y0??na_pP6 zx!)ZGd_R_3iKV7jEqufOdO}3 z^&LA8=PVqoiuXk*-ontwaHs6((ygwZKo-R}YLjBX^&X9Il8pPHmDNc;??E-O(iKs5 zPTFnJZnRyeG;F2Vz`u-j9_>V}kYcOGsCZfqrORJ7T#miCyMS86y0B?}&tc)w&dJzP zuqqKCVY#ny$Bkshu~a7YcSqMJq(VP zIQ^aLd?NVpC$)GJX0*HccrW419K&Q=KPeeFCvtxI`g?aEBR2V(bCL4kS(G!Ho08*l zLZo7^S4RMwJ6oG$1VE`tc%^U(};S&Ju)ieo^j zmq^aKI<`tFPvu86Bu)t7SIf$0IEBT0Wq2Eyjv(jSML?C_^su~hkd-a17(i9;@w9&s zH`7zp(o$2?>Hv|0?e??N;d24={S&G{bIluw&CmUFzWxq-s(p?f;R7w?^}riJibk1R zs5Y7ZQKmy6x(maASOZ@X2?3ZWfK8DSN}fI_t&Y8=;a6jGP;Fw>6_Y*kbMML%090p- z{G#S3LzQ6H=Lb%V4Gu5H@(Ev*H+wYJQ?g3BwNU+ARQh6C~%I39Cj5`Z40MDW38nda>o^h+RzEMl7p+mI` zp;N!F8j3hDg1x`R&A8XOA1+!UZ>mEndgSN5zbD_0!pCQCM+#a2R^fVc%1p zrJ12cVv@)0ezR0AKhrpysp+h8)FX%AdZmULhcDZy6jIT2c^B6F74b-~bf_y4Ct?or zP43;^yz%>oYdlb zGsyt`q4f^^(PgdY-)`D&W53Srw?H=2%*Ux`k0&2yzA2aM;7Z7}a-K&aVPcpE1q!E< z3K9S9H5@!3+}o3ND`gE=7~XPmS$li8^hVd)m#AL6r!j8 z+J)no&9_0|Jhi9_znFhWL}l1Odp;njFo*{9DPq(V#w7~PcTcV~!ibGOeQKbNAi6B0 zeIfT0&*mbi{vuEu#P^qU?n3`W?zN_Koc!y6`W8=HW>vNqk7rfl(3@O*0xLG)v+oGq z%B2cF>UtGFa11q^-x5Yz-u>_&@1N5_o8ra|M3`j72TId_CQ#}4Vlwz$QInwFUs13_O6EPJr7qRH1 z*!gIYvgYc7o#i#8YQ?oo#_HXN^-Y$?Fy1=8PJN;0D25UF32a8}n&)YrY5Epk0PUCE zO#y>eDwK?W`e5zB>;1OV!)+Dr(QxiP-V?lV&%WAo>_`J}qQ$JGT5M~%Pp@w;oA$9Lg7 zEars(cW;F6*f%WO1)OYtJ!`1jL1l9)JZ9K_+ZM5@N5PFok(M$#AB;r7JkHbnl@hLY z%*Vz*L~{p=OmE6}$djMZkDpy~&-;6K0rmT!Q{J&&PsedvRV@~GVE1&7kch7jSoaCX zPIf`c6@W?2NB9vxzJRAkq`IB@!QwT+V%qsEh+j0WQ>}qc%(j~N>p1nFaPn(XMn=7c zmQI&mv`9sk-|zVHWzKi4SO2V!O0aUR!Rm~11Dnp2@|xSoVt95Hx_D6$H5Cw7Wx^;e z&h%e>;HpX`Pr+V)WEuP9I`{Qn7-_a|9!p8$q0#Fw`R<(!gC&JTCs>+zb?;D4GD{+7u9mf2>x&r5Y6$Y_SV4bSSc+Rxt4v z*7MG*e;)?)57ao$j$)K>rP?CEd^-heKo)rsl8Q173F{X~F8I5x=Ag@xF|y9n*n8{CwR4`MFmytMhR& zN70A6FJq=;-p;n;0!rM_X|&|#4vcQ-Gi1ta3m)0Xc#21bnniPAMrG8W#R`4`dTHiPyUwN zFIia#T};XW8bqM9Fkt-e%zy}M+zFvkoNpMrE7nz)>h;HtB5zC+R{3(0xnN`Y>iL^8 zco4z(0zj5|Lq$xOSXFf&h+S`u#dLBpUspktL;|sFF?Xr5s~!vyQq*(HQc0P-!g9($ z^~C3{@HKbRF48VUfny{^8-qbiBn_8V;F9nTB~rzdu$QkVnVfiRGFa#law;OS>UxVW}m0)S?Rbj>GaNAW%4{|%uxGYJQbG!aBDkGVf2+d))6B@xcB4?3J z*#JI`n!z#xrwqxJ6>7*h!_!@kClo8sCF_=r5Dq9Dv#e+skHH^7|K7S|WR94cZ~Cb| zxcl7}aM9@6Y_N#TKeUM{R9Db#VG$%-NVB@vV`#wI6b1r6eHds012-zZ3JO_X1mN z>j*3{27G9Jj3EOh?z-p}K!{Jz-}sZhwNJ0#{=oD2!P5GeUh%sztv9%g;jS? zp!~3vv@l>NGZA4XwQ^A@?CigroFLnvy0X$iOk&4^er#1N z^&~2c4Svd)Du%sjU2p2=mXadK^mGZTJjnYKY%E3DKA#n@h~pzS+=UJ|ja*?tc*OI^Gs*}#$Gc)d zzLy*HbM*MJ!E+B>abw8M$H9m-Bzn#a`DZt0P4&6)f9rHvw}i6bmyZ$U_&fSvZdbp& zf3HHde+4_tBP z&SZr={2XsT%KU#E<^6v?lgGrw$@;(E$@`aS@zGiK zylr<+J7ORbNI5y6wBRIre0L>ZF? zB?GuB9g@c?Nd1-SOAj6)zf-b$c`9b;0ybL;>t%u0v3=z^-$t9+WFTQ)KE3GO%)jJ3 z`JMVqzRhsCo7F%`K-Gg#Nm)F(mII&iv_E(OTbPR6Ew(R1ddD*D49ExEVW0E1kch$I z_yMnKfZ8o4F2_G*DI~!_Hln;OrbhFRDA1NXKyM1tKaX>yChP8TDURKWLXFAO_Pv}Q#&N@>#pib}WWz1fJ zpS$^^uUflz$QQOLUUkhrbE{RNUFgYIxFc5>ce*CS7FC`@;AfYy2XOS`@iJ8H{no2a z887}r+T?AvTTL+=Lr7wRzaf$AP3|Ud7qiur7Jqa5CuhH#YK{)86S; zuK*XcoBoI`cmn2*A&>8S3`6;Yfh+4EPeE9&YE7Et0TJ=~)9GeMM;du=)+k(y{WtM; z;j4H}<|{f$nZGb{pKopa!KJ47hbFTq8ZE=NWhwNxH46L<)s2W~$kGcE6ei`6{zQoGz0Nav47Yk2;WgE=F0guxUh~G@o&&;0Qjf4^o4!`{5 zd>Z&mj+t>6xjVsA@BW4)mNBcN0I@2TK3V05;*ECN<;TnFf_|5vPWaZJQ?Z=PvBv~G zkQ^=1d=;c-Eu{Y_6RpV_7w1OW#0tfgbXA0wKmvv7?z$pZ0kX+s<*YW``qwhDKqF{E zoCw5M*Z|#3aDG-eYfIy3ok}sKwqV3!B1$x?kZ|q(FeL?RQ?pujLI_2osb2KQd=;wx zF!90Hxv^%gP*-L`?)<*6AtGc}C|Dnha1^d)JE>Qs@bSM?Cn7ZW`D!RJ;)TPzAcWkZ zVjEbk;W(ttVsI#|t5(TcF~R^!IGi&XvNG1dwmpd2gJQsm62A*Lf73#Wd5n`F1D|cQ zQa8eQSELEQLwS={u~H%H9FHnaidx}pKO8e5 z1b$+N5q}dmSW4`@;nIbHLNelD;$1!&dsIz2VmI|{7-gi_r{Sklb$}s>EnI4}7wIE) z;@bS>-lwQy`4Tl9P>#(>%XsIi=AxJcp;9ukq#yxa3%<6(92258%{m4yi;57def^Jb za8I}pF-~8bR;_xu3pGu*G7@(u;w1BDY!Kc5KyQ^^=Ml4(q+;YYW>WB7{~A9t2;=Ye zm5I8b|Bbx2j;m^E+s8pf1Qb-1lm-O>VQ*ps64E6tB~rqsOS(Zq5v5a7k&>3~5JegU z=?0Nf1Oy3*-&%WZj&kC8p5Oa@pTFMoImpbKnS1VuHP?0BYq2*xSmjZ`kkJ6Eir}3D zdGcbJJf5s1=?i(f7I5D6rK;@M@F>???>sc|J>oivIcd7d8w(fb(t=@LnU`3#f=C&z z;IH)D=`b%<{tDA(6*uXL4_44J)7XNChfUrB2AIT1D{~J?a>^#!g7Qo?IKEMW7zTnb zDz)#dUu%`9=g`ERtnW9!nkr+$UCCZg=}p3pj~lBMv|}snK}tL=#vkWmYWQ^0@I6(h zdfTIZ>;7R&Uwz^>OP*DO0j*A|;q81L>etVMFIHY8u}|lxzx=Fer6Itet(5BFehEx= z-+Crm?Nh{(l>+cLuKZufgVl&iZX}A^^xw!ms2SGjZunJGAl=lmpOAZP;Zja zj*!uCmkyW1EfS%ylAPI!-N7WyxJzNotMIJ3WtO(^w)$I|wNoCLDX%)%gREbV=n>Np zmk)mnX_u|8ijCz;_eg6=7az*y;=9GraQ!KaW>AtWKkXLIx!B0Kjt4-~NA04>&-ynD zww6>M=*MZ+#`u)OZJabV*CPjZ;lO}XS8eU5dvtB($)~vWL@WboP|u zUx{M6FVP8BW8Ap(At+0b3h_)dW5A`xm$xZIlS%AZ-I9j?8K>s&a+hmWSQnY>!>%pT zrOD<;Q{69B%1|Cr!HLP%QU<;#O91X&-`OLwaN6*SQ^KJTmBmf;!R8KE z@0C}N@G2~Pn9E3Sgf%P&{DGOx{mRQP>R1TE2Ong5NzOsUaP@~qx4 z+nCGOs%UN0O4TVozzz91wapq^Z4t8(B`8BJX*GP8Q?9~@>En%Y`=_HpXHvvP)JT~n z;2)iDonO|j7J^e%u{-D;{`e{C`Qp{%ukWK^#4qoy*R9=NAg#3C=UQ#qU45N@UyqiL zPiO*1gHwW{Douop)X=-#=uwN$Fq;faz z+%@dp*nTrRYnp!j>BY5hvvL7rOha`I+85zjcX7yRU|y4+b|ImUfDg5t^sM{YfXnjO z--M5j#7A{R^89krT-88fcE0qG6h7UwH0dnqH%u!lyVa`AT2h&~5b>=abeEn;WWQe( zzoODq&7d-S3NS(pJxV&mf zYiaLGJ<>j5wkDvbQK#K%wruT$UbnZ*{o)yAWYW68*=+VKg=l{SvG1;~e|I5=oFB)v z4!q*{^ZtGk)2i=8+{;52to!z>w}sZoJgX1<50HNPrrc*J4u&f}Y-cPI`%85U#!;8p z#uOsy-(Vev`X7p2d>j6gu|C2ZGhv2xagKa`>g`hCiIF9qZV}o`tny(5=eXr?I>v>5 zj6JsgwkVYOxJM!=4Awx zBie`frm+5Hj ze@Z4%qslOqg-lx8?2ST74ExicmW!P}Fa0!wUOGW}B7|Uh$?B~9vywgo#JZ?}wLS8J zy!>$B9X1C3i@|40J<`TnZhTRQRh}-y*}hdJGp&+CKUeBuD28*G(=1*wK%_XrdNAAi z_=9P4jrt|~FJ~Q$-W8IY9dvb%0MLV@ILrpDdG-QnGTb}(@dMEFq$BMW6)uXB} z&=xFocWn`PJU9Q|HndcvWuNM$l`EiXeP69iaycJYn}x#NJVKCJku8>=GAM2j*O^!K ze5%C+PUU>7Tu+_v_UEBT)KPrcyc$VOX>%${o_Kp&@EF1$tLz=!_5v$y`*h_v>j@7! zd3$7=?sT3{7P@J$-hxN=QuG}E#bN(yt#nTJFI5j?p35LO4RLoYgZPmd-kywZTM;Su z#qQ$p6SrR0_Pf--Ab;8!sh{IiLC zeOycB32iz?>D1e^KW+PHlii)a5J!n{yAkC7yj*NRZ#fiK4*uKHWz6Q|)xfJyZcA#* zK1JIw>vI(|6XT)$RNI3{rc1S0PSG?c zX(|g;K7YPfUJHAE|E-;UhM~lerm%W>iZ_oE1=ptOJNyD=3s-!Vz6Zuib^G=?VR}7Z#S6 zvk6a<|IE?mad=l5+thCELCIE^E#31;ejuYd--^6M!dLf0Ojf>)wpP-YoUIt=kiMkL zxyqO!2`%ie5(*2a<6vB&0$iax<7-~_yv5T(S%xubs!xr{x%yn=&3bP6fvM-uPIYpb zW{7Z}{q2(Rg|jIMP0bUcZ=PCnMi&G+CJ@}^QoS_La;>9V((J*iY8Rt7QyP{)G@qm0 zs=q=UYobo#j+l8xO_-T)dlY%CF`i?FU-HrqQ#I9_@2#c?2PG3Z6SO7o zwD(h#_viRXA7nd#b)2n=6puPU#%dmpLzYBisF-Qvdv|(PgV0Nr{+&MTwhm=Al*5UalJ)5 zFgmI@gzcQ}mYHU7lQhb6eSL^QS{EvN9}HBe?_%y^xjP zGj<;RIHUD*rZ(qpzmA%-B`-(#xRTnXE#p&5Z`x};IO|Pp59*XGpCcwBnX5hTT{{>2 z&GMDj_=U3J9h0eN?KH6*Y1Hp6D>$T7Y}p)`n9sb!b?hlojX#UqLKhw@aiU22CNYr2 z)MB7{a?&W=hxJ0(?-%1(7wk`5jpTeG`;Zdn19j}=rL-O-9=(hKEA#fjMGtShI$`X| z6yI-(ja!*hKUG)vfy=iiQ0b1X;^DBUOot1%m}r&b)#<)A-H*udG>*@dBcQyArAqiI z>GAtlx4(~K@G~;-NySB~aIn2y%)sDV`E<%_d3SMiRx(p-)~teOw9L#kE%!c+7U$CR zyPMgF@m?hxxsogD4#O;WW|LT4nyMaC&Nixv4T{5;Z@he5$2R;)UoJ}^MpIZRHp!c= zHwia)@u}0m&Z7mA7Z-b;VAS58x^=L*C!P_RDw2Hh<11OB`1}-m&2zl>j4IQNs?YXl zi0SG9|6*jSRNnS8?+087(QR+}X80T`H`_`FVQt#ctg# z)qRcXn9+N~nl_<=A9h`=6oZ>$b=5|J57nF9?OJbB(~i%66yG#WnnJ1_-R5Ots+Cm@ zt8sHp%jr@~m)*K{*pYL3zb-mdX<6w~uAzbC8!=;g-xETgaq?^P3FdW4wi-G*_Hu^W z8uV&0N-nv>F?A7=MyjW>o}Ub^IsE98oIhp5cRliK^;Cu>8HKayLDeGtUHR>YTiq$% z@iw3IDtb1WsPBC%d#o*Zcv8(?V2l5d&O7F|vZ7j2s_`;goE10CDJfDp<%B?3UlOBk z)H>4~>?vulu^BtE*#j=-Y}|2`^K&HG_tvL7M!*F_p=Yp^jyOf=G9U0E!9Y5WKwIk? z9*dmx4?SA@*Po_>b;z{iR+zsh7?(L15tj`p@#?*_rcM?{9=v{0WLT1J=IDpu;oyv0 zusCh~iY(c>`hY%CKINzBawm(1U3tD4skXXqon`KepFh4Pm5I9}-#_FzY||DlUYQLA z94Bb*E*5;PS%af)WSQcs-;Q-VIV)=9e*H}q>?hGbWMo~r(+ta)3x^vh$8utJ+z)&v zN*{U?vii#&+R%DZ_&-T97m(1vH{ULPOMp8%*`IVx$7=7}jCs=lsfIx?ZaY7os@He( z@YsF-@ye;0r+YfLDHcUc)4c~}vy<3TelBdMSX$)P7-z&TJ>vwH_ zHZ-?pvyZ-=@acdUw}bVEcYC@m+KBbtoBtihd<$FMo!Le!9e zF>!MBiqCJC;t=aSoS{MzRuL>i4EvTcBhx-o32$HUr}}WWB*eE27G;j9(T>JX4+__% z&(8JtB~6UqsKiRV^DPJ0S*JZ%$8;u@TQH|-)Vjrf&CK?EBkX7Q!mBEN@9d1bxBZ?h z36S(prILe5b6e%J*RvZXxGS^-+D*vM7gm`T1^#Q?7RN&eqDq zIpUq`)8Dwpv#&|t9_dup<-`nl?o?IiKW#aBa+9acL|dZl`DVA*J-I=`na^RWJ%Kfa z^0%*X*N7r;kjIhU^tg(IbDo3%$@C4(**ol!S{Yz~mm%e6&!x{f2|wEdOy&THIjT>H9%FX{Y7?;h&Z-_giXK z9q2Iz;~w&VeqP3P{+ZV(qwoiU|KR`REuychL|;i~E-!|^61%p)ey@k{mC>9UUpv*I zi;TAc>~u;7o3RY`OwjFvM8;te13y0r%}%E%t=$SNe3%M8ercXqbZ1uoi5zk@w^`+EEdS2OTQ zT0v5~!c6gPx@tlVflUJ|Q`D}lhMWY?y&$Qb^@`_TKB-COl)mw(r=PuLbi&PDZGNvl zz|bl04wtxln_FtnlIxep9)*O6foAQ`Lt45c_^@EN=gNw@FR6&HVg4OIy#2D(eqHu_ zSZE_=+2rH)pOidjpW>JUu)gg6v0ey=*^)^~=Ru&cTX8Y`&S3^VDRmsR`ibtIJL0393a9DR@ z3qR59oFtxjlA(6`c|cI9q0ZM$XnlNeMln?-MXK472~NWLli&AC6b1_fKA- z#<8?~#~wLPuXAGh@vtO)y-ioa_l?GpH#`l%H_c`bRn~1~91O`LbPuTpvmALT@(4+5 zo;B{?VnN*BH=W(C3!xyiysJ03ly8c6J8xNz=MBF0^Tp0veV0D1UUoO8Pigo3LbG!6 zEvCGWPy?wx&J@j*bpw{qdyK0X-LN@$m%!B1_|xGEarakaC;QD`*vAjVr@x!<3=tGj z7B|22Zgk-3IqjhW(Z#V=#ivHD@~-kD$8Puf}~mUkUqZoM^+r)Qj%UqCck zo#IAMU^V(#dqkyaSf4>~)noJFgO5rU?>5C2F{@Sg;xzNgMzM1$r$zBZq-lW+Z2(Q$Isc2kVWOyujWu90?5l8#nfXdjv4#-L z^;v=Z#pEl|?ak^6DUJcJ>;u`QU;61OIkB?x#ZgpLyKHXMH9tNucXunvG0&oZMNvvn z;<7xWkZ*N>w4xa%e)2K;@uBw95$DM}OvJZLNcV`qNIv&`z}tj|N6zYJH1)>ip%EMG>BO=cjuHKCq1jkDkoS z6UZukA}RMV-V9gEVOf4`%!3+%SjZ2qytsEQnywcfMw-UbS`UQRus2l1_+{8HNsAMo zPP%_yrOP<+u~2*3d>Y)f{BHA)L$a6w+VLyGDP}LLk=o*cTru&{aw9jc(tRxNq4#EOjL3t1U(%O1)SCY>5to@?pYQdyd-?9Aq|KF)z$etxbe;Q`=y94-JrAB(Uw)$Q zP;IU;5U}L?S;X2J|C_@0Ew;gL7BXkcPrg+1@F?WIHuPp<33-2c-9Yb9Ph9F}A6EN? zz_K+O0BHCj8x`S%z2dAKQEX^we+E>Z)w_WbG5|H<&L009#yhB zA*%3?%b(3QCETgAOI9mWBcr$_*i^I&TN>U(vMfYf+v0V9*Gkr6+oVw z7bDt2PO-)7lKhu?sT6O#Pb^E2bXr5)lDDc_CGLv!0G?VTcobmGq;Bd?0b|{btXZw<_TFp^55y zW>-M*Sp$l5^0bV^?Q999$cw{)K{Cv*4ei<~h2x(IcZaH0cIXNp7Tlfe6P~G*n$tDX zy)Ij1I{*eR`xT1+!mp)aysse|Ls`1genC6^7gG z?DZ#3QYT;8X^=UNJ!9PuOBZIB6E<3W1SYAAHpF7QT6zh! zc4>dVC^x?tz`1c5)?#9TrE?a)`}FY4%r!pU_iPV7TW|^@2;Oep+8X1EBi&5HS)zYt zSDfjE%(m&@QpwR4l^>-3k~lG5GOaK5Zufv+BbE6a^>P74hDF!nU5amyzAUWFxAYIq zt0zSc_65{httC4f;Jh99(7SKVkaNxTT-EG@11O>n6clxctA6&mVv z%j?aDnO7mOT?o0`2iw$Ld}ZYB;;XTAK!`&n-g3W-qfJS2T7!lA<`+?yR? zwCrO^={n3$!-j)OhUH-uIo>QIXc@o+E@~fL6!U8SN~6ZuT_LeSV#G)%OWq~pzJ;70 zs$)^toLj(=KhuQgoFKUcZf1!!duOt88NLmgf{IqvIFNnCSjwd0H6%{y_V|JBFWe0VaM9MXD^E ztx`mnWZM+vSPaBlm_9D;5tvS&2?`#ad?YEh+_CKD62PW8$Af+AO6{mV;riV{1()PU zROE@?cWg)mX%n7LJ&L{-sbeu<=jgY==a1_p<#&nirf}!QX@xW#iH_=?+|y4;rgg+! zNX}14_&cBfa}xFqEDLufSvG4+?I;KkT-$6>^hp1HLi^*ZYYTXa!}hZ8Ppzm{ON|ED zju)BMJkYqdqhi8;82SPUeCSP@!h@V7?`XH)E(QT+sru#C{WF(8JTfLJ*y#-~$QNpw zPD>3Os_Vu^91sds8elLC+UZrU60a2a%efM5B}f~7*dK{9dVcSG65o&N3(QE?9s;=% zvi&ojzWeqHW80Jy#f~9_R+?qgG80d_u2d>2H>9qH?+7|Hd$PpNOx!F`*!I3w6kzg6 zmUqd6TD_7mR>13lmWc1yaQt6@;CiR127Weogg^cj}--#`62dkL8Onxpo zp3|&Q_V9q`;?)xqZ@ci3tD`JPYd?}C3Sz3v`f)PRAgownxwoG>r$!T*4?gHNcHP6fSZ%Y< z_m~O=or9{xVyN`z{J>g?KVhp(pM(h7gz16rDaF;tSv5{m#Ju5CUbLQb954XOnq#74q-XKX95W0*kFJ0duyO`n3I(W`O`t3ud6hV!`yQc_#F^76G*hRveb`>sA~ zH{TQ8yO3b)@#T%C*;j>!Vre*WA&Xa<#}DWZesIX-v-aBQD!wy(Iri1Wt-CzcfuP;+ zWsIYki26JDbAb=l*5NyHZTv%_>eZwH9*fpa-CV^_dt*j>>@sMmWx8_GrqR#VxDu)btlErc&(KTS*8Iz7wR&!p>T$hpQw)uk`WffQ! zlCS04R8Q2&xCSrg=umc&z%f}e)szo48LpkT9Gv1+n{THKdZ|?Eji-(kkiXz2!6_Lj z*k?E!Ke)lZ#Ix+hIKlqIRMA{@H_oLVoXd5936Epqao+ z!N(gi8?e-;(_X0+df%V_2t3)AS;E|D5%g1;C%0m9HSROFm8`qC`^lFy*C^et>=qi| z6!S00lDxQ;Be}4@;K`YO>*oa#i`O@q;n`8imx(KszlEua&qy7nE`dW)AhztUuAhMCBTx5jU%OxZ4zA^KlnVBzWK(x;@$nKm%IBj`&AUrGmH7F zTQhG26>4#(y6N=N8O5dk5W{4=S}GM~prpv$)I4f{dDTp*+?2{6N%bL@I}7;3i%yQ* zsivY!dwBaVZAM~UoJ88+VP4c~=`)-Tycm>w^VR;V9}J}@7Q&Ynq852giF0qd8#UtH z{-&|-=hfhn`GX-^GW^o^N$TPgPi5;T?cTaPyn|U9?0ZQc_}c-cM76~9*|0R`TUv;o z$~XGOcItS$`=>)y>P#_kUdv$>pEwx*j@`_uv49_<+f1@|@jK^3zVj@b*b${9JHFF$ zo)2s<*G+xLue-^s0Hp6y6NS(NpHq&REBga`A>ocR?cK-hE~|8U=d{O2m?m%69$I-~ zN~VW4l8m{&Wn!1O z;7<MdEc2-Hx_Vy2KMVMaLwKeR7CmxN)OZXqz-qm63z5x7iB~xPl@a#&b?$djk z0j}9(JPUE3q{A;s*G(;?*XfJQyS}>a;zL(pD_(R$lQtLQG6#$1N0LO=HSG7#*m+MZ zDYD(ej$r3y{&_;vI-H#;_q57k2g&8~k^9}sr=(sHm{zoqu+HEb>Ct>WYrR1AtUlA7 zb+E7Y`quEu+79P9j{VgtLQDcI-Dkpmu{E}71;jl`_yjM$_K@mR_RfB16MJN@DrQ=I z#g(=wgSbb~+xV;W%G(iG1Al{ywK)UdBwWRQdNcga+dLnhn_GK=^hAN>m{%}4eLR^) zL$`_FJ~~I8Y(ple>*ASvh2(OM#8~_?nFW>u))gfl+_+ zK5e-m9HEl`39@V8ib<8BW}QwYi#XmjO&m!#P^r?1ZS-BKR3%4)qzde|JnCZxbV}xcJ}VcA8iLaoCTL#l3eDZcSZ|E4|Pcn)f^hZ zUr2`++qKsZ+85{!&peD&54GDJ$GXI_DKqzl%ukWujGiy_Vy&OaT%rTH#JcFBSs}LLTo(haS`HE%(QP6LvQ`D0!8KP=;S0n3{3GdmKuv5L#3tQa9b~^Si z)Sg@}Z@WL5I;-uH`Rxs7Yk**MQ3IdB-M(1+#m4gUW#-1h$l^x+S30uaJU1JNJ->XV zMivU}{-8Ct-)Of`UQL)U!yCIYH#oaDx%kXZmqo6eVEtBm#9eX=^N3kX8ME)-q~~OP zjfnCJ1DxKrV^GSywZGb=la|0LRdesLTlx#B5O+*ZxgmBbb$CtCMkFR&`e97ryu~M% z?IJdHz4YWk4i7dhxqLB!B7cFySY@EIGrgjV9BXwR}L ztH&-A*WX7nrr(HpKA&`^uN&7!+=EDe@WNV6!nEL*V(E~v8u8lRLdB3RECN=8`pcC8 z(|(`MRYqUF@=fbavQ6admTuX*@SKm|f0EWEjfqTzZez){d{465!#Oiq>MuCS_I~Sb z*}Gc1y+_~dy0@Y~9hl;}9?V9J;S>Zm?`t>=rnIa*iV4$Z_K2GfZK({^IUgLV`$31A zz14Fj$W*{q!dXx=!hIpg^sd%6LsLqGeM&7Ic?z?v_b%n+CLf=d3vOlfo0OPOLiPTF z!YUE&UxG~cw3K(1`3~OL)Gj|^tb89EHqQ=p>w)VobSL6x+occN>zBqiN$flx4zdm45t2^!+F6cUS>6Kgt(?Q5KJ zEqNCYsu;HN7{Ba{GFHy#2R0W=EPiWQYn^l({LWaZ3QPe$W97H&2Hle^t+f^6wQU+C z?n`bs?!X&g5eAo<%pYPu<8?NNyXD?j3$wXVrL$aT{q!_@(4z_yHHjk*_m)B-stEUc9Y1J#fjq6HbiJIB+4C zJ!*9FJkQ0E8%Rsms0#Kc@&P;(5`~pY%dxN1l`d4UmJyHm8(FeMMX~#S4H(IKN*NI0 zg6l-w#7;G}5B zXa1Qp>wIrJTkr#`&rzHwq;;a968R!ha~}9+ql+`w-j>r?-`vA|s}m^fUqQ0w7wCS@ z`_$UG8DTLG%9*R@Y;Nu`%yb4Gk^^<;dk%>L^=|IX2kMFLF}^KmnJb_>xHeN9SpRVQ zePI2A?M%Bp#lSNN*q&oy2mQg7d)zbilDQ(c4iz)7Vf)_C zsrZ~|yr^Dlbm4sRI1Tf((d7FY+S6UM^Tzuot4mS)LACIryxH9knQr)pg37G|x6P82 z>)PF96ra=*B^nmzMEQP8C2ovJbXe;+V1M5_bC~UG_`{h`!TkCwxprr6onF=NsUKr? zL|=SQC1xR>ON;H6r$-kb*oY}tl~yCn89ZYE<@qV9KO>$mE|Kh?K) zpWkKi&5Kn^4(r?S#`{*`zpgNqfKe^W^zBp~Ss`H|wMiDq>puRFYG=F2nL4qImaSH< zAHWB?2ugX~REXsK#JJ*WN54bs`mDycuUCEy|I^^7Z!MD%8X{YWPi8CbW0PTs7OEc> znF)*RAr&_E-M;Ys(q0j}z#B3Ik=m{9EmmX9>$>YgcK%}u6N)QSb#fC7&Jl!R!Zgm| zOxlFDz9-xEWBs;->xdN*9jZcDIYKbB&z_xa73o-Own(cQqGax2Ss`L-CgG{z7W znU&r4p>{VazmAbq%B&cyFl}90F1x*J$Q`>EIIiO(K7`=LtUDI|g#5#Qcj7Jk} z81adFhw@8*t2ajf3w-v!dq6%4F^ z5(QB$DFr1KRWnNq1L(S>ft8u1D-9Fs5;Jhk(!j)?27JFAXe26X<3ghi*k^;mXt;TR zA2=_K4j#LVgMp=)p@_AKC6a~%k6pyx5NYi|!^aJz!G6IE8yw7u8Q4lA%}h)kz?OLI zst!mibsAov08B}vQeZ#8$3r4HX<#r8peq%i(D9xFY9NZXNNaFN;KxHEt&PC%Zh*lM ze>>jaT8YVsgGRxIKu@9u_DC@M=fMNDR9)=>H)O1hZD<4p@Yq$5CT8{ycEDta09_%0 z$xyU2LfV;Go6s=H7y*Mab8rPNsyf=*S|Y8$L889Imt6yxA{g+4;NYRrp@DG%NnQ>Z zkmLlfa&yChEHG^}oP0nQ&c_WTxltvYV0~@`Sf7`V1_6}o(C~19SvVX>@`9CkI1peG ztOPvt1(JMlFv$ldVW_@%;9RIQstPA)9R{otPzUIk2L^Tw;{=WJKxLe$GL%&q7ubdi z=$D5J><|XDIO+z*%?+gCJgD|OU_EZAPXq^$=0rINL+}7;K5%dFfxg3d!Ljpjae!%{ zHsk}C25o_TaH0BvbAUFuIl+2xVA22|xWMti0ZT{y!{MkpfJI&eI6gQWtjCSu2KoZ$ z77mRAXu-w9NyE*{156JG&&$*neAx%vH@*=)j*vVfG#d7%;Uz@eI4P&+7x;D&mDp~{d@I|Ry47#!*W4vn1y@{9|rX@sr`%>*wG zWCikt6B;`gG%rSmP=7qo7|^~LLH!w{$~YmL#*j@;luZ~1WCeKR1Y8GWs2wNdH4^fS z6Y`83nip=UcRt7p57ZwwdR3r#fkQR9pml&jy>me|`Jj2>L7@6Gg4PIu%E4ghnSi_o zCIq!Zpqkv!__!gjxzJuiHVx6UgdQK{3$Qrgh&cHmE09fNI5ZQ`7?4m70qh9?G|+n! zNTKerKkf`eM>{*<3`gCFsQU%H56rBQf849KHnw2RNJeFUFI1^^}kr;$ByJVAh`0v=GeZPcvIz*`Ww2%bd8&L-fz z{Ppcdza08?pg{*5bSkK-s%whM{SSBm9L|S2xVeGu{-;C$4gdd&2*6OI``1JO4put) zI;UR){%r;Ri3l7Y{jo#$|D6Z`69ixiz)}F*Lt`xp8zDU9LQw=h6ds}Q^au-47zbe? z9K`VBSct-39`HIEzj#rEf)l*Xi6R$&gI}l}aeR-!f15HiesS?|{h!4zfN&niFBtm7 zL!i#hKb_&nQQ|n79Y>zy=eyxC%s7r_hR1N|Hw5|bom}wWzXt7Z@0-7zT*q&i|M=uW z-JyRzxd7()=acLA503xk(BGe2ax$XQQW7lENJ}TAgPEa$0@4u)ooq)+=8qy8u#ZW;uzd(fJR8^K9~0Qv$ifqm-GaDjpXG|UUg5%4mC8x%31izsOY8UVAXmMBBq z;E~IRI$D9M;0X2K88@J?e*X>S1c$};q90b&D?K`2jPJSgddO8?!l z4&E-ukM-X}0O(^K2Iu_0d#(dWdHh`G0BAADI?*f_ps-+$2T~1a*2x3$TA&J8hSmaT z-i~JR0NF*ggLpd^n)5=8lp87oBmu}zxzXGeV%z||McIV-DIjuCIjBD_h^_KKEEk~t zs2(6*3&cnCLpZ=&p6;v4!G68*#(yP zzo^OJ|28!E7iRPK@cExJ91yqv!f^f)Hv-~ue0{%vk2ar$zHsPq4DnP*imw+V5dXD%8L}XBrS5AQYfV2dpAE;s= zjX?1>AS4PH2eN+~=tOPLV~hd_jQ(0KG^5}J$Sx3vN5?__Zv{Gm(D|PU#jzv$NH#*p z;-6^3F%bXLVSWsZj}wvOl;uyP;TTOg4vv2!6wtwo4$S?Dq(DH8raH%|z;ViQoCX~S z@#8e%IPp17k&e>@bl?#U;>Tg;I6*^)QqeGaoa!7WMgKW$AE!FU!5{Vu9RGVV9C$eN z>lXW4$@dqq`un5sKL;!D4E{4%q3-nK_x|reqF;{vJy>Z;%Bm@=vWO$i4b&Y~4Xo|u zZLDpM>v5=z1}vljOaD;h+)zFALq<@M!$G|SoVJL6`Ir%WlK2N;!8rjlzW@tp`L6*B z4#ZCXBA__`ZAj#|P$KYkcE6q}{=@kHci{>3Bn^0O1xQBd0U7XM56XgQ1SbFg{-A;E z_hx{o{?!kFSAR7OfEnsJBDy~SvW~m~l1HAPf$Vq7|C9#83DC31|B3$qF#hrod>jZo z6@)IJGQWlb=lWyPfD$ekO8lc{?{Bm<0Gxl)*1&H3b(QI}u;vjEqZK+@HKJ8GT9ZTi0a-cH z!O*Gz3cXa?cX45Ah65t)Ey;)v!zJseRrs2%VK7BwOuTJT>a4F5Jp z{1?LT59stCGX@kc{)I986+VBDKmI$$ASJCJE}`&0kheSlvV#vrkN5&Nz!y09fPgR% z{RQIB|0rMX<8It03-M4&^(G&0HJw+Nr0|^8WrFRsF#CK;dtO-3?x(kT?`%! zymJBXM?nF2KtR)F(Q+!2|ij1Hm^Ml;M!C=s@xjL__01zodf> z52GIopsCprje=^TUkdsYae{n>p-B#!4ndwR04>zZK)_q0=s+$M69@7r z+j#6y*a3LPi+(EyViiCh!bNsy2tXdP_ZvD^k0uaIlpf&oPVJ_fYWf!xtw6RkK-$|qaP~6GP5UC<13P^A>2YV%?otTZ4t&KGp zx(3*RjI{&O&eq1#zyV3)V264y!0c~6q+1*bzC)#CU}t5Idfi9K4hg;mW@87u0E_C+ z(FzDvK%Ss_x2NF*&v$lJc>{Y38sOuLa>ip@$zQ;#nW-CJ2l&U57582P(?oHM$jfPK9o2KArZv zL)(8`Zvn2~z3ztYu(1Sf6C)LH^r&rM#_w&_=T*^u+KyBeaveGC@w?LoI!A4pM1FUg zwe4sk)J&J(1Z_A#Bf$GG04)p#*j4-5(X6l?v&r^{O(|^>;#Bl9DTV(&V9kJ|SqbX> z-KN~?kxiYEs-Bc&^t7A(-oXpLqb0r#>;q_(z$NDYe$*BVXd83Xmhf2Ht4D21Ui{vc z{ErpB3bYMAY76XA$UeBjFD@Om-FW$X+uc8WmIK=QAGOsu))woiE!VL{YWu@yn~^G| zgrm0Z$J%lnwavZx`y$<*J6d1~(`8W^H?*tEJ-<)r=Jsu9!|5|0vq}1gO-XH%YajZc zb=3^}eUX@&j&^~?uSNRt?F%MG0@|uiv8Si!*#n~5{fEK81YuN@qo#|&ed7F9a!U8n zP1G=2<~_Fe{ZREutY?WMZPG3Qsv4ir-m9h2!?AYni9c?`0?KV0LW`C4d~ahy3>Qfe z)Pdo166c45_W`1NySo=SDn9i>?)oftS=TLnDf;687(-;tXBW2v%W&>!19J?vSm$(I z|K*AYf3*Ox^pB73R(rFe3v-jhSQuV?eF2Rjf{9vhK<9cIa+6mE2VAhst6I0sdDUCG)Aq<8Mx#d5DmuaPMiH22he+>Fy>r+;3hUie0yCti zFfc9xr;$jFs?WG=y}~|K4IO9)qmQx1a^ptF9$<_4qUjLrw2vdrK6KNr05kqP*?4@c ze#04c^KHv$lh7@UH4uNTuJm5~2A)n0@p}ZE^}wm3)Zlw|T+jNv?Ncn!tY&1{^^QzM ztk8we2dR~)J0x>mAwqMcisRXjGh=hB8~&eBH&%l=aE`R3zNilOc0%nEeab^Ok~23? zpB?w~s6jRCnLr)du}_j$-k&@NT7M3+(!sd$b9c8lLcm`d<;SDFYgDiIMyoJxy~J@n zRo{9Btk)A-;D{O5;GAwkqzmSK6oAf1<=@{wQ)>_Av)T#Q*Pa0TZPt`4>Y$8P=*rRK6eBK^(qiGY%Q3Y?<`-=Bz&~4A`h1H`!fBClO*!%<&;z>AH)8oaXFvQ6kzn>&kZ zr4y2t^gU3tgYM#kAnW3cTcEiHJ^CBf6Cc*bfXTawqjxy@<$=FSpq4+KQv4#gL_XEc zHJ=7$rx^8?i&CgCR^>%Z8wlZGNrO)LmhpTo_NHzKn@3(dRbA(}0-G^5o+w4e1)vy% zif=aHaMP_{N}pbDdHqzu&j+w~n)!t`8Aq<4mNmTxvm;bXv7f{~FUv@JBrjqogc5M5*{#~Vs#UAZqyZckV`0nQl{H;9T{`TFG7cFbRU6duE?QCWiyL76C#7C1Tc7BUG51<6? zvNujwRs-`sXS$rv@>S)mKg%7iRNbNIm2bQHBp5?%Usq>u1Cx6@Ew4JYgu;x-w=+v;RAFs zwtdH$&1}%j2kVljn8t4GGfa$Rxf|0L1!2JW?t0`^N0lr)Tm`#`?){)orta#0jTsZ; zR;-g{mfaXorJ{YXN=~|34ofX6iz-RC`_euFxWf-*Z}d9wa{=WR>!sG-X3mRVHIzPD z*A7NYv_A>QCZWz}eGaSf&o!>X+Aho3Lg#gFjuh0b;+#<=#L&+#c`3Txiid%rk1zaY zOlw4feCphCO?0(x!8Jbi+60E>+~?e1S;&ig^(JH)cAE6ea7eXwiM4S}Y>npZivn$` z70HWERD7INDw1q^(0jd?Ej`bKSIP3Mmi_oMg1V%rGZ{sRm`D+I*14gl5du%-Zj?*6 zT?b!B`RGc(f^{G^+8R?*>#@Au2e-S&O`DvQit>BgfwALie)XlZ-Wm6mI{ z`X!-HlW5r|*VIf?vNa_=ElD$NQqPH~YwD};BipsN4xp<*>ibP8}Y0xO~TAq1pRYHktWnBFA3o3HgxoN^HjM5s}pO^q> zAdzP~U3$9;ckG0AQD={)G1=<{>y9q%AYIWDCVWmo6!^FN>KP>S2xaXeWIuDoL>eO^ z*sLU1;PRzTkv0#8OYN>#ZeK>uvBooUoISY12@4{Q`JPJ_7Opt{`HefD_sW6bW__2w zawWcPl)wG0z~#;Cj|k!$m6KS-q&R`{pzTX$GL96XC5u`x6k z7wFaPbY&8Zdn2rdKguQqeyxGAzmWAEz8BF-hbqTP^&gD#VgvHoc7~dXY{gT0IlpUvU#~jR>dXHd?5k?~t9bqT= zu4f=%YpB>Px6P@Av7mU_Z`?EW%9>7oQ3^{EMyT}DlXEI^BMsJb13x9(L_?PNuEdH) zDKKblRQBSo2EGNhYfO}(UZVN3lM*cSNs(F;N6e_4S(45~ukp%VCjlzlJMpZn3r7IBXCd8&4^t_V#!VrKY5b*t9M0Rk&i6Ycyd!|xaoZ_{8LQ6a_9_J-pdEDfmCkYKA5m2{P|otr_^} z8iV&mg|IrnXDo}u_IY!T+15+5W%YjE1T3>>4Wt7j)}kcVjXLg)Qg!W~2ke-9N zyc?=|Gcxu?nAoQJa9hX*1WH)9TTHY$((r}Wfsf$|n?HF{XwZxDtNTr>@rV%?agoBd9A(o7Bw1DC_5>e5EVw>J4mGlLg0q&O~^usPT3< zFzTz~r-WX&;Ek-sjZ|&2Ms)Ix)L-#ANldOYTpAnPP()Z4zU^V1M4JCSjWJDL>KkX8 zP@~+8{b_@e0Rq~G?UMS#IFr&I`YGuHUDbp+0L7Ny@G92&pkmTW8K1N$?c*T;-w2Gt$=oNwsoQsW%bkztoO26*Mjw0JL%Hi%4YG+FYY^-5DD@`Tq{nKs9Q6; z%Jwnf^mw)Sm-FGn3b|B^l+PvpWf6J~e%@mpFq29?lEjI0^g z{(eBQ_z2dF^ZI2K1qhJQu(h~V)kx^``HP?Edie$e;4B%clQ_$}MHs!B7Feg@)7jK^ z*`dPEhTb@swHGeGy294gd7AxEn6yW}8?hR-H~cj=m8%MMiQ}}ejvjG?9zn<%nogHj z))5~mT`$pf$VGe-Fnj&gObQUQX#tR2So~Xuju~QrnpBoj0EYIMd@A# zHo(1RXRufozO9LABf{meF*Jh*jlS_S-<>=hP9%CYHpNFKO3RnNIZD=k)s_XbWqM)# zItjH;3c&5}+wnw546zz8un;g^Tk?0R)y0YGgL$_}Dz82A>W$GEG+t_Ozhdg*lxF2t5|9G`f-H)7$sH)1D!ZLMW^h>6p7qJq3F zeAI#e#b zS<5x_7Iz$H1g;AeORWiCpd-FOL_(cqDuv0sTkc!p=y$P=!iQ2+VLr^Vqn^Uy{t^>o zwo6xMN<*w3dOrI#LsIHasM8weO>&GDq*)|7W1ArLtLGJN z85|tb6J6&j04p+1aQ?txtD&uOG1mV=XRNQpCTCDV&!ab_CexRmB?Dtk5zJwrwUcTTDjOo<-QAi(N9^D-WixL z{*M@*E8+d&+u)nkHzO0tL$p|GZ#S5bE8vR*a%&i4z2HVV2#%HR=H@#won5V7B}NLY zN8*cT1b3h&CA5+sYb{09UHG7pnc-L49Dm-%Z#nXqgtwgUdB6F?4xb!YODqIOc2$2# zKW66H^SCMSZ;W!hjpC-xd!}~S3-^;sajf;#h`qwMQz___iah(Bh(9`i?U4rn5~>C8 zZuX9ZlJ)hb2HapfQbK2^2k#;U2)-UmYCu%PXJ}uS5Kh%oSkppy+Wfm@?%3DEO6emO znf7lGE2K*ZN0E-cRUb(2K=l;NG4+Vg8myHa)5C3L`-vp3i^G%DRfKMEJ6my0jbz%A zGF|nM!UQa}*JvWdf$*2p;XY-RB}f$#vO|o)DL)YMvmKr=BIYi@@ZuPs`DzwY{TUI) z`UqKM{T#5zI@14U&Q@rD?Z zf(kQMewM7nVJ?e6PzFchU$GsL8+|CYJ7(rw!i$R%(t=3Z9P8UEI8c0GnW?v@>GJk1 zZ9jR zEVUC7n>#^Xa%jyzFz!}~-cK=dy8yi%S~=-i{-wrQ6|ClsH?xHO-HE$g{BsS>3#WNU zRLl8c*TY|+RyqFAH2#z?`mfMRxjcoD)#Sr8##U*ciMD~1KJH><>hE3_o_E`3ntVV0iY$wivYjQzk#k@ z0iX6o{D@@y2d?O&HaQje)Ndl7QQDsXa25K^vB7F+1xfGaEEfH@`y3pd6!8WJNmWU4 zO)d)cOo%N0vDP6PFtHG%veb4h&w*_%qdF*J)UD4wU(cMrkSbFk!sMZF`-A$W8%dIQDkXzt1cjoZhYDAC*CWy`+>BC<`}~W ztp9(OBOzyUIkB3*X|h15m2!diVynFXg>M5G-N!*$w0CtnB|9VK()??sB%h0Kw2LG5 zsP-m2^6D>zkm<3PY?>$dBizkP&n9s|ORqvLv*N)q(J?nxA3(eECqa_De4sH7bNVr0 z!ok&#YR#$QEb0X@Eiu~10GUR|V@}VAXLN%IEay*X%DuTw-*PEq13@ySrk{Kb;2kiP z4%@9#0M?<0ZOX6xJw`+)jR6`5dO*?SmJ`qcECuzqtX1O!1~r&njZE+h&d4Q2{?w>Wvc#%9E5}}y^l?u;D^!NctDwdF@Q%hx^quT;i>t}{syr~?(*I7=$ zn6L+c@Uv2Pj?Owu0@U_>7o_CvQ(5kawy z=r2H(4vWUTr2S72K1z%5e{HpU!;NS|CV~f~0+6UM6YC{1l~G4#YGyEk+Gn=FS?QVj zLkVZq=BLb0zwn zJ7`9HwhC`5eFW#L#u{eh+6o*n(#%g1IU?CZJ|EjnBu6#~%l@*%K>@L@@6B+YSplIC zs&vo=MyZ<3D%e)dJ*Cgms350lvKjkSU--a%79n)dDgf=;)V*r*v16NKqEq3f?Qls~ zEM|{@$C+x-H6vlnm1C7D1zxV zl(lbVv5fYR@=TzwS{UZGjBD?4&~lmf^)iaj!edmUMp=C|z)yEe-@+Y5Rv!pseDUV4 zZ3Pw%^28oOHqg_=3=cW>Sm!pLkqNh%h?3{a2)Rs_tHrW>FrisRZmGA%EULOoOyd{D zm8H4Mpd;~_V)P@WiWlR1w)r3N&y2(11Od0WaxUyXt8Pu zUc!WVK1WfNs9WLjc!_#tB0okWCFA``n7v?BlA80qriUvhX+WO=fc~}Tdws7K zD0A*D&v!}^YJt}m^5P^+(Wd0Dk-!nv;j#JYpBw4#JC;n!)I8{-#C`qh6NHp-S;w;S z<;DA9c19+ev@EFG86DJM5VwZsil9%;E~q7?ZNI)vkx4n+5aH`n=Exi#uWo#XhU7La4Zrhu z7)xzGJ6+h$fF^#AKGJ1fvx~A395PG3J~|$3CBGsX?3b3)8ZWeGev-XY1(@TJc5X!vE}h+)&$y6XFegwjqzliu)F{ zsX6nh@x4{6&G*V1-9`_@1TG5Gp36vr^)ewl+7Hk6a9Q1%z@{VFt66q%h#DI8MFm)x z)fW;7`SeXbIh;y4m|kk5xWXFXW$hb$Uq4j;Z}&d*QRzVEWc&1u6$;!&j1a8RW)B(a z;jh~qPpAKqm%=r1ewaIez6S$<{_Uqz`x}!*&HSz%>O+P>$G(^!wxKc#myRc=r_rQ= zU)7^XiJlGBce9@(C$}VakceNHLwF>@JhUJls3k+~Yu3sH1gT}&Pf=+;%vW3Og)T%3 zp=DlHVMBDX>kk-EFId`(nY8Us(MA`4>MBltXZTX79Ij3;9)42~Ip7IImtx%#lGv2hDEM5Zo0o%5VnObFh}-~^s*@%Q99cLPe- zjO~YLw40TcZ>>K!BctAzxxn^U8336*FNwIlC55%g zUu!=>)%;3<)F43uAUWWgHY>cBm%m`?HFJv!5Yac{VC6$c2A=xjl>Dly?&YeXj{^Rh zM|oOC5)J2jxDe6|o#uGfs+BU0oEPoGo)W0ner4|mUmLzk@6$Gn)=gl(O63B;L#aYj zpJP=_ch9cPd6)MDOA~fa&6Z=0ui``wU`okm7o80-`m<0KA{u=K3o0F+OVs%rso#mj za~abnxQX~{11nudS}TgLZ&JerAjKc?@rWI@VKFSq-f2z(+xG2T-Z6%~aao@ZqDdf( zLg?(-9dE(AQA5##=_B4HBDtSKu4)`kKOt4X!R!d)dGHW|^)J!Lx&_@(=Rsfkts;?_ z@Y}F@-pY~?7Up>ZeR-U835}=N*opYep8^YdQK4RuxVDVNkCWG>)PbY3#5gcp4<0A( zr-FwlVMWFhZ|p>U2H?PuDcB(SgF%YwR;}cG`5cpFZDZ1OcI#c%$SaJS6;2Pf_^6Za zOU5hT+(leUEM+~~z=h}UPO-%%7=5<5)hk6>uuk35;nPtY3+(@Rg_0z1U+We|-YxeD zU3PLaL4@x!0{nUt?rdXZm&3`?V59W6iKn}( z9+v+0sE>GuqZR|}{4`=tD2fC-z6N(KusR9#*kd|Q8GAD3fPXX4J6d*8QF3!J z`xU1ZH*gLAY;LHCs69IM)`nip?$|{4^0)?StsNQbcNQ%ocqYeBoI$u ze3PG}lmIQH8{ZkxbGIv!YwzfbY0#CT4$BGIs;-uHd&XtSX{yROu_zOA#jGw_390^k zIa=9m*!=V5tpq#hOo7i6C**_yXI6y7K1QUi;o*wHeU3e{_N7~$C-1G#1ns`cnKEw5%34)gM14SRRZuC;?E_ypYYWex))`cxIrsVVw3mO@ zuus%E$zSx5+iYIdOC<~%{I$(c<~#qP(U=;amR%~xfHG)d zyfC=&l`v0{llVkhQGptoaS$w`=0258?98lOSVv5J!>PE}W+qZ=UUOgJyw3?cSDAR) z_J`q>7q42SSl4DzN6|;4t#|XWy{EIh)bU-cPlNJjb>?})*7)Ad!#m5mf`Z5FILo5n z(O$vCFa#>rC`x1skI4WkyR^-le|YQn);PeZ4ZO?|cJj^|t6z~EY#*2W(;$PTBd(@I zwgw7Skby+zPv9)|TBoR`F;V)M)ownr_jH*T4dZnK-F|NyGhgJ1MV5KOZxFJA6VO-` zmWNK0c;?GCTnYT-q5~C&2$F^yG>xAU{_Ir%BgBT*gR-_3@2F*D!M1zo7je>)p@xZ3`O^>_3b!6V?5WWte&Ua^3zIrnWDP+9JudIY=d}1_sICm-MyP1usI(dTG54CR}k-z z#bs$*lu)o>t+A&mG04kKWeMC7b@)&Ifsk z1y(t5+#~WfXMX+qD-c2l2*4uoZYyb@Apa2nS?7&SWbvRs(u6=$ zY0{diVm76Q0^=O+j{>EdA=Sm%OL_ojYJm9h6eL$vGd7U@FO6>r>%O0))x6%@n;4o` zto}ed0ak1ofU(}DTfn*uhNSK!{EYz02AfUUUSfF~acasNM5Ir-2M2ZDb{k087Oi(NBP zL{{3rx{Nh6Rj>c(dWpyJ*Y`jAu*^R_=wlIR`9rw^fyOVfjUOv|eH5OpZ$|yEVZXde9A;wjzyWBD7NcZ9YJAkF9{xlc)ZzDrV3O2oOf~KWtvm`!%sRg7nG1U5S@GGBFM& z>K|f$v_;Uc`9JJNM~LR6YMS@uUxFjZmAAI2z@2OAzlJ4{>L19J{JjSxdCMOz$EE55 zL?WPg;azC_?N729{Ra;)HvSSSL24ZU$qjI!`XA=27fI+ghS~0e1kT0o-`qANI;tu@ zTh?>^%e*X&YQF>4!H;F|$n@XlshlYM>8tywzsbPR9me96@sFnid)5zu*!ZWb^<@6* zX>~=>Zo#h~|4PH**wv2dpSqe{DJ{$D|BU4i_Qu2}oPAXFlR^bhS6 zbR_yGAsPR<`@ZuFv}q;k@IE?GSyT0|n1QVRtI1O7-~L^k0gJW&8U9iXKvm>FstQ*{ z{++5fE9QS=<@IrB=3lAWs*5@M=RVl}OVb8Dfl~BGZ&f`eLF<=;8iy)Oq?41rM>AU~ z{u?XDoPWoP@3`TAnZ*j2<@F!4_B{Wc_Ya)BzxU?5>ym%#vN-nqcUpj$Jbbw0|IuYr zSM_hR9GfSI2mVQ2ko9GkYT5%3_CJdt`aLG5iACtcYa9RT8?1kb`2TzX6!?ZX!2Sn5 ze*QrJf28;WUrhb;8S($?I|u(CZvub;{{R2`D+*$E`Y!*k?;o?@ZndmuEnFu*>LD~EKlpB!Y=alQB3;>$hws!6EdTJ z@G$7a`9;Zb7MR3rKRn6EN`!lJ2sZ$*6y#+qe#zcG2kan#STJc*jpH83jGzrb#jafc zJa7m)35S{*owoi*LEUL8fM`=?AH|!!qU3UN9OFYDV`fJSFUTQ0xM{9=2*1!4H5dyMHyyBOc{7s{e7Sxfg<5ok0 zxBpBi?1X!%pFEoB9}ewl`xCMw@=QqjqwX7I+EkiH-2y_r)TRiJx=G2`zxh1smJ+{& zm$~YB)cpf!(|*Zz6dPz21n(OqH^}xFusfe9x&A=T#|UE)DS}`B4J06g`Zs#y>$qPY zb?S;=`sn@1feQjf@bgDeFpv(N!hh8P)jE&_68`ia8G9xK2gBe|9!N%%p*@zz&^-fe zDoC`xPdpLke{U(P)y&=Gegr1&x2E{GMulYhO&piR}JFMG@Z;B<{E3Fl)D zpl3pu+yfr1bOW?-U&K8I(t>>5-URE>lY8J8;rby}1z!pFZub5)8XL$yLQ*F7Kbk-= zieQ4r)?UK>>u^)$(VlmRnUF#KKb;+bC4Nbi82qPMEb?$Dx9{WOYv7Q>x#7`*0N_WZ zS=8f?+!bjgth_&2>_yHYg@anuwOUIANU*tl{v!d+PqRevbq%#$lph|+l8WZ4G&xUk zpFW^xL!(Wl@c&~OS-!UOPrTSzp3|4No1`0eF-ELJlYkCZZ5nkJbvVVF`@HgG-k0-m)Lsu;l?r)lP2d?!p$=2;*|KwWwgo8N}QYvZW z{h;!#As>b)nj#np{3rRmXz3fpN$8x zfeU}U6O0PHF07OJdeTh0De-C~99mXHV)|!<`L&unQ7zKzsomi%*g?K-xcl`_(1y3m z8jyW=q=!lT5!GVDfaL!;nCC2ej6*5;3Xega%o8R$K0e;%cWblz_1XSh`Q)dMfUiHI ziQmypY;-bnAf*F6N7X-Himg; zjba|+mvJmk6v0qNCUdonaP7P{4l|mpvCrczjN0`&p7Mb1cU1?k@CzMNTM?T{gnPTZ z>j=}{o7<`f^(Jw?;;@{N+Sk5XO%izNSzs0*`4vH0%qC{1WkT(>wBxF++2Ttj9{kLOFp9)lqdtk+h|p{w0+pu_zbfj^1( zr5ZTJng{m2?z{bFkhZdXx}n%^S6I#gb|5glZjG1nwywY*L-#a$B8;ag#_drup=?x2yCD9gvi0m#Yb>W7vD+qjgN2eE`Xb{15^}ewzjKFYQ^lU=9BOp=MH!2Lno>P|gm-~8u zOu|m+?p4Yky*tnp>|m` zJGE{JsI6jx0g(yaw$e0kX=^@9AX|qEoPrS;XBmZt&=+%#vVcHq9Bj{xS|;#)nZz%> zmKwQ*IV`H)Dw%Bre94|c1bH>C#m@gOPx}3fG#vW5i7-Z2zx;ARDnH(W1X$k$?5VG% zYpR$93u9(N^r$_?f)$M^a<6BTje!TJ7vFM~g;|e2Px~)8TGFZ9%Rb?3VR_%h``X;? zXMj69MHgObHn+SQtH0W&kQu|CN@G1ka%5RCUPrEXQT(!v6{VPOzgk@&-SseR9BgZ@ zNUW#uWpiVpr@vmOSIn@RE;s6nVSJt{&m#K0`L_lkg4tL3CfySWv7<|YYE3;J;9(qK zci+qxplI>Kq#kaVtX{GC=5%MQP`#qjrf6t$KA3qU+9O+-t7vM^D&hhi4&)^cwHOFJ z^Ht>8!hEOmI}`Gg*>a*VBGe>2QD;)#^aBk`S;aOM?9(Jg$IL%I)T`ITnwzN_pF6lU zA&Y2y%7nZQxpNY>{AyDB<9F|`_hpBaGA(nTkhwdW6`EU&c!0-efZ20P&s^f>j=O5Y zMiddXrf&TllXUPgpvAJ)qJ;5&# zidg?vb{YCp3+&NV$;)93d4793zHiMzaLu%;v@@YDBJKYWFUH%2Vt=8#jMH8t?1Ww-tYmp6yLnP#dIf zrr<}=>I#+IQSzD6xO-6#T*%Iu3`qN9$sY0x|A~Ri=PK((p3&C=5OJJt*HRggoPHW*qrE>dZ?^aAm%n6*%Dl8H)IC|cTb{O*?)Ziz;yJ2&?)l#{*{UOWCDW2r9)F-$IUaXS2W}Pea>eEgnA_DR z^ZoY2M)N+gow_+C=b<))Cn`QkN)4Xdidic!DlNwQ#}j%Hz-glO)Y=i@&i6hewZ5H0PQ@Ep?elMCWtH>0NLywN}g~#O^Fdk6|y6 z6`N`BXYX?}8e8k=Wk}1hPuYl4il>W+s^d!fQ2k}B&WvqELE72n;G-boIVG5PjG2(( zf{U8aNLT`@IPeFG$fQ$%#MRUxlJT08!SRgq3bp-`EE4^L`&>=336Bm);B7BKm6^3o z6i%&80A~b~#*r(r?B($3fd!|q zfUK_x+JQQl6J)ku+%)b_rB&>;9Wk;?hqC;X3K$T#@o=S_VRC zK3}#?{}eZjM2v3Hyq90U`r_g~p(f&nyj+3nlJW0QE|s3Pf6~=O(9H$m+P9f$iKw|; zs1oMN3UipsrVkf9ro@$luohP0rUna}>af!nfBLEDi-U?+E(@t2bu>=I2q=>Gwex*K z`IOFPZH;n0VB4!Lh*tSknT>(La>oV5L+k$h^_gouc!UO0v9wAIU@&<1Xt}c8-^p^_ zqt-nIO6lp;{8@!`(dxUxYQ1(RL|8IMz*o4t*7FB%zehXL;=M2za;W{zcuA~Q+WX@B z27XGQ7`fL+gtrCI#wI-!Ev|Ec50;V=K$(s*dP!F-dAbY87mU(7wELm&;+JsXhT|%O z1J|E=I!6=>%F<|Mnb`rQuEIn3JSX!{*|F4-Zr%av6~6~hitdSVW&@`SubJ067d;fS zJ(^s5@a!15%`Bz?-Db)OE+jQXRC>E4Y~YP!i!vUhLdxd+!mo};$3g;Ynonx9K@Ba$ zzd8<8f5y4qZjzulVYy}VYt1g+3T-aDq1{_QoLWgM67e6Y#aV=IbDO>)P0FC}`ot%u z3D33%u8G0pz;u+FJKete#XD$x!(J)F9&DRWbVjY5h@Txc8=%l%@mr+PJy|wsNE`i% zgx}W3NoUb0ia0gw9@<;A!FfP$Gj4yr$#!By;N*xe+^L**fb?2$Mkk) zI+oi`Ccu;H{xcKamJH+V(l`F!BOk_TzTKr*mn;l2;4n#PQrN#%t(W z{6+m5JK8?EWA-wnwb-Q4!I9k;hj@X^D?f35yBTD>$XaRm(p)vBH0yksPfaYHUyZ`qezgCKq+!Xmz8S zwiur^b^`d>P0@hBCW*vGEN7onl8%sRozkzGlxv2(Al6?yFu|`>-+zmkBNwFp;4%I7 zD${&#{Rx}L8rnp$QpNu6HADC8%7K;`%6eth`MW(kS&0HQF}e+%Q6#GlgvJ6Y^Lld4 zWrRY#vm_4UA36?_KYu7T{*96%{X#iE#O0>8_EY|JD{?2R zucVz59U?!KXsRW#e57xsxWOmNhM>SHsYf7a*hII+>(dk({%SP$%?1UKDF@UjbA^)9uV5{a#hKm{mh@H<2@!(Do?i<7wegO#RTV^N1|} zJtv}FiAC`RG12$Eo0+jC72da{41F`>^FwfFLM~myW%V)pyVOE6QAYD79tG}CowD|m zoU5S?<;nb0O@jlB#YT*0rJH#-=8oUC#W$*OLVDl!I;{)H8Va1%GaowUlwzz9Z2Rk% z5yx=zr+q%dq@#KflM%&iTU+5jN=^J+LG}naDGRbcC!_Ei3ND9!6vO1QOPrTxNT-pz z?3K=e#~zbIjA3)kD_Qk+=o*$E>h7B9yl}#tK*=4dKV26Hb{gqZy;72ue#@9gZ|}O7 zbW&WAQbvZaMgEL{cb$G`XTn-j?8lVvZxiAl7(JQqXtQ_%L&9ad3o1^2xZmTgO*Zv;pG(NWADguw@v+B%c=vBz2l+t%grTFPKqb|zMsI`Ict?E z=^+HJ5sgtVhUe%M%gU6RUo;*!r@7O7N*t2CL=DE~`Qi{seEha5Dn%;ZwWQ-?1&!=w zq!JB`kHZ$en3&bO8@oyW-F|CD0n3Oi7Lz1T(y%Xq%b&yxmvjVcX?1(*f6=`fs9N zb%O1GhnU!Z?zID-PO{OPWJAX9^g9g96Fa$uIP0H-aAt;oye#0i#W(E{P@wu<*g*L* zR^Mhvv}~I-hplFD=c`Yb^yO91!X$*@^~{%esP>)(t1)t-k*Yw?atvH#L`uw^&#t6Lts(AET9OO(0@(2VweSaP2m%!@7oGz zrqk;be=?r(MKX3fpHK5`Ue}O`=GK|57?7I5&l{Y+&i}euN@a|1&rRRVZd=ePYFfP$ z(I{PeB}Y)3b%T}^r4X#jLBDQJTfQKHfm=D}p{&I~vh{oxL1oM!6S4{~?AhtQhU2Wn z87je4KOyD%RQG!gLJFy^V)GQriht?it#3#)RGWS*1XnLOMw=l2h6<>yxzq53Nm8kK z!oWU*(fn9_bmx}SnehznGHc$HWZpbizuhW}fS6NC_nFCVL%dey_s(@L4amNp8z!OC zjg~~CtivrS&*UmI+hQMe=8*VcrmJJPo>8cBO52O`Gx1+de#8<9Jc^r4(&zU}+f>nI zs|Q#m6;rBmZgsBv9HZ;jmn2Ed!5p zv&Z`6U4=ztnx9NY4g@K6>{;h@D4!^^TVgfMj(PV*RQ`R?#Re8LL|Lf5mk70yQ{(!@ zT+ZBG;YSDWQ+K{@RQDfOC(=ZW6LtfOJOSf)?@x3&FerKZx({B^g}5KU9iC~MUHOK} z-br~z=)_Q*Rpq%}>*7#h_9ZrG`zkD(596)vdM43#ooM%}Zi@(`o1B-TRavMhU9sX1 z9gaK`!%DpsXPObRI<8F`OwBUE^tay_$17r9tfj6xSNff_I_!ZT+eodo>^9&_{|O7$ z+#y4k6wADJS*R@Qy%6pF>Og%W*FMU0w7G1Zm6S4QgNSf-b zr-{$?r4V^V8+p3i$>-FsTPE$A&$N3vRm5UZf9C3UZp{ zK`SDA7zD}MO;hfvi$$JLS;A$Wh_W~>qUP3}I?>JrcerObPTEi$q5uzVKP*}MZHE_U7$-A7M zmyl^WHb9+Ph4#6}CRsU>hSKY9M1dEMb@TkJZ#okhZVj!$UK~{0yL|^o@q^f5IUSI~ z!-Lf%m%`@=`gq9$+LyiY^ic6ZvFkaNQI@@n5Tc+jmkjH?=MGAY=hG(nM(xFv=P(cf zVH2Vs=+YT6g|ro5HKy~bNrhdBpBv&Knv7sEi$xm30lx0b{Ove>P4fUh$sRh-wigv+ zPM_bm&u6X53W#eXN)6#I>@jE3o4o7Zu{{WP zy);-DJwoZ{e0?;WH>B7+9Leio&v4l--`+Xw)|E2(OoWEFD>7*3S(<0sf@XNSZr|Jy zLE_fyOY`Q(XLaZJ#FE$0ZCXXbzIMrh^k}X*sv8*AN&v9dopq z`Tc%dRGng|Fkcq+f8Q7p*h$Jy994FCxk>RG%8|sS)EBq9rq5%BH!Nhu|00EcoE^?A4y<{srU>9nsRvt1_tK=!wA3)C{2fWVN?{s$&RL+$8hH!vUs&}?* zN3~41byuAprapSxz?QeS9-=N4^KnX=C8vv+6vkA$*+I&23;adk)rRmZhGAl3j76@* z8bXC#sO=jpJc3^pdj&epwXd@^NRIvUVr0xE?}#DFCeO$%<0To@%j!SP60kGTYa3aO z=O9Dix~lASk%Xn{)`j^T?xeCcJff;@rbx>22v1$YzRmaEm;I(A=l=P|s?c5W>esz# zQL~xhzSOgcI&GW`8l0!E@e0T}X!#}G5Zls5>)tqupXNwE_}lr?J6$(U zLsVCKZ!IBP*k;%GTv*@V?I;-R51!|{kD$6lmZoBq;grfYD zANGv(TErfYzsTb}sDsd{?c3nnC}`96Fi(lerAuI%-vGS~ai*J1 z(gar<+0gfoJz^NwO1UlO=Je}a2PPd{ohtM?)lDY%Xq1hMJeam11R*uBnTL)KEM>O zVPo}d`XE1PKYO1%!P0gW=O5yvqfvJFIv4>@fzjX8Qa2~G@d-iubvb31U*}0a!t;3 zxa2!2809Sq%JpnfD))dis)w7DXBE4<;8kSf$-a5TQO}fWq(1RFjMs+lz}T0%CgfIZ zj;+FekMXTX*6Pk2XL6(6rbH-HZj{4iqkWDy1zAzwX1uQ~TQFjLe@y7m;q0q!$>dF) z`<)lYGE#L;w7`y3Mo9*4+7Ox&b=&T&hpy>6ekoCt_DD~REjRTG`t^#GPmTtt44WJk zTR&LS=nLi&RTIB$vUDne`(`aCS3C_7&ePP|wOvdo9X|E_5~x8adF~mfG%ZW5q;ne$ z-FIT)@6n}AJuUSX_@bEqOGAh4$pJdse!Ar1cwsLIIlH`t zMV^k&5`|NDShKp#26Q>|EhLqiEhSst^v_RaK4F!$D1!Tb{8~rMHXNj7?4M5_TU_pT zt1duiPj21f;Df+0t0@XZR76>mX6gsxQ*E94a@U^jdgDcG)_mP=TckgA zL7RM`>0FjmuwQuXHjof?>yMFTL?FwM^vPp#f4~_dj>F@~v)VU? zk?^L2f2^(+VZl5_#(I%iQui{%Ddg0ck)=V^V#m*w|Eta$qowz=5$i~cuGbrH*En>o z?mxb1a^W_mpDb3dSeKtkYe&GreUh4(q*ax@itfVGe8YRr2-|*AROMNso>(rh|BIX+ z0MJGddXx($oLmXzFY^3}8VgViqfZSF!8N1RztTm#5gl_vVQAUU=v+@EcY~2f&7W-j zS~nlXhIgKLztS);rr~wRlIom51g1RV>1XcYsNY|o<++<6 zzjf*v@*b3AZBht^aI?V%z4j9nj zO2GPaS0}1Ut9#{NB!n5toPfGPorY0eeB7daM3mH#?$2VR9yOl-aKVP=2Yu! zYlb@hi!hBU&Wqa*hD6Dz#53Hy&ku|eG@ksT*1#G17Lmpc6KISLM|m#FBYSxUmVK_J zWcwOUF{_@Z0&Fd=Xbk`PKY!P_lq`n<5 zWG`Z;Ht4R<&XwpG(v;l=Y7Dw)7hy*{hE$n9s6yaQ9&jAqYx!o;^+ml!F^?a7u%}#Q zE2|i;nb#wt+=Z*ZncjK!*3k4TKF`uw!gzT#^n1oD=c%-<9qTJT>#JYr4av?a!6iYm z`<+w*mNs!vqp->bVu7reZsTbxjY^U4AQsNw(MuL^6Gr`lY`UCzTuK{$89y_)W^B9y z=DEo(ad=}Xy>^TOA{O=<>E69hq{+u`na_<|^?T0`?{m@T%9GVkQ~N0%G&c#|vT3z? zuup|M!Dj^+cAW9NaB#)5bnj|-rYt(j`s>S_Yu_5I+t6Fn;y*1hfPt(>!vuuR?KL!k*&lh|VYnLTEv7 zrzpAZnW}8^ggVDN57yfF>zYTc+^+L=(6522B)CZ(++^_9X?3YgBa$%+vE8kCc?ed5_Zwb! z{f;0M(^{t(J=#OhvU+tV(ehnoi)_8m;GU_gxwRgNus`qGLophOX`>S&O3_<1^+G3k zF3Q@&R-@^bn_7dl1vQP#eXtOC;&y$J=^EyVU36Fw+IuevS93(?5Dv{MwGX4C=Q=fk z8uN3DUxrqUM$}HKp_hVpDzA6=3G58P8I(o=N7lcu0BmShu93~MG(=&WR94ov7Ne1k zd^2~oAv*V%b6+|uE>vm!<(*7V>=TdPSjPV5^P0k z%B(ro{p14PO}-H)GV3YG&Bul9H%d?idjiF8i}mW>0{XAheCrx{E`i%bgtR2Y6(( zDcGfjKe93B`BoyIkQ}ID36ZZbUm2VE?nN;d&~6j|8s;@T2W9NI2ItKsMP$@Bc5q`y zRy(r>&Q2Nx5I%c0i++fZA~er0BB*^nnhR`2l7 zpJznua&y=#f&DonB>zcF2~Fw+ZR5~e9{7E$U3`nn;us8iwoYk@P=(@Dhr%9bJ&hAl4IQvDP_a^TVtZLPqT!3d^X0b24w>Ed{ z-qs9T6e3NSo6%Q&`4eu?$>S>EsEUs^lrOK2I<3Eq>G@iWuo_2OGnyOmVLnM-= zvX;nMbkmELY7r)j{@kH-g4@6bsm_BOWWspuk)VsU1$GF zGJDUOwPwxC&dj~m{S2=()?xY=*8BVFbF;<XdB(3I?8Yw9!V zq%?agsX-wa_K0EEq9R|Ya9=iTAY!zi7pFS%2H=ejGQgqFTiugBKZ&#+I&v%)+bo%-2p2p|qaS zDGapr85xkpX&-$pM%mLy?Ra)a@2*juT)$(9U=iOPhKqaAryR%H;;Zz_s{YQJ8!kK# zI-7tw3y#07Pm5iK4DHhi`_>bg^n{htsm8~)y*FSmc2JCaVcxc~f2$#$n{<<%uPo2g z_`>zcfRjA==B1U_*P}VxNQXN97>-EsmA24E*N;{|0pLmFeEt1QyYFV= z-_~WtHW9fY5~2($q+^GPQ623!a(*02%~SYg!@@=-FiP41KU&AV2s(BIfXuszo!j zYGyUXF(K9yST(RZwZY#2BlTS8CsT>p1G*ZYDMQ!K<{a`{PKfE@1X4R6=C_4uRGpT} z>O1I@s~ipIq1Qg&M{{dq9@p$PsFg089+y2Y*~uC;TB}s`%G$j%TavckP~Wzc(U(P- z1!WzWtRdA`T5RW*2yCpw+GusQ_&qw{_0A~@u_zMw#G3PoXF6>JLwJtG6Y zu@3Ne@7v$!8M$F3@Q>~Kf3d=yEl{Tra&{A*`yAyla^;0w{BVX@>e8Tjt`}is1zuNn z&m|g4d1sKb%lK9qaai}`YX;su1Ifg=I`V4*Wm?90o5U;KkeXDq6=Rd~YtKbywlpgP z28!%m(1CvnR!zn!0$0D`Et5uThomy>Cgbkxg8tE&WJ>9uxnu2`m}HQk@I(CVy9+`& z0L{wPO+#-5B@|LcbK%n9Q$DL}fk#6+^7MiA4#N8j@2%Ut@)$i694@X^%OuBp9(%hV zqVLy$j^)Cqr%H%5#k$^FS^Z0oMXgVFJK=FZBV$O#*CC>B8&4Hx4?H|@Y&@hiXO};U zR_p>T5t!*p$Pi7=iNo$`9Nu02iK6AQFH-LzmcGGmuzJ7)iPX*2VCuXh(jG z6G;&0;tFY9VOw|?t`Gz2NmmofvLQ%9;lcwx?AXk0FiEF}@se1HIn1;lqm`!g8Mkgj zU^Flf-CZ}v4)qgyn%%CCuMh^WW%JThr^ou$%Z7t|3F?LlcxAs>iT{-FiMm!O$er7W zSHNEv5O7@7)L!b8SSg}Z0CbQTb4wm3f)sqs405tUO82r7JlAPcIk|l63lOUwIwGH8|Tlk!>{}@h0Gj&*Ut~vT-vi3atDQR<3oAk(h7>^wCQU3AJ$RH(o_myDDt zYiRpOliLG+H4T@i?87Pv;-B+7dkKXk%}Z{^J7oyqZ9M9TkwO8j4+C>|nOUSv`ehSV zT|C2FwsBu{gIedF;k~Sp^PgAyc^8P@R9maKK%>Oq#!l!(j4{1&U=SYJzz_LeZ#O0UsG#t=59R)$5A^=(j7u0PXy9V1W}=YSE^ zB$rx1#Y|S8mm*7PzTdpFbT{Ymxd;LrotckrPgjEN3Quqy<4+7Q-~RFwag{|Ez7CW8 zvRm#NybUL*%s5!`tQEJFUCb~rt`LMysISs#SXAF7MFk=Pyak{db5#k}d%*XC z8h|CWBYT2TuVl75S;Fn7=%|Jyv(A;Awd!gST6XQ05992j%atxk+C;6@-}*UrwC%PD zgI{?h7!rvndus4EHX23plfAtt-%L2*t!3=gXw{p`vxXnBmu8&4>}4#SP>i?@3}iYN zRV!w&SC5&&lbqnP?S7@7e;|UGlX_*rf@s=&$g{^fsc623ERR0}5C^z?O!4JUm7CgiX($GB5&FU48tO=!z5k~%k`fMnhm0}=k)_MyyRx$jaj;e;- z>g&J?=R7og8FUhFcL||H2&_IH@GC1VXUpN&QXGI{d1duy#vr<fVg`{?*vN zi_xoedBZQ7`T<2jS{y@{h65EzLg$ggFAB==RKU-aH-l>BGJA@q4 z5XDMtvU_!T@wy>MNGg?l7wfF6rgmLY*Urh_pciC1E%)v=DQlt-gai_jQFyQVfOod!xQi?zP|lJRS$91>ua6#6N{qX z*eRMKUI~(S>EN=}iahz?EzOXu3QBj2ipSQn9u4!&l2+Kk`AN--pufNyb!q??O+K44clSO2jn{MtY>F(X*3U|Tv;0hN zJc?Sg43H2bbMhvc#goY&ceM`8@ufNGE0d^Es^K#P(V=gRt(m{WJc3)$A-pxlLu6~2 zA{XCFKeP_{(3~Di@q@`axaL}4Jm1If#^ge^-$Ei_SPx4@*x=gaZJ-262kYVxI`ephI+l#}n{igH`BPxDzv3V_730!!C= zF~U)jzO%@K zN>M+lIp8Nf_(h3vtDqCaEY+XyV`IkrcqB=-?mF%iaVB{6)F5HOS-jvhfD&&DGcTto zlzD|AVn1j3eS7yiO9NP#U#-q_etG&FBM|G%jW>0D71(_ty zHK{9al(~Lxg*%t6c_pao@o%G7Bm}=W##oo-`R?}zc6eN`Lcko}PHD}30NaIptL>2E zEp*9DHoeqC(s;K(%ZuO-_+p<+^EgbK=noM_d7J3yLx&=WV(;W>_N+0Usw`4Z6H&*H zzmWO0J;LGef%UM$Ga}(_2&^*phk3*COHkie1u&V(p!~n5F$bLurj%VfF0a z30rU8_3jU|-vsAr$=-g%;*)oCVTM8$@Gp-O=)K^#KY-I>V) z1)^>``Hl2rR9)!00~1(6r$H!pk4~ePHtLu4>R=J(Rs(>5G@w?D-Gnx1FzIhj2G@XuB*= z>*eaRty?&7@w--^sy)H04d4K?6H5SAzcptxVS9Y%+1FJFF92o?_# zn3{P~zBZ~D;YVHIQy#HD(NnQ)i|V;K%=ZmKGP0Mo1td2bwMJVDO_pcDZBvMom32zb zv#a?OL03tq^3rPLi9IcO;-#HeUW>lea4`)KFzR2vjOCZwxNh4&{k5rJ5N#76EGVY` zgVD91Cip$$T9ECQ`X&(tYYe+n4M9~ThlCvOp!Z~}H+*3( zu=zC^sVFTgArxs_2fcGDtOAZ!`uR zBZfVUb!eHT@0lf=lVdesg2d>LR~fqqv)12&UdI&$lI658VbA?MvB_4;U^1r(e^x8`o(Gac-W>2w!Pji;PgZfouf)m6mU=!f#v=aMDTB%o z0wI>Rp7Tb$&y18iCK)O=asQyII7O`li4I1z7^F-w`Zw9Fla39!7b3~3Xi>FK3B zX%z1S_{!Z+;6RVxT11~-#MSo3SoT}2J+I>adB=l_++1rwZ=#RzoCIl|< zZ__*V`E6KZ(+6=(5bICe>8(a%fwL3hS)jGEH^ODZAzi-u0UAE*@01}d3)yA4&{TcNrn%D-1~Iik6cC*~`GF%#+S>zhx+ z%&Y_2vg!9#UF%Et&NLYHNBW8?TdrA33u>&YKAfmR=9AzLMX&V8&oKDrP%FUY+7GM6 zk2X$am7T>))EexvQGLoqj7@FGrXh*X9vO?@=f!wAyaCBz1D^Gku zil1Y=7rqMCU93XHCR9%8iH4rOO&y-H!J|)x#wSiDlqhXu^?~S(UD#dW_%n>9lpL_q zRWMHS^x@%aNkV&2E5BT9&Ff3o&)-7mdkgH<#Gh2!*Njl~>Gg}Na5RS3UD6fpFy^-# zYD4*g%7)LiUUITR{TrSY}1xk=pdcgnNhqu#U@D z{Jo$*68DM)J}D~H9Imz7VQDnEq5>4#sjmpS2Sx8BTb01w+mckn!xZ6DGEHJwc|K!o zZ+=)o3woR*+Bl6+Z65!wukek*YrS@HE6RklHxU$I(>8 zlA(}mKneCjo@qQ1_rfK8t+;7yfV&B3SsgA_J{%0BBPOh8RAqT<{cI*hgTM9Mg$vZd zOyA+(VA_|^z(SFr5bk#TY)Lw)@ss8+w-StRjP}&%GS$sBM9xe4)UOGCEm~mnzR+vU z!%JtmDC-t*V&jc7KG$KNo8nKt@iI(|)l^zeGE8KIJ^A?4z)_)KetS#uDN4YYI9Z9Z z>TV5FA^}x@0c3N84Alq5AdCx4u8onjM@uKP2sU9gf6Df=1&i;9FsC&vui5i8D*FY> zp38tM3B@PSbPVltaS&h!oc<`(ZB7RiI6>s#>Ybt?G}!d#|0Sqj$H<>ZA4Xil7M|q$ z?BZDKJG(CVUc8e_fpWlJ5ER`}-jNM&ua&ER!ZaV6fKtM0@jZlUWwyLKFlxtp`-vzQ z#$9LUNZIg?ZE^>*QX}L>FJOE-76GZRfFEay7zWpiX(N2S4yfdj6wQD z^u*O|?{40MpK$=}kc^b0S;q*P(xzZF8PAq5!!?S27J~yETazcOSK+tugauTi#2Ppa zVuN-y@6X#f#b-*sPH&9gdOOy!Z_Cf$^AcOhvbue2(2Zn% z{mwU{gP5NYTuMVMAv#{jew>kc3AxyP{z<1NUf~)Zo288%0_^LzY~)ZL@FYnu zRa9$tg&jbKHR&wWHqJJEx40o>f{b$>9;zW!YV-Kv1!}FlX|iMSh5`L;vpyD(M}I6%7{+!K&H?G=eq%-ac%Mp zu;dmGQn$%=Q3(<0lE22`wTVMjGbIlt` zWCP6}ffIzbs>N$}Fe3C-`L-k8dz!uiKQwjbU%VXG9Eh`8Z7?RVG{X^3q;*It4X2Lw20Qv`%fvBTo`#o@jf4p} z@)>zWlR!1A`3PX0BC4R6bv0z6(k%nG4AdO*5}XpQj!KF2Ei=Avs(m_RqZkS` zRi9auYC4WlWbVGFZpo+i&g!16oQWi3tF^Rx65m6>=o7r?=-Tb=H&ZY?xd9M9LwA`r z1vzkqL+CukeLtdBbk{t*a-a4hul=jzmV1^19B-H5XZ~e*JFHirCT+_$&g@yz@SQgw z@pmVEW3_HnS}tf!KGKWK?on^G%|p?f%IH>Xt^3N2>WF`he_@u*W4AU?N~kr-@=zZP}a{pMY5e_}10i9GN_ z2?XSukIy|BhPT<=62RqXt@F>#TG+nV3T!>>!Z%o7deEU6)Jw`#OuR$Jw0}LAa zRDGA-0{O0orSmI)V$+;RodOzQEkv`6o42SSKR1NT=>Y76IxacRW^%SIl+wS^;ayb8hNWN=|w6ula2TU7-F*|M_?`5{FE>Qud@*O5ZNMI zIK8o}iV@scms3lrLT3^#C~7)?`wiEAyW8kgHdS9q)Eu0@Y(S@c#$jWy_G#{o`?n~! zN}WT+iP=U4<;iK&xf`mDgHqXhrF@X^GEV^krsz!AyaO2{bsdo2qkK6T0^II7UXb#v zDEV0#sYK(ombSI*W1%Xdld~lxE{rr4&eCnC7_iVIaZOCD)?AdbU-NY;)xt2XErHcU z|NcoSZ5dXN^9l6*^_Iw`B`RFXUk*Pz$C-vK4UfeHvqU&A9&e^ja?4pHoF{3xs-%TC zqx%*kmw1XIq@>a($*j_i4AW(W&x@YE4`!@XWY^H?=KlK`juzA8>r4V3lgfVDwVq>N z*`m?FN}t9~`>!?Sfs4VOxpQcFs>*gnEq$h@Z{;cEsnw~%Y9GAeoQDiMT`J`g(EqMZ z8`;T}DLSCH;6mS4unegbcg|B@>g7k}Tm@7c`QsZF%Z8s+T;mX8u`}2F)b)=^J=PNj zx{>nrRxFW#Su0X`gSCQG1_HGI$0NSkg);jh$JMMDdGP4Rjp z`4#bI4@w4=WXg5zZXm-HG{bgKLAFFQMoUF`i(W))iu5!-g`jbau}Kirr|wIKsPxwZ zr62clm416pa4l5@`i#=5SwMDTKbV7d2}9*Ey2oSsOB4vt-0%FQp?trz%GOY!pgA!L z1F$_6_YyL%WXTX%e|2j)CchlrE&2>VGd>NOa=kR3#z){kW6Q`wWn!fue-w=I=9P009oZW!x_0SC} zu7e;l$8YD7HHJH%yCw61#A3e70&I62a+7}dnG$F>-U;uf zkCtm8pD$I-^y`S9Wu6rD6x3%#ZNElTm$0|&`uBhL`(fP(fJsM z_WZ~G2OQFfua!PJV=?!yH@Fld_1qb6Z54YBsy zDiz8-b09f?>-Cu0Pj$xIb!j{AR}o7NfuJqQsd8`|+n$3y>QX|5H={1@KCJ}cbEHeu zZyXJLO_Q}BTr_sr8noaYVf$6_we;qY>zLVUIfGcXvk|QYvPe8ODC9d=K;zI|1$~AW zy(QXJ|F2{IO$@p)UVs~8iCCnSme$o#VtZ=y)QKoxO3If5pLCsS4KDt9&Wp@)?hXix z^PDK|72oC@Ll$PxQn&m@+wHIP1pZLK^Xc`W+M6xD-+YcsN65FUZp*Q-{cb%FYAN1U zDpY(W2)Rj}w^mp6s;0Ti;ITi+(nRfK#t`lg(`_o48Cxh+75yB=Ql{~OSgy7bs#Fgz z;AS{2qSl)vGxlwDF^?9<&qRY1w8Uk~ZoB9*BCyVx@v7##C>8ME;JI0y zkhaL`{cz`Qs6`Cw71ZHc+0qVFy^4hKRz@0&p+4>WxYh~X?B`hUWJ1~yY+@N-_A3KX z@MrDw&)09G2#1z#TxAE6%pEKqvq87xEXJv*I=2^9Jwlqj+S{VU0$?gC*jw#f`Sv5k zOfe7R`E`Get|^!56-Rm;cu!y7)hi)U1Ml#TigcrSJJVZlsXP-`&85a|g7Wmr{hZ-q zgZbQ)p)~f0F6JwGll!RZ=K>Z07_GZQc6^H-Gws(`al`rcevJ8i)N*L{%40tbQ}D|C zSf_3446)nujoE=&15gL}gVkj`iO;z4Lx@jR67u-aNZ^$3wO@Z4yT1 zCGzZS(BD~ADnWfluistFVy70fJoa=QIa%Dhz6yo3IcPZlw&=cZtwO^+@E-&52tyhRVy)pByb zkN{@es@=~=V9AW98-dKYpuM++M;37XCKai-fLlN#$v7|J0>beOfB0ke)95c4QGN4(&qC{v??T7j zska(~n%0$95y@%x;m(rEzA#B|`B{lGf*wU~fcUWh~mv->)$ zo)vmoZcOGsX&Vw91u7aY{EU&QaS6xBzsSjDX5OCVoyKgH?Qm|T zIt?9cDjlBn0&w6CDpUa-R3fq0(3e`!o*6WO)R+e3! zs%(mxCB?MrjeQ@$S^5Ew34UB1BT#cVfF{j{pe!}z!Hd`elUoaXkKSFYmh$Q*_TI&c zyF?@@0(jqjOLsTO#J+7ccgZP15;XXnK65l*d>le?*E>p=&{|oXJ01sXJ>qn)%X|^D zRHMTBJnJ=j%TMaPBf1|zQle4FL5y}hjO&BciGWj}SX-K4&D-)ic%&%j@c?@=D7$%k z{}z2NC3R@bq9M*a;A2K^7qyXrcUzn}^u_co=+pX9fCO;b&01AP_*S|{9DwVgHepP?x zX&xUS<8G8~{#8pbwsG6#A`ondR}S|GoW`cQFsB~3Y`(iyz^6n3 z*#xd`7dnBNf<1QbH5tvrdu@HUU9QsT{PgY_NV3~){N=2MEPhWpOTR=wf=ntZX2^(Y z{y_Ouk@Vo8Y{?rwI%jNFD)B5Hu+){`9aCs5HsjBxZ)<-P_a{e`g01C{KD}n=O8w2! zw(ZNN$j-GN2M5H3L1sf#e&ne+(f-u8!tNz4(~m`Y=I+ZX&y!cT&Ed&TzugB_q3+$p zBlD3gC-1yMHj1l;98$z~$zD=~i1{^q#mM(DHT-C`**{^A&6~meqVWuuCTje?ViEXM ze^AIz_509O>Gg;8IhE$6xrWI$*hMRN)J8pSoVs~iRdud<|I*mvY*udoeWwImdY!%h z%to(ge*(^)=-Q;DAh?ci-}XS<-3?wY@aip}=`qTMI1o+64Z2z)vOe`bhMK9G{;4Y% zxC>K*YH(!sP?OQlo4bCu_UOHwh70;o=(N z3ZG%6k?9_@txNqkKKb)Z8m!6Jt17_kJr2v?9_EVy0r3G+;*}6!-;7+b1%JA=V7czn zu32s!i{g$D`3&3d$3=>k&+!J711@Vy-5-~=HE{!f#h(l)Hz=a(4`dru}%)Z%{?uN|mYA3s-&jecHgr#?WHa~6D@ly1?Be_HbzHK!cR*qVx1 zS;#8dXT7}tY8BEoHPGT^=yLf~S@B-G;kzcm3WV5xROkbi1h5 zv*$eZgU>6w(?<)u@!jU@;IX3EsQ!IGI`uf`6&+D==&4uVltyOPxf6q)L#d1S(rSoM zYkCiL3qVT}X5lmCkSN8A=hrsE64Zv?7;#>&Bfg_ICD$)9PZWjb_{;11Ba2pA z7C$!l`uqycy{(4se`oUV)k?YxYvl+oEzO!ZJN2ECrZ)n^Zk!4fpTGGQ-#n>1U0-tR z4qjQ{tWU^llXRF`JWy_h6h|#?f}Ikfq8uct?Zo%@}@rS4Jp5}q;v`u_WNGa*_BORKA@q0a)O<*TE( zpL?7EaV?bL2~X%6ds$baN>O{IKc_sfHL@4K87`r^HgYtfr?FfcNu%s6N$E4a2Qm!-CCm7ygGU9_a-G+rx?6xlS( zG&U{VysGQzVY(m$qnoJC;jZ#GIiXJd3FVL>i7wz!`eH_R;DaQz`{J|KB;E?rMTfYo zhy{bWkDmsXQV@GCOR?Esjy@)?yq{av&z@}L!P~dmOip*w8=!zC&v9P2T^Fm89Ps5; zcTczpR&317Y?o7tJb-HRQLi1Z?@sgCih5>wuJwJ-?UbRlP%ZOoOWIGf;=R6dW5z|f z!hC^GbYoL&M`~7x(ApaS^scdKEO*QxNUY-un;V8{6+1 zEl&dQ(RNsDu3CQnG?<&*kyi=6zS-fN8lO5-A;2jjDw_N}MEPgCduwIg$ZjZIMpZ~$ zuz)usX^%T1mj)BqdQSqKq*W~HyqMeC#i$Z1VfB8Jtfr4s%dJ=(JQVXo-?e&LR92dL zX&+VR-L|@vJ47dDiHa}i8pCxL`a;oGMY9^f+o*TV5IrWrONx^*5jhrvi{9UeM?K$k zxHb96f6&MtcKVv$DdQM0c_VzcLUrF57*6#JtL9!LkY*Qv&RmytCl64zo*@M+Eexq< zXcGXkL0Z|$j`%-m9uELSj#=@gD-fTfPuCmraC_+jG#)EZP>wUA*3aEG*_k z-~%a25NWj751}8h$3rKl%a0frc=-qVXb?Zp`5Swi--dsM0MopYsJ9qiFVoQ62Y!@a zUJ<{2uz`9EP3YvRkGr65(xJsM?iir8K{bYVZdH68!MyN+aUZ-~nBcK=xr60FW_|;0 zS-Q5ft)R(oUKrRo=ko*cCld?6s>EcDk#Yecg9fkJy8XfH_E`Qmf?7fp-jnxCL_!&4 z+h77=w?=O9Qs{ka>Q_fu?1&SgI@=e+o`Eo@c6aBRS8e*AToUdxPhOsFOfVA()rYAS z`mp!Bv4pAE&Hnb$S#&aEoDx327r0jx9pGp?d+==}^0DOYfOMT}$y*y1n^_AQYdz&V zg8t0TA?|N?&`tJCeSE@Ee+!k%U@{03apU|*SYoSLd5XAqS)4DS0x3YVP;F>n$+`nW zWejm^F*NlOhs6L=>cUlwuCf zj->8)8NbPYEF~Eg49h!%@7+4yeI|yl*EK4kdge^X&^6p>sK#r59*It_?ugoQ zfPkQO*5g(6%4psjgPG|aVG8L%Ov$j1@e%+}ALM7Gc)m3*df~j;N90|-E(>niQ3>@( zUN`AvN%M7`R4(rKlc8zK*vGWlk+C~S< zudv8wx-9LYX_T1Osc-44-r098$=FY@+7f-3_1RJm+tnKefrF|mtzzwG3-~@BXWOVx zTSi!&z9`fI>sXFi3%ots!`$Au={%X{!v$=x?@vKQsk3J;ob>5I*=(KLUcaaRmDQWT zM>y$POlVQmyZt|2}DLa4)e& zD=Kwg5g|=fXUgB=)5mkQf6H<4#<1g1218{&f^Q_V>69sb3%U%Nsge9EW4^|1&uee` z#lJh+(yTzxLuyLpvu~QYH+`MjJWoGW%quM&qU((FKM+~9 zULUi`r%t@%N>XEK-BX?>8K-)N%9Sed#3A7rw#iEJGquYmm+(;krG&^Bv;u;cC~{0j_Pkj; z#XHZ8#?i=WP)|ra$Mr_`tGl(1t{%0t-}^^$!J2XYPyo=r7uZEm%Fp_0hBE#RygQ&f zV3+DfB{hEV{ByN&YcU)v^iARd+va?>3w5Wyeey(@*uaYir#9e)hinjQigMCW7)v z84?1#K=Z!N>ieZndR;Aee;bt};88JmC4=OYtMbxqxYt>|OjnlrYZCQK0JvS9qJ!4+ zBzFFOBg6hs?GIbY4-#<%rJ9x`8Bx)?aj3|npROVJLx*jT!7cMYG++F=KQ1EU80Y&}o+!>cDuT;xe_w1=9$S>F zG!z2BXJSIR7#ndv9|9wyd5Qm!DoCuMVBEPUHaPS(g4yV;Ua*pHsNB^kmB_ddJ5JC= z&bR%$#FyI9YiYS2+hwf?j{L{So;@6QUQ3DlcvTq;#xMaz+{v&Zz z4gekubq&Q=IG_(OIpz8%P>LRPTHL*bOCMz4hV8@KKSA`*VP)izb~aGqi03iuDNUnD z%>QUFfWpX}65pCUxj4T1L>gY6hWXc69r&Qu4dv3{x-IAroj@h!mw$8&b2&$CWr&Jk z&=)RlJp@{x^8FK;SFMWdPDyJznvD9P(_MT2N5L?US^)TB-8cweN+$b<&OauDDFj-b-ok&0l`hi=^Ac%TC4{#e2; zSOsa!x@AHZFx5(ZiTST}^O&i}yp3}MoR35y9 zn7sZ@s}Gz%UmP17RHpkroMHI4z)BqcLtu{8en>~)pV7(5q6=Iq&gX8` z%6$y}$Nlgrinhgvoy3c#`x*OVgP89Pl$b4l=F)c~vn@W3`6MRVG;6)QT>k|2&H|Qx zl2T%zP)WEVB$wam|8*dS;7+^UEU&aO3fko5q4^_{CB5m};k!T6BDPR*vVDC~lsz)# zhmNYO!QYwvoyxv(tMB08)a8J4w(h8EN|5q}0;;3IETMnzmbrE13j@@xv?=)Wu0 zC&2&!c*#2C^UQ_Ra&dY&-#_a@Fg+>^Rt`EsK6@-@ej-&DbeCLd=Rnm$Ml>?O-=W!k zvC|Y#o)s|^^{1PEWbm~3l(z8_y>&}4dsv?1ydU!RUw^tZCYLX>XuNEuOgZ{bSJaOK zmQ1y9q$@W1{zu9EiNJ+^e@3#1{YR$qz?0bOsP7X&)_JJD9PRvX^S(+)fwsGW*t}V;eaD}4Mn&8u zza{_C8#_Xa)g-8>dkOo0j4V)ySyZ z|9L8tb~Jb5(JfiZQBgsT$bX!m%%o@un|FcdP`Xb$zvD2%Ob8|F-xa2Rk1qdQ4E}%P zYvQ5hr2Q{n(?4n^H4_&UYm*%&@IN2^{>p`-PI_zaL2H1zos*WEn~#H^pNo(8HLc)l zj@JSLTmpi$Mwmcd4Hq*9S}tAzeva3iT)h0em_WV1KXG%v=H=kz5#-_LL@_{FeYCQ( z_;0mpCRTPX|NWwD;^JiWR|*F|FDL5yD~_G>zu&mHcsO_jcm=rmX$3g>I9~Je@d@($ zkqk0(ws& z;F5q1;g%r3=+=Can$hInH(tn{@uQQ2yKRo_yCi{ojH}3->l3+TaIARD(p{)qY@0a2 z+3zq8aLc$jX*L`tMlBwr#`E}PsEt1#76MLEGi~D~vVi+pv8mf)F0Fj!D5ZZBX7&rxv|-kYuo(*vxDPH_4uJ<3xzeO!QiP?9Q&C3)mQG{==aS?Jn~c_e#^*F8FX z8`kpbpi1KOTTEzKgZRLgyx;iU(c6snR1ce}01a^rut6(qWf>CEk*1hW?!Su%@V@m3NRY@ZaC_n+TQ%m zB{#PcFA$m&+Ko%gWsIu~#OGK*qx9ex@Ge%bHj=+qD*vh`0mU)U*`X+it~26h1}Jva ze(1V+ml6D$zir&$Ga`JsBJ^7=BHp_uYo5i?G44r2luu-#i81_rv1P3q#x730Yz1yz zG$aD=`4WG9-Ws0=|01yk(VG_M9wG{s5*yzS(zfbAy{C2$MTs`LyP&B}ZK>*7Tk%4_ zo(}T<9u0`^SRa+_o1rFC`J{NR9VVK=T2=I(e@tiPeR|##{3@K;1maA04;RaFlYV}O zvcXnv{c8P$BGO2=L6g8~Ij;|fA0X1{4q>%VsYjK<09Yh@aMX#My&_JI@-hQFs#-v& zlEpRBwET0{6u}!>16(a5kz!X{tLYN&q%F9+Q%S1OVxV$L>M&2ynY)L3HTn6wB zU_Cy9CA!Dm`WeJ+ssi52$$*#k^AXWD$K9pKXy1=Gr7O|oW~K@P&0J_9XJfBO)E=!V zG>u!PKcC#i32?>?`blYHNYF9bRZG;rNex#rLrW4-138~XtJ+Qy67F-uO(`V`(ocsLG>#;PYHG2D0EKz;=9k%&mY2Q;H{AZ;;dRusN0c)BS9ABKW!2eR8=|06&K$yq7k=>OUkVEHI&9)VY6r$M}cUtn?o0Z*@4nbRgQw{OI`%k!A)=&1*Wc3vPhb4 zZ+GuZIT76Rw<4eVLecw{Z|2`wHwRX2tvF%Nt(!0-eDAwQGMmoul$@;b-PSbQH(fn` ze$27_ABPm#?OygYXOUy&jiseA1K0Na=5%Awu=rth^#^>MPcN;USpdIjxLWm0!JxsT z8)^e`kCcZv%X;nKI~AN7}L2TX5+Yl4I=}# zlw3dBlCwRe*}eW=G1+ywSF3lecian6Q~&tBqWq^%#=epK{N({luSSpk=-Aj_wsd*( z%9Z##{i5a#J~2p~yPqExFmp}u4|$8Lhr3TLUbrDB@tw8FONQiZXnB47p`jJK-rCXs z_Rou(TQ~1CBJbXErhYZO?$_%Z3x}>u8TZ82?9Y68AT6nK6FmMyi?(e)-+4xr{ z@77`WT2}0C_5O6gsr~IWWUFaDYRC~;u9qjf;0=>)-P1wBw6-s^9X4XMJgYT6?A8|D zdVDz8JbIiw*AWi`$)m@}v{V;N5!UDtZLz~kE-g_H=8ATODkAJz8mzZwhPL(pPh3_; z!W=(qAH&a@gC2Zrx)4m*=GY$72zbK!*is+U2sIIn>R^s1AE5#UC56TrRcRE4Jw)SF zl}jjNQsE<1TJHn(kOA6Bw3ZR3>PHwgFdx@c+Xxeut372f-N1a35X5KVwOlg{m5)=R z`hakT{0BidF`v$mTyE%ChN;0U?rDe6u>S;+$ftr)OyfH8pU|=YU`oew+tEeWVA@yo z)2W7J=nUl=92BtsblpHY>k`|cn+DR)AQb6hPy^+k!5LmFB<3^P;gdLrq=xfe5(DL~ zWY}KGb!4y9trL!C%%#Cl?n;Slqj0=Z_oKu>zM_z8YEDu}Q#Jpngu|Jl3pGIqqH%;d zj8jw9g>iv=%D6;W!UUnJ51^!p8eb;h2&3r2H7-=SP`*^HH%{O%s;&jdLHiM1Q{{3v z+9EzmOvDE#JWMk1<+rfv^eHSKP!HCNzrd04UK_{e)%+RX;&+oeRQ{ z9Z=E84na)R0|ce0rwA(G0PmUig5ug2j1a`fI8kFR;95b=alv7KRff({{=p3b)&<%J z+D|v}S`dq57zEXV0C-X3D-4cmP#8L@L17pOUxZ;2Bv)!EPvM>fVTq8;L_U?mx-{{? zAtB-A*N7%H6*~bYdrifu%rOzkN^L-+?YL(L7MF{a`(fl^hm1ZWc5CN#CjTh*)P zF43STBOlh=UBzsmNul5_(M+bR{sZGwd?sLsnpZ&6r5az# zG_^j6(1=>AK;uNgIwB~-SfKI$_E1-bBXM3rhM#pYH#spop=}_yN2jH^Y~WGrnsH3( foHQFC(t}}tzRQu}YMb3*Cn33CXlTSMk$(RI=GNdS literal 0 HcmV?d00001 diff --git a/audits/2022-10-ERC4626.pdf b/audits/2022-10-ERC4626.pdf new file mode 100644 index 0000000000000000000000000000000000000000..154fe75212e317a87cfa249b9101a04e789281bd GIT binary patch literal 204184 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 P3ADOAJw3B!^LYOO&o2YP literal 0 HcmV?d00001 diff --git a/audits/2023-05-v4.9.pdf b/audits/2023-05-v4.9.pdf new file mode 100644 index 0000000000000000000000000000000000000000..21cd7f59307483e93957a3b2c94aa11c0efe40ec GIT binary patch literal 485395 zcmdSC2Ut^C*9HoR2sWA>DRvzUorEHYNKp|`Q9v+2gg}rKgwVU9SiuIUbQr}#CxUd; zQAQ95A~gn7h9aS;RH=8LlL(>s{o{P||M%W`p3FH}YwdTvYps3u-Y1-W+;T`u2O%qk zTD;{;OxW*>WhG=JNGDG%-nC2msD~p~Li!NK4(lwfXK&*yVU7gKBN9sR{}q+tgRC5i zb!2^)XMImD#){rimW3`ugCWte(-IVN3sB&gtQJL>nkn$dDECAt#cJi#66sV!H_z zbtE~FcS!GXA>&A( zDZ9xI>Ag-^40(=t+B-yRM#A@E$QV4yj+uA~I6KmYE@a>j>nx!l1E)>e07C%ZK#{bt z&Sdz6DKX!Uv9`uKJ0q+~M6weJ&pcwR$<8|@%zxBE+Vr@Y1WHCq35k>iX+)u9rDWvf zk#ZmrXbBbotGx}@7UO~^V{8caL?;(KmIVv|e~u@opdclOl$DbM6$g0M7(Ctv#DuVS zM&L=#WQ3bN$dd~h;cRb5#E@N_urN1Pf0)G$iBgnOR+{2wjkm`V$p|Mn<5(L2>FmO6 zuE6YGvzp5)qX3oZ<|Lvu-o@FTM1)+jx`f26HYh+JIh_tT5l{jV3d+DS9`p+=0s|Eu zKrs6-3?M5jFD0*}s06MDMI|LEMJ1#xs2zwO>y9Bf;;~S^Sbco9!C z5E1CA(8UP41%?dxAY4h{fFR?XNG^6baKs{*K1ohY&5u$*lv$VkEU$7XWl#hKIq0GX z39u(xlc3y_u?QQIwF?3C9SoFOs1~eoW)=WSMh*Z>br=YM=xpyyhI*Yd#ujUh0X$ut z!I=2-D#(KlB(JQjpv4X#yCC z8pai4kHrilg2D} zipug*G73|jfPl5JcOlI1IR9WZYvcf#0;7cuNY+#;A-40^MnOhN3Jk|TE?riZ5m+ZD zDCb~Aho)hu#!lGNF7{5KMxZOh9SI&i=LemYw<%Dln@sl{2taQB#49K$Nuj2%Cn5$+ z19k}JsEfcseGp2h4HlFUoB~QjI9#YVfoabM!yLXK{Q0lfSp7E;lslDvWp>#`)mgAK+84CG)$ zz~Dh{ZAnhxVq}dE^Ji31776CcsWL%BA|B)D2xWzAPr%|y)()(h6Aw}Y)yTyeo}lDd z>yues4GCrq1vw;=HCH+UQbe*nVB-vC8f&m_0O`f!!9)Nurkkh3+(5uShLm}}Ho3}#)n&RA;~XkCaPXW5&jYR1Sxj~8@c>0aS_fJKYGI+tMEW3>Xh+6LAeH1m6ENIiF@(kLjZw#F2JdAA zd@44;@$z2CPjsV zd->w3HQh3vuALso=to0(9g`mS%0-U^{B|{cti|Kp*@2Ejn>L*}92SKPJ{)5B^1Ih`<%j;@F_Hvlkb}Yx9Vr;Cob&q=zr}JA?+ClTAt+=D+JE>UUXOJ|g#Qc;AS#~{u4;TB@H>TTjojJ}ySnVv?UuK` zHYRTC$Az1{8L-_WysmBwsa@jOp3?e3iO`Qd&!Vr~`V+nU*|1d5?|8$q!p2bgW+JUa zhkCkJkJ9kRgQVE)mr{#Muk$eSn-!|06jWnH=x-2SWVN8vk_&Xc1-c9_Q4>B_TN1XQ zL|d2^W~{No{JQum2bXWE=CtFxI(S;`jn*A+Eukr1OfG)rSn=ue_t)j$ljUNg^ed^E zgoFDG_UQ4wQ7bX()YG3t6q^q))(vr~%H3>@Ik!S>;_;nTPd0>!TO#|u^>i@kp_+{d zWLmO~q3+w)rBugS}N;_>_(i4}Y1_cK_Z4q$~DoB{1xr`leI#m`^RDDJ98>UkA zPm!p@e&L^DGv8+*_>L-T*=0WNONe+}oryZ3FBN;CKdP+3r8$aF5gtXOG#S}#W<;JU z?|v+)y^3yd1l1zFx4n4-bUCs*E$asc=q_=_Ek5*{3b=lpz;MdC!Pf_COpGSUUBVo? zj1-j>rQ}eGieRatq#!G$q@;{ODnLJ7Fh^hs_+D4~2-cb8;soyYCE%Yxq>nn;6aFU% zO*|HB^FJ6(U#HMz`#)c&%F41cF4W{GbV%!~)8~8JP2N1=tj4?cEfH9C;o4u%)2^-w z`%t_`%2ro$?X%zfyDyK8A60zq$#~QC#$)G>=PF(Dl^aH{mD?5^t9kiNsnM@UYH+u? zcW5bu|jkbK5azIQBE zF*JOz*+!lu zy5&*}@BEaOOHviPXzujJr?G-cD3Mg>bi0KKKKVpss6_6FdsN9QsS2AGm*`ieQWbwK za24OCz}^07f$Q2OqoE1QOe1z2&ZZGtTr!T6Pf|kau+3F3?ac>*yF}In5YYMCMlbOk zGY39KOMP2EwLIxwlB=X+W>~78aM`;0-hd5FBv&bU#Q%w^haF{Ey?vu(p2|)BdY_p3 znjPv^;RR`rjqt?=E_T`8B81|*q8jzNqmEB}6Pis?;;FVeZ?0s0Jylt_5*-0(((&G# zJimTDmAP|WfD4c#drz$GZgFW|my3Mz-5s5EDMddSX)%onXkN^Z+D*hW92^8i5yQ^tb$a_<)~X8 zqW7^U+Uis>nt#>AHLu(l7$(3;7TV}u^&7VHmP%LZAHT2t+%k6S#tPc?VpFu0ubXd{ zIL%gAyxTDKRfR2=+o_2$Z;usQRV)X((N+6#7Y#JFRq=IfR^g1&+7`D3KE!TO;oCVS zjJ?^hnWEM1qjLF&DW7P(aPfXJmkQjN4TBHCY=x-u5U+^8NfnCnH;5OeGEFu0ezbtx z{V-*D6^-vxkI>%6^aUNb$#CN-4526v19n6qGteRmZULDFF0bPIzzkvz2Cxe)RXtLC zt28k?^b&fZQGDJVRN)#1fAd5SquH;|v^1@0XGw&5)akTqJH&m_wW-19jMZMARzHKS z<4PVpc{q%5x9}R{^VM_5Ypdc6GApSl^tXf%hNQdLtCwwOo_7c}ep4^Ft&a&ApIE=K zf7ijpqZ|7b+;!jI=b)6OF1QFU`;>hKE;eS=o`?sKvPIyXpsAU2{kKpHzsPO~jao*vZH0Ywb+* z+}tns&f}CLnMRT8X<4kBeLRRp=>}hKdS^Z6*L6$Y`=o(8m}vCQnqkc4?{i5VyEBgQ zL6Z-N4iK@=s?cG<#Z~A>qe;s?;JPkB46@r)M6I z_T5%oMStV@Ko!_z8kIjd=R9UQ1)5s*3hoki*<)=+Ro}XIg$-C)y|`k zZk6{N?(*+(%`MNDnviVxEYJLQ&5;Gg7=EBCzpfZkoW%kM&36+s0nbC0W?I5d`gwUJ(4 zpddoYi}-9Wa>TKRc=MJpuJs+G>E;@Fqy7 zyQj7`j!5kx(uK9b`74b113LZDasEwD^16@mKRKM2S0ned=}dx`93$>f9<3l_@M)m4 zTSTc$H)sPwIMChGHjx$DNKd{!Aaf)y@2ahu0)S3mhFtq12l{sKT~F2`$6-D`LfZ@8 zZlb(APmuzioR{c%{2?7pA3F4ajz(pQ*`9K%a}mjkYNX#!@0LB--IHrDxaPjAn@c-r z)RTLAfC}uw?Qf$_xtR<>m?@de_zs|JQ`O?3-f?v*at6cq(8YkAY+tAOW-9W zxVk07GzMc|6duaU%k9Jb?&=n`>%2jCPba1kB(5fkAGEOLUOp)D@jbdsss6;mc4A2A ziM0m3Yy=b}Wpqrud+Erb> zgJ~u&CVC#0?|n8w=k$-q7MVV?Lp3G#8@<92$H*WEXs#S_Gk?yHct z4}htSlkZRT)DT*-+a3;Sp0mx$SxDU09+)T}>$Y&h)2XG}oU@q!<&wRFm7SIRLWP}g z^7d$IO73%yseq6Ba0~f3qs{~d8eh9c72M42xL8QY4A$^=tk}Gn0&4`QJNE7C;1v=w z-J_|ID6t`KC9Lr`n1bLF-J{7duLcGWme>%ma&x|6`+RLVlVL67iw*H#Ak|w9Xj?7h z;{y(2jX-=eVdBu*U}SQOvYwm$D)Tx!_V_0)t#|lc#{0Y1M_>a;eN`!3z=& zxt-Z=D%l`Y{?k<1T!R7$KmmXffbvb*8(;gP9(DG=E#KS{@P0b5qjB((RCCcWCD6D)Nb|7;UwncEU#t=HJnk51YEmG?1?1oyf;iLh zU|txGNH$m&oR;ns%)CuU9+_~}ADsgWG2@8p+@5b2UyoKTB&6I~R@l7$eojsVXj`yUR8J9YM}H3GA?aJs^hmui{9jV*7Uk1OKO(oa*;Dq zIHHmyHMTJ>QCX*Dxf|19$ztkj*nk(o=v0qNhKwN5MzX01he7Si*qbg3J8aN`W^+z) z$4!Pl;@LHvD#uL%!(e;p)E_jD!=h)LCOsa-XTfA<^E$jNnEHrEx8nhiuGO)#d&x)7 zZlXMTCTLdkK|r+T14k6|oHzLtSTurj)0z*^xqrprxT;P@*QnoU+q0YMZeF?S!Q*3; z2BfEEZ~yR+xLDyt+vRmu=0RL1vh>gUx<$1eq1GL^bYi*6`y9*do77iF1ca{+@@*bA zVsI2YqH{el;!!l390t~E}lGvL8%R6jhh0S~=1%+S0^!VUrB8C} z$44vz>{f3PyCYNmu=i`J_2(lG-b|!Kl~6ujdXRrq^QEwLS9H3r%&tcz`#e`2P@5Q7 z8rps396tN>wL)~I`~K2{4`Vi8ZyaiGj;U^rsaW$S@o4f$ODMv5=Yh$S_$|r2MdQjt z#(|qum>*#?$>)Ni;Nz3byDe=VInePXul#tS5a^VQ1E=hN$b*3n`T)JKDGO_sF0l5J zqn0Jmt(Sbx8TAt%5C@=#xWN8cxNzGNW_!LQmM@^2k^`NlgSJw9>dKG2^U1A&4t!#t zY+U~=edGG7^o@~JGr`~v)2WXEE}2)ipQ&fp!E$mEuP*p(gN}}@bILp+{D<_xA&&r` zA4~;jV6x*t3RILO9dwgjH8-PlOO@{pZn2 zx8GkRSS;aFZ<0cG1o!Iesc$NJa37l>{)9J9dcgZgXsrY1i!pNEn?9%fycgpt7L$0x zP^;a)`Rxdnk2V-KT;!+Rom!`38{~a7R5X;oW^{=DIX}j-D|@J0blXJv!+gdc+bEI4 zfnmbp)Ylgcamru$L=C(-wrx|7YlSub1_s`mWw3@b3K%ZmrXJAx$0D-RCt)*K!{71O z4~Q7*$3GT1&ZmLFI~+d=n;MLbl3nL%D^3ONOlKqh3#2C10d4Lu;TYgxfeMHZF*CLx z;h18lPtA#$!#>)RLZ7mqU>Z{2Y9Aa^ANT&cBxLa)sgsvI_gM>t)OC)oelB09mTPfZ z=nl3|SHO%2D;$o2A>x54^ebS{JB1 z^w!jC6*l`#oVp)6z{bl%`9Clba1XsTwuKsk1F(XPgG#rh9i8w|c|5nBe;A~LIB-V6 zhyR|+&}YD7Crn_P#}BqDN7Vx$Uq=RblaH!tN*?2?0x`X8q@6* z;DMScKcWvkIi>*@bxiw#e8h%6(zRl_tt~Sb5S1qFA?N2Wq<(HiTnG-&mKgE$SQ0Ss zZIxCDQ@ep;(R8N6-D637ODiG}YT{Fnzwp`DZ>uyJtR^ZJO`13$tO7!)87~Ct2tXmh zlvN{i>oMpgu?gI-^mv0i4{0$uBflYqo)>}R^qZs5UC*~udiBldK_6UwGeOh+c3M$h zS9O}TpWEs71%qzk1Z9Vc4NsRZ9L-B!@*;Sgjzymb=a-?Dc}dVslH2hx47daOQ~?}G zU54(g&}}Yj(u-&|f2Lvl-0qZMUI8t1mnBsWk&zmRPYg7!GSYn9u_HdAV@IqJ^E~cY|B5P;DkCl+ z2j{n_zjBfohru0J{l7Gfp{n8B=q;}f|7Gd8FdRfqdm zP#>}}0_*~q?4SU($t&O>;Q#@X3jiWe%%`{q{5E%aldX?D_}w$WQDs5i;Z~F8n`;wK zj11cz>HAda@98)0I=-beH7vUPWa3@10qn-Hfg{b2w7!_S_@oGtJ})d*Zcs0MbSAVu zo1Pb*aJA#lDjo7)IAJs8#tXsg30juQjoik;$oNgVB30KD^l`1YO)5?lK~d$#KuDar zp1`dejEoDN+Y*Q&HJ2pZ5(3^zVYY;TH6gJ{F!BrlrtX;E1Ry}_`TRm+&^lm#zc3x( z;MqKknSjfnK$O@5VTz|%`Y_de$sh$#Ae(d}sHJdbpz!%X_`FbdeiHi6ljd&#@>&S| zu4g51p7;PTl+)Qhe^B{(PGLF#5QIGy2w)1OTO*Mb$j@8TaU*&wz8%}gBj#dU5b1Qzw9ru7-SVAMXWSjbN0uuTFV!9mZ}%)~I&O$-G%{_k zzD{x*A8+&<)f`XQ-ZlFBrvl&n=oi`d-xq|9jK({DDKG4Ox5Tses&{r`ACdPWb@2v4 zvkjXy5(R|fR%&h}2VUcd)Z7hkgx&#QsKHw9{0ox9dktvp{_4M|uF`C>!-FG5DdaqLag4d4K*VB@_>0;VTh)uUd{ZKt6J=^zgN z2LB3`);xNmQK3jcXs-^gHIGxJHBZp&J2B9>P$Vw2m#5=auTICGZky7+(K({N(Rq`- zQJRv?%cwh=uTo3hHc@~Wh`1!-uM5ab5oD#22wPsIUhn1k06+jXgzIlGh3y(s0nUTr z)-wRv{QyAVx~IC~+3=;F<*(WuzmHcj55FH9jmcd2(W` zudLF}Xnk#7Wvc56zu~@Av56rc{uWX+zSCpuqd2K6@3w75p5u=0s_346$%)Tb z#hTtuR8dsM$5SgTBa3RiE1XBtZ!cH>m@#<9;@(Kz1U_oFfun0q8%ce#-py;zMA6`N zwXtk^YDP9`T~u#O)7ap*VZXu8r0(X)U6hjM-QLZ4qk7IIev@x3{JdonyuNT5-{($J zOzz83E3dXnJZW~m`@QR(@!>H?g@d&=rFPG2+;jebnokr(O49=O>TUq>|5Kzmf*J9qI}&MrXQn`t(%u zvim2zHb^u_c2z`2qQD%TEF^NF1Vl4pOW*cXXU56ZpqmrCcAgP^LZUXdxxrZ zNEjk!d-x5eUKw0)H??{FVv6=K(4 zYw62HhJ~;EiL~_yFYg$7a$Q#V>8~wAwQVNvi)6&NP1aX?9Bwm9IbZZSMV+Yb7_8rW z(xnZzQv7*LH`PI0*TkXky3K;7o~5HZkmT|+jFS3b{n0|zA&_6Uk<@`^^&#o+(!HYg zPnwmRM(~J;u!FC}-#JaZ^2Bg}p(;gtPwGs-dVMhwQ15BFeR-%#{GAVfcRi)L zWp8%#Tk~z%CHXIW--g$cFuju@c8q+^_otuGkz<&*B1Xji2+U_}!PebXdT#58C2f6Y zNB6h)_4)D>eMLj`0|*|ZyfKHK}fYvOCf?&e6&BBS^17N4#}B2vq2{m{C-?Q%mRJ$Oo!X`9@8eD;%G z(vyoxbmXcSjw>1Rd4mCRkB^m1pcaLPCuaub_%$`xMERelCH1X9RO5V(j(k?nuB5f$ z257H}(!{b$(i8i#j;kGYRY0PihS1vT^NA6eE=}7Xm*X8y4UA?tb3XoD<@8?6g3y+4 zUz_|g(My?h$E8mH)1oz%4_}b(l;6Bp8SyH|;rtuB;u4B@?jQP@JqY63Nn>T=ohOyj z<85DhrRxxxgO}aC)kojeks|W-cK=~}^T1`@KdV%FZe$Z)DbpZ>IUG>EO4?-l_LprDlb^`DwsA*xho_J=lHQ zkb7`sa^LGXanD`4SuaC;)pXxH9aeR)-9rC|FIqxhkoFJW*$zgx4q^vj+lazv5wlU;%6;v}B9x@Bw7hlS-TqVo z^o})ky}P8|6t3r~JdMd8d7oY&e*RF=&h|kM^$_EtoxwvlNnSZpuY0zjD-H9s>!n|( zugz038^6(osUJ3|SzEN(qF$!rc}T57*{4&D`mJGxG50FEox@bje8M`L>r>>L-CQkh z$TeOwODXCaH)skz?0g6P#9Fs6G79fE{x#Wlvf^vL*yx82;hUlkd0Tfhzs~5Cc8Dn) zNy1*eXV^B-WmM#s>QQ!gJa_2g;{>mk ze89J0s|+n-a%9|n_@3I(-tRjsKkYF&&@j5wbJw;mWrkW$$lXlY?=Qyil=R&`rC%@P z5<-c2iEXvwLIa+~-|bV&zJrpeGsMa(t9HdWqQ=MGs}>FuJ_wFC^){qxkQ%ZqE59p! zNJr-$bIfY=9(!3-)tlvP=|g*1qkp?k`mv#GJ8HzWi-8l>{oJe+lHx16&0YOU4ugBB zO_{S{HT_B<;q$gclGyGXkpqp#NEVhoiWQa=gO)dDW%>@g@rn`rwPmK6nA}n`NeffI z!ifw@nT2Y$;n{9H8hID}ZOa|JNnct+MVJU7OWDHM{7!Jgs0=M>??48v!XWRXE72m1 zR&%BAmciwiZEcmqHy%y2Q`}Oen#xi}(YgIzPf=qHJ$}ctT4bxQ-g+UlE<53dOU$aq zoN@2&N7?GlUBknBTxj<@rTK>@QQcYT5f?L>zH1kG)-+TNHDy_^8P#5wdewJDM0=N@ zQf>+Uj`8mIO$Qo=4|}WKyqZY_6X4T+-7`yWSjP_>PariK64ghC&fm$jR`Kw;yDK|Y zv`}f;bzfb>1$h}on_b4+)uU=c8`61uYp)NT59$>Sp_ie@SC}-3sFI>njr3z{%`KZm zqViu_D)*V1IB{8Lnm=@FP{Qrnhj;L>Nzvg z-x+xnm62c%-|T!Vf}OI=D$JYjS(}B}GXD#sAK2>xHn+(tfj#U0E(v&g`@1y&qmGOW zNCSBAo$FoAYS$;d#}`mb{G3*#bNai(0(D2^iNLGTL!<}1!m-?zY4 zpkEj#!3L}!qt$c*{#`b|GIsui&2*9e>)iapaLQIF1+d4Q`Hlv*IRxwlWbM72uTXz$ zUng79eqpecL&``gBEfb<3B~^dV!to~%RwC)Y}o^gc6MfLgWtcIGWdSsZw^FkwFFxl zmFCnEkY-hQzFPj|Js{K7gYQ}XCKWIZN`als@<=dE{jYHOg~h2Xcy)-p3<{bt*{Dp{ z>%UFQFAUJr6;e=A2J`sr6@&tKzXG#v^Hpf}OB2{i^9w_>tRnnU6=iUf`!AFDl_442 zJ}IN1?d$9uxKm^Ts|aC;*Nq_>~p&731%`f`_d@ zzc3`r$%A_eMR|F!D|k8$|7*m4Wk{Z%m>hVYg)$1fBS+$2&Dbvt$!wLJs@aT$DS*ip zer3^om7IEO!#{sP#B`zIUuOR1ASn+fdPNyUXj}Sp=KkN}{R=-j{De1KKlne)_b*HY zY~5svAea*rz$;8pir|+c1-T!;UHr#x@_+Mk54JA#&nB3uU}p3vFas+7^rmR)O87qy z@mJAT>j3j+U*;cw1|(3=I7z>C7bO8tL}%`ePyKVdU{ z4T4GIzs$|A%w5xknsPg%P~di1`KOE3f8!-!Y&HFb2}vFW7STvqCGgs)>3sdaM*J71 znV%46EC2sx#(!b%P@e87Qw(P$TmcE*Qu?#sMG4GT5&pfGPFZF)1EhSbqLd-bgUGrg?3C+1ZZciM5Ow0DRH3oDE$bveClp;ZkQ z*+flMJF(1y3i=dw;SL5i-I=qEB# zMuo=6=*6`kq}`UxAU#-Uz_{U%k^11UK5*k=*^qc5qrhPFjH|)5^sPRTC4y?$v-Cl} z?nwJLJR-W^Dmrj!FVaHry-ORchJ38N5-WM~y3}Z@J__}i_YE6%yHr^XE%$kKy0UE@ z@q3QY%|BrS9oqGOqcGLslK45fvYfPdy!`jc|-iDCl{C47pMBqcUfo-%SS)+ssY}R>OCW7`9aezXxTNVMm}R+) z8Ox`uBr!(DM#nzUjlF`uwz)L4G=@HDkC_~?octQ&cky^rt?Xo9V`j*ROo|gBnC|)J zYtficC~3E}d8B*S%fpLxTNw*U>(SXyIkMjhO1Y>=R)y%c-aXb!Ieso;WmkA6cyP%$ zsrvY9b@3unO;^e47{Bg#O795PGv~LQcZ|%2tR~{=FjAtZX64uK*>MqT)!sX4e-q;B zP*P5EKC#bOr{toYxVfT6$4BH9AB!f=^)>GbyYy;Z0;5TX#h%DZ#0C9U#aYmm?R&Xm zA?~Eeu2)>H8C(|GZb%PV55TqwrDeo3Y2s(1XaYl54 zCptVJDzAOVqaY8l|}m9af7hz-zc2R@*5GQ0PM8AD2bv zwRa@9oyx3L>mDUo*tzyZ4?Yl!$Jr#SKB_WDRp)v&4tDkkt2_z{sHLx^|D_%Hq^E=Y zK3?r9ngsz99oS@Vi+uv~3*aK(<`d^Kbo(R3_VhmN0Y;B(@_QZd{}(}GfF5_# zC;8{jL-lUiN+!>o-E>-xTZ8_2HJfk`ZUmB`6!Hi5b}ii_Q_I51lp!{_U7W|%ji2UO zwtTk(eXlLQQmq(bdz72k#6 z;x)+vUP8V-6%q8|MMZIUDm=#8m4~E8MD|7sEaxCJU7~(74h+lQNcNEA zm`Bb<0XX5=8`JV@tQ!m1u|OLD5(~h0!rtbhN|6>?0jDg(a)>14%^$D>B)P+~VelE` zaUPFLfJd%b!l_Vz+;l2Z5F(pX5ITr$Zp=TA>R$95?VbD^LG8HV`Zq$V$L;%3-Lf z+@YHm7cU)35ob12 zR&0*b+rw244)-8AAI|7nU>Gcq)!!qOyJB;|Jqb?2;v3W>ker*cW1ptp9w9Rz0CN0X zxe)cf1Rr|wjp8HMLhMc0v7k0buK5G-G}zl*RN&1YIAs|kVUoZbS0hYP$aFCbK9l@C z3Gr&+ap#PPrbCfhxZi3z(wU*avCWP7=dpd0?S|t9-e%?LAIAoQ6#`ia!Bpm3Ru%1S zD@aE0e!s4p@8jv$wk*8UBU|kgp{ZA#Q7eWY8`D|kll?U4xI$d0wy@c8g;>Ppt&|L$ zrpc;hR%P*g$vf{-OXE2SGxTI^6}R!KWw`nDagvvL(y#;f#k*ed@lxIKVbM-9^! z&dtDaNnZ9n=mjf*4Lb&KRa^>rgiQezz-U1updxvBEAYrM6N*i5vP$1-jw_~q_k9pf z8jQh1nPT`v_vO`Vh>7T?1R|OQu^aX}D z`J;?~)<>DZTE{h-4oYvV8-rd5m;pKZ1%?C9)I&NA8mwO$r?{Snid=u5s<{4q@w(*; za3ah1;+6$%pqzif(RiNO6oLdzxEz$G&DX(ZoD`<1fJ*72yKek+UlA~)*$jfQWJA%H zrS0_b!se}!Zo0a|NHC-jK1+^_XDOicTy=f_+HPl4H$?Mn>+c~ttLUU)UF7O2 ztg|2*8BWc}xgZsBxudL2$aIb{BPTGdT)Q7wo|v{|3ds#8w8CK>-%ijRM$yADg+QlS z*0ymZBZpTiVhJvj>4Cl77GS~+nzJl(@lx@CfEkm3Ps0f=(0rzlMYRwwb!OUmfSectdiBK~7qSm7EyzT`L8sG)1Q z>gD!oO3H7h$nDiIpP@(J*$@Eqjq~XDb(AjU#NXKv7rIu+?9PT*1l%6La8m$&%A0G& zrAx)DqhTemVaEWj(qKf`)EM^Yp9QFtF69Fr{bxe4>47WLIj)%c5PJ|#5{$t~m}2$A zv5DNDCqC)gKhy-rqVN#v%1Y zey`)*fHLkkg9TjO?d|B7E%u!ED@%Gy7kewTjdb?^RhU1%^TFsb9~>7iLRbTLheIQR zPl9rgBd&~_qaGZvkemZ2&lwm7%VW#A1#%B^1Yo&12wVNBa*&*Za)(2+j9b7A2!I?v zSI$AT<>Eze^)Hs=46#SCV?k}?IQ;>58tiQ@D)8nHoU#m&FiGHzqY)-4V7e6spGh9e zB~}eQ?wk?PbSP578dlSh&I|>PZEnmzkL`nOHyk(cHY-p6I5rS02gnNdbjq1fKXTVU zuyZ>Xs46AgH6m7Rpulntf>|IHsCOc`aMj@Tvamc>|FVD?kiXp+ zD23p%nn&)BL}+%r-N+rb%Hv?(3@p$lY!xQ}4*;l$`B3j^bKsfakRePGc;lu5c4)J} z;<1-Ygpo#_;g4T75$^Uq@ov9E*ThP=&f^9!+g9Q0Z- zc8PfSOP!ncv#Mk7!^Az+E2ss#7u)Jx<)>Y3VW`&882sXZx0O`|on?U$1oo)vbJI!n9DCco)$ z`(*DB*P#X)bL-=@ss35Kcd3_R`Otz2{)jVMDI38;?FKooRk*VJKRw6f7;X;bkvbdUi zd&n;K0zNMGyh&2a;vegs?dW_fV1{0&WfIO)Rda6x1sE3QD)6!yqtWX$nT9Y7&~h8Y z#t;;5@=O>@^g3<;MXhBzn%OoGpq`oEC(y*FN-Yau5uDWy@&{0#u?RxOkM;KAKqSBr zqE5|y%=65}WLZ2TWt}GYXw{(=FQnw153jL7pCY0v-?Fn|#D;+O_7!VGs1pA&!!aJ7Nb^N5pjE-dx) z8-bu6bR2fYF{4V|F+xf6(D^XOhs_1u&k8q=_o2j`o^~=CXhn6&Yr;$_NZtiiL?iVKw&%5~D=Ft6B$YrPU^TmhCsGxU;no70?hH0IOup_MoJBkVR) zoOCoL?YJp$dkDrq3*ZA_Q{@)xMrTL~*|1}@Ug0)|J;J7?kVipkn7oh~U<9DjWMNj@JMb8lGx`Ln%=;P2Y7QmD-<(>~V#53Z~Uq}gBw=q}j)V>ZNIKvVMnei)X zk=5P_R1F;3t3lhlOb`tO{oo51dlMXFaaip`zL#l&XR(LddhTq|cKQpU)&=ExLH9x) z%OvN~Tk_-m7KI3p5Bs*faH($T>K#(@ei$C)@!3&lNVPIox!`+L>Z^#nuW?y*mA&U{ zn>@t4p0|9@3uk=kym)=oLwe+X+#iHBUzB$~9T(YcnTuNgmVV!(;~Fm_NDHUDStDZa zM#_4jxUvnL_2AG7$+>aP`vSvYd2IOx!QAyi0j<|K2+J>0ogg_EMR~Jk8F=Rj5CA!T zuAGnBc8wRk{9>`wz7Tsib}Xok(>{Lyo(6lHiweB?1E(xQBuo-`<7|XU3Ysp5!Do_h zy(U%-Jnozk(R3(ML0VSRkf;U{fxYm7nRLRL#|$&9G)=clBy|M zb26u>yuZe%NL}=eqQyjR)Vr3mgLw|TV*{IIiWCPfFAMUs-Ze4&z1?Htv-f1;=sue< z@-9VuQ{}d>s4|=(|L7wZg5fGJo|e(nuR|mR`HS?L$=^p$(Sp1k@+auN?zaO3%+~V8 zg$8gm$_Z#nF4zG6H5`ttrGeB^4c_FX+|;lcdJ`T^E3Ab7e0qUgIROrH9!(rpBG8zJ z3s(lUhhR7e03QIS$z3a<*g;Cjh8+XAN}4teg+0b17HptEEmr>yR_t*S>3_VYG+8o$+ZbInO|@UC`ONlz*}PpTmpD+CV`aCO$Uy9<6Gq7qUJ^n`izo5(dD z99b$M)JJ{1$twI*W4Jwl;cNu>CQ-UpH69`MsgM$~VaEWjOkqUW^fByF!#qkC2N+4! zEwpk*2Zk{=QckRnEq4(#OSw#SLi;1@v^$*8++hqZN{*Cf86;mqZOi3F)M?{#Qc8f3 zYnBkQ;%q#zIu6K9*^H$$B4F^i)?5zI+6sn)4HYdeQP)W?#ED32(ew?=D|VDLx+I7)iHd+wIh6=ZI zT|U3|ghi3sa>gZ()DE|TBEx5!n%8wYj(cf8BWdTji4S3J>EX0<0*!Ai!CiLZOWqz% zUD?W2AAdqqvUCe2{)C443_bd=Q~=O7&ZF1sxa7o%KP(luvQ^0Juv9DpZVzA`S4|NEgj@|68S8m}Lu#P9^0e>w9WmJWfI}XB_G+qrYKzvpv=`s+=3USDK011N^nmy- z^GV+Vv4vMIr1%R~t&|ZmOt~l)UEZr=rdP~h4B8!XF51o&e_N<61SzE7x7G|LkQ0? zkDLc5j1QE0renpIRYF<9js@BP5Dfrs3VWN2iaxWf7&v7aM!+P2Hx2?!l6U7b7SvTs}NRGJ49CH?1zI$-&QED&hnB&6)pL^Agz9C1! zTQ~8R)!mlKKE6dqeXxVSWxDv(3=N1LpIEt|&ScHIFX@#NV~qRh^9l4daP|V9qG(a;MnHI{PWltvfXgpz}u`m{o~j`uuDKzxWj5Z z4|;8!xHKUu^i@f!eLN`oN|;^w(AH0m4^4g}Se`MrANqbTPtn4U?@llQYY#^wRi} zxg)3t(l`lldk7{L@oX!3OFg&o8SwK7tOPdf7{DeV6!r+20xEzJ4+T&$KBEsja^hz| zvFTH|BZ}v^V(NVlf^e*0jAghfRzDo)3gNk?eSoO_v!;o`G0qbM1pJd22dx`H9!+46 z>`>Er`X@2MRRP6G1CAX|@Wc{M@Wd%fou#e||9X4y^xDAMr%N^Ko-XB}fg{iZ-2y5S z*6+bxE#shEEt4RFPueRiN8>B3fLV(iZ}RE2{#mT1jAwTKwP!1NlNQAYn(?bI=ohG2 z03I&EEDx-uzktsZHn}mNKjuNtrNo7N3uvQ*H^cEny5;$JYokVozoG|aJKvmcH4H9W zn9`da;`or%Q1adPivGBF-R+3M!twUqgABuUj`F?}9?^bpHKGQi43xn?3)%9y>F8}Y z#>62E_!IO^>XF<2$aCPKfPQJ-Q;bUIJUVl|2(!f>&BH(+`!wc zJpJR?pkQM`YIjbhoCyWx4y@q^i{jO~CUtJajNcx9UnY}vaD3{S*3++{XIe|&1%mC{XZF5gTj&`a&^YPRzIfvB;UNA!X z2r7?iT(0t~8s|d1R5e1;?|YCsRA3 z4XQ%d)K^>-O6+Yfv{T)-{HDCn!v6gBl+{jM00vs)~yf2a{gc6GRdco@Ghg zD4u#U_29)s;vR%dMNaxgA5`iUv6SHus&!UfP6R-7@+&RA+Z~y2^GD7p4SgB;kb!-4 zUiy;@5BEM+)86pjj-dMEkyM*?j<)E);0d3k*M;#qiiie_1pkvUa=oD!vNB?$gl&@c z=e-m3Eal1T7H(9ozP$_?{8v;}l~qv3=kx;kgC-e!JJdzGGKTQITJ}}^EfveZKP>x{ zwKqmq)udW5QNXioaGgotovJE}md5OOA9-6_1yWU^V8Kq4OM5z$!6T>mzCSzgsiVj^ zANj0ZSm;UAjIEaDt{NYBlxsrlMCQs+bTtyb3;_{4DM=U_aXbE z2_v@W+}?4S*j=I09BH}4fOBq9QutGK?#b!@ElO6TgyZ$bQ%qupM=PxPl3xfuFQR`$M8HTddb z&JePTCj39leRW)w%NDkvpwa?@bf+}zO@nl!gmg%3y1P51k?s~mx*Mds6{Mw6O1klT z(Gz&@Ip@=R&$-|C$N9bPy*cx)nP+CrtTk&rt4S!;G6?a6K(n#T@5ttoGVm;|>2m(O z?Xr?eU@j{)qtl|Bv=D{Grr?axnM)Lb4CIen;l5AQhgJeNp1q;s9f>3Ip& z0?O>bxT8E5w>uko#&ev-B-XiIaJOnowU671L_J7kA^CT#80**j=$d+tnmXKtb^{S8ujI#2D2ZS6J)bAnwGe_te}&vvx7o5 zSp~qMd$##TX1O}ldYoK%=3RCDsaDdfy=ud31h{C*@@9`sVZvg^O$Ktcf(MhmwCXWT z@}lY>Ta*5rIQ!-OplH@O{5(#LqB8Kna#b$vkwc>v5BQQX$2zA^$6cyVj?T5$&$_BukfCaaU48J8{u_r&u5EHeF5a{0*{Ia| zf-aUy5{ewRkX$y}kSQ_RRf+@C@F`M7vO(icv&1PrSIKr)|3?R` zM2bW+&a5h7z1e)M%8*9MO_YIyFPljm$R739`gN&YL1KvyTr%(wBzndDriUczjEy)o zc-*^i+E?~gHy=z}@#52GK1`xLiR-H9GM+#sYuUG=UQt4`>? z++|AQHP6GU+i-bT)p6ufc)1hr-Y^C2n6)J3?`rzOn!2^{cyn^uiO!ny!$3f;6wR<} zwKI2tshe?9SN2%|+2b30?J?@A0`VY_-KPCrI{KUe(EdU1f%+cZD-M$krh?p8q^fy+ z{jQBX$cZ|y@xUj32W(uS?8*N92}f`QXsXzqi^c338vgz4w)m9BNfQc*MxExI&||L> z&K5s+p5@gLqicouGpTe;lKEcGzi=41j$ed;FX);=~)`*m_w*8hU za{E)5fS&1UtewTuS?qea@{}}}8_#NP5gwSQSFH_$B086jsPnC3mWku&rwhS4ClkY? zqF4c9N2-aHS~tNO2h(%fF>7A(L-guS-z5h}bkGXRO*F~e$Z8_#D4-@V1*fmozJ#=2Hi-fY4 z?->sm))$hf&MH`5x)|A{+zyKc0VAR=5;0cf0LT!a>K4I9GPK6rE1pEc^P|F#cDYF?$C!++n$us;K5Tyen3l z5v~Iy8^?xucc$prHO6Q{b1NkdsZFf1RpO_~;xWb*j%mp=ORLEj(|USxl3xytuPT3v zGt$pJ4BedEHPu_C`&efn+k24MfY&`WY*bikZ1SGbF(p~sZF9Gv`!HqEX{MrMSX#0q zf0ILOSu*Bnlk(KZyyOaPZ9|H^9km?0bB)!4IFqx65?gYd@#ss~oEt0el_ z8JF76lj3Ua4nBrSyuFa0GqO*do)prqr?aS;=v=OEG&N0G)QD^vTXOWRQytWt3Z!>@ zuoUiBIcvS;3BF%s?LN>69X9To2RD#w$m15dZ6GqmUUbNj3zCT2V>M3E9jH?4%Byv4|qE8+OT)rRq$jae{$(y1x&ut{#H4u{jC*i z1wn;M67pD{QjlKlYn63t!UdNLz4$_>O&3=TlhwCRGu!Dj^L6XU!+>)@PX?`qo#MMO zX8-6CS^-@+KwGnPVacfjs`}}@>d(HGHnbyEfTwo zoiFt!LVG12%7%)+>OC;418v)|Y4U288Ob%x_8%WVTC7A|Jb#@_pgsp`lyfsrc>qWNQI#qgLT|p zC?+*8PgmV9_S~I&REL_Jn?!NsYNqV7TsgLIy0xNR>$g_dC(6M{d$_U_eyS-tY*R-m zrk$=7>}F*%_Ey1jYN><0XmS4a8)(Y#lR#?Ba!uG8d zfMfCMPuRY-0uXP0{q(IBwr{PleQO1vg8cg1w^jgxm#a_g-&z5(y}y3?)(ZQ#R)Fl( zuU~#^h5cJA?B7}eXjs1f_N^60hHuRG z{IEm-mlp#Q7+7xCCHkEt;O`lutLgiL60tMUv9U5U0W<6OSAPc@GdmsgpXQqz`Grw)kY^@=>w0gE?I{&(Uu2k0#%D@O@bTcqBumEJ3zjym@5#ma3 z{&zxLL*zdli7Tc3gF;+Gh-an}EZXjePse<#{Cc3M`3TG}SSKYm|Yz)6A@;$UH7sAFgYkYDLSbWF6YzF%NJ zp@^^eBUl0IK!Ah)e=g=v=;}Wa^BSE0+-UxUHou1XZ}NPHIY6lU=hQcUp-3%kwE@7d zug0HH?@WyB0B;-v3t%OH|6#Gd+CM+4K>t{*Ync9RqxIDu`$4g;Vffqozrzp&u<-rq z(d3F}%FNo(+6Fi*(pqcjL3FgNZD?(+we+v+(yxZ$56Z)IMYqMq2nOs_@INQePbl|4 z5$GCjf5!;@gs#7a*l%zC4lx#nUnubZ$TBlDvw>LYY3V>{waj#B4NWafAXg{-ua+4t zU;zL&nvTJ>mG{+t|55CKLJI&}90({_0{&l!_A`qAk43wN;@>-JKcVce;rW{k-{Hyh zD+S&k;c4=9!CB}6`={<#NVV*=3{Af7qSnCbg#2d8(E8SuXu=da$bA6!t^rp9l=eK$22fodOrO4e@z z%n3jnUn{8a`{FmW2Ihmct%ZfT)%WJgS1;TTiU(Bnp#!mkzk?$Jh z|G@bD#MW{R-roed4lf9xg$MnWyXI;M(?aa7HeU-ZD=kw9pxdweY`%I=e-KPYb`VgV z>B^Y}IBtHKRe!HAKVeP$u`s^__ur4qPwXAP!}R-WzZ)4g7CM$cJtCQDnO>m;=v!OB zC2C-3rVIIIYyt}q_$Ofbn0DpBKP1x_I5>QHt`A@mP&FvsoCR!F2 zS6ao!&=g`~u4DXlW|*6p0IKE6l>+#SuWtk2uE2h9k}v@mJ8bNXfTI{Fn)K_G{%588 z3FGHaq`L7 zuSVtT9sCa}uxt4I_RjC{0qROH{ONJ+*XsZaD|2AS1|a(Cn!di{evJe8L0PVq9yUO%D0nV5lF3V`Ash(5V0Kk{vw{9}UsjN<-d!G1^YZym9p(AU2s`MU() z4Hz4Uj{Q&1GQV7HU!9JvzKb>h3b+3F-6SIjcn5Hg!ma{{KrCEL+C#o ziJz(ec@2%<-uB%<{AC%lU(f(7R$x(CL2PWT%znF*`)-r^8p8C0D)1_9hmnN|D9#5| z6#I29{1Y<$!~y(IWV(jc-!x7?p`L-WHsE~$Mv4&dCHz6a6$=aKF9NQBqoIz8t@Xd2 z4Zp^e{UA_`KtW^>P#O>jvimzF_zCR`R3)SX%6DJYeY-XUzsFPkXG3sJ%l-vd^8NMC}D62$Gsn)MwuMRv> zqZ5-DZoj|2Z=*OqQXv`XW_RqexT7iIW>_#DvC_J^zuip>>K%;^pI_{x9bO)TCU1*) z{g6=Q@od$}xMsFF{rSR*<|T6jck223mpNn=E2^mi&{!&_raVo_jTeh^m;0l2yo0m! zpxrqaH|~oI&Q)!my;<)r%wwljS@yF|m&=R&GwY3QYeTXD9OAc8+*Na1*e;r0$Th4J z;L{P~aML;W`M{k(l;vl z6=@dnl71fM+ZQ=NR(yNZ$Et#lx^zoNewEAQL+4}BrO0_cR_*A|vzw~W?3I}6^#0zx zXsWoCQw=?c!=rcDm(O3}82F&~ZAg)!Prs#QZ|J!n)#9t9?R-wD5eMJ#qW*2_iIqLB zd)ulnU%Z+!|8{fdst6fOw;o1ZFA;yMZwlr~Ol%^x2>s#R`M0m4NvvOXcBxMp*25Zg zjwT_+Ncf2r*#zqeJzKkHQkjiU!kah&BXWUpgfL6rjjKAC6vM$kQV>tKD@tOxofg+e z_0G*~Wi^Pix$ZtxGfpcCpWPXBArCDdBYeJDq2?fBPIjnSwz-OchR)%GIOfh6&8`g! z^2{%Z6U^<-O!U4o44X?qmOPCk=VY|AAq7oQCvuvnckga#>s(&m@1G;oaNsymQx-DF zi8~K^3NJo&K1!u)+!s`&-?zj}>d4`%X5O=I&|DuN*$TtC>X^FuQdB)G_{--SX-|dP zL57>^US_&Ap2RNNWtee=kOx@^mks^i}t+d^Q~d# ztMW08%)*EIJnsJ6{Af;VX#{Xi_Xk~^K1{rHo+wKoaI+KDpNqPk;u@R^%1S>WQ&i#@ zc;5Z|6PBvk-e!48v)=j2mV+>hW7tkz@YrqMrua+S4CJlVO;vTZhwV97xi=@P5>_;M zc?jp-!2bNp8|$puJ9b#JxsLhb%}`-Fr9~F(4+QDXuv*q@-s1)Ji#u=PM{Y>r!jv3% zkz^FD;iQ>w^PAZo?YT3aayNcS8aX$s#jtc=ceDe2MkuU8i&%rE&#IJ9dr~$`AI2Hg1boXC!*2JtbAKB|T*+abuYn6IexG zlM$loiG0(l#Ul9fCAueVXdula1pR_GaoHzJH(^S8H>kDECLX}ubE3#ueFUC;E?A{Y z(KF#GO_hN%l`v|`FBevaMcLXv`m92$YnXcbC4NaEsMke8I{ ziTxNAiHrE=>kn%ko%IEzD(ld?xNL9c4=L}Ume4I`qA$eMuj;<8n7hRD%< z9i?Vs$X?y|6i8!8CUow3|Db*;Jj%z>!Grs+0q ztjYUo3K2^;sPLWtm_0{awLMHdu_(_$!veWs|_qhO^>4e>T-`Lhpo z!Yyv<=Xw))r^sWlB(gFsjX`sbPEQu`$vLYC_~q66Nk*R&H#Z+Zd?fEvd~(qH6j?k` zx`cr!Mpi&3_(DkB+r0;0^uS;Oulo%Z4H<3GLFPMd_RBAb2UxoKD0kOKrplxdb}Jrh5nq`>9t5i zjllVcHRBnkWzOkKdsZ*6rl(qTkr{dWpZh!(u<5XnKGuh-C68L;EgD%_BDQzu8B^+O zsOxkkG49KE?q?u|ab%CnDA$4c7cesWQv%y)lju5b$IeHjU}C>a+?O!9qR2&oYHOZ-%MG0ljI8-b*I225h-q4hA7Zn14-a%Zp4 zI_QjEy$9F8N3JK->%N50i;f7NGLgqL5xU~tMVNl&I=)afPop}#1bEPA&*+rp*Kd8I zA&ZgKAuNu=5tV)&HjY{$qTzIeXd+9xKxx6^OrtQD@HyDkm-S&eTvgI056iU=s&GwILu;de-D?gs1ay`sjO8;uq=C1-*m;# z6GjEPg}-vx*+$;6O!jGv@W(Fk4@$UMFJ?)M2RwR^Y&YM9BY!d&vyfabQQafT87^#I zHrzKBR&CWY*f+3noG3TBX*8(!Tna~&wH9oG6KaZcD=^cXIenrUi=CqiN|DpFkDoKy zF4b~Q^NKie;f6skhandW6sp5Y>03I`lb)=GDa2usP4X2F{(|OPCi`w7=K?q zaeLSh-{&yIPiWW;Cz47cTe%+@vm>Voc{a^;Rqq~LYP$2(N*vgvg4KdMiOD?aNfQj> zK|Ve`0TY@xCY7rgQ?kS|Z?|&lQO=xbq-gn#a-FFTU=z%Kly8i8)L59U>2m(yxBUXA zt}b80D*EWgo{visiN=$~OS)|+qN7pXx<2R2emc!X0U*6=$Sw9kgU06N{``gJ+!q+4 zGW5&5b?z_KIs!;tPkLvf3tcX6i)3&W{CnOFP#f=G4aEO8@rIG<>ZthdnK$xQhNk@H z4uq;#2__)mnv{tZbXA*>jRmL)&Bo3OW&ympCJ>13|K*Q<&wF5Gx@O(}#i5j$6%4+9 zDDB6Y3e~OHX=qyDB3b@$CdB{HlTeV7@Q%bCLB}{lJw6$8(k=lvUfVMDt*z16c=hH` zr>Uo%bc)gIdIVMK2Z?DFk`Ah!GB4)Sjf> zOlu-OOn;W#kyD(&r#iowKz%UIoL!Io@O|^#o2?4Ao38KQ-H|LwMl5G)WK0&en?0l^ zr;Fn7@Nn(w?XUC;gExfSfP$?K9H}Bs%em zaB4Nb@V>^=1O3!5pHFg&V9QV5fJF%QtGd7@^YN~_xRu`T?c6UZQ}a&)cn|f%rU@+B z8hPErEln?1oE?Xdo}Rpcft+vd&G-{k)n}o9Xl8j+GxH)3;T-B!_6>5=*e{!nt_m!v z=UQXO!Z!8jFl!T!NivdxLRm!$Fu2JkQ*!Kida?pLG$f$kH3t?zjpe9>@ZOm9j1=DX z>bMDAN~uHC&>V@D?~N+VC9z1v+X)QCx)B;M6bhsDl6$Pha#2`oR6PjgR&!qmA)As} zFg~L%T-Cq4Fr&<=k+moIMM*xH?)u{PJza4%b;PvtUOw1J(}>6S_M~R^>70^N9GHR} zSKtSPbDikZ3)y3NZG$7r*STmkOPi-ANVJ=)@rk4OB1LYbgO=4o$8z|i6|p#JbXusx zh8#BUp*1GHO0iTbTY2p46C+aRv!`WSOjlu0zlW43*Aj|Fk-rNUGH%8=U$^hnk)FGE z+Stv!&!V%o9qv(qz{(*Kf$)m?mHewHP+p7H7!9?KKK>k2d9-BU1*L?3bO?bT32Gri zZItbSQa6>IyE|+OOZXf9(oCbLs>^ShywSO8I{IbiQ_v+Dd-poKU25e|XvNpDyZ!$Dra(kBtm+XCw?e znlN&q3>7zT@#@TxGkH)VvY5_R<$d@@Bn8%<%&22c#kc4L=luog;2VMa^Uzysi*IK* zD8JBa)p1J`3*m<(A01k{xnG5g$Y@O5yCF(KITND_tkw(>P?EIk-PcWO?$2gEY<18u!?~ zBxk6RDeoK$s{i!f+qJhs(i8^nY0}_R!{DUwwFc;Ux@5n%j&w7;QJZnmAsml09$~3G za#=Qr$YD3gKv@L~9pRQe`N9wysLdG@@g^^t?@)0$o^q%|$`e}flHs;iLI3S`C51j- z+w?lU!L4)o9r09vfE4#tzN-E6f!DidvQOCDZLkO>$JU^45tsKionQFV^Io884{e?}0h-z~+i5o5YEa{6pV}Xr$iy?D*SuyYI8AV-YRkFk86UO5uRq(RMT{VtweI8v0tNR`qQ>?;&)HPKU$#99b_SInm9Ont! zerfmO(=v-|-x~~OMV8M@Qt@`9Srv9V|)}vZoP?wNsnC&9jee9cHd3~C96!UA=TSwn?v$rYUHayg;E0}56eVs$FdGj zR^v`KD%4`mZC3-;bzlcBw6!qnRkl4}E*I2Nr|tObxRh5a1#KIK-8r~D=kBqMVaCzQ z^LQ!-VJkcW5xxeN2*i zyU}(DkStwarL>hl26r|2_Oew0^zke$sA9um(maO#!``;KQe)N;?RF!0`tNG{QjA5rINrX79yEdE+OJa~1*ZPnGMFgOhBIo~#^ zRJzwA;$6$;E$Qrc8yogb8*y||P7f0bI;#wz9Vw$d_!2G9D{u^OgXCPHBfWu?OLoEOB|KtF=i zd-AAD%O44`WoqD#E!MqL2qsNw@TiJQ`?7@)7F;|Em9^?u%^QD3UEdhK2ceb90K7D^sV2T)`{pv&DqDNPc zzIZ9+@DyyDM;Rsyt{HKVgY{FwAoAetLgon>Z#Wgy2V4%Y&!Mx|Tg9!>%~~9aYy57r z%cw+gj}S&BJ-C~~bvym$Ba|4I7aC%u?>HVM6Fz(}?l3{j4ib0-HK$2;-_zhlr`JFb zIy5UEw?XaFh_4e+oQU*g&Lg_u^QQZvxP<(lD49LFeQxAHS;5wyE?E{sX+`X85FX2N z%|A44jzrd8i6viBDc6M!hwp=Qb65r4g$~5?c#bTWHYS>&B<5tY^^qeGjjQCY1Uaol zM-}Fw@=9wK)P9r?D@?8MtzAEPq;4GHY*8eNM}&kzb<&&R0r>cJK3Jj;ZlqxvfFsk} zpyq=xKE{O-%|F@mKVQKedp|=iGM>IMK`k>gf>EXQd>Zz)t{rkVsad44;SF798!HCQCuyjk&N?c=pWe2{G7p|eff4U08{ z!c}e>jIvd1N=F*6(RpXm)JbL^^AC6~%2~%t26Y`jPY;_Gj%=fXyA?eocSm4>3TBL= z{{|$?OEFq?R0~s*jO_4S#wtu1<~Scg-kXj;z$cOR#T~(bthX`39-_$Pk0?TJdEdUH zv3qA%))}9V+<1@#T5RQkmlb}xoJWdC+Qz5(dUPj#N5RR68xJzLT5eJ{5|hpCiU!21 zKltqFq=UPpN70J1d~ZW@sx6RAE%B4ERc9rQ5Taol7}kK%s4Fv|#Cr^8o38j0jh3QF zq9B_c#*Bd>MrLH$PBk8OWaLA5CEq%|H) z-09Ey=)SzTQUR16{5~*NpNcY^PHWf1xMAo5s>QhcSy+QgQgDkh9xFkpqHnt7B z5SvVtk0A{2R!&Qge@0X}nK+}MOrUU7wj(jQgf?QFywPK7M=Py7Lr83n8G^VCv{O{$ zZBZRIO&lg9I7tRYLq52GEUpw?I8F458=~la4W9)srxq|g%D2#~Um0(fK5Qt?aFHp2 z=UBzBH^>sC|BzMwnM{z>4eF={h9S*wL{Zu;kV(py`Z4#gvhhP9nE|wL{TDjoAZWH) zj?PC6QLZ#Oudp(3tg&gLNL?f>UfHFRHr>zoXnY$PFA9Nm$C0oDt(K3UW*5&A=8hM* zP=D!ejcG153ZtjB>pOt!o=BC$y((i8YX$ zQoX-r1WI_RDU$4=R(97%2!}-~Z!&*ztsjEJu%tReE~zt5-mg#tDqa`Mg*mX9a_p#4 zKX7$6N2q(FU$FEtz$NZR-{vvteQ9R-EDJK-aB~%fa28SLInjGIad*ldHKMPQXv}!g zcQ#E*5ox|y^G4G{ltuRKe}LIt-a)@7#aR2w>F{)|UHP-fjc5Au7U{g?;&-cw<{t&g zcqb5Ay;*yFBdSc8Dy$`|9H*HClx1WhW&divGTJq^VUi%_qwaJ(-_XIwHA3@6pY4`_ z8OGdI++|Y~WR$Q>f5g|RgS+6kq`Fkx74B6%lNJKbc8|Mo3t_G6Q|Egh&700X5oo$1 zN?Y52#%7MKYYz9|DR>v!Vt9 z&-XQ1oL-KQ{;90k)qjMP1~xVp)*STo`ao2ftu`HyuE7EGHFA=Y)oKXh&F@`5QB+{nT?H2n^~6$$gKctfg!pO zHa#Hn;+mi1>u~=EeFk#QfE-9xpfvsUJ_CV?U%&nTyw5*z5zPoB(tz2)3;^@WwL}^g z7G^qjcEG&^WH2%@|6wlrKL@mq762?0BeNb8;O5d|WYJ*)GlE&Qb(z^%wRD(4Oia33 zU{*Z{`@aDF6F1%0JI%~W2fXJB>F+uX{^i^M71IA=s{TZSQ$YOEp1i^3z!ka0s-j) zx9tFd3oF~d0R0p9`9L(vZ+*VvkomTvul1P?prrVpuIT@;&p#MKz{bLI-CMh?qH2yO zcF!$UlX37x-2Me|0WmGKr-Jw`lNetiF1F4?;V!Mqi>v539zV}?`?KKi8P*4@~#G9>d#n@cxaazPzkUz#T1zSm1Vt@$Kf(ZcmL zzeo&y_RzyP4U!xZx7rzTpM=smle6`s$SRZvE`w(;NrAfd+q_amOz6ZH} z%VxGeg?D=#LV$m}QRdRVh4YBD(Up1QW;}2zj$Amn^p|65JUKhRtovBCEmj7^Q#>11 zlC|}HJ{Ea|_?kO&I1Y20ntc`$G9o-%E{?t9G;ee1E$Yv1N6_RN?VQ3gZyBM=y;HE; zdK~guRQ<8Bj?}i|1m?Q0|3ab`f}(20=aUHh%l*2K2UVR^v@tM8uBp6I-M;My^4i#) z1mSi%!43UiQX0Pyv(7R!im&4|i96+*-}=H;H(t6Fp&BlFdXf6&^pMq@s_{6SG2zx- z&d8F|oV?ea6nMAkh}(1VoRq}3dF(eH^*M#0*F@8=(j=9d-Kd&NhG3|vsvzXv*6};0 z=A+Xd>-E36;$2SD(7~Y73+3{9FHzQLJug(+#K{5g?!6)muN5O%ZSTYc(C7F8?0uib z7b}$L!R~MB_xv-=TGYW3Ps#1cKRD{u(9MhK@fn4ZI#Ob{37*-wd1H6yr0PKTCe|Q* zqD%1ZFB^2WG;kHevE?RylL?(Xb|VDQu1dQVdNt2f!tfatjy0~3ket*;TRdG77pypJ z=BF@eyEV2FgA=$<$xl1Ro=gYS(!Nx8eyv26j7VNB9=>XpFuEZ8lxNF8;oRPc7e4c5 zU3PDLsBFgqeeMPIZFo*G)Qx9i$s29mHBM@jx;a52yPo0$najQPtggqrMgEh^6D z%POD?`a=aA+N^d}>!(mEV#8sJ^h0Wh17ZzN3j$D&Agf%XiX{Rzh&tAA);w++Y>R!Y zXS*f?y#o$qtMO4e?9_`c37U-{eGL4?y`UXk%mW!MrA^Y*lLMa0|o_F%ShGvU32jzU2>7j#w z>Ra*zudv5%w!Zx*Y57ey+i~lBcfXh)g_h4$M!7f44tLlK?4kLgl$N_E8^S@hiy8Zw zlZt(cvx1V}%CH#{bb}g2`>fni4mZ^b9~-THZlTsR(QA_BRD2ai6PqyJSurd~!dLe( zypR`k5V0BYsVL|uIc0J^H*Zpt;MwE&^$~CQr}rE+PaNU;SqX`d2f!HFZ_knF@d z(=>t>*87=MgE7%atGv6BjvK|>U|YVuFp>3PtGMfddE~ya2MLi=`UrLEU06a*lsMeM zt=t`}J$suA9q~O?x2I>jdrPZSYP?bo*<=ra&<_4|y_W(=@VUfMFR5nMBUWZe)5^&P zSe)-#Q@7nP$q28bk`0QpNqYUHeIp~w3W~CiXD|-mW=bY$X5SLEQT`C4nzns1@bmjX z)-jm8IPe&P(M|mn&4@rnrAyeF=Ln!7^aTAZyl|)ovC8D@e%_Qc*cIwaFQRL)o_9Qt z<&i9jeUW8{Bna|)nOPY4Uju*3fsKnGChq<&u)1FH)@a7K4 zTJ*l=;UZ&^Guhtf8-;`wkU2h;h!f-C}kdts)nA|Q3)|69y4`T5vLN1J< zRY zU-V}bX>4!>>rMI1drNn4h-gjF4b$X%Ol%+FHsL~52r3ZA7i36_4ZV#S8{PuxetuD& zPc<`qnetaA{J*8+MOIAQao>>e z@!s^J|CsTmWd*%%e~X54Xpbb;a`^rvjZV0fH<@0z^utyoT&I{~OBwb=*oCEcEaA*W z*)mxj#nypZPA~jK5JvN!j?smnBnlb6%OM2AXP4~;1jT3R3&sUoiFA?Qvw{#kml_%G zfR#LIc|$rYHvUR1Fv3xT2OI_q=N|E(+%lWQL_cmn4M4x z`I9oVoyFY-|9at16*{XQ+60|J60*-^KV3>M@3$+%r{=TAi$n)3j_+ddRdQ0$rA&^O zAv@g@Y6maTC8&)rwLb(ozaZ@&iDeo-7aCENc-DrPvn_iLJ5YaLUSo{k|ENDn=%w_N zWZyP5BlKJ7)-c_c2RpJEm0i}`Ja0OLh*dnjCv}ET$Kv!i9=a%{D^!OhA=5bUJwOlU z-$Hcz|dU?8U26}j zb164vmxE0L^F>G^W78qbl-!BLET)1S>yrjk#pY9@X$G!|a3LL1V(Zfgg-+OSp}EzM zcoyHv9gLDL%vZCDqhR0E1)>*gTR=dX93wLeqXT~~ee#U$zzoeRR`wlu~4{v&#=s;&GmAk`H zti5|$8v8k$%W~Cr>tokp9#-MA=Xt4z`;nS#J5os<>xJv5XsJ-0XP0(+OtJ2lH`8C7 za{Pf$i23gi=V1QhaE{-7LSKDGfY0a39rX|Se6GcL{Nk3m@<`Fk*=hrcV1SoK($LHp zpnBD@Ayoa{=W~rTk(uEtD4PKYG67io0J_OPAba@dEJSujT|F>ZheeBBS5KFLg$bmm z$Iis8qYcq!)?#7+vM%%he;Hsj{)>h9Z{EGHBmRed26ETv*qK?_fsk(?e}fM6wR=Ev zz!eQ1JJ4AmZHko+cqf>N>3`)4_|H1ca^+wA#nJUw0X=}P=emhFqb3nXT7}qnRJ2y+ zNgLz@uY~Z7;;>mPm`%Agz#I3JQHLZB@!4v46G21<{>#GGAGc;0F?O`;wW9@PTwJoU z5_}t4c+GEo!K9UB%>DqxUb!9hN=r5GOih01JPAv9bF$XoXuS3eZ^QipD6a!WUh(B4 zZyo*IW}0O9hOUlJ+#$*{agI;b?niD%C);0+502(sYpUGD{Vu1PoF^|93uKY--!!zR zb~_X_lSO|KbU8A>57uzB4@7=8KFeL$6y$$kFH&)ev=95Zjz>EAF*3$h__8j+?6GZ1 z-r|U*^(J}24j1pa^_Q(gG65qrOAqmZGO{nHi9T6PL8n``RJSw zMshhVjr?XT^Jtakb`?QgV^{(2&LWRKmVL}6H^B?lXi!JJU;GA7Siw3EEF0)xBY`?_>yyzq52ZWkdchX+F-T7|R=h(1-?xs>h%383{doy?PqbTN4ahmiZt z1>(jCl1L;2`b)-N=t-583a4=mvDu$o2vw~%jJIxyHRfvkR_rF$bq~veQpgNJBWC$ZpdR z<|S8{PC=OqG5yXF;l3rE#IkkQojz;s0#%xiVkcPq?Hz(7)_7zu85~3dPaeRs>@MD3 zJEDz#yT4C5D5bwv9-#pXsmtg>e6q~4r0SH{vpqsm#0qYmtk?&$As_6t8wPH~jC8%0 zp;3SvPzsS^?3qs3t5>a$=gwIXkGI)xlc|=>QEih_cx_=?a5Jgh1iCON6f@htyZB;NY=`s|`Mn$kPXU>`f}l2@ZRg{unoMA*t#X}@Eiz0GF(u5c5K z)M~<12!Ose? zlRS|{91FuTJladvP0A#N?YqJTrIf>hS1XnI9W%4n-uTH(huz&Z(~@f}&()}K*y$FC zH9u>#!?%}Mw&WI6^3+*nrNMe8+sq%x9U<>7E!9;1K?BvfQ0UNv*>YYpd7Dn$-Kg`{ zO9Z)#dwrG~-N7n!GL1G|G7vYTS0kND0f|n6mW`6beavtjXGq(cf%o#o?xmUT6A%eY zBM&r~CZa#AF#%yn7r>R~mgV-k(Cf5+5>w47$63C7bzdfm@kIUY<2`hPAe=bZ>2{w) zluGTCg~E4;J!(2b__eNv+bJ}ywE^61V#?E&G-fx9rR+7{_k{?x^qfr61c&VrXE`8Z zQslynpf*_ogzMN@F}3R*EVNOfW|f7n2+F|vV;WH(i9S}%xP++>9XOZfY`K7fyNz4n zFvxFH^M5LMLj+wQ-9YJA^f@^`EXvKu!3^_;rm522P%>YVS@C7`)M-#lUuDS9136Vl zD@M8FHaQH2yaTsEod>1qG`d9|tXq;hT83;aLHoShRLGc=(5kHnSp58Eo8G>C0G*ec zz$ppN2&ahvZf_6bRL65E-@9poqroJW0@7(3Ma8ZqaZmU9-`TdCR3W1FmI_Jl(SRjR zRegg@a}pZzZAtWFxwO^Sp`M9@%kkQu4l%>k7aJ!xPbeg)Ra3{~9q_Z7N%l+BMK&{@ zVjsjL9KXCU1_|O49%~QQrn?AYCi>&hZ#@%vGlCCKRkXm+%%L%|B|OmZA*nUS z%M^>a6AtMdJ&6JnJA2BfGk$_Tu!Y4DZN?RzaQ-5?MfGM^kM^x;(sOP_yM`I{BvcNR zdTn2x6fKSHiVxZ7#kd|aDaeKO$fn+8RrG3Q6Rlhi-x+=2;w2}q&*`rzam=(d@4()6 z(eHdbjz4sNEgdJL)lV!_c>AvK#Kgy@Pj80H6F;&)306bHIFderFD#m;%#NxOG2lOJ=B4Za@#+(2qWyRBe|VP@uYrh1$j_zm~NY8dxmvGP?Rk!l4e#3OUh zShMZIhf^4*;(UkmtR6U*nWMV4LuQP;v(_te3XK&I_477e$U|ot472_wS>nbh+Kf>- zruVj-s&Q6tiF@?gtgI@b)cM1ydWR`^M@!2y)jZTm;gQjZJtfT0S1Sfsdhr7~Lk^OS z4lv)JXc*fC+ClB&ZC|?WayhhxfHE|ujZBqTj=Qtc_!OHO=dY+6&zDsbY^g97? ze)tG_NgqOPRm(`cUFF`Ves?A$RC2;(J?8mS;yJroHA=_qO?o;`Y1O zo=aGT#GgjqyJK7wCpp5JM=5d8D=qS->&+0W^OFwAXU9p)7lmg}eYQ^aj;EmnZ@BO< zy{30NHaXgUs94j7qaDW}%cUeaj7CQaTleL_QmDnz+$rnkf!nF1!ZdQ3&8lR>(T!{y z*uGh8tOwYKH{mo*s<>p`<}+;~=AdLK1$R5T=>2U3D>+!tDq1g_j`wlSPsRtfzLYy_ zTk_iRp0r2dR5#9PnewLJH%Wq)3ranJPyFh=L+@gDwqfYLUgg`)Tc-nA(dXg9? zGBGDPy%ppbTDShFp@GF0{$9#N9k=Z`lPUdx;n5!59?WTnmrwhqdpg29Ed%Apnbqn_ z%=d^bS1xA*9a5IVNHM{dc>(IhnuakjOnku?JoYhnIc1c}QHo)p>AbMC8v-2A-o>~IA3(pNbfAPrJLGB zm+}NuXP5Ksypj|uWka-3K8cTf(2hmvQ^vxn{!A=VkmW6f+#|a4V7c3enfyY#q?b<- zgCxX)_qjy+q;SJ{6jK&C3@gg*I=u~+X`X{{*#)^te2aB6_IFE1G;U|1q54|TCiYuC z(T8IH~vq8#`aO&)pd` zTm<|e3IXr?bR7>PZ{D(WSRF1)=30FatlK#)`GT7rjTB~?2|1xvTbQU*oN!?gJqx4} zB2n*Tlo7+&VBk2Qoza~Iv*AKL8MBn#{>}p%G)nJ30KZ?UdHblIoHNBfC zY59K0BfOQwI->Y46$W$}Hw?S4lvzyiJ#lCI@chz z{%AN`VS?Y1%{vzU0LC7UGOdU~n8#pAII^;AwL2xsS+u8p=!w3yWxFpV7{#p6wN9uM zeM};z^J$pc$;B#)iL#|0Fx`En27(hMimMaXej>BnN=atQmn+FAzVlp(Ww5V}bYDv` z{RvIzQd~oJl)7IXM0V)ziRGyoX;}A(N{KZC!@OFF2Rh?Udc$1=&0rN#2Uu$oCd+e- zY5s`Kfj8~ya_Y`GvH6r}oEt3z>0X#&===O)+Me`U#K*oP{?O05LKIT1cGubV2bLi(p@VWfjE_QtlSn1SEVAqt$(n>#3}wkuA5vkN zk*_ktZ&4v|ag){HDSJ?vL~^UAFjRTwL8s^Unj72_N&LJ3K7f;N=}LTrLPAol?g*hC zY$4G-Bv(`@?rm3-VTgo`JO#{Mp5I;2lxg+I4MyA)weO>~foY9M@|)OHn1qVChw;q0wCN_}zMmnk}NcY8MXJ35o}sztk_!-;Dq^7p48 zBRuyNB)JD4tir@UsIaU?I+dU>8RE6Rr=c{gkJ&=KV5VcI!xTY{m;z&oBu5B-V$3mQ z(+%CWu7CH@N-qp%d**7?Bb*3?av$vJHZoOyck<$-r^&ky$X}{IKr;F)2DQ~!q}Xa3 za}n2Y>RtbcllhkVqQ7^2G+JW_THT9x+#-$-`)C(Rn5+3fdu8?aiB@Omk@n1ZIV<9r zP+L%jxSsP);@sTz96y@7+??Xo844y)Qggh0+lukk|KaYff-BpW^xP6NtHe}dW@ct) zW@ct)W@ctAF*7qWvr4c8B`(R@yH7{A-5vG``?_z09~6q1(!-iLa^#%r&m7->+_6-= zuSqd;^XPoZJ7&_RIlaoKaro9{{w>T z|9B+nZ%N=kjwJnGI8F4$4ESfn2UZ4lj(;yc9P4a=l67|7dKKB{wXD6auu}lV?fS7PwbgO^9_~{K|9RPrPAb6 z+b_&y08qB4?|_ZJ58-=!yRPH|o>yj;XNigT>uR4%`Ekoue?#v6Z4Bm5HYHySnO}eB z-mt@F$4Bl2LZB+<9{`uJejD8CQD2ucuU$(6k0M2tbyo;sG%7qa!`U;L>b?R5sKQ0x zUzZ^(e|BHIa5nqdIn=jVXFK3FWm3`K9Vs*4oR7ZS380T6582?QWAO?H3 zxu3WvefRM#qAqSKEa!XB>r>mE_ugsyh-Yp6qmiejz`Md!I7UU;I78qZ}p_QW7gYGN1GRVb+ z88@ga6eV^G=Qz@i?8TM^4cVxAHqihI3kyz3M9NeuY9JrM-7`Iz?9DaBN_-wHEQP%E zQ}_jB{d3r?+XjoMPNDGr;0*1ELqrwG4hA!SO9 zW0}iV?E(Bo{dg6e${!I6C@~(BQG%;iD)sZb{pGmvKR`b%j-AIaDLBnF#K?~hespca z2AUv{a=pIN`Mp23^1VMY))J(}UN0~CN&Jv#?*!J3878|>70>={NkDZ|Vjh)$|M9sORW6&w>eKA`83T0gp9Z5JZ_uNr@&kjx;5A zFpdz$u&)3nH!BrMQGtVr`wsU&+{v_eUjUloqLKjw!-I81d={330yvw{7%18eTtl3% z%yw%hlql-8K&k#|G=DO!ose9u(hz2ll{;4GA^b63y#O%c$QMQsxxi)b1O44Z<4Sos z%=i{Ibk$H1KQZ`58*N4z^VYpp?CLbjJ2<(0XK&nfN$l+c-Q*mfuwHW(4_KUFG&sew zV-K-G&?;n9dRQ6ICG2AzcrVFks6` z>a{0*;)<29Fs)R>8QpMnw%}r0z1y6mIW<_Jml zj)V0r#I%VVW06ENxC*gtRp4d5r4NOcVtgMqQrFFl^ckf*`V5qsh!Y3_4E2b3%_9jZ z=PWY%Ot=?<;YXng$1di41REUtB!(jB=+om5+%Y-o;%oTxt&zgTGIV#93MM8sJ~MV# zq7vVPSUt@gh~HpXm@5-W>jFfS2h@0GjWFqx%=IVf$prjyK}JngdBP>@P~ME4P&cjw zxS& zcG`F?Yq&G*09YeKup=xJmQzPMVewbE8d4)(qvr%JA(v(xvf@@zW@xICvIj%T zcga3&ji}5_%=m42WV%v4dI6&8`#Jbk%t=9#XlUTN2WEW?Zb*ev$ZVL6q|qZSvKe#C zsusuyuFu6#Pd3xU6bHH0M$Q1XIf^L^0IDgh`q?%CnE=&58cT&r1Fb%Z(7!p@QrTW`MUTRl@BVo&qmtidgNzW zj1SogqhWVrb88oF3~^Cp#7Ocwr$L{CR*H^gF6$%H7 z9F(1D5k;I-l9!|viZ`NZ6lO%!1yXs1fVXs&@o3jb6iRC4g9Tx-t|whZoJ7sEryg_R z#PhnIKdOtw2Rg2jRo`M?Y0@OH^Yjn{#7Wj|vRYRT{{Y5xxTZE0L>(z-AVeQ+g>JYT z8vROpoz@$V$+f{#8aX_Yy=<|u^WYI-1l7*%^ZFbt3{WuwX*CYonjiz_3k7@liMm)* zX+Y!*bdg(;IXs!?DESh_(1qTVhwBnq>@`EAg2B1W$Xn8)HKAruTHsu zc`peEaZ8<@PMl%k(%x6F1@NTk5|J*=ojsAPWkoO3THl$j{*+4{z13<{z>1Is#^KVV zzKN*yp3;cy9-|#_W!WG}B(T0u5_|f>S~3Q^DR|^*mtL8;MsO<8f`_vSRLMBsD0$CtbCsE=(1pWkx~vAObki41Rs%jdqt?BP%wrlk^0O2a z1Yh0aov8s1NMNQR7nei-OA7D9Fo*M^tm?E7LQswl-p%Mxx?X#AA z@+p1*TSns9tg#gQfF_0}%muMMgn>=N*U|vzOi3Ipis;-W>5O14APj_{~Pca5a^Gai-5{a zQ#$$u#aZ0NhNu_ov-fCy6z}|q|(ht~oSaxB`6;V49TmANU zmZF?OVFPbQJIsHIrVeO&kg5bpxLCZ^i)P32d3HpD;;;wsyK4yj5hW zQXgQaze$HPDD<)z*}ANsq9-kGCe#p{hD>=af2agb(px>an7vx;j?6~>QEVe0LJ+Yr5R^DpLp}-f z3YCP?M*d&{{NFa#b+Qc^Q}pXqTF_5~w`hP2BZFeqBlg*HhMN;wG$*y=Put0XXfPQt z6Z-rLkvMI#F;Hcy?^?w0ObM+MU`9nLZNK4D$)htE89h8UZv4*{Q@`jwHP22eP+qh%)O=gtSrO~1PS`3>s@khV8(U_^Gof!P! zDVVOC&?5puKd(=99lqHua@C*JqT+X&yW&Mhvb1mq!{@v#KcAo@+H_63m6{#71gc+55X zir7w}ZgkQfI^tE2yC(Z(nK!cR{3wkRudVIuyq{$_ks;Nr=Z3Xe-lZM1V%OBTlgqk|^h&)Z-z;4CVK@|`rbH39uWbi=ELq~xID~9pc z3l;Nkv%NiKSZ+Ojkm#WzC`vL>u3@OFcY{q3{68GC?l;}V?8MEqH$J>lUwhmas*FUK zTWcrHNfRnuv&sp!?z$N{H|%R|(_6b&4#f=LhHJzqo`*}7Hl5oK|tx*dro z7qqPL_I0$y8Xv({mXF?L<6f}PeYB6|;^?wUlU1(Rbkvu4-@4Q#Cg)?pr&I?Cu6TBg z1G$Iku_%$K$4P>!tk5GJ!9Wj)eMxboQG55$*rQo;o2tmAM_l2+>heK+#CP_i&5%47 zncy4XxoOW#Kx(I1<1?`Hxh?4BInDDMX9ZaOc}eM4$fq%!z+zn8ANITW+k1l&5vMD? zpK^2&nP0P5MFC#VVC@kTUE}*;KU6ZW{q>qY?LGjlc0GUg(cgjEl?m4yV&drBeD&Ki z?gIV4F}JUuKaQqw-RWbhV(yIUqj}H=$bJ1pDGR&0WA>9k*OesxAw)vtht`$2(myZ&<05S;uailkeNZY$8>y`8IFq>9>lo zd1ceb=j4MUJdWtWH*HX5H`RP`Z%-RM&WmX#YQfEq49l;fS(DIs8aK$FkT zknZphQ?pzVc|Z_;1|Zc=#CXtcXtU*`NfYSgL*3H=lH9()ue%t1!#eYjU}!%9CH4d1 zk@ABPSt&z7V=OEbiqy8!&?jzgm-yYs@Y!aotmV~~v2`-Lyt^1^} z^crI=Y)7yRwFz@f9ooyA1sZFS`%LBY&-+PC-$(m~)?cfq>DGc#u$uQCRz_tJsL&b5 zjHW$xFQg~oyjN_!QVfR%>bz3ICb3a2I;?t@3;5hTTxO=Gy4~z(XpOth3l9%|j{m$V z9G_-7@^uiYD*nNw>8Y#dy4vf|DT2?OJMg+{BFENSM&n-WrVFjhrS(9`Cf?$uyNhkK zGmVZRQ~AW~_r2@Izz&JXZj^k>XY**W=g_T_Ic#${qSMMvBl>-L&&X>CN3_v#0Dkk9 z@7aq0uBVJEBv#=%Aa=9{W+TU`t6`7Tc&;%_~A z*x|$;p=;jg_VliGGf)*@dk2t8<8Kua&90Bj9e>9KO^fd93rSlvIi&+n)^B_eC;B1t z(cOM~G=$woVq;tKyZxhP9^dKNzQekspYIesB6L(dR>+fi%NcgR2w8vtRP-6?MXh%a zeyA=Tiq)mn%4?knOolG=L~3)nvU|jLGlzH3`&v<1`lD8%yagUbUfW3@ z_t}k!ut(&0g;_;$B=!8|ETdce-RuY^(jCdP?^LtFC7yE4o_i%MBVRv6eNanPATM%Y z5x-fqZXjB(ka~qYzgU&v`oc%FZ5ax;kFM04WxGGa!)jd)sm`VXUAp8nR>wu6E`XgUeyPyoEfg)=kOBm8UN@*E{ zkXn7fp#N8~j+%L%P~AS}`b4djNzr+Y<|O;Uvtao^9nEb%DEHt%o7e^B_cF8ukq+F# z6?>fk50H!5a+4+E*C<-N*7EU1lo;(O0PmUhU_suR)}>c|TK(w|WGPs?YbaJ5N&4b1 zr35cZ6Msel)w#N50~q6_W^fw)I}}2?a?l`dQ)XT3{#C+o2$eKx&c&qXnrrj;U_71- z`n%5vE9-ASeCN4T>>2XI6VRAK)uRjwbGI1HRp5b0_CxIP4nO;&57nbcl1Nvf9TlFg zXflSCgV4OdxOwCGD-`VLQA{k65j%Kh1*V; zBXDNTkBM~0xhQif5k0CZE>W7(`VwB+k>`Q>lnB;^Baua?EnabXG16F0izUb z&8Y-Jo`ak=SA4{!36%j)gJ{Tty;eWAWyG9Kt)Jg>nii6T%9kawSd1b4zAFR1%eZWe z{DRI1@6E@WB*7g19pUVC%-T3foG?h~)(5(Rr3H0sCc-JiG!Ey1T+S&=ytQiiyBjTE_dUN})IOO!qWtCQLh2Spk_Ry(S|)@mV|Gj0xCIZv!@glY85 zJV%W2BO`=2j(=@=+hgVdJ5#J}3WdLBo?B6m;4_k@oi*+#z7h&z1ODCxuVQ#d`s*)& zvuUF0^}$9;m+4y#Q$h;fI6XD0=Jb(rMd3X`BVc^c<#%z+*)H0W^V8(?3_(57q}!Ud zM2nTo%+He8@xXQ)yzC^!p=t?>a|B!k2yl0puXFY>5JkTm;iV&3_9{SvAjqxSm-xd& zLnf(bHH!@TM4Fsv zjD>ZfrmagYV|h?`60wad8F3Sf21yP-W(lTdSFJSFNAX4JRPW)f>>?a5!#-o2+*$f$Y#-m2mrl=04uxD7W&L=x!%iT$=5{eumcvR{)G z^}GFa*ekYoP<6~^AtP@JeenJ+u`|Ovc#4-+vued0wzLmG1q{cMeic+&#g!ktw_7@D zBFI=1GZgu;V7WyoQ#_ z9=od;Tl8n@kZR^cI3=)C*LRtz$XU7LSGK2om@zgus)r?~m!-_Y4G+sU*Rf-3ojzjn zcOw{5{U5>-Y@QFxV2xN>qjbRXF%I$0RPW5E+7z9gnNHo3B$zloSoQ@xqM69{0*bga zo^X_cX*`~Om3wMng6>D8?ORyd;Xq82Bs)JseTd#N<;I0|2U0NEbbF4$HHbR@(HU0ByMWYA5K+i|($$K&4Nnv{g&0x3tjr`G#FOnvptR45> zJK_1y;wLbcyCVI6)-m}HCqDnrJ0^c0%KjRMb+U7DG%|4_`1?>c-T#e_$-g_f`9B%g zWM<>|?>Z*aIP12=t+zfshPiOTCqCa`fEW%yA(00|SI0uQr=p87`pNmT!`^)>BSn6$ zEpB5`jCgj(4_BHt!mkV$nZ#m!{M9M>$wqmaSjeZV3;)S$o&x+AfNj-JGXv4dS!}+3 z9Kz}S96yXsPW1ec@5AZ&;;^3?c$g}$as1dkT4DYd^19QZH(Sbz~#^(X^mRRTEsB8DJkUW=LbnCeeHyc*^!jY06A& zV}+H}#KT)hM02C;2_yXg1WNM@x-m=?m6qtME~rb9NJ4;GpV)CTMXh*OjKKNSnykZs z>xcbiEdGHunKQc19JZw9^8GQOY_NB%K9X)DkR!!Z4a|2lIF!WVfh}g4G8DCuN05sB z{pR`W$s5*^7O6ykML`xnsQH~gibFr{bkGeTM^z>?BfcP#=Nv3byOZ8!F`49PX7us+ zYxmEwTkD854~F(p-jpaTADW-mGXo%Lt)2$UoNY=+ElFD@)F~}$`%2NHO(CeE`$~1I ztp1Jj1J1`^`6kY}!l!cKuu~X)?nB{0$19e*y|Sd4;4qMpQ{DFjTiO7))&>$@D#*(0s}aeZsB3q);Cs9T1V5y^G#*h4x*rzb#UICqF}IjbFP$Z7Vq!$ z?;u=d$PS=K;m!w8I}5|rW-kZgoVcM4_G^)9`pA;DE^8Ukk0qh!XFsrDrt;_INhG|f zRXNle293$80csIxADsK0Z{m@I%fx;Q1|{4J21RbrXGaxY5Bzh8igPI9`!&EcIVy!= zdqL@Q^OdDHjw%AiU6_4nGQcpe#<7$nZLhMJgUgRw)PYFbrO*wTA zz(uGBxO4W;o68QGHH`1+CgdQi?|zb})d&ZjC7xW*)-DlHo6Vr8Sr(NfJDscrAGuQ9 zs$tI!vQR(sIpIpP7OdtML9rhc@>M&T12%{kxnSKs_HeDxfU#FeTIQy@eTgGBvt*M^ z9Ma|KUStJP(mXW3*wF@>ohd0np z+qg(kF5d4jJE#adUFMKO8G0M>SfpmXyjh#$2z^sZfEGK$ssDKT^|5PAsqFP5S*jH{ zuT=rl9v=O|Rno;2(z||(O_j`!7%xyM)EbO8r)wzalswySfK(lL$8eJTiJ12dDVx+= zUjAHxhLl{e(LRLq8GCK=3pO|Cx$OC!(A@gsrY5K|s^RO4-EX3D$@lnE&cn`!#Dlq| zj-DH6@2^JA1s&ouDXvuA^E+@})7S0h^pWLMaj9hIK;k$tDfEd{w4ybTqhHE^`3uf4YLrHGh&ivju@D(EiGBl2`akDIAiw0bRsWJwbi)d|J` zGTdDqe6D`qE}bObZ_Ihr>+LWvOl;PL+OV;7El)&)(rTLAv^HI9vTvlMX~7z>sa6r{ zrvJzcYY%aeHO%*S=t)wt$$R--FFp#UIi21IwxEdg6IRraRRae=AI-=Mi}JuL5)N@7 zOrB8Bx7{ES_zSUTb%?1uam=bO&Y+N1W1CSR=Pj^HWdKTYti>ZWT9pv{cldQlEx_>< zB}GRO7{r@qCEBIO1Y`*p*~O5~eoVLsy0wEf6coDf?5352CN%g}F+EK4zRIPQ1w$q! zS>IF$KceX&$YiEyIvnxOGS<(ov@6^4tY z$T7^?3{@Vxn$wLOKh6@qN$2`tb|SoCy82bQVmTcvi#%$@5sy=qLo=d6xC9csFgBrN)#(b8`w$#zQG6l4RAG@CtG6C^!tn<+zlZ^~i#6FV znNwq*3p2Uf%*@R!47u=N1pYWi4ij6S)JUL%w~1t7vR{CFre`gl_ygL#%DbsRylF6F z@;j!=6x$g0LIS@SSE?5>++@AyD?#}1oMOq5wLV=EF^C^nmzuuC52>br63pcK;L9W8 zh1l<~~;c&mJe?8O6C4P00_5BdhplPZ267Xd@Qd)j9?by3}Er{k>`B28V zZ6zYQvcWw1=_ab%63-h1p*8=paQJq?rbBjr|;_Nl*_3bFO44b`ylWB8R}O4y{`xO+2|&o3k?(V%Kf=mk;{eBaMsaKHjDEgJmA*d7Te}8>t3% z*RH4BH#5Idfy5xAfl~Q-o1M$tqFvI&een;?x|vGX*;bw~UUK)ZWFATEs2GGy()DUG zZC%;%M?drOZuYi?YoSuHVSA=Dsq!>8OnB=Ud&HQuKVfgwQjG3)Z=yi0 zfW|LBJ$mU?kUf#hg+)i@WUAdnTVL(5H&7`Dhdvw>ZqJ0|QQVK?lJQtB@p~;Gj89Gm z$RYgjS!*jNz8;-2L*UwYk_e$*9k^rH_C?w|mfccZXjC^9$JX9Z;-b=QB=N{iK7sDB zDB9k#P@LTAeh=KwZ43nkBP*A_My5R(9}XdnPH!ZZl@$hasOz>}pWo0>&05Wx)M7j3 zXTzF!)bKuS_?g9Fai6k1Ya50r7V|=nPc17JcyOSKQoOyWmjex%X#fo}xwmk$<&oJ6 zv6m5hoj9R&Bf-E;ua*38*U?QxN+u$U*n8~6#NQVc!p;DG!AehRtiGx7Q;nILsk?uA zsCz@3&o+%qUasRQ8N-X^k4JB@gF{g+GuLsfpLhKWZr5dsnwJUkQu#Tq%KEk9X--L# z%nfzKu13vurBkOMHN$RWV9V)nrR(WO-%+KB!hKhf=VsTXH!_E{hk|WQ4@E0W25h*G z$xQRqbc9;&z3yR2-X|Yz?LZCK%`nZ@@1X`Btzl|fvMyEUog`e%>PoLL;bj~@71ZKE zWSO^A=R^A6J=pQLFWgrO2c*mJHLZRP9Ujd9r#$z6yF?(27#o>u`QerGJujlSiTR`@ z|1!$TMm63xe`i1!$=bqmYgy&U_9B9QTF!%?)vF)6V?hW;c`S`9Zf8o(OpSH*2(~-8~wZi+r6+6>E*}?b%pQjN$;xpQNU!)TB z2jp9`DN6h|9Ckb_Gg5N(A1iIXtR2l#sv6&XaRD%T@X&Sf3;F zU(PiP5PbjBA4E$e$cNV@keX24Pgiy;2`jWSj}kS~Z=?U6MdinP(YN35(@5SJ>7fa2 z5z&I&<^EJlTu51t7@^f5?cKGm{J~&S>@)&N_SSQ}Vel{N={l<$?)VVrD9H{Zw;}Q= zdSV9>P&3Q~?!~$D_Le9bLs|&1n9Td0TJ(_QMI`$!1w{}F&?26N305dO5Ls64@hBxC z>mc31i6}(RP-H@C{>(mvnqDHQ$`{{U0;~14s}|A5DyTq-_FMvu1PCyW7>e!>AbVJE zb4@B`@+!=DCx9f*=aXQFKIvc^KtRQDJ;3QR5cNs;XAt8G*u6D^=oLCI2%O_k<3us# zc+(y5tQw7f9zheJr%x6(9HF6r61jdO{8I925||6(AJ&HIs0mV-a@T?>4pV;|cGAD8 zoc#KWw0H&s_OlWxG@CRgdcv?pNs&!sI*0n84r!j7n~6M+ZkAGbJ?W(1@uPe2q^iJdl4R&v`H~1a{;tTw+NK=i~7B2KT5#o zN)wvSWs@RrXoKuBE*K*YU^pOp@Utd~GlwD(FkZ)Oj^f1$h2(E}LX^XKNCw}BF!L`H zg79Rbbm&u#=I+I0c}z|A8kO_SoslGoo7a({gp$P_Ei6F6&-+0~B8d8r_Q;zskhPLb zmbe3@Q**^I4yG7DYdna>ig)fHlXZBqPo?F^yI-dZp-xXyL$Sr%UKEjX`uP>8UV z^}+c@nm!JtU(`=dgsD_t2jQoU0}Owr8?^RPv-5h0Ze^i1+81=O z46o}AApE4;2}RI&VS?MuPKmJJa2_NCxegaT>R86fR7 zSEkjGi%cVK?1ZM0}^3)8u3$cZV2zP{ql}+i@9=*D-cO@( zr$CZSeuxy-+oG>>aL%j3JS09}d3NXt6=%a!tNU@SC;?tpho*fNm!JqtD{h%TTrMDk zxNh`7_H9CgCRxlNanq(R1Pd_Y8eu0t=)?5p^q7e40i|Y&=&Yk{ePnY9xVl`U3GAGX&;y4t~PA2 z?ZR0v>hIOlc&`KPOi^@#9$h>g+=VxtOz6c03*F>vTu+z06H~G05cYb1(?ihXTbsuD ze2p8d+r_sglOIHrY$(C2Y1V=+9dY*ld;$Ev@q2v?%loizGLU-Egx}Ir->Ll!40mYlnamHJl>2kQ=-_8V;*$R@ zKa1sRLS!#(QldH5p+s7Nbp@7}vuRZB2iMo2xSN<|a@B4=RJ$?kU^|WG1A4`9+29Re z)_P}1F}zUjM^><4MgNAQ5)Jx!t>??3+wSMfn^d|hh05}sK0i$i-8z>5^9D61co6Yd$G%@TWIr=enCz6*Txk)FEj^3%X?(S>s z=QC2O$g1Q23`wkiLYUb6)^Ra6>sFr;yCo?d7N^9%Wi#%7m#EpUA6O6tb6f*t#po zWduTC+&7Q9k_90r$qPPg|@W)+!Mq5eg$n!27yT`&T z3Ae>E0o={wAJf_8cmsu7t=;6u^mF=ZSz^CSGy=$`UEzvYi=W{$&us=NMsI7IU5>$C zVpi%?7R&Ck;ued7t3kHyb$(#X@r%D19L-;f8<{rtQ(BfNd z1l{tdh{W}ZpDgR7w!51YF3d|9S)&HE;g2$sET43w=rGevhjUmL<2nRNq8KV7qbq>I z4g8e3IdRxtb7aOJ?P`a_$N>a4LIC;`)G3A_`kI9K4XzkDeIKe+Fe~_~((o((x3@3K2^##dwoN{@eL8VUwco*mg0mYHy)h-t#x z%+BxUjR*HP)xNuy1Ikc^KCvYuRtMTmBUpxIO*m-$r)NJd^ z5)U(LMLd$0JyK;5MJhJd+?T9^kLT|-)*A*Q(BC6b9TYF-k)%!{V3aKe{VV@k zHiu5#XQ+5Z>nLO;bkd%DFoQ^$xSTDd&}?>SjphhfpnWz0MH`+;(J$*_U_aqTY-}2n z>8F$|9#Dv0Z*CCu{HTaDMfVxT$2u-#Z^?Xl<1Itau5RurN; zV6IQ&y!Hp|#*biq_>1Gjc?#r7EwV>)3KW~89r&L3ozI_Z4G`k~8xV&h>HZfSQg99qA^#ZK5)@Hj`H4BnFb{&nWr6Pguc$L{xuMjV2tTZ_-l;xXC- zFN?QI2P0&a9!1I*0{+g0(w_j(Qfv5U7-wdnRDd|R|vBTuIp zt99OX7@8B3wmhR>;ZSuOMjgQ5F5>`w(b06X3BO?cPS^HQHClhR)4P3Ar&^9%re~jv zj=7JHAQz9O@ylmDL!sQ336l!Gbwi=At2j|98cWQwr(ib}UPV*hL=0=ywP{bNhGp0S zIFrvt+>?7Fp4-M<{+kZ$IMK;E;aQV*45iRQ8*4FGp02QhGTv!r*A18Oym9Fdjdb({ ztb5liF;Cbh%!M_EhMx(<$G)sz;YgIv&D){IQ5l0p-Ik3a`@piuSy_IQe)uG++0;-J z4r&QNVYp5gS^!iTyAwLqxNXc27ahBH0;#4jq3#-{vvp4L}d-^%Z<|4ayD)Hpg zs-k${9IEzhf@64(jowg6Ge-&5APBP`ngtK!4uR~9egRBnM&fXTgXS54mU-Yzoym8V z{ovl@c1NLj7Sc|I;TIpsWeD zQ@WX4`Ub*-B++)qVp^*`Cd{J?98+jIE1Fccbu?b*MZIg$eQfM^QN9HZ zy#@2^@3@hK_mQs(HOPLch>EoT)}Q{5tzE|S86E<)awkQH2VX=i05J^aa_=s4=)`^c z9lvN5wXC>y@{KoW)p(@H&dfEz7M^kLZ@Yc6>{U$o|;L{7Al#+y{5m*dC#6eH)-j>20ZR z!^CIB<@3yO^UStOF4`f#=H((a71h3;QnbaSN+(cXrm}f-gpY2xMcsnRy2*pPUXZ_+ zc#_lb3~ty!AD<5Dwn^bGu3>KzraEzY+FhhncI^bP%qoR|n>WlHQ6C9FdN;_pv6k4$ zI-BHTfdlh}guZvIm5ns}&_36ri705K9@sU=vE&Z(3I!^f^iWsZ7YE40{1rQu#|j6V zJZQBdHPn>9BG>aqlR3rw+{#CyZtR^F@S#`+8YS92Rqi63I^BG{rXq6adUNDT{M*B= z_%$2bu65UYz2x@I?FnzSXg!K(o(|{N1q_p%HZCltMh(mIPv_4EyTY8aP7le9}9bzVYon%677KH*pz|R-9HcbpD%|gFDO^gKfmU6ZAFlP;378a&Cizy z^P4Uxq|{r)x`Jdhl&*~{XHl3Aus|BZxA0AR@V+k&6c-SgL_%f=GY#KY|H6q>Ti_d# z?0LpXm`+R9UU;Um#-+jCCBoq{^M9Y;eQs$fQEP!-d027hwEpd!b=~N@D8GNogZBf} z>Mg}&dH(qzPA|c$%gTQBt%bx6e6VR>{bJ;UC0?m}W`E<0<$rG9uQwk4+XyI_srf{$ zxrCum$>mJ{`H>WGti$}fxT|6pdwlXObf-aZDY5lcrKB4$E5hTt!Ok+eyLaCkX8%qT z7QJdm)=LhE)-C7-pWHmbGskBZqv$+i)l4yrAvf9JEa9@$mN2>Z27=Sj6@*xdu@j-L z=Xp>8q|ak&l2J&~DNAhe;M&Tw#Z;S~IzPY6y@t^3irerE$k%xY2Rst`r8?eZQnky^ zZt;G3w=jG<`-+LAAq`dN&^-bQU|NM%XInl>#5p4#D1geCV=N>nbN zl|jW`0j<%~tQpcF7Xct@1Uos8$6#9wZ$vGVhXfsE5Yp=nBT7lI@UqFB$sLviD+g+C zOst+ORH>K`ANZ{Y?0CkDh3&jTSZn??#2+*fHjF(@YsKg)pKNY;L{+MaC*=bI5S-6z z?&}$179!p8I9DB_8v&*A0vULP2~0%&jmPpaEz5Adi#wVmm=&o&9Iq|={2saY8O!{-!MputdT*>wzz z`ZzH?T8IRUwvD`*;)kMe7fHd{H}wlVtVN7(i^ppOwdJX$RvI*@SsvIa0nY>iiih(< z6Gdf&#nFHRP%~Br6UCp^-ed;7F)v->{?sHP6S372!j?PrV+kR9k* zurw99N|S>wi!bk;Zz-WQ}v9>~~u z8e1e;j0thXH5(w1 zD;x+Yn!}Ks8MC2YC7Ak9i%WD5Aa51LaDI^f3MW!b8e@RiI1rZ*?jB7Lq_dQ&LH!6l z3{NKc)`T^h@c8Xb?PC0iUD42%6qeiG>Mp2;y~BbfmT0NRbs&-?6T5nHbV^>Mv~Zzd zQFDL1{KqWe3w$oRW)bTPS?&xgU2~=_Y7;M+-iSbJ%G=Zfr5qg30$K5a1RH7D$kr{X zV=k5}f)i@*hlR4@1x8W% z8AuOFO$X((=}n&*avtQ7`Vk~C6sz2qCgL+)&JK8hWf?Bwg7Vw79GJzh76&>i!KW-z{G zrX<3IGNiM!M|7`wG_tc+uRew_tcteB4R*D_^^M5`oWhmN<1HN(7zn6c5S)l@vIx77 zw+9#H*&<3L+x`2gXfnniVe(sC3-Gp3#%VKaP_1=GRf1;3O|}P6t*nP(6HAfavE|fyavyD=v2hQWn|SKgVBfw&7>pP z=B6df$>lu+N4b^!QV&zBRJ)!BJH@k?%w!USB+c1*`eTU_>+TIl)(VA%(86<#ESG7o z)+RXEm)usU#pE`L1~c1k&ZFY5%F$uRceqjc>S1N)*y${&x-N;bNv}rUvdC7^L_a7Y zIT;LlJG~g008WwTsiw_EhuaGDqL>}m)EL57yWq>NnEW1sjLpELAk#0&>S3f$>1QK4<_N%bi~poUgmxDr#;Ylg?zsuE7|eJo(%leqAN4^ zN9ddBBa7B=zoxPz3ls3NUyHUxHzV-7C|s^@wYoo3+=}kM`Qh-OmHTc_cJ?1_yc;sz zfN7ON-u;+6<^^Rs+I6l~-k=!9_kCVO;KMsF3s|{NrrTOS4+B-*iF0&(y!quxQio4Y zUALFFgs|Hr6y%-w)S6z~^NZ-gM&8HF1>L~yd2ibDiGLd%i}~!MXL>T1{__oe|DCYw zKa(2&zvp{0|1bES%>UqfGXKr@Bw%3qhX)MHKRjSq{^0?`@(&LfmcOOT|0~`ve}9yJ z(g%f+{x1+FBkLEwl=aI9g!x~Xn9L09U%sKsvlccnHE^+Z7BIH4uvK)iHgTeLva=?V{z8fV_XN?u7wmr{ zT1*_Y?5zJ{GQq||%goODWw`MbE%tw0{VyPh{{IoJztj4kjTSrGmzxj^Jrg?tEB#kO z{cCP9)6z3D(R2J|PC`%n%q zpUkX(V?DEc?MV86Nh}6tc3K7oW=3|_zukcTsN(mVCG;WVE%Fu`Y$V4_Ab`ebYI3?|6^78ca7Bl$$5gWdtm$b1g2@8 z%~;~rnwvl0|5*2#Y}54_etR2YjgLB%SrNYsx}RIzL^;f7`>Pk}D;}9xeo>j3IpdCu zU@B&KE~wZgVVLq;p?~%i>qA0Tj^Y?&>-PN|&>ECkSXNfUzxP_ClH24q9#-^Z0Zr+7 z_G00$#b0~asGH#zfOqCMpllZ24-BXJjsml<9~@o9UvNV9m-AQW5?(L+ zp*Ys>WprYVw~7LzNShmr%fmz_&^GNmtdA=SbNEI~O&%{-7Xt$9WWGJfDz+_ zX}bKu?Q&R9Eo{iXwj}3qQLN_#X@>JV;2bbq=leE|aMR1#L2nZEiOa{0`|*?$*pJub z2hq!40i>xf_$mRQ&cSQa@d@o;f`|r{_5rx`>?@nXz`nT3h>#Z+%Pi)V@#qMBPtE1GB+n zW01-K67kT8J?M-Q24s(?gmw^mi;LBHO?GW4!MihL;_S6B^m7Gtc~RE!5_Aaye(x$- z17yyh`_!EI-zpBWWsxatd6;RY`J;bNm~rb}o`iI2otf-CYoF$VR`~#|rU|bytb>l| zc>1~g1e7j!>~u%$gXn9yYNW8zv$;>kZ3#Ty#sgbL>b(F4G9( zU*B&Jfd)zT3$}2Nde+Urepz0Rl>OUc#T#g^xpiBWaPIC|6aiwP1U|c;qncodx=BAQ-Z7GARyi3q0WXAnf9fgMum9SJ|3_z3g)qbf?nyjCq8( zeF;1XPfqQ_`K{B5kL2kkT0>_*Dvbl0aiGlykVh`BWv5+&*?%5J=O|6Q@&Q{Q1$+uM zS~Uqtkgpcy8_+|W9Y>yTtcJ>;3TT7=p6LzCPF&Ons^HlBDn|^$I7BKeZ~6;Y^cMY= z|Hp4%yIa;)?6G|X^q!CBb)udw3=t#+}nZ3$9uH`UDE;e}zTv)w~75ZHSDN{jqvADb~ z%A9s{##Mpk!CpbAqcarF;L6{#gQZgNc4R;gqIER5Torf8=oELgYm>$R;Se1l3XZhB zY*`R+HfZ`~)~Fk!m`N^3bWR>=aJqCs9^?23&6Egk5HDPeMn#q=7fcQ`qV#WkqF-+wQ;$TK(g+H3K8yz7gQx6rrbEaso1+fa0&0A?04?8?2vW@Hdf5| zeG|VX!~>>g<^?lq(8s66Ja(kwQ5l|%cC>9Kw@gn z6QDZq846O%9F!f?^)0d>AMpkg&X(;k8|-^?@PK_u9NmsQ0`UHuZx&5_LG3}}m2%{I z^c*D=rT@0vCrJ3>jQYI;6k|tr+y#WaeaJXRB+7fsRw)6TE84t_?rxk42ri7rz!x9H<%b4sK6FQVL zyL>6dqAMTRWzLF^G@t5Q@}tX%M}Fx*-+dd1kr==k)fWFzVseIUAH;>% zIPuS7_jmjIV&5_;4Ykl*{_rorb*CkN=;>EPRAe!1F(|X#m}7D8>t8Tyd4G4=uP{xJ z)p1BmZr3EbSf+#5MPSjA$(ku8v_VZEs?hKnJ<0)$m1{;-IVEN5Gbam-8=#$5u!o&M zv2l-s80z*5C@E%w3ByoHa0HhTUm-vq6WJA%i4mjb_EFu{LE>Zg&c>vp?1hfb#`M+* zO@s3i_(F1=;JG7|l4~m^6xa-du3Zn*ad*x;5$wizavB{kF!em-WQ|&As_|=uoowI{ zW{G1;?P_mNLL!aGS@W-OJd!OCZ=lSH2jDQS!dWb_VKIl;v=2xUIjh+cq{WHla+Yo! z-M5-gus}SAuEK#Z*d9eSJQtIQOy>E_6^{f+;Ol&yPokj&G=;B8VV8A zT3V8lH*asE#_u_A+q*~qNhf1?v9QXseN;FfoeIe?!D@WdpvfVQAVt-JLAB90E;@n= z`*G0mdL?K$l+~z=={Y|Q&me-B)@gy-urUl8Y-+_kD7YsOkq~NY2<5`PO4gg_VboX4xG|{%pFRD?$OjyZJ+_{pTrr;-VKNn&}HX3fexpp^5XW|xLA2Ih2jHJ19$g zrux3%xTXxiRZ_0>eGATN5|jIx^4sP-*#+WrUhz;4p>;c{jB!qC%xgdldRSF(+=v${ zscfm*)X!e;T4%YyS+1{hIaPG$S_ zqRIoI)hg75CJcTDIk+7jZIDQvfi(!Lf8esp@`Rt?juFiGAIN(PEZT3mq1R07= zc4_F7{fm_o$W}pu_tImoe!M%!;i)nc-z#pQRpM?n z?vna(Jb3VvN8t4i7T>qDSB#(ULoY;rcUjv$tQ^KYmvbBK2krK1HNV?Qe`tYszvA*s z<{tFghzmw+S;6)`pXNG`ApZXKTtd5b2+1$l*iU+PaXa>e5}GjbK|DUo=^gi3cm)?~ z9P81!H`&V0M;cZ8a;I@ZQwx@zes9(zpk1O^>&rP6vkvb*fp(bLLKs`KztI|MQyR0W zbgZGdP!0GrIP0IBU_WjN{fl%57vhUWXfrIdxzJy=dkR>)_kguqVPa#;?UA7r1)Lgy z%BT;uua)x-k829nn#yuIopSE(V;l#8N$@VnR#mBg#oy<{-v&-c+f6_g*{TlnGY3BJ>JAW~1VC%Z;6c>1J^ zO7QKozcyjUwBa+7G?-g5XSI7s!ZE@8N-H;hTsFGHr+ z@kLZ%MVighhws0;Ua)i!ay`7?G5r!z15Nx4Lx0U19!@dqZhdK;dac$9j}6QV{V`F+ zFl0O3GHo2;f=?|5^&$sT#pG38OF?Po!%qT-he~;o*U4K6X5d}wpel;U| zg|kP-(_C4Cf_+Hu`-YRrc%Lg2^m9wR-+*Iz1oIlkO6KA)nsISOb8oreI3O1ZnkbWY zGy;)NqE+gI0cXt=KOgZce#Zbe?=t9CSsJseEZuLfZ7&?h%%!^vB@ZY}sSwROuQgYp z_IIxlDO^Q;QR!yK_tfgg!@CFgK%1_2KGw%=s%SpT_kJOl8_Hd2HH2X)H;{TCDF}tl z-mWh)UW8U7Jln#vOI&Y6e_PAPW&^!L zi44+Qsie$8430sKmGD(yZiF2M!LTIRRiuM*M^of9!a9k~Q3iG!RfYrS-a)_iG?uT* z)`$KvQyq#*oh;a2tcY-Ji#iw`C>Pba z*Tcsz$vgAMC&zT>j;o5(c$bE4#SDhMx7(4Bg#lDUGN)5JqpsoHBa;`5Bnkuq1o<}GV_`6+@{cG!p7%yFg#8PRP)ALL1L{2qq+;Z%F@hBTSDbjFo- zk54BqJ0AHZ0|sIS`5uwfUa+NI_WI^o_Wo?QQ_!$i2ijupq`FfpI88q;d^#{VWzL?7 zR;pl7q3+yYHY4NHa44p`q;P~$f15N5a46x;Nvfgcgq?S{zVNIU*>5|@l`tO!+uZxd(+oWd0 zaUuv|Ry~8b)5}I)Uan`42Wgn0aVS3)ElXV4b2omk$l~iChv3zv#9<)Vr0TYF#y}sp zq#5GTBrMV*wDxsVfK97@>z)OiU&`T8f>zLsjFjry#>1-kyzH30oQSUMIeb*0x)o~{RudEkCOzvx53S{tq6!Df;=&f;Tg;pzN zHDQebZ-RbR8RJ!^kE^;NA43N_4?^p{L7qyVOHF0O*CK`4{OYHSN|m~aFO6Tv>h7k6 zXC*xt2&zdeziit^>G!RHZLh{P&@2Q7JTT%Hr*jJ`&y;Y6G~3*k*#boPU8#v#Q4bW{$w;V z07srfPPC!ILZgaM8tX-z57Co;XFhRe}&|i{a9o zNPjmp4oL>>!LzPw05c4%7ZJFwdh*xe2u(uTdqc-^`Yb_@F$m_PF%!CA_`NT@3JjB| zgufbvl@IMs9fCf{ixGj6#bB(pNaArS+PC0|%N~T4yj421(mvQq6=j0NIv}?%so!Bp z0WwKEtUiiG7eeT0Sdt$cqzW(}3o-PNsd9^e7wQqinEXi6&DcK1-W0Lbh`Uv5riw@3 zu$GKlhUgkD!aFWr$%Yd5BuQ@ID6WvDSZO)Hs+t^5B!t2`r#I)1eXa~f*7>DM5-rJU zrc%Si-i#=7oUCfaIe&b|qSUmw&vj8y5-DGLf1#ZUF?UimrBAp0yENI0;CR5BkV=Ml zl==>#3{hDOK5D7>qe|tGpkxdydEawzo!}O!$6^#zRz8hH_fs5t)}*Ar8GTBnyvS%m zvY`u^HmO*mqYEiOoS6b3dxAvaAyp!Rwi-!R_=qCR#QwFP^&UTGW=~A9ceR43kHC-h zm}(a77pb->w7lhkm?U(44M$>?FWHm2GPYd6chcc8lPCK z?HLo%bk=64Le1XTSbUP(P7Sr{#7>#22ecl~*cdog=CY>oho^>2{FqiOH0e7U^!@?4 zPd-M-TFFoKxrm%jAs9sUqlt#tUxcIwR zd3I@^yF?>c0^FShg^a9-rR9o9p4u+87A1DvhFgtd-d+s`EHn;9I*kfxNKo)fo-mW1 zaZ^6(Xu8&L#BIwO-S@fnq}^{NZL{=`ir6MewK_8#Z2Ka-tDc|~Wtj|w!53KiL=~Vx zv+>W`*?HI*C4#A8M<;-b#7grUv>h`PBS%(k##`8IMTf}FIC^@^N{h%%5!QsH+QmMS zbsPN;QT9;|xhh?)6y6R0@B@xf|=>+5uHCW)8DcZOAkYT5AvFBSw~s z+N`0U>GZSlk1n;wBnQjx&QX_z>@uyeHNJ!Nb-JxUe60*vgxVSDYq{7Y#cfH<~3;dWP{cLi*9#1 zS+_;O+K?pA?}9ED-hkNLs3-!jOf%>Q#z(M%n8KS0=F_9=hqoS(gKf9T{|Vk_{U(A{~JE2|Ac$kfT8?b{Fqq&!ekr(U?^Gt z5!L_x_|ch}I~mY%GMhWlvAUTV(ODXCFfshafd1vk!e5K;Ke<8}IoRldh?EnE+nE8t z10L)w08U0?W=7y-nE)J2oWx8VzyltCUH$K$A;bS6gtsxUH83-A{QE% z31yeE(h}ZWndq@pUlnpibO{Aisj4`*_ZRJf5AxEqWJiQc_jmWlr~K5DQ`?R|CM7Dm ze{r%9_LwNbtyhj6F8Wzcw1FGPnKjxmbGsk-S9jV-eoyDuayxz0d5NHe*7gdJt>UW| zIk6wlBfC*ax(hc%AM9o8W=#-A$x&iPST&Ur*K6~^LV25D$if%HrC+^W9|<34_=@!7 z_WFg7?|O%quaMiv(JY;)PLty_&&WAa0ybXa!WiCf_tm!F9*+xMrFuVx_Fs_0dVI=~ zedNb|{CgS{`FiG0CmgFjzh+f4`UUoY_*EMMUGBU;)(6(H~3o8et1Wne)aWw+@ndo>8;bjzs+UOcU^iUKjZ1gQZ}@* zksa|PdUsa)I_~KP8;<+VawRqWCN0RpsQU64aFzDJw|q14nbT9ebB9nPF!cirZAdo& zuJH=4t~imNfsqS5Z3cagZ#soX+ewoX53o8UVOby#Y1+A{pydfPS5N$TE3r}4~Sm%uUq>QXEj?H!$7V|DOullQ-HQ{-29@pYS`+l$+-WobpfLvWj*3ug_(`v`Nq-V ztDij{h_6d+O6;U!x9j@rc<#6~3x%!(_AU~dPH)!eD*&f$ESjJevl&-vXkO$tKB{PW z*l0HMP7Q2JbQUxC#(ZCPm6tRJ1+5W+w>;F!-}<4DNJWanI(guB`A8v(3N^6Vq9X+x z^V(gAONPvED;-tE@VRQ7edyst9;_4el!|&?@;WAx#+8yCwgmY4zF-B_O*XQN29-NZ z+VQ~^9JsA|ui|MIg0%BR#ZG?fW{LQcOOYV*g@75a%94`18S0`r?1KiS(2;hH(bFTR2>+21BkB1*iKK3My@h!-83pU!2 z-wYBWTwaS^S?N<1vZt$57UgU@UOBI`Nv{QUx`=l-sO4D+}k$?RIi6x3g4OhO0DZxt`Z6`vla3+AsP610cm&ZQDuq^uT+f9pGQvxXDb7vu zC4d=eS2aWDP^gj1}q^>&XH^k088b@U(2(< zXL4ipKw98mtL(Fgtz}=G3pw&*zE*bZck!m7*j1&WcN8@r`tZFTUdu(^Geg*5yC30J z8b2-zN2>z+DVN83!V=meykUi}z26C^6o5ypf;~`|xG$`w4_SSmoZsUXe%rpLKhWV{UQajuZH?fquL3`L0utw?#Z$(yXO3V>>er#&*k?NS81f zNt3?VhalPVH%DA8bW)m;WCMiuNf@kj`1oVWA$Cu&wOT9W+$VZ97VIujf-fl*sifDR zQcpBD!NSUvY40h&gf@QfMd$V-;GH;festttgsv9F<|lYu6_pK)Y56VC+eL*1```+1 zs3V-^xMgxmis(D<59V(YDCU7ClxD~(CC+}nF)1^YbIFwQ7>enY+f#gHktXA&;@%zh z*1K7>$8P&1xH4t#|Z}|AVazMFsV+o!24}vtSh4iR+^HK zQ)mT+2?E=zWz`~KEu2IwXe9E}8l;;uY!D9`(-8}{d^5Ta0NfXphvezJa1e1J5xtO* z_Ywma3lAKEaK{YtG6ghj^(U}_ds%KS7J3&LctkYYJA`NI1(VzI z8+7Q#n=lu4?Z#uKy{fxEzAMe0ZZW*z8M-9)=}xz;Tkt5=LqKOP@ObM1Nyv}uNnj7B zj=JW|amRYt&iu=X`i9BQFM1EMm)Dt!6ZbfSi>?_f0NZs>TO%{=%j>)eIQw-|^mW?- z-=pEFxe^jCtb99VM_(3U>!gYA;)NuF2e7-{LG(!+KP#A{*;Mf54Z^{Q5FC25G+-k8 zgCYEaNFwhMLQk^6-y(Ih3NX#Ei2nR!W$bUg&_ejvOP&G>;+9%l9S9D@^CEev2j80C zC(q^CcGFgN2^xqB`Y>LW@i-2tv#9uI^kp`gvN_l_^7o*s?NqDhrPb$O*zcD63f@ z<13`SIM2g9g2f=)t$N=&4*uY@|H5E#t}Nb?+?ue2n7i>`!PDZs)ySSI-a%}fCQst7E$@jQ49l9x6dgKZDm?{>sbfeo>_VX4me zV&J!G5-$a)(U?x4+-*p%OH_p{8@azHCub7t~7_EurRp1bkwA)sPno5K7)7Hoe9XyFk){zLBKO*OKlA z^I@Myg5LQ3^Uig}KU^|>J{;1<3WA&i?L?zlcn7O@T{5iK#e4!IaL1qRvi7q3Xb#T_ z=Vr-KKmo==Ywl$UnB;T~0xe|4KYi)mT#Jmq$v0CH+gX8)=PE?3L$m)3>1&U9{0pI+ z&m`D#crT}7NvB2?VcQXRdSyqoSFNEsEcwAD_ha9M>3Z=2G;4lPCGc`Som1v@JlcX1 zADy!i?;UJ7g~PoF6V^6ZU2W{O%+IjSH6$@8O9Ddgo z24H9!A;eMupjtLIAxBz^W)2J7gDzkGu5OvqI+fn3cy`GV-I1W?1p(AK1(ExS(xOBi zVYdwxohJ$u8pXHvNun3VBu7k53wx&{cNK_R}8 zW$_15$85YxDy1E>JL}U|PLys2iFnx8@Rgbmm@DL#?1{#t9$82Zn=6%rVqlUxSSX-g z!2$Q9QT(e!RN_Sf#Ub%~kVQvbP#I_XHr}Lp;THu9MbtD3)}5-mM8mW{+0ym|hH0~e z);A3;$*1E)uh}3^!Qgf~wE6K&^f}1&g1w%%;N23X>b!j_Oj!B_cVtQJd9;ll^`#+v zSmf4c`f|!!z*C(Z0@4xonecq*P6Z5FNxrxtR%0)%-qRfMQUDIWg|xwpWnuM~e`FUz z1oyle9Mr~QMn}=fnr+mY0tnpG2m%3G|JB*Jv{`HDuG{n$MYCpN30BwBK5ky^4 z9j@?HkXE&B*EdPau4x@JxhP!hx@kx0RDk~DQK`!=Pc-oqqx(%-rrBU->LWa3 zEnkGxtw+D4Iahe|))=`$sYdk}t%_3bmv%u~w%#q19P4YlZj9cfX5rs}|BIkGAvyfoOps9CmnS?=}K8oC3US%j2)*OK_+D${7QmM*q) z9!-p-NvcY6+)j?9b(;GzvR`yHj$gI&!LpN1(6^Db+R5F2uG~FEA05u_r_`FD zd&-qs6Z~p%!cx}kg~uAMpE^rE8j}cCqqI{|t6f@%3FYaS%%;q_ZFhT}}#|sh-tWCCo zM<4Ej^QY=M1`^MmMYS4dG%nj=VM*?0@0V=Wan4CH&XQo7cWX_Yrgrj(3-@E58`vbF)~jC_)7I}YYGZqkAp?sz?XKCW7kPp*dESy_}ZTXe{)2s9*9aO{z>M|><~_TQ^Vl_{&SRpp1mAu z>=2r@!&ZWrlOq5hXa5^pAt$G@k$De1s$1*KPaGRd*8Ki#GWto2-Yj3K$W3%$Bj{{n zuOeOp!X8)m)Y!o)@JaS)wn*^uLpN}OG`4?Fzz;SRQcM?%>_kH*@Vfe{F0C)bpH^>Z~Q4zU-`dFICRkdBN zLM!nO%ilyn54QG4%3V9M_r@h*;d(Di%L^+U0r>0iOI>#uyc(eRst;`R@g4pwp5GJF^TFG?e>GOA_tExiTgviHTw>f? zkSo+|_IJ~b>DVC*PWP|_ZXqo-1OPMLH7JnKKvxA-&8BToMgTbub3^PqLN1c`Sd%`9 z{M~za9Nr(N79wA+WKV-mZPYwsHK`rh1Ob9;y7p=nB@&9tj9lc{Rro#0BidW+%KkC31`kF_&ub!#{0*}Kq!uwrWtb6 zgupDbji4r?0N9DNM|g4as1!-eh@IcDCQ!287JESkh@7;6L%->EG=)@p;hG?z#3Y5_ ztDMWo%`ph~x7Ndp^N?goC&ZhDiB<}W4`??TzvFu&R?ex_DF<2#sGLC78tCI%?oBxI z1TjEnot}zYk6X4vBwh07Wvod8Z8kOo%`jFDuBmbhK)kzO_hF8N}_wcf<57 z4CV;xEizrkdkPLwrHy_YGLw`jgfn_JAmc4B4$c%d%j0}yis#{-6+cAXg3hVnXk?y+ z6@jh3A-Cpa+@sY%N~M=qL~lqd1#3|r2Qdk(G#;1y_QQthr(z)PwOL{;4!kaD9Bd4h zmHi>=U{JXfMb62Xb23Ka%#F1Zarmp>0VqmH$9m0cAs#IR zvYEYTY65VMRsDWn+O$^7$T)e>w%$5~o+alq)P)teotpp%$r#Oj<|aZ0MsR{q$KeQ> z6Q=IDB5yO(p2jC8aS%EnmW{0x50+9*7$tGmxW@bPN2o>(QIocdn^u2KVsC6q3*iiM zjV{iX`0Y`*KJs!m$Uw&siQI40E?9k$y#WYj6&pop6gIpkO_e17c(u?TDOegdL~t&G z9VtB;vH_d!Af~Oz6PuGyRFVU|T0o@9X@FiW*Nf(#bFn7Om#mqv<-<&w(hU*$Mv$Ra3pA1x zC9f!=-pXOavv`u#JQw$g*?*Dfjv=CA%S-W})`rt4h?wD5q(9^DC&v|6tR4`LZ01D! zPI(IoM6=Z*N(~qmqBvslV;jRL^f#lkc$&ir=<%KeV#Mc`mptU{Li;d!zd__BSz?p1 zMtclpnqx`FMhyG?xjk{;^xLc#lTl+xAHA!Ay+K#lS8w|WYT9V*aaN-te%%IapvFjkVJe zvf8e)Y8}i`Sl8eRRh85lIZzi{(gq{>iP>%Hk&5a9&nMeIQuDn{iixm#@{36D0{LOR zih|?;?m za>eAdPSN-Z;%@eOGwN0rrv`%xnv)_wr97!$Qt;gE^Iu*qFb6;AfL<+HZu4)GofsLB}~pZubggi5o=+p+{i3s#=ly zPs7KpCu*>J^7IO@lF!`4?kEE%bqiUvTeLDI{AFq)L(laE{GPN9_E5!uWXFibUZO$V z%7Dya!YYe>9mM7Q37web$4qcG`bBKScAoI~Dom*#!{i8SJBo|nWwQ3Vq*kC1R&iSx z=doLFOky@H>&E`_Yq8@svQmAkZ)0!Q*gHQ6|L%-KO^;Ylg%j1&5d4uIO_TcR+n|}|?J7nCoYe?(oP11Ol5*Fhg?4e#;mk$e zYnKSQ<#{(M(60pw7u8-+5g+K+(jH8~efzHLZ?6iwn~-&IrnxJLKthu<06$n;W2X0; zsx2PN!4yh%IdoBQ%Q)m}IC8VS+$;4LMGCjnF+Hc%NK+?l(*C|$lm~+zw+qzQcL^3m z`5iy$T2-g+YapRLbMpf!)bNA+Ev;$BO%R*3f^ZeF)+rgNl{0KM_mf>|qT8D1_g0mQ zPfzM)-irb4ed9a!4)t>3Vo>SQsdv-k%i9NdkyB99{{+&q{eN$A{}`Mzv~l;nSg|rg_)Csor##8 z^&blC{|bsTaW*$`bTTrqrMIwSaCT<^xEmR;8#9|28?gXPSeT8C*;x#YOxRcf2Fx6s zY>ceTCWb6V?3^5o94w}W2BrWG14BkOW_DH<4rUHE14BdOe~}#i71jUjRR2vy$HvU` z4^{cUtLWGmS^n>d%KxFF``79G?}!3{K$wXgz{tr$%mTb!?2LawRG>m0sBh-rU;)Yk znb`lRDS>G9zjEiyES$|<4C#UFn?cUr#8%V9-rmI8!j{1fIPm=YfbQSb?tekle^S3Y z+gX{|GKeS&u`@9;n7BKe*g9F***g9GimILSKeX?RfPZ16|0E>*f7L}YG0`&tCGH$R zj?4y}_uoUn$VAV{$j(X3%)9W&z<;4lz(1WcaB;S*aeG)WocN+QV{;-<#9JqJW&`$MlEK zY`(a{57$V^A@m1LJZ6s^p*4-#Zw#sy%d63#+uVE^_ee<%O); z9eQNJ9(q3P<5u^&&)vS9-}77E2SL0v=m*w=U7nktUvV;$WX`13Sw2CRqFC{QM9;Tu=A__!X zphX7G8USfVlqhy{Hz#ib7oW`y9C)T{Me~>3bn7iVR*$F;uL!9X^NKlP zD4e+Rmp67hUr(p1_Nm^ls!GTUD+qov7DX%iHE@L)g+)mh5iGyNah)*XHk1n(7;4ad- zIg_S1Wokx`?TBDlUmEH(4UX?%0^gy_$4P%!BE-|1r8GOy%sd{&92!kZ_a}&I)5sublPDgO5EcmaNv?d>Tg`i3UMzN zG(PKcc9v%u?C#HiEQIS1E<=>WP-D=R0B(%U za2RbGyT3Wma4Z!31?)NLD}CCmj09&7uX;j&SwUg$ankKQs4PiCkiOwYP~Xp7^1b?5 z(RiS{@g1+Mhd~6g#~Fy#s_}xW+4Bs`{W+AWnIdLj&yzi<91X7r@~O`X7f)HYy*aM% zchHjG;6M5%l|t2vZ%r==BVax`P|R3k&6~2sNv9zB2BI^1^=PCYKa9J@AfXYu?E6vIC`HzT*C=&Re^sDEUqt1xudTg6 zZ;ut%+Lr3mZ7-VoS`?yU6gAB*1(N0C!vGmwSTl#UFhTP*5OVa04c%9odMHcNnQC#i zZe~BOf#pgbjv0ONx8tl>-e6ZHG93x#5b>{v2kOQh9ZC~oCy>>r4Vp&XebbOwVjIvN z5d5W>rJ!FD9L995%WLIDH9~UWUkQ9cTcOXs z9X9(HN-0GYAnt=8b_vq_*>f;AJ&_ZBdAk5$6~Cy+PpnOg*KCYmc+4^!xe~CFHxxL^LZZ)pP#t`JG!ff zd$0ACPB172pKA(X9zm;VHf=p;rUR$0<;P`PsttU=TK(#%y8C6xaolHJYSSH_b@Z~j zUn?@nI|b=aU9FPWxJDRyPM_#|r)9iYLF+{aevV}T`<UdWX`kYo;O&nOnf&qg!8Fol>x)`A!2^ooj(N$(7>#hBBeMI5 zwaZi=NF8DtJM$R>+z8MZSf=nteyAIIl073?vM9FgLB*FhBWJd+E`h_c+T2s3WXKgp zsY?fCmGL#2fbCL|AOBKi!&Cz~KC{_MrOk%yC_OuSQ+hCTk~?0_dUCo8t!eOB?4rCZ z!f>O{oj1Gbx9MU7f9;2#$iDw*d6^IzF%Au2kI;N^ z2|K%iP(b8$UNRBy<(P%%b*OOcOuQ+WHmWEwNkAW8T$aW#nOpuQa{e&;b;uy|uE4g> z&8sDc2IhOgVclTL&$`O#`~J+Nd9^`Br8(q+GCEl)S(SvDiKet&vrx5-&pEbT%t zRSAK~#o~?DRm=C5m!1^DqawgR!}yX@!+4`!77qV(4d|C-(h*Y9bC%+G#9kl4w1*C8 zNydi|6{kT+qvY}+aK~*uy@u}vC*-`9lxhuv43R~!fq^zB{iExfnlcGyKO!Hd|88Po zCn*obaSW4z1e zHRY6yuR4sl-<}D^^%q5=#WGy#NU_}~q%*#-)+Bf&p5c9&;4&!C!?6WOF@;~1HmUYA z`qIk{4zrT2%(dO~kd^{%8>|brE}g+0fMUL8|I)D(NdLhT#|9(;y|7#;UoL!1W*h`z zC05;DfoA}l5FSvdd;;{S>-_D6vm4_TQ72`ov9&&B4#)DgH0>a&G_G!WW49N51f(P` zS6UZnpv&Cv7ZTV@T`Z^W1m_h6-;%7T#$|+hb`^Pv-M8THZvdK;8&3Ykp0IWyAdKhZyOSlfP|90S^66@ zFhoE=tqYRSuz=^S?6u0LuvHFPhmfO-4&79A3~}0?nN?5Id_{}~VQ0)iCT&jj*HMCx z!&k;ldvl>`M;$YQhInXd=)^)E@)_cFk#wK99nZQ=d5OSiE@w!xTq`j%Q(0_|c$?QE#C{rOSg_}1^c>lB z@ZJH3LGG`FLXy27)k!_uIgLqQKHx**$1F3H*$Ud2TAyk6%Xh#DF$tP{eGw>AQl#dO zW-=@}+tD(UL-;%OzeMz3No+KHPHyUoW>VOc+^D;XLh$`2+j1iPJDNEq@ZNknx~Jk3;SD`d?fOcW=Yea_GHNWS~!%6xHy zT%29)Ml~wA>7K%TzUmVT6IY!U=}q&?-VcIj3@%fkTe&?#hk)8RS-;!5xmLcx)Ux(& zM~iwMKh}{#x8-!C7v2Vc%$}@u4!&4PC{xR5!-j`xu`l_t2Wsk>=wa))i>lNih1?nx z9vH7DilxRRv^bSg@Co%Umj6Cfrlf*YE3z#ZFO~d;Yfor<_cHyiZ1Oo7zAAqidK;PO zcBDok-`C`GuCKbu-L)%wF)Fo@==SAVG@)$Ks6T~IrTV$QrlD-LreSv!r5<)wsngFk zYJC;bkog5rAG7;b$!5MRzF9T&JBFZhvDWhgT_)TzH)l(orgEt5NE5l37oXDcq4KQ{ z@#(ITp`2y<8Oi7~z?juT8^6^^@A?z7mfKzQh*(J_=nKqhBmoFK(-hKn(dQlgRP|?7 zSRzRjd%z8>ID`DMD+n12jN9C<0!_i1kh=P@$cUfq}9= z636_t%TiWAPwe}qf!XX5Qk103#KVsE6c(7xrtP8B$K7Yvw$E|&%QToHzYgN)`;Clt z#sHv)K@5Tto{DY)Vs?I*8}os-^&Ov(Z&0!i4bGI9f-7TZ_#=z5^=6I3NB8qU_yi@u z`a+TZW|O8au7p;)`?O@FZ$9#+pnnv?8&D6r)pmtlT!eYpH8u*x;=`|w{S)Tr!2rB4cp1E#WuIGUZ!3!JD@$}0s=FyTU@Wz5K+)c8;F8>-Mg#EV%qx;(!U>bTu zhzb@MHl46tqtqc2r(@D`Te&1`X-i<<53NwuKuhd-I|lw&@-Pr+bWjhPL+@DA*wzfUzRhhLXNoJFy6_qxtN7g zh_@kS9u^18!|)!^bWc|Zu*)Q73j#~1{10UM$yFdmaGcmQ`wdpXHBv*I*SKLvMr=tU zsArg_ew;SHK7<)wy@>P>rUN=nKXF9$5GGfq|8+Q{vsFfSMl& zHrUYSg@2XNX%m09OJEuOv+$hGQDr*roH$&mjLPoxy54pt{W_lp%=nbao6PesQ^hLn zl5eZM(3n1NcOiR>W;SJ93S_3uZCdT#?|%!c>>(-wSHGi{5aY4KbFLBi3jeucq2OnGY4FamM=ImBB`^)Xxh+2Qf5(wRp zgSJ~f-F%9|4l!HFPwg@B6gG}+qZr}2Sqg3T#96Y^>ktS1#Vc1p16udlC?#n3IoOIL zn9{VUKX`ggEW(14y&AtdI20PXX(a09e)4)RShj(QWSW#SXr{?02`yl8R^`HfCGIw@ zb>{&M(?&P#udiOCD3l1yv# zBVj6bls*EbU0Rl{PriQf$aB%g_nK)GqW#n~ zxQU1JIdW}#W>)|Ow6pzTC=+G>t8*jCcy){-xV^@G$^f6buobNH8;KD9j0)^tbVS{? zLunNnRpM$J%7yYSVSKW4Oa7?0g14sYV=r_i$TZxUt%&-({Jny>o3FcGk8BjRk-4rL zZVc`_S?f`HHyUuK#TI7EB`n(I7Il*=%h_8A?n$#g zxk;I`bgn5O;Z7xU*G0#w`f0I#P3OxLVp)U^Zu~1|Kxhhw6i*m+yP~TD+9Hs|uU9X% zfz#68ByPO76@Y$qw1<&t)j6My2!CntwUo2})0sJYo#1TDC$+RVvWdbLlhBl9v~lZH zOqfpv9@tC=xkaM_z1`O7;+1`TY>y3TNynnVg#hWb#7_~@I=a=lYACoTTwnD#UV2a+sNub{+ir~uzA=Xxx8JCwX+b1&HlJJ+ZHw)Ut_!i~ z%SdrP@MWIoR^v`+_F=2()iyOs9gt|p4nXnFGxqnQ*TRoU5_J?nM4}HCPU*a!miMzZgXWnO6>U=xx zxfMu&qQj3S9rU&fkGe{t<@_WdUZAwZtYo)zLV|76(Ff#6Me-$k>^**GMP>c#e72kb z(g~*XoIF{-3LZSMFk|`*a<2|f=Q{4FJPN!5=0W&7D!i*#<`E9BS&4UEefX%yKG(?i zT2`uB4KrSz5+WKd(%Zd6GKnIKjvKq32=JWqYQnO)m(_C|wv_ox#;sCf=+_xIlWjLX zG-pe_4$()>qYAJwe*X%ec3%!*`#$WBmCf-d7`AgT`axchg(wA#07n#5Glq4pSn?KD zSo#bkIj;(uHLnj&$ik-hCs&@}Il@aqFgY{MibFDn6LhJICR+Qhjx+0V&B zi6ZK|QID*)c7tQtBEfaatVq{WpI^#lYQ7A$OoHIslf|QC4fp7dFbyG5N}5J+uw}Vv zp8%1+P{UG%+`3+JcmYNjCHB90NBRzYOF@{p< zD@|ek+N%AbDLN^{6*&sh%^s(u`4ys%#avJ<5_2p{MEDrYMK!pGYk#lPd@agwpgfiqK8gA@8WgDY@7StrYlwyy(b z1EYQL(AUJL#ny?4FEqd7<5y^y)}LaHUfh`*_M^FK!~pyf(3(Y$2jClTrq| zOr~#L!`J)P4Dkzk=8*<=?g8*$a*TR&y^6~xPTA>mlS=g zciIVPIXoD4`@`?i_9}Y&6M8PA1~usFajtxnqF7`m=RUH8&{Le9$E_K+^q5J{)xEW0 zj{iy|SF=FNj(f>q)Hzx*Rs0DrwqAHMs-&XWYI+!A zjy;w9gED32fL9H+h35iZrQbcYT00N6e) zZ13j8bF&gE?ig36G7gT)Hr|Y@uzkH4JxGYs>_=vt+!FZ>8-EH{M?@L=tQnfcOW%Jb zjU#-7ikQnfYN-@rq)UbuqEZ=Q(cnT*gACru5gdIZp+fsjpK8I$a{k<~zjJnUEn^*o z#{n&k%%RetDzSCbU19v?*M)*C2NiM^=$Fpyh1Kb<3S9RfVEp#zmfL;VW+`apt0AyO zWJBqq0Fh9v#_58~87FOmMNHxG)}(7AAdFviHq9${7Zi!5Xmie*HZEB ze*F>5EbOuIKSRg=?>m$O{|kq5;7{o?@TWsL>vxCp{~1*LUr^vOF#zb8m;p>6R2&Fk zqGSE(5)G2A0vG^HAZ(R|9rWLStC#OD*y=xp3|ar6%l#hNKZ%etfe2XaYz*Ixok6{jPy7EiqRPhjd${>~!u`qcFn%|?2C#r^^FjW%bRfP2ke!JL zL`>WhGH_k(!z$q++1_}DEy(&zQ~t>8xmnuZf{Ob9dI5bemL@8U+kTwQLqTT zey!>?b}mxHWpo^g{0=KUCy+qJ9p?ln^#-IgzILBjko=}J=4hF$PkT6<-sAOzDRLEu zb}Vlf!b}gZoa9J(+%L;pRX@uf@wh+6T=?n8i~HS?*I<+y@8*C!AEg@Cq}A2#<{I*A zg1{RN5{Man{r3;8_ns_)L|(xXVtKAJK*@2^s1ZV*6!%MH(9HlnuLrzta%H#24l;e7 z$Gr-rNm}vajhG8|h8I9j(H)Jev4yCvx_AY zP4(yRt{cXWoSr|Lrac_qtzSxjvocfwx=gvn?vh&X)^Cq_lcnO5QEF<(G7^J9PP~4( zX=z`-lAI$nWmmtWHyO6X`7nLVAwI)|5fjLqc<`6UluuHGqkgyqewLZ&lk%R!_{?B(GZ#fP?d7`>;CC$-L{AZ+>7EQ{?V95jpZ#iCjXeur<8Lh_^ng7`pKV8?RUIPvQulDFB{L3!2#$ze_^7v`6MOT%gP1*R{ghrDedW!FqJO?qYf6|$dMIueQPzZ%L>z<#!SUdV59&{qI^<2 zFVQsYTp3$YA`%cIO!j3WAKKM{GE-#T9dz|JnE&3qLDq{Btl1L>bVwEt1&M4j0wclH zmAPffuO-*s-0|k|5=3>T z_ufifkOZH;k*rCi%f-tDksoDDd=v51>&W9gz6wd&u1K;Wm?Hw|};mWPZP zDCjrp%%BZ4B5G2VWV6LUzfrrIV~ljlC)MKw{;hC0|>oDAZZ6-KIY#a!qW zc^IU8Z$PN8F$cpv`guFgw8dSLyQ#b}Lv0dE)$|mgPRSE~a5Z5ybu6)CR*=#Pd)rEP zc3A(oKhz^ADi5xXj|r2k7feJhkt)2vR@}>f1Xh~}$wN9;HZ+&J4e@5Ku1f-!@ML&H zFKn5E%wwWw+c7(&)AhCR4)!D;nd6vY&jkV5-#+DbmMKD9Amnsh`6VN124k9CaO_fZ zs0Rl1xYEjO)x6h-@t{)oaMp)R6s#D+SH&kMVm|=B%-fhTa^4V+!WNGPkdcwj0iTR4 z?7D4_Hy;sdOQV+$-ygnXuP{=VLs|)DFUJz0V#k&&I{lDewsgCIf+o2a?H}AxdL)C5 zoQPBTp2ZhwT7V~oCYzf$55v2wvjgla4Lo&AGTBN;B8gIuH+O-E=}|20m-3h6DK%|A zei*p1+zU!^z{np9^@?*1-!S!DEOUJnl1i#?ChZmQQ@EwzWyKPVEpFXz@t~pd#O($7 zD~ggF01+6XV$0HqZ*<92`FZqO2Pbm<5#tG+FQvYT$Z~FLlZ01$18w;e3w34B=^BMM zF!r?Bu_0M=;?$we;Pq;i+iy2a8b9Mh(?=6tBoNz=v^A*8!G}aInwUEG# zeeG9#8D&!HsOU@=77*STDyE=W&d{sa;Pk0e@XMkC??>kS;P{pf=fMs+Bxs!`zv=1> zec869*|r9?wN-6(c9a#eW-9#3NGSF2ai|=*$?@E>+Ulu@xbuvCeW{SyiTV02Os-k+ z>_&R;x6&1=pPQfO%#tWe>YS_3_Sn5Pm{Yx4(smUi%0SkUfMr_?u{SD*wOhW_YA02Jus3E*hbrZz>IqV|=^HBh4PE@MHmtlw2hkM?Ks&unb+f7H! znj;LC8dbdXLJ1E4Z3qHLRy>lI(hGx%)5<@*2AW&#Sq#5f4GiE25z4ZixVSX>hYxvE z35SS)g%dc53KCy4@NcZP3nKVBh>38f*1}US#c0!8YrKV&L(EtYNtU=MNURur zA-a!_YpzZbkb7UZ4iX)QA|O7gIcZ@(IzSEeD8gLobu8+)S}CvPB8wUaxtxFL z)AvF=ocp|gF*3`H6!E3=Jcf2f+ZGrO(&Uib_5&_yBKs7hmNN2OAM5u@9U@z4@3 z!VFk;y&jk18NEIdVxgGb+kO=;Kh^=nX(I_z#@Ns;g7WaAPfv=Jmip1JOet1DrE2R* z#OFZ*COt5}K&>(o{}3*(I9w<2W!An|4rud^QMgVzFE7ECduTcKU#P^M;PSLrps&bMOH<7!zkvhG=phYlmyx%fr+e`<7N4MYEZ<;`~JFg z8$7p|OPtvz;iPe8r!dwiExzQ=}CUMoZlxoLp+47QJFlxNmE{QOfwZ&ciuy2H~mF95 zT{>0EW7ykK0b#RI{Ln_$$M14+`~EE*f6bvQ4_*Q8N>DFk?R4}Dz8%0!GkU$-LMaNZ zsa*~2%>KZ`N3QX$sA=aIow?yM)uQWytsy(kvm0pQp&RomGv3~l*J4T1Vr2K(1- z&+enYNH*rHiNJFoEW_#T9Fm9jcF7z;G=!+y&Inb#+)LpRDBeI7cFSGX2N|(o-YBGC4P{esxz%o7K+I}r3$nn5!y~gh$B5O+KL)aTctxLmc ziN~Z8AuBt{Jrhq+!k0mI!#!d`wyf@>!Ffy?7jwlXfX5w6?fZIMjJ51d>BF@AX%L$r zWMpCbpO%=IkST&3v-#$?5?5Lq$bghR31ZsKOi)!qe z0s_{WC_HBczben{Zl%-?#(y4((SE&gx*(Nk?^H{0MJstDm}wh+84}DO@WICC;<$e5 z4gQBnEE%oqja$)ecEYqC9kEeKib~247&_h z7w62Ma_Z1d*D!gNNKO>?9M_d6-6I?d>iXDa=}bVFA*3)x7SI+to1WYLZn7rkbA zp;e|)pjJNO8i&CvTpng27RnOIuW5&9)5SrL6mj|X*5~GN`Kgbw5(<==&U5i+jsfCp ztCwig(t95kIqKxPMmw<8m_)|lTxQZoqiTTHkfuS$nXq?mp_fEZQq*_PGcG)N5k9`N z9jvkg^&Ye`cIYW_R=eg6BZT8F1`ee&SX0nGTJR z2a`nQ>sxzcvWF9-A&~*FH%Hq+T;MMW_cJz5r0~Wd>>jx99&YD9wiRBx9Dzy+M(LPvEEPpGm>a#nzB8}AR^%qDZ zn!cJZzhpZWQLo`&q{>){qbg_9(_n~ZJzdS%7j;(10BPx1Vek>4c+b|!Ka<3~aL*uS z<_cySH_-NG1a?HAlZ-@e6WPLuj?V(cOWH_c82J*2sCQ=vs+<@#7%*Kyr+CsA|xUo zDZ7n<2o)KxPE2L_^jh`607_^tBvrfE6oa8>YcP{Q2!VMPNJA$^ZI5rr2&bU>aa^nU z2SQL`vK&ml;RQ%SsF~>2dvT4$h-6Aw*#9cA%lmTorq7gA>;U{NPN`owctsAWYqtsH zOOS@nd0YzYRa(J@QWKJ6MZm|PA}uwf1%q_RfV>YvB%$OieE z8i0IFkJTrDA^t_VJjA&Gt4*EZC91g}xIk@MMOC5u;sWk6-AMwIvJnw3`4e4E9=HPE z=i+kWGF_4u3vM|ANfz z*ItRB_J2S9U_o+47DmwRJ;+ZN^no7<_SXo~FLFSUpJuu;*82AP=C+dBw)(Pm7S?uV zfAiA)LvH;defuxPfxpQ;S(v{8Sl?ZU|1S4rVFXEBzYqQ!g7!DLC-4u``452WKQ1Wj zzeydL0igD)KP+<@*#UH{Kp+T$B4YXmPW^=~bAOf-0Q(;#vES?bpDen+#E1ce&w=&| zkOws*sHrGBD?0-dBPd3|pQHbV@BDwjR`?&r=-VFnCu8*YVgkak|7N|+$iPm=1OmMo zSV63IP!H+9ejc$g{eG!^KOX!yLIm20exwlq$O^*70qh`gJrhVi{$unnokss5M86=$ zf4;afGJp!x&ua8rM_Q14|KC@P{#IQ7P&n9rIlKN702~NlWdEH^T3tB|uQ$RyO>=w{ zTw&z)$p^6PYSK0h6QLw;+UM@^Mo6?YiST{5|) zdvv)x=cJNV88Np4`C&V#Dl-DgcB7ojF_OOSeBnuJYsGJWK^ z!M$?9eIEDTH40Lc_Ue2jryLSL3o*Nfhb(I2Xfs7bSOm)&p{8=o$Sxg;rb_9z^&Qdi&KGuvE*oNG8A6d!M0mo7wSIRAIm}lWZ zaRNy0L{;;ryTO&@7~HvE);xajN3<~T3G_&!9ROMJG749QX~^puXb0MiaYkWn+dn#Q z)bts)^Uk|}+;5>jdV>X>BF*723a`?LSaWkzY zH8@@KEmCc%oV&WkoilB%W|>_?aM8V|r7;~{ybrv2+rAxZxkp2Hp<2FOdm&e0lJTBu z-`v~OR9z+OASnR$Aj0k7sHWTFX_(d~+HUJy$_|OaCx|*2iUD-&69?pjf(@2qS?TVt z^y}uDUym}Pt-_#u#In?r1a;Z%*x+S+{hWl%)-il?8~OniboMa>LD z<9#wJaZ)~kX8*JS|9Nn>2SvIt6{JP~E<*fSSv9rxZsyKJ=ErC(LTa{`xVsuidTm5= zI^xW)I3+`r;BV!}$J1VMT1}m`^(rATt-#Q^;BkQhDODqP!C3gd&KEnxo-^y2#a`>` zoQ62`Xys!k>+1d4a>0R%rv7L|eNp9}#YY7>9v~$Fb+@2mu)^aqmJSZFuWW*tSELN6 zH(Rl9E)_cUT!g@mN=x;<3?{RpP+9y%PO{VL=aNLMtQRkA>y9O}^vnyztMH=fyJTU6 z30ZOv4TsxX9a6;_ZFP`s`DD9@7mk7zrC@kg+Szo#{9uJTVA`B2Wcim!NBY%dUrMqG z9ge95a9Vejm<7Bm_Zb`{Xcit*7?)moaye-T?fwLbxN?R9Zr?LpjESuwN-Hk}=ja4` zK->GaPUxMF(9U&JKT)5w^Ke`(j5TDGYx4*GcwgP4dnQ`&ICwI8g-u3(azP`M_1^et zgNeQ|=6iFEq=OK5ltd>lPhJoI@Dl0qDbC;z;|-3sqM|)*rqNekKv5!U_QQwcBYGNG zEb_G`&2U7EG`Oe6D}*p4%7Q_N1S37Y`i8YY_Qv@eHb~eRNcd(Hw)hWvLXFR)^UHbA z;%44;G_r?tBMlPoMST(p6-gvaYFB3iFeQ)$i9&u#93S8GeF{%%W#moX6sB>(#%7ng zx|oSJKU{9CB3P*-LysN%0bt4`nA>2J=8tvWpd)Icj_65D=;Q+}9#~#%Z8(i5_N7e> z!pCOia}tY;v-7JDrM-x0YO!jzk1Mn)+sPdV4=`Mfk6sds2lpF8lsF==G*+)>D{5)2 z;7h3aeRly3AZP2Z&}^WOygu@1>nI65BAqizT6)AD*m~%#(=Q%ZwoM(KZFrPDwOf9S z7;7%ST_yiow((FKVLx(jawVL?J9;muQ(+n$zdL`Ae3!8Nh{^PY@{&FzjKn)*gJ*Q6 zSLh=t?v$w;o&ru)(fp0%KM2cSFbo~{=UpoSKd8t$W`6V)5nd>~6#1QNx9VF$#VG%r zAX2!pwY%Eq#7RY27Pz|WPWbM=0+iSruB5dP9tQqt!;v8!7;Y_{VHJK6QJsV*2PZH* z^~SKmJpAa8nE`QKd%hX9APBrmp#yqcSDL#EdkfLh{t6-u@4?fL1bx6L2@SJyMFCM9oJaCQP;Xgc_&fd=RQ);OUMRXEgF>&5e z8*IoUY2px;t&3((y90SNV2Y2uC8Cg=QrZdv?a89^nL(-014;!JP%3m1_eJ%HgbL#j z?zw{Iyt`{D;CCNU$IK`1I0nNDg>99boVz6k`RkD<}KKJoOe%6vo3NZd((WC zOZN&$F1=%p!nH?@Q=Sf68Ks4+jlRCHog?LPmw!Q6%C z3PkhAw5*DPW=|RDw4K=Y_kJ-0%rnH1ZSA7nxEil%)BY&oO7D^lQPbc@xr@8&jx*Y3 zR2`Y_N#{&!1*0hBD>JsT>1%&uNXC2uNbL;193Lcr$s0L!S&TuMmnysYsy))Rq5M&U zXehx~FG^$8dQ7Zg+O7vvJ@qW~-1^*dLZ^GDaqs?CLCmyh;p^oR%lpuId+rQ0pPg5# ztu<>B_#>@Yc@^T2vLX=2K3px<5hfnfhG+X&{Me*MTd7?!fjIg703eQHa@pH(*pnC} zJKwY*&X{;?UPGfOj^~5^#(G7vGwyEQYq+R1?}j5!YaeeuHI}WWDx=ScSu>-E)VheG z4YW>GxO=!}9-wVtG zKc&9N(h7!-8ccKcd(#;6?l$lI-QK!DbJa~SU1%wf4KnLA1lF;cN*0qEcBkLF>o33- zwL*u0*)ZpO<+J@!0)jUsk*rEO*Raltk!UkwHD)}2z+m1{^-Y-=gTj&5S}H~6OE?HjC%#eITNADu(EY^_e)8Zw)0|p)k`a^Jg zkjV>%w6W#ni9HC~G}=I$hR6=P+qP5N6aia08ky!gpVqUA>6l6;J14#Fi7?>K!dLN0 z@$6FcUFm&))ZC9VmdpE{M*(u8ij_58%L1m*4+xDmQIey@_2t1kC6&!{-X_$o?i_$J z?B&j;3G<%x=ixPx7bc&Nv~;C%mq(SC-DY4P0CL<#js7Uwl#oVoY|V{&fu4H)UH^&sj(i9xn2?~xvXL$O38TJ|lsXsJ7U2uucpK=V4h)Fx)ah~5?n{slu zSR{yAMksk}(9iCCYOQ)=jj&ktP~5{CW$=0mb~qO8Yca?Y_Sk+n^`bJnvl`Xb*aAT> zTzYSeGo>Z(!#s0*p%;PYC!xmlDD?7vlx3Or@_a{dVNo4SW-pNsp=O8@a{{01>UQa< zR$rNileabFeP~-pEumR?d((2 z4$16+=E$u0MWIlD;nm0LQoL}hXk3sinA2ND zdx|MFVt2MpZ|X)r4YM6Kkbfc+Sr<7z1c|Y_pmApHA9n0#XQ9UD{6fE+R|Ty;ywveu1MVO?W~ZTT0{;4OG`U1aPGCT&w(?#mn878tr(KP4Wc0 z>cE^~mn)7np{5{7;~euvU_h$?X&O`dToWq`+~BJr+M{Lik6n;ydhf_Q0g!J|(sq^M zxvC~fyr-g`IesP)7M9_*_L}PmB7(A%~#nD;`SY+m1Uix$CjqDxl%=ar&+p;O823Qyp z#&&@ds{3Xkbe3`5H=1jyTMamw<5{c|hAcPG4QV}0mU2!oW<$bG0gJH8Oqhq<;J; zgz9262=e4>Jg`pCM9?(OI8E%M>(rx9^jzo(8(#-wMxIku+>(-`16aF{0$22rY{j|z zc{zHDd(sbR9!ENFTw)GMzx~@AXm1ssAMODsah-NT9$nc=*Br@4{Af)h@Bo0>?b4&D z_B+bYQ)@3ZMZ=&XvdVx!Bgl$fMnp>4IjtcpJ}}5{r}jOGY#l9v9>wZ-Emx(?4K#nn z{v1B7zTeSSJ$do4qHIo2brHXp(M*>1f<>vUfUnk%45^}12k`2++#0iPJUl^7HYoiJ z<2>jy8m(oDh#IX`7MA=A*?E#z1?=4Xt9*G<)?TlZw!pD8RL@?H^RHG((Dm5FfB9Px z(QK5ZD-`A^4ucKQ)Xm~DT5!42+chcbl5<>C2wug=Xl2cxC*@;;!WB@_ob^(l9WldE zwW7W@>I%BUQC4d`d9f)u^VVe@SdlCvVj3rVH2v1>t{h3VW?;wRE1eSTzF|sCmDL!k z<~_12^9&kT2Tqmex`_B#TT zaAJ#mmy|=zt<{Gd>de3N3K$v$(mj7_=X@j2OV0W%F|7CaRlqFr z(%h1YIzwoq1Kj#zlWxtP5F_i#W%$a&tKKkP2d7~`VlZ3JTGTbsi;&*IUem9(K}PO% zeZdGW=DW8mt;<1}BI;bLNtm_GS8eE@&7CQ6HVCaNlSHO8%0$mGgYr~Y{0LGa=Tzpf z-7ynsqH7k!?vyqBo*`PKvd&h0S%0%)pmI%Cb|y6>#oA&>=YqLp2a93qM0w&=&&kqc z6u)s8qiMqFd`XsEK5(YEcXRkyO>bm+e+EM7eO*@hBlzb%-_t z`rF9tJ`&Olo^C`|A^+xlWNb#-cRv%?|Ctq;?GnXq%N0RQ8**=*Kkay;Mfot|IgH1> z_ls7kEUwiW=?H<%C-TW!zAtUJko(f|Ea{|Bpo%`wwdRw=PNT5Bc*AGZm05%No__!u z@vOXhc=J-c9FEu9m1g#zw4YF4$76!u^A5chjbBZ(WDWE`&gvmlcXJIE_e~!`P*n>XsyIM zyYD#XCTs``NH4cJ*)eQIg7=?oZ)e>^#)zSbY|4}i#~Y}W_s`H`@^!~B?h)Re1!Qf$ex z$%fvfky{nCq~S|!WAk2Gwg7_-S6Sw+Z=AK(xZN_j2t)kl!wUBDM&rVmRA_8ajVM_~ zV{XwxG+q&+BB*1pxP+pajx;TV#cOeCWBEuaGviV!abNwQ7ri%wI4C~q;-0=duJVcT zY9b#?sRS$3cB!JO3UhrF$oZ@66mh6#X|lJT^fTL)G){CKGz`elsw zZi&&Zun!ov0_iBP}o~uBaZLgPEDz$1OrDH0qoJ9d6JT$!yiAP!G5WlvfX~y|D{UC z%7913NIr5;;u+@lhw!{?QWtcxUinBDEx`~Z9YgUdDp_3?IfhRy?=loHuFGQz_l$GI zLrXAbMMF-Plv2=2h~zT3`-}SvM5W*xugXgeitGej4q8NF_c1(5l-TANGRmfcF<8(x z9MR@oE2ag=X)2OvZ4KC=>Fwc_QyqY6YRs1v@GTg^^Q5L&PkYUq>I|wi(n(oP6>$qL z;HP>G+Qx7~c(8UTR6dn{*v{bOxUmAS$?SgJHj37LU~JrT;$_^=*1aNvg~hVN+$vOZlB ztLZXj5#h&;EEM|Lw--fEb?Hq&Zd(bt>eftU%4=`ht~|5b=R0qvXG@y<54@!t+64hG z_8H#w)lNo*2PUn5bA_h*V$q@ugfGp#ETJ61&wW4WX)501yg<~$OFk(^C=h)Wfa+!? zP@FlVPNgFmm94T7=fs;BhB``cq<-Mn(uBai=^1neD3?fw5(8A}v9JXYPbTq^`G8!Z zKUE|Y@6D{C;@*_?n(KGgB)E;pS(DID3?K;4zR&v3aDnHv@0D7vjH#Wd^WnaD2Cu+* zyj_CAj>S7a)VQt$BcY4FUh=ZZ?;dc5OI2W+`fzo>+VTh{ZnL+a7`CbUqIZ_4ohZ1Lb#6(f={&_5papsuOkKhOTtWEvz#{PFY8=Yblm{`mRl^VokrkNxNK*nd2ak>SVl z7#aTO$TQ!k_`9h7W2_t0I+%`?i3wz2Oauhsm5jh2*gY!?9f(lF$oP#G!bk^#y+M72 z{}&^0zmRACMsxVVYGD5(Hu*1bLB1jWAg5{uX2xGb1ELhsF@rpxnOXkQq4@)3`!A3^ zehmu{1oAWdAQJr=7LXV8_tC#z#{3~H{{m^`*M;=kk|ARJWg#(v_*H+Qh4ddRvVnil zbAPXtf40p0vX=fH9VQUv3e}A#eT#lE|;i3DnIU#0vpI{6xQt4BOAq zzs7RpaMOrW+EAO;@r`{=*xJ7)*z832L0%-ZaF26~{QC5wRp zJ0p{>j=m0)Ht3yzg~b2>s{Q)fzj)C6D5!#l`no2T7Dnc_Hb0KGOpHKUNf5E{58w8` zaKHup8lG<+G%O%;;_t!(V&DB3{eLDr|H46+3CISbeS==u0HF3Jzhw{ew@xRZUNFoc z9`Ii{dq9Rtw347R>mRb`UpVmoEWR0}b^16~~`Ev-~bR-<+;~)Sh3%!}4?VuUC8i z)A0Pb`T3LKVPyW+D~y#1qzVIoUb5MK?p&Z78de4tcF^4w0Q9c#V?X;hgy+Xr%n11X z_x(5Sz9rSeq+1NnZvR@{|#0V;;pt}^%W!wKB6JlikUHJp?tN(ts_$NGO7G`GP zuRP{uyv0yG)-TPinQ0{5SMCv+5oj3Ctl*R@VbQt-9Y$$TKMR2qT)7nv=r_9FB(J2d z^b^gEAI#aA&UV|KZsUENJvpuSdaPun+KJ3uP2)LusFI_6WC3OR4PXj=b1O0ld*S@vcs?1dKRc_Kw`=|#4W)lgWQOT(qus^##4FQ#_O*Bp#ju2YiGJ5`*LT%R<{bb~{Q${{rj`MRE) zze@yfx8!*jHAv8>IFq;0@v!W_Jlb;iaM^m*-Pjy5aJ<^QdVdXHvb^5DOTUJd%NdY% z=Lh_>mr=|+@p>_AWxqtEhll%4|MBQ8h!+O-mb?pZSp$PAsVzpY$2U{l9(C)?%DlrU z3fGM}iIlftSR}9M`XylvVYdn6+-LojRl#-4mai9ClfdWObs^O1BtD<)rQii+M)C~t zhZh}qU9X3cJ?3!BUOY&sV}_~RUY@v2sN|JWYMlV{H*^6=97dL~BMIKnX^io&thI8$ zk>00NKh>Z>CtcFBER4tyW_N+BF7(8LHTPH$a}=ct1+|{=?9IGD)AiNC7n)#A&kINc z^RFm*J5nE>$6qYJfFiSo-X@KQwAAhscM3@mjI1XhTolQ3_y9|Q+9~rzDC?1OSP%ZL z8qVy^i#=|^H}e#pN3@K-k7H%)mic5_161v5?@pq6R4@^O-*OYOwba&ftoN(KB0V#{ zJe;*?@vtedU+F0G*GwnfEp%^(J#Q4~K3?_2HO}DE31y(=5Xh<=5B=<(q(O`nd;sRkrP$P8NqY`@a4vK}^^K7YID`X#(mWMJAF+=& zHj}D;xfm3p_i5C7B^lJgvC?F81*IHciK67SWpUCTZJ9_OqnJoSqZpvzZMIbM(1bx5 zpBf}SHbp*zBwSo9dpqYP+GhAvLz6}2Fx)WqnBW3f4NU*EiE`f7I&j}MKyf-tu`-dP zl!S{3Z=rr@6e$Z?g{3CLT1#={rPl(v63}b%R6a^<-<-9rlL6SF7B2u49(I3;SBF>U z=3-wsI!46ZCOL=H#NflgYzQgm2dNZr*M@Z5Ctb$i{Z)%06Me|$R)qYi&=u(iE~K#W z8<*7gW4&%yOWE{Yt}JnqE6XArGBPV@2PRMVp|bFwA#OGto$VsTm@X$?QzCXF#Y z&0!);0v=3pP#ei-S8By!oeyZLl&}eyw|yK|7z#`=I0Mi^Y1fx0canT)@bbt z(cakh+ILlh-EaEXjjpcMF^<2*xY|0F3u_GCzBw9tqhvQu6%~1r)}pxXsxa?$$v&x#9p4_J{v=2optH+%NXi9{?xqD6D(+%TH!ierOu9>C z_9Tz{DOj8f1~}Ku19%D~aAND3pVk(a7w#muV%$ifYg#=ofI|gQ;xydt>@nm%Ag5G) zF-|Tw{ zqPCq?q-GO5WYiNpR(w%fRJpP!E=UOYNc;l+0pjIV<8Uk7QEjZQbBW0ol@oBi3^(8p z*DRNm>br?K8)FP>l36JZXdM z4&lTXh-MmViNK?EifOFC947-~Shy!@DV>h(W(Y=~e#26X=qhxn#QI^sZL&)OMvyC1 zx!sx3k=>WyKa;wgB*`;{5nHK^lVs=lQhn_1d*7LDSJkRGL+7^^(ft*kHcr)+^h)8* zwR<9ltS3_#$Jg+SV#MUWxHHcBVf}&w(GAV3O>T7zc_y58)*?sBbh<{7YZ=kdVR^*Z zS&%9#DO%4h}+)(m@NP7ZYuq+wN@QL~eiChX(NSw+7xB6@n>ix`@ zb6P93qN)9~Aq)!rc)*Hw(74Pe^{=mMRvY=gP~JA@9@Y^QE>Eslpx(BrA!*Fn4~E_? zg}R54AQIh~Es@N!AD~OMm~YicT_Dw3BPYuHw=t);_R|1Y5RaG%;>#3-BpA#E%RAQ= zKXYEx5C_*NLt7IC*>Lz5$uoSUXNn46yczPjgaJpBq|qbiSszY-ZP#ogcJrJc9XI^& z4BQ+d-`>DbVXcKOT`Wc?1TH=i!Ex+OH&2c4rWi>z7B++dsb5A44;Z(YJ0xD^hj2#| zKF=?<&7~($Ja7kH>urcMj_j}3My~kC^{VLh7Ol~}vM(Ve{FA!{TfQ0>1VkTZ+aIsA zTn{H{uGIF7OTaJ{v`a0NEXry!eKIgT_G^z_XE!`NZbz2vA zDDLhK2^J_6r?|VjyBBD2cPQ>I#l27*S_(yqyL-`MMQoNYuvr>A03d7 z5|Wwsll@hwFWdTyEl|u3g7iU70`o%qw9gBV6j$R*?(s*voxrikRm|VJb-3;@4sLasB zM=jPV72`rXD2|p5EI6;yncb-~bGmt{b+opjkESTtQG4RgB=-|@5-*F%o z*iW&!7$hnf=3uZeyZEDh54}lLL%RZeKF|OtqFC>9WY9C~`DI8ZYHk z_f~IvGYuWj2Qs(NNY5UdW8jL0a@V~=-W7Yoj(mkgsCr$las3Wzj?ZJQr~S-ZB#mR& zO=Rt^YctbE3(wTi2lW2h%?Sa~piSrDv464O#mS!qND2HZFr zT+Eq8VnU&!VxA%g`x^#JTi~+@cMIhhMl!F|?8fxM3%sklK|e#;v0O9nJi()*JMczS z_Id&<8=OnL4t;R8Is+we1sXXXe%s4K)xdHzFI+D=-b&Dxl?%)wdaD(g1V~b=&U|Ly zYeA`_;4EQ#qeQy@<)Zw^lUUShLS~nfyC6uBcv~CI`H&GA;Z^uDZ;>u#x$!FDR(o?| zU0}fQN`*saBqzq9aBoF2A}7PFbO|B3bT>KC9($uNF1B@I5}uH9ngHT8>>1T8{>qn1 zXcexrmyk~~@&sx9GP&^Fec>3l5f;AUyblgl+w@Mjdq(uOxDS&n*>K?8YKxM`mx<#1 z(YejO5YpHB&UQ1?OU=0gXQ2AXQ_Ub~9c-x5W%)~*kC1&00ci7bWKlfCK177YiJ4C- zGwNC7l#1PT8|5q?M&y+-Jq(jyhhT5Y7ME&=Oc;@-Ya}1=dzp_^)z!f7dJ?Qn9o(l8 zhb)W_DjrNW>g)%jwaRX6A2hV|7`=Onkkb1Sul1o`+bQKlw`9;TgT_NKsTdh6^;3?c zWS#tcG1!Tfv0_EtW+Xbb){S=*>vrvyA`JgngkG&i5ET`bA^MV7((WikYxS8~ZY5QI zAd|qwdV->@sAJ;J-uxaMcSJ=`aQlm#Jwm(UK!g6s-`1l!e=_R7R zdOBBuotk5$;Lp1hnIvOD@3=hgNk3Pbs|vbo1J|8sH=0dFQHHH z4&vp^c9PG*d5x@`)HWV@&PE=c;+K@n3T2)q@yA8McR=xnlsBsf^??=SUz{syB+E2z znG~fl_D$rgJR-7g6-%ZF{6fIJmuUO7v>? zZoU4Jq4;!y`6NwawXg`Q*(N~s>Lk7dkj#Ei*ea7ltw;#@Hqhp099H5A_Z*lz}LZ^(^LtBYKD1rX}qwE7UjxuMxnPYWTgiF9hZ> zFxrT>^7_5LP84z&p?85;7jrF>$63?|ksKs77wf~u!-^dxLCM}s!xj~u67oz8aLIlu zi7FLc)o%KHz9>**&F@RZsIYE@Dw>5WFyrV$R?}P&SxMCS$-V_zB;|yG)GXTeKUoRj z&`dYfj!l$L0fu?p;8m|&sj?DRWXhpqW`GQG%oJf~^slslCEeSZv@gV&^J&Jgq0wIZ z?(tT^OH_*O#OQMx@EoV^GG`*2eh$pQBws3h-vFHGWNsO%pm1g|^#$Z2NeG%{HVTUC zTAN=tBF~_z`3n&M30R|7tkIWSq#AaB4I6|no$ASuf_yN8Abdv_RmC=751=F zu~KVcaN<$#hI-aW0@&^>k9FgHnP~GCM;K8P>!|=NfTz-3SB-2|G#o=5#r<=Oq0Ur_uq5fH^mz5$bXmm4>G*Q3u(d5fx@<+hZYn7tX^L zO=`zJ^NyMT+CTJ&2OOk@Bw`3=icb^~$}+U4BVPa}O)$QhoqZ-vAD~L>MMV2%cD4~4 zN)e!Z!XG$6pe+^rHOx6EPXhHh7Bg3uLcB-}DabYZmEW)uqgZ~J0$FJv&a-B5KdNLL zaf8@H8G{TSNEy^K&}NL=62P;8|TUpx!S{pNTE zUX=5uETp95Z5&30kmbV0IIT@+VTPZaG2mgF32YQL59yUny_Z&uS)h^+I7!4qVZfeG z5KhV{pQ^8qurqXg^%gTyV%1BfR6c4t?Ry%^hmYVi6!s|EumxOC<`Pk-t!QuEwNG&QtEll3H9CC}Eit-nFf|7QJ5paeNFcZaFodz5m?Gr1s;xsCBr!!EQ z>_xG-72o{Ml)!#xj7gOPli|}?J~AkZ&QUBi16D<3t6IJyHLdSYn8#Bp&-Pl>LEW-0 zSz*VaW{=UsUEnex%J4<(cvS)$Z0HzQ($LNkF37CcYf2(3jyH!csB$A#NmLGvC$;*7 z`SEUY$`N@cOezsl%0BxZw~FGuDVj6TJbTTgoW~KIXSHubAD3mFk%51^l=S*lTDjlT zXUv*VoU)YKK(4E#%C5wlq$iXB9x*h;fWQh*2DdrGIKd4+EZpW=S!TnQ2siD z^C=cG3(YftCba`63?m`XVq7}mWC9-uNmpi&-mlLd0?W$cl3Mk}= zw4NXF>G#AV%jwHDkCIS=H|^qn1Of?wN{Fu?2hoyTl%lZUWjH_~0K?MR@?dpCke9-~cJ z?1b}lmzCoP;uvyEG zuRmbUZ*9`=x7mNfoa{f~PyqXPIP`zR5$(rA`<)lte>3Od27+CzIKDHT>_9FSAc&I_ z$VJ8tMjg1mkNyeGgYV`%|3cf_!O7mklhwt^(9YSx&i>b3_^--=eN}kA!&rZ#9N7Bl`{@4{%Kd?E`ETe5m=Iy% z_)&Aed4O?!gD(E8lKa`O`iJ(;ALwrXRtTJ6i#&F~Pjck1{#Kk|C?zf`*Rk{Drn)~O<{Q-Be-)1Y22W)T% z#&^ICdN5l6u0t+PaN-sh2MhbR!T*Qn>JL6n*~JN*)%BB&<6vi&;rLr{@WA@>9O!DtP&U=Pn64VFgK+ogcoYHi z*_j9mVQpprHjFp}uGE~S-|ym)fam*VdDWU{IE8ky(u^^8vBX2DUrW=OaQ6Gl&-A)R zw*MMm_Ts+z#HXTd$$!EO1_=8+^p+aeajwWcTT)9vYXYEW9r@(WZNFnyM3A6%1K>w zS^c3Bph3J&?DV{Xg?Nf{;q`Q3Rm3pAPto%7yIaOZ%P-G6V)3;ADJ=ffl{B!j;avMP zrn%AFhe6|4 z`Zilc-nGCTLDxVdk*vfzHS^;Ensj_q|^w75$vZcY~2Gx(*$ z?Mz?g6k*n;o)wlS{LBo}o~LnLa+(s`xzxlV7F~XD!Lgm5Vb(|ky%yyTf`qOLjh$Y` za+FJ2EY_c8w6@OLZWy7N@pw&>v0)Kft|z}`mAzvqM~8Wime`wdw^TBqeH*e0hZ72b z+G7*jIe?D*6wH7&pzI5IGT^RFS=d!BO%fw~b)c^Q^5MMjF#%jR?iIJ+qu^6(A=FHf zY5n^*P%lv-%Q&B!D>wvI>*Zd_>x-Bu8uLjOhUf( z&QvRgctkTfF>^bkI{q=^DO=K&eP1@-pjZ_90h{eU&|ez$nz!60o>+CR^^sDZ4RXGe zhz_5nd45v0yQh<1C(8`jl7iWw^b>|10S&|c2Rix$24-yv)j52Ah!G)UszVppG(1~u z)Di_tuH8A2ChHTy)X_B|4U*D6B|UCScFUs8B+}--5Px-Tam!JK2c>4w1%=xueCECW zTCSJkVt624C`nX1qI6h>UbS)GIHdJ=c3dSGl|waOOGFJe6&zhG;%|8&P>E!X;WW=_ z8%I;Mc^=m)G-Hp{eCEh&X0Le7034wvPF&fekvpx6kl8bg_0p^9N>Aw@$y4{5Gs~}O z>kmoI&TdUq@X{Zy2F_`vTj>JFU3HG0RI}K{W~CGC1Oj>CA<-CzjJMRb#UcgnnUpMr znEf65K}w%G?oP_9I&SUA5zQQh$2W*j5f!{Y=-Z^e;4K#l2nmw;A}Qr~|UCEmXZ#0un-iTIjmjpG%{{u*MwN_9>Odv`XDo;?UMd*&IDW=OQZ zRS|}{Eyo8d(XGy-F9(g<7!hl@`A~zlZ!?t;yPzTRSEE<9o!-nlpl#Z%MJ4e&m}c2| zJ|A8yFn0Qo!kv-jjFz2+1o9x}t{3lk9aEV7`MN%&-F#`~!$#*T`XEMSrhSuJ^R0by zp#I)&R@l(Z8?ldQS<|ljKsI&Jn+DC9o1#xsPclVrUa_&gjX}y| zLLVMCm!L_A(c@I3Pj_iH7WODq`uQ$uv64>p%RP2LpDM%9phS|kb+GQW6!Z$vmW}6* zAX?&T7-vAY7q@5)r%7*0pNaD(F0i%LD~@(|BHdrnK{dRO1`$d=qOyhOiV7VBbxWqY^e-5ul3;iZCg{4UsK{0e?G6fjx=`BLyT2Uc6dBo@QzRlL@N3zrL@ z%i%<>PI|wR5!r382#!9eKRbeam91hO!?EHTCkeBms+G< zbdcOT5mqMsswx?t^c-u8#yr#xQSzv(WC3V~6A#j%@yHTlbL=^VJ?|^*l&*J!C$7ZC zQ;uF0pd_ck; z^5wU~FpZycbVunGQ}L+1=kVb^lm)=b?pHfLM@$k5P5c6r(&Yt%ZRseo(#3Vj(Mcj2 zK$1Ke#8#*jT2PT+XCoOR-};$cm#U&i`1ZLgM*YWJ#Cq-xj?RX$yt4jG>U+CWuUh|W zipsSv`(U8~?XUa;symc;U*7E3Wt$l7T`iq1cUt3-h0$DSDyBJ=VA3=X$Jx0*ju!+L z#sbeq=(>ns_9_KqO~z49FRU3Pi!%BN<851G-sSk>#fe$BodiJg?zrtc6iRpUoRdHX zsN%pW(BeNiGuAS+r80W45jlJ8p5y7?5 z*Jh_|Hjx(x9Igh3T(Tck_ruGpiBRLsu7wD>M+{JnPIsdbmqPsTcJ}e;gF^$HEKcZd z$qk=UTW^k&rw%~FmO~@wJbn>|v`V@{6JGmcT)!Wl!{>5sw_ud^ybb$6<1bt-tJ&l4R(8;QeeP9&=~eDZIG9Tw3hK#tSu zZYd3%&*Zbga0y{CD7SfJoXwc%Vg24RP`ljJHB)5JdkF_7-0Hf#qZ1W48?4w}Wh3Fq ziJ^1zWRY7F^caDqMNUmBb@z&rh7qo1G4HBMzG<Xw#glI2-K#7z4O&yifkiGXZD72)SDUDhmfz^ zt@IhG_s|wcQPXK&r?d~PS0=`F+A3#60gcQ@D9!N7oi!IYT^b2X4t%kkylNsWa)EQ7 z3;78ThK$~DMQBcQF=!o;S<_4|@VSmMD`&hq8Cfr4bJs~(Rqz7c8y!Ob+|cQ&F`avIu!tH*Txlow}u!)8fLbi0bANmo?nFP_FjEM=Be_ZZ4ec_>P;N7*fl zI92vjlS2Nmkopmn`eABG8Jmw$X>y%}Wz&tTM0U0h&~M_uhVs05f<|2)wNt*@)56L& zH)jH652x+(P6C7B^C8a)-8lYbfrl+sG=DZ&)(=}4eIKt?b)mEBHMU}#Q{&Bib~(Fu zR4&==3ah|kW<{^>vXUXeR)lVkB#EuT-4Z_79huzOdJ}j+=C;@VdcgpAELvy6mK{IT&OYPHVJYDmr$F zpwR=-`eRXt(Dp8X0`lc&$+)P6uk{HO z5TA>L8Bc@Z#BPnz!aZ~d$I!KItc+!Jp3*uk8-jB+T^BqN*FR{xFVZ-_>fUC~JR2YO zNAhDgma-%5MDR0o7h0!V@Ek1!O8z!5aJ&&SY zh|o(bbRA7t1}OC@`2Ce9_4(_xo#$Atygleaezro|KISEE6`!Lo8#9I-?V4ZLe6dI! zNnZ=hO}k*QGr#Pzh{Qa0xf~&)e0B}Te0O;BaDPYIP9!^gy~%EO*GQ2({Zvbx$XQ+Y z#a)G$TR42Gcb|XmX@wTs(`94c$_(ERhiR&sNalHd9=v8(Evp={8gP<62kY0Ub|Cx` z&ZQm<J5g$vOKHGEch$0f8vLCn`?_0x1?;-rbp$4gn`p_fw; z1Te)oU*Fm)DX5I=``kc@K}AS}>Ebuc@ba#zO7?uM4Rw{Up{G9{6)Mp+7oIb1BrQi+sDC7Qk322IPX?LO-HoGcwbtx95YmON|cnWxG{xp0!F35gt+| zGA)^q@#|+#Mkf$$2o;l%t$cV5NQ*{aOR7nvv~UPH(Sbm1C3m@m><@VKfz9HCV8VG+ zzQ_{{raswJa|n40%Z2SuQ}(3@1QODg*bJkB$WB^4SZRBoJ5KQiyY(bT`6W6pVc<~V zt=r`j1OSm;S$DR)!@Kat@HcPjCX=63l-Iee0WCr}hch?%icSjyqp&&}JG>4YHWU>` z;HZy*ACa8j5Z5PCIvkfQfy%}Ex@EK4Kl>$r+Aw&G^mZjdkl3ZD4yN3Snmtz)5=V-9 zv{E^*h-D+5f&RJ{U8&dxfEl?W1V?R$X=iO#uL^!4iEtKImlDTAr_Bbh30~rW+H7~2 z_buMQ2vD!uEj0l*YhmUS_pf)qP7*$DLh}qFv;9O|!NM)~;UGv_8_~4DrRHTpwsz!_ zIxU)CiQLNGYs%Tv#jo0##VNuR2(~;QE9k_>MD+7qkZYgi`Q{(65Bj#!(_-){k|IZI zV8A${B+}aRF`zBEso>43CG^_FR2L+a+2UpDSXY&l)|th1H1QVP7qK_jBgNc8(%Mr( zLuzT;J{=&nya1H|E*8*WNHB@;*S!!jaNQAyn#yO%v_vTNK-rgX<`G;NfK>c@Xd3vj z<$>x^sMi6`Izqc83B8WtT!iB3Pf#qTNfD&)@Q)cLYujn=<9TwQ)-ntG*>v6z69)<@ z!36XVmLSd~s`?9uP_ZOh__j_yoSV*IKqFvkjBMinc*dHCMfr!WrjQ zI^Wljk;f6mrgO8@k-@z(#vSK&lHfaRf?^zq`=XaI>>fnUS(aFQ;iX^u$V)90Du& zdGk8NOLxiStlg22a_dx3nJ?WnGj0kmJdKO$*MB2U4j6MdnYYvuTct+aU$nSP7Es*VucI(;OR5+3#7g1C8~riG6Q62M8Y&MMRk|> z=pL)H$K>)v&)9@!+4}2e4sM0X55+l@b z7{y%NV->bVrT3ClSf7OkW@O|gD3oz}K*qU?a@e4pa2UxMWTO63DT}(0v45?Ykb?)2L&1BVU4!lyOpaaT)mFf%oD63nH5(8`5S#8Yx%7ABtJt$tF0Jj+3TbVFptFpx+ zLWQCg^wCP$setQBm}yT@%BUd>G>PotrQ)QL9{<{^2c(t=pTrzaw99HKh@6xHzlbv? zk6jqn?3gw7TGP}4lAPm}q*l$Y;44Y8xwKcX+2uG&PLE6p%BN&44K(IeV3$9MnNrN+ zDxrEmRe2RQ5e9QvA=6!aU73`hF-pDZhKux@3z?5f z(<_V(B7inat!)!hMm-HV-GGg&Db8ob_PRZw!^pYePv5=wTx6mrzj^N|HaVny)pVL* zzT#mgl`7SZcRU-U6APT6rk)L_1MS5xKoT<5V+QEvsfH2EKJ#P0WJZz-ibK<+m#cfl z0IF3w6EDjs?rxT@?-r}QmZXuD6SK0K5tCTp8Jt4+KzX@XcP4i-9Ud5fj5+bDEUsHv z_;a=>K;NW+4D)@8c2U?_(;V}ArH+KvJPBv())i^PMA>e)uAUlv*5?ToxN;xVzw`xF z-$Cvfa~dcRG=8(*lPW5U-OL5?wz-GDwm89DF-P&y&alH5dG}Zvw&PKBdr6YcL`ptk zuPIktLiJ=9`Mj;cLsE%My7t9H?dMfkUU^ZTtfV* zSLkIj+x1$yD0wkt!>fc)n&9Oe7e=u89`hOO^wREk^SyH9A|^sI5A>cL_UUw{B_`P- z!BSkY+3VU|!RJGc4zMk38%|-9og}>kul-W`Nh&PYby22s26dyRc|JlAZd*md>XL}Q zSF58oTPK3GC8&blDv?b$dMiBx3q4EF#6E`C>{u&q$2osRHRJC+$CX{fQPytzIm(QC z9A-c5a5Np#e6(qumK>W~L`W(uP$iGDB5BBf{Y)n!Z^4qTnd5zt$?JEioL9zx%2B~k z41LQnbKG7A-jVchyzw&&*;^jDjj_{_Q*|l*a+usT(fL$B`)HjF~+sHZxOoG2UhOD;aXVark(;gu^taYGzlJLo=DUt|KZ- zQmY=#6WVw=bB-+bLGMpaA_m&{%;pR&Y$!Y!k?p(g@ots6Rkm^;PCqWUf5k~OvkVys zwyjJ%G6%Fl^qM&~+db0uXlH0{>clGa{if`XTi=MRzlBJ?zvBOjJm3hhA8tLr$pbdv_&NAzHDLdR zu*yFu&mW+ZfZ#;Rp9yKdR1e2DM+p!&H`oI6KcajnW&SQV4eUVh`)AnSX!O?-`bDGv zh#LAQ8vOy{=oe@YoYDEiosjGoXpikLE7PAa%l_i`^mir`-}iyvxoZ4|ZE$|`j^p?a z?XiE02j*Y{fcH910N82d`{m+9ZGrQdhOe?b+ns|e3`AnzBLg%fOJ^kekjUX@?`JN|Ee zaKD9faM#=qBHbC$R4!{8dg1zbf-OJ|hAk6Ql>)*M~ z{Eaq$t((8m=HI(+{$86uK*s~v!J81+;`8Hay%cz#r=kI3pRnZG+vez|w#}xbpA2-28(yf8Y%J+xZL#_IUlV9sP1X z1A^^3|Foj{%lYi@u-fnMuYcz&&CUs4CxHMS4zQylI9Z*G9mE0lxdm{54bIrvfZ%uL z01)^T`hE1z+FAaEw{<^wV_QQP3sz-AGgA>mXO|xzKLY%%K{nv~C5L}O8t{1pd=v*` z*I>IqFxSrhLmBR$gZ~lA`~gD!w>bb7lm(oL^1WvM>PZVGvws%SpCHVCF$chT_kX?c z^WP!VY#cnlBGilgVBfeV$D=#!J0>!THvLD25TH0yo;Zrx{TZd$kgP0xBq4iWSCZSC zQU;uXwbVnBi`k{PI50u2`B7T6#_n}b&y*L;(}#l9j*YW;rRc7M7*aPFm!q$? z8y@x_?C=O`B4$|>OH-=-*dwMvR58q1?oYc%-sy%%T(Ep)i?kj$QVO5b6`nOUeXIx$ zzSi*Vph3l37C0s9&%{J6s-9ZigO}52D3CWe+7DRzpaC+XeSk^ht~onr->#lum?jq) zl17v>ZF*qqtk8^)(JQ{QgzI4%u&^I8^&s7@zxje2`oZXxJVI$*ml$?VZ0-1{vXc7? zn`|(7f{R<|9|J+p6O$VfWMYO~k=>z@kglu|i8%HyZovlF`AY6N)jmaAOkJuD`vr81 z$UfsnSzqc-o46)`?I}fK+XqU54$qG9$rV@TM<%%If-i3G??M*A{#<7v%l8*|OM!g{ z%TJH)zc7O7?o2iPt|KEEtf#w-h3Dg~-uIN}E?@Jv9d;>gvzG3r@9&P>m)qdVTqa}H z=u9A0^f5pSAdUb3E%nVjZW%;R+a3UV^Ej+^UaV!i(V8wJ#C!yrW{8Z z?U~jnLiGZHVk5TURIVf3vyA?D_N(;~Fy;Iu`(lnc7n*Xiou6(qYxT0^(bFp=S2VH9 zP^XZWNDDpNOUWZO%y`F;BMYd8F$=hZ^0zGvcef(;`%oiL2Mf9N?|46EUmf|KNIf}H zeizq|_;%sMe(THn@NQd4jw>|gE*1}pwJR(sJd4fPW91pLRa)N=>Nk(N(jSGS7{o$O zAVGUr=V;cVbj{y6(sl~4pmG1CcE#&{Q24XvY@~UYyQ#Om zT?|Sf=OcQV>TZQLGjN)^8nXnFuc(UbWV=Nc|JlWPT{!{5mbGMcw}4-p)(n;@JcAIW ztUo->tVv#A_9Hu-^n6qd8;sX)Sp?x0^&XMWl|s^WB22Y`pP(5+>3f}QrWTq|$RE#- zCla|PX}H;~hpwNQ9#Ah&my5zj)Y`+xUW~p(j|)Vk$=p0k6h|GeuOumWCx+s;sZC!% zWk}tMixr<}Tj+84)vXYHjlGy-qmm>j;z@OcQlG3RtIn$5VAfNwJ=a>YhGj}dG7Y3N zmx--TXVH5U8+;Nq7LEu3#>*GOQPZF_z|#sW?wLmsBq%l&uzgX8TzhfEu?h<%pD=)Y zuVG^zcUgQKrRjuH*{KYa-Xva;P2GspJ)wG`tZhH8;hh zY$>lN%88$gXk~>$=LE?|9O{kYTd{ZYf-&(V5Kkc%Sfs4WGXwK+0*AgmELZ*_YzLtc z%RuhEzDR#?YBhf$O%F%K{=8RPogWW>}cWG zqhWSA3?~??p3ErDq()l7B%xA(9%n!tj)_TfE9K z8)bm=Q-43Ok^2_tRuh+N+YP}`FVzWGL9i0#!Jcn0;b}K=u(iQaVeNmA7{%4Ts3+&- zAyry=u-SN>Eu>O}ZDR-J#=aY%b&ys?{VB^UN7I?Zbj5wv+jXE^7Ph_(s@K;M-XO+U zFLVxoj^!{#G$u4e?IdEsT&WEW(~Tl7zAn%;y|Ujk>^GW@hxI%i74GW@Vz#|jGSz~q z22P*CZwCAIAtEkT|o1%{N|Y8C$K+14?SR5N_kn0Kw4#Z7Gm$N|KcMaiiRLG2ASY6 zW6QxYCNg10z}8L2(S38A9epO{Vzx;T*Qmf=jAJ$Xmz_TTUbkV*SJXt7F=RL(&bg|Y z#kvACsF4H#%s7+dk^;XnaV(H^?MxlHj%A#TbKCKJ~)2uRIG9)<$=S@AJhT zScDLt!b4*u4;>?f#~YF4>JSayoSbt%efZLG@6gZIY=lWq>A12z8rG0+)fXU0Wdid$ zuP(MIi-9-WyndL4r-KCz_2nh$Q=d!LWr(H$=uWE%WH}a~nzSA>SB+pqYRmj!cN!dt z31!c-=QuE?eH;Ryp#TU^!D1=4t%wt$Xdk!7-6Qc=TJd{es6>+i#*c7obe+QzjgW_K zYBYd`Z$_<89gps%eJqa3+Z{60i#la;Qc1Q=WeTkHYQJpWG_m4GNCJFs``Y~GC|)7d zu|0-r_AFZJejnLF!-g`Rs4zwDs9`X3M#QaP#>C@6nm;Q#Q@_K<%ZN%m7&KMFRu<^+L`dzp_awtS#e4LMc|-`(4=Js{_eZoPSY zKH)3#=!k3~cRO0^h`ph>-EjuzT%qrDiX+B=q zkT5@B4^JpCSoIL_!k}AydY<+XQ6BS2rtDWnBIt~= zW7jkv(-c@vxyI&yISKydPPIwC%<-+yM^8W8U<5Fss@x&&nmkcWs&|xnu-e^_#NsMW zFqgbV-rdmrWOwSskC;kyU-@F#_slH0{^7|!&04JHo_r;J@%=>1P-SGxxx}_c#+{nz2!rsbPu8kM5-alA zr|rJ(_)qMCcU5mejQabI=h&HT&w-8Y%4GW6HEq6<86RGc?Ds{#nVL^;-j=6ctY&Z_ z;tYVvqJH(vgj8p&{|!|I>Hd;KnXm!0B1$j4U*)zSI||5vLcLQzqwESE<%GzmA9K-y zz-mECI1g}}aE#dr6!*YcqlSR1=r*VpPW%$tm!34g7Y7)kDo#97?e~XPj=RN>WsWV%9R2Aih!bi(b^lI#o{bPz22us zQi1*W$*u=U__GQ(0X9aG-jiB5!#diS^vo|j=oeMug)8N7)~xx&`lxe&54VTrKIHT7 zacB0%ZYNz)0*6F8wsJd;W)ZAHdiDnGw;J+moR63}JP{$YMV_8M^+*mm)GagaU1mHI zfQF|rm?;<}U+%cQ;actLj4tWk8GALe2Z9m{6 zkErl?P)h84Xkk0h&$vsy(s@bj1a!-3C9Sm7TSRQ&(q(9hU0G`=`(je;i1%8w40l6- z-Ba~-VU(jebcG$#^q#}#gB@qa87jx;oXg#J-BwHaoo^9A3_Z^8TJg_#M{-%EeLj{l zpwF@t94Vd|>Z#1tYincHP#J((Lln8n_SdSc?Vt>HtoT;d6qjs2==Be>7TcG+W15lD z30^%nBWsICPXnHP>JdNYG^z*bwciiTxtk5Xm9^}7B{zMT|Ga+s5VG}7swRm zQQv)*D)uT}ePOdrcu=r)VWF`V9j$yYZ7SVj83@lQqH_prYm@S5s(Mwk5-X5Yy4HhO z1IMmOfUmo6tNwCTNsP7*zMS|?b~Bk%CZuIm1~KpW?w0?gDO69CMjnyMvL|wr+Q*fr zaWIzKrzFG78=GRMhU}@)veRN1LvcvXvVi$I$QKi1$`s{Lz&F`mCk}@Op-YoHv$bR^SW3F+b<+R<9aQfmlbvbtmv4q>zFsV0 zSRN$gT$CEi&iT+J6vV%ua;R2RA1sWP&EIG-mO7?tW^EQau+`7aJz9^gqhFRkb~KOI z^A40e&||dTJ@AZ?59}qbgnXgZ!yj5T<67NVDUor=OLW*C<7k}?#cB)-kB)a+!Nsq3 zh}=6qe`ro?&wz^Mtekuu6`F%O6Y;^-qHM+M_U4lSk2ve&dxR5ziqB3t2=(QCQs3MO zt68Hwh5Zn7an|E^sNr~31v&S^N8Sc7(TD_TAO-3cB{YnRK|pvY*E9C54}*@$kuO(} zF0STCa8Jsah={Rr()uK;-x_Cu@{{@n-q4f+xI{#iD;I;EsH7;WiAk42)c7U|6vS}5 zI0$Mk28S(0@rx&~bY@q=lhW$W!h}{=087$=8VV@EefdK(5H5JJ!Ew!@q5k}I*y*LN zR2-XZIz3gdAcnyhZ5WJHGn0$G9;QXIcX>-JzOMG5#}VVOd_y2(G_kkg3;ZzLK5bpb zrPa>}FvVEtVr{~~)&yc#_0FR5Rn&=8Qbc@YFrw3M3W6GQ!*AH8y?m54I_pke87Rp<#RYWgYA)oJF&B6 zSqo!(L!%zoM(J6sI~qJ;RMHh%0f|FeBv^^gDS&yd0nM_$sfkR>VK~rSAbAxX`6Blx zIV%(V+9A+d4SleyMr33~ag^0 zt(YR^9W{zC3O+k}5_4WQgA`_h^(dH}Jywvn04G-)jr%bq97CF`5!k3RgOjU2aL84p ze-dqj3s!~o+RX#ReMX{(yFgPlrC>JlTZio^i6X)%erBMe<4j)IpB8W6)2%^%6xX&V z79cwcj;_9y2>)nC-3d&VQY)d@cqUcDi%}UzDcSM{9j^c%6OYyfE}@NjJTJ^f>|1m- zMQS?fDuGwDoW%(x{mSRb7{QszAy26@gsZli~Sz1<0>&8Y_#n<-@2&j1&f|ybA*5^NwWwkS-Onb01WSSZ}(Lu;- z;Ixg(&XDn>^v@QV55)l$5GLQM9V3YJuV6v5lO!#FT+6%`99!+1EfzU2>CiXIyi&M^ zfmGodk#)f!<%L2FnZAksMBdCxqS!qv1_syf?);*kY^;%oKzakz(<4n&!ytl3;L zg0!ZxN+;*`Ani;*ebl==Kw~&w_c1NHEb?WJ6Jhzp2d0St^CJ&z*c*%?RaoU$D34uw z*`B|4jTajc2Ea)9(3MRM2Se`G^mpM;bSn%}tBqd;5fHt$6nWD*md3R-=^(oB$g0>w+j5~e9O~SetCrf(eSfSwFjEmS7yqG^ ztvUZ_yHk0_nB@pE-uMgdKpP4i$4QBr$`vfG2QWl}=k*rt#LMe@*5!vsQqG4+!ZalN z7BBEDuEJ_RPLt-PO=O#d!j+x8AL-b`jC7+)-Byfw`*7@S<0`5rP+WKZHPz$&-r^p) z$xFQ{ha7jv?2rQXyIa!U3@HA8g3AK`0iyUH0)JwzVE4Z7cq{NH z<_Zpy`f>Xw=F0IMbNyd&ApHJNerG!i2<9Z%Ie{QB-pU1TQvS4q;{aoe+&n;V3lN;0 z3~u`US$=TeQLKNV)AtLCCHc3x(qK=;Z}Dk=2ibgok^U8hz)@j8tOkKxU>1uLOeV5} z6$1Sn{Sz8nf0{ynfSLG>(E6=dzNe;vIKTto5(0uFu>RB%ax%3sHFP#*cH>~-`RBx* zvAwN>p^K%FrH!SFC+lB}M&#FFVJAa3`yU-+(BB16eV^68vw(h;2aJ*Ys2>0q7@z<< zr-D1|T;Qw-ZZI^R-M9uViR)WW3hVhmN2IRb^LWK3gTL+tyGIgG(hD(&6_WU%ws? z3YBB+Sg}5Cxx>> zf-Dvp#-VZ;qb1Ibjo_vseYlwJv6mCyUDtmw&vd2J60>fQmso!dn8hcKe))g6`^u=g zwq$Eug1fuByIXK~PawFvJHb7;Yj6ne794^T+}%C6d?&f-?(}`{_3PW?dp)}QR|f0s z>;tuHSJhfIYfcZXBnH$<%hAEx-sLfUJpL~kbo~DO>EDb`EUCrNjy-7|8tV7_$Cj7T zT8(`C9Ina8TJ}yIANI~1d7Lz8Y(5~oK`YUS0TLS$O45v3_2x}B=IkcIGaE@$E5&UlaaNNw@qcJQ>8Ngl!IDbCw{rM>np zzDge9#qII-p}T<~=ZET@BC0t@j(RnVttuG?Xwgy7N+V>$1Wv~1j{`}^Q9D!D%6ITV zMFHi7Wh>joZo#|@*P+i*=+jo-s8=pZxH>M%r+Cn3OsxpcbKu?KHaI~7Pi~`@ljvV{ zN3VL`Y!V3NQE&JZ^W@jeJY#t?VAFy;FPs1q#mwi%-C%CX(n@*k%J>Nyvw>yc;-EMdV&l5tBI^bnbWo;I(XUg!w36YlpYV6sxSuZJPR}6 z;!gcEM&d!^zC5ZDfbb5wO0IwR3!^2804t_oqCb;7)+CT&`6~#_85xL;`(SN{2r6tT zv@!JCr-sv)i{}FH1(Z(g*Rb};$1IOzdwp$ji z!Wex*htt)H6?@Z4DzQo_zzR+)2%1VPjH|=2mG%bCAC~eehTtA5EWr_n5Hdo>DaNKf zA7VR=4W=2q(wN&ulH(Ob%wvz~1oo_#6oxz^LoSQIC!gS<<_C4ut#xWKi?}&4(Dv@~ zs7xIS`_pSv8BeR5= z=iL#1dyoAk-LzWAD8IT!lWlzR&I{ybAfLG=NSF8wQ$&pv@cIzwcnlF^K_;4tOWD;uI{^n&9Q1dJ0N zr()s4%7^#ugK#nN%~@?T!cFLkWH4)fwz8eyi(VI_xYOSg7lDqt^b;10$CBS!NQno6s!*-N4HP_GBPLv0M=y9s>y?#w& zfq|z-`w>{YcI6Dx(AVp%!S&!0$6 z2v!1UaT)W=LLhCwC95?8oip{D=H=_#odSWV5B7HucxM;Yq5!J}O!nNOZ)1+-IhP2M zAow~tzs*P0|0c9exu+II+OpI6+N*@C(qvZt+vg#HDz;DSD3PbG_w*tPnfDK-gBg zQElxmLCv&uX_wbUt|+Qd^!b?yF~-BW zsySl!4+B@@Rz!>9@H)OLP=X`K0BN9cuic5v z@j(gp3#E@4NaxtLAnmJHNL-=lqap@zlu#V?LBMYXdN%DOX4sZ@c9})v+D;@=nB_EU z_DwU(?(HA;^%veY)+DJt^5OWBTc36= zH}HARvL9rIJYTI%;(1&?clGhG=Y7-FZnJ34XkU}?Vk)upB|F5IJ>MKs*SIz_xHH3P50XEJwNE( zZ1i!O^h7E}J8~)4e2q05Or%v9;eh`Uh;GQTd^Z(S#jkd?(Qq1?ysDRUsnSWIiam{U zqEc{-+5>Zqavwg4k3<=!!k4~SL1qTxY!#427PEDB>Gq*vLr;?E7Ru6%4q|K+7?gb= zo?batzUjlPCheYjg-l3%eN9>g6CAgFR&_C zu2R8THIksSD=N3@>_~h%=gYUid(Ggr_+;jgcy(_SC@H)&7@5rcWrugKF$%E_VRWe@ ziqOhgZE)p!q85*)dEYbJ0f=eT_6lnYfpN|*hy+M)`&}7B9DHKF%v!rx$nCYOJs z+Qw>Q5>?emnbNuJn%7~s{D+*SsD$Nid7k3pXzFV$ zVeOBavdOc^SKD%`Zz0k9y^BMMHE%ATN%zBD;?CSg#F=3kfU(?qHm>40R%{%fyw=e& z`;ZXEP!hl5RkAvNEn2k-tve3n>S73QTanhSKi1Aja^soo!7HaIcZ?sFdnT=pnM#gw zw0;|m(@EIs?H*gr?B)KJI8(MW2?Y$V5J&SOU zyAKo@m-Wk@cZK18L)L$gDH=ZGtWLg#Gd)-Z)$B;?&kIDefYL*h?ns-qWQ0E0=rkT()yj%9Rjk69}v?(P!d-f7PJdpi!~~UuZvd zG$4fNIKw$mK`|hlugo~9w~JNX<&4Nb+bP z;gcvBZ{#`22dMMHsh-S(Pj=9sh2WQ$$*0rsnmz72aGOE-s2j)ndUJS$d=^Dq8mM+( zCUSTrBr~i}TYObZwj7}FSHqKOt`6{Qn2Uk!De>!vyO@T zX`7{;sk!bdNBccxDi&;qpfUBmZ*2Y?E;T8?x9dyg>C4^hyduu1RO;CDVt;LmIJtu2j#i@EQUDw%g5S_%9QbcpS?p}MZ z|B(4yYT9aVg$x7(O=0rl{y}f3Im77i&D59or+ncKeK-_FY5l2kr}T3C!H*Y~?YvJd zyoO8i3quY!8wu|-ioZnM;;L2&nMkR4Da;634#Y*-oQWq`4Gc;&zu(8W&6Vnn#%#++ zPY{8iCES2)Tl4P&Y$O!1#BajUVFGCgk{7m7rU4yXej>eb@DR~(l)7OK67MUM*N=No zTZYXaXTCj|_rL^Y`4AaTGLiCEHKy~2-g=-LKnxX_$;f)!H&d>3%y~cxw`*4gW!7<6 zE!2L>DisKCP<b@}ZP z6ca5U090kT_eE9>LEi|?2bF_?ef^3bN3x-SQa||>?1;2^&|V5&1ko*!&<&ymq>a$c zn>5D`OC(XfcCn4>W%JZYMiVaQfvALm;zGwKge9d?$(yrcni4L#W&~eapUUIPQ8u)PXU^UDv+i@eOE2h!*mH;a za^ifzLantI^gk3yeH-rjyhH?KTgQW)+?v}*_kJH%rC`gbnAON|xvC*Kz13 z%`oeh2AdJs6mc#tVKbob>WF-ZJnBLMt*i19w$CtSxH2Bw7DCYEcx*gQbvtC*Txo9D z@J#B1RKMIq5c-u+G<5CsVAfEqAc`BUP(Bs^1%7(9`_u>T@qBdvy#2}R+b)}qT>uB= z%1}0!%UU&@TEhJ{C;cW8@jWWKnt>YpN1+%5f-b5wl4`p;S1wMBwHYY{=;W^D*zhml zG_iBRBrDcUnpC6PXHz*By<5@FdFL_ov+2^5*`c?n2{;xdowcx>Q%@5$uCZHVlt081(3{2g$`pQT^ooTYr6SU3kK+^=@z)n4DmeajV14`$1TL-kv zR2cUs)T3ASt#BhXIs>qf{-s*7W9uAMEGsF>_m>`&mz zIgmizgsiq3#IIgGXRF!La1ls$YFSz~LfDb`@08#vbPJQ>CT15qSdQ}t>s?lTYOF}G z14mpe#P-HM4?zelc^nFbBwK^@NRGn7kqH*uuL~jGXuxhV9uKT^Y~&5mdM%xcK|$mv zI0Y^*Z?&b>(+yHJm6MgyE|Z)Sf$(-r67dv@OQS^?ZYgfqQ++E_3NKqu0rkqlX%57% zdB!(D?CmRnY#|nlKL*#WRu2ZN65YLw%TC@q390Bz!ibBPFKiG%_>Q9v-~rI8Wo3w% z8%%<@eW0MPRzqyj2(OrEzA&fAVSeF^s)I`5#uF=i<#m$Mo^6z%KjUjy>DwPnu3#~p zrciXF(KEGrW<8fj4FdtY{s>cS%Ins8-Oo_`IhL*sPu+y$rnG7QD zBXhe~IENp}sEU@Q#P2 zust4AowGbG)tA_ynkZ?iWWw zN9PIG$|IuUs}lMsf{BZqXE8G%_bT0OPZj7_*}@5wCbP`s^B7DxaFH#7M_ zf2D-BU45o&>u@j{p84(+JZ@{JJsJ9eA%>p~5@PAoO#y^JS4ygILO=dq1k?Lg(?}FV z6GekpY&uo7(W*3hrT5XV6+%)ig6v%sM^H(1U~G$=F}T_%sIls&N@n%8p*RNJ$ht^A z6B46s!*hbDummkR7QxL_=al(c@K4j+g5^ZIDPo;UC4W9k2&50n%C_HCwWvdL_tz${ zR|OAF{lW&WoPdYO8)9~)gQJTsKSK`?F4R!0hR#xPk zfjJA`lwJ3w3z<39xYZ@>YpzYGEXf08TwaYFw$ zzyW}c%#Y?jU{dtAe}94m08Ovoe*Os(05oxa`}rqGfbAz27TZs5Ew&%rTK^}Yfgiu( zAMTj2|CxB^mzD_|=Rc7W>woH*`~j{ACT2hbmYoqmtpaE~a?k^Wy_lIf2?5{-dUj?e zz=r^FB|wM&$LhaY3+=z}LH?=h_*?Iqg_+~8IcZq`2>scwwqXGvK{x=MXTO?;gZa0` z{|w9g0n`IC8wa3m4`37d-md<$*RTNk`T)gFRscZY-`i_gnSaM0!1@Ph&;H6bfAX4N zP4n;UHUHHze*o?9Yph`bARGP^Ykot>aDL}o0PqL=tH+xEjW7>D-owT6yP)$2Fb#iY zBqn;spF!s@HUh}v{#g7M4m$sUiGF1Jzc&T{5|{t%F~0_8W-hLune5-wNbi12UhKb% zLO&{@f5b-Lx#fPJyBL{&Tl~+m(0?g!|7Vu0zd&CATxvf{oL>q#W;Os`?VlBk{#3~Q z4yp;zw)}g*FIyrP>E*rnxG!tLF*smhjDJ`D$G zFg3<7x}-FV$Ne3%%r*<*Ew9>Un@_%ds5-SN!fQWav^gzpDOn7t9I$4R9XWh7A;_jU% z;C`L>4COrbP5(vMr@ie`=Vgeac%6am_>w|*;atbZu=O!bo8Nf{W4dr}PuFU(VT|r& z_S(k!?q-#zZE0v~sMBeUJHh1Rjamo8wuiOT)p1&)Nf#4>x}CA&9eo4yG&jX%Q~T=O z?4jm`v-)alt$jSVC3}`)EHA3bUX_^^QKEU!d&zY2&kO1xiJ=)L0SQ5zvo1sWHt9*% zUX`5e=&Ugl>hGtV6G!jJ5Z0;f18Fs>w&@;%aV~Et3`aJcSo^Xf$STJ)OIh4920!SfI!vFT)~6LKSWLdtN>p8)CfBJ(qW!tgz|s?K`NH}Ry~m~S z>g9sOZNB^}w`V$d%hUgXKzLY%YeNg_=7jK=}J z6f)P`lxp{fZRMm-=QY3$&Ad9v{T2`3Cd2clfBMRA%j1-Q1ToG@=dBb*$0lW9E9ZWn zB^NMvvY4_Ja(JnB?GP8Z5({%%c;1n)U^+LiJUJO=2FpgDw!H_=0fve7L}SrJ3J5+M zbk_imtvhSoB3Rf&gDi5ERGL7jNm z2j#;@{(NKqFSqgO>UhLe8{M_ArG#Ks+QSmsWt9tkQ7qyZN6m@e?Kd9lPYVGc4yti@ z$9GDPOa@sPA!F`KSM2Va>(%-lEyWg5mW)EF9^%t%Nh5K!uk=b%Hye8tTxj)NQpy@E z_7K_q{7ZJ+^e3&Kr!?O}qO)=FpZ?Yy!xnCT^o-)<&#j1VWDaf{ zbuR&*9=1SY9igXWYMM*lE`;JW^B&1=<0e842|-$>js`r8E7BU{r#+ic9ATg<<)IGW zU{t$-<6a?NO@)HH&TRXim2o1b@oMc}Rh=M&L@@BhI>e4696k9qP`*to(F98apR2Ru zonOR@+5t0SmYY8LswzT-c}qg9NfcgP;jyw$69G+)X;E9|?jm}o@v1>ozHS3*rRURD znU`aT0AUy!7D1&mj?1DGaGBj!_nl=0E!?-aFiqn0QX+;ZPJAk8+lYnNWZ-6d;~b(B zfD%6nJY{G;nHJ5>@CZH){q0QYZ3X$=L(>X8>a!!*(j1O2TT?4(*CK zLxe^!2&{l3w(`9*2^$rn)jpCr*IhjYfm-J*12IBvM-Z=sb&tjZKRP*1FW$@hw#~=T z-*v#lDTvy1H?Uw{loYfAg)uyK44%+Ucl;$osA!cz+OZSz%mN=yOene5i~g>cVI^IHHt&@EBxp_Z|Gh zyr7_%{{Chwn1BhZqCy#qChE@X673H05d~*>v-!+!3n$;Ee(hlO*X3R03O+cgm=Jq0RYzuVe`!)QrpqzK?Z+H0Y z;&7%uTKW>FoSa06+>yHnEy%F(=o3X*g89i2SCn(8sJqDRhhf(+{{ zMAIWkBNQgyoQl4QG64@{Tsg!cAb=K*g%}xf((~Wo)5d` z*u+)8OXdzHu%Ds-ewZKGi6zgcVD{NTpKV-t^Ez|L;lj-oayM+))1@qIL|u8qqUj!g z?ba1{3Dk^*Amg}RoaxJSTZCs|ii;_DB7BTxf1hlLr{dGD7ur=(u`>ith!>!-Z0tRv zy~2Gk*BS5tpQ4}M%oE^q8z+_HNZN7^XsA=YU6gaX!B^tI(MP+TvX~|$IfI18yp>ve zIRV1#RZzRMXnPS6swUsnY)Y=1mKZ*ve}8u;MM9-R7B26Jif!ibamQv4QASje1W7y+ z^>!RFpECh^I2b$hn^0u!0>gC4=&(*m6Fa-3k|=6CvfZ>)PtLU<5@+4esbLp$99EW6 zx}jAqL1B`AcktDP^L?@GMG$+?^R+i0S^*Frn*F&1AKGU(9r+H%mv0r6PbH`Ak#ii0 zE?`!aV5FM~`BA|VUal%ZV8VNxVv^xf>@n&vuGz_Pp6y}qRN|;kxOUTaeh85wVahyJ zo<*A)1k>l)^Ee1{p*I1!K`d|?s7T;=;<$jziue@3ZqCH@-yMQg%k1Kh;?U|6yLPg5h-fX4d zKXiz_E#gy3PuJSLVd_8``~oZB{rKuI#&!BMJm*{au4G$g@vAp!N{yAc9mq;#(sf+E zUuR@XkHI$z-kCw9zQ#&H@>YM75?^G!un5N__*$*c{O2gL3bj>`hrWfAc-1+t6fn7 zkw9(5pp9ljBJ?Py-;U zA-U5GoFS}9*wU;_H6ohCHshL0Ku1gGO^zZOwH_kLy_kfCN zYePOqKpdihzdMMVrx0z3hv8Gql^c9&^!qJmYsZ#r<$D){)Q!vfRb}+W_yk8DwO%EQ zaNrB3iF00uqhUQr^@YHkmQ01Y%MHCP`bH%5y3`}MO`fr?^XvGXd&c%n6s*?@33C1Gi6KpV|6E z@cQMn$aV|vUL{g1qX$V`qPYrS7}1Sjo6+5&!r^JrDlqDYPa!0LBw+|Fnx&Nn{sX-S$-OrY8BC+rwk;eXmDC>{KL% zYi2*W4#Qld%V{^~J+QFBbAv|&vD9U1;i~1QGMTHnZdNr_E8NNr@YYo16TP_C>1k1( zZD9~$aW;x`eqo$VTn=F%b`7pmu#@@8kF0t%o+y0b_cD*du6A$XoWOiPXeoV~9T!r} zHil3Rft)+1IaBn==j5szJvGczkudhWr%Mzkj#l)jmzBf`J+OcZZ{(RHy1B=^WXcy$ zG@tb>8>@?P+VcXxQ|VJy#@6Ej=CtX^S^4a)cMsIa6k4RtdYK!pjmrKB_(V0?E31=4 z?9s|%EPGG&gc)cXROL$@5dDr85M&+{DmXUb77$A6+nVf7@nb(?Tl0+7(+mqg`Hrq< zwRcR>SDtp6u{RBgit}JC-A}W_9f+8kad{UumOE{pt&A!I0+q<$R>-}`UU*T(9%tlQ zZQO!=O7`M`{QMt5>9_RPM6mscCFtYj2Lz_Y0T&m3eOFNKx;iJwyf9vD7xMEWC7exRfmK$D)ik=R|i5Q(hOF~&_)afgE52>+bw@&obEBW+fUTTyh3oAikUe5wIqEDXa3+aF;% z1yX0AwbSI7LTqcAx&xttAnn~wArq~Ne$X$3dY z=k|f=ts)2OGL5_JZ}&OmYw~SVIK*N#w8UcV(B7{;KUcnNXFWGEyPi;^&F;MFs~BPz?o(B?+ROg(mix_~-lkrb45l0F z)tj9Ad`qg3V(>GwldOXWV(}bpBDdfV#w(Y_Z#=;U@7h_QJv5unB~ypEU+Foe2r~ko zi+^!>(Sz4cORT~-J$&pS%LU!h!y?QD6Whp-= z(gnS&ZIk#>?giT^IM5U&*!V0Wl_Z+vxVr0_u5%ui;ibeuiywZ(UE;? z5PR0Sxp-DGPrfB-mveqmlP3Nnf>@ziki!Rg_Zgexj9seXwk4y+=Ba~`oW(|6FkRQg zZMxcfck?+ag$uWUo!!%w3fX>3e?jBuGHQnW)8W+Wtr)~a4n)EkK^AF&QCR2lD;uR! zaE?mT_&AO(;p5fq6X{KQ8!S5>Hd0lG*Rh6Ev-CRQ;c1h4Ot_6-P!YiJym%E)n~L^o z=wAD)*KyqouO)G79t1c+X`3`%GQ82UY=@xx_KjM3R|fuEbnrSbEbb_QrH7ag=65f?+g?Nb%dVKrfiUq&L3coXMlXtb6N7_UXd7P-R=m#1YB@{h{k zmBJZD&+$W+&;5DF%k8Rn29{v5c-CjXo*P`?8{QjcgsIat1xrXd;Zx&g_ICCqc~~n= z{fO~$kuejEpd@1xp{ZdTh~~`8T6QBp?u9#!Pw%^#k2HYv#^084m<{(yK9JCv``E-I zatr0Ajv!1u*EYd_g{-)H6DmRPy~PHW`siB7+CS_2p_;TK=4BuUV~ra;Gn$gJA7mZ< ztF%PWZigfS1wPkgvKy$Joh0Qcs8|@^5EBnL-Ztn}#5dsd3-S?b7KG&CEgmIN$N1=r zAhp!*XAUy}um4_yB?AL9UryQBreamkDXy8|d3BfwUdve~&l?@%m~aQ8+mJ9WJiCn7E~f`Ofc2!x+p zdA!<#XLJE;dL;z{^CJ&Y&h+Zd()P|3+>1>EX3@%(2=Zm`iyXRZOPa$K zDB>AR7wKk>y-k;`8nkD{nj!kH1DUSDTZjw|wydaNmAg#!ZhZ%L`& zn2Rjsx_DjrOsU#0x!>Of7a;uo%`A|KrJf2O}egaWfYH*m5AYh_jKfT_j?|12b3u;kKkOJGE&?)zbRJh`&g0EZ; zndNSRZf)ySkR4T^0J(Bcjv8OdulO;Y9jLLUBufa$o?1acp+`{&oF5f}N^be{MUKCL zmx2&omVALz1k{Ix%Pz<7Clg@c;FxHr>xy=S>~6KA`vE+M6i5oU2&esil!g<;MTv4%y5|W<;d!aJGZLgX3*N@izl|mQMb!OQhAD< zgPMJ)Q?cy$yPBS!LQ3E-A5ug`v9@V9xRWx7&_=unF%0 z`4MNS&2D+1+xVL(riD7lbJ6p6%Um_K!9o*rhl#s^@|QXwajM``g5;?+d6f~oW(Mr0 z^^3?gA`F}hQ&*XG!t9Bq&wNS9ZRAQNwLJ)XfqYWzU@JnIp-UV4Bax zBf3n_Lw+46k_gE~CyLS{JtLY1oHYR@B7B7^3DD|!Te=xQ1iFEnTe>tZq>!C07Ltcf z#7_e_nEU>{jQ5b#s|ukpUBQlf6PdK=zNRT_C5FKuOlQGMf)NI8I%X~py*$pnxa%wmPkH5$KA>24<&8(PLFjoZ~66Gh_bx%HW6%lyB&z{@9v1Zcddd0 zP9vP8T8@v8D;>N_&!Rr_I#v--Zr$gIeJaO8phhm#b9IYB;y>NqZhvr5jD%2qQ(hAJcdR%s8 zA~>-)aWk?Zdlr$9a<)wseMtfogzv2+Vv8Dik#SZwDAt*`AZTfCnlK#93T+m_(9u=G zR^&%R(alzQreQhNz!==$%dJ6(PhD4X`$&j|;ynQEOqi*Td)uk7E9C}@RbNtx8w7Sr zRRsKqq&_X&cUpGsr%*`H&L)?B-7lNrZb5&mjgwHhnLY|en_|iE3)1j1cF@2r(1+?+;Z}DKqP2Gs zBsMtZc(*-pCX>xh1pWE6xme^zz|rvJMo2e?O6Zh*oXzNztD<8X8PLiqf+;b*(oBRE zR3DOYxS?K63$cRUmW_&S7E1aSy4Bn0v+8r!ppHVP6P`$#S_G3 z6Iv5tjNL#rpd~N|nSoUGi{7~=I(x5~96kw?<*7a{iKG~el8qv+ig;W0^BiRjmof$m zuqEKq_3u5Meec|{Lvkeu72!SITIkcx9oKs5!qxz(axG`d%Y*6UVeQjqQrp1iMbPG; z&lz}eEqHpo5|?bx#^BCId$&h4$dFNeR~mI-?ubLfbG6Um#zei_xqr!U6|m&N=4zC# ze}RD@4rg-#?>Li&r*(QmT_qZPlJ`7-jMw6HNFwccB(YeB{8j1cX^^ztGPP$QjzP#T zzkZuHS)Z_7^wB=jqdHnE31!#l^=7buPd~)10^RH-yydP7p0tkVD>Y|)}$T1+qaQt(_eW#WMJXO z_fA?9r^%Q5Ontk_L>GB0TX}Tbt3A8$9g5T)N>Vt!EGdWI>S1)7KUo*nhecgIYp@*3 z0@E%1f(=F^KRW4LbO0bWtF2QGaVx|vsH7}^MQG`lhAE)2o3%~z;jOK=%D4+e@m z_|D(66~}zF+J9q7WireV^gfSISy5RNY=DY?VogPW5U)agqgI@ray}sSjXp(&6!4+p z*vEp10(TzO?QFy#V!N6%CRJxB)~ux^W%?~OoyDv=YW=S&8|b?To<`my#cW{>%@nt1 zxE@lpoZn)@HBNbGs78o&qH}Lzq-Z6LGPvBPX`A2e!$hhO+|}+e+LlnvCLW#)i|bq} zA)18m*dBbwu%3V{ZbQ?OjfMPzLNC>p5s@~6QBXlO)OVT0cc6~bLD30Qsd&vMMkg9(j|*LWE9&2*X1?iA%qM`HRP4b7$IzQkZXw?c zwc3Q%F>^=E*_n#0LmyOTpI_jr7wk>u65YO42hFlBMeN!ZV$zP7pieBa^UgmBFm7iA z2g3{@lB^=JW<6AKZig5sv76~vA!6)y8riKTz;W}kN>FzfqYAm%R~g7s z*i(y1S+mS2?#Uk}YRAhfJlrf-92aCMO^^ z)%)0cp{mOC564du2GLFH6|E!ApZKFJ%}cIG9=%Tjb0n77=f8|*WN9nEJ*uo^!bx|n3u z!4*gi8r~P5s#URw&>LG|NG>`oc|Z2Q4fwXM%Me<1lGmbAcNtWcx)dZ|oB7L7)=T_WR>tY(H( zD^}wDvow8bddak7Ln-dt)wmIEMel-#%)txU<4RSeD1+n>wS(7TEb9dcPe~eI)T^}O zp?Z@S)jsBSEL$s9*LpDNY=7lFfcGqpsD`%0Xu}OYr`Bgb6eE*d_Nfe;+q->LU;wbM&=YM^qaz#L+o5wUwsn<#FURBDcO^$&pWjhu1Rmqz z)+`6jbQHuDj*z%v4bF6j+UrSmx#><(F%E5CFM*I1I5ADNBbSZ27Z3MI58d4ZaM`ux z+p3v&DilAooK)8B?tH3KxtX|iMz@`J zufDgW>y^XdD>w~X+3Y4G-fu5-^=ZNa$XqtEK` zNU_Q)bIVYEg^$3HFibCw#Y$l0%47RD^#YnbFTnNRfaL)?Xn%&^{C@(=|3LKo4X`}h zPjEayy6*=Vp6w?%p6w?%p6w?%p8Y2{p8Y2{9>6sA<9ha=V0-qTV0-qT_hbKgKlY#Z zWB++S0Nu}z|Htw3ejGpU_kRMi|M92&z34RnMwW?_gA1Uu%?iu z--H2w2|r9+zeAn=$Sr?w{P_zMn+-q~_cQ+dm3aVf*bj&LXSvS*xp{tJr2Ah93IU-8 zAa&2i#X|Ut_k4$^b8s>Na`wNu^Za$l`B8)Xoqogoi(&raH@_O@-`Z_{XP94L-2a=$ z{F0~G0P3ThKl2oTh!_xw85ubM+Rdy#qtL(b3-vb!Kz`0PF#T?};YY#xcRJ6nHUh|y zviz2>zH4l9umOaM0c5IN0D{?n^`P?)*yxYUE&>Rx*_hb?g$*m~52e;0<<6f4Nm;)O z7yq-e)}N*ue*eh-z`!BbpQlur0i3vi$;0ncsy~!^*;xP&{zoAP_yn-}FZ@>gQoa4M z9r#lr_e)CtJ!SWgUEAOJa{Ov3CP1Y4KKJvhp_smJrvQupk#_n6MK54@l^#G6%nTUq z{JsnL&3On}0IL8uVg&4qnK-!sGtmD&F7+or`fXDQ7{mQt68Zy0?_b#lAnyFbiCDgm zyR)%!FtHOd0i5i|;=hLz{V$gJarW_dzFmLeGiPE2Ox692Lx6O{#>@&RqzRdr*?vZ+ ze-G3A?Ks5tyE)b$r$c|-QUD5k&Yy7zAgut{Z3BkznV7%xB>acOq5op1U&avsHfi-= zNo^kkq_%Mzs!lJ_E-gFpRv3Ig38rsiN+9-Eqmeq>;v1Vd8{$TQaJmhg7M5s`hVw1w zWloqoA@*EIy<e;h+y>ja+{)g1|DL_|h8kLXlyVSOT*0!WalIL97 z8bv|gtl5jV?;)6NLdJ5Ii&h#H)^Vg}FhHTVMZl-(foJ?pg8U#596MlW4^_z-TkCPt zrbQp`D*xK&VOMIEzmy6yPiLuxlM2lf_Q8j@Tw$*!O-4$wrRv)yMoR-p%Stenhmj2K z{I?mo(f5{@12fdEHx3*vxi(!DRUg#R8&j%yYORmp%NgcJy5xog$DH4B90FAj3-12; z%2T*Jp4xWi=2v=9RC8^V$$PE%1Gfjua_UxoD>_o#+if%M0CjG`o0F##b%DpLLmQv_ zDZLh|H6Oc|6StdL4ypM7CA}_$$L;K+D1}f3pTG+i0Up%k;cc$Zx*)fqS&+AbkC~?W z4+ZT}ZA&ZXOVP)iNOFzlFFCa?(XhMh&l-DOE>$+iq7UL-Q&SQcPq-=glooxFt?H?d zIh*;;O;e(u-am)xjTw3FYMx~fv`?Rpq^}3REO$ICpB%a{mO7;Cq)2G(QbAZa1xZ@L z!d9^eK|%|FF3EItPY)u)qqq)L37+>lLcgE2hgvy_=7DZN+HpJ7?nFT?ZtK~5gKQk+ ze9wJFIlsSlN&i4q%*@53@ntSb4g|+)+y>G`Z4|WeoG!)*iEikw@quNJ_a5zye9q)< zi6z!EI1SVSIa+C3u`GlsSR|V{2oA(c&WV9bQ8d#c^hXgHBs~y+z9P?y{N?N=n}*aB zp$;C<8F{TZC-RIwD#$?0X>Ii(Fqi^M#psB@hGMs`Ad;Vh%vhA_ z4csJ@<-~AGzolqHnu+DBmZ%N!+AU7`f0V3YExIxE`@qdInR7|{#*(}Q%k<+Jqw<}| z?2(wmb&nS>J&Uk0E%XPX{SA8`y&#jpy$9C2Jy=wsD@r3$paRdgdC7O=m~XS{^u=Sk zQ8QRZC+42FqxF3*zb=ATe$KTG8RRp4AK!DqU@%jN1#vuy`e9OXO!4vlFw6V$;S~KN zg3P;axj~CtyDy!^GRDl)!Jj?pERVnsXh@q*+@HlhV%RRPiZJOZe_JldWxe!-cuGf%*C;^v?GbU}-!rped*RXn&mfQe=-SN~LT z^^#Jcg5SOMB5{!!v*U;sEQFoQVsnL>Lky3})vMzYQN!p{3gQs-E!LXZtHF^qeiKYl z>tl-2Z{Votu89lyF38p+Tb2NqKh6)JYjcbMip*sC?(>{yQ|l(a-Ne&{ShzXVwKEZR zzU=o=JkY0)>Ef=NdIm>vT8TFwLp%hh^w^LBKV~$%fo7rQ=eKL6+b5{IIF5d~d=T(t z!%k`B79cX#_SpJ*uWj};ap@jx{8aww*>w3;sx1P2M@6}}uENS{@9d>+^duXzb^V%> zxWK!v3F>mKGnzP_3c#Xt>+{TDMMoWdriC|YIX%AR*@ti<4+lQ7y5=>Mp#R6+TSeEE zY-zf-#SE5Yv1BnbGg-{c%*@Qp%*;#{%VGwLC5tU)W`^GBbe@x$)mcI~y zw7tiUf6bT?YsDA;#Eb)B6NFlXM!3tT988rZq5;pI&{iaTg0==v<4KE1wB}*#Y9*8A zWc7lm*Y@uu!e9t~hmGf`^nktQQWLo-7LH)9r)^wR#UBO4jpYgIoa}B*qeO_AG+)hw zXFR~dgW)mn6y)SNhTm#KP3tH^`PD7%BhJJXtX~gsMCi@8SmM~A1$p(M%=y$&IZUEU z(SZQOhty7ToY9=x)3CNg(WahwXnNDQDRU89BVm6?OH=krqi|hyfBWX!lPW2Me-JniG!=kZ;ao&d$a0lGk#pxevi8~ zMw?7i$IPW?S;O-^{+bX8DSylhV%&AA&FU?)+|-PwE^y0WDenHEbc!Id_Amc*4A=o> zul4$p)To87pU?KkGjQ$E86L`S&wdy;ZlLhXO3wzuM^4Dp( z3Sa&>igJDTvpgm?pg3~>6e>3G$WAI$RF}6-pjV%0>qdv(lG)327f`{T6=EXl&E-jE z%m{Ra&IrVffh5NgJEf3~7#NbBq-1K*R2z~A@B8>5Jj%n!c(zZxsu#QK%=JH8c7l6KQTN}*z zF)OGUTDPa!U}jV=6KKE^Db4{)rVW`GXg|zgg?*8esjcOK-mq}oA;1G$a%xodmv(Z7 zW8_mdMErV1VW+4}!?E_r(@Vd4ZMnn~v|!mlISG~Mw@ett>Cp0})_rdhu72C1kZDay zw{b;tweL3lqJZTZ$PXyS&Ga)d%oy)hN;3x>xfLfJjXAH%=Wo>A3k@C;{VB^XWC|@)%!p-lss? zncF5+Uh*-AU~w9usOGTvcfEy(kz-7J?y=L~#~k;Z!>nJXZ+(3-N$0gc3bqgDv9>8u)6tYg8gqVz4g_0_}!e~)&Bo^mQI zY9oR2zJ;WVP-U$wW-EtXYoI9bFxAxLzIzvZDYd$y%aGtfl*%B2L& z;d4_Ge6I$CRKhga4`7W*$Rmaj z%qWR(Q*yGSb`THJ6r#1IrZZa-tzo+Rb`WtW+QTV31=akpz$DS{T6;M0Cq88X%Wnp8 zeCZ@3f-sZUse)N{W`UdNuj-unR7TNhTpN(g<|pZ z8?-HbnoKffZhE!}&neI&E$j+OdDqY}W#+ml$f#nPI+OJ`$BII}1>extzM%-aj~WYa z_%Fn?g4Y81W{NjtFJYP5c_WZlhl+OlFCb{^I1<#+QqVXoP>4CJIparPy_~5V4bQf& zjJ4?N#C@lY9A5%H|0dhydDA~btxjhJK3mHk^BDF#Bk~>B9F3qqhjBBP>r}WMyaVPu z-%6(Mq0}&pc_3brAvp)L)dehSrL_l42>PR8yZ;V0jhM5)$izdUHTQzN?mHiZ5s?TS zHWw@w*DF{YbyqMbtA$As?K}(XgN%f(GN*QfrwIW-fT*>(dR<<+UN7Xk88o(A411w; zv`5r^8i;JcKwakcO4kcgG1HK|+WvCYf%VcI`5ZWT7j2XTYHXd^{SGFxp$n{NnZd>z z5{h7b>K)9PAtFJ)B`1N$6tIYAJ_Mp~>xuu+`3~JEC;l4?L*f*)j+?22fUD*BA)3 zbp0c#a`v(W6d6^bQpJ+&Zq9ypkGs027p+QEkC9KCkk`NCTvmrzH>+XW2$0`31 zP-LqRojEOwO$fM^Tpg4!?1p;=hrbJA-QqnOw+{Wg;sUtrbek;u@|e>{jn2~v+%o}( z@km-FY#NSV2G$w&2qHHItgY2|yzl6?eP|vS4H8wD1pyG=Suy%aTnj3T zXrZr~P*-e1y!0gHGVn_eQnr-R$YAwunjP51p3rm_r*Fmo@^yK0{}CdRmfB@bNYhcW38;&~EXd*%D>pG9$Lp5y5T$~@Q5w0=T5*gr5jzHc;s|o9j#8ZlOVJZLeyfGn67Y4q z-61qi^dpaOA})IGeAr37N};uR1aA1vB1m%wbQLQP=4VD=y9TB}Wg3jV>^={Nqr}y% zr35qlc54+KRaTxOWlLR@1iAxxOv|s|U!k%){IXt`nxAn<(%tVJx5p{l+E>>p1u@OE zhZ$X|Fsz7Lx9G(~zTPo1d0a&$yeaeLtjio(2@py88Z8Q_Xk86!4Sfsmrgzx+=>&w_ z=gX~|xg}}^!EV!|i_$}Yv0b-G*g~OdEfby(+nSnurG^|K(NW4G*uWM@F84W@v z8NvifKs{@NAc9}&S;xHG{<)sD^HN%05;D#EcuGj$#=>jFg3Xh{qb?f7w8&RlSaJQ7_|SoU$? zbLDt3n`7pSU{a6+$U+Hg*9`F*`7d~=bj*tH(7j_pLm6b;tJWhyn4vGx+L`~yUE+ir^%L^_An~OgC|mkqVH3i z@IX6~y+yPXR4ND=Vl*LAiL^GsDN0~aWC}-&j95ON*WgWpOWK?$-g9Pt( zjSuh0XqSn|`H{QZ!0`>BVs(Bi&keF$&9^85oG?hBWf`+Nzk>NMq<|vV^IS^3z66+Q z=3ndv=-@s%<}5YH=5!5G-QX?4qJMaT0si#j6IdHAHdaaovJ&ps5T0&HIu}!-fR657 z04p5GEP;V3eofaJoE``|bZ%iBEx8&PXvTq>FiuBPjf=lc0u-lrUEU1L$3UTO=#q#I z1I0wVzF89)M6h|=2VD>haIHpC`%oarAFHPAm*J>uEnG(?gO5QPvg@_IUU{WHb9%R3)yeTHMWaZXy-7ax)qgy&nIbDLME4*d#`-!Y4>4Xlf%^v;B$N7tgre& zK0~@Wm5A$oIW9r*#I`%CgKKUk3R|_!_Tq%AKF_66 zL|~Ng{Bjh@%-7m2TCg~QZjJi30q2qD#Z1@HaE{b$$>-eDH?c4EzTla}F6 z4$nXC*WVWjK=d)N($E3!?jJ+~6hQsa`aeyizrkM60gwRzs742{b^cu_0SY)%vC=Wp z0_6T56H1JK+B5$#)c;~A{a&Si#?l{D`X3TY|3Rg{L0$aQbd>?HmCp2QR{CebVFrNd z>aVHlzhJ!mAFw3mzXeJF3Q*J21IkR}{-{Mw%S^+{fD3R&2lRr0l@XVY8BojnN8^7% ze{{{QbgBOZ`t>J>#;XUI1nqvNR{;Y<9S3uJUVRG_OIZi=-;OHK($WA*cGLa|3-~ef z{ncRtz$SiE>>uL%UNJ@%DnL>J$oM})F}gpqTtAiv|AJWm(B=1HF#vM#e|NEdN4@x8teZ9LsB$h+D!R9e z%b0nTP214-4*Sg`j8>;*2C{l^prR?sPX>XuUhq*P6(~@TNgn4bWW!6Qui_iOI z-(TN=Dc;9JTWbTg!sEu&OtT%ozBGQH1LG`tUVU*&sT((i>?iqfOC>1^g46SII{x+O z{)i|}cE-~EZoBMzRA&JFqzn9HJWPD#5kb|(V6PSTiG2d0v>oYw{B7rfzWT`QDYxgM z$Mdn)%UR2+$8s7?^YcK`cdZVYVQlQW2hbNHz1+K`b{SP}?yc>rnai&SO4OFecOZk9@`}yhk zmiyJF>O0a|$GrWp7cTy5~B=_zhr}?%uYVN(>)qCQC<(MoT%uA}SReUc)&(#a! zHC|4EAiUab4JU2aGjHzr-Mwf0sSM6IBLgf*iCmahyYUgY_SdOW-jq zgj6B^^joSg<&g5C#pV}6%5Im7*H|m zihtF+eV_6GC1^7_1Lx1Ip!Chr1D)XMa152xpdt@UmX??C-2}*r1w$O2A|dtp`!z>M zTxfWoP7C|@)zT9jtX_dc#e##Z0nawXHql~7bs*ThM*A)*cr)z4g6v*coUqsXcM#U_ zrjldIAsAj{tD&OO~4+OzIbM0Y1T@bj>l68-w02bsj#fY;^aHJQ5w!S<}a(Z(up zRF}YsFQ6m|6l`0PayR;elB!3~8YM;hv8b~H4Y9YB#9TO79-zIhY!!ynqsj@<0Q;pO z-g$hV=|8Zvk?X%Rbp>N4JnNExP)`O10s>DPlUY+%DZAV&l%~p=Mqzlg-wKwR^C#$ah^w)Gbnq(IO1khd=-7BG%MDsAqP;e zKNM|y=czeIqk>c1xjjUDRsS84Bx!1NMsHUq8n~{UG?B=%Dtx#ugVaz~j;2&)-`zVn z-f$cO?4m*1b`shx!%7e@EUXBl0in$W8c>Q*>&$HpXIjCJs7HeT$1V`9`vN!1xkhIM4NTgiX!8XZ*&V;h9--6o< zMwIfVk@|XPHDHc-?jQE9_ANk}wjn_0(Q^|gI~||KKpoW_n9-D>??ijAO~8mOL>Em$ zGT%rrG+Sl#V#!mn2_EZ@vO@asF%lvM>F?FCXI=y2bGU0JCQHR)cxfE-dF%1|#LlbG?Sc{9&l?%E1LDDI5HTow zDgc6DeZt8e({&YzKCdp_InYJlrWAT(w6|0mK;R)i3owFWVNglig=l zIxN&@kAi6!Woo#_2J(?dxsg_JboR8*&Ta8QQvva`gJLxBO8aB7*x*))7d3Fh z*`1&;m?YMvpULiUgHw?Otd#`@x}Fvx%wxpHu_aX>UZKuA(HJEOX^TZjeM;`h?&0~u*$W2B!(265Ub*EO<0#wGR ztwHe{X%q-!RG3wb0{r{kh%VbS@59?`3DLnjvf98B(rsbKIwXdv8(qHT*pqH27n!Gz z?X1Wq`mY+Eend*fn-M>pT;YGi#R~x+7Ini#5Ppp%%)iljov+8+(uX0fb4o~c{Orwq zNG^7isCq$s+*Te{cgu?wZOLGB28SC%sv_tXf{1*hxiPf@=UmlBA|q@nvyyhyMp4+2 z`UE_QJhsyo*Nj8ZI<)KsE6076AVHRW9DuvJ2^o?un<-Ts{f;x_7(>Ws+zAJkKdez= zOPwsKdVrFn+!C>#CUBI6@Pmk>*ULB{Pu>g!plnUq_{G{ag`_s%Oc#lH?6iEHB@C8` zmvq(aZ3NUJpnkpS@eQyoKtZj>?*G0bu6rs0$&II%${0e(;5306f1zp`vNPuN;^Y{#Fb zy>*haKN;I$m$wWr1G5~ecn&E@2w`5+ZdV5F&m1E3Rk6uBUH2X-01CT5cCv=iBTEkH zWvqyVqag=q_sP}b$)=v^Kt_wr{LQn)wXhGZ*(sJKYreI8Bc`l%P)n9T)Be#QZQE)W zbjR5G`90BORR@Sg^NtcHuoqe`!R_#Rn9*nb%@!r%C@yZVu8*x*8K1Ic#If2REU|)M ziZsp9wDZgLJb|i9qyH$6|ypia;U^L(*e370C@D~F{`<@Dgm=dXw67{Fi0 z=U_Ua5b%eRmcH(78%s-iXJz=PWWTCnL;&3cTp&)D@9NSV&n|U!IV+N5JYqhYC1m38 zu-Sv^8&%s%T+sv`H8O!KXjWF;jHQg&WywabdmKJp(mdNVDD~e&GGhi0Yp`k@)Tm(j z3LA)c46ftMVZ3d`Wrz!is5Z%qOc$ScE7-@=`OtQ2B8#$2Kjzkh`VH+=9OcX;NNgKk zq^nr0GZ40rF8L!X7!Yg-5UA2XMsHpgA3ntz3z|^W*A3lNckQ~%*~v}mgvhKnL3=cP#{A{0L+ADZ;4F|~@0c|*j}_ucYyo3QlX!W+AmS!uPzWH=!8UDFqK zoRr(dMKY;z7H8)4gNIiEl`Hn@{2bZ>L$z#wNM6C98Kr!XC2X_phG#4yW5; zupcu6d4fxDFo3N{=+-dJ5lRlshvQ2HW!6U6nZLr6-=dhUq;4d=EyURd+a)*Go2}I` zrESLvyCH6D#;+4#GhxPPfeAGxNoFMEG<1hKp%IWw==l!QonkB*J>)UH%aI;(YHruq zSW~8Z&61y((i%t|u;bFIyi_-$JhxmZ~ z!seSe`PZ@sqxBg!Vn@&*yL6A`5v7`Livnv9Z{@oQ-Jz{0gr|%aFvHCqPqJ{h-g=DGyf^2~=NZaS61jCYibz z)i3xo56yPVb&LNv2xIJF@TFFSo(lR1Z%~eqqvLF$L2D$msV?5iIh!Bs9VSLJ@k(Bg z8Vw2NPF-MJfGIDU8?`JXcxOi3+4h64lFtXJ_3+DKz=G5oE^?B=XPt$g zzTadLg?h&347YF^r75c>ch?|fEiGK9?s5*0nzAA{A;`JWFlq!~pjB#!$`gpH`_W`8 zjH?Djax2E#(y1~G(5yIWzl9o8d&YbP@s~H?etOu9!g+b_>7WvCu4G|s-jH#UdAM)$ z;}=2=ZE4CnoW~a;OiVm%^<_93cJMoqn-ea{v093VZ_UgNOigxLjzBu`EF$-hrV0Np zi}9%a?K(}KO5MXXxY0bX+5UZbTR^r7v9n2%LQ~y+|3ZB~*|D*y4OiVrRL9G7#H5p(_?R>~Cci!_i^Q@3Jz#DTs zLe(Id=O<%=YHNm&A(=^phUqCJ#cNf0136q++;303nJNn*l>ML-zj#-0Krrn@Tl=|b zNCGXBQ9&NksU}`Eqt86)+*CY#+d?ddxqFC zz~#>C?56OzUwOY6lOEK=-fBKZ6-hLh0*$2}kOE@s9KFD!0m^BMV)a$Oj&$P}=*q^# z2eefMSVfl^+n3YCTi+u8Z4H%=0h|tlxU?CsZO!)0-+r-BN!GAp zDqovB&1$4tt`x*n;qS{!uRvvTW4F0~kump{)a}!(Bq68mKf%Q0hDH8I;)gpmaQk;U75j)?V6D-cdxIzrMzw+kEyr zg)?iPe-exDKtv}oB&%(9s{qs=wQFjB`m^hAi5&7HlmILlzM5yX~S^fxYpd9P~t`&VzI=Q^;RJq7SOyXYZ(5(G2frmt>b!0X5$$kym3 z(ics3Yupr@*mWLo;>wa6QuJ(W9sI1}-)`<&^-@^DWz+7`yJz*fcA#J9?(8D%r{B&J z_|8WS>U_;Gg*8?1+$^0%usKI93TWAb*oy(&|fBN@0w#;GkF$W4W^pd|10L5@{Tn50BCY@4{z zQ-+ey(Or7q+X-|f5Cns@P?gx{5>IO)66EwuKq#QzzxJ{!zJaU6k3h30il?RHANF>e zq--xQS4wLe6{m`>8>cs*PuQY3vOUDu(BaEtKO zFFcXqJM=fskOUYdd3Tw$q3u0jJsbm=qA$^_sNc8J76q(SsTQZmWtP(o>q%KnmW4ea;oAHka8F_7VZY6ZlNX<4fnRfWBNREA#ZMAd7~X z5L8GfLe7L$Ob79$!LXof_XktN74hk?kb$# zzKAXYM0ltfRsNQ;9AcdmD*YB`tP-cm8G=3G5c6w{ZmkN$-3VbEaw#}#Y;1X?zulIw zY^5bIaTR~uC&=$z1Xe?J#-$CpnKDn{bSY^#>zHnlnv)wsh$k@?p1|FehGTNMR)bO2 zsaQNiF*u~u(H@^f8y;e|^kj58u{a|fs|hetV)40s$9Gk$wIP;>(oU9XM^i`U1Ov7I4k24NDeqxX}@RR}>}06b;hQbLIa#K5VLO4cTjvDV0536{nZ>n;My&lR#O`wc1T>iLXD?HX6{!8*3|UKh{2!~0Pg235Lead+bh*nkZ3 z6LxA|PZs+}a@8kbD*rbFTc#{}#$`N1YXY>-ovh8pv_kB_`b;r#)!({u<}I{e6N8Dy zXzXrgYL3=HxukkoEaO+f1Y)eBD0x^V<}6M%fb<%*9wJCP3Po3?+b_$*G20;GYUwtag2CvD&n8gxEr4RB+)U=q8gritt z#~5C23P-jP%S>7oviunL3O@^(EjlapFiN~XB-Gqw05eZ7qeW+Mf&ZvBnwT76hgxTn zuCrMzk*3=wHeYD-wYX#zej2sOrbf_`acPU7*VlHDDeE&sX}jf7gy9Eb8hR5GT&zOq z2gfI(-_Rny_7atx!pP|X(NNnWAM286i6P}EGq^Jyx=J^mU_`BwNhPBZviuX-{r-93 zQX)^ZBsOCi1DldfT~Zmn%LH$zYuaeB&bK18b;gV&5DNWT=@e+KUlqWkMhJ??yHZfk zKG@qf@j)-C-egJ*g|r6a)6;xm8X>w+G`yo4nI9GTPM6Tgw>(+VLc>$P2_TE&HaCsp zT$qnKeR4jBtX0sof;{T^*1Jb<76Hzx?VftgZ%PfOzsk$Nn+dx(ilI{*n`!zpxyOIs zS*S2KQ72~-G5>t>0jU@Nl&#wH$s|lQ()Hl9@zYI!SjA4*mJ;Ti6~{!C%vNp4CeACI z?XW=W|As1J`Tw3O`mufWpBVhH{G^Hi_11sTLo7e3B9@<25x}kC*Y=-O5$jK?2w>&* zqn-7q(I3E3=-2C?-v`)i{`LCj_p$!`KERpuU)z8EK7fVHFW3K1=%gQA`-?l9w6p+o zF-8C#L5B<2>;0u__%Hq>v;eCTMgVU^LyrsC-UIBR|6MyaLlbiYHfm~WV=D^-YFh_O zO9NYKCo5YsY8?lC6MH*KD_2UrU-%&%J-~&DrM-czrH=W3{zqE_Yb#rOJ8COet$+Mi zEkZha8ahe_DpoC919Jl%I|FJf2YYJ=dunwOV|#mRJ2q+~6MJI^T`D~*3u-BA14~r{ zYik2@6H96i^5VdkY;)9V0+rf8E2E_;K}{(GIOT>7RC3|Bj8!KkpM0 zz)^8{ygOV26y$l z>EoX={64N2Spa4=|3*XZS64=n-+4gM{mGT_$3oz*#tt)}b~!B#Jp#{9mp=DvA0?dv8?|wRf1t2RU4Zu(m7l391-e&+B|2+oOpH}E} ztd!#Pf2>XL>+7Sx7&yNd2Vh3a!t#qzD=jNP9aa{=c_M&1^gmnw=g9LrZ}9)b_>YO1 zk>>aC`nJYWB*B1a^q<}ZP+n2FJoJUe->*XQg(w4RE=czdN|nO76xhzOs6zi z%atVwfHOT(&~fMCM@ z9`()PUhC_`VUCyI@#}>L&I*B)1M1T0>x6w7TlgdWj7(}~eWYil=A-6;K8Dik&Z_0= z^UF?)(@Y;bcF&JSlk&13YBGum`VR_+> zB&v)8B0z4G{vga6gEdRlB^{8{j}fp``%bc131qniXZ7WB$!i(Bsbv<8^-YuC+?W-c z-~dydSDV!w@Dke&Qi*F{B`Wh&<6K`{(Vn7hA>s7=Eat2%r9h8#* zrxT}BOAGa<;??hMw1=O z1IJ`v)x{QdBv{hx4cnNFDqK#-GTF9ji!Q$3%bk;cNN@R?>9FkDkvVtPs&TtZ&T$9$ zmXe^N)*SXadq(s&lF~U{)1{}YORM(R`zRwk64BC9l_0svoFZiG9Wg1!pv+lajEnn4 zbPc%YFOQi-uoWYum70eHgaJVjkFXjqIYrU@QUN7eU+LsJyz;ZzV}|bX%v#3y=W?b? zBAq=W@ibOVdoQjG`|- z-T~MR-54<-5{Au}Q;v6vs`!vIZeo6NAqklbA)H3Ax?4y(rxne!7*l{|@g2euR-+_Q zmM(Gw1)-BQBtJYJs!gyqNZ2=ASdO~=T@8eCKsQvP;wi>WwMe`Z+-`vZ_EM3Hezl+k zPQA`9@MPtdS2i+Q@)O{mlXXVfNTQ^ z%ubFnfBsae8M#s1lRP6cDIuM3{#J<;$67ca7h$p_bNF6+RA#fsKAt%P@QcOhxfDMn z#>$db#hy8=y1I4-KU=|~RN&7xe=&Kr?R;#a6dAH+VXqQ?KS30eot! zDNEN&EZ-VvsHvV2IydpInB|B)$7H#4(gYd&Jd~xEyc>~|L=q3ip~v}?9F3-i){+9k7?B8R&9fph8IGCynXz?lxN8Rd6 zD~}#Aa!x}=JQ5#Q`c8QdE4M`l0wX1KcPCcYFHYcwQ7mmvbJvdqRKf~@XI>F@SF((= zN$%+lvt-X-n9^F5oW{-HC*fO-8fG6NNO)lj#(w@KdQbS(a({JuY9mJR&fx zYw~I4b=-LN23;O*!oex6M6RjSZbm+tn7y>$;xFGr$~liI_I+c#I$c$EYOW@BWXZH` zdAcCb7Rg=0x^bQgz( zzJ-6Au@=v)m3DQktgr_R(jdK)7<|aQ^48235=`;X*?7Qi3An*?XDn#3a`O7EAFexGfSBIOjBQ#DU$gGW9SshJ3`$zeeBA0UZ9w{w59j1Kvt!o0>1bZbHICS;b{3>pqpi2hOlCM9is@1K%C22TtxDh$I@n$Nx;@KZy;klXNUQ zV(LPyWt}w2M`gYjUo0K0+e;gc%vB*2vQc6IK&Kkt04iG$GzzeNdOq7`qUsII$l=)W zEu=QWd7uq)j6G3f#u~^I+8?T39W|;}I*#h*eBWH%taUoIu>?m_{5`S$d@hPP(;8h$ zoGkcqn$FMt20yEKC@)O9Myn^+} zUKa%^x8V1UT?VwXWWo=mtrVZ7f_Zi6@|bfyeN9WrnsQ6u0f8X7fE#XgzDH3*Qb7KB z-;!h%nlBwnN&&a)atXZ8?YxIh|2p{|(c5P<;0{4QTTRC0IKD8xRwrI+^P z((b{tFY*pXBwioo9lVe<14@aQ_mT=rea%YASPHKM9)bpp!w}d?tQ(V=-t&jF zN~5xqJwTL}l&+N_UE*(O%?Iu-_7>m5eJRmO4 zE%nA%08u8v9R!k&=P!k9z(nSN0n^#YvyjpfR#+cXDk%LDbgZTzaUoWPZWuJ4TN<)+ zVB=T%&Qqh*)$}4sSU~|i2=PPBN?I{L3(|(=7Nr(ETmc1@gZ+(u03SGh*$rdy!HRS{x`Kx-$-I=-XRwpV z5wnRo0e5oq38hYC4-m{L_uP-<0M$@JLs&-3MnF9zo)n{nt{4MY9#DSiQk6IP10;(r zR7|ln7)G>r7^hH#)S*nSv+2@m(v(uuwZpzyZivZ?7q6BSr3b7BA!w_nq?SuJ_dfZx z?BRR36YuwZ`65=4g(sp=k~+1?%Q7ADPpA>GS@1KNod#@nPa5aN6zkfmF&7r3mw1NMWf1MzN!Tr1ErjNLYRlX zsQXkxL!*=>D9`e!*F{ABi(vNQmPz~gRcwdQSU>F&9P1t{qhtr5G3x6*DJZFsh5Sh= z9&R3FLJ)Ns*-js7?_Zu=kO)EC7zmLMV`4*#8lF992@}+`HaR)>^u*XaVq;&1sSldh zM0ECaR4bLU3`a7{xD~fT z7e;ZE>cMW=7p{qH5iXOxqh82>wNIFSO6&Bg(z(Fc2SJlzH`-Thcy4Bz5ejqco|6_w zzhq%>?Os~ne`ev$coI-hknt2}3F=1EJoi@e&|5pvFFVr+9a&boQHxkUb8Bg=TU`}M ztHA2#5}mYBLZ0`tdNZA_oNFPga;;s=avPow!_0CqS~VenjMh%tw3FtG?*bnJnekxK zPI`mM_*=r)8fIRfRoY3j=)H5>N+V9?4zfZ#gnQUEbh|Tb(8Da`uq^I~-%^ZXiQ&^r z)Sul$+?a(Yw8e4|tB#t)l|$_X&?Ft7ky^_Q&yOL@qJ=rFZ>T2Wr2AOj3iU%&)38Q^ zT}j5vh0B@Cgv&vL^^L_rUg1NknDB%fGNeuzOCaSMydW+D9_*Ez z4%AI?wZli*fPhpq8=-PLN~{dTw+bW)Hs?B%d-O}*WO=KLzek0A&iQET_DeI)NsSKiI95^8HrV&;v>`hY^`33G| z{{k8>H!t7=>N4WL#w=TYmG2+&g{(LrUyvGpHXO(9{2)v##pngvN3qgVx~CbcVjhzL z)N+9>SHpxW$zZ*WMOxF0YpJx-W?HN^u-MGEzE9HY5$~RR#xZ*?lS@6-BEVghIf~@Q z!4Uz9B&VI7j0e{hyzJ0Dwjp%|lKET4$WOK|+Koc$iybzT7XRKewp&cFeworCM87@q)2!uHqa^oQcE(qcP2}7 zkHv(+J~Ev#D?|pjwmN0*t<>h!*@=$qy|>)dfgZ+Ay&3_Ef%jY0g$Zx77(io*SqjZw zjx#*MyZu6giJj}?yGLUm#UTiYh}|x8wPfLxLpdR^p+5mWXA2xtJb_GFw)SyN>g?@r znTfhE!S;}RdN|pX@1b}3NGv~rIQ4&#_tpVXbzR>uD5!*Vw}f=g00R;Vk|Hgg!q8pP zDBUF?sg$IE0)ljhASewg0xBYcbV&J~89)K`zAnAL_j#Y|djA48Gv}=HJHNeR@3r>w z@>Y4Qm%DoBWswU4BVFR+j{IE8T!d5#F1GNr>X3bgz`26tNgr; zbR&~~yiG|!UW0ShHsyBkRM2kNJ3$qzAxk@rL9&dA*tM+lLOml^nxY=uqRHl4644{q ztHX@$G-piDZ03%7a(a!AC?bPChChB;TjFKqs?}e2v1VzWotp0RnyDE>sY+46%<^+^ zhNiWboYz;+x7J^?rj|bG4((QD4o1v%O3dM&5#YR5K1ro$0yCrd z(O^$BjY^-8TJq*%P9=fjRN|-A7dKX~yP+_D!vAtLueore(iVbVfLwS-II^Aa#;tqO z*TQsNq<3;zVs8#9*2GfkggZ-GgkknVaz3jL6bzJ1Mrs$~duk z&WpcVDEhT@xZlER?N%3VZt~}4=5n1I7K|%({;rQR-YT<7y>s$BaiP1{Hm03P_3j;F z9=nh6q}FOs0?oU|A3i*E?Wl5XwfivLmTBhEsluvI)_-m0EM8M4c%UCsU4aBsqaoJS zG0*Heca0(W$lTB%W}cpWP?BHWrE#NxHNGyKv!AuKdBdM+%$sF(v3B$NPHn3wS;y4h z?fg_>{4wEz>;*%7a@{^@|0<3mw#?B8aYlQ&JnQ8Ts&VoBy{g2Pr<&H4?vg@AItCxj zrHwVmsftzSM>S>9#18V)TLWDf7&mWvH0H%@D!X|Y7MyZqRyZ3M%cyn6-?59VTFb{e zVD(Di-1DK>Ek9L_%*L6OY4bBByOeIZr!U^?k8-?qTZ&bUrC%?w{MPx4apdHmK5g1v z5O}q4;k;;@Ir>sO=9Yd(8GZQ)^M)rZOC@F5ba}P}Ce20cw4vn#B)g_XrUCDuo{pE= z@)P?FciQ{AZ%ohdCPh3wNyhjhoC(UiK;oskw zG0@-SPboH!{B(`%9U0G@jqg?V)r+}xPkj}`-jEB5r z8Y%FY9*^wkFT09KQfn0&IgR+ak7cy$o>Vo_b5Z|!E>=TDa$Pfmy0F|3I$i2%0o}(hG>=8 zN=u%!W-GedG~+u0E-=1xweLy|r+>-=eQ68dY;JU~)>86#abL5NmA9XJRPvrR#;bl% zV$G0p_OrYfi#>SWG@v9{CGV=@`G*tIV#HQBB|L+}rx{7Qnpl>q&c+Ezuf7$ME>k4W znjv>_u2mUKYA&d*74D89>3Fi5c&SROrT~9y`ts_)3Tun2T<4Ja9GRmYwYm$sqL!45 z-T8ru{BRBBKu3-n+Sw#^2CveuTdwol3|#3fCExBPd(RcB?O>beqgqoEp_3^^(WF|G z8KIl$L2{C4pmi`lZu{O8Q?NFLaXP3qhCleRz$KSB?!w&rge>&SIt%8{gzjfCXmiC@ ziE<9nPKbLOlvfQeYidgy@ntwCx1>(Qq_*WbzvBoDeKdAU^IlwNZj*z_iI)#^3+~0c zn;36|lUUXix^}73-RIar7uLVj(_09dg5Xf2+rcdjBYD+0z?HxDi ze}~QRl7Xjt@QTdn#syrTGUAuw^WrZh&+$5IswM_$3X^qN;$`2hXPwRV_(ZH(GSfLV zCNLYFn$^z`#_ex@%l^XMpeI=g(uyRw8ulL5odfy}>u;NK^5VktCXFIHM=I;xkXIsD zs}(Nc(Rnnc7f~=)+06-+TXlt%hWqHQ3|@YXJn|~hSy7tnm3x?ttw3ucjgUjrc zeNE7qabD(qs+aOx6YrT7jWJ@n)%Otu%c+YBl8GcQFOLL&WUaeN#c#Z6_nETp>+-s= z{PX16`|o6Vv_-!ny>*sr+*m`kZcW^sqkCCb_O7)poy=VfO^5|r;(ivd);$JeNA%k2 z03CMim)`dU^Y1;qisswSPA(?g*BIJx#c@Z^_dG#oZN(x-F0<48F2fHd#N}Jd)h9$CW<;2uM=k=7YeJTMhvPG(6oK{TBiB8;SfNpiwuN z4=AuW!XOYVQ54Jv0uC+wcQA-X=6J#aYy$sH5*@+l8;K5M^sgY%j~M+%rqp3g1QhOY z?`tA1SRNtpI~6w{CvYSoOg;TCo@e_fUjD3V23`+xOb@|q$ls*U5qMyEKzn-V5IjI0 zEqw6b1J7^dOTqF@fkbN_AYGg1J9|L9aQ5(VbNxH$LnCuE{~84MV*VzBjzIK{K}R6^ z7f|R&hz?~=DZ{g_|5g$ZZ4Nt*de1}pADCkYN!Uk|miPSB-+1HuN!Z^X z=SULv|Apr{np6&g``dr>d4NsKgRDppACLga2j&3gJ0~#7d4T#8ZV(lS7w}u*qyGah z=)bJ2{9C6YA1h@7$|QcnVjMyX!pp`1;^hTOFOHzavp@Q8Me8@**u&i7=4JyN*W=s* z@v`y$tGV?X4($=NIN2aSatp|N-y8k6a_e_o+e0%Ea87_W5XZR11^Bjm+U#F~7UXC- z2?)Mg@&{TTs4V39fm>WauaUjce=AzQ;rJe!iSR{6&FHo4o1vo8x+U$QZ zT8FB6f4+c2Bf|+kS}qP8@$g5skPFsBW1mxpQ385sz(@aWDE*H6`(01LD%%obl|!F!@2YWN`K~? zbAo~6efDh}(9(yKn*$8&z;JRw{`dRle}_vv$NVPvF3}%w2@IJ311^0>2{=0Tf4xus zM<^Zg#s5Qb90Zt}hl}F|V8wAyY(3_Say}r(OzxaGgC^N}9g#SW&K$XeYn$VB6-~o5 zC)HL%-Taxc$;;QeWmM!WRU`aXY2{RnIJ|A!Zzs_9rK0c56UOc8qBt>UP2tJPQBv$K z>OCfVsXKJZ=fl^6+@!FyW`{hX7jiN|pH~oVD@Wr*ZTM1BDGMAmZF%_D703#gw--KG zQ|uT zwwEHjc2?(iH?wb_)tvm=nN2w+yxmq5x){;wyT0<~Hs^V-t-INjo?8pAG08sSm6Irz z?JD<8nMuD;x~CneSi{`W7O{N<}tK)kGlcCv6*9oQ@YnQhmSCh)bZFimj~^!idsi z<$IT6SBAJu)^1&cD%}(&!TGq0Z7^Sg|Hin^s$i^tzk#qR!*% zLZ_}A&UMznhyg+~q}c46!hKMsGcR8DeHGkZ6vIl;Ywq-t>QW263*or2O z+Xl+%U9Wu;{|0_-1=7?_Cwbl$Z5uJ$A=N7$Ikqv)H{E93eMqMt<;dS-A8*(7jsK)4 z=UqzrK@?q_wD+965IzaMj59Y*{sINHtut?QjM-!a?&j^wO(eOQd|gEgZ^xBqxh=>* z8RCn{{E)6MGG||$vNbnVlO0oH5fXSVtjRQn90H*WSbwF(dAeCJtSW}#tRvo(T~H+h%?j&Wql)0VV?(IxIdersNC^HHM!6v!ZivG?Q zPA6;=AJ^4UevJ)Rzo1yTGv{iTi{8im^~@8CSrsQbBNkHar!UTFPv#_+HuTiS`J3Xr zdH8M`ZIX72fwV&cr#0|`F0WlphJMHd&efz8Mn7jRE(eBJmgiOkPK3}F8980rK^llw zw4q}}KDElQh6T>KM#xet!0gP2(Ml`66;-RK(wLBNLhn)jXSPN~=x|#b?ftHMlB90u zUz23j$|$!!HF#w1bHd1Hyc{bwGTNA}j$A>VVKF(P!3;G(ghm1V5-tRfDKoi7x~YDM z;iR@pfjkw*q@HL0aYlo-84Sy{v`S7}l^xy*Q6g|&s3^t;K7hp!q!rInaW z)fp?|V!hwmq@b=oi#K`QD=kppp-DecTbhTIr-4P4453_jf!UPFtw_BCuql?l36n^k5S) z&ya4Mffu0MaCnjbZcyU1$3_S^zdeHDtS@h{C)azV)Qw6;N zt}`>ID!EkCE~?k#L-A`FkO*#B$_tCBFGwg12FQ44#N{!3mcp*=S9q8sug5wb{1{bt z%ttJ+-?KVGN(xLPh=?7hs}ws_Mbk`F=UWN(u87LJTX#i(jgiw0qhyXCx>sEo8XX;T zlUWJ{f<6#FquN9#y(vZ(d|!>QC3g z*V=X&+*qPumCjsy>+vAdS81M^F-SmjXIpTXG$!T)w^vYRsQXKyYabP)J~Fr()ol1* z(gfIv*cLS$&pM0-zVoag{>{xcDucjAT<)*!G!KbN4CDLdk6 z^K@5j5jiadYNhQ{QHY_%%q=vd!6Ybx9V>)pJH}*!6Y~b%t)d8 zye~pml8S^cr(?FMk-ZurwPkOj%C^|zb-Zt%xb%kb(@B}9U0hlsm^NBoBH|Rr?^su| zd0ou%Ffkh{p7lMDk`5Hc{aij%@&JEPZ&G|+lAKlZAz{vYlnRjc?s* zA^QYyN-A}`9LWE4MLC-7_62``o<~BfZZ$16qdi|0UGi|`-PTUHJmr0}J45)Xzo^S9 z$=^eBBPAev4KaC@vCNTUM7%jABk3+!zWj+@P@{u;vuKq5nMFx#Que`y>!r+J?g5nw zx0ot$a!&XV;JYD6zn8z~&EA8m6Yj$q^ujZ<2rtLRh_*IBW?B#_ue&$`t)Hohpy%bR z`RQ7jg@rVZWrrd;Us#fGb~7E-9`Q?Pi%AQy7D4 zE((7oms;9I?dGV;K(yHB>BShI0{X?gA}fV#-?Z=WOs4AgZQWuE38Z$zme^!+ciGdM zLic5Xx0HB8K6|{06Sa=mF*xDIohV*~Y)+Y$tbyEdjTF@ICf86+jCcl?s!PeG6;b9V zKj)f%ve&Dpetk78xe?G8`ybN~0rW-M623qq7rozs;Z)66;#;kq0WZ?L?-~2z5jL~Z zRT7`m_Y@Pi&_iP0KK1oujTN*CjT8(>!MoKbR-dnXRI+nCpj;$@5-B>5&9+fwgQ+Q)T=eb@~Ew zK00MYRS|rfNPInPh1|P1dE-4Lt?~Q%!rYH3*;O@-ghkkGclPSIDuZ&5pxZ6^tVGMT zney!hzY)v63c0rkVaWa(=r%Lmxe|2Nj2Ey!5Sqo{l3z_a8_&Q-f*=4P^2f?fnpzyg zV2LJ5=ztkdKr)4#6D%jNX3tH_BeD-ewPe{B><;v;e9I@7;G54{-avVBWgp5Fy4~F> z^yQ=mvwca)H7QSWA@RTEN?9lEd{8$?hC6$iZ)dn8?go&YODD zKXox?@W)@o+a`E@Q8kenZzBw{q&X2{ZK9A9v?}VEA>3|VtLJpS?WQwTNQ?rxHUT~= zo&*_R;llfUrHs`Xo8UM@PFoPX$eCD&jgrqb%Rv)y1vnjEwKCT6LJ0!G(9$&2i^);-{oU)8Si;Yw}M>}9|{brK(T8p+?TVXp|{up8acXwnnD)JI__&YJJ zVZd%V1N39x^qKWz%(&T9Ems`KfJ04K~WWKp-In6 zNPFTLuEt6Rpg7$Q$l`7sG`cs1G-L*tuKVU1NlE8W%>xi3ENK=y%QvH{(Fv_rGr~er z6ooIwjv{I0Uah}GdQ;4gU-?lwtyu$f>n8iWf+gJGmyO0K&FAqjc0|ltt>NcAv+vQl z$CH6sOxdqcMr;`+*r&%sId0a?IL;v!LCtaFtP%r@+{IUKJ=X$1JnStO*9zkpJa zaOcuYBf5OOJ_)^=GD9(;ZD!GT>^>wn=H9?cBAOIM-yLZ_f4)oK`?ZKg>$u)YFqXYH z^FtI!c<;7hl~#JO{F%iwRUqSx*^^_sC_E zV9{Taq!E)Etnh|dH(l?%*!M~f;Mpj`qIc438j7hgBa?>(9+?k4k=LGzdj*d|JUL%ZQNeR_OGU4fi|SJJw*1Lb6{+8dHSzEJI(eXE1uuGygS)M>9Y-^h^rT*Buw7i-l*obOemINf8;z(-XU zC(A8Z5MwQ6U}@ew7yE)Tlj}X!>o8Irn?Sc+2L&=%=%xpnlr;7WS=Ym+E+d`yS(a?* zA}4+z;vV=yIBBEVmrtfRDX>Qonh(ai;cdRi2nioeZeGLjbG&$y{-oO&b9Gl(XZ>|9 ze0!^YOnEvXMAb=Ln@ChWg)|hu2WLWNY~Blvce>%-#mU`q)@2oX-(MBnW7rs#(pxLC z=<<04t(l&ibe7Ul+5P+{!w7CQj1v_abx4qcMagaTD!>k-o@f@d3W}&mxsaMBR_B!3 zy6G~kOS-dY=JqA`G$Mh*X;{=`Mrc7(I7;|EY;tc*Sl6n{#GTdo6raPKwU)p>eC`}l z-P~rDefgWoO}duJ)sAy5`Wph+;|uB}l2E@B0oW24%43AxbFiAzMFeNm8$23T zH-Krn7oQH9$wF3Z6G5XiRaqWkiOYbIHR&ePQ_5*d1gVUuo(-^RD4W6~YlH4ir_@~5 ze=0mlyxt{I-KE|A{JOfPlEDtDMSa*VUfI{}=vyaz;&9#07~z$m$zlvmqE(ZfHo(c) zk<`uSd*4-MCL62QRyQl8Lf6H<(XtIq1S#p3mKaeikeYXc%HL#8T_!l)!!DO|H!rcJ z;WktG$m!USYFD3blN{O-k%30?1{f#>A|WCd3n(8E?OY5GXp1~~^)q%a&01bN? ziHwfAp1P)>as1_YR=1%72N0Mbm_@1szEt8v%#034)3iB4Zd;(sWH!f zML}WS2&0=!cxkOjO&#*SfzpnM5(hP0E|4}BAC>HsmaW=Eh>{-mbh%kJ5qd4dDIc|y zWO#(bN(_-itHh6Bp*WqSYVw+aN0|Vi!MD_wh;DyT2zGlTe6v5?YvxM-m)mn^-?qiR z@1(dwK|jPwaYgZ-A+wz7v`WjmgH(F7R@zo#qyrl52eWbSxw6e!0nh5nfC8C5$&vHCxGIXiV!2?kx+IDo$xL{3NGPTmt+v)(ne%b^ zaL4k8$Oxu{+4#>-r3iG2nT?$sZ>Y-F$GRht`B8fH4(Oy?-B9f&Tl!p>920k;%5KWU z$>}|ka%Y>#8t{`SCVg0xV}9-_3b52Mtn>LP3g>9VO6(GLcXhUVKZ;WkeJEe%Yi&Nn zx(Dt8H?~-xO0-;e_RdyA@7Y2KXcLa?LPaK^31?B+xQ?%ZcjEd^WXm+>BOa~~Z~HEya=o5J$(TeIOUy=CB1FPxSHphj&6St^ zOkj?~L77W5tsbp8iV#&-J(z$lAJ3xv$Ip5EU_VXfe2YelB>>gbsuUtdrFAjmycVj|x>j{zq=nPgKU3m~~Na2Ji zf>>@trt(Fz?LCg)YJ8yawlDUi)o0=mf)c_grq#{`a=aD#{2oMBe0mN^&W8b1?lMT@ zcWgdU1GY6suEwJE3E@X`x(tA19RSI6$~sL zLxh-PlvNmPh-}{#Hxgz)Pk%0F7Jx3U8`;1xh9rS}ehm+m7U(-wu<*VLCx=;f>tU@1 z8?fr)G3gxHQMAy!h-&xxU66t7BTb8~Qc6dh4jNgPi4(#d=WP8TUWi=rx8ll3!Rf`` zB#Wq&=M|kbsxJAoR0@swtmZH1Q?F#_VQ#nMUTjb}2L#cLr#-QH@XI+)9K7}zL%N?fIo?$PjMF_6Psz7>*2eod$qVYB7aCZ+f zmt8*v`aEZSE&Le~frcBQXeDUAXl5+&g0Ho ztyjD=RPf?qL`SVz7={P;EVsGCEDctXMuun-a-C6F_#DG}9yfpKvv%{r>0#=A)dw%q zT!vu(22JXeh_{X5)d1fUYqqA2(l>AXLMwGDaSXt~-#sT&`x?zGGZ2yXAB=??W?l{b}(YhrR4 zON`UtSyZ2M)~Up|n_w<~(`RW}Cu6qyp{8}?`64OC?rVW$jK?Q*At{>?0he;5^GUq; z;+ArI)hWeuQ=VF1#GxPaL|Ynn*)_Wu z0a8db*{FFm$n$FM#CassPTVi}E%l_Q z(aH^kX*nAbUZH8BQFJ=rh_TU0XD&Rky5SK}s z&DS4{@ez%rCv(M^sWX~iwwHd9)sh=S(L_zdcg93^B(tlc=+VWjjI200K9CTOn}9sD}SD4R^zSA(eCGK{f zukSvk>?rUIsC8W3@@CtX=gmHwBgF5AdwVlHBm|Sv-k0K zn^V|IUu0aS2?+OU6qO1x-)3-GRri}wcS|F=FG(u7IYA~Vo_m%yt6Sff?GZn2rEE0f z{e}EB&Tt#;84`(#XvZ*`46rzcZD|Az-NRMB@W@$>*Dj26?3QH2Z3YO_Sv=t@xEf!d zsxH}+F;>@nsu$hjUiaCt(Y_x)3Tdn>>f=xjdU>Cp_|+F@u-I9t&Br<>VG5#gqMt8l zR4u%|9N}g5Y~*E@3P`FU>7$+Q;HlT10-8nyntcn5C6|~|KB~O!ze7JJI+p04kE_~e zBly-VQGq0kb7%Ifk`kdnjlNkbjrp8N4tFPnVsSQWkY#(Bz`gRRMKno*KDlLZF}IYk zR{V6E?Oe^PT|A&CUNSc;357&Sig-N7qiZ(m#i4)4htC5DREYFmJVxCK0n zcC&cS$ER{DIhCQo?RzoZ^ft|im=ld*8@c~FO>LBF;sZjP z{<>+Xb(VJD&^33R7S6_8SE2G?`um91@88UjKS9>$7#+OYW>rl2@;<6KWAiSdP{u<` zt$gz3BCacU7UR3LyC50lMdquD<-OfRgIPL)^$$ay5Ra>nkz=K_b7{mkLm?$quY9Am z^6)=&6rz}FlT3z6OU0TEnZ?yfLYhgkObN=2T+rqrU!xoQ&EGnod908~5|$`%%P^^> za6~*vjFdbvceK3#cSIb2NvS+cy2OSwKP@PcS=pSt(Fv!$hUQaWc4fT&c=2v&G%K$zp;lL0zdus#xsT+m>m+lLS{Sdk z%1?BtpKLIH{SJ~!D1dg-`m0JGzCL8|QTaB$PSGd2xn7=&9P^vT*{N1x+V@`szi0IlxoJESySuO=SGUzU?bXxlgL*IStr^()YmLUt<;QI#8 za%mP7j4p6mdB!X^We8EyL%X?s<}~b4ha$M%Gf%!k6HKrlXjrP+Y705t=C$Ev{dB4K zCneNeKh%W%*Co_ku=I#ucMbz_?Uyiv_Dh&S`z6ev{Ss!-ehD*Zzl0gIU&0L9FNp@h zuTKRW+zq=A@N@rq;Qi}?_pb-uzaCJ90RJ4&@?r1i{`J87*8}fg4>&V@@BjPP za0Wko9H{Er`?-HT?)~d=?_UonWZwJ#{`I)`ugATAJ)ZsR0mX&D=l+kBV#A^R{rnvu zZelD;kjVE$1-{0#QOu3czD^sJiJ`Iz=_|7Q34wD zz(@aWD8Xp@2PlDnrZoFp`d%r;%L!rQ`d4u2SXnk)Y5fUGu+p+UE*(M%=#RBG`cLQ5 zag<;x^AAws;9%p~=hFA=OCAW2`uuO;5+CSjeKy?S{XR-Od_d0bK9>%o1XSDo8}!l- zDE(O`FAuD&_D3#(f#yg50xofJ9IG&ZJ4=7SB_1GW_eU;q1J!l^0xtcC63kWm1C)T{ zGxn_6;c68g;B1>cZS~L4-oMuZlJf^I>W9eTKNPxuug(Cv5CM%J_buPI8W!N3js4O8 zH?V_+1i#NaZlLGPfuGI;D@@?#2Ie_XcK46+)Bj7}!Na^i!H)Br_kIXFphet2$$S5A zvHLTho*O6-I`HYgM?Ty@)yF@{r~hxU`?H!oZlII$fv0~MJMMp!r~lt#_heY zf%fPJ5yp3K1?U6*FODz(^1&E*?7$}Ys{9`?5C~Zh!i>WJ0%tet`m2x$+t3l0Ma{uc)v!0i1QfPWTs zfPi)0AEOQsFq{9qQ3pUi06-qjqYK0EoyXs2AnfS9A43li58uBy^!NpUe-?j$z>tIZ z&UogJW7_NLZW_UsbYPEb25YdaNd2dF)py|o1mK(=FC`?GKZ1RVQx zunF-!%msnK|EO@|H=+8o=;Awn4(}raCsY2TEbD)U3UthigXc#4fd&IkgFmpLhgbz1 z7WGeBwEIn{{w!kP0@j9qw3b}JDL?-tYxygvM6E4texa}aY#V|LaLInOjabIHh&G*alHl4+4_CG1>^{Qi$1^WEg-Mz9~FK60bIY~ z>2q-c%V`{(JP@G01;>Hy0~)IUo2Yyo5HN7c7Hkpee=64e#qrlXhZg<+!%kB8Kebs3#j8xZQi)t0 zDH8r#;qJ1Or0KQYv$VQ1*>*zEGMD?!=1l$@SCg~{>ph+EUK`7Ig*>-b6Q2&!e0{Jk z*ZJnng%1?-?w%2MS>v$WKg$ZAwZ~lT&epWwUDH~=ac=C+g%qn!!Pb}dADr9@g|~xK z>TEI9<|#kz@D}m$G@n8ovd8Z6TyIjP^xUY}EXCi=Zz@@Ac(U?N>+_9Nl0J1Wtrj&d z^wiKa_d(8xyY9VDwoSaM7H^hAZr^xHFML0~w9A9UZmW_^?slri_~f&}Bd4;uY>%&v>-XN;TYtnKY4g!pw&Z^ku6QZcPea5oh6u~b zJGg=YFE-mowQsBG{L@buM6&JAk_B6Jk)Zs>7BfT}r*8|^JPz{N_6g%H;Uy|U)|hpD z^?~tI3I9aIdT04Yv6b&sxmE+7>iqRr?xC#Zt1f&o0Zkk4-#f3>x*ddD#TBC!cGuy|bP7++i25Yv>VTKs1d3RYvb_;D}=_L+7w|-3ot`0Qz%);Xvs^YUgI4_ z=ITcvSU78EA&-C`e=WhX!H4m>#)EtAbCIq*wCVA5Yj(7nSm_ud1)t2lMFQ_l6m=+t zM1G*73-EIg$Ve&RpeFgKO-OTAj7?E>YMbzGFjPpmsrDt&rk*EgTcg7q6(OJ&1|o( zbqVBg;!&@qB&VKK-_XNpicYcU#&9rmNms5+AU!>oBFShL3PFCvugk42Z?|&tUGo4b zW_UE1Gg>0*19q+6N2U)Z_gZiJo{Z?KSFv$07&Q#LPy5bxsui-<@!D=)-M7M?lUA&Q zEFBH&DGnR;(`y#l5|q#B!G4Zco8stl@h^$q<4mD)8y&t=-5(j_>*nl0mz8Amcr`~p zStmM^W6q1m5GC>j|0uT}2pcQ>Vsu);6A9D{7WXT1P`vr8@sejP-bVX`*(yKcU<3;XM zaN?y@kcE*&(_LvKmOLT7_7XoOZ#tjB@FNKx0fJ3K$u$h=F$D)MiPj~Y1V4!_6YB@2 zoghmy4BUa7?C8%tqrKu$nP-vn?gyAXD$T7qd(*0i)_9bGueUXlPFf6_f136SGqL;? zJbG%2SP$vj_aB2Ls>)+>J>+oM#tR%cpd{gs%QMft$%&M}T#&Ih6~29c4Xos^sH1dW z+9T@SJ$GV8CAvWVRP{|-%W$SAmqit%O8gie$(RPpJvr4YsNr;hxV=%OcWIXLL3iSS zp0VmpYfx!GnRdquNpvY1Q;$+?hJ+R**QaB88sUl>)fO*1I-U!O&}_}p_!rpEk`4&< zqN-AQAPp6&cQ2->1(R zQlV#SK|Sq}kL6dC*GBJO^nRiAT51p@2(6AR?`w#!(%arDQmF~s8^)}+@8_=scHP7w z2@bvKAn8w>ocf7KHU5f;iEL_GT8fK*Yb3J4tkTK85FKYQM@@M5=qfd>KIiCmu4JQ# zldVu`Xyi&4dY{4*Y-!1uWF|Z*$<69v`HxoUqLV3OBo8Fh?tDOrQm+0Y8Ot@A7ek$^ zNd3b9gII!J^98b8E~83AyFMjQp|-*>o`$2hkm;KXc*Ju7%X(@kx6{Le=j5yEwTu^Wr1Eu&GsBjk(gmIkoBXIm zrMBzZNpCKdu!zOSk4#suYv<*xp{%HDusmqJs0ZSWOm?6wVx1vzc~V8Gcl$iHgippx zgNM6=myKs}bJ~o}*$RxrEhDzarmHci`3k8dua%`5 z&+HHn5nfx(v(TxQXYIE3q&Ax$#|bt+TFw&}dF1a_&yTTG6_?!T=%wakxml9}$}&xg zx)MC*OEwo*d_B8kdRd-s+Ad3t7f%z7(|~dtm;a2A;Lz8Sj2m?vg9>hDuA#)Vyl2#r z9Whw3kg5ro;y-n4t*u?lGu~KfY;kAl#o6$?jK-SpA31DyeU-@z^9-j};=|CtCFpc%>+C{QC{qnh@kz~xbQ5*VRRISc}H2EO;~XQEI)~h7swXjq=J9} z?+(Jp%L4{N0}CkB@Gm|Dcu!C(Lzt%x;yJtmW$Iu7rD71ZwsNr3H*m100$RpUDMBrv z`u0$&OOA%74vg%Vq4o|`ntR0;>}u*7RGh$43JAgt0SZyLArLlh2oJ35o;JIvwWE~- z6_}G<+|&;E3Wx_@xWO)?5Bve<*!x3X-wq1<&|W{k!%`hy?Aen_S^qj9oV5`ZOg!LQ z_6M@;6@I{F;e};R@^AvRD7-+wyZvN_Z?bT(@856lp%vL>0iPQX4E`{OZw?zc2t)R6 zuH;}0P(_$ zc784-FKm`69v1R&aJ?tw-ioWfl>wB>;DE$`At}ICHVz298s}$3fg`g|ls)MVNdO-> zN|e3EFMD^lw)mM8@W=RpIp1r7zDdD#fY%;E`_l+G^dErX055ov)OWm&zeo6oj|zBI z-%8&YYWKG#|G3-%uWKo{`t=_t5~0Q$YbiT+d6AaFf#SjZn$wy3^^g`vKKJ^&Y$ zj5Y8wRZSgCtQ{SwluV7S^c@`S4ng>H!FhOrMryxQ4ZLum4p2L;!Fhkw;PSvWkd=d} zz6AiB1=PU7+72*f78a(k%_1sQ6Q~tnYV95DObr}Nt&FK0OrTVDPy?u`6O>Ba(Fz!} zw)zX8LBLey0>RtQ9Gf!gm%Tp@IJJkuVH*8tQpB9~Ep05I{NDwF zzv|-x9V+TPjQyT}v(M#2H-Z!RD8e$u=ftb!U0Nk+1kL-5@56b5nBF2T40e8$SydpiT0t{o67ss2y)zlzz2>> zA!}{L3UxLGyb-{2l(4gQw6UiW)wiM&fdYT&1FoSVjFwP)dnyNODtV}#rKvq^h5^F| zEc>oHe=aZ>C|-j6Vjk@SdcdHg(!=pR{FZ+-HCJKMz@~$p9Wei|0%8Kz*q+MN3YhG+ zj;3}{DkT6^C=A>0V(z`TzrzB+GQ+3)9+2NO{15sP{<@Fj3hYu-ou|5F2>AH`V1S;I zvN8f@?~441iY!vw4Q!;+S8+1m*;@0omvS@txR*T^C?)>ohdw=JcO03wF8xyvyFwR0pJw6P+f)^SO6;OJ7S#hTm9A>g`@IwS^188 zFz|t+Gx9&YQF+JffS}*r=Fes0=H&rk{KeZmY6*|LO<+OcD30)fqq4zl0g&dhr-haD zji92ixc(YUoBf4UAi#GA0lk4>7d`%V_fYu-V#jR*-;dFS6rld?jP!x<59Y&5!Hm^6 zD@6sUUO<-_n0%9O|LBY3?&?oMu>>X|PB9w1J?jH*BI|##3{DqKk4S7f(15L}03;E5y zI>FonK$+@W0{)8KH(Sc}bCJM6?inux%mq83)52l3gxG8}T9F-WD zIM#rh0$Xnbd?*R110dUhuMfEB`$T~I@>I$ufD2}90*_aYB)kESxVMb>7Z1V(oX7zB z74-kX=I|Z2Iq-p_4+4unEc9(`VDSFfdJyhv0p|NVIri3=j_Y_Hc(ND|&(BsH_Tc;l zUys`(z8~$8;tyUQJWi#$>S*C$3aBp_ihKUpUr7lx&SC@e@^Zjt?hh3HwIu>`9J54w z14nTLT5DSy+v(ewm>K|XA>4QUF3!(A!e0bLa90A3gW^v?15)0P8lSy^qv9O667qJ| z08wE9HOy!J#|^i?fsWZ7FvpK}M@HYk92Nmf0TbF8(AVGe4$QF^ zgQ=pw5RQwBgN^T}9?w1?zmV;i%>l#R&f{RgJyh77w)-Aa0EPmF^Kq*4asf#*e1IGH zqwBTz+`oEj$Lt4~<460k?K+BOpKDN7(a-j~a%(;N|d*VcKi|#{0V=TnEb% z`;pGxQrC~)JmlUhIbL^wceaxIPu8Lu6mpKg#4xvzhUw;*T zB8631xHeWeR`&VJkeAMu?b^sz*OxWnCm^GDB7_xakl{z?Ws3PYH&GBgaq6|AK|*fc zD!Isrt{BKS(_d{j`P|C>yuz=eaN-MA)U{&xH1M{9m)AtzuMr7=B$~K zyT*Z5C;QbAE8kq-eeLB$x{7bJE8#I=?>KSyV-VLmof zZWG13%n3D_QRcwbOH?>%>{5WyNR|9RUksc|W@d|#N#t;5o_0`OqTyX*E=PC)`r`+V zShWukEqI9P&ZTT(I7lSu@su%8=LokIE6vkf?qldT);r~;dAA9RhTm1!VG_kh+PUyS z(Is%JD8Yu_IhJ!$ycPHGPLz(7tlYndL)#=d^Nc3%?CfP*+-yu7lNdw_SBsQPrqHO{ z8uVo$Ic(>;-P7Ifg=ShtN%L-?q%7(>GFC>ADdh=(}QbI4Gt0QI}ci=b)KN9}?tBD0&4V)>06fK9VB} z-vYb(>-G_F$OcgW{i%|~na2^$wl3aC49Xn9krd^3VG41w$aZvK6*}|yF$rf)^bALi z&O-U)bmFmFt~u707J>tLlI)RJ4GM+$#DgsIpDD8kxapmp^^3oUBHKu6bN`tL(}UA1 zZ<+>>FL7LKF8pF8m*Amxzegz@^K_YmPh3DTl-WFpKr^4svZ9o~fPH7J_S54alI7%7 z<)l-qH<@tm`zD`i3`q%Ujy$>&~3;0l~5EAmOQ$}k`QM2cI1Ht3A152=z={b`xayV_59%- z3*47aAD3v)B0r9=X`UIe9qjUK>n@2H&Ym?NeA?uEgQ9b5;g&m*-20CLK63A#RNs8l zkn*aDc|)-_dH%yH@$z=JSa+yhRnz>k(T0{#Q3*@u=QF30)iEwyg~o22a0+Ppcs7)` z^=(iOMLW;t$Xw}cq`Q-(P}_6jmCD=EN{V))3Fo^@w&?j^c}f(!*S4wi<)&~j(h4%t zdYGRMNuzdb#%oGtY)wqd?P8=A7`T%<%DHoUVnj#P%JliCM_WGcDcm?BNqduxZKfP; zFesy}W!_&%rnADd?KPBMk~E7h=_@ggOat-Xk;wFICq_=WM(C?d=o`wmP*qbXB5JH3 zu;WK(mHkG2qL9Ji%Unou2|q(gXwZm%{j8J3@Y%Kz(ZsoP&oF%2^zXbi`M|>2N+-^d zEdFLh*53bJ$~hO+Y`x6N(FAGJh%EB83S0r90Aukn!yA&r_aMJUrLKbNDK6q7(@(Wxwb<=U^p&1Mxd9+I_MdN4f_h+FqZ&D(xt-Us0P`u)W%ZYwl79PL&857I^SbP zQB|61SkUn`%S6N5JXd(BGRKCs9^qyH;?OyCq#VRo2*sGTH1&w}SI_uh@q&oZH>hyN z8ZY^4BI=xaiy6gvIA1cd4%AEGnSnWvFUzN(12h$k2-H6Buo zbNin?QzuSkUV;@tb?yYk$@WvuB-4|=C>K>ZQV}3w8%)okq4d~xSaO_qkT&=mA0Q+l zbaS}lj$79ENlu48JEL^-vsT5~1(O82z4r=zGSUu@Jo>}TbLmLYpc85Q4s_4cyD-nhP@PB{mP`@9 zg^}%hN9g9(&1m*B)D7$`r@RdW6*LiI=q?e@OsnTn;>z^j3dc2~Cm|L`%~Xu^S5oU` zxGfogUmSh$GlkmO_2^b^!&!~sS=UF-G*1=~?b-=OmwgtnEc`4T?or&5U>top5x)SL zr6Qd3rAHyVp`e$V_UaQK|LvY8wBplw6Jq=U+{Kt{eL)u_+jXwAeZnF;f5yYl&i52Q zt;87_d@X-K!<+z`ToK#h5&4r`GJ}Zg5zYoj5s58~o~<&#oDCY%2Vb&e(TS)zW8-E( zw$@NIKib{`xN>Yu7Bw>+W0~15GgFzFnVH!xGcz-n8OvB^ zW@ct)W@fg3b@$wvp1F74{CPiqM8;Ao_f|-Xqa)?oAT1F!q$t;rT2Ztn&=~R(1ATC` zM$nkL)S_9DdSsmI$yQ~ai9eurU)w+hPgXT9sXwq@c6;2Mx-!QQ5_Due?yy~La77a| z)8UT~UR8VI==NS7T0Vd4$gjuLR z2!xhS5o!uW(iTz$P~--xJEE)$BTg%7k&A>)8$^Dg8VFO~!K>C-qq;z`?0YvTS0i7D zfH%lnBEdsS??=Cez0O%8F6oajsQd+Z?en(d!$GAB)3~l-Cqan#b{+l;13p(C2O!$d zFijF2fwH4)r_e?w6Q&!c8?o4ry(4X>@g~9?Q7dz++c+=+Sn*!wmg1?vm79y4nJbZ; z?U}=|zTMAAfwk9MLO(~e&`fDoj1#62EH&6;URDhr4KyvM6ik1b6&D`1qqNu)HcyJX z^r6nT;Rs*x^B9EtIU9*Q?mM8 z<>XKyW#*^Auqrmw}Zh zCtOUD_%)SrlwqM1Ze}P~(xp_W-ZbbKCZWulRsG|q^r;cb^33I|$*_w?qO@j}mCo~A z)7WyzX4Bw`yt+4jyeteL82DiC9*r=!%$UJ-sUKVAqd;juQt+L7! zepn#UOm){v-JOdv6eZW3H&FlVpW4{p7!i<+GkuLHEk6+%Z|L9V&~%F%2OaM|w}S?IrLR7ls^;B49(|TNjHfEUnN?M9L$V=Pqfa}U~N&2 zkw03+%|vuRguntgqPsfz8RnPQ5g)2je!3S(r6ulQO$2X6MbIRYVnct>xlZ#t))U0 zUCj4lOa{y8`f4U}%5$Rriqq==Ts6HiJE{$%3%)p0_5lf5{c>Z^TJs_X zGRJsz+p$og9P_fRZ)?-c2(a7LIS{3311gTW-^BtD_fuea*KB{PF)v-0twDzhaw!-o zeJyonH|nR!;OQHoM#F19BUC^;kV@1^?2yP3?%_~a;Qoqc&RLV@=3qP@B%y8xWz%-m zpSlP?G)Rw1peaHV&n-YAnz}+|bP=HH7(9Z2f!WG|P=F3=3M7-zS)xv);+#ZOYMk4t zY?ahfFf>LXY^ra^e(c;h`Sv!L>b>z#zx7r~QZ zwF!IB0S0mBCszinD-P#UzfM-qtQ-2~sMFh5x*g*;kj_4zgYmY2&4b4$)X$*Lkxhp@ z1NjxI%pa18-z9#(Gk!)>T$wQuhg3H;=U2FBv7ALB=7`k(cjJniScOVzMHQ;kM4Azq zeNQzti=VpX3W}pRGM$s@Cl1eT7UpTa>X>q~83=?0XwM)BMT++j5UIEPJ%>>F>AQCa z^>;a*?sDE$#kDi1(Gjv@U)IKcs2^RKep~l8HC{G~(O}AV(-)I-{|z(Ph~ivRg{0q~ z4tbs+FxN|hGELt*L$|N&bF8E)YMME!K(dP+&}gkHC#E4QceZV}X)+qLha zRBWiBGLRBjUD&l`BFZi`$l;%c%RerYFle5(Yjr@)cqnW_ujEk1T3O8R#`5(N23kZ` zl}WMsth%Wm&!uee@NRD(!2vR8onPN!mpehy8!vuOAz4?s9WSJD==?4P-Cdw3;UMnO zRl0_agiE|+aUb^nC*2cc=kPHiw5)xQc*#@I)g40UxL<739o!70O7KY;+)0_$iZ3A9 zLQ&mml&s|QH)DcR)Kn=<3)E1|X;@aTFWJPvPN9a`$Na@Q;Addxdzavq=$+@FidhTe z5_OFl;!&U)g(Bfzxr)kM7KOdUxkL)qnq}U6oQN#cxv8qHPRqP(Qp0hJ-NP>sF8=jK z*(2a~<6tdM=DUWh#BHK1%k%keE9aoDwQOjFY&C{VJtxS8y>1!z{BCvnD4O$f{Yj-l zguyt|93Ge8zET^G{nGThzg&t5iVDgBkSfwRAqU7Y&(L$!Apavu3$P_0h=>kZ8e|#h zJfMO|qpL}y3wj$%k9#(+iz;VOOh(-uM4`-_Fu!gpAv~iZlvJZkk2qg$TRA8R`2w;5 z$brz5F)Pp)Mq@%D!;G{F?G8sWELS-kmD)ip62C|2o zX|U(V1Hl94CEzM{1vrW%GR7xIebM3vo=%1tK#~dQfZ&1f0xg!lD+fkD=G@ZZ%h>$M z;p?&OpGabiJ&*KcsC0-7l_o%enb^D}hLYqbNJ*tuR~#EpK>%g#XWRvogBMCDR*y#Q znMa_SgKh<#tU+b0$`?g|B*vEv5(6CJ2klQ2l~xvNhpvy9oZNuEv@W6~5~_dRw}a4x zM>+#RqYSN_Ct%$#8w9V#>uc{1BEpe#ixb_^s}CDQ2fxT`q{ zwZd%`sX^--KL$a)GpXU_^`(GzSCrQ(UF17of`|!J>Esz>RN^naGTKM>E&eStiT-RA zxfhNs@OjkyILki-d(FZ2VIGF^Jh6nqnbQWQ)UZT%&HcCH!kEKwl*D8xi4w_Rc__%( z66Gk|z=~amMfaJ5-jw(er?{S3CW{`y^Kgm~NrPnVvA>T3aE8yHATCDVn|L>eK-m)^ z?bEgr9VfQBGlm7hnx%F%!7JAW8gJn`0!(i*{k1Q4THRPTiSc0{Z@fHtC-)&;v$j&7 z+kEl&LZ0-!g{sC4-`IJ(VV}kMIqu(3=?+NWn0b38!EdP#(cY*l_YR-jx_L`oSvtRd zHG}UQvvk9)#Nev))7_4GqqNys1jDx8E^mv{J!Erj-OA5w3wgXrZ;N@n)%5g5ydmtC z33-OX-*N5T-=yy`Wlq@!lp6zeDw?MUY15zMf;MbvV!(; zUX`ZS%^N0WWxk4j@Fo4RRQ4rzmiFB3G`SN0lhS0Iw&*_C|Baz>$;1m~F0O#)2Tk3( z-Xll4N^WOSh~+w`&GOyOwjs85@8RHCRaWM*%WD0!_RAsZ%ANQM1C5sKSq4kXFV*a~ z`4E$V$f}1FAG2TRfc3iy;FSd#kA~P#r)sr&ufsQ-D?d#Nl3R%3CSI0 zn<~e4?W`7=_j@b#kjcw+;D?+VjOFexF(@>(W$q%qLZe8fDlfaE#%vk`3qO7wig=WL z_M^@`zM&U7tpvI2&pqH5?r9KDUS2L;xhc)Ed94;AG9=}>2Wvryr4Ub^+sEPPDcI~E z#h*}a+K2FG7<7g6u6#P|B2%<=4k$jIa&@jS?|p1|@jJk^q1IeRz{S4MJ*i+-J(==g z*?b({WDgRG6U^YBH})5gUJfM*Nqus5#~RH3D_{S&p4R`Jum9bH`k#Hho2$}1+Gpk~ zV*(Ii1PL%G38)x}fOCzXMgmfU9Q`YtJ}})Y;n~}bDI<&L-pcbuZ|#fMjn-9;!z_=<)Yn&1;erC; zqljz)e+ru&p;_F<)?Hw82BbFEnZUO&C}D0SRwzE9>BxMg*KXljV3^$x>m)3PazcVF zm83&j9M)wmKzmzB{A%g*c-6Jhi|8Ls+((frJ`DsW z+&wLM1&-Hv%tc_HK~DKm>mnblgmC%_E#HSL<&fpddd z@c6wgK3GR!MquqgJ(eBK%cGta!0Jx?H*2J=Ay@dp4OkaZr$Sa6kGw6c1;8FXt^JUi z=;}$e@Q19WrQ>DDxIR&CFyHIrmvl~T<|q$nng zT(rRV`xDZ;qwzVK#p_5|nTEqk^)W26_H$kfLvcjv7EiAj5u!`V2vf@?cb3&TBTBcq z?xe%(4wSeF8;Aj-gzUS~7Z7gAx+WpBqT)s1DIy>6!|)_QvdHcFnb;_7_1fZA&6s@F zq!msPLiSLE^JAWV^b+qBefKy|u1Q+auVpgKrRjan=QuZoO7+*=+r?9W%9_s6Y}jpbyq(&Q>6+=p~63#5}kP zV`o2c+2Wx-DANkVxT4hQC95-p+~|i~3J_!uR%8!}I4b0W`6<>CZ$J@^Y=*NxWz-U9 zGDTxlfMt>YTo;=(wOi+(RiHbCwIYOjhtMwjds?_-O7tvdi`Zru0e}`FObtM;Ae59s zP#A6?PkR7WTLn|pq&e^iPH_p+frSpxYX5Ui_E03{9G6zP2UTpO*ua@pSi|U6CoHWM2 z+eG!A-J?EJCm+R=w#Of1GTr^eL~ri7&=bd#k{;fnB<1Do{DDhzjy557FMasqIi2=4 zmG+iH`=Eide7|Ma0eyqINM+bN#^GP33Zo+DosYg1+^TVC zN&UVz)<{Kjz2?j@B@@j#Lhx~F8zYMgvT}DWB-49)I5txy`4h9nGosl^yiwPc@$~Lz zODBwMLx|VIQ$OiATh{4)`xN8kSRP+?y*%#RZw5}>q4J$i4I7J{mA)akam2Xazy$U9)o!Jj4yi@IERxoNI(LxpmckvBj#_m-%qVFN{hOsFKg*vPXWh0uu!cYhJEBoRTiN;b<3l*)}lu7T#{w=%^rWBL*k+U?C|2K&YM$)W&Zi<@5) zx|6J`(M@O-x)Zz|eh-w+k4{DkOt-rZ_9@nk?TN9_1v(*g10x0G1zw+W3dED-2vm>m zNYEg(fIHB9i!)h2^g+TE?kmZQQqLe(b~iaPE=iQ%86+NLA?PFssZcib5C3Q&NIp?$ zUc(!ZZ)6O#yE#JSBtK9xljtLCzc?bWgS=ox5;*D@+B^R4rP=C5ycFC7W1qi5%~Z&el(cVzlR7XaU_^hdYf(OciNrP?;07>1qY*JkRbw^ zl5S>I3M1ttCynK~Qpfz01pbJm!C3DEWr)!$rRPDAz7n^GHjpr*+XJZAmL!)RDZrLA z7ZW)|@2dgQC@uW161HC{d-jeki-_HXRxbr(up%)){M)^laTosR_JkhPxIqg3puQ9R zwCxGWsdHwBYs$-9ZFW@Ks>#NFW)tkK9ouX@coXEK0iodeyDJdlO$YjQ9L>R-M$cix z576f?A^Ubb&*W8b)@l>x?I5yt6XktOPaGwdC92l$s2ig%9JZ+1`uR1LT@mXq)+CR(k+kVpn#PUfb3Q;8rn6V^} zfAFXN5MGu-8kntj#MPGN{rNk$-BZAm&hbnWOGsgt`dO^RH=DwTssKQnb)?j%l$S7m zoApjXzom1B=9Z9r7Jd6t&se-9`r2=+kD;8a!7c=^7_`{$Ud?Z1}}G1ldnm2*{4;-3etMaokCHN?@n$Kq603 z%Rtr*pWTUMr|LjH>|5MvYw9u*1Z3{y9>oiOY~+@`(@S8^rmh(%F}B3Rj{xN%FPbyf zIi~&yjOag+7ID%_9<|Mu&)hg>{Ix$2>yy(~R+feD_7wGSm=$SFqkznrt(p*i!O}6u zY^u1R=j7TpVp+T^Qz|DiP$4fB*Ies@v$Xl~AnNhW#6*X!k)51%Pgmn&rIc0lW8#-s z>n2A%tID-w7RxVn5#?W^aF1B?1pA@<upR?xj&J!_8J&7M7 zKc3VIXyn3FU-1=s=jG~s3bF9>8o*1gB|fD{nMJ}7Q%EbbPr7lp_tk>9IE%-&Q0{OKj$&oE&{&(a)eP_A*Fh z-yN8*wAs9tm~R__h#AMu6NzFYNm2_($rHR#bzZ|Q&c{&zC7Bf+q%O#y1d57WIl}zFI-s^Yre~?gkL=T`n*h8JX8TD zQsSrmT$RQ8jkIQ7Vw}Zh!U=)5|L#1%A`O}6d8o!XhT1&J?GCsX*;vm=y+61d_jJK# zvtdF(M@K))ty!)l+eRKzgfiYP`6izq_dSnMnj1T}Ec}QIqxkb3dF?hNOtsZnI4OAQ zb6wbChTz$!D3lWu;#2qIc1NY``WHTh=1%}^1uVVJn81dyF=gt(TLMgw?#CzgXNAC+ z&?j7-0K@vf@X8E-3;_JMVM_lyugt;7@SjE-m3g{&qRu})y*W76SbJXZ4CH(GszRB)*;vrA;*3xTVhV|ppS%;9c7Mst@K-0$LW zWf{gyRf6?zMCxD-w%2+}ho5cjFWQX+Kt1N8R!1?(0yjEaMrV(sC^Hf#>Ej;bZ~2>B z9W*Q^-Dq<=r4T}-XoaN1mnH8E_r4}_zt^g`?r?^-^9NUVoE&HD*E2_xHVV{;0hVWv zk9A!4ePc4{^io3MDyJ7Obw{iEI-Tt|M*^ox;1ro#j1PbGZTkfE2fvF{(BsEEUx-us zXsKOAe#UkZo?T2`4iyJMe-KXwa$i>J-}EfRzC!k1u+qGrW*7MB4=^T)h==*r$g<<<+NLfsgsrGoIu!B-3NiFZ`7ASMFyH;-0iZ+<=XOdiQ;@ zA)SmHpidCL3<(rvl5(Zs2*K;wi(@+aDJAd(4$K`1=p6*RyYiV2BXCLrzY`-Pe*-Rz zV)#PGlzwcCDq>(%n7yUUs4ayS$6A#Ar~cYUa(&IxO_MnN?6a2 zmbq|>JH@k4eEAt$>Ltb9yn@{Hn*DH}YI^6*7RMwtdM^d{d`$3I95XxCGM6B8Ykp$N zRxJT21n0Vr_0Z1exi8|>t4>%uCMlmDr}D~gNMA}ZZ%EX!gIqZxC9P-9RLhx^+|%#@ zY9*dxY&7p&y-RxFPd?_?1!~XcvLR)GHwbvZEEj$?KIo(d?ze2H*|Y+^AGCN#F=!AZ z@0e+gSJy~&R#3=hu66SIw9t)NP9XlcPYSp^-t3rOxKF+0R*P6k#l4D(E-N;DJ=yf) zTNTPq!!y&h-om|$(`Yd#be%Wk$x9*L?OZq`Vu`AK5AeQV8^pXHvu>zjvvnyvZnt{S z`RsHrOHVa^5%y@GEL*f(I77VSBX5T7H2uBZr)Z49-g~F%&)YLAOB1Zm0*As(^F6n_ zb1;K~$-5=PhV9(0rgPE<_*&i2g5g?RP5c)!L=@&Jk$4s)eDmPf!NyPy_|Z| z+~b3<#9`nu@32OL8OPQ3JZYYxOn5V56$vVb0)KCxOfw4qZDSWc`3{Z zIUNeJhTdUqs_Bvx{e1iZM%n{~1N#FB6Bwq!G;5j$R=A*-cQR2_ru}?bO)*bQ*%K+& zQ%8uCz^C_*_RrVJ%FU_lrRLzwBF?$oVTY_D~ETb$_9m5S{9+M8E z4r6Dg*OcBd=!5Lo(AcKfx!8=@+}M%WU?kC@X2NqqjF3pgX6n5YB#L};Bln@USZsms zu+3C^8?p6-*aCR)Ze)7}v221Hh|kP>rLo$Coq=xvd*;2%saQElGXpbsv+rhhX3A!U zW{O8{KLw6{O+o)m5ablxmm_u*IjaB37K{+Mf$Oe&)G`JCGvKFeNXM5Kk)wqv>z|wg zorvowExdPPN5%AH)RfeO)ZEl`Wkh8>V|c7wWi(bsOHEbc`iebk`tE8rOKnx@y%$iL z=*~V%p!zX^+<*tIrBeONKrhq>;iZYH>>h7ePE=>EGbvYBS1VTuSLY^{HljA3H9Q`! zHX2W(r=~0MZN;AT?X0VhtLE*+5IPuLWN+E0w5yO_$lh!OABMN6tMcvD9+yBL{0?$Y zpQpGhMSzr$l8}IqyO55MxR6sIO%JA>ciZ@I)fH=)Gc&;Wpsa7Hv-L}Zv$^jJ7`By~(##2)cvm{nBU zS9`0yf;d%SXVH^5uQ&%H43P~iH`BfFq4_vO;qTF&ls7>`i^Q7|ZzT2}doFRjq91tA zrhCI;K1xPPo=O@@-<9l?l$8vX6zAOJ1?GPJf|gIn`i8&r75LG)bLCqr!fFql?DF_fo%`pH^^`y}LVdn`RT*ME6p?YoE5vV-w=V zdY8JBoVF3^#D6!xQ=M+j^$GhRelfe-WFTZnO6g09OnFP0NlE*{TF7zWp8{YoG|*yD z?Q`t^#jw~n7T!#IaFD`jkkr41f6F&U%plvxg>h>!#>s%+?+K`7Iw(rnG(hObiQz!O z#>2)=M^4AJj4BT;kEtI-h_Q~q#pI-QRyg~i=2Ax9!0Y_|?7lj}Ah~Y?rIqYqd#QV= z$WS-Zi`d!ntYHbadUNn1Y#rZ&iyc ziF6st%htjDvGa6&o!qaBOV|I{CmWNE;p6a@c}=yWI>?LK$?;MAgt4O=<3sn6@N|B? z+5d_2>G76*O^&jIGJ|Z75{^=WjD?bhJRymMEJ7+JmXa}*N(o#A*ryc(eO;`jh0I#A zEBm$34zD;s+)lh$oI_k#JW(88JUZVYVI_f91}oc9eP&)JT+K9Y zMmJ4+(8CD{oC*6z#BL%t^}}prh$Netp1LywJ zENn}@F&|;0XjObD!ja@iz)DR^NlVoDp^-UKfFO&eFqp5C=I&Gyzmooq?S5d6Q$aPq zLVEqji_u9$u}y*Zj}~qx)sv06-r}MefmwsunVFl}ky)&n409TD;#snM?YM=^g#=b6 zYyOqoy4KkXS&y&h({(iFl?B$)uhiD2E0gA(MYz(OnRszov016#r7I;&XD7vNWbre3 z7~V%5U0ULJsJ!%F%8y+NE5&p(KjdBx?uuq~#eBHm+wWv&8jCI^Hq*V?-<2Q|0Euz2 zaanQ6^6~QN`jcO>rjr;L4YdaHBPlR1;ABO72G$}^nb3`?hnvU^r3ZR312APx+fuGY z1{NZ%F*zAKCYKVbd3VJIilxYyD47VExS8l`Nov2%CLND)@hXntWG=_KxgE?&kZ{~E+J=h*YN&PeuHtIJnFxfXk zGgdZXG2*D17`K>gVYl>LFjiMJ6<6n0pRGMGUXOLsT+mj3G$|iniM=;lU{a?uZcn}U zUMNyut#vkekF6)S)LrN<%Tp(>oiGY95j7q(CO0)TIyBL&9jz&?#jbfiJ2<#eH*xee&K$LMz$h_FDH^k%R7-7qN@wMZ+3y z^XB2j@Orif$)gfp0!CtTY;sm|vTD3)rs=4|L1s4jLDa>MOOUbczP-u?`2`z z>TS|N`Iu&QBgN%)8;x7#UVG-F{>Gu(=H7csBip6khOS%DZSRfYO~P&M4eagc?di?) zo5PLfE!_xyx{vvX^7Hz$ySMH~##_*HI+AXzO01@wmYnjG+LV&5j-MQTiJn0Bp8o_$bJy1td0Xr5C~#14 z7mPL4stP^BZbR@%^fs+4m2ODzY&1{pE5Ytca7dVFG&rb87agYCqiS(y5sjh^KoSQr}$Ev=?DTjlM5ppG7L*laq_@~icp7}!qgw+366 z?T((_Aaa<`Y7w>Fvf>3C%eeZP6+I`l$@&IOx`yaR9h3GIN_CI2+49>mHZ_~t4deF3 zmW7t?mtXgor;-b7<(Hbg_1?zo#_#OB)bA9hZG=O@ zqcJim5a^<5WGE(R8_-oz7co{NLNFT9VyN*{xr$vSs#}*7*L1lWpI&x^`z6CKDRdOy zY_IjMXZz{UJLTKzT{W+xcP=9yQ7`Fu6g*1;DZ(hlzlzfhQ&CV9(^e<4OHR-MBt?=P ze`x72)(cTwCyi03>e?#~pOZ>Tsw9=sEi2u)4kyK{N^H7zvr_6SwleEa zD|>a*R4tPq<6m1F&IW4yYFbAxs5Dg@evkF2F&)*R^(Z|HsF@t;pnd&$wpasdJU9|O zA~>2inlQpN3Oh17VmaD;qrXqHkCCLSz*GG;a$~-);b!xEb_2fO_=ApCSEr-ot=nGr zIbnY?xl`ri`}5$wZjz5?N2{mq^Y#tO{-=_VQlE0Z%AOLcvXTn35$7K!A?wg9-5D8 zu#yHP3KbLOEtMpdCFSzS!3Zp+s8V#Xqq2_tvU0JCjv`0tP0L6+)#WcO6*r%K(8L%e z9{Fdj{nErsC2yr?;r)q`Y)YR}E+x0N8!2U1Wh-R~W#`2DlH8Jx5gnGcl5z{9`KA(a zWyO*;<*bsAl4j*aRhkkF1t;10w33igh|;VI_v(|Vl5*wM5@#hZ-TER6pZT~F#d#?w zB_{zVcPAYuaVMwx@)dP2?|L=vmX^Gio0H;siTXx&ll!-m^b(s&9gX%Hcdz@xlflwP zrA~!+=lhWPY*in{cfKY1@%B?HfbDV|FQ#4f1(dxD9EzVi$Yb`2E+nXPvSB&c)7kT7f#m-UcC+9mf zUS-Zj>viWY%HE3~8dn7C2Q4S(ez!m_6wDbfs-IGxoSdFH^`5Srh%7{vrYo@(OlTh# zpH`-8x_GVUwvakK&XpH?G<~nSIBvl>-T1Yt(OCXnbp6rEfUC~ zrhHSSGwXG={m4HJ{mtO%0n8>je7@z88B1ON2GjGG%RQnSkvJJQG%hbyJ7F zd~bZP2Ns^0YyNgv@FA9twQJFKUN9Y&Gwa*jm1ghH;9YoAtX^zGY(=bE?D8nIsQajg zf$b>kC}QkE78#3-nWOJ_%nxi6)@>bj^1JZ^9$1UaJZtPrPma40Q8vuqt=ATs@~&S8 zxT9XNW0?)@0LFh;ELsV-`!rwx`osA&?Y$SB=) zy}+qRYz@U8)gICAcXIf)I5@tIZr^C{Vo%jHzb3e5azSwce&KY%eSz|w^AY!v>5=o1 z+$El~H{`ZD+EY~8Ytm8slF|Le1HRo!fUmjA&^=~mX=w?W-3A+9PDJX6!M*Uo*~LO4 zX72F(?1Yu7p|0^R9`?S4At7rO3!Bgii5hItKukooaRGXIVVR}9vvrhOz8iWPZW?47 zW*TA|fsik>unKq_f*E_t3I_~PKg5=g8QS(IHVB5FDQFhFE9=&>uPG=VEEl>f^_ALI zb(f*vAV`e0Ki{ibT@3i&^j+UU;80K`NCE^t9A9=IJD?q)zP}6CQHEoU)3@0!J-s}L zuUu!hRg?dPtWG0wew&C!U-Hv~^v8vACRj=*PpPHwv&%>hTK>jDOYM8fG=mOlsjJ^64tP=y(|7CJ?`%L>ER#2Q-2Y zxO1(-wE>g7a;1fxWeMtzJ+(U3YfZlZVfc>_Y|;R3m0P7D1PK1vS3+ITmU{IUm>6{ zAY@rSXfAZmf4UTa5aY6i_e=rL>O$V=|Df1c zR$aBg|EeU=30*%^Sj`l$p#Co?2YbxX1W`*Z)E+emM+DylQS9F-SL8MQK<}5BEWWR% zfD!dTd-R_f!vBdr1A%0S{;6a9w?KTvs(6iq>^o*K_Gh%3hsHS%Oss(c(O&<<8OW4;mT_43R%Q~0=%oY95 zb- zY}&sT|J(!mf9&jkPldPqK-Fx4U=j4XfvMSj!6B=*fY5Qe!gJ?VIr3UZnb5-8O)ZjV zR$10}7g|l@61;`8Md;kWwYo>)0N3qD$W9Li8NAhn^xuiSE53h+A+GlN zEUNY;$%i2(vK3THAZUWE9x{SdkDoX@Jv1cQb{7fGKg3fogg+5&dBWsqymH60eiRpp zx!&%6ct-GTC>V6vmH->UsMpVmJr+Jh8FUa7cdpmZom~zQ@?@Kj8|POD=)G+Y9>V`1 zRuyh_@!@<41qHR!BS3)b^Yde;M}mad`I~47hwvBb`uvjEr;s5vcK9T5%)&rv?9>cx z^~fiHxnfZviFWveaM(jY4{f(_5HfoG9N4d5Aa%B@l(zWjaE^jN+ii0&5bk<7Kx07B zsUQ%3gSwX`FZDmp0kUR0%@1f|yQ*R9_u(gf`TIfraaxNY1b-fxMnxhj1iLK&l6I#{7^f)|6vJ+d=zkWqN{^JKz?u8}g4w5#AhCA%1aTH<|A1H+D1{vX zDMEgq-w*a!WJrY_q+t#rdxW?QL6XCNP5XS!YZspe24os@m$1a0G3Cx0a(W;VYa5?( z3=k=!b7oMLGWZKPa@hTmQnWn{J+8Qb^mYRdtoW%Ka?muVU_2J4b9}6(cv+9ovFmyv z)(rw6mUH-7&0=A(_WU85bNFeO^k~geVKol?lbUmk|Dpj&&pF0Czb7+j90VjyHe~*} z{4IT0sX|b3`X}Ock3{Pki&ohyPDK?GxGN&HQ-p4yGB5oNM{rn<5Ucxe8qN?joB>Ih z{G$^&#->v>OlHfNb!#~P0+C<)S0`DY$`XNmY1qexW#ym|Iz(uHUGewhDdF%JQ2b&K zkYFMJHC#4<1p#}n2j47$_e*pE3&iaK2An*fp-|s%CrmBgiz^&8MXz z&^792a--1C>yXU&&!OkC`2OF7u(>R;^ZyjYCs^~venY4V=^u`YpPev`P=f%3b(P?c zJKr>Fd6y-)4%L;0-y%%gzu)-(NwV&;1l7U5TJc?kXk*=~2d;#7{TI@IZyEmXBL0P6 z_%8;6=;|*6VJgF;*~$?XYAe7jn4+>`-DE05LBtNlWm*v(X6E0u%gXir4;BLTg-P4u zP(LUH%>h>o?62oJq9Ipg>M0-53V~i)h&f*2xDx^3Y6YS4ysH*;5`pWFC;8vVpU-g| zK3kyfKkeJU6Z&&sbI7zEAb(IOY5H}r**`+Mv@4E70q$R@&BOh#5TrN!3Sfmo_Yc@2 zJVQbVC4(XtViM|7qY}av;tT}RZ=qW94Iw1e6NCPu022H|4-`)%$v2Kv&j|X9I*3S; z-XCW7iz&!Js;?bc)n6|6@Amdj+xs7aUDqFeHwF|Bk_*8V=ZbynpM>kKUB5w4#01H% zJ!JZ3FezH#|7%(Wis&HKg@Zyr2nKmYKMy9w0<0+ArG)Y~iqq8_i9){%HpULjB-0g% zg41OQf_ISZ`%JF)0WICt%Z!@ly9m}sw#5RBsHkKHqJwhvZvuzkAy^iQtIXE_fv|v9 zV!DoZSwiSAU8VUg!nK)f{kw!W0{}h_^>q~D`$j~73y6(|5)%c>CkFY4YzDm~g#AzI ze^dGIa-bS8p$cCp+F#p(X#oSP@^zsh*@FK`p}@5Mwv)ea_y4=h|EIlnCAu1`_mu{7 z2-BkljFI{`3(+S-9UymW5v54}7NdZvXpqX0tdY)^->|*M5qenZe^k- z2{6?#J#xSqiGQY0RRWYVa<>f8k~kRWe-@X4KvsbMo3eko!G9I6;-GktyG4nf#K7>w zwuk|6B>sLv^s!J7$lZKIU&O#b!}JIMbHx4*LLOaT-oQpf^)La{#Qw%YRgq9hfNn-2 zHIe@hA{CLVFj!^i78;<9$X`|HDjZ4&(EWGu8z__+;D4y&uiE$TS03nL=oStj4baN1~i-P^nVhw82ZzU8P1@+J3|ErV!ucz`elmHbFNaQak zgcJ@X0O0>h1SJgie-s6Tz1fyChWBVpG|3ou70$*^80<~K%C{0x}_h_gXdc50u6;kLL|WBla_A`ad`Y+@V zC=1jTVT;4}&=(D|j9srEm>Bw; zIS*KJ+x)OxW)FpsB!&|yFyE2o2G)I++%8W@w>(m`bCe|s6tYZ||2S1`hDm`;x+Ipp`^;x%GEs5m74RJP=Yo998`d#MB;0@P; z8KNu8)IE*Icc?7Ub=7O1M$-CK7pQ-K@asB}CF1WzD8O7}5T5$uJFveis?|RAr1fL` zu2^Mq9mE3Y>RqeS|Gq@eW|e}?ItGt@5Df1Cnypp)G?WIlvAVok>3A}W+SuBzdC9g3 zpUS`S`-Lob72daF3rlS4yT@m$k$4%aglQg}MR7}IRNUVSM31w}@9tbA+cVvZlDW7` zU(=2=-D9S0B-&dmCzbLyE+#%MbQFtJsNIoQ^!{) zP{$93^oKqB$KUGTn!oP`t20Eh@-{YI@razl4$sSVWfhxw0zmT zw1CtyDMOuAlhdORP>`AttuW-8b$(7ZGPg0YvAh7tD#p-=(kY$UG(C50Mbjn>@K{-P zcfxQ!ZK)r{+ana#!3CqE9{ZiJx?zP^|)KWA**ylL3zF;1nf0y9KxVo}FYb-@9 z!j-9AGczkq=`3@aQR1Tc3g_}UHnH)&G@Zb}o02=eKAUTuziTa1d)-S#`}pMIm^kJU zdtrINv2@1toWUe5afo>1V&h|3rPsQ>N;7q#T=x7TvBjhOynVKnS=KZ=Y|+pfQ=c`p z0eT^FqeJ61zQ}>Kdch`BqTL^Ieb%CU_SK9-`uO%Fv$ptzL5y7<1f$h4;6>2$;`03L z*umxTA$~ShqSH$1k`4DXYoD}z+B9>y^zIP_a_osAPw~@-Q{vmDPn!U_m-Tp*$*{U+ zA!gqybnWX)E4SA|gxKbTdz8*g(iQ8#u5~10M^vp3Y`?_^11cHw9y(diTLKwlFa5L> z3RBFG3K{Pn!b@X+ikt|MJr>78T(5LA_Ru!*AP|R={aPT1A@EjN9g8_RflF@@h)v2y`U~w_Xt92XJzw2tA zsoQf2d%F7#(Fj$L+z8vZNkk_PF;xPdVK`Xh0$x5@IW`FHHwf)nIFb@}1?{a!op{M^ zKyNQ27{-w8Jq4mChpVIJHu?83guav9P}zG*Mpq6q-Cd@hlMHIuQcl3fK91q4!__g2c`P?82n7-6A5qW0d9 z>tDy0;*s^uh<)Bjvtv@n?E%ALQZh(!nX6zbPAJhQ0;B=faV+xp^6>Ie@|{As)$~bw zO96JX$cshJ1siG8DZ~dV7$0go6wUQU^264oprnn-Yw|TsMv~1si5l&7FViQDC(#Ro z^QQBri-&Wn3%V*k<>$1{sGMn^EzPyfK5D&H1Nz#%h480%&a+jo!R0ut>}S*ZlZYPM zZGtqNb(@R^*FzK-$y)Z$OKgMQEEnB&_|dNxJ*K$izA#(wmwH6L+{nED37d|_~?H8MCuWOyHkFB4!__p|t`1bhDpT|5qJSRK{ zAERDtUOiqjUL)^~9z$L$UIXtjt8@$sp{SHW;@b*=s1(BD=oA{^{|^99K(N1&Vx>4K zUP_P>r6eg?N|92fG$~!mkTRt#DO<{sa-}>eUn-CaC96~<6-y;jsZ=JFOBGV3R3%kQ zHBzlqC)G<0Qln&(Sc#K($u2phCdnx^OT(mdq~X%J(s|PP(gjkB)GD<}?UEpg(g^87 z=^|;Qbg?u_8ZC{HE|JDcXZ7V>Cy~orZh{MEzObUO7o;^rTNlz(gJCr zbiH(gbfa{WbhC7ebgQ&Tx=k98ZkO(m7E56G-hG$fst&Pe}AewmR&IxlPAlU%U8%(%2&x# zolk!vY z)ABR&v+@@CIr(|{1^Gq!CHZCf75P>9HTiY<4f##^E%|Nv9r<1PJ$bAAzWjmwq5P5j zvHXd=P5xB=O#WQ{LjF?TF7J@PlE0R}k$1}9%HPS~%e&+s0Y)O1mN`qB26cP`OAMsa&j#QbsFdluMMc$~a}bGC}E3T*^e{Qe~2InKD_q zT)9HIQn^Z*qFk+XDpQp%Wt!4WG9O8i6-7}MjUfP`O^YLAg=6Nx50MMY&a3q}-+qD7PzjD2tUll_knu%H7IR zWtp;ES)tsc+^gKDtW@q-Rw=8MHOg9Low8neKzUGkNO@SVWwSDQJzUQk|CUQ%9GUQu3EUQ=FI-ca6D-csIH-cjCF-cz%VFO)Bp?aB`2E9GnD8)c{Rt@54ny|PRBLHSYnN!hLZ ztn5*KQGQkSD!(cFl;4&8${)%B<)Cs%IjsDt98r!c$CSU6n*t=6cuYMolIHmHrNO=VS1{^n>I(H9^(uq?1L}k7L+Zoo26dylNqt21 zshib7^-=XP^>OtH^-1+9^=b7P^;va``keZ_`hxnR`jYyx`ilCh`kMN>`iA5s)Z`JSA@6}!E z59*KVPwH;S6Uy^@w^@J*NJp9#>DOC)HEx z-|CQhT0Nuwqxv;Q3(-QgFfCk*&?2=c&7wtXF z1KRD{9ok~;PHl;Hmv*-H)7lyBAI+~bdWasXhw0&ZgdV9!=@va&kI`fGI6YoZ&=d6}Jy}oD zQ}r}GUC+=n^(;MG&(U-BJUw48&k|rkCp#dZk{aSL-!;tzM_s>kWFN zZqr$v(|O&lJM<>qsWudD2`Z|5R z{(%0V{*eB#zCqupZ_*#pefnm7P=8c^On+Q|LVr?!N`G2^Mt@e{qCclUufL$bsK2DY ztiPhas=ubcuD_wbslTPat-qtctG}mj)!)}Y&_C2a(m&Qe(YNWJ>YwSK>tEf7}l z`d9kb`ZxMc{agJz{d;|v{)7Ib{*%62|5@Lo|Dyk@@6~_P_vydu`}IHc1NuSzkbYSI zQ$L~~)sN|a>BsdG`bqti{K zsyx-68c(gK&QtGc@HBdC9@fKoc#qxV@HBaxo@UQ5&pDpqo^w6tdCvD-;A!!+dfGhg z9>F7eMtCmtT;v()x!5zxGuku8bBSlHXPjreXM(50?lhJdcNupZOO0j5a$|*Yk8!VYpRv-o-&kd=Hr5zx zjdjL);{oGA<00c=V}r5L*kn9n_>9fQpz)~jnDMyrgz=>Dl<~CjjPb0o#dywm-gv=y z(Rj&t*?7fx)p*T#-FU-z(|F5x+jz%#*Lcs^YP@fJV0>tNWPEIVVr(-$H9j*wH@+~w zG`1T%jIWHZjc<&d#<#|I#`nf9;|JqM<0oUc@w2hV_{I3u*lYY|>@$8h_8Wf~2aJQp zA>**|r*XtMY8*5EGL9Q3jFZMG<8NcgIBlFU{xSSs#v9@d^@e%Fy%F9>ZKjrPWP zW4&?ScyEF?(VOH=_NI7Ky=mTbZ-zJ1o8`^+=6G|xdER_)fw$0W^%i-Hy(QjKZ<)8; zTj8zrR(Y$vHQripowwfG;BEBUysVe=@?N{w;cfCdz0KZX-gCUez2|z*^Pca$z}w<& z^|pE2y@FTtj__XSy~sP#d$D(vceHnm_Y&_|?>O&x?*wm$*X5n)z0^C&dzp8#_j2zQ z-YdOVd8c@<_I6(5=nWrAOu)aP1LU~u#2u%uO5ZlLVnpPS^~4Hj^zPj!HlDmVeYu~B z^iA|LF+QK4iEdjOmE{3}vBwEKuRCCd5U;CK|YX2`%ke1PU zzRI)OZ?uiH-geS5|6l$$EhoB8C#C!Szx$r|`*+bwySI1r`u#io$Nc_7wCcA^LO}aw z`$Xapt@E{S)xhP%_ixB$7~D-RGYRJN#BFH%sDsHq-(1=qo6XV}a4g;By4lZUFd;Xu z_xsP#D=9A5fccz-h+O{}KmDWpekRN3TSlv2W|kB0@iVE_zLl$1`k5sEAEtHM-0}bF_a8UwkVpK-%{#ug&uWWF8}S@@B`3{# zOo7Ez@4bl{CT$opTT34w^1Vp3j>DuC+ey`=>P_@L{Yl!x$fO~uv7XHXj$vfqN=MsomJ{hiwg~h* zQ$`Cim7ci6&y@OnmhU1LQD0uBT}hrfKwUjU-8k$&7|{M?EVojy%>jRpx<;SX$RHe| zy>gTmf79AW=^*@%c8YY0|4-7dq+Nq^Ehh?x>_cG#5kpU(IFL@Ay_ybz&k0<$j}8#p zKL2s*_Sf@B2OOaf9;0nNW=>ACZ2|52fZbEniNof6HXoTtxYvnn%mcv~{86ol|t$8Zs2kDf@`!toj%kYP5AH=#Wk_ar~#LHs&TeVkX{7 zhL-CJGEl6(4W!Jk_61^9w(p6+G|4_YVa&;qW=1I2#D^^;SRM<;$%NC)iK~Y$OYfsE zX%caqx>H7b{SP`oOUdjc8nKBclu@6KxF$XsEXfpq${amU({l6E^c}gL9e9rTG{(1% zyngD~CDe%=T8w34Ozm4gQ$g>HbalMuXWD&(mX9JY_xqn=@)T0~250*H&$^suIgz}P zCrJctrX70J?;m7B0$uk6^)=1aMW66dZ35MZ*G06;i7S4l!F4IoToWy%o!66Q(ktYl zi>WU~wCcsxzO_5n5=Z?1kZ3=qdNXl+9C?WTU3)(>!5kHIeqKUN?)N=Hp71?GHTojG~k2GirGhY08I@Bv9|9b1XfsM=8l7G0vWG!HpZL(0; zKiWhen`j!^MP63OBV=q?{YNMS!O5ou6GAHG5Nc(Zu(9SuBQ2meQt43jZ=Af2l$+<1 z@*h_RDNpK~#(^AHW6$9?A0mj^U6xE`ee_?Z81V&g9+abAG+ z55ggFCM~@)L4*GN^y+EW9ZPpxY`3M;aWwQW z@yoY)1L-^0% z{2Ggy?YTOPMpkeoLn+AYFp%kBuZzRaf8N5Gvf=RZ|Xl9?m3D?JdiYJDUg&^x~`VCK#uS>6FAjb?>(7@7Qs zOmM|n?QNRr_{`PLbeanPY9Zo?Z}W7Mnx@Yu@+cEUs?(uB0~j$zvme(bXSFK=$AX zy*{uwNTr22ERtvu&{opXNV6kaWMMt?GBM&mNk)qAfk3j7OviSH?+K{|*@VzMkWNdHEY^PK^TG)GgE?@em(bE>6LZ87peGcll_HBj`e0gWyoNcJ=l zql9ErX%x=P&36X0b|5ovS|js>zTi{l0bJ$?M2;TEO(J>09G5 za~FyB#Xi@S19UA!Y0~TqG6Dz#4$d*lYt1#yf@>F$zF^t|?LI{NhlVWDpGjx68%g`k z^}CBQ-+ouQ#SuwkzUxtQkxnxn8p}vYGo<+KWGzqDjUj7S)0s?|C4)AfyyFe@t4R`jh1keRuk@Us~wesDDoXf#uxxuChSF(ZY^g=e+jaHGR87e|&wBtfjfQhN)@ zkf{0nzQJ`g=&Uizr_B7;JwVfhF{J#?T&+>iAGf>ad*^!tsmHzr%=FpQ31$6CZI}ab zx4HO2NjV8iz+H52MKaxWEiv~dmIupU=>mX;1T$KZNWA&1=EKsD$*T5|^eWFcXqJ?U z=bSX=@k@jY`>(U-tx_X`nOuI(kW^*fuZU~vt-^_AT=q5!Z z#Y`c~VrXP^lO#BSES*W@^4&+vN6alII^10}XQmN=u0BjH$v;FU1HGGSE>6;2lPv@5 zZy~1(m>X7+_e_#5Qt4NkwM-1`R2-o}Dwam)BlJDQ`tA+1*Me34Iy#_UrP`}hn@DE> zor30$0jW#|S;y>wIk(MSL}u{b6E~%wIJ78gXu;5-h!dY@?7yI9XxKR?h7EoAedLL+ zPIhi1Y4=I>RA~CpQv=;YSKqNHg04EpA#Gw(X-KB~D@>Maa-d0B^e!|yw#~+6G2x_f zg>?4NsDAUtg)~1rMsu1x`UDxrhpCk`%3k|@OQ^P(YFlWJc9@%NblZm{KtK7`-9t+s z34Gs~tMRYM(4>u8;0c7h-DYaytED5`TyC3VobErE`*p!FN%8K(I1lfx$;`4iXxL*+aC?%%t^#iUuVgb{v%qpvq$>|6^gn_GRq!90o8+KFdXc7o|g29 zgA{My*`237uuQXMx*9SQncZdzNq^TxJCw==H0%IV9LL5Re97yB- zr6th*-0Sl#Hl#bSKBu_F@re?nL-#GEC;HxfMaw2>}Kx zHRCg_SV@8-T_-g?ET!||jYY`@oUMr%{rMor-67=+r)6WLhl`O5pFq6o980K3?y1w3=lGM{; z-xi&gJ{l>~$ZGxz%FpJS@Ez9$mLX-RBHi4Oy=n$cJIIofBpajX9FL~jo0Oe52X-Kj z(y8>PZ&_g5)7*hQzJQs7XhA2*zqQk58my-A9+} zTDtQ{XVVc%Jc;zdV|4hXkd%YC^avJEM0+Bzt{bAWKNH>kx2X*T7F}jIH#h6SWR#0c zEx}CN&HZ-DSqVPhJ+!3T*Ypu{8{A~bRJyxFv^4=1B^+XMtNHtabh;yXhF&)P_!|-B zv9p?w&Qag0>&&Qva-Io0+oV6U965vj4rQYG4z9K&oV@E)I9cL-$7Iligzo9NIy&hT zC0WrnIz`RNy3L%T)xJyVpeM=9R-ZX-o}t=fltIaZ?~xHrUfw$TqQ?bZ<2%TQNac6U zAWN@pC2gsVyz@Pp!;)4HL-M!z?O>Tk+vhmDIN?pMq^G7vb3VpK3oAXP123qNaaO#& zV@qJiy~5RDIc@p&;e`2HobzaQM@A+gWWZ8EMDNNKES-rwf)? zLNjIq=wAMfbaY&SAck==({Q>IPkbhyySJ4(7FGSGk(GR62T9uhPkUD$Wkq@As~dP-K+`nPuUQ0HY?VA2S0u(Z367e$ z1p!|*5)IMgf8$yB#ud(ghb+!p$*Dni|jkiQm?7k z)O^3+z4ah}WX{Z-GiNe$UUB;C%X{_eRej4{e)o63E`?fYiIM0?C(gRdj9u6`*Qga^ z%b@0rn*g2VR*N@cUa63<>l~?+ey@{UGS)^fSht&1!=Tu!hE;TIwqss2{fAVf31oUB zwl|(2rax1AFi?P@yd_!beR?Bw_lB#Rm@wh4k=`>#5q&~Dr^F~qqs`|-x)svf@GdF< zWpiBaH7YGU!IABY!MaQB@t2qd$Gu^IsP2TcSx_*EANNfP5if3H=>Mbw05s-A2EK|? zbmvH4;&Xw()D`ZJ@PtH^vuQ|M(vXp~n_dcWDaToA<5$Jfu@YUu-oHlM{2Ff8A^zvS z;r?6`!ex@I1j;KdgDmsOpDh}`;0d}*PrddOFqkgpb18dcu$9ne2C>W_HKWW1bT*!@ z(F|)K4S;0EvrMp7^R2yr?S*0lp)}!!iNj@-CNqX}=4jrgITsyPPazySv@e-2niS3< zoH0j1jV4i2b(zgPm~g5mBO@h`0#(fRpi30U_S z?K^#DGvqG|hhynf=(5;h+%8!vbjl7p4?d#HX`9^Fv7sg;M$TgdVW$xqTkR!wkuaW+ zSupR8(d_pzFSSzB&s`#HzT>mVI32{R%WItn!th-u$<_?eukq>^iPY8R zwD%D*haY<0%U~I#)cqq&qxmd@-o)-^n_~WW}m7fr1qak3YplJ`PL! z{t0OBfD2ZttO}aTHs(Czc+E3f+)wp@;fdU@5=k;ovzNQe=yxrRd@eql*rp1dLxmtk;&fzaYlmay300)(W8ofMxYxNtM>~ni4ug z(o0qtDA^SAerf8#*}rBi&P+^9e!%m6#q#J}`m{WrXI#x8nRgFu9u~u}0~qDs3d(fKR^f ztu#t)daP*DXAMK*>8HyxJ%Z8cg7Qp3;HEDu&pZ<=`aa+JQF*3CFxuZ*9&8P^^fG~Y z=X82!d;}IWSGf7QUFfV&`E_{hQxlx2gm;;Qs)gMQ|LCnV?Z-6b@@j@l`##NfY~{2h z1Su=TQO+h;2>q;!n0rO6atT%l0%{}mXQIA_sMdO_neboC%D|!_?qIx!chrZtG^|4; zV@C07@LW6NwF`_phLr)Sm#&V^iE3RPajPd+$18dn0mG{4w%VLho601TU|goH-858rtZz}#1OUKj|?RM1F#;YCJb%Q;ew#>}6Sh4Wch zPjm4$sZZ#I2#MW>M371;NruBRsbfiwhe|+0j4NvfL1>R)JP7R(qmAjBPIx~9y9TO3^ zV}`Mc_6NUD7y7^7-#Da~za>-1g_N zWIO7-g=5jC#^MqVpL6tx(IaqqM^m?EqCOn8oT|vv4Yhlfsy!xpPjz!C4KeMuWmBs8 zDN0NscknT`JL1oX6xp)OL>uh7)PO^tYflH4^_?y?}hB0jgXIJ!8gfoozzE>(h4J z?-%>EIYcXa+0~5EWyh^t3%1kA(-YOtvGdxUbA|RdB z$~|b}Rga6>{92Mdjejlqvph$tO=bv^0p{UTY>{rthZne7ATKLls!_mrRk0dmr6fb8 zSwuNz30F(1TIv(2mnPZWV;a{MC@cRZ0qKRuepWh@g&aei-I}iVpogU_LS8F|ISlUv z1c5cc*V=@c>6)|72o=+W2#pnYL2~pp#_PeE46pi}UYogY7I63y;et4+;xx&vfw?!q z+&GFD>aEUmqWF)7+ebK`@5?G^KXk&efgyRXn=UPfqSnF1ute#a2;14@y0!NPeF z$3u8bgq0JXyUKk7KE9J2O=o4ax-4IizJ*ajy3`ITgPF0SmFY?8nQ;Zcu5!9@7K4|+ zTHI2ry>$(x6(;)Q8o^C}Nc8QX)!F5wn-0%t)^kkvJ*SCkGgRZL?WLW>g*TalJ6Urf zfpYI$^g^|bL?RKs!=y3PbAr|j!_CpD8Ap$^bI(ekJ5s|*QiIvKb0ki74Wp!n;v9+Z zrW53X!U5#xeBj_6CY=F{&TnESXpWr~-xAUtVs~J&-U_zs^!9fU*W2p7PUbtEr%G$= zBdtr*N-A~g$I^p2O%8czlW z5Ckhy0?ts&J}#9@U`(!3*Qu+}I4Gs`kr6$?_B-}2TzLnQp<6d zqo_WHDZkTudp5JM2nb2qd4+MS4RM_UIy;3LLE`o60)z@gK*?NozSg<4%6?%hBLBjV zfpU#|Z?jz@3?JkyS!+|H4$1}LMnwv`nl&kIS0`tNA_big^|1FaH3ceZWA(Hl4g_0k zH5`-;c?_Ia0rYB8wk0 zU2vEy4~%G#Go;m-SdvJ&uS2oDZ9M9oWM!il>%f&W+Uikd9{~|UmUAf8cnVq^3|r7a zW(f^#7V7SjLWmI^)G|vYYbiyk-piAjSe&eMA;#pTv}H`V&3YBgdWLUpS5bcW>fFXTK*!C+yN3mN%oux%{T~O`Gg7bNm!z*<0Kc8yCE%B zkf*$P^6+gbjfo^)ve4Y{VpqOD%ouCUv|5ENzb2CwQaQVFHlO%K8n>C*w$hqGEZrUI z4hL-LJ;Ar6oyeIw{XymWCWT+~8VD|V%NHP3wR176f|p^PZD4!r3V=063!6^3ca?yl zFED&@BN|P6Xtpy>a)mlLrQu$cN=P}x5^W2b&`Dw-e6EvBqtP8~nFY1aO3j3<;<>}^ zpsIjg0-Qg_9?)X>f-$ejO6#F|lgjRBmF4*q@CI$7{Z2%bvV}dX5 zf@<4i#)UW1645-Q6bbdWo%ha20y858lmU(PCHgqh<94{Dn|y^GYBNLMK;88H!|I zoQfooGfxAaW3U2WNq(b*6Htk2duTW4t+7ZCp18K#Dy?T=ec;O;XXr}MFE6X6^0R76 zB-GV36&N!$+m>HZF$AVSJ!`=v6A(#~7pir%6udRK>)+`UOPBeJY1&4;sySvtf(>4u z6==__&{@KIz4{QPPRFfI2va^+suH7r@{?Pj!1w^X(iZS$_HxFFD?-HK8jY|iv1g2D zJQ|_NNG#6+NHq%l9+Q&neh6Eauq1mJ#P^U7bhOaxv~xXF{d`CdLwZZ-k>OrtIHAlZ zEg9|?=myQkdk)*d3Sb^cq!!}T%)+OHkth9F;-xB?Z?9ZwE-y7q@P7G=ykBK6w3BFt znU7~wGFJFysKlOBRSVQsP>0Y*G@bIQ`i$*SC7Lh1H;)cw`Wm)lYO zXoQM|kltF#-kgU-=_yy!n(SFZP^X3L>S*t(oH-J-K|XicCyI> zLcG)Bufsxo4QQ^_t+rx59J`w3bo7=p!6)AB#=f3*uC*(ov#rP#q^DJ|fEsjpRsK zA@D|G{N!<7KUa(pA^+sLv;uY6(t4KjKw4nP)T6pgMFglJxX)Un2Rq$ z%3Foe%YIvb4uRmKPXOyrsh1sd9vp@C=205lFe%x}Dl&_!F!Z02a7mKVCC(5X_!1p> z)3Ic@N=+mlr89}f9U_Bnm7tnlR$I7LrDCDlGXMNxl#wm;o`l$6Gkajpnk&>{=PiCBakCN5P5f01~Z6;dQPf27tF?LeIl z*684@#!E%(5i#5(heh28V>Phh9KJ{Or-f45bbCpeZok)5wMy_gx?~dM_y~7AF1NrXy*xu4(VGynw2&v z)^t3frLSh;&#-6uRdq3=sLTBgak@jxc=;-l4wptP6+`PvYvMvgG~s$x8Z8{9sv0jT zla;PjvJMf*{W2v%mS9~w3-(ADJdC>bG{FR^ipCwWx`%fOcch+73DW25F=A5WlV+Ja zUDm9`BKJe|zCCZWoo*eJ#W^Vlj0D%s(X9}6WH&{iM2a|b8~;jobRhUX5D1GM%NPBSyo?Y!$?5T(OLFBfNI8GYGTnVy9yE8w+$kwIquM#Uo_X zvxGq)2X&_tLp-s%vvrG&X4vtAQgd?m zTVc14qq3uq_=8I{cTgfkB`+(j$IS^pUEK0FNFXPDmr?HusNZ!flmSP>(@{1#Lf*s5 zvx|Z)htvJyy+7TtIR=_ActloLsb#CkVmppX%&)b;yO){?FxM4bD=>Bo8MW$jCG+m| zxm=I-^#!_tR6dz)C~60YIz!qivMC16AP3iR$34et+$ma99c7EI10<0$Dor3G5;$e4$DeN_e18^Mw{V{MaRZ;khwWVD1X0aGQ#3WnMo8 zaHTSj7zh((%x(Rx>b(7$S@Z0m#;E7ah5n`KQ}I5>>tcO^!STAxqCT;6Uu;~~)ct`J z;|Zp_kF_(>eyNVmgDz1ISC?R(xH>7SaC=k1+5H!^#yg~X=WDb&B3-T!F?TJ>m$^LF zUK-;JaaCJ3i`*JvfyUtDwvdf(B8=9uSVHO9>5X*-MHhUGiIgdi`IY{Ye#{N-3;O$y z2ipS64Q}#Rlwa=#cl7~^ej!h69Aci|ANxUiQGCm{G5IdScU=p`@O3W=4R4m4>yUC; z*_B+SmZoF46Vf~CfpCp--F|_chT6ap;FbuYSgM7}0F_Oy(_X!JR29<`L zY2C-)Q-HPb-eUR$<~of7=Pja7uxP6CmeX0U;jDC$xP8K#2+Z0VGn>VHsD@8&b?KMY`pIe%0;KSEZV&bSi;(_qaDuG34V= z*3ICZAC)Zwm~dU8dT$RMV54!Sl5X%cizc2XVPq1EB_`OF6Q^p<*qsq*BIHC%RoWeScPxa$nEmu9N`onFuIhf>O@h0Iv{8H0hC1GK#lR3#rnzf}nzT_!CZK6b>3Ul5nVC|K`+Nq(6)_SS2zlj!X16 zQ0v(k2Of!TM|Mo}vjC!>1rP&#){GZ7WLjZgQR==a{7j7_yi|46whlEaM6y1LJ)9^C zq3gy?8@i%E4h0g6-k3ue3~(WFqq2nej5h&J2NDaU%pas06exb8ofT^q3*}6*9@~+R zZsAoAlO5E^(t8j+G%XB2H?f&CD3zbpq? z|8GFnAJ<|3*bQ(vgFJYgW6ScvBwA}J^>YX9mcc( z()$|Q*Nb|FLcw-i$DDhg(wcXcNj5mQ!C9=(9VjSq$LJk`;2b7YWCvr7e;2g&ZU5`g znt(A5VG1^7WhFP&rLhb%b0_L%!6!+0OlPsObaqCZmQD5UR?1&7w+28#8@aY;gvB|S zJ5_Te+(klRn;EsOgkS9GwtLNFZK^2SFoP$;t@C9A{fZaK10v%lj=S-NAed5R-V%4C z(m$%>WtR9z5OGUJ&H<;%(F7!mmYQXEc%Wq7ojZ~i#~!I6%7N@6J`w?1=SaroTBQJ) zRK9nFQ$yg1+j6!PIJ}0tu|dLy^Q{xr5<{97YqFB3MfXO{u3$<13f-8mlv@kvR-};% ze@%D0H;Zp7T9m?B_p%%^^06_H$GuytWUH*b1C(q{lc?RcZQHhOo2PZ!IBlD!ZQJ%~ z+qP}n{(IiJ-`sCz-kE#vtiM*QSh1hV+BnGrB6QPF`8NG>(1!4lxUn?uJJ z^JJ#>?7Rw5vM6;u(Y?LY}%1Nok4BHH!$&Vhc6xAMoIapQm>oM9i+VEz}jB9W`N{G@$@YT zw2|@2+$MoHXw8V9n)_Es@lC&M=pR$daORYIs*b{f)4^3JSmvp~Vgj$H?-lSkK`C0C z@Xe3%Z<|=cJPSBJ00C{@d-39#Yd7E^89nsFU~h&F@|?hj_Mt~qz3WVEeG0Kw56XmS z5|3CGL;NH&J)`v>*6Lobi9VXTf{Lwm4W4WF%gWIadD6^=@1Zw+q5Z%lYc{OEOs4o( zq;0dA?eG8>-C8AmZ}iC(v}F}Cout@v@(%P78`pixh@IQ&KRTQQy#W7!8ZbgnFu6^Tsl%-6Oh2W?pyql3U<#l*(W z+I@y^$u^5J`vgxu`O3))I?uLvtc&UB>DuSGIs%;iZSI3-i5|}8X77`BXnmWz$M`FY z0Cm4bFqNN%0y;P`wSEGf{>=s_ojng=R-5>P!UuH+rR))2nrzRTG>75m{@^@$#+6!L zM_b$|n1-UO`)OdQmfaeK2SFi+Wo52BbGY$p`@VrEHb>;7LmA1f$x+loH`&ApY(*LJRUQ$wZe^jhsmjEjbn94_T6at@I%fP-q?XVwZ4ZP&bG?nYoxb}g;8Is0 zuZuyeC;IEI{{i;i=XVsHoIxjkS^fQ1VE<@l(og55i}aRMn7#E_ZhP^|VceEIpDzeF zYjHvvHfO`!?)=uqH$s4)1roS&mysmom>;wxi-`8ru=w6?yc}QTb%Pyvoo&(gevq_9 zF|K2yB2yEes+bNkKc_2eQQSBtl)@y4@UwgXa!OTf$p-LI!#?4g;_V5frrJ zX}SZh`bQrjNY={vZMFb#HX=ZjlM$BvftMp zQ1g39Hf3f1x~)(<{Bl#{E^jmU&`M5!q&hn*`UrN)H19I`JkVUy{xVy|p6KE^<37~S za;kUAPDC${UPxyP1y$4Y)BTaoaj*2oM9qH{*fO}qaVz!EWD3jw^zcqzd3o4@f52Kx zH)d(5a=dbPHSV$48rRi@jyG~;LOMQ0a5vZU?#RfWIWYx#ctmvPQ226U?(M$)-sJ@U zGS@rzVp-|^;`4`Y#AoWgbL-u6?EU%h%jeH)ss~02Z&UI@^@u`wm)nQOi}@YyT!ptM zZg%!hT{FI9+s!uAYSz-x$2yZLO^YfA=Iq=szA;Fz>U`BC{_a*mpX41EJ^Au!o$_%{ zeSOO|r}#!*o-BRetwmW`oN{`-qqpab7n#kc3fr_ZrwQt&v^`#8^n>iW)%~H0L$N=1 zrxi-nF8fjc)(46I+XIKFFN%;PUei#gF`t)Sn<`s}f9beB`r_W>R3czsTYx>VsJ?%f zcargcn0Jzynd#r9om|lHazt4`?P`m+LJO7j1yK+X2kEg!0@eU&q)NLr2>P)sDad>L z(bQ{7WSeV>{5+Qgy*pM|1->Ihcgx49K3DI$^WG!# zl9W@grM3Y551KQbb~!igh{D)S8rVX@O_#!=PIcZH97)NW$tRpbA*$=mqs*Zze*3H} zP?jF%unG8URM%gq9PaYE>{A)K;!Dc7q=}WgOshp!g_$sO`6+j3?oIVyR0gVu8>7b_ zP_KxnY`uB=ye$4(IGfS~K~K%?LOs22I-R~iLHI46go)4ZbXWPmItg(ELS^cfrTo)U zwC07l_=$}bn7?SUqHi|_jkpFV$L$dhiQe({S{TN#d7@a!<`AX=OJdcJl}yuEMedMN z0>l!nNj3BeNtDfG>d7QnpKb_;)#ArlCAql@Z*Rjj*^Yt;hj!HC4rEVUpwH}n`V4hJ zs`NdH9G2bM#;3GtYRS}87>O62;3yMMTUAUM)-cd2ti*&aNM}LbTcBerxt=+mv9X3Qbztw$8dWfQ*D`)DilwJ2 zbrLx4i2P-5gm@yKvL`i6K{N}j>~1E-O_>zpQpCMRbyhGi@mMP1s6|u>6q%5~Tv$L# z4arA-_W~n{^QB%Oa68D%bYbkqBbz(osowgIGI>ksoj0x)xWpAYZURerA}RCAHdkpK z??i5#p~mOZLbH^ebnt3Batm{qce`P@Qd8kb-j>VbjcAVCqMs0rahCBr>N~IQpM2?Y z%Tywx@clHEZ0~UCsiH9qKNhB>pOC_9n&V089IdQMdK($oJ(a~sRs> z;+n9;31x5+IX`qvaTwuVc!r_d6=l1*Jx`NH4=FPWN7F6R662&*7C)3}y7x;AF)-3` zXVek%Xz~rwtJDcYAEHys-;ZC|T*{$1cPX~ollb(5fID4bP&~wJy^&vWZ_1OYFNu(y z>>UNlNXxR6s)bjHMf~i863w?R!-FR$auZKLaQJ4J;gk%+SVvYTihY=cB5wn`W zuuza1TF@ufu4w`BhxDOHK||iavlb9lObV7f&bnx3-SFnD`P$?(FfA?20u?WQK0VU4 zcUSfFUSlsps`2~9bqc2%f?R9iWWiE4IzahIRG1$AAkm0rWzbkE62E}OYVQwTsftlp=!~&%I7X=*OROO|C*2s#fU<0>`K@KSL8IOF zY-lIRh)uz~+FT6{Z&h$yC<_X2pIM{35uFw0{WE1exjIv(67h+MlLbjn)ws2^raMjH zq;da*aW9N!D7@ejx8TxIz+^E#V92(CNOaJ+Cq=uC!9K8)%<07ps2VH)oeim%Y{JuZ>7Z~!fcaM4-%nOLbmYI-l z64GJDCU`uh?dHWY7;fE^Es;~8)p%T{RVVoCSxq)ZyN4voY>-vV+6=c zeCa98%06tNl7@3i34g)B*fGbSiGS2vVO1KeW=lbZ$aIxXri zL4U<7DmG4dO9W2PMPc%(1O*~3CN<>ef9St8`eBgfBU>VyZ`8G zT6@x*As20XJ!>RAa=n;La(XI9U=hO^hEU=T5HfDe$=P`<7s6@a?xuBVA(WO3{g5%s z`6Cj_8-rbv=obz}HMlCzjSceB=p^J>p*yBigM<@}3c?lmJp9Kk`YwW*DHwq_W+?R7 z@IZ-bXaadxV%ywoF7O%2$fKd>a5@H!bc+L$NmHa+} zSxA%tjFKwo*hbc&r6aWT-4qCI6*P0I0Nw?}QXH%xpQp%h{9us~X3@TOvHLhO4~d`V z@(A!324mA0B|#m+u6EA^peZo@gyI;+CYUnrHcK)#kuDG>oN}R@+#(}-1d%)}M92YM zArcOD_8UAZMD51rcW6*Q(Bwsktu=c{FTzxtlWwxAn6PyA9=3~!!8EPuM5yeR|&07_l} z5+DY9fV^bluOWb$CsKE~0g4A;mY9Mb1^nqMmlkQRBgj?(pyEa=AXuQYcse~JQWf7q zskdKQz$(*P`JgM^B9%SSL^Q}OJzp9qu%^U3PFOk8m;ufs0^^Tmpkh%lW4)y!ZY|QwL)DcI;tH#uG)D?ZxN7P5e z3AuCk$~@DKXkB51fStzKQr^dy9HupA3Si)EsqG~I2~=UKp~@Ze;RJK6{>D@pa6moL zBqUVR0<9w8*s4w6iy{VU?q2WZgULCpq*^ts-bCBAPu1I=Am|xkg#%z2eZhN_VuDnC zp~-yKh8K@Tef?P4y&q7A(4WGj-S9pMHLqJmnHsYrJf#OCJUd@({YJuAxm--57P{|4ToVb`; zpQEHxu6O}L)C)Z2hq0sc4+yz<TDl{yY1G{wC=muwyv-# zU=DzmxTd}6zd7Yd;E4euAa!ot1=sHjS&itZ90-U8xx|X&TZNbxBW&@z^8(E7?lS((ey4c$mAxM=d`J&OgcKE(&l@s zk(P?Sk6>cy(qqx!SJ{0E=SR6f;yD&?inLLGqCzs6$#D=UmX!mYGXirSHV{>J`o zk2s$m&paS)RAoR1$L7j4M%g}=q`vmpjyY^J!7=Zr_~mZjcDIsNs@}-3!WX!omIByo zU>C`oh1*mA?{y!)uuU9`;2Y0_fDM=3m%&qi?E{(GH}R6>u9O>nQTQ)XZ`L_;Pmg1= zPTucaku*h4-!@vOTc*oq(--aAm%Us4yXvE^3HqHr^p@(MxG(=>58S-7&JmC5Ld$(- znWYc#F48>XzZ+CB{SOCKEKCece0)$2j`k)7)=;ji2OQ?EDx!amR30kfgowstI7p^9 z0&Ac&Cxld30&5`pkU|ZR&Em++XHN#@upo%!LHZ5m0TqqKMHeNALVXbk1T;_&{QRN) zY4V~x>2lPDpbj%VxZ_0z4mzH^?!4Q}sx7&tGYf4pm3hsUYXt3}d4O=NPC7i+)L2)N zAiC*+8=6;()x~V@obTX#r;z~|+@_~fT#s7ZhyiOjCx#ACR>?tK;NZwT(}Ywz`?9e0 zIDhd)>KA>dI;2g>e^zH9^F~P2*WhvL2D641(9j2{w9NH7B{}C$5x@|Mv|EG5t@Ij+ zIE+7L_lYYmX?6zhNB*MnUjuMb@%>!Tw!!u|)7=6*%09u)E`^wV@{Kmt`Xgj#&4E8w z6+nj)AV7%KS*fPLjqgvG63xoNO0|stqho}OHPvUfDK5)Ft=dFcYtxT zv_ik|vPwkNSVjkhs~m5p#+E?Ngl#$s0t@VW5-s$~pGY+Do-BWmf8rPnU_HnU`+vs3 z0-MhZELCP*dIvZl3i51|c}G%$BL_`ju3HWc6GHz!gBN#rAM@q6q$h;;F3tonG`&XM-?|eKm}q+h>9h=9t=F;@&7j|f|*g{?7=#U?9Jc3A7fvgHrOqae;%koT}u;e>DI)3GLuw}Vu z6UK=ORzYg#z8egvb2apzs3E%;<9$LIznSgW_=2XknLH7fj4&^|c{PHDu5sTH=yy$@ zQPuWf(fYM&x)`X>x_338&IT@x0yNpM2hM4tzqhekfu;9-PNLNeSdnUvvDHpkaj*5k z)y1ECJuD_AtNfPZ=E|-KutA zLKvOr`)~l=#eMmzW0{d|Ph)Q-hu*>5GG^%HqbxOk`k4AIV-m2T$V+5BJ0z2!@4Ml` zHH}?PIvqB{KsRyTQuX5cfhq2IMJXQ{hz<89au$worBJd_*ErTyJak(UX~t@X5gY;*%` zo&7)Qo#k#t)@F6+(gEq}Vi)1AjKysleg&;YP$$q0NaVD^9VvD8UH=NSFObGsC7cv) z1-yaueFTsO%oc${ssX*m2dE}e^1sL01`3P{g~oIQ(+PZ?=!)Di^j!i>CeW>GhRLDc zw$Hitr{?(n2Rrf^C?r!L7vA}oPQW!ux1MjYZHvHuy_E& z02<(q#KN{YZMg7&83H^oj$?a>fqbDu7@|TvQFi#L^At+#{ z=la3~S};*^@RIKyjC##}6n8^KG;{hA6=k`y0Bb`^c;Mmh~SA<3YUDT4@okGmEJ5u8}t1GZizZMvbCIz%nlcJ~1K(8i<<-{t( zcTjz7%P}HNZnS|_<@L*9uG+~8=(bEJlMM})aD!Tuu{}*h>YsdUsj>#jnvm&(c!qN; zeHC%UrWp>%1LxlFe4E+u+u_d+o{ajv$+sq+occZLxB2fFJ^@`L(RWSHYwsXkgVlGo zFD~yMbS>HHclgb_tnXl7u}f*)^Q-fN#*CV>Y|7foe&(?!oZo5Yk>-@N>X*p1q@&r;G}3>R;O>{w0@zjvo%ao7YT27cSqAdQV& zpuTH)6WL5w6>dA=vg<(@q^}Z=ABe=d8~m&|pVkxc^XK8ucui*L`V|~w8^g|lcX;vP zrSLxExMiwz%Uidbw7g5Y+(Q-k#d(a{nj-mQ(H0R8F&zczh8QtXxF?rPL@MwxHYN!% z+nO?#nWrA_zC9upyHOKNqV&u*q5yt3>b57T@^VL9nO0EiW3m^mYQfeV#C0StJq@N-JCnUgkBIKu)ZTEAazAJzHImH^m z%!aNTfLT>7nY0gbu4}*DnCdf0AD&X>4%ebKZs)?M3h^=d4v%9r?6r5x3`-_I>O~?| zP2Uw`pr)yZT)?uz^PV{CB)&!C66M}Yv=?;FBHm-ZKqy2yC{|9U*0>POBoP!8J@N3^ z=5W6F5v@IcAtXA{wki4;3L$aNegYd0`PpaRY^7YU+!(t;w9h^U_Hr9B9ll1bM&C$> zLz4eNUz#FV-`^Ui$gM=AVr(i}q*nSJr~jhTWEO4JVgECFQVoa0$$si%#3dRpV{sXe z`=cpFOi^Ddrj)5M9EFO>?H)ru%qfXRnQ?b8zb^gdTF7B$_JWvRbRW6CVJ2jgzpL$b zzw~!*>4rF*bW<=*5_zcTnqjUw6-0<{C zY_jSQ#DZ`xlv*v77!xXyhlWpX96@FozA9sxRniN&l;&AO-Fumu{3umi;RZT6slK%; z8{@Cn=UzWVUhzx!Gsg0+1voshFGaYt(1tHEjruy9-&4p>Obu@RlW8Kf7-=Mes0XE#w?f@2|MR*n$~50d72#@ z&USd<7CvoVQ4CLR>L{3BC<-4@in%OIWtNW~2pc5UJ*e!snQ4|T_{a>*XRwOnVqIqz zM(yP8k@&6Cma$o{DYtCKnka&s>lyGhoHX*jEph~F%=4v5*BkRrQaE%W4iJ-T{0zqh zU9t2KH|B}SzN()@QY{PMG>+;i5yGL^s;#bLNybo}dDkYA`4V6~VI|_XtusmDD9Ohv zl<5>cJQvIeFsXqeRVn3em7Y$J}7Q= z^ouo;C3y`E>gjfANG~)dR=qH$R4sK?(*L&<26vem*M+-;6Z04=>xHmKWC_n#&t$+= zR@tzWBrYe5?onYJ?1*VNHR{`xM$|A|pJ?@rk^M=^Z}_u<4s|+G%{I^bOLjF*Vcf7* zgif2j(M*rUSExg6xAisT+&z{R1NUb*vZa5{U_dN>wX_@rJ-^=C0iMmvd76s!Nz+9;vD-( zDv$Wf9jRKQIo*~OA)S(SGgZ8G7`0Z?*V% z*HhRAW#CdZ4X@27>0c}Af1#b2F1Q3!5`L*Txlb%ms%w`*)HZ(+_u=6f#mj!(o_k)* zCvBkK(ShowCqMfkA(pvC&p!$;M!UMTvs#}w6S@SI!_}GVuiQSzqGCU4N!?L8zw*Ou zw4e3}E%lM^c`nAKt_GapYc(=@?wzulB(1P==B7T%R@>^ew7$DhZ$K)p`pDQ%J&MFs zYQI(oVSUlCmcQ+V2tucwv8GUUu$K@WL_^LODJ|67jrLJa;R#u@se<6E2BxY!42|NzbmrnwUJ@?I${<`TU&P9I5hH{?Or}b&CQDYxE zB8};x`+}l*>8gfKe^b`8!fEKF+%yaI{R-$U5}wB&^g?p4^Vi?~$^bukZsYkiWP29g za}V^IofYKx5$1vXH9`IovV}AF^OKSLn5|^XbV=T=mVYY)yrX?>tAFe1{Zh{>my_Oi z%?1j)f?xB?2gOt5>uk?QaO!hnYo0FjmHwmwHs`a~Mo)46H2wJc&`!?&66m zde7H>!rt-ZJckXm(qaCXpo^U+WYgb?n@89~;@JOVNCOceu?)f$8I}97YMC0XJ2+Gc z1%$Q7_bHQkO7H&dqa*w2X$m?!lheiJk%zh7VbWppyqB}G@(5x^C>wz&!deaGsr__j z2vVq@L(tVKI#>I(4?WQI3{-HKvr<%zXeyE?`NPJfi=NkX7vpBu@+*r1LeS<> zo3+SdjtCyTgBD_EZ24+HnPx&J>sMX!2z^byGZZ&su2^T^KL4^JkBP-q#hF}0*3>=k z$UM6I!cW<7f(Ic5FzR0J#?nQ9=~u6Fmu!N-LfNy^@1O@rB8y#$=dIchc}4zq>V2%? z^x^zBQ!&Re`pcN#kpb55^IzXU-Q-_G-i?INKy6L=b%nO!+sKXMyQGF8HAkwxQ0qc1 zU#GG|B?LK=lZEW2#{^v<3}oE1KT!Q|qZab6+1qFWgA}L<8|0s}wFWa8KXG3+_2BFn&#RLT6JVM*oAfUUK5r;rX9lMId zeaNRXEdHz|4uRIpeS)44N@kEvp>>45=ruO@Jw0|k3MyRk!>MtaV7}gdo>B8Xn&v~? z=0_ZvBUF(?QBMn3l=+1*Ld3ZPV%=9Faf16T<<0<}nj1*hy%l61Y zJxRT|k5o(YwyOH%24^8_wQObXRGef!HmKxk4(?tlea~|4WcoCf4rn~*V&hLa((9Zo zF=fLyXmW5OyZS)k^XT|WWt2`CcoVJP>|1lXOX`?}F*~Pv+vmZP7`+2yy5Y?Hq3g-#o{9QZZ7uVR|A%qss|I!%86xLEvCcP=yb9d@N>Xep=Z`s0y?8la7~%HX@VT+x9)P!rjUgiCX@h zl(9Xn)EJIeZy4crrML8FAEz#dd`dr%(c9NhJuWOy@Hy8pn}_UO3rFdyuX(JBvcxLqhJgc3ug(lnfr8m zj%9!iTr0Dg=5$$(lOQ}eFXp}Hw58w`h!@Vi$#jz-Kj;NC7s|bhok9&Y2OkG32X`|= zGm)#6o$mEWkNtJ?c32NOm}QT$f1AH4h(4;PuAR?y-nNIoI(RiS9*j59bIZ1R06Vx3 z%Dd<_`*%X;Cop^%J{+Pzk-+|-g5dqYgrEqxQbr(%iwX=06b~W~HVr%qNe;$G zzl7u`Y^QvWxOV89g70Ekhq{8eg3LzlBzP~nUh7K^u7=RZ=0o^&eXifB4(!7HGu+ueuYG}P(u4}~Uf2&F{SMPw$b`rS;I z$8V_E&x=@2yeQ6tbfeM_jaV(-j(sE9ua3ASdj9*FbvHT`QN4zGHgWrVGf|6_PQFgu znX7vKnd1^?726Ui-JDZU`5Nom!cpstQ@UlCWy=|0^3+3$W&D}Rl6DomPIlX$7UyQ? zHn`?soiCAK(LoV1@t>k-B1z&=VHJ@)ly#)H6~mCR=ptpY@x~ps@=iCg@H^Q@}bD^bPN}R3^aDqDry_C zb=6->0}n&AzuU-doYr5P#douQdk|heG`sBag}qT-wl(Yi>Kgn&WJkis!N<%-$i~Y? z*GJ-~()-QN*U9*K|Lm~4wo4zzzE>T36_t&@sia24)D zgYf0{{^uF@rfmmLi?;B(`sg>+A;ZAbk2c!=vjx3C9gq)1jxQrut z5^0oNg(MGSE$7X6{~Z!JnO;f>shs4wR7R|;>aJ7RM_4%0m84E)Gv7^Ye=(B2geULK zM!!5#m()AmFZJE(FdvdA5>RqcGE$O4@&nRD(nwhg2@5GM>QdH|I1=tsYIC(&|AO@R zOPN;o6TgChdsll;dog=Kdy~2ZPs6$l9=?}%W7Zbl z7H&72Tc?pGGJ09P#CF1$+Wn(AeR*$wH|g7^5q@%f3BC-Z45ZAsxVUtsG$yh_zCy-> z@q{o+^kNOlOiE_uS0%I}8mSg~6YFn3TfVqGqmJ_+KB1D5zvx_&Gr^vOm4=m$m3JXi zE0(G#D`qv$-PuC>l(f{@LjAO29<-Fba5Jlw#YyyZb>44&NI6^9i}c}Q9$vYrz&rib z;nZ)w&s<1LL`z4@LQ76dakZo&tpRy1ZEjMAo8DS!)x_L+b-rPJbjK&>W%0ky&==wV-BteR}Ouacy@1AdCp-re3p8yeC}*cUQ&H_ zO3qfci$Yi4Rz5q4kJ-!n_2HzcU@Otv_BHJu_9VK{R?3I-qw*epmS27=sgu~t<<;*# z_uhx8m&uSRj=7ErifNR2(0Kl5M#4J&w3yn=onyU7vt1S#U^r78S!pThfb-`%(i3g)DD`5W#dk% z@TPpJFP?{%saM9{880S>O{x4Qmt#B$FD_~dNz~MQ)U?#>B$k-hbwAD%PUPmN_IcxnF0C46`suJls{@uxf7f8;LJYs%)IlOoZ{>{cu#d8 zVJBgyVrOJ0X6J8Wd1}^?zl3a&Z86=?O84--ENoG;5x0@Q%vc9)VL#Z+YGZK`y$#IXxg`#`e1aCzr1ScYx!)yZeMOsXg_c7ZU5a~>*nM}el+5?cT0At zn^JrrJ90Lf9_ymI>E!m|7Jhpf9#Yg)y?)~5ee*f(j ze{3t^%l=dQ1%KZstBcl0{PXf1_(k~TtGRET@zU5OsjXZ05^t}{DSO}MSN1{Hc4v2G zD|s9D#@xo;`ckW{^VW&pq27Vsk@xaP!JFHY<)zCyep{EL&)IiE%_*oaUS|0U9$3j>hc<{~ORv|8VFC|1sz)niN$#ryf|)CNvtl=IZTF{}3oPG#=$^ zrJi)qD|An_n#S!Ae|@M&^mkRe28ITPR)$iB`e|JaHICMrqU-+N!(L|SDe4RrSIt~q zj>eiMJDVNWAZX|-iuN`;lbwK|fFOAkKJ{mdox|Q}s4j~4B0JNa&E9~Zknq5~(7fin z`Miw0yu8u8)4bO_<=+W;_2F9KbX2q9tKmhc6Etc1j$SjgqAsW#+6_f!!ZZ1z^5`8J z_hK_1qSebbmeQke z>)79jlb7nGdZ{v2AE_qwNr*@QOBPEaODIY{OiW6MqDqvCrnjcy?YPgF{WB{qH8D#q z)h2D4{Fu0@;jVoWH+xVBpYSS$Prae?YJZ|#h@arC*IMZ)esVbrTqs=ll@OFTkU*Mj zl8Bm+m>fx2PRm_dQFvZa2Wf(yP-+rC#x+)yJVD*|=lrmadn_rjl1f|s(QYN)WGcBs z?NM%J$V5NM>wCA)N@tz0iBB?kV%zB6*xabYSom1^=)i68t@4;WHNO5OZCCR;MOXX# z=&j~~dh(Wnx8=+3?c3-Ty-$g!(F^kdePWm9r}vBLf%cdW#aE%H&x`(nIJFRU9(5cQ z6ZJZ(32HvI1(jTdSrte9Zu@UZ)MV9VRAp*+>O(ah<=UFvsNZeWYHBuQ;(I;lLUOq6OVI4Lh&s7jZssZ>_F*PXtUEtPGS zzBZqZmD!eim#wNhm7HEF3g+wN?~0>G;4!y4xQmC(EUc_;EX=UXAj;WhZm#e-pD&9Y zx!i$>b66Xisuyoso2xgt$X%uuVWQbCFV8Md$VFTpr%85|4@HTpMoNj0vO3FNo;FlX zE3jG)-s_ERlVZ*1TL>(KmO-jAm!YXJQ3a_l2$X|qu}+tfey?j~EwNBs7&-P2f+F`* zhi$jmRt2uca$V>~_9F+92g!oqL3Aa$7TFGSDq-M5-1~QwWLpv-4uAwu0w@NA08#+S zmjvM7fvnoSm$~Ejr&QORE#MEl<0pYG@K@gHD?e}edyjub)ja|h48K@01Yr>@d=-EL zu?Xf_WcGDWUYdkir}cq9{!)!8xmx22wD(IwKL1dLAdMJ;v|SYcRao;M z$|z+bN=`EevDibAI3L_=H;8XOycj4FXL_A#(|I0LFy)OIi6Fjcoh*|o9N9a2* zqW@+tiZ(kT+UN#qqwoA@Ghy1z)dg`=H;@>8XIPZO9x+PipUiuKRPa$Ag~J}1?!<7r z10tOk2z9#Ne`n%>17?O$qwkCkU~Mk|z(?r@ilgt$h`Kt~f(ft!lmQ}mwnAjn^%jR; zpBU2mS^$EW()Ff>+Z_^Rv_SmBY;T5GqV07Gx7#4nY5FHq1AM_rLH92eqPGN?3)c~h zjK0%9;119e7XBbm0xrbMr4J9{>RgKlaeYq2(*`j`*IOSBd+Y?9z$$==(+&Yn&n7_r z-o6ZAVs}mS*Ku!8_+RES#KQF*(feOTgiMKxauCa~XXH725GVBm@6dPN2gnFm0COQB zet;lG5cngCF!)1=A*B0)8-A-Lkan_dRzUayLVp&Km|%!m1VJn!31JY~&>Toa7D9hA zk?BB)Gz39pA~T`Cg@0W^^nYLM|J_va1&2fE0VLuO009r(20+9i@CO#L^DUu>Z)?O% zVpJ9X!LQ1`+7@}Dd;w>P_BOM&X)rrdnl`hsFapvliKX3F2kAXm`y+JUxqR)^{EBn2 z%x@O@(Q@>DazyLtz7%)W(Zba1OLf6tN^C%!-j9%kArK@urW*kXLkLJ%;s*pI4B>wT z_rZ|tfgxM`0>5{l+7N^_2AlkGaWt#=k`M+028@^ZfdnZ-EE4!> zL0+U1ai9l@96ZQ*Vn25hg=mn|Sb_foQpK{4tz}JUkj^ih#4Z+uF0NY?saXODU2>ZUQitUK z3@wz38XW*xNc@6Hrei>`;sk_|?9m}x!aBmhAbcKa6k z{-n&&gfdG4O8d)PL7qN`GHW1)LZfy!^MLp(3W~X10G4y6MPP0C!!0j_(Dy z=n5MDEcgl<_!#P50uFyG!U7KeNtoLciVv54qs@N-lmU-re858Z4X~?0L1g(VAR|}+ z3+W1!z(c_LIxgBfIROw%Z=H7ERRkM7%yX&2mT9RRbDH%7W8L_Q@#G-F|78-i-GGQ` z;A+q;_-U5HRbZJ44=W$32nf~f3D)faO1ho`qq$ju?OgNzfPly7-J@{)$vq8{)(weg z=MSE-4M^_V4TM+Y3+@&QZoCbM=_&w*=js99-T}V3Id^OptJq`Pv*xjV!F&DqZyeb6 z%CG6E`){z|;m)`CjXiZAcx*57+MVGUBm7sAg?7}k;E^$RjQuB#XW8QRNBKyARp0+u zfTM1G^Le%@;5kPB*~Gi`4Y8;xR|(K9#1gq@U6`atL=}(G6w%^Ml4YVUD@7=cDY;fq z6c(jLbyAsEo)HiwMwL}zQJxVBk^w!5m&}%VHJ&Ap=S#gGDUc`gV){FzERikriZWXq z!xwZF&id*Kc0$YNm$jOzi*q9TiNZD=yq=$T+ z_K&-NHKeO-x8>g;Fg@n$G`}U7_Mh9Vz}1+p6Wx}7gZ?kP3EKbGllWKH;vb#_kB#R7 z?Ru!jzxWEMOS4Lmmg@x?q`AFbJlsE3ajDkzBG=rU$G@G*D5lLqH24PBoS-AW3V$Z} z1h<@VU=uuwJvV~#G)2Ki@G@S7i8}$c+$GjyC)jHXUv=R2e|fT3gSoPHmjmj3BLEfP z94vqZpjUUOmS^ODjT}hw0=<2) zN=k?zB~=H8reaQjkfwDk& zAYGBJzy0F>4DJA?fO+7rf9NnpNC*EKVW7htB<*W9#z=%XzF9S#D}!PSoU2oJIj|n?^{KBqe7pPh0&q2+>qB=rxE}BIso&qAC4hFY zZB~G4Kv&pqO8`CKYb@XYjUdF01Bsb>5ixf{BkV-PIEaXGViBW;|AAX(X2QPj>Hm!W zi<18V+to7ZRKTE9|Lf`OnwfB_U_z+-c1Hg)&pE#R%m4bS|KVK!sLcN_So7QA<^gqu zx^|^gsPt_?VMqo#RO;4&N|6S1p!`7xI$r48l299!B&H%;lJ?h6{zi}bfAN1S+$;sC zPPt75s#EA&j$)Sx{WEp`IlG@hN{0fWj2``k^qy0D&oW3qWB=00L9y;DKi3&vT4U%hyBzB`J0@L1~Bq zj#2!;1f|LMH9`5G!}dI1b(HJhKzfSZ)KIRXfYlV+sG$E0r8)w95&i!AGT$FG|3~-Z zv5NwlRP5%2;t&TsqS(gyuD7oP%KsS>V1pXx`&yyIL;}?*3a~*9ivg}s{0;oSYV?0- z3c_z7Aw>ZSCeu@yxN?{Kgzhfd{bEr^ zMGEB9$JkOTsl`PLTPl?~XLeo-}-9=kUOhTb zX}_?446JFh9(WZOY7r_-*9o{{u@vw7+`X-Byp)J;O3bM@6+xvD{|+NL7crevySOlj}5SVPU!^bX72(`EP0)VeLV%@C(`cbU_T_Rh)fUUqjY1G6>5>T!3p z8&+ozyS=x|J-chVyS>NV*)@|lVz*4Qx_f84yKMLAR=a6+=vMb+tJ~euJ>9rss@B8t zI^B(@@gdWgpslOBXB0m*Rh!MU^}2QH6?$NqqukSbs5IMqrgdnuNu1hcw%hH_Nu#5S z`osF%+pTr>*j9Hp`#H0{cS_gvUfwZl)-*O7J?@#^?Y+IM1KKpEdxqBWfA1)py#M17 z*3)Ba7|Tn^-Dq~P-cFp|(`!xbai78FwtHGvH$5dhjR|-f69P};*uQ9X^MBGR1P9$H zgztcC2QH&5mo?;bTWXJ1%F(-GUHw8>=5= z2mPzwHSAcwZ9(HuI<9c>1WykI8n8l8j?6{8|53pk{J04-j0PE34 zRzJ*iQ@fklLH`rPQ|x%0_32qwKh5fUS^XS4USh}d?4Fld{USRyu!H*l20LD5?cQYd z3U(}E$9wG9%-Vjy>Ua771|bM{u;W8^e9DfGSo<$n{TZv*v-(SRY-7h)>>m2xC$_R< z6+7-?#}DlImbKf#>igO8BkS)S!dT%>R=+C53AeCwiVEEUu-#4=3YIfYf&KHNy z7rL0dP!J*>VEt%x{&$S&?DslWx3gm=J7%!oG?r;XP{am?HJkk&6kHLJ^ly?w*#Za` zBG`?QLX;58x>_QX3S~mMP$AR=PL+` zF5)=Xn7ceVo-v+1HDNXNH4Qb#*PKvuV$Df4C)b=(b7sw14GT`3c}ixJyXANJsWW~( ztM#n*vo1et(OE0cUN-*a2~l2QQpBWH7azT3>!rIc3%V@$va#xk>PhO!>M81}YNOhu zHmfbFtSahh>gnnk>Y3_U>Nxdmb-a3xdain&IzgSNwyIvWO+8fwNH>nHNo7H~x7WG#3HuZM(4)soTk$RW9SY4tn zRqs}psrRV&s`shO)fMVWb(OkWU8CNwKA^5uA5_<=>(veFL#j_5PzTkA)koAv)s5<7 z>f`DY>XYhI>eK2o>L&GB^*Qx<^#%1s^(FOX^%eD1^)>Z%^$qn+^)2;nb+h`8`mXw( z`o8*s`l0%f`my?n`l-KuU=x2xZ%->ToK->W~UJJcW5o$62O zF7;>i7j?I~N8PLLQ-4)|Q}?R})Zf*E>LK+H^-uLLbx0jn537HxBkB?LsQQoU*90v{ z3)VukP%TUg*CI5R7O6#P(OQfatHo*YT7s6SC27f8ik7OSY3W*qmZ@cF*;4 zXm@Ihw7ay$+7fN4cDJ@nyGOfMyH8uLtQW z(T-?GwSP3fF6cpeupXj^>S21g9-+JRNIgoA)?@ToJx-6;6ZAwqNl(^O^i(}fPuDZ_ zOg&4_)^qe+Jx|Zq-Fksus2AzQdWl}Dm+9qtg7(@H^wIhleXL%si@KzH^cuZZ zuhZ-G2K{*b1pP$)B>iOl6#Z1aQE$?l^%h;$75y~*bo~tdO#Li49Z`Uu^uh2X6sd}g0 zrBBnZ)VuW_y;q;E&(LS;v-H{e9DS}nPrpi^uV1bA=?nC0^lSC&^y~E-^c(e?^o9D( zdcS^)eye_)e!G5$ey6@jze``NFVUCkck9dad-Qwt`}F1d3Vo%%N?)z7(eKwE(AVk@ z>g)9N`Ud?W-KP)egZjhzBl@HIM*T7Uas3JXN&PAPY5f^}lm4v!oc_H2g8riZlK!&( zivFtpn*O@}hW@7hmj1TBS${`=SAS1`U;jY=Q2$8(SpP)-RR2u>T;HO9p?|4=rGKq& z)wk)}^>6fV_3!lW^&j*d`j7ff{U?2w{6qtd7{Mj6K$qm41f zSfkny4ax8rHAbybXVe=F#_`4p#)-yB#>vJh#;Hc5(PT6mErx6;#%ads#u>($##zQV z<7{KRagK4Wah@^3m}s;bUZc%8-ea(Z`@+sYTRbrZrowqX)H4CG8P+4jHSli#xmm`<6h%FW4W=ySZS;> zRvT-K`;7;TwZ? zJa4>UylA{+yllK;ylT8=yl%W}p4Gv9QZ1!kdHWEPtxW~o_bmYWr3 zrCDW;GLJJyn`6weX0<7rlIbyP%v!U~tT!9XVPzsw7ku|lmd zE8L2(TvntNWkp*tR;(3g#ajthqLpMNTPaqmm1d<|8CIs1Wo27AR<4z2<+D7gz$&zg ztYWLgDz(b2a;w6sw5qI8)^XNoYm7D4s#Xao8>}0xo2-S_%~rp4i*>7Yn{~T&hjpj5$hyl~ zY%Q^tT6bH^tb43`t^2Iy)(UH-waQv;t+DR69v8J|>q+Y=>uKv5Ym@b?^_=y*^@8=H^^*0n^@{bX^_um%^@jDP^_KOvwb^>d zde?f-df)oM`q28w`q=u!`qcW&`rO)LePMlRePw-ZZMC*p+pTY`Z>{gF@2wxK9oCQ5 zPU|OYm-Vyti?!R@W9_x}S-)DpS^KR6*6-Fq>yY(_^{4fhHDnE2hpoS@5$lL`)cVKr z+kzcr2iqZbs2yg9+Yz?Qj~uTB&a|`aY&*x! zwe#$J+ie%vg?5o$Y?s)jc9~snSJ;(yl|9Nn&K_-#vB%ogwrESX$F8w!?K->OZm^HH zPq0t4PqI(8Pq9z68|@~$*>16ATd_~GPq)vo&$Q37$JuAw~{Nd`wF|mo@#g6UG_BlO1sx@*tgoZ z*|*zw*mv5C?7Qs6_7Z!keYd^LzQ?}TzRzB6udr9ztL)YG8vB0x0eh|epuNssZ*Q<4 zvVHb|J!n5{KVm;>Z?qq?AGe>dpR}K{pSGW|H`&kH&)Lu0FW4{IFWE2Kuh_5Jui3BL zZ`g0zZ`p6#o9%b(ckTD=_w5ht5ABcakL^$FPwmg_&+RSt7xtI-SN7NTR(qSh-Tub@ z*8a}^-u}VfVgG3F8i|j?pOIhLalz27hc8Y2Xk_VW;Un&$rI4Jt#~qfZxB*H{chF{YOdiZS?#1_X+F@EBpt&ZI1=YKl_Bo{r+K}?+Gdg zSb4wEkVVD0LKK&_`GqpNa;CTSWxvqk8+5%Nev#k* zq>$6jO5fm2zyB$3Jull9`2COheEki6_UDk_KPUwGg(!Bjev&aj)#qP`SR)3YjltG-ypI^zFl3F~s@0PFa9>?Zo( z&-}tf|6go~Ti6}vkjlNjhu9syCrP4veS?1gw=^x|DmVE3pOEHpY$)%AKj8OoWfz51 z)-V6oEv1AaCP2yHBI~&W?_`jx>j`Ru}8eRR0?ulRu{a^a`ku=)y3n9J% zjXG9#SwEW+HU$4c);0e|Dt@B-X+i>08!2HwpV~rG@VwXS;t&4Yp^(&}kkase%kLke z=HF5A8{M;$3P)ny{*mT;AMX|^`@=WjdNIN;MAOuT3L$4GAuql2H2TVhf2$1B=-(=)p(Q4Y!TP=4yIkjn$BoQ?ap=?3 zp{Gt5d5V_rP{z>jscZs%qK*hO#2uuNX}CO4hIzdmi#r#0`h_@}%%A&&RWn!3T)*Ja z{zv=QFImO@;EIsZCoJCJqTao~fo^N#ioRvfBj_Ra_}%`41i^4}sStu#qb%PhCWV~q z7ZPb&{B$9iR-=FYg{xUPFrStGcw1R{#6NoVO{^Z_tCM>2x3_Iopd6yJiG4!fy{e8<4yolUg=0ztdIzEPwT1$EDf43p1AVETKs*Mi>3Nd{`p1 z@;t|+HX2?lOok1)t&5fCo!doIF*uEtp`lm0`mdzL+&YcTr*E)}l>?RR1|gJ9G(973 zZGZbJN!0}FUb-DVFavyu;LfFAO|f2AWdQQ4&TAK$?GK*?-+ z+TlA!#(fn20CU9Y+%=FZOr!fl=t=!6kwppNbT!HAUBXLdDa?+9c)AixZDOc(BC{hV z-9S<+ITzm=GNh0B0%XJ!_ssC6YzZIr|MMt!vWyz2T_i2mJkkT(o zU9xYTBV}Ce=O)ek1+zc~IY`n(M=GHHg;P7mwEd)TIV*FBSVricY$5KNb=R;__X+b? z&0)(p*}roR8w@SdJv7W{-)35dgCuo0QW)L7gO;WsoXptBH%QNu`6&MgJ%OF{!2hD+ zXJ&~c^)P=xSN8M?b7#$Ei(W`!1uenfIK@%h1HPrlq&HYoy864fZ8|IcyIia~=o^^M z*=PEERv!`~SaVtmMV-{DjexvT8-@1cq%gZ zt-cqS68|t;DZcxicqEb5cAD>TYWE~bOG#S9notMgdBG+~NDwkypa5mrQr|L9r5G?hJ9Nd=`ZS0EL}b1n@2#c zB+(qSzQ86E>=31H= zQSk>oru_uuNKEMv-TQ0h;0;WT|AiaK^Shae(Ahnl3#sKE-_6WqJBKS$;pCYax7|ie z!MYnvu6RlRivF+_{mwiGQ|A-BZFlgJnV|o1$E!!s<{hzTsn1H!En}6CL%xia z6a>X?@iHn)5`tE(AWLScF$M#=AkphK# zRQ$?41?R$J(l5Bs%82U_3#1pa7_f?a72ne=LL&8heS@pX>8#}C<2;15`zcHq&&usI zdxr`1`z_x2)8!ai##kZ{A@%}uJP4c}&UcHT^n;eO)ZWiap35DdjeD_ev5{GEc zqvWhy+yhX8!KDQM2r~w{n#}W$RPTkZ{xvtUpMAo$%h_{gK^JSZi=q}<`kejANkx-) zK1k0Y+PBOZuZuq}3ZTMR&zSTQNo`~SWP;@5_prunk+sh5pL6rvh0KC~9=bktX#c{9 zk-m}rVMCv$?LD<>Nl)kK=I)p6w~C;9c&#RAT24xUVD9a zkaQbKPt%N2C`6MULjlkazSVbA>0^#>d!NA8#+Phq(xCdLIxcSq4^4cdXk`zO#Md~p z>jSi=b_Ldqe>cUhdpWuBg~--s2V4Ug1zSD<9^sVO98k8mt=Jk;heU#m20hkSELx`?FrDfJ*9 zO;`7O&t>!N|JK!X`v=3JLkDS{io!j{NlzVK!809k$=Cg`C&`LI&WIE|QOhkn8G)WJV#5!5XmjQLR)VGma?86i`@|32M1)cQt z*Ewq-jUe_T78%^EKKj3kh6HuxwQ zX7fJKfz{@W}%eNAgL|kSvRE|V|{DMv#_gUxZ|U6{Wzi@ zzUy!t57+5xIZOYESt(Sf`-;4w$VG%4I#)pVrFu6w0eWidk*A!zQlvJ5Fp1g2@xIk; z>PK^vq@EV~p6;O1N1h^uW%HjAKl7aMP4B6$k@k@?+ENpQOJ`8n!BR>VY>Xotk0j|e zV&?&hw|vB^<0uPVOp=!*cJ8k}VGg_n8OeX8BiwUU`ueB$Pj{lOy*#n-1@`Rzl_I$_ zp{p@o?^Q0UCQzIc%zXw$K3-ZS7f_cTLITC4jZR)SLe`&->HeEb{Z7)w-Fc$V7hp2t zA}+=8u$`L35NE~te0Nj1f%bbSRNLZp7&4hQkeIa6VNu2*oLdK6#DBEuc$7}_e*6uO z^2jmCM>gtPel_53$B?aVJaX zHnXve3cvkriecHPk4Nw~@J66aq4CuoOHMqTE9obfDCQHYsc_RzT6h78t+T={txv-e zgfefd>xgUH@MYm~Lt}>5(8kz4-@DGj*iVa+FNfcKHy@KWvz7J-_r%oZFG^UV8O`tk zumGs-I$9kU!--*?j3B6C(oxPYY$ZJ0zkbP@Rclr)UElvGCtmiri^wtlK}#T;W@+a+VvkP zjmN#-*5z|tGz-EwW;Hx1_6-s%dR@Gnbvv8CEv@~O$apBXXOSQ+f8rdT+0izXZ}~Cl z4IYi~aBr#;CRVa^mr1WMQlvTI`#CAhQ8I77l%z9BdYYn(HrlP`&qZY}&Ho2~vZvC+ zn&j~D53~vn`7Wm|s);0hgu;wK@=aqpvx6*y?*;!W?cz}i-S-qdvFsoLI18zh%bc} zn*3m90>Z`2`!2jSjKK&oQ^|DN9JAQL!Y-H!56XV?T30yc^bPv;`(&09(`$_`zU|cI zC^$9arEJkkoE!Zh7Rq+2r)D#amV~i0u|xDtt+Wy zbD2b43qkJQ=FEAD?=6?}_Bd|s&?Q69rw-lFKN3Ck!@~Zs3w}ubqkm}N=%t1ICk>51BUeROtCL6m)b1XtZfGgHZOo_{tY!4tyh3I9qvIKgeVV4qqDKG($B6M`xOnVk@Nz%?=< zeAKqop}WKRob)^IS^d$cN7q>*34 z_pn*NhRu2fy<*@l&yBc>C%4a0aysawxqNe;jFWs;{}Z&sxr_#&(Cf!R?B)B1CcZ$A zkiVf`h6RrNFs73G+$oE}F@np#)%h+VJg{deg!n!_Cb{^x3-k)9Z6;00{jQOz;c>qW ze>Hq#DsfdS<#>bKxj)9940nq(?roGsX40&F&i9|G%?FeNv00^1fO6h#eZsXoAD&C) zz}#-fqwMo~rv*yB#r^|znuj{y91D85#DX5$)nt#$MU%FlZ({M6K2MkGQH>X@|-()K7T8b%Ehid;e1V1cgVCI(0T!t<^|1c zR@U;Jv(3JZto(=%2K#C2R#G{@%5Ugw7JprZ{eU)SZ>GQtE1)#T>%4M2j+n=h*g8H; zq4-!|fNMQMFmbI!4~ssZ5XMr+<3Kl$^NiHl8c5}8Iiq^p9;R~Q!?ZWR?#ZIFl|;qK z)Upy;CzHnVr$Se2i3KSG>*qTQH}GCBpwhE|ws1DkdoOxjEfjOt;G#HXyW=HN>GIFq zFL~#6QW@Imyy^KCud+8-uDI<(jm)mZaPm2e`L`H6J99orNFW9Y^1XB)mA>V-uW%CU zME@57iJCli6JPJ6XFCn=a+lHGDzDqw|E!(7CYOU^tDg_Gc=!-6gAP? z6QPtI(-421N!zrJghYly5(<#g$%Alvr%x|dOeNB5rLuLCO&^8~UdA&&*NBHZ?1gNI zQ~iH4m{y;U#akzMFP=zc#zdOQL3*9U9omV0|E=8g-k|WBe6asr9)wbxPblzrB>obh z)$HPi(&fDM-cId*CSv^@ug|#jxFfyKHx=m4H+*ZEQ(G7wclFnYFHId@aKe$ok(t90 zCme|w=^rjR;mCF2aToF{?I#?G8ksq?{e+S2Bilx?^gCyGcxP%C88o+W2KN(9))yR( z&V9jBFh`=R{8iHy;!Xd%zDHR3F(+)CJ;F^}bKYre=gX3BG{Qo7ax~~z2#=;p`5RWs zNUF#}C~aoax%_qfCcbyIk-HiH%gi#!X!z~|ixHl4B8AcZ?==vYUpP|mGmwWEx0AlGxtDCK2w;2n-oNbhu5>A40k(*3{lteD;@!aB12 zUpdy1=Byj?JoD&n5Z}|JT~z7}&ycrcUt^Fa>U-CyaPp=5@QDedj8^^%okef0ufT5o zhbXz{(gEss0x{mNl;(5K{wpG;LFX+ycTd0YsF(CXYE7Vb2CcMPH5mBxD5!;2(58Om z%p90a;X(d^1Z@k3IugCM@b4zfeYE}dBaN2`!g(LTN#Z+SfF!p4N803M##{NfHedS> za=Lh$f8a#35ZG`1hFT0?^@VD(sN|j@vJ1d|H!Ut7NY+46>EQ>e>mpI zm$$M;U;aeRi~5g54u3*zKA|>4xkH&lhk2&|^JF4mAAhSvwA(d>%JEa2Xq|s3lOjZP z(N^-&E+>oHO=t7H7tG-_JBQ}374HS;O=*9iEa4xYpl#c7Dm}|d!v^QoaEeg8o`3bR zX*~~$oe!HLy~`h=FTna9p{~(8Vjf8ceg0_wqloSJ8Dif@0ww1jcK6KnGuN{P$lnw5 zz`-}ToXU;MoevbLJ8TiJrPnW?Q=q`3N4(Sc-nVQHl>>7~g_nds% zY{R8${VF$wb-c|HKjfdvRXR=iCooK!{wm&F31xl4 z(zX0O6ED}o6*HS2}o z&zbv#jrK<7^yq7wBs%kcSk%UmO!Bb&%) zyhA=?XeSFRn*9eDKn=dAr09kAD!!$aQA)kyQZilrl&%WGxbvvoN47v-xN-x_LH4zF z@V!a?8HFS9wNJa+6ii&r)3X%5-AvhQ0Qgq2F4n$YW9`Y_Y~8<*zO z#?1!j3xg2f;M_nNyoG<#$>M9gB@5y^6~2L6uwOyn7tZD-y;KUOC~yNdwuE4Q&PU(1 zI^rOGlGMsmr91du#vS+~i+^iH--s@`+EozlOCUP*Po#|ovH^ZB(SKy2^Je-8KDcBl!qK)#Bzc{4JYOIA=Lpw&qobR@ z(T?R#2^lVZ9_ffT;SCynpLZ4OxKKz5dCsCh{>O>jcN+`m=8e2LDtzeK;ndVM{i}Jz zyozstta7$N_&e@!%J^x+1m)fTPdnEh995O(ZwKhUJklVh!$TC*sBD~a9ChLYcNW+3 z?J&sXMiEDGU5ec(qeey$35kFRULJWM5FSB-sN4=dc3C&$?o?Uptd&|Qb*+l4qhKcT z5_w1h+z#DI@A>_{?_M%hGyBI@?XI=ehw9TG>F#^G?>*-`-}n1|zq4+2z~m6N62aqQ z&)w#}i5TB0ox@;dj)p8>k)(yYgrcaOu1>Fr#$QQQrB);q=DOM$$59M|{p%8zS|hCM zXf>Jak8=cH`a@!DN31a}2i-D6Ml~<6sP}@Fqs^_FPj4@M6(`<8-rR*+@klGf&c#(| zwoxu5j(3b?g-#C8PT{dRIy4iw;=H(LEsz@N;iPoI8eAWXgI&`o4*R|qUriO0@reMC zpYwrskF4qiSk5!C-cx6X=1!s3A$JGz>NT-{L%)6p(Yr6b*GOS!@KkNhdjb`dq9=f4 zpnAXGxpE%kw0S}gM@^udv9R+E1*wOtlz`X|-}zi&$~sEe8R+e>LvworL>fu0 zkPO2-9ORX2*>3rU4*2!btWBfIQ z+{Xi@NlFDCjgc>q1~AQcE){ zmd%P3BmQ5 zBgVd~`@tiwKQ42?yzQFQflk-IiuNU`1BcB=0@2jaoBF4gPR%SeA;gbUjd0s1T%2|g-Ha1@OsPWvdQhUAN$;G5 za|S&YT#g#ykQq006hGSzGqu4X4~$lqS*aGXD!5R&K1{U>xkRyARh_?VzZ9_UAwZ_>m*V3KTY*__>_8!TLr1Z^dWCCohJZArSWE(MpaY{Fk zcp*I|hNq-=lIU&GwFDLqImCS74X&I&n=y+pYhq=#JS`-rqq?@bmcMuv*Q^y`Uu`WX zMDEUXX8{fLp5jZ=FW>-NHbaTJr9zH*73`GAmbIue?b`sLtaLM`Pb>R7n}ER>=V~s( z^lgH1u4Go?1{|0Xa9F)gX_Lk+h1o-D6_788nKv99pHqZ3_`6QA2F56FaEMi(wFU^& z#B*oa>Bblrf5dc5Dd3#)1UlXxT5rLlmMS$PKP2hI_yui(-k$do!y7w&fj=!F?u7g7C6}rytj9WEkCDdF$kXU{t_v+k z>u0Cg32gu+2xpdB{Md0ulDL3}LH?;k;Oi(qWq`cDtgprB)GV*7p9lP(eqPoskys5u z^{z*#7$7g+L5|8%u<`vNfjF=atQz6W~0iOh|)Q9KX%K*HNS*L$~ucuR#~E#RQO#Lz|h8X}G;O9&4(QULQ_T;%4U z@K8DtZ$<6LS*>}@2{`w!rEF2a0jMmqgIo?6gi&FK09*S#)z)GxDhN@#n2{38i-c|} zFLYC4K@`(p(8*-2El+`x0YjjZLM{RL153(1ZH_=;2r}$tx0XaxMg9h^ShKfkftW~N zw^!1HzPCw73B`7uS?H9ytkK9mey2PmCiNs25Ar^NwG&o_umgm^w@-kC>ojqu#Vcb1 z-Z{uPDlk1`uv!$)J;6dWNK{8XP=LD-W*!CHds^vw`1DP1^=n}L4XmBQZOk50dJ;4` zDJf5{WOP%D*Btg!6_@~|2*w#wUSqs$kG{Msycdg)$$k{%vX0o-pE$OOvC!4E-%0E+TW}+vA4mM3`_$*bP zV&-;6!f>n*e+H1&8rN2~2Ju?U7RGN|Shth$_4jrMOJ(ogg)!I6WDm;U^*T*Iht`_t z(5|*J)#LsK)e%r9OuvUAGhY9_c&cP*QKSfk9+jda1W0OD>pOyJa2=-tG9fjA#&Sdx z2pEyjJxQ3Cdau@i(}YFjLhmj18#Q`3Uw|j%B37K%E5^h;=lHsSg-X%P!GcpGmKVdy zI9^z_t-;`Aq?=*!$-|f&#=7Z|=Fo zBIK);8Ncig_v?u7e)kk0{G(O%YH?WNnu9M4+fJlWi&I`15>?eVwekSbi2@5{_K3N$K}-i89MX;kTwj1wkDU z*fsceNu_NK4c>+Im zjORT^gpz%738`4FNPhTaBEkN+)E9{m0Fwa`0XZ{N2r&s9qXiGWvmD|h1CAOceahY^ z`70dp7cuL_h`&q{=+>Zqn>S3?Ay!40K=%MG6N{)?fZxd9x*12Rc}VY}FG(L`%f~{i zRUxFVV%4phiND-l;WxHNjia96w8QQJTYViEyNo1PF59J8{QEp_8IU zogr&zQK5d6(YNQ#u~S3SMF|eddn!Owb9AeMj&RcgTI6@LWbv;IS3VU0iGDQnp826i zrF8(#Y`DtFwgx>znK5#q1ERvIP{MEqM=TV2FL27{YEAE`HB4ny z2SZ&*2f~xU6rcHM9ao+@rDPiyQ!XPj+iq@5W<*q_E8j2=@nqGl)h#dvU`GyG14+Ek z$8H>imh&|p+^8ji0^uKdq4gHNoRG^UEPs>iZ*p&$^)|u%zR{%gH7-1(2wJn8VMXkC z`iosjum4%RvqZZ3%gYfDVW&qT?;%fz+9wc|IxvynjT~^Qe zXx|j$7AM5h7l|Sr*ywWU7s;j-cn1lzj{EEjl+rFzL2b&qTVySeWRl2j+czJdcv)sr zNi2SUs_q}b+E22=fXn+H0|KY);h=xtDSbMd-C+hVBuVp* z3^rMY1OP)2tPbhz9kG{D*z^p_B|!T0z915o2<-0gh<`xBw+;Dm(qrCJB% zdSZfddwJUz(e%PhX##r8)2gl-LHZ@{4{{`v48x-6^z}d)&wB(k|6HIIgR{FE2_R`* z_YZFoatO;Rmmcxm%bKAVvXMBJ|GlakbWt{S^3#|`CM=OGbF4+>NCbYbTb95?yBPEa-YW2~;AY|bAkK5@( zC4OfN1Vt)=rP2|gV#9GlwaS#oz?kMMRVh5_l9lkn+(lUKVvD%PL@2A9qyVnS>WG1` z{>75jpOV%c)`FR5r(2AB&RpVOkvg3y>1vObq^Bm@GYuutc>LmzarHA3qJFjiv>$cT z52q*lPo(z%lfK1onsAewzOTd`U_Q+^_B?1locYDj$X7r0}WVhr4X*>tTJCq2cG@1H5X+s2bKdlQrE^$>P+U;w>brNrXzWMSSp7qyMnxl-52ej|*C z<(z4DW@w3jFops2-UcqD<~Ti5RyS}VZCIil-c-2Mp0!R9>@M~e0O+;m)>6I({deh? z?!#_*)l;TbJ?cJUr$5Ch!0$$y)2prwiwxwrJ=TK_D)QG;-5s1N*G#YhsnyeSI2 zcEQ69KuG(Yh~!y(Y*J@&kWr(Vrb}3Qe~vPN=SZHYqCB9|uC83f#bC+&CG$xgXVBw5 zhwmDT^S)n?`_7o{CtltAQtGkp)_eZnnQQ;=rrP}`OJ9>vG?-P_{;ax+xObMMq*4w! z7!Xzk>R@znTolwvmENC2|1GIoP|7}QiNMwKwz#S`A$nfGVx7FR6`>U1VH76q;D|zc ziOZG*aCgiQhao>Df3_gp-l6Ya2vbxtdtRI9a_-aoo#j5#Y6;Bv$n!@ssSa{X0YV99 z3htp>@xZE)>nqenroJ}Re`?(zup>Blzv4iKRL;a+#1I8AH*dW|u7|Ovszr7|m!wQn zRKdmM>3HyUWREaEMBV%lbxY&3=6-Ptq9*%Ch3?zJRn*|yOEw4n(5$9XC|m~tyAy=& zjCZ(A!B|MbAQotNvyRviFgAiMMaAA?uM#UY(0J0vkI)SYe!ajB&6W*9zmihHUesm> zdCldrXBZi4GjN5LX0yLD35|(BUe{eqPMM6$On}K+J26w?S%u3FYrO_mi-INl+f3>u z3{dLgeh=uAmTV(YObT!#V3z+dNy1Di$;(LR_J3-5q--{7Ry|UnR6!q})!kqyT^Pqi zR6y6H22RGoxNoBnVO&o8Ex9_x|3n=k-H1X&YI?2^@jWX<#=?EfDGa>(hxS6+o^Y+bezx*XJxToOaZp1x} z!TPNx#GT@v;ZU#v)d^?%Gph2YWU$-03&CQU?zun0GqR1`G^M`{qZl6IF7i%$h0!<_ zXHW4?xD7(*S`qa5!nO5uqqzYxH`SEAg+Z>UXSN{yDw1bNQ%T_4_(GOTsxu#qZ==>< zYT#w2cm+tQ1r>E50y$c>qkv~XxTgUv^J;wsR~)-SQcW0w)4j~)Rk$g?I3pR%k>svtHQARs$r7O699C$irXnv}x z9Z4Pe5}80DjPx#r?G^`R|4kDZoA8jg8b@kZHgFWNFC+i{vPS_h4&z5*t<+6+Bh^+V z;|A=L*j1c-5reOL8CL1&GSE+wQj;`8{bx&TJWaeQ*t4nJODkwC}J- znG~LpkM))>YrVX=gN3hJs3gg`v));)x1&GJ#=n(v9^*S+RhiJyt*koQuv18Hva(U3 zpp81JaAauMX1Da|y}r?X0xdkFt{9%HI&XgC8_Agf@T7hm+X5418pz*zyb`o5&7^Hz z9XhcGa;d0e#Os#(yJK{!PwS|aOz@QJFxc5 z-DyYgRuA;Yy5c@6ZuzMUa_smnPckf=m3B`^Dx9aV(O{C7k1z3}_b$H4MD|agLA;OO zdU_#t%Jr{SxQ4#h&|?T@AJI@OT?r|Ca$|Bs8#P$p zmlR0T2A3ZiWF!ls9DRE-<*sT@u>7L|2NII;6xuZ=*BC!%i%lLADxJU105-exyfj(r zy-0Z({~)KI80IwB9DTITy2GyiMbRIT1jz5YBrUTqAhOjnzb`Gfl=E%B!k7VCJd2gB zln)hTetG(NiK;bIE;$;p#O1P`=YErE7A@?3U8d!`UEdjgS?luwlz8> zviH}UUa?jLE+-o<@AYzWp zObW7nehFqD@(QB%9_K6u%39XkJt%;cckyM)r5<_tJ7-&Zy%;9iTnf1Z=PH@oN_-z1 zGiMDWYCF&R*kQ6c;Lo6JzK7 z;uM;&=PA`&kFvA4W>zc1^|~Yfi}nDts4#w_bU-RE|0^Jd?f(kIu(PwU{{;}k`8OcO zv$>UXC>&mHslI0|0#oGmJ1JH~0_qSdakOX(<@jCXMKRI73eD=z&_Y6@@1kg+p-)*^ zfu2))ckQPSkKkXXrsF5$8KgQ$!E`* zZxvYzY1;`3=+rR0Da$%0tLu9tdo$b&#Mz~_g$wQeTT(9-#5d(>sMf>wYKbpOJaiW! zosYs#C^59FdjY;4U*|hV2i=yQ8dGm%E}w$aw7E_NF2aB&u84`doFS_Mn~8&LPkRQF zl=yo_wUgb7^+KgrDK7p}}O8TN@MIU7f4pE}Gv)b^L>*7KHbk)~2^OP9CZG`}n! zIUIT0ZoFW<1U^1B#_YZR;EI&&P4x090z5&!7vrIjtw0~UUAitdXY}E&cC*r|Sw-Roro)&nTCue*{T{I~h&=fvlI~HWf?OG6 zp*#FcxAY!j za7whIo@wo+u!H5o2+4d#{DeLB@OYc%Sc0~BxhFoh)H$Q|C89DYed>Wek8pr3(edN9 zK=^8*H-7i>bOu{>p}Bz05A_hHpEI#84wcDug-_<^W>zGwDT8Lqi}8fh9%NI@8R7Bz zI3OHDZ0h2IYEf8kpZCr4hu!l4QoNzd#;WycZZi|U{qwAwn7#5mW6CL^y|9KHFw3(* zir;jf_|izf;Dezt>-=#4l=!{$X~dWOcuO+!uYh>@V&k>o=Fcj;X1u zs+$vQu`Aij%kYY_&BWbXk{LwjDl9_I|_6}d~-n!Ek0vRhwkkvpK3$Q@Aw zG+wT0`;j$gw0gkMlBUDteD06ge)YQ-jggVyBjRP6;BgBF8$%5@2OCmjoML$83*E7o zsRQ4GOA90Um^TOqrUQ?=$H#g)`q|T4d6C<9geiL9ET|<{8sCg`f$|Oltm{ zJHR$LY2r&JCcmXO$9>xoxMiZ1pXk901a6-o%mjKx+@@XJtt<>I{K5m_ou(e79_wuD zfFO^o4{BVtPib7W_cac=*4Y-GasfTPOz*Gn#=+h{UGq=1fyf<3<5>}~8#?9;?ujSY|yj2uQT1p^9kji0L;7PIt2s@%nI}iECCM;HVjS-c6`74 z2E1H7*FdIJ`20-zwDRQnMEL+b6j<@Ccp-t@oN4*UdE2?&+4n;5V*R`VxqStA+zEWC zdXai@gw_>Q6ciQo64Vxy7qs`I??SUv^LuZn;)i8t*>&bO?^oe>4y^)vg6hV#aqdSB zT?#Xg0Kl%I-Wc<{f#pZO<=GhUGl20yy=C2~^h5gU^Y!D`sjpIBlfT}5HU4_tH3EAG zTZ!cKD&?yyTmxJK{572Xn>4iBPaC;kkzfsvuLN{<@Zx4`CurEa? zhau?C#H)7nOYuohp-eb$%uA8U2_Xdkh*#+-Jhtcca5_13!3l3=GV*6hG#P4VwJPf0 zR)0uXp(mv?q+3e}P5>n!&^gi}(aF#&=;$V3)1}heYVp^3+1$<7jMPjx3_7f`e7d9L zBIcsw;@~3ZqWw(|YT~&a-ss=J^N-(14LE&Eh`EXe;Bb>Z^X^847r<)cauYjS-U#nz zMCc@Zv^g8-HhASr)JA#RxIx-o=>LLpj#v%3LyPQNUeI=6+_$rj^&d5YbTL@CL{XdR zA&gK(RI3QZH(8`)%nQlE$0$mXj5qES+jmhKA`O9F?=G|kIY07>TnFO6<;HTL*#1)F zYi4F9YvxeIUPoL9sH3?InGBpf6xo@~&h8PG2y6(t4wOe}=X7$}U!4@o9uZmiX7k#c z+DT@gH+x06F~|qIh1bb)7zr6h_mWVm7k{H1#mlYNZ=7zV}y} z5ab6_$ugHiydAfm{UD%dBBvvG8K<7};L~h%5vvk*?i0lLG0ch0EuVs)+L=m=X|u!S^P< zH@gJwgPA*+yP1`kgPC!d;hE!^>zS{ZIeX2R8wbL|Kw-)6SV?!YlLo#d^a2QKKkmjS zl`|9ddEtN!M>~>wmE!Y92gJtCUf}= zF@3J88GCJly&11-7YV98zxYP-5qdI=b26|oFfi~j2vm@aqiJBfdZ*#K>gdYoO03>C zf$VFycKi5n8hLCCR|}dNe>L=ZV>Ys$EHnxHlJC>|f%+rzheB9mKXxDZJaK@tANbz3 z7f2|;(!uH@{1|qNutgMZ@S&5=$JxvGG4#B$uan?K=@I*!_t#DD3!yLISr;bpUEI6q zcbQQMQL&0Cit%=0!XiJf5FLI_e*26_im{C0fk8pJn##oc+2&`?w;e=FbPkBuQ$@a+ z{>>V31*1b|F}+G))9&ZcH^*SzFN$A8zj%Go{v!XyK8Jn^qVwd$xvAtNxLN)>>z(hd z=sgcs!8ld$;yOR?B@Zq|U!d%WYT`aG??uHBP7&=ex+dF6+D_h1-%jbRd>?j+Fhe9~kkmov?d;)u9}23>?@WJIy2l3bPWwu~ zus=m!Vt`C%)^NV!Y~tAC6yq%6h~dQJu;T=<^oHTF&W7o*q_BvaI+=uxG*KFwh#T~` zg;BDon?ML4j;;7GPL}nNTe7XvFd`P8ajqzPwk@arJ6Yi9#%R%K?`YU)+vv3HM{vz( z%cv!5kP&WjqiMt-e(X{@H?yP1E^M+R3$_u%m>17X{GIUb?r0;6!000YyfUhn{J?^0 zOgMo*_&9+33AwgkTcu2EUfA+`{jx`X{gg+5TJ^eB`wY+U@@E3e^e^ob_fc2OhhGlg z9BLnmACAl~l%Hw~H29c5t+x!^r(XTIin}_c%cPT0H&Pc?_fWS{m%_?aONIDA>{hzK_&x6l%_hhNHrt1r8SjXd~}{hE}ky7*V{*)wWg*MWBPIJ08hE= zz@x;PMx)Nyc6v|GYuBaL+8a}%asFg)hM*C|;o!mG38|5xA?oq!9WIB8;b;e&;VB23 zF`NvD5*5$NZ)!3A#ErTK$fzYVRU5xg+jHR9X-fwCj2Chn>^&xdWyVjreRm(@9X~EG zLdYNf`iGh{i8 zm%fn9$#9y{mhA5B4!+13)Jbk+I9+PfxL6^pEo|^Z)4|;(y>zi-e10L#6n}hM}qUld6zJ z_o6>F{0$~R^-Qz-mp>-FB@zc#o9>xMcPl&*wwD%Uq?6$fd=v3Ljpnv>vT#!QgI1Da zl75nort%>6JeIzmo80DxaQj&Ug!^fIbIOpW$W?BqzDfEWjFd^|RdSa6a}UXYepUNc zXw&pN@cjwhs*YRLndWBl&rq>vv1~DBu_3Yf9RHk)oRS>c5ZsUo#+cAREM!_-ty%q9 z9k%BE^_(R!$51RxdPZ%Py6pY@9D1?S_tvz_`j>iBCpk}IL809o5c0U@LzTcI-{ zjv=9;)_oDbN<;F0rH0i1(g_X1Zp3oMjAYEv_VPXN>5If>q}Eq!>$q+HCD&(*)oJi( ze!kErfc2vM=y{&m=Zk4Tbxw;&9n2s_GekGUNKIRvsH?AR;Gh>=+e_D+o0p$go>yq3 zJQNm#AVWy6rCC#E6G!7rq7SgN6ZK1H|LY* zdzo8<=JFTfP#ET9Y-z0-+Dk7_rV;aJq)p@bm3cZZho%dqGpW5hF6XApf8%}B@8v+_ z)9v{PGLi8a)a{zP23XoyDhawK^t4p8jHNWKIc3>L_bkm;W=mBy(Z7s_+7;jjgW8^2idr`b|lPIA3>~wg7=Owe=`FKSgc{`%Bc9m0x8A^2Zn+qI7c4XppXn@75>doyJt;1{a545Nn8D#*|Ei0jh z*E%)yJqf0?^@t6$R>=MgY>BR6)|QqhNBhSoR;3zzKkJtlBj$&Phj}L41Ad`ZC_#9$ zK-WgLaP#92b2D?Zt3Pq)+2@^Ok#?-pw?NJ1HR$okn32*&hxl_#Q!E9DY9cD&#q|Ue z^_;J;YV;*Ms#it0itIV)N>XJt&||OI@FuNbXn0F#ROgB;M4htXF&SVcUIFmVth#EU zAqAlu;LL5~yld<00Bj@zp+Uf#tu1E$Kc@;%8BoN~f-rt?P>4|IP-IY&P*Hylj4JU* z*Tn}qPkT|GT=pA9ItlKNCvAg#crRD7fqz84n6H$-2bcbQUE-$*|BZ%N6*{{_-S~Hv zM{Uvo{^|E_E-Bk$RFVBsL&W#*ogv)Z2O)NGMdWW5#Hyi*>dx$n7EB?yVL7jo*t^Q0 zO^}%^{j^jZkq%$T)Yn;ZY8#82oAYyBr^yk=veu!mQ1+b#D`8Xc_bXuuoU?LKoMyik z+X>3h*Ujd{*1NS~1yuIgS!U;BMK1h0*9PbZ4IG}i5!@>Wb<7HB5yZ`XrZ}9ea`X?kH_&1ejq6Z8nB2j ze}o-x+|;@P4EHvt+})fA3DYZK6fylupx`pcdkVp4Ab=N-0dkfFRChAiZWoZojcPjH z^Y@Z*yvG@Aw+7JVL|qvBQ@J4MjI8=cm$kqySR_=r+3U__zYb0OTL*{m4u8K57UJ>z z-T?r-s1xHowcz@FXZpA~VH|t_D#FBqFy$k_011Nf0Dgbn(+&Q;G(do$Jb=gFSAngQA?}_@p>}<(~seD`ZapKa=t|Ex#>&)v~a=|=8|GhD^Hyn&E<+_P-h9QQgG4Y zK0MPmsK9q!?_fR%Ly5fp^cwo@N57A7|3&DxDkx|}Ow9Q%3h(tGGF(SXv$3e9jt&M$ zVEWyuU>6xok|rd#=vLt>|a7@8a6li}B2QlEb5n(Rigo;2QD@y|AhQjh%L)E>e zgp-DXV11{kaHtwIK@ONfaj2!&#CXtJ0iO_fiX@<}US|>{A_(Yk11l;NQ-N&NKTCPSe-&;%L% zd%#?uqM2V0et@eAQw;s=Zw2?yT`7Wx;gS%v`3Twiybpigrr-8P5rO#k4LiUWS=JF} z4?nOG>Syo^g|mx>VnFW_gK3h4!baR6fz~DapTnZW7VTsxTy#MZ7&A#IWW=nG(9NNK zt71^ph{WX3d1QWZa8WT(%IJd9Fo0$#1%|Fzq_ge6F8#Na#!SZawU*dw>gUv@a%3VE zjlpl)G@6`7PB2T_gzGhm&flO^DjuShw7;uj@HEc7S%v*n>p8d7rfsE9&ryl>tSr&~ zwDntC`_=B@X4~jiDZE}9bwl&M?G1dTaCfQV8H(na1y)-Me5FZusn+l1vHqA#rAezs z?ON&5$()z@(LY}KnA5a}m;R|)wyhPN=PbBQS+?!7>wo`qL#Y%Fa@9qtGzrqE?I~T_ zoI5(RaB*YjZA&50AFKbXcBXt?A_Loz*9ZFv%;0#Dsd2{8A>B>8*e)EeQFQ%=UB7!1 z(*hc#HNugK-L+zndgHykp?N%)QSwHOo#qms?F&Nqq7bRe|L=4N@)=sd#j$&(D2{uFfUFKQYJU%|Vc5(Ck$D*Ld#-5e` zj3stILt4;CW6#dY=KQhUp^MSG|EgV!Pk1^m@+D4jTCp!x&lwG<#}X_B{@)wEF@nTW zw~~up9KoMTfDrI#btG=!%SB#Gy*KA4>DH=;PQ}QbKf7OXzNvUT3xnp){_$XTQQIrHSI1@CMQ2Snj ztA9Wb*rBI90a@20**P zoWX4%cKt_C3p;@V;Dz8kBw;e&?1PyY(E7=LHi>>ne7%MK`TrsOf(gNSNUUVPg$K_; zaGqc$cC-SDpR=M#DX K3kB;%9Xu>;5^^@f~&aDuqc22>b3aIH@v3&`7FAasR;|g zc{KkaBQYse|C2}Z+k?u0bwkq~- zFn=$nw(S1&A%A|~|NrsdEhfWeKRFmjsZR`uqvT(k$(R!1c4NA9(UW8#VLTx{L}688 z&$19D&-v1x@b~=hE8E4xRm60up*KmxXh?0)ARdu@O@~;0a4s=j^5~0FFuYQqDE~D) z73%u%UoHE~H~f3ZAJZj)ek%z>B(*_`==C3r;2*Z22bo=j>W)&NkH0ZlRTx}CbQcS{ zrZ~)qJW2e;a;8rxJzvF1dk%xcc!cFBz(zG0NpObAzjhd6epqg?;XY@HFP? z3LNjdBSq^V3trWg?BxjNMdnw$en(I>u!AVXynh_NX`s}gi{6M7|MemMx1;{w`5?Es zNo8dEe|GGX%CPk8`=-eES^+-uS($&7zjM7%*{@zh&ex#*VPB&Vb4@BB+=KqBBh?&C z5f)^#OW+mh{SGGcP~`sT0CJOwJeT<>-o+vY2axiYVk_^*90ccmp+B77-?84y`Go`n z&ZhI0mhPVSYt$h=I&)Ywnb}6XrKkY9Znh0 zm1g;$@~PUR7Qmz|KdzPLQK#9LkZ{dG@kY73=yr8$vL zd4285^74wIH7<8eeR+Lxqj7J(i}6B3UALtB!|u%Rqe? z6)NJCc%!C7U4+H4wS{G>nKj7l1Yanwj*~so=Gg2ba;i8RvaMzHwNu0q0dRKh3xU)- z=8E|UrFs2}I`J-X4)(@N%@yrb9UhOtt@iZ!;B>?Ca=!V9@$)h?_q@{lR@a<*$GofM zgn2Z2>mHpJiFzj;yw(AZNORkR&u#?sEtZQ>Ac)>n+gcc>XJMNnS$Cx!G^3x5Ku;=N zZs=*ool{>}T5e8)xxzbSX?CS+WpkMK^wIm|*ydm#XK8v(PJW>AI^qO>WrSy*B|CIf zJkr_A)zX#`B&dQt#aB^${IagZ;{LLQ$+K@+T5gp8sT^-g%A-{N2xM)3TCFd!+t6BC zo7zF%h74~ja^4XxK&D?_%}RNM zLMZo~5#ljh{0>cnQxY$`Xxv!#X%qO$l^+M39Lh)rl<#jM2G8GepL|4kdXV7T-lrIN z+SZhekQieAia#=RPR5-CT##%Jo|Tbo z|BkOSbk5_xORwB16>+tl_2iq0e;VaN6y<@#jTN<};$TH;EkJoid35^0{^-=qODLjp zs5-swC1MsBW$$oAK0r8aLsXneGEkY<>DVlN!mQlc zBW8yhYYG1GNFEKsAEUgO(51TJh<3%eW5S;BmNbCb8}JsbI4<->3P#F>TtDaR9|%g7 zuHYNA_p#R{;|$oC>EykF;x33b#A?ns6o@}0yReEt@<_SN9S6In_s4+i^K8fm+#JG4 z_nheT(iA2={Mn<^Y>DY9qwg^pe&C5zbV`k<4&4Q9m-7qFE;b3RYTq|z?i(zgQHGL5 zvDHP9qyPLKyD93Rq|1hl5rr8=5QPzi7lj=~r1xNg1ZyzWugk}>KH-j-^ zY-A#1GsA)v39IRxRtvw zZ{Ocy@hN90>Z|HQuJ!9{>#OVQ>nrJN+0gEde1|;jgDFr@GPLRHJ{aHns{BKp!(@q2 z>Z^7hGjP^T<+}Dws;0a3b3Ob*hqKDPoG&UOehj-PVGh@+9g5>R$jSl5m4jD;ODByq zJvS{ky?nei%`nY++{HAgc4ld(ZDr~B$o`sVfM5FY#wZ0yo3B_ z8!WY_yvMTVu=i$9dXHvLWxO!GG~F`IGW{^^FnxkcZ`^0^)t>lX?f72W1h0Wz$G+Fl zT@4s>k7BQMd~AFnO((6A7iiZ3T0QU@xoZFu?6r>Hq@D5#*!k=~4mOY7Rf9413dbkX zGI=}gY+QXnkHdHMV7$G?af0#FG$609-Shq`Xm#gtsClJ%;I0;oy{Es&zgIc_G!9Hd zNbBT9fCxA@=2(SYO)Ysd^p4QLH04H$vMKq?>^YC_PUyjB9HRy?~_BJxsP&@ksn z<6z@(<51&>>tN3|?+%4~(<)tLl+Jea1(kcQgbsV2>ya%4}2a45LVY`F}6)-o%Dt7h2%8; zW~g)cVF$PkdvSUpbQkp)VBNQTrs4g6*NG^-0K@ulPE*-4?B~FuEK3D@iPLy0qN?kcl zm0V6rgC$P3uf&LYNjf5?besB4`m1u$d+I*vVC9lH>K*Ct%EgQC_0it9D(9=xvWJKi zt1+lBXjCXxsJ^1spw^&umTsTUVx!3+pI zA*A@NnvJ@Rl8u^;ijBsJVj#6Ejoh$Zz7|e)9TjQ3(y&>+TC)sJZXNZpbkKCM6SXVt znsnrJX_#6+^;SIMu&8kii&k>ZYObtW0rgBg&T#v%_pt1ak8#3<-$fRSj=LmCg;1SP zX_qRJ#xZ^%&V6`m*vt59jiOc_oqC310+j-dOuX^1gYowoWvzTbKA^lzeV)oP-g($# z2d6Lpk`^y6e7JVlaTq*|G#olCGdwa(J4~^oW?XxbQX}TB=Pu%|vQ*NR-&Wq1+g93E z*jDM4oyMKU6U7n5rw=piP#QPZ zNI&%+$E32_$m>!lyR}c)H`(-i4Nj8isLkp zc_`z-!|*#f7m>fzx#uLV)Sgs**#(hR15`tC%L0qCEs}66#EYUW;&99Ri>fWsa4RW_ zf-PcF$_k2#EmBe{Op20A)W(!+=kVDz##F#_F!hS`%As@U^{VtLBXe)+mFtV!Xo_6w zrOVYVRfDuk^$UK3?(~aMlq;1h)emPq>V>RT#nhB5l`7RLRVp=X6>U{*l@UrsR10ZJ zLrO|gN=gGQN<<*SozASz+{*0A9PjMsgLI2n9$jm7i6Z&~N#{5oZELkt<$)q=i`M0A zmlC~$HH*gO-0Kp!lE09u4jJW5<8!(r%ER&!5F#G_Fph z{4o0)f5&~0d!T#8?3{7m#ABeB#h{8^96CoiOAgWSl%11XboH_;R5gkfiWN#r=hzRl zozq+Ny~Ul2pAKF*=iZmyr`@;R``_o>$K2Q4hqOp}tF4uF6xb*kXaE&~s*NSK#kQrV zMW-dF#iyl2MMNb;#VfOsa|*Kxa}%=@bBwdc2Z;w72MY(B2aN|PSG-rAR|r=U&V?;9 zPf}~;CrZBRzDhSG53>eyPY1RK&{wWkSss#4B79|pN|7bLB?Gft2Z&dB9@2c}&-ocj z2(z^Z+*h_&Z5~4HMbEh{?DF6#FLr@31Efiqdg8Ghc*~F4MOX#jEzz{|u=2$$nYGKX z3i~V(wQ~~k$StY0OA-q5EpfC9Oy+9ptmq|1<}T{I$^~g>L+ZYii_*>w*Ey66m(E(@ zRwAb8l}?w`MyV81|a(&B5T!^k$XIW=ie^_@|k5`9RpIXd~}AIh678!{@c@TkDv$ zQ|Bw3&C<0KT^i@huguz)HLcS)^i#9sW+}{L>#3LdmQ}4&IP_Ap*Gkt4$7W9!Ow3Wu zP%UcfgX;K?KOdu6M_d{iA4sTG`DJ);en9|kmY!F&0;w$AVC^I- zzUHQN(8pyi@(((^m3os57B6Nt=`-F=25Sm83$T}he3Fg(-5x&(OM*a~9^VLyB|uXi zVT7dvpmPuZj3P?VkVi;HNg)X25tvb|b4ACeGco0O1>iGaoJ6`JY1d?&lDT4O*R7nS zbxs{W^tV|ky|ic-cipeQH@@Gw$Gnffhdk%^WYI2Pxqx>mt~X2mg!`oZ#Pj6w^y*3c ziNd>zU)1%WreeRO0@Px&U%;>0snsdgsn#jisn;n&Q~)gI1od2*cz;{ZiJX-H+{S}!v% z*X{|QOrNm5D?1ck)PR*Q1w@m+3#bP{mjahP_h?T=&xJm+0u`B)3I~OkGxrAfINpK+ zrI|A?^Am^Im!bCpEh`&uiFy{!SRccoNGD&j(1}-}effs_S-c7DvnZ~TcpaKyFRs0K zTl6O~Tq*II=r4J==He~UpN(+UNk;}b9Kv)-Ck8p+gbC*kQgKL!Dd&ztemKLVdrZy( zKP`sS0u-mZOaGo#);<)0<_1onxefV7WfizsH-z;~oY2<@p z9nP_M(3H6ojw{}pc;pns{OZTq3PLVW(lI;Y49X;pzPhTa<>4 z)dROnw|$G2N31^V*La;c2w}kRfc}qLs9RO`y<8TL=J>1;c$8tWknu&`d7^#)2c~h{ zy|B)3a6kN3&Uxe}2lvdtCHs@CFKgFZwgA~s9IL>jY?CA$8}X!QlQ&V!f+UdIFHtHmo z+Tk(|OW7bTOMMf48~xAv<|r(cER`IGqaL;0R%~J_ES1ca?3JvQoVHB1Y_=>2sUot4 z)TtrGDJjLNf#xY9W2t`tM3uboAxNG7D>V9Hi!%hwzqZ}pQjonptOm1G){anGOk^CElS31VNtL>QHyzbTS zl>D^&$}#t@>@MxD?au!$=Pu^1<}Rdp$ZKxZs>8&F*?<$s1Y~PWu}!v3Jxw}IIZZxI zB}yVnG02Pz>*@qcC{5sLx?Ts~!rL%R8aFk+OB@-42Z_GP|Nea@>5{8C*Al#@TV+Fc zmLODTZB~8A%!yrqR~DAKwfoc6%-e=R*+6!fYvEPn1D!Q?yNF|}!hSz`+}6<640q#$ z-^iRP4sg$fXwJFu0pI$vuoQUAFGlpJft%$T`L55kb*K}2?WFV4U^UIwULal)`{}AM zIL}+0JYD~xdkkLj$v4_REUdv1Q$Ge}nt9rVcW`jkw;5Rfmd)Tth->SMowZBr&7}B) zi`kmZjr@&yyygReYSv#${z569p zPbPuE-cjjng(P32Pa$d#`uk znti*kREkLdkG(-!?vZ7C94rckj!YT~L#_#N86ttxWnr>oE}TA;X|@tKK5qreLARzU zBjReOH;;?A1&&}dU(T$&k&wDbr}9FY2lML9PUZJ=ST!O#=eHpPnI2AZnZ{~FcoPA% zrv~l3(d|st-V7Se){G+8Y!<*4z|VETPIoJ3<3Qb zeEGfm{l$CGFD~9_Iz*l(Lnl4BX8knb5g#5NgNt!$9s*>okWr(|YF+e9a+&Z58$SjR zRp3^KV1D<_45lGKG9keSPm4-@L0h>1yA{wuvvk!qAREJo^OiM&Yd71;Fud;&zp#V* z%=xj4HZjweJj!jD57y@#)@N_X_bVD2tQ0KeuOTj<+(<{Kt_Ldr$kG=ETb!&zYcTJw zs~gY#gOg3)E#}t3m|MkZbB8mMdX#Td54qglZY3pYZIghG0ugIc4xdr*JwU{y`+#5S z<7;^ydM=`As_#uy5n#s}lvwvX&MzRV=7qJIn7Ahusk_LE=nMZ=ublweVrTSvdn=*+ z{x`PVU9b4kQ#*QD(wzpLSoD;)l|SfhIZdH+c23h4tE`^%TtfRUcvvv;3pB4GaR161 zRJ%|fpXqZAW9VUJxV|hW45pt}ar&6)@*?N-*e51`?lvJX_0b$a-`d}k-h?_+ioMzy zUJKxgh!CO7Uzv-HS>27^Oo|NMW&?(AOG7oSypPYF&eglG6VBKqokvnD4F3Afk^r70KdwzD+`CxgVjh(Ep5Gb#FjU9`?(O*7Ehunr3QQ9@sfkavk`Zf) zk06gw0rGjBPKY=Y_YX3=rBQXrv1^5{W)fFl41zsKYCbse;5;3+<{`f_GwgXV3=%|UD*sxW*}N{ zrLSe)BQMX~#$>wJ;2jcK6kbuDM;_gBr{FS!0@1PrCIh)K?p1djOOqNesx`bY=+I6V+cP6Z&=Eg)`Y>YzK|(1RY^<2y_49~46B_XP0!|gWBT!%;y;56(Nbmb-EOnh~BFP?DJWR@7rNSbd+AlD-) zFZ#I*vt|0)&q(IL0l}xzwYJV|8~M_DO^!v|w@M zv+3NHez3eA45{mG^rtF3x|a~RNbPMjJ)OncNf8q|#)tU3;LNMx4rVrGyD3_R2Cw~J z%+It0y~yRU@W}~FLN*m})FTw=AC<0x^zhV`3v1Kjx6=b<_r$NKm_9R6`+iYkgnu#) z;;*-~NTj^vVoS&4wWrH2gH=V)`SGCnE;PmgT^Pj2CPC2GQaWMGy$)k5HI3W^w_E;$ z@}!fj`JJ$%R38Jnett7YRg5y4UWYnIYaQ{&fF0~>!ul0+X~E{`ag!Pwmr3PQw{=68 zcq6eH&3KCW(T4}6CuX)Kq`V|%vUWdFbxx`Gq>^uh0f~o*+WbAr&Mm9KwKYtrf?HM; zV$Bm6hFPwLq12*nKB4)xbFkY^Jgz|HiwvnrF=gE902M!#z{%(S&JY^bfD*r> zW&6=M5mndad1mb^EHKl0c^&(m{dI+7$N8SYktMh99%(JC*(C$1)vqtbG6n85iFv?Z zILhelNWm4>98F~7nQs|lwNbAQYUjtY&Nt0*XY!^f2YLAA>wA^1d5%(K^0`%)MNL%= zQ!&}RDWE6y7ly^^oX`etFh(poC}m<%EIe8Vc8(3RgG=KotP&ckAeU>n8csL$SWiUQ zT=+%@!|6q9I96WE9Pf}wHiyb%>$C!uYFtj|Y$_C5<^AH?YnZv3GAB7Sp09&A(nzBOUJC*hDUL(H@6 z1F!mM5dR6il-HdZ>eVb88AWAP3>V?@F1}8w)4Y5$g%U`e##>wk^&nU4q=a|KtMx|n zfavM5?4?VpMgFd~bSwDSsKxi)xa83gq(l&LApvmv?Wd)&;S8 zGM7!XrzxNF+=3X4&mOXq#YfoizI+|!$LgEne*XS}BKj?jbxxSj0!cawXL|#%ep-0c z6#hzZWXMW+M#|_j2}zussmK3TttzVyfK35yQmDfZ!tWLdBa3i z`Q9dsJhEDAN~V#H#Tt;XN}7Jm93xgs9jLKMaZqhhSD6q#QD+*E=(%E%7QiaW4*Pz1 zY4cI)g}QcHF`Yj#_kk39b9%p??q0X8V;v)Fz!F>kd^;Xs-D58j%%{7nEmhEwmP~eR z-e9SMN3S=l(i?5{j5j<%NBJn&x$Mw!k8DUg8;;Ce)4&@K!kIF`NlZg5fQNJRd9HkES86^i5rP z?xUd87sST7k$?gUK^LJPKO%spStYZ6T((hG@+y=Ip#6WG-9wWuO0*{6vTfV8vCFn? z+qP}ncI~q9m2KO$Yxf!Spa(s;aU<40$c#j+%=cOP;Y|7Dlfra4vt2@!74M9cLZ-8| z_)1T0AZve==EgMvOs0FxsAc)jN`+5!dgYT1x0YP|EKm>#U6H zN|!g$2R}iB;7wW}q-`LScq@i~MYwGh&Goy^6_k4LKSZ(oBTVO&P|vP}O0KlvZe2XB z+0Kee@1EtlkYZ?_6O%PFrRtr|LgjT&+FU#_r6Xm~dhHcQNJKyqCul04uD>M?P{w&b zmtYGgFX@9DH2C+m%Mu^o@Tu%8;C-Il8dux8G>y8%VPQFhB5fHCA9x!zTUv9( z!Npvg^3>%~aaU|nQSV@~*9BgqUaQ^YsJG`5>p5{XTNMAmrUz2xT8_}f7tJ#-@?3>= z=^Rid0#okc(Q?CUUqzX6@I6jPSke+Pquy3S-ta8_jGpA`a_TzQw`!o&~%gX$hJp?o$d|C?7{7z_VbSgQ^gM*cLEcX%ulfae^W#*sDyA&+$_FY)@xy1d}F7 zL0FYk$RE^|rua#btc5fNPkuM+_uzD>4wa$ADKP|g+49LjghQ+WSE~0f2}N_e#zuxx z>zvM!6Q#yTs>ue_Ol)Up5;`IIqeSo`Q4}EW;)4RccrxctQUoT}UZg9-D0SCj85-tu zlh4$YS=ue?os&qChuT(vDuGA-a0*-H%Adxua2{;AKGDp3D}T7SU9pkVo84DiL?Ey$ zqcKRmrsoS)V_eK z8h-45c8LcUJo7C3PrEYuQts-T7N#}XAT!lSy<20k*O&S4QNmAu-`S`B!*^qP458mS z1EX}hX%eM@cd?%mB5VdleV*i-;o^kLPx{>KzmYZ$#(7=9^ZYqMHCdc!*9a@02zi$D zvEQk2Lt0__VlO|ZWFn6oPB`&CiG0e>Ba1`6#XsImZ2Z6ZOgQrk&cMLgr}<-TtfyWa z?B6|t@^y`kdoHF5_vpRD_o2E<%W*zr!%trrS9emEq5R}W3;>vb#ql{6f|rqyqc6S# zkSMlskm9>!K)h$nneIPn1Nm~nuSR~!E}U&%dR07*I0`C#2woYj8?43UB-JkL|Fkiw zfE6N57AXN`i26r+LZpKGPzx1yXzq4*sp6dbdyV=yKZlpz@!hTLnGvuZNDk7zW1NfQ zFBH^$d(vHxS5n|-kHSWGYo72iy4R#e*z%#^X2F+qW&)SZIR88>F=b;0!-(C9wmcsG z&K03H4<%U=Vq>QN)Ej>>zJp7Hn-6Tpo$e)w3ty*zehc_Ss-V7By0;91h7_qCmM3Br#RB8>os+Xj-E-3scKFW3wl=%2rB|F9jrBHer8zIII`HIfY- z_lE{}A6oyBS^+iArL;9_37lD%+Vo{e^H!mq5Z73~x)AM9#FYAQl5uMayGY`MH16GQ z`>dN|!$NU12L8FaC;=_&{S2{VI?uLHxQ25d>k-V&H59CF+F?fdR)lGitynqyI@|o#7!V=!gAXp9Fo5jmn0cV)^vnFAEoLFwnxhpzB!U-n#^v^SQ#g^Ml z8n6*~I0XIKNcHSF(7^Mr^_g$3b^wp*PWLil;NWmfInWX@BI6Dw4qf1m>NqwiwnRSP z?95F!WiYW^`%dh}&F4;V@jL%{p*MaRxB+b#L!7?kCFE)Ja5os3@i|g>gMT*YA??1K z3}QapyXpS^&NNQ85&QOfjc7p}@eu&ozvw~c^$I$ku?<`3+z|tPG(~ah?l;r%YMnV_ z%RT0ze5q#hTW8PfPAJ1jvDy&q+EU!m3B8cM5I9eEyNY&jVfEX z-~qgXo)ZXK-IG3fEkoWIe-M0S2b$^FDn#E9b$@pEm^E9tx6W2Bw1;1%(de?I)kPst=piRW?uNH+gk<=ZH#Z6wO>=5IeW8*+<%j_vGdtD zV}7(nBh&)%$FjN{aWOOh{11XiseQ2NU+1;qvGH*$4;8p$A$HN6=X|uu8&{uROMO)%0kkA@$==L_}|qW{bDS%4EEg%x=DW%VmwkI zl3NI~@SHdfA7O9ET>U*Uxd|oDaj|?3#s@lDBqG;69uRa4_BKFUzGmNaxg4>ntF}E3 z2L4&!ZHAOoFMdk}&VoOpEb^fp8!2)qN0+d~PtUSU@pMJQ8ShaIV~nQC2o=Fa#}Xl- z5Io+aNP;{fL7|B5yMt{T)t#@}YW-zpclx`%z#e%-8^Q;|1qD41pI7?!?Z4;2XuHy( z_BCdEL+GdM_j&YsLdWHL?AwKyxEsfH!u_>20y8Q7K9` z4|oE3egNkRo!aAecZ$2y(A!`Q&hI1s(|0i&DZs;t{ds2Cw+oP(;I_q+hW}?L zY@CcRO1_}2+!ci_8LI%@wy+H%k9>hpjP-8yW|+6phcH$}_3dI}12`)H%`(y;Y@GA@`%oi_~!eaIf#(P1V zP_6ifIzDd2je~!IHG5B0ik--$dB2)qltJMU%L0}i2`=;rwATRz`@}1S@e^&A*k9_RgTLf2c`j z2PmK0nDKz!8O;AS=Rz?s_H}T_PxC%nO3-Bq1Mmm`;!aa#1||0{)uKf5j}8QJBcySK zAUSX1Url8-5+T;_qyhy;CSkTeHZ<)7#>qa83sv%0aE>5S;lGd|pV6zY*Mor)EXxdg;8PwF1B{xaw)b3{rT8Ep6ytzCW5ikU2`bUWUCv zU87TXBXRA*1(hFOa?KXZ1%q4LQzh-odT7psm`q17jmSOL&RFej|T9NazEh59gxS{>P8n{tz}PYs5W#ebW>f-|+lt#TNta`x{l6U+-j zBOlL(MV6H137B0PSxb!yYc%rNzJA&OS7APqZV=E0I|^ktj(Jgt9_ho9Df9(anaqn1 zbZGI^GnU}+t3pU1w+x6Sk31OMdPiOyFPWk0;4NS|v)d23O0;o4o ztN%8BXQ0t8$bmhvVS&_c$L{Q9H)6Tl~?uM3990a4#?My1cG3Vh|dU(d+AS`e4v4 zl?u>V@q7lwMd9n(!A_lQ#?{3R6r7>mA963?t5p1X@U?9nOS*dVrLM0A-l7hN7(M-t zLW1mza5fd@Ap81Lx4?z#S2pE7T_bn8(-nsF^*{ISBr+8tkwl57iFg(o7ApIc;!GzA z9}eoMP=EhX*oU|pherOa^{fP^u<#1qE)hhDja-zPB6cSs#a%`$3CGs0Om)UjvS0R3 z_~(#q0O2NctQVU9mOp=8`XDshDCcHe?XX|^=-(cI6itrrq@hsX8qus%j@L|1YOfVpHm~4zTgdk}sR7}pA-pWBs6cU5|i$+7O znU6Jf0&6@6*V{r-Ow4rc5ieH%hawmueiW(q{UInr*Plx$NB=|jL0F<9!~1wqq;Kaz zX;V}_JN2Pw1QJ~T1_wIVlKW?W73efWAF{QQ?Dl5x(|4&$V{H6x5YIt;b%mj;f-M1D z1KV@M)w+Z$6}baPl1^1hxCKUbJ+oBZl==lOC7C~r;%u*WPOJ@>HM9fW$J>Y@o z@_e$ffypMa)oZC&E3)F-;v?xfCd*KtUrvjZd1ARITvh5n&jW}*-i}-$0J2<$^b7I| ziA>AP7}Ds{J_==RG2zP+1eYz zG{L6SKKb>&S4+N{BLaXR0Ee$c2e5_idkb3>vP{f8g?=20RYG8#CuUuIGbrZvQ0And zkO-Sdl+PYwIc7O3Mqj+S^-IJd?mX7lp*+M56vFrS74Vt)g+U%mXh@dT=o*GwHYs&v zqkw1VehW>mF`OlL4>lSjo>7i6_)5=5g}7&9Q8IIU)|E?lP5F^&NIQ?ya%nyQSBz9) zjLgUAb6_YeML1yZ3<_=WcvLBXUHX03D~-7c?Ds-a!hw>Hl!FlyQSoCpR_eK>suy9A z^2nOY6g}m*%&6}n(IsSes@+!X6 zqULBKfpDRE#KN3)tZNwInr@+=*C!~QK8*c}NK{3Ye9A1b!X=?DPCV(G{z|5)BGH57 zzs&L6i0o(V36w+v#mU&;xeC71Ias~2>{Pu=YBi?%tP1iP<C^r`vGigCg*=V({^mShB0xla0%KI0xQogM2c6;AF$L?l$G2foxNn6nxHwR(x zu$1u*rioMtyE?hf!opK(G?vl5aA{n*)z&GSFqcSOJno9_RaZ-xC)^v!LSZRpc}!!Q zlf0;QN^Ss%C9SK5TOyKtUCD?x7q*+8FFL=d+I&OPC<$HU&Cr^Xn&desyQFGZ3g&w0 zC?Gbp`oe9ZB!sGFoAxw)6VS^yTOEn$| zD2VDKi&s}=W6t(S?+#& zxad;VU}aK}RM06dT`GdO!Q)bkHTmCy1n!N!2EF>@?3m(DoJs`X%Aj2F8O_Kflk?0N z8ux#O+Tv>bUp zMt#8)n^y_>1zdwt&Rqn$PL!egF$L^DlhXYIg*hZkq?&dYb80kbix5E{h#-|bYXJy{ zVB~gzAw~)Fu{xaCi-^Q>Xh@=5s{lUy`LAnZol*8*5J3|IQg_T#3uX+X{?V;8*mOpH z^Q!q7&RHe*OC=_OCUMFz97cj#nL=rIJ>|C#Sj;pR@N~$lL@y&fzqv~s+a^KX)qN@L zGF1P(6gv48Q3<~e9_8?*j{f5hi=-gZA6aMneI&xcyJl8?f@Q3spHv(XVv?~iD%z1$ zhoRIH&Y}grgaV#{w~RleD=i5PhWhiUztnsBB6_*Br6kPXAqU7zK_Xo=A^E_{K1d_H zxraZ&p;c&~@NgF21C9Vhv(yOefEcjYIPG8aX4n-3w`7J`rE4G_G8Cm!poT=dj0=hC zb(G~`sYH>z$0|i@)$!6g(HN@hA%i1T3hNwFb)^J(Ht`FDoBacutiD}>XH__Gbn^#u zQMQYaYBuiK4n%=6Sap!Wux!>0>AEj0zO}w+R01Kp+ifXlVHn)GBXftxq?cSmu zH(em~i)AJMlW?5$1z4&U;|a$djCU6csA*w{>fC6ef(N(+9iUC#wtLhMuH_n|z4dc| zB2R%I**GO!QXgZ&5k*QQLEJ9@^VvYxq$$Xmd$4vg=4aPmtJ>#^eZyq>vAwWX##is2 zv#acBqhz{Nk-LvlB>7OOgEEMU=V<~*J0Ir+QVX3`#oWAWV>k1)5BWqX-x%*OW~C0p zbjwwyy=pm+u95EzI!yU#nQ)uJD6mv5OIZDah(SJ6{xF@82t7&^NxauhvH$CeEkk;E z$zU=bI5>xnQt)MC#4N;fUj_995Zp#{~jm$FNJex1O1 z?Xn^5x}s*yg`Y=ob|LxJw%e8`0lvaDCS-yfV#VXI0UWrIl zGwuZN=RHk-eJF8GB*#tfp!cHYsjlN@p<$=q-0m||4b2Hiuq-x-{?RZV^qHVvnENef z5&nX6HkI4--9xl}05w+m8s$%JHtr6KG5f4Y5c1Y>;J#}188Gw@BN@D6daN}^vbFt_ zxka##0C86>twba)AyTInh#@j#lwOkWApw1fR6hdX_H;S3uP}LK!J?5+>UomxY-|gK zIO>Qv1%3Km8-r*OJCLNKj#N7*5{?$7S!Nz^~x_DI=FnY(P1J2aeIt#sWNc*;uHbBMrd7Nbsk zUIhTJi1tvsP=>~fJq}wM{N@f+T>A-psaF|=j^1-EY}q78%8O&nVfK; za-o?_Ux+bivK%F$jv5PoNZ;3XdGy)~2>hCT`6cZ?-2=m5J$lX$IdvXXNzIZP5g=06 zPoC`k+jZ^@4Byo690(Bdy4V8?tCtfh`_E(@(S0U8ySyWMn93Au$y1%G6r}~&A=N;F z1;P)+=yMfFmt~ihUVKPr$<2Ana@Xhf!)a4nU|%f?)7*NFZiGfpF;mbfko|O@cT}K{ zz2&Kf;FlL@Av&0-CV`PG>qRNT%6O%Bu!58+703O@wFxi?=@NY?^N?%TctCv_q=i=5 z^m;2;v5M+PL)lK|$3YbU(F2XR1(Tx0APspD_X>DphTYqZ@6p3tsn*k9W>#+R;bw;# zK6iZjhl;DniYVd_N?c1s(A_JLMVeF53AC)D30EgSpgTkDP(ZSYr`@I{q95lOIFp1t zSvd0p3P9S{_5SGthNV+fjVa3Irf)>ciWlzvadqR-cqxY>>5;{4seRXW8CR88xjmjA zb`90M3Ojy0{pK-CSKvU85mS3{EB!FAn|F@!fD&>E5OWmO+z6 z9s!)HA;Erh?!rw*HDtcv=AS5B?uh;Vo>UYM|6hyCewpA~9@vKTI4vo5@j zStE~IqC3?2oBdJ3W6ru1r#2<=aAYaPL0&rmOzMN44nQN#G!-9xaN#c*1C7dmftr$4 zScz8uu_Dn5zL=BB+R?zat?Ew-E^R%(-K@7C!DqIt>$png@;YmFKgSr%yZB*nzC}QJ zx)A+{H$A9lWnxJ$BjtNk2sDW9EYY<%69#9|scrI+3osm0g+snHR}Q!;!`7O~pp)f} zyfGUn0zFW|8EdTG5c9ZKQY_wFVam{B3wO*+O3i|Mr@l{!M1* z=w_dxcHQ|^Jd+ffY60_>K3*9>QI_=FR1}ix^_+7z5uy5+L~BE>jpy6vsiU|R5oi?< zB+l$ur(D-}<%91#xX0kvR( zEr6}c`T)H`OW~uVkt_te!V**(-#xIc#PJ(yQlF%)b4{TQz3adJ)SWljR)~QD4*r4q zjPklW&OiY8$!GDfwy@5N6U&e#QKs*`Akfci6v2+D=Es3A;x#XI&|=-+?vf)0#_#iz z_P@EY3ZY%Cd`}|^v}EaoKEcV@_$B5rxeaE4;Z$RQwtcxIZ(yDy)bGP>d>wOXUTydm zK|cQdU0+oCk$urs7nmuLA^I7*Imz5+_)?ad%EAQ`iW;*6+sX8tukKxC9<3^mY!6j< z(*jt0_6+RC!}~MC08D$jU`(nQQW2=(%Sx(L@vmo}$tB^ zh?7M%*!FtA8o8O_{+NgsDCyV4_xhda9PzPW%H&*10Sf^j>6Ua z+bEPj13aZCZl_kxbCs+rp4I8iNkbcC#~zYr7YNx(ec;#Y$^98 z``*ow8cYd4NJU2E!rpAcz4{a&6)tIq4|4d-1A%oFLcob!?ce)u|CLbgpTF%1klCIb z#7f8W!wX5W%1Zyg70|@-W`NQkO|iDU*GG|D;9GI-oKYz>CH&^U$E~pc^B)A*`OrI~ zH};gGOG>|mww}l`W1*ZIF&_^{;t4&ph=ez)*ba7x=01 zhH|~1?y1si`ZZ-5ZA;;AfEM@NX-~|Psb1sWM|}Fq*_^|i|18|c>|KvxpGE&0)f=vn z^z{|<*QJF4=#5RF-;SvP=hoWWwM~Z~Jo`V9DSfkE&z=BN`=6GxD`SfAuXv`TZdp#$ z>pnya%9)vi*R`4VYc+Gt*Mw`!Uq&7G0F~UINbH)sQO`LXf?fRYImI_US`VigEFXN6 z>&|z6{iEU2h8r%#NgTVbBUaio3j>z5hZflH{#+LNrT=N&{3|pQv={%yoJ3?c`~P_$ z?Egy-gqw+z`TylWc6@w1RaZLSvdLImM3N79h;{K9Na6#b(zR{u#4gLkkTUt5m26}o zux9E~pow)sJr(hU{@fBpV-D~uSrw!^*H$DXyi^j7Y1`nZ#ekqB@}d~OlA*5eefg|y zrYQ3B8~pqD<(f$G*xj(Xar3&n>sALqf*gs(SE6Sbzu$OlAAEJ)O&kbY-a$PKkKlWN z-9ppltZGCS*dYr)_qj~Z-HlgHSC-%ToPQlZq|_5K|7;iU2y^*9{}dH34nAq9mG9zI+|O#zRnrAx}zPo{dbR$vO2hiVZPC~ zcHZ~X&@!^JTvG`6BJyh}Yrv(Mq%Bz`U=9WZL~Z&F2{DPp3TPz$Og8ZBKGuy-@Chl5 z7y$4s2hI+}`~oc4bx2to<_2)sE@=bKd#C%g*CGY7*q3(`z4#NBe=V|+-dNDGuvPHl zhNzoa@~1Op_X4N|@e!kuF+X|XI5^x#)#cOIOwoUYCcjvZA`-oWV z#C5`1O&I^agY7!UREhdYsJ9`_Mlh2eAuQzdN%4ss^I%f(set7w(D2E;=NZs!Q}Z#% z9WXGjrzzl4p&=ueX-$s01}ibEgr2u(hK|C0#whzh|E$ipBvPS@EjMH~8h`3b+leg; z%FaE=hZ++9MT?HOh(k)y5+hA5^(llW{j{uizPv+42V*uyj|Vk#`0i zHR<|KYk5syEVIBw4}Dp1=qg{zWPDZQ+#wW8zMm8tH~W_(y0MARg!?7!>3t-xwIX6v z&lu`p<(pTwuCH#5DZeIF!0(WwJg#AylaX~rnl@`u38y>JXOp+l zgWf}P@J=G@HktLG@87Ux^Cz&o@q7X6cJ8J8Ma>nYTfN!beEERa7Gr${Gb&izntvCU*gGw4?S7%cezD)NGp+XEt& zlBYN$38Qk(JtBt!M0M?lC0N>{FZ866q}YVX8%k5x+}o3HpyKpqzhcY1EL^+}(RK6R z`E~nZ8c}`;%KF6UE|R;$tUl47a`%5qF7S`|sTat5`k-b|jk6Poq2l=`?^N5C+FA5B z@_Hl`aqw!235@a$tZktiNJjWldO#dVrm3%w4brMPtg;8cq91AO_~}geQ=N4x`viqq z#X20A8^B$u&t7z^&=&&c-E!!lR<<9{1(ULvrwMy>0N?S8($QY-KIT?Q zn{Qpt1|`FbgWK#gzD#=|W^>?J53o zq}d_*=p)@YQ^tFATel>)a>jibNa$5FJdgi5BM$>N0W2pGFFx)&Um&K6GrZn`TG z!Fm1eRs!=`W60Wo08`&wr}uKB;TVZ9`;K-dl$SJxH!+KF-_Zl?14|<*sW?Vebya;l zn%6W8j2XC$FkfUCHyA<&=#R;oVscMKT`c-%ImU!{8j_PyHL-(cY(C+_auT-QMk>{) zvz8$&65R`0nuf}#P>bo<#kE1PwNG(4LV-n2G{O>JlVP(HCGRN@i;H0o_y;u&4MbX{ zgmCn<41}j0b>+jO3|cGnw4(7^#Rnz>Lkf5uEdhRQJuGM=7+HB0^-z)p9NRO(aC*97 zeQV$6`8TFE(hPhWf!P+9~HjI>mZMG`B61xX{VlV?RTVS}3Cg{)Smd@{D~ z;B=*nn)uL?1;wm}Mi5?lx{uk?Vc+(xty8(Z`;r`c9N~M3VeI(l9d%uKnJiTmZ1^fN#FJz?$C5SRb@5od~}l2^w1b#vvqS<^U@w`!1TX(P1#CpBW=P+B!(w+WH;E0 zr=)7hj%F@hH291RH5zkK^s}Zm=S{bcSWDq%H9ZE*%zP8sN*2D7X-;ZwH9Ur~DKgo| zr0kS)YZPiumhRtQ;%@mUowbi?#l1R5#2Lr25Id?)NZ0;yf~(vY-0ptfg9?`jyBy}CSKtu%P_3;fjMGPxD{&m8^Y1>CwJ>hF0E zCnC4Ub_9$pk*ddkJH}T0O^666o`6K~6nt;Gh$;KbN=o^4{yT1FCFaVnHW)yceEoHh@P|AzmLHw*qt5Tv|CKRFQiez zU=H2T7jEcKVt*kMb5C!mC0ESZNSwZsSlG@>dA{Lg5=PGFT?dg$@d&1EVS?*IAXioMY9bd@-zL30KH_b)Jl5Y&y`=tC(4d?tD63G#~9vcSB~(eOjY$t6lQO z81_m}8(KmI$m1Mmx+#_wpLjKvEtg`u)iLw_XG2g$1V zd&x%8>7xd4Hd4^L_{EQrH>QEFNpO47)ge!DY^<=~cY`u0n&ew`=PAYzVH0TqNZ0l^ z#5BRkdQDb{D(ZV6u`9jrTGrw*m@cSMY;ytso;p5spF(z*Uu6)pch@6M!Jasq5LHm8 z^P86APa*TF3fkjevxj^g#A>Nu@|TW2R32}RbsILau8nFe!CS8Wpk&tys{08reV_+_ z@kh7znh^uByNq0i~89*7#YnBlWst^)UoISO)(;JjwJg>$v8t&8203R>nfwP}C? zpb4IF(M!X``Dzb_p;8_X>gJd)I16vbG$V&J@nWsm77a8L1)1ED#R^LT(#pBw^|v;t zKuJGOrWPX0{hkf698m^=J{+r#?CIQ|1X#^#B{Sz_47DabX zEBC{$?f@YWxRMVQhX|AdlOh=t{1J8{1MCw5x2NT6!Rs}-4z`2_)+S+O&@wOdk)R#d zgrszXv_wx$#yZee96ey zh+A>dyO>jrFrCb#d@EM90w_MxuQPs)#Qnk_fF{paBT)!;fl92mQonesjB%9Qn3~!&Hm7a+2oE)Hg%Tdwx+eB1U`7-QLCEilZgaM`>>rvvTS87*-w|FN<_~bQkTS6-oSCgNQ5Yr!Q1~ z(tA9THMHmOf?2Vu!Zl-%tz2Z)?X|H%#gb(}8U?QuGDF+A@nH)KmeVuNC~~-AlA3G` z`wCY7nv*HhhuotXC2ECR~kLpWj=k2naj_eJWN;(d{j5&GV`ahzz{sf4`CP%UGA z6Z~)s<-W>-{uBEJZjyvYJR-%=$os2`U}3kt2g zvLOo8lX=oELSNy;6gQ)Okj^@29lbBHJ-$wZgL2n|&u4>0i@nH&5oWnpOb+_{i=y-7 z2`oX$_t(2YBsi`RfpI|JA$%ygP)?(D2uX1~W^{3~z>L8bB!-pfHP0Ir#f)<-)apG_u3*H{cN~K9GFw(Tmrq8BXo(FKE%^T~$ww#T6?j&HHwVe48 zs(=45z=!2Y%G4$Q>J8jNhFj7VH3+3L>DT?^Gv(AM_;Ym^`GGWta#c~@6or?W;(6Z6 zydYCh?B)LmH-up{Yi-BGONl#et}S0nL==HX&P9MdA<-pU4eD|uc>M=~??iCg9+oOz_g>E5SL4PXN%6P?$ z7lkeK(Osv|ubN?NZD}H4tV}+zZJi_3vKj00go@d(n{M}OXK_p-VFI{R=82SO2btAd z3Zpp{#pVGXE zt1d;SqkfK*1-=<={BWy;RYH{Ql~olG(G;K~6yiaTmIZ}IHJqj<8^-LtyIm{Ezg`+j zxsLv`B^B5T?=)n{QGbOU$KNv2;{r2;?^L4PII%F zK+=u_^C1t;sj6wpNzS5EybeV+s6ly)cema|xT0CYAV7QNoT7@6szVW$9)Ny59FShr z+)=3>ExN)HG)!eWr^a=|%qKOH69U?65 zY?~jAQi^3QLKg*kbwJU7#kDcP{hK<4caDD&zd|&{oLF&1V{r1{NAqq&d~Wn5ql#Lz zK{C@KUWcb0z%1J2cVL`cAYdRqG7Y(t0J3LOhF{yV%!}=RI!$&Gh z4-+HIG{^PuFB?P-WS5(v`YFrtH*E;M1^orYqiOij2@%V{LS}PgAk5NQeQ2?=3I)OO z`H^jG#BfaKP_J$ZLg0JsxVFX#&IerxsX^2ZF|4q&c)j4sIdL>^ipUJBJ{EFj9J)I~^W34^MlN3Z&!)ZZ5}ESqLkb;Vi|AcAL!=>0S$Sy15DI4 zv>%13EGww2{v7Gwp295~)J(5=^`Ar>WFw}@p5s|h|JUe6c@s|4JsUos9Ku>>o=wC| z0pC>A*aWi?%lYkZtHQ7$mO--{wZswJ7_vnZ8DkD;gTG*eCmMnQ=_nv@G)Qe}A_#rl zc*HX-snSkN2{1}N5f`Y0@P2Jfh6~ILvtFLY(vy;W%e))wpVEI&rKzv++NXEBwegW$LjhV8qx z+SG@*ddTHz^?icxLNuEwu2yYl(_y*4;ep{VWP5m19FhLDxf0TZ-oDj_GPn<hD!I9^l@2JiEm3FIoFv8H>W=kFZO9S9}BvbyJysPGndsTz$bMyiY*j{ zIoRi@VTZ&x!|HZJLjwU(xIyi zqtpE+XhBF1dM4d~m&32Lc7d$MtH=tXRG1~TNUv}edYv}A=}b<8Q=aB@_f=0Bql$Gv z$w5a`y__17JL=0EH0Ncw=mV@j`oHqK11q+azNb+F~ z8B&*YDB@-|1?SR_c+S5oW!vT&ifpV!C1?s=l*E_}X7*H7IW=feO>xb&62!srx1T#; z-G&q#n>(WRu@P}q%PlJomATZ^F@o+VOo%7q#;O86X+?EMh$jIIk`DN(LYlmEtb>1{ zr~(OU7nF4ZPUYO4h29jO25M}n>Q5uleDTJW!1c{yT{H+QgdmK6Q~>$-)t{p)O(K9* zdR-VIPar=nMnM%E7I0@F#g#L-dYM{nK@BK^g16!CgPY?{@6O0t9VZ;3H1RF2M}Lt)MwZ*2rKlxJ&5-h zJKH{e;pl(!2=ro?BGhUMbk5B@>0DuHdEw4_Ky~t@4PAykG#4`v!LI6y*`Ff`% zbiEz3)bG@bVUhpF3sJBd(jhd;=83hEHHQ<)M3Z_RJDams&4do7F1JD4X%v|#V{jO$ zGf;AORH>PZmNz1$E{X4;geSPL1wWP(%o8~K_$T|?b#rzSo#225fDwlQ=abtpk~@d< z)weWtDUWCZBk*f-R5+Hg{bGIlUwt=!(46pIaaNmw8RrQR3}KxSztHRo=?!uCMwpos z28fRG87NvJr!a?&FAlN_!0?(%B(vO444)=^#?>X&C1G+qZC3TjI^cas27oR$^><>( zplfKsgME<&&k><*w_rQc3NeBS7NFuwdy6`d*3;%uq5P&ghw6$Iv}~t5nPEbonucz=M_@OSjt&$$e-&ivHm}V5%47{^H@R)j z94dEYajzn2_@t??;g4;16!#R@!Pp(zL*Wj~N0txZBi`}A9YOX_nhQtr6Gy!+%HMTs zTh1G(TT|Td4)6+~r+iQH*f7#&6}gHW_{j>WVriKOK-=&kQMnq9L8wtaD27Lcz#2VN z&5{yqU8rPRW_8BaX2j@M71d-a@bB7&S&pkhkZXc93xwUE`y#h}eW`s1z`~c(3kO6G z|5)z|-}j6sw#6B{3*;X!wdYycX0VjdBQbTqmU?~PO?0(SeJf-(G61^J@et~QK?7{k zoR73O<2)q0op84bw>>4?kMNyTvMd>kpd>zc?f9Ct>xIVK_Oi>eN2BAtozPRzr~;p z%L%E2Wdc-_X2OmKDfY!XI=?oKr;dyaugKxY)d3p7_9W*IYX|bd4-kYPd<|svyzi@E z*fXRBASCuc+w>(yH3EYe>B-^CM%rryJ57T3^9|0yUnDKZqxe@Ja4c=~6k23c|H;pZ zv@!Y|0LlhA_bL$x)p{V90xsLr{iwKf(sBP&BBP_LGa`)IlsE8DNA>Ze+~uv-d~>E} zbuf{=KmQ^Mw~*IE^SP*%vG`>SC;4PQ0-k{gYw-aYWCKnDt*L6GJZ>5XrAE`i1X%Zx zwyJ_k!Ojq+hnatOKU49(nHS7RlaW-f5O8s+qLm=u@RSUs!A^?@lqrj3$*Jo%t0w8L z+0o4%!%QDY%uaF?-#$6~n2VEoEB!fZdS6HO^h%A}TE7_;n>3*-8csax>UB>O7kl$k zDgQVzyjV}Aj|sSV`y2m``7-uU)4dFY>N!6&iJXGYvaQCbFtnbw^hmEmQ-<`KxvN*q z@}P4FBeHkCPyGCOsM8_X+-?NKlvQ^dgMQxh5($7BTKoP_f;Mo!Ed9yON-I# zmh**%%=4KrHtyg}B-&31WB&EG<|70>&i!THFlHw`J%9Le#6{+#97;2s zm{^NhXiYynfD;*lE}7wr@@_WKQLS#_iD^{9N?N?=5QjBXzc+`}QW5F*MK-pvrld_H z`^ZckQ)T7BQ6^nrZRW%mJ^fseC9_1?>2`00Yf|KgVr;FOPD2OUv;-XBKz*JNiO0R~s7Kz)DOad`G7zEhm&g7}AMwUNfvNYUQ4kL%C zX0jDq`DcT0myuzK(JVlh>P2zA;;Yv6k3(;SvX&;V8<%;8)t?bNMkYl{XpP>(<(r4l zBAo{^5Lfkp9W#jEgn)}x1w-IggB#~Au5sp)06i;%5~v_RI2$KR#g)Z<%pbMpC`OH! z<7RzCLSU|F71>v6Sb`E3IR?#t0atbc!$dK-N{6(8Dv~aCDPg5S(CLX&rt`TyGEH{K z%NMxllYHbQ4~pQdnR?X`3x6E+X|bd1@sC`7SFTk}RbYHvBh)JReJogUxR>%$ zJZt}Hx1zXg9^q5xaOX3BnalVIwn#ZmLL9>-Du)doA8DqYT09zZliw;cd7PYT1p)Z@ zF0%9#tI&hU>zLsllB7GZuydO~cqBCzZe^xT)WMKhMpr163g!&eybp%5GwiSjM-#Vp zf*j%6>YUavN>{ZtI>|Hw?SCQb4$t5-M^ZohH_iFSKxas@r?Azhvte%S0ab=KgMBn}q2bNj(j&Q`oPQ(OW6y?E(v?+$4`OGqZb;U8v z^>)2V%+2>T$@9yK;lWx%Z@@O%YAmRoYKFLsQ5sv|#ieA^d_zS<P{!C!%v zDXOgzYDeHd`N@dx;o(Psu5=bOq-Mq90g>oz*D8;vBt~~M+;)jgYIww_PIen!8IQ{;!KV)`80LS>z^ki22RWj)ABP)}kKGq2ddONJW{9_SJ zLc;cEvca9cVE#cGT#QN=UNwlBBNYZ*we5@Phw6+NS1^r!yd#-DX2*b@o=>s__zsfr zFEI}HgdTd!z54x@G{{BGLgu_kkn5!jgNYz!8EX-dv&d z$f4Z%Y}Pux=56BU_eYu;x#3oz90=Q{MIp{T1F_;7B~M9B@<#SazSDExlOx*YS6E{j zfw|Q7$>W!;mB-6EM=e50qtxASsZ1-p)y2vpkgr(nruZXz=oL9+BdocRMS1IP8Z_t2 zaf&1riLhSM2Ay^pl&iRv?5vQS&<8m5flNbFVAx!Pde}H_L|FPU-hlcLSl)qk1&Nrvt+zD4M1BlfjoVgcm5(#62Kvy zD={bJoLVbSlQL5t){hK8MX(>Y&;~?)2xGSehmMDM^)|0V8|sP^k`hO9a84~WyibOm zmU7Mm@r$g4ToyWnw6SES#F~ACQOUE@knRONJQnQEWl`u*V5GLp^|MZRR&>X>ZJWYw z3$G+sY?+IR0&fn(49@={h3k+L5*_32(|usJd8K5SvfsgM{12_4|D>Kgu&{& z|22*|7UGjVgu!iVd^!yQ(>oJ+&4`krV%JOdShD=dsM{N0x%O5@N1%60;ce4r_29rG zu+%SbF01$O`JQn5n1~DQKRIP8!+|zc-1$}LeN3ASQQj9Yk?PwRlpR8Ml_tXk?rRIo z63CbX!n&JgI0>2?Btbt3e^9b|fuG$-?V&{ID%cALQO3#n1p`Xy zpPG!zEdEoDb+MDxOV3H4neR06DGW{Vkc$zFp!E;+x7Hf`JXGCIxhY5S#1dd^mACdv z?Ep(O4o%7ul+BfGIqd~|2Jn*ZGL{Kq1z&-2LgEyWE#@%EVaLIMrQ5z0MWJ+K7n4{0 z)`bbbbHNMFl=Qeva8KK(uUmKht()9Tc#?I-%4l5>WUCidXpWQ4WkG$JS?wdK@#8Pc z@|eA?u$|O_Nd#g*@(Kw7V(p$v8%O2vUqu=r-}B8})j=QPw+~gMIlM)=C$P69dsiF6 zGX-FI4+@b>JjUL`lG+>C7AqI;A3*bn)UHa{7}J7 zlP~>s8AqIgf3I51R5faE!HK)yOxA~)Jj!}6KMn=|-a>@7Ru}4HtXXuP${A}A41AvV$A;(a+b@a10%!OO$zY}>l|3l=F zH~VejV#z|x$zRrUc2AfrOr6s$-|d4pAlx*;OCj2SHUDi$tnbvlvY^!tJ6-=<>dZreTfdp71b zeTjOBopif2i!`LHKjAORU+WKDxAG7-ZS#xccdxrb9i#; z)xXLT|DNvw6W(vH@s}T^OM3s(p?<8`NY{})2|KAt2eTtYZcIX1Rg30WkR~C=GnAb1 zn`7pM!YPQtNomKhLt4@Nf=dGWvwwo*SQI)j3{FVLB^wyQyb81a2(h-7_)4LZZ{IHb zIOPzbKtS0HwKR&Y$E}+QH4!bo)pWrqkF*(@`MW`?(q2jVFHkO0qvza4t+6BDtHUev zUF8YaHM(O+)XvBr)v{sUID7~fehkoiq&s0cfi@wK#*xOb<>l(U&jKm=EG+#?$Ha}S zpvfV1q57vK2=E6272l*& zW$qD!ka5Q0)W!ciYr zZ$x-z)IsE_$C@XG=CB=-zE|gP=yh4NR)v!4mb57kO*h2Y00-sRH4?PLNdA=XQNoYm zuQMXVa*b#fBC;>%@IX;QMjnKr+7fOK?FSExhS?OY2_x?q$#H>r$1CcBU%<{$)O4Z! zgnP`u<^c3tva1JPw58Ort=ML;zisSYPZ@;!HahJqq~t}X-HM;#V9w$z5EsGbAa;9S zY#s5qKphocm7%H9e;#BI1bnrR~^5J*pjnFLka%Cf^~JW<%LX zRpqA`Qn{3EmPR#7bi5J!jJv5Zqv4|+;QcKvn-B=W>N{3L6|RH??uC<+>IX6( zZ=>Y1^Wv}P*H-9i%p^nf65*cirpw#u+;Ab_2%&zZ4B`4;bPkn?tU?sKym}pL9wi2f z;7XEHtFUoM0WS2rw~4$evfrc2kP*en$%PAv3@Ob&LIgNl{4+v_&9Q$^kJD^UTC;Kr zaO(gKRff}$aXbHM5B}U_0z4D~3>-YU>UMg)Jsua{?Hk9IFXdNNbvx-T22}!IMpLn6 z=kwMPn%!cWHADHm-_65fGjX)g0CcG~1B$BVZS(0=tG^;54`*Q=>ozcg9g zXhsEl)VQKc*02U!gE*h!n4}uCKpBDBMUdONGefH?6!Ycz_gcfn_SFj;TT}+qkMA=X zbMw8C>eR34E~{o24i4a#F5ciUMYR^Hn%}+fHPXhmYiYCVeMd23croIKkxy~^59#pe zCuN`b6H;U)$JZDDi9(Ot-HrxyX2@J4 zps58_j6{vIa{O8p;orF}F_WW`B`aIr<5_D%e{Tg>KG^6W;*5bFV@Y*`ZKwr9FP#nA zRD3$)vy4toGNA<8l*4!>f$w^*a@svRE2J&rZi)CTjk~scPFV%XAMx!P2*Y<<9Wg5$ z@OQspV$;6$C&CrkWb?RLp`MV1zo0+;-)&s})!8stJ=?hj=LWzs6T7(g(H{&{Ru)rH zNg?+@P*f~f^r=Ujm@|7UPTd;0T83CJ8`gy?9P!VPf*1@SQ|e|7ahb!otxtkK-EY6M~Pg~~RS;>H?>k@mi4`aH5B7{Y6P zR~nR%v7eG$XbezAmTr^~9Q$}#l$-89=!*AWP0z;Z*82Up7`8WXbhe&yuq=_dJpH;^|Aa>~V9 zvHjN5H|JVQpZxnVex)}>lbIr$hTvT@R0dk>r5oGLjTF%-Y8&1Gjuu9K z82sKot5MJWV^ElYbio_YVCt5MsZuc)*)={EcddT`J z5C8tx|Lt;J?!&x9lCUatUj3&(d2V-y)!=gMV}_j%Pju*E{C0|y8lq4h9k1w#jQfsW zdSaD$50mx5rk0h*@#VtFjM?g1X8E&7#(HQtNw_Hd_yH#q&kLfrvHs`Q{9m?)q2UsR ziD^Gbe;b6#pQ*XH0+coqrq#7Kx6aUbwTJ{>a~86{tp_%czBXxPm4N3l55`+46F(cL zHzVQNBO`4s8JtDZ{ni6Qp`LJeQjsNX6rEcj4z0$2bD6ER2soV1o-)k~eYIS*j?~vOKW0O+NCiDq4)gN- z{E7-W4S5KM{*b{vQihLDCEyV>)B}vbBsV@>u3d+2^2P0K_FL=ZWP3|ltPQS-Y}1c! zNK#pBE}Vuk@Mv8u*BPXzl5rrudCO1L9IyW|)<}-*&};K4-RmS`Tv%!hW>MQRY1LZV z?DN5h($*;Qky^ZBsuC?PDk{E#Zp_To1C>ItNPYdl=y{7DlyVEV%RW8Y2P5mps!Oax z=HYZ)Y;JU2k%|}Fte{@OE3Z#-d|;>6sU)-X5=*ZMV%{-zVu-7>`&|*qXw>Zl0NmdL z08SxZyl*djZ-LH6?5lxL{3ifHY)0U%-eBs4cp_0u+m-2?n>J*HUOAE_estUuO7N6| z)C+_^dTW~#sEtW_|K4}#2&JQn;_`1gJYIvZqq9VPgCabALvR5ju#bky%jE72vyFli z?qVeV}c)p;ROd-^NmEJ3JlW+6T@Z!r-??Uu9a8NZ`I)Y4?G6NEJ^_oC9HzW|2cl;>*h zcgA{Kr4yHxnVBEGPP4AkYx)x$g(S>y^nGZOkW)L0kw8pHp@HiRLZZie$;Q^#@j?nZ z)_eJ~y-qZtuMol%pR@iN{GLzMarF&ZzCqGDXT)1^Mnw_atwVyx#&?Le*kK5N)cwf` zk~lqR?_?PSwoXh8nB>z#b3s1BnZLe(6G4rNYgOR|j%TP{N;1+`Q9B#OP%ln{`?6%# zRgYKlTI&_JN zkB*Lui;gb4hrfxtqvK5-@i<>B{11G3m=RqKa!z=-8scM^vNJfmpZ$>(fWmS?UVLU| zPmu|yDL#XTcgW&JMBJC%d3=LV6mW5|<4>21Jy=^Ui_ZN zyAw%GUsq}b$z02J(?c5OgiD|nf8diwnM!`sq<*;#+1bYCs8KX#XVy7T zT%OW4k_jsSKnEq`le5_e89cAX7$L)`AI~m2(i^a zK94+3iwr3D?p-sS9H6nxdKsh^6c zdhrb#Yv$i%h$Q)K(&#Z#G&%Kg0~9irMm`jGRs<#iL5W=$Xja&fYVt^F`$S8$I9zL( z=l6so?rqF`%JH3pAETER0JI}@_HRkDnGKKlfyAvb3?J<7;xQM?Ed(>u${PUps z?LN>cfFC!o+>~HPjKhvdqeSr!VG}p{Dd^O4duZmne~zS+6ZXe``OKUsiPw5)mGKqL zqR*VX^0o7M^7T|DKQ~)?-lrSLwGUZ&ck=)81758Hc;7z0@A}ne{Pxzk)JXG7Am5^Y zBUeKNyom(6_edSnjRAWNQPwdInK}bbsrG!~-sw^N?7U9DB7a|kVZipu0)$ZxNrLz> zloN3%{9quAICjB<^bfsY(e|G*EPpyPNBxoJkAM;|hPiu{W)|lm9D?qgs>mb25b)!9 z8ToST{ZL5dSYXpr(^FH?+iGNtW)?kFXhL-yof$MKRJtDvCxCgY3F-{q$>y0D6kHV~ zsBIl^?caoqQyiN@#zz?lbhsiyCCY0uouYvcx#S!W_?o{xBrgFG_hXseaX-6XJjMN2 zr9jG#T03QIQZzsY9iq)4wi7SR$l_3Z)70ZEg5^@M$8uM-Jl*K554Qr1I9G_uN z-ee87-Q?uh8yP?Q6aDY*J;%<+<)`yIUwG#R&AvTdpOopPDTq^)2QLIkPeW&SXKpWp z%zwpr;oS98E428+QYC$KJ=@6AqxWc)@ zodJNrqCl7ZuN)1Rqh3FR5~FwA-ao}ye-svnYA?L*^daxDH)u%hqqr%P-66)IolJVV zS^a`Nkk0SA(~+qHtpn!8E6-d7$?u!NQ$dEJUo!2Mil#L!xj^mEK1gF5B(??a!kj1Q zEMUnKgu(vbj$I&1y}dW?jAP zJ^B%8mYrCsU{82kSWq}l*f|g^ASWP5A`9U$P+BDrE1I2v`iCX%tb74?0XeZjL8@?t z@C|rrBnDiQehG5{T4EY;iHIa?XamPz>9XiuTO)Fn*&1A1@`XcvRDd7s2#HV=9y5A9 z$Sqn&H1vL`2jq6N|A0RiDa%>tpbW|wsX>zV{ABl-RhtahyMtpu=w|CCxc(H=vBrJr zC+c@nL@Nm2n<6eWw?d0(i;kPfGDB-3Q(F1N3kYGdfjTt?8O8(VSpY@U1zhkLAEhE? z4<#(+TR?L_JVnY+QP}_e_yh)*@fWNCLBhL(v_leZ(`!pamP1TOF-R_}4;ORh*M2Fy zdQEhvJv{*^2jSjv<5*RdPlqudLDNaO#Owz`b2PR8O}BQDZaJBB=}8S%Dw1Q6( z#@h?1HJ0R=?=QYnaFmmtJJL>7L*w6{A>M=V0eXQ$(`h;DKito4qDkvbz!gUDGg9qP zVmCbKKOiuS3y1Bz1PJBucX^9HC~pwm9z~X=5xWm`b8@Tc84k~lT8;-J0KJ)w$(aD5 z2J|@VJ*1wq1J-T(+KpEp+;$$Gc26E2&le(r4u9aDnA6PC%#3SS9T!a*wiSVZ64O4* zDrDzA3xx}VLOIbwGdH|{2-hxsgb0;r7c_q{7s~vf6xNzytqOqZUh6G{7syBM2;;jm zrcac6>Pll7+_T0^XMh1>3t)ylQ28QAS5LR;z;d zn3f2P2TWk@^7#0g431b0CVn^cf&6{+nSFekz80RZxy)LjSZ7p}Q&g*+zA8cTyTyz- z{lszDdhXVD`i^b*iq*)~=vQ04t)7q5dIai-t!*ul;zl@36jVMM36%IKarJ(VR+cE| zpQe)3^@FO)PK%jkTvju&$6iP5$LSACmN@?YqC#+QslY>&kVz6eS#xwilQ2^@;xcDK zc-R6GD4GAz*V)vFjkT{>T&Ta_>+8uw6!9yjiw@B5aeK>c-N?kb-|Dh|K1mD@v1H<5 z5~ok_W;m^-A2zUT`^_Rv2Uq9SA950P%qxEJrzlYx;!7~k<#SwDm zFvy}nJateF?^>Ud5~`+p45-yH35sg6{NN_QmUAR9;-oYB#YNH|dp46>8oP_w_E!VW zG0b)_2aeB#qkMmnybRVHm`}LZF$^(Sd=$&t9C(7n@7#yW9{Uw9f;(CR!h@bs!AV?! zaWMYG&Q5F8LmiT$TyY!q0quTC(+k`v&z^_>gDvRxF;=GVmcO9*p5m3jD<-FXUA{)1 zrKqUgOA5H0+`AOOQb(kCLJZnLxobeV3ryH?YF~%K6|-d+&YP0J*6^!VvSRKQvAMxUzFK(<$Pr^cm%h~(M|cX zQ?o8@cSJ}<^WXCAsl^YKF!tw9_LHNtG||G&i#>61tx4pW2kSsRzIIC(`Gdv&_HV~2 z!<}@=sR|KZCeMh1r_f;Ve!O_Vp%Lu0@cA~d&wf4HU~8BHPgFW(uhDCmw{u_@E@y7H zm*`dKF#c1cvYB?`pjaL&9krY07xwL;I znNt|$+;ZV3=C=CqG0!TSP7@Iv(xOg=t*on?Kto*}m#&$d7)zwjvG6qB=Bi2sxZm5v zxAmUph(eJ?Lv{~T=Un5i_)1t5oFKt#9hg6${vPI?K~3XArdaUTGPyd7|EW^wcaJ>L zqz4Y+FWrjg@Bu02_z!~e+|b84mioaEe$Qj##s%PXrcmebu_>H5wRrV1%nOETM$&Qj zx~`kKvXQyDk@E4;2$a}~N%tO$)nMMMomaS@Sk);3KZ^Ifs|y*%K7CFk*L!{o5ZC^cUw;n+ZZ%+2c zabj21!0Huvo_BwY^jkxA9K$w-qx;pu(EG~Z*SOTHt?t$DYdjnkf%6p5kdDOl#c#c+ zHj}w#B~xVw#jBp4^U+BVa{-f=8e{>-a?(d4C72mkS&o!oJ(Fd6X(97dP?JkW7nC@* zpSAx-3pGHl1%s8$&hFvjbP4B(ujtIdepL@>N zaMY<*g~<8i5aR_FeUoY>$WPkeFTDZDMzj0xG&vO0?-FOiIi6TdR_M_w%DWZmkP{Hx z8W&D33!q`=P=$>vW;&f~a}Cw`Onw4~>(pV`ng3x`K97UVR#=GjME- z%Z+E=LrBOGQRTsk+2FEJX{%Aa-C7G5wWv50F}`v6c?d8aBwa~$^)=%<;ZD#e72o0C zd>4Jw`F)3DKaKpw$o=kNsCY%LgTLQJN<({g&*E(_=B0JGpIkbkgt(S-&RRP@{rlUe z+$SxU%EeAs-AXZrc=R8vzt^eUx>z&U#(F}2|>S&7ra6!&-BC;j_po!wJnXmM3# z#6jxug@VxMs{HaaatNAR{eP5K3e7=D^8gl; z8v%zUZa zplbq)o+h(Fz~->_b;126PrqldA*zi-w|jlop(eBCw8HPUfUH<5jgVc72rr1r5R$VW z{WG}bX;nzNiD;4&2^rDC2;6)KnHR57@G&cc9YG7konK{>Zy;w zp9~f&FrhqU#&k=YSz%bEsbCqH|yM$s5>+us9u~q?GuLa{MF9k9s4i zh}5SCWI|el*F**DQ(ITcT3@nJBi8_~7ipU{I?fw}?%Q@3mxtQfb?kb*+b*T;8Tv*3 z!J~S^#kW5{kq8lat15(gQC#5I6dpEzG_ZH6vM&D+7&l*M>dlL1{7aBI?39>k^C!8t zPzObLX14Pu!8zD1S%b0gQ4C~0SD@Q-nAJzr;PNNsi)&u0l<-BQ0-HvsLq+k<*TqZN zgwN^|2Ywi0cmzjauTz5G)Hu~m_dO4qPGQ) zx;Xjh*#M@}#3b>9UwC*~^A5#@K~uVGgkG{1)Nc+lep&*s3wvV%u8t@~<1RQF66Pll ztmZl@nCXvqR8sMATfIeqAL;*!Gzd9lu4oyMKd@^poLC28k3=U!W;k|PT z=={Sg00~u>w4OcJpaylW$c?Ty(h6hO^I2q%YyEXd1Q3B7rX7V@6W6pPb77vWvEE4Lrl)^WwTo5F6RW3T;u8e(_fg1VrYqOFu)E=4nhhafJ_V-4fyhyJVm} z*`BRJgX+!nJ@{PBtP7xG{g{kbPnAUB_D@2)q)wI%?LYMq<79Y5^5t)z7~lk^KF;CW zjwXY#ydu0|*a)_7O+_;dy3XL>iyPeVc7AJ8Iw6+}ZV|Pb-5+kQekqlE*?J0bldznA zF)Zo8YhT~!mg=+@7gHEuC%l-tZ}*9K4k@{OGsPP*(7HAIvLq?rJtQukr)9Q(i$ucq zf48$y2{FV^69_x z!pC{huDyyNb}e?!vcuBA*9+ceTq)o+lpW&0GM5};Af~xyMTp!`$7exUZ@BWb6> z<#5iLzuO7Rf&EAhuz)?)gYw}d&WAY&gZHgF*CMtw!t)8B1GVJ+Ng5UG$LYr^O##Q7 z+XrWH_@3kw?-E~q=YIS1MJnP;aO0wfWRz5~qZ3lG5cnZeI$+0MM2ob04ar)okG4B7sV=Au3 zE}jl%#7s&KX1`VcJ^kMh83!u|_kTuYQ#@9h7#b}n>aJVX^i~|}e`nWYsoMb2#I?4J zb0QL`61sSnYyBb)(I&==I1216luYKiraw4psjnkot{sa^*w4uwWi|npi+{$>CXWPm zDuO^`rqjFLp3ePzTN^hUx4eI=A>(scGJ$($o5qE-C^Fa*{Av5oA zkoBo#gBqUICyErVVPltr)E~3wrR3e@%wL)|S`L(xF5Y5PQqkM!8 zm32W>D4V;Br$!@)_V^R};$)B; z##oUxJ~-uqvV?l#zSk#r;2ag*|FI}IJKHxth?2J1#DfmX? z8fI40FIhj*w#<9$foYS!;47LB6Fy5(XnsW{=cR?ojm>k9(U{3X&J&gX8#~V^tTLNK zy$rM&>{42!`ATKa5?o~8b>C$>D7O;)(g;VRHg%tqHb%dl0)9}wq!b^C+%xmY5HfWh z@_SbD%jMD8C({)#MCmT*&b>`P77YZQ4onV!Y5cBc>n>Tv%)TzESdAGlw(#nxD&U^R z89~i!EG<>#Dav9u8~x21VG zFgz_FQbR@86N({vhT+*PD-I!0>_eFF78-SUd-#YP*HXW#WP#6vXdueCA{X{6-&=5BaRA)+Vs!K#A;D30Te4Sc`K+piP_e6 zGdGF-og`bTMmadVt)0vhowICg!A+}K5{*$x7V!tHaHh2;*0d&gw)$ka{>s#iOfnDS zhOy~N?x-O*>t0Ut%12(tB#)w*U+x@Z_KS7Pkh5DP@(g%C;WCKGhEL2E8>t1=U+rZw<%Ed| zg{4Fpri!h!@-d`k3Sv!#orZCy@XYSZ&fy)VpWF}s$JNZj98*On!4Bno9%|&V+D_Ca zyMA?mhArBKKYvm2tRmM}G+2z(ci#M+JG!wP1L|G;%E&tku5Y77ZL089Dt3Wma8BAsq z8;;Oipq>q4(AX~%R^bA+`nHW-umJ8L9iZOW)Liv1ro7-J2@S|*)X=;SM)8yCESg~T z@r-K1R8(EiE}e!p zMKHb05T}VFut;$;#OHM<3!)3+mfDZ+q73GySH=gTo3i%8O3vmc7uJBl2;K?r z0EwfwJq+4ew}ZE)1i}QGaHr!@pPxOC7?4DGgsurYi$HA^6gyWcIkT7i=p#=P{u|2$ z5hOMV>nBus2?Svb+8@7_bHrHH&&D9_s=loGhbCtG8Tm&_j8B%lkL3O@s*1)%iE~=l zWH4$^Oc|9@;|lRCN`-WDX|__Wd8v7At6Ud}4%v!}jvpjazW`B5-ecWId-pIr%7irW zNhf0uN09gM_o8nSo{3$Welq%02B~#pD@XQ+_D45|H%IvQ3UAPFX+AnVWI*a2j?m1G z>;VMayb*)L=vU)!H2+Md zy%SZLRJG*FKe}p5I2`J+DhErT=fbWDyqdn+1VxN$2FglRFN+`NO6N1j-^Z5DF+9sZ zEaJFkm}l5$ScOdT?DXxo4Yw_~O&K}tIqg}}Gh4I%XUDw|TRuxZNB+a@?diqbOmVMN zlT?gUwN#E&*9b^_AYm}S{+;H*omlde~TAAAC-YTksye zp9|U1ki7^Re<6Ch%nP1adrG^ed$H_k(!x%jlJ(odi@k2>z4Y+g-9Mq@%+B-Tm#+kl zzf^9RLbn*zoiAxQwHr3{nvKQ2OYS^*#*l=R&4<3v?eyE7W%rpi_Nc=lN7_248ulG* zqsktsrK!5%^qaW3SLs=n??U+ioRi>@WDHYv&%VY@3y=Y!mc zfV+%=pQFSoBKj?&GsUc5XM@IqID~wM2-X|82LwA1cL$05mbw%#iOzRl936m{x+ifq zmU0I~9xLw{ve|ll^K$ln-h~+XI~vkU_1YRqB;!;@?=&lZGCu8_$e9#2x9L|8)f<7Dw47l!frG#jP~_VFbB|KoNtyDTayq!PN71Z8*=3 zKPW9vrNxCYD2|jm%d00UovsV*#s(|*%JC?Eb@7ij0waw9^bZ#t7UmpuBkMn}+EzY_GdLzp~5X z00d$@Zra4V)wivYx4Xi7dng;52vY+S-o}!1yZY#@SN?O19ZqvbcioJuE9zDKr1bX# z%rB@vg6(X^C3NI#n-?&<6sn%Y;^3a0+72W%6>`>{=T}EZWxQuLV(&oI#0y1@A6r-O z50Ppg2Vmmp9&4}%|B04b#mbw|Z8BnLOJOYD zmJmYg6~(L?8U^Y$2T`Z>(%n-2*>-h!Ekl;hks<94z=mq?+)q9o8&awATno3My$r8c z6JpGIj=?mSYLVU8xB0ymlOGYP{=*U1tch>)CYsoFmEU!Vjpk^N)97NC?meRCh0kz9 zu5&`8`$RLZ&%2DL7|OhEi+6|7ryW>@4aPj*vUnv^sg`7|RHM|14O zeoafSnT70M-O>DOPt>nX>;W=H4m#&7U&7xgfnH69-Y*n3OKDFZ&+W_cgjeGVirYy# zN2fYs_;k|9>EWd3S}!O1#xVLLJsE!@5_95?M8?5ddtpdlppE#x&rX`+;hr{0Wbbh6 zXl>bou>~Kdy}~~-U@Cd)+_?E4%R3YT!Vy_s?t}5&Rn>hDNm-ER+C&Aq9KFq+Xjfo5 z|CF&Lt@_Tuy56qtr;I(n`DpyUKL>4jz0=a7i1Yj`xYb~QN07w)6h5mxuY8Jqid}jl zusNMTKKnD=2rERk@^YdHz?w zI|&WnKK%Z`7)uMro&E&!<~r}S8PV5%9v9`P?~fu(k=W{AM-_{O%5aH*s4DBvYDbeQ zMqg#W)5)`_lF>gYiB0(Q*=H`ZnV*0RT^66b4yWh80$X+ib;%&UI^V?H@A{jK-W(Dj z*z2%1w&Q^hanYDd`MESia~p&#<}Nu~q@)N(Cl42xA2Vz5ML- zS&XUyA19Q`=Z=SmC7xv!Z#k~7%qHAGf~Qq9%=6JnSeaty*2~rd5xgCZP?ruaFZP^d z3hp_0XeW6Gpc*P_4(EZwS5C@p8R@`a| zRd`Fv^;RoS@_<(lud$Ok>)SN8To-f5d>v7|+zbY1=WQR%66--kdMC<8l*+_gC8q!O zVT0M469qGiuSY@a z5#%PY8dI#cIArPuxo!4Jprff!NU-APHy+*kp3Z~XoMMw|NZIzj6c;yD>_k=$H?PIQ zv;&JLbOmyvTM6c!FLj5$2yinKM4faMFX z13?0R?Nz0LbLp|H?@hKi>{tBLs$E%IjfGI`#Ygpec>j;sR3h6(g0&3J-@59&3>`*P zLzzO@Q|bD5BXOJ)PWw(DQVyTE<{04!R)1lSj-z0^}Vjhbp2>77<6t*`!455 zyF{UiGg(^X53VKug!jbq{vw|WFIJ3*P$*4})stWRWAWhb=-)-XFRuCsDOXSW znBhprn_)dLmS5M!uf4}2yx){c zE%3JUT?TWd=R3{kyLq!;z!E8Avh~%lZ?SLh)I*{Nj|}#gmo<^rz`3ML+nK?xlC=1f ze%eRmf9v9%JNC64(!jE(jJNMudAx6rRg*im0%Sf|-%^rUIXw7=`3Dpd#9&J+R&m*W z6#0*)&h2nuIkLAR@b^2>Y;K6(q`VO9u0N>Pv8?oe$2fWZKN%-0H#f_F@c^s4p;Iu_ zRv2}Yy`82js7_|p1hxc@Vbvl?spaDh2aIS}AaZbvs9}y#AtA&eAyF5h5Hgr8R56r6 zC6p7WiDAH4`-s2tRg}2uZoaPHZ#r!B^jx27D^)&ttZppwP3j!Qey5=pTd(T8Zz8kE z2c&N9tZ%Pzem{P;5g?$y!?zn$%i0<5k4{MYhAq4QITX>9`wLr?Pp(n8zQ*NweYHX0a&q{B#V|u?m4l!Ga z&}jE~-O|vI{z-s=>k`0k#EAqn15NGSN`2^fA+cAOjSt+&6doRU1(NJQbf4510)p~L zZ?GZ1MkC}|AL{(+mk^w5v{(ZJO~8(sNyI<0J|`d!bra~F)4I$>gGM_YC~@3?4>R?J zgHj1psKKBRRWXi`-6OV7z3>RIo5Jh%6#2>1%v=d`$S_D28M~rR$N~Xlr0%oenSXZa ze7sN=(D*0Iq1lf5<$S$h(9yg4%fneq`!_Nu%d&B2#}=S=Hh_mHAWi+iQJ;=EC5yptU7Wd1zWZvb;#ZEKK2wG zoso#V=1o`x=`uh7M9Q5x)5oOX?6c++>cXU-OG3+hYm}CDrunaVPF(XFFW^!yqceH< zr%l?|!{bfM-1bw}!*!j+mHb_EY;Cn8_VD?RiSUPbZ`SUGL8(2GmrM=PLJ-iZ{4LhJ zHU?O`rfBVEfI}4HoZmieIbqruF3{7OJh@zTeERfd^OxKlu*S%H-fiAZ*l3<_53xR~ z)8t*$&iZW-L#@6IT!Yuc?yAYF_)4G7bQ8Z97VOd0tdNvO&)7!a;`Xk*>JaK3)dD3G8N7Mf#+Jls^g)(N(GMbx}BErv#^2*Y=080WG3rP{sD9SFSMIUNTc z2LY#qO4RfRg0_cJX1-5^K;<2X(NRzmd`cHtl+PE|H^Su5ODYR}?Fh8_d>wHM%_d$D z7`UKko#coaTA^|kk@5&JJtS0T3(S7<+T@%ek<7e}ueOW(U?m8Tli1xEkwv%;pf||l zC6A;eZ*wtgu&l5YXEvB_xhE;-$o`8V$_USdoHRD)IWW>UT4o_)zQ~N7#4_h=%;p*W zVFH!$07?R?3>pcF3+f443d#W*7a#|o1zwAUgUd|$uOF16fX+~~uPHza6d7s~Q4{0V zrEffd1GEmZ3;ouyFCBCT>Jz7)%+R23F903X0vsHSA&@0dCNMMbEzm5mIdHmf0_?5N zD6kmJ9>x}46}%Ii3ThkGVBL2e ztYu;eu(Y#OKPTxF?^JxR`IVF1(X;}48FTrotIPSwI*j)oG!Ocd+Ulh{h`XHK;Lk_>R}{?(n;9op672D zApWVD==ikarNT)&B7o+z3+-`l#eDbb=SN~wz6A&Er7nB_6GRRadwSCe6hpZB9%UIC zwm3r3T)%3y-$oT`Mwr@0wacc+H2%5$^u6@m*6BOi!;r%|!`31Fm%)0eJ5a;U!-B); z!}i1G!@R>khCO#&9fcj`9CaK89W@+{9K{=mo~F)s&x^Z-{3GDnnbhFUKBgma)3_?! z`E1y9fA!?80ZNr%5Taq!f(&7%`X6r zC5>k#&=VQBfqWX6Ob8+Z2QCqk3W-HDu;|$LJOz>wr3E<>Z0-cI5UobsQEwgvjw162 z9S5@_Sut+P_3%V>Mny%zMIA)V4MYzd4m1sj5+)Ot2e;5#+iouizwH#MqPx5qNQ^?{ z9}9A&zAPL-iz+7440GkU%pRa4WD$5lx;NQg9pE915K0Tu$?D3|$%@Xd%KDf!lx-?q zRxq6HTd*NrDt#g?D5p7dB3+$@8{|xAtUPliZ6WA}RLgCwI}=xMBHf&gAczz4Esz}# z2L%T$6(bcn^{e_fb<~rNixJm@hGyF?h1*vRGT8jnw`TnCJ|YyZ#Av7)*H_ z`Z^;xKOFkO{Uaexoccy1Hb3b4T5zw-N63C)>9mC`qE|EMdyGUS#QgB7^s3ybw5lwu zWUCaY1XijY3siotRO|~6Gz)8GQwU|!anZ@|84GNsyV+QHUm2ns-|wuW8KnO8k@xsv zA*@nWr@sF*oD0K++8+PLRZUn;PEAKmP)$S4NKHJ2=ya-Kx1o4TurDmAnMoq(C^#93 zg~nWA*~iLe3%!>Mr=I?Fr-5Z_HR6%_^r&Ifil_f1`0b<$s|9FT8r@PUU%>`XwJMOFb+p;Ov zW_!pQdOL%=$5Yf@%!Ln}7u*J%6oRH|GXn&H% z7;}J3bRU^GASrPsosq`~Fg27DA3aCn7F$DLWHUtvaEV4Bdrr0GW}{}KW#eMwX(U`s zb2X}pEh^0yqZ@2B(0%!BgNOTjrHS zcYrfrQ>44yL+!yS7;CCOFXTYQS<%_zVH?abWstWP|04CU3>G+$%r6(yjCoOc;5fj` z_egv(dx$vTn7Ylyli-PRXC}h$jz&(7ijGQ^PLPi3)Sod>i~2#V>*&w1l^1&RiEFDa zbP#iz;dC@1^#{+^V5kAT#(*Q+)@bN01NZP9yRJ>&IA$|F!f)(RR^WxCzNP+e{a^ad zc}&&B)$G-@SJ5MRBgORP!`P{8%(7$0BgexnTsHc

DA5c*CxgHUhhcBZ>@bV^8E) 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 $@ + @[ -s $@ ] || rm $@ + +############################################################################### +help: + @echo "usage:" + @echo " make apply: create $(DST) directory by applying the patches to $(SRC)" + @echo " make record: record the patches capturing the differences between $(SRC) and $(DST)" + @echo " make clean: remove all generated files (those ignored by git)" + +clean: + git clean -fdX + +FORCE: ; diff --git a/certora/README.md b/certora/README.md new file mode 100644 index 000000000..cd85ba3d4 --- /dev/null +++ b/certora/README.md @@ -0,0 +1,60 @@ +# Running the certora verification tool + +These instructions detail the process for running Certora Verification Tool on OpenZeppelin Contracts. + +Documentation for CVT and the specification language are available [here](https://certora.atlassian.net/wiki/spaces/CPD/overview). + +## Prerequisites + +Follow the [Certora installation guide](https://docs.certora.com/en/latest/docs/user-guide/getting-started/install.html) in order to get the Certora Prover Package and the `solc` executable folder in your path. + +> **Note** +> An API Key is required for local testing. Although the prover will run on a Github Actions' CI environment on selected Pull Requests. + +## Running the verification + +The Certora Verification Tool proves specs for contracts, which are defined by the `./specs.json` file along with their pre-configured options. + +The verification script `./run.js` is used to submit verification jobs to the Certora Verification service. + +You can run it from the root of the repository with the following command: + +```bash +node certora/run.js [[CONTRACT_NAME:]SPEC_NAME] [OPTIONS...] +``` + +Where: + +- `CONTRACT_NAME` matches the `contract` key in the `./spec.json` file and may be empty. It will run all matching contracts if not provided. +- `SPEC_NAME` refers to a `spec` key from the `./specs.json` file. It will run every spec if not provided. +- `OPTIONS` extend the [Certora Prover CLI options](https://docs.certora.com/en/latest/docs/prover/cli/options.html#certora-prover-cli-options) and will respect the preconfigured options in the `specs.json` file. + +> **Note** +> A single spec may be configured to run for multiple contracts, whereas a single contract may run multiple specs. + +Example usage: + +```bash +node certora/run.js AccessControl # Run the AccessControl spec against every contract implementing it +``` + +## Adapting to changes in the contracts + +Some of our rules require the code to be simplified in various ways. Our primary tool for performing these simplifications is to run verification on a contract that extends the original contracts and overrides some of the methods. These "harness" contracts can be found in the `certora/harness` directory. + +This pattern does require some modifications to the original code: some methods need to be made virtual or public, for example. These changes are handled by applying a patch +to the code before verification by running: + +```bash +make -C certora apply +``` + +Before running the `certora/run.js` script, it's required to apply the corresponding patches to the `contracts` directory, placing the output in the `certora/patched` directory. Then, the contracts are verified by running the verification for the `certora/patched` directory. + +If the original contracts change, it is possible to create a conflict with the patch. In this case, the verify scripts will report an error message and output rejected changes in the `patched` directory. After merging the changes, run `make record` in the `certora` directory; this will regenerate the patch file, which can then be checked into git. + +For more information about the `make` scripts available, run: + +```bash +make -C certora help +``` diff --git a/certora/harnesses/AccessControlDefaultAdminRulesHarness.sol b/certora/harnesses/AccessControlDefaultAdminRulesHarness.sol new file mode 100644 index 000000000..e96883fa2 --- /dev/null +++ b/certora/harnesses/AccessControlDefaultAdminRulesHarness.sol @@ -0,0 +1,46 @@ +// SPDX-License-Identifier: MIT +pragma solidity ^0.8.20; + +import {AccessControlDefaultAdminRules} from "../patched/access/extensions/AccessControlDefaultAdminRules.sol"; + +contract AccessControlDefaultAdminRulesHarness is AccessControlDefaultAdminRules { + uint48 private _delayIncreaseWait; + + constructor( + uint48 initialDelay, + address initialDefaultAdmin, + uint48 delayIncreaseWait + ) AccessControlDefaultAdminRules(initialDelay, initialDefaultAdmin) { + _delayIncreaseWait = delayIncreaseWait; + } + + // FV + function pendingDefaultAdmin_() external view returns (address) { + (address newAdmin, ) = pendingDefaultAdmin(); + return newAdmin; + } + + function pendingDefaultAdminSchedule_() external view returns (uint48) { + (, uint48 schedule) = pendingDefaultAdmin(); + return schedule; + } + + function pendingDelay_() external view returns (uint48) { + (uint48 newDelay, ) = pendingDefaultAdminDelay(); + return newDelay; + } + + function pendingDelaySchedule_() external view returns (uint48) { + (, uint48 schedule) = pendingDefaultAdminDelay(); + return schedule; + } + + function delayChangeWait_(uint48 newDelay) external view returns (uint48) { + return _delayChangeWait(newDelay); + } + + // Overrides + function defaultAdminDelayIncreaseWait() public view override returns (uint48) { + return _delayIncreaseWait; + } +} diff --git a/certora/harnesses/AccessControlHarness.sol b/certora/harnesses/AccessControlHarness.sol new file mode 100644 index 000000000..e862d3eca --- /dev/null +++ b/certora/harnesses/AccessControlHarness.sol @@ -0,0 +1,6 @@ +// SPDX-License-Identifier: MIT +pragma solidity ^0.8.20; + +import {AccessControl} from "../patched/access/AccessControl.sol"; + +contract AccessControlHarness is AccessControl {} diff --git a/certora/harnesses/DoubleEndedQueueHarness.sol b/certora/harnesses/DoubleEndedQueueHarness.sol new file mode 100644 index 000000000..d684c7382 --- /dev/null +++ b/certora/harnesses/DoubleEndedQueueHarness.sol @@ -0,0 +1,58 @@ +// SPDX-License-Identifier: MIT +pragma solidity ^0.8.20; + +import {DoubleEndedQueue} from "../patched/utils/structs/DoubleEndedQueue.sol"; + +contract DoubleEndedQueueHarness { + using DoubleEndedQueue for DoubleEndedQueue.Bytes32Deque; + + DoubleEndedQueue.Bytes32Deque private _deque; + + function pushFront(bytes32 value) external { + _deque.pushFront(value); + } + + function pushBack(bytes32 value) external { + _deque.pushBack(value); + } + + function popFront() external returns (bytes32 value) { + return _deque.popFront(); + } + + function popBack() external returns (bytes32 value) { + return _deque.popBack(); + } + + function clear() external { + _deque.clear(); + } + + function begin() external view returns (uint128) { + return _deque._begin; + } + + function end() external view returns (uint128) { + return _deque._end; + } + + function length() external view returns (uint256) { + return _deque.length(); + } + + function empty() external view returns (bool) { + return _deque.empty(); + } + + function front() external view returns (bytes32 value) { + return _deque.front(); + } + + function back() external view returns (bytes32 value) { + return _deque.back(); + } + + function at_(uint256 index) external view returns (bytes32 value) { + return _deque.at(index); + } +} diff --git a/certora/harnesses/ERC20FlashMintHarness.sol b/certora/harnesses/ERC20FlashMintHarness.sol new file mode 100644 index 000000000..2f989b243 --- /dev/null +++ b/certora/harnesses/ERC20FlashMintHarness.sol @@ -0,0 +1,36 @@ +// SPDX-License-Identifier: MIT + +pragma solidity ^0.8.20; + +import "../patched/token/ERC20/ERC20.sol"; +import "../patched/token/ERC20/extensions/ERC20Permit.sol"; +import "../patched/token/ERC20/extensions/ERC20FlashMint.sol"; + +contract ERC20FlashMintHarness is ERC20, ERC20Permit, ERC20FlashMint { + uint256 someFee; + address someFeeReceiver; + + constructor(string memory name, string memory symbol) ERC20(name, symbol) ERC20Permit(name) {} + + function mint(address account, uint256 amount) external { + _mint(account, amount); + } + + function burn(address account, uint256 amount) external { + _burn(account, amount); + } + + // public accessor + function flashFeeReceiver() public view returns (address) { + return someFeeReceiver; + } + + // internal hook + function _flashFee(address, uint256) internal view override returns (uint256) { + return someFee; + } + + function _flashFeeReceiver() internal view override returns (address) { + return someFeeReceiver; + } +} diff --git a/certora/harnesses/ERC20PermitHarness.sol b/certora/harnesses/ERC20PermitHarness.sol new file mode 100644 index 000000000..08113f4ea --- /dev/null +++ b/certora/harnesses/ERC20PermitHarness.sol @@ -0,0 +1,16 @@ +// SPDX-License-Identifier: MIT +pragma solidity ^0.8.20; + +import {ERC20Permit, ERC20} from "../patched/token/ERC20/extensions/ERC20Permit.sol"; + +contract ERC20PermitHarness is ERC20Permit { + constructor(string memory name, string memory symbol) ERC20(name, symbol) ERC20Permit(name) {} + + function mint(address account, uint256 amount) external { + _mint(account, amount); + } + + function burn(address account, uint256 amount) external { + _burn(account, amount); + } +} diff --git a/certora/harnesses/ERC20WrapperHarness.sol b/certora/harnesses/ERC20WrapperHarness.sol new file mode 100644 index 000000000..ca183ad92 --- /dev/null +++ b/certora/harnesses/ERC20WrapperHarness.sol @@ -0,0 +1,34 @@ +// SPDX-License-Identifier: MIT + +pragma solidity ^0.8.20; + +import {ERC20Permit} from "../patched/token/ERC20/extensions/ERC20Permit.sol"; +import {ERC20Wrapper, IERC20, ERC20} from "../patched/token/ERC20/extensions/ERC20Wrapper.sol"; + +contract ERC20WrapperHarness is ERC20Permit, ERC20Wrapper { + constructor( + IERC20 _underlying, + string memory _name, + string memory _symbol + ) ERC20(_name, _symbol) ERC20Permit(_name) ERC20Wrapper(_underlying) {} + + function underlyingTotalSupply() public view returns (uint256) { + return underlying().totalSupply(); + } + + function underlyingBalanceOf(address account) public view returns (uint256) { + return underlying().balanceOf(account); + } + + function underlyingAllowanceToThis(address account) public view returns (uint256) { + return underlying().allowance(account, address(this)); + } + + function recover(address account) public returns (uint256) { + return _recover(account); + } + + function decimals() public view override(ERC20Wrapper, ERC20) returns (uint8) { + return super.decimals(); + } +} diff --git a/certora/harnesses/ERC3156FlashBorrowerHarness.sol b/certora/harnesses/ERC3156FlashBorrowerHarness.sol new file mode 100644 index 000000000..1c76da2d4 --- /dev/null +++ b/certora/harnesses/ERC3156FlashBorrowerHarness.sol @@ -0,0 +1,13 @@ +// SPDX-License-Identifier: MIT + +import {IERC3156FlashBorrower} from "../patched/interfaces/IERC3156FlashBorrower.sol"; + +pragma solidity ^0.8.20; + +contract ERC3156FlashBorrowerHarness is IERC3156FlashBorrower { + bytes32 somethingToReturn; + + function onFlashLoan(address, address, uint256, uint256, bytes calldata) external view override returns (bytes32) { + return somethingToReturn; + } +} diff --git a/certora/harnesses/ERC721Harness.sol b/certora/harnesses/ERC721Harness.sol new file mode 100644 index 000000000..69c4c205a --- /dev/null +++ b/certora/harnesses/ERC721Harness.sol @@ -0,0 +1,33 @@ +// SPDX-License-Identifier: MIT + +pragma solidity ^0.8.20; + +import {ERC721} from "../patched/token/ERC721/ERC721.sol"; + +contract ERC721Harness is ERC721 { + constructor(string memory name, string memory symbol) ERC721(name, symbol) {} + + function mint(address account, uint256 tokenId) external { + _mint(account, tokenId); + } + + function safeMint(address to, uint256 tokenId) external { + _safeMint(to, tokenId); + } + + function safeMint(address to, uint256 tokenId, bytes memory data) external { + _safeMint(to, tokenId, data); + } + + function burn(uint256 tokenId) external { + _burn(tokenId); + } + + function unsafeOwnerOf(uint256 tokenId) external view returns (address) { + return _ownerOf(tokenId); + } + + function unsafeGetApproved(uint256 tokenId) external view returns (address) { + return _getApproved(tokenId); + } +} diff --git a/certora/harnesses/ERC721ReceiverHarness.sol b/certora/harnesses/ERC721ReceiverHarness.sol new file mode 100644 index 000000000..3843ef4a2 --- /dev/null +++ b/certora/harnesses/ERC721ReceiverHarness.sol @@ -0,0 +1,11 @@ +// SPDX-License-Identifier: MIT + +pragma solidity ^0.8.20; + +import "../patched/interfaces/IERC721Receiver.sol"; + +contract ERC721ReceiverHarness is IERC721Receiver { + function onERC721Received(address, address, uint256, bytes calldata) external pure returns (bytes4) { + return this.onERC721Received.selector; + } +} diff --git a/certora/harnesses/EnumerableMapHarness.sol b/certora/harnesses/EnumerableMapHarness.sol new file mode 100644 index 000000000..5c2f3229b --- /dev/null +++ b/certora/harnesses/EnumerableMapHarness.sol @@ -0,0 +1,55 @@ +// SPDX-License-Identifier: MIT + +pragma solidity ^0.8.20; + +import {EnumerableMap} from "../patched/utils/structs/EnumerableMap.sol"; + +contract EnumerableMapHarness { + using EnumerableMap for EnumerableMap.Bytes32ToBytes32Map; + + EnumerableMap.Bytes32ToBytes32Map private _map; + + function set(bytes32 key, bytes32 value) public returns (bool) { + return _map.set(key, value); + } + + function remove(bytes32 key) public returns (bool) { + return _map.remove(key); + } + + function contains(bytes32 key) public view returns (bool) { + return _map.contains(key); + } + + function length() public view returns (uint256) { + return _map.length(); + } + + function key_at(uint256 index) public view returns (bytes32) { + (bytes32 key,) = _map.at(index); + return key; + } + + function value_at(uint256 index) public view returns (bytes32) { + (,bytes32 value) = _map.at(index); + return value; + } + + function tryGet_contains(bytes32 key) public view returns (bool) { + (bool contained,) = _map.tryGet(key); + return contained; + } + + function tryGet_value(bytes32 key) public view returns (bytes32) { + (,bytes32 value) = _map.tryGet(key); + return value; + } + + function get(bytes32 key) public view returns (bytes32) { + return _map.get(key); + } + + function _indexOf(bytes32 key) public view returns (uint256) { + return _map._keys._inner._indexes[key]; + } +} diff --git a/certora/harnesses/EnumerableSetHarness.sol b/certora/harnesses/EnumerableSetHarness.sol new file mode 100644 index 000000000..3d18b183b --- /dev/null +++ b/certora/harnesses/EnumerableSetHarness.sol @@ -0,0 +1,35 @@ +// SPDX-License-Identifier: MIT + +pragma solidity ^0.8.20; + +import {EnumerableSet} from "../patched/utils/structs/EnumerableSet.sol"; + +contract EnumerableSetHarness { + using EnumerableSet for EnumerableSet.Bytes32Set; + + EnumerableSet.Bytes32Set private _set; + + function add(bytes32 value) public returns (bool) { + return _set.add(value); + } + + function remove(bytes32 value) public returns (bool) { + return _set.remove(value); + } + + function contains(bytes32 value) public view returns (bool) { + return _set.contains(value); + } + + function length() public view returns (uint256) { + return _set.length(); + } + + function at_(uint256 index) public view returns (bytes32) { + return _set.at(index); + } + + function _indexOf(bytes32 value) public view returns (uint256) { + return _set._inner._indexes[value]; + } +} diff --git a/certora/harnesses/InitializableHarness.sol b/certora/harnesses/InitializableHarness.sol new file mode 100644 index 000000000..743d677dd --- /dev/null +++ b/certora/harnesses/InitializableHarness.sol @@ -0,0 +1,23 @@ +// SPDX-License-Identifier: MIT +pragma solidity ^0.8.20; + +import {Initializable} from "../patched/proxy/utils/Initializable.sol"; + +contract InitializableHarness is Initializable { + function initialize() public initializer {} + function reinitialize(uint64 n) public reinitializer(n) {} + function disable() public { _disableInitializers(); } + + function nested_init_init() public initializer { initialize(); } + function nested_init_reinit(uint64 m) public initializer { reinitialize(m); } + function nested_reinit_init(uint64 n) public reinitializer(n) { initialize(); } + function nested_reinit_reinit(uint64 n, uint64 m) public reinitializer(n) { reinitialize(m); } + + function version() public view returns (uint64) { + return _getInitializedVersion(); + } + + function initializing() public view returns (bool) { + return _isInitializing(); + } +} diff --git a/certora/harnesses/Ownable2StepHarness.sol b/certora/harnesses/Ownable2StepHarness.sol new file mode 100644 index 000000000..09a5faa23 --- /dev/null +++ b/certora/harnesses/Ownable2StepHarness.sol @@ -0,0 +1,10 @@ +// SPDX-License-Identifier: MIT +pragma solidity ^0.8.20; + +import {Ownable2Step, Ownable} from "../patched/access/Ownable2Step.sol"; + +contract Ownable2StepHarness is Ownable2Step { + constructor(address initialOwner) Ownable(initialOwner) {} + + function restricted() external onlyOwner {} +} diff --git a/certora/harnesses/OwnableHarness.sol b/certora/harnesses/OwnableHarness.sol new file mode 100644 index 000000000..79b4b1b6c --- /dev/null +++ b/certora/harnesses/OwnableHarness.sol @@ -0,0 +1,10 @@ +// SPDX-License-Identifier: MIT +pragma solidity ^0.8.20; + +import {Ownable} from "../patched/access/Ownable.sol"; + +contract OwnableHarness is Ownable { + constructor(address initialOwner) Ownable(initialOwner) {} + + function restricted() external onlyOwner {} +} diff --git a/certora/harnesses/PausableHarness.sol b/certora/harnesses/PausableHarness.sol new file mode 100644 index 000000000..5977b9202 --- /dev/null +++ b/certora/harnesses/PausableHarness.sol @@ -0,0 +1,18 @@ +// SPDX-License-Identifier: MIT +pragma solidity ^0.8.20; + +import {Pausable} from "../patched/utils/Pausable.sol"; + +contract PausableHarness is Pausable { + function pause() external { + _pause(); + } + + function unpause() external { + _unpause(); + } + + function onlyWhenPaused() external whenPaused {} + + function onlyWhenNotPaused() external whenNotPaused {} +} diff --git a/certora/harnesses/TimelockControllerHarness.sol b/certora/harnesses/TimelockControllerHarness.sol new file mode 100644 index 000000000..95ae40621 --- /dev/null +++ b/certora/harnesses/TimelockControllerHarness.sol @@ -0,0 +1,13 @@ +// SPDX-License-Identifier: MIT +pragma solidity ^0.8.20; + +import {TimelockController} from "../patched/governance/TimelockController.sol"; + +contract TimelockControllerHarness is TimelockController { + constructor( + uint256 minDelay, + address[] memory proposers, + address[] memory executors, + address admin + ) TimelockController(minDelay, proposers, executors, admin) {} +} diff --git a/certora/reports/2021-10.pdf b/certora/reports/2021-10.pdf new file mode 100644 index 0000000000000000000000000000000000000000..22df9c61e6a9f74b29f90b6e36bd3d04f99756f5 GIT binary patch literal 92882 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 aXJ@ZxYwu)>@+&A9#pUoWT@sTO$NL{da>MEX literal 0 HcmV?d00001 diff --git a/certora/reports/2022-03.pdf b/certora/reports/2022-03.pdf new file mode 100644 index 0000000000000000000000000000000000000000..b6ff81d1812c808e2f683c1e5fe10abf71ba5438 GIT binary patch literal 199401 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

E02esqZ$^2gTs{2 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 literal 0 HcmV?d00001 diff --git a/certora/reports/2022-05.pdf b/certora/reports/2022-05.pdf new file mode 100644 index 0000000000000000000000000000000000000000..f24a44910c4fba449300987456b5f440e7f99511 GIT binary patch literal 132223 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%0D7|ieYKPVYBX59b!U}f9eB5UvK%HwkWL{dR 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 UVZ$VVhf9Eu51oMlq$-2{KaJIBBLDyZ literal 0 HcmV?d00001 diff --git a/certora/run.js b/certora/run.js new file mode 100755 index 000000000..7b65534ea --- /dev/null +++ b/certora/run.js @@ -0,0 +1,160 @@ +#!/usr/bin/env node + +// USAGE: +// node certora/run.js [[CONTRACT_NAME:]SPEC_NAME]* [--all] [--options OPTIONS...] [--specs PATH] +// EXAMPLES: +// node certora/run.js --all +// node certora/run.js AccessControl +// node certora/run.js AccessControlHarness:AccessControl + +const proc = require('child_process'); +const { PassThrough } = require('stream'); +const events = require('events'); + +const argv = require('yargs') + .env('') + .options({ + all: { + alias: 'a', + type: 'boolean', + }, + spec: { + alias: 's', + type: 'string', + default: __dirname + '/specs.json', + }, + parallel: { + alias: 'p', + type: 'number', + default: 4, + }, + verbose: { + alias: 'v', + type: 'count', + default: 0, + }, + options: { + alias: 'o', + type: 'array', + default: [], + }, + }).argv; + +function match(entry, request) { + const [reqSpec, reqContract] = request.split(':').reverse(); + return entry.spec == reqSpec && (!reqContract || entry.contract == reqContract); +} + +const specs = require(argv.spec).filter(s => argv.all || argv._.some(r => match(s, r))); +const limit = require('p-limit')(argv.parallel); + +if (argv._.length == 0 && !argv.all) { + console.error(`Warning: No specs requested. Did you forgot to toggle '--all'?`); +} + +for (const r of argv._) { + if (!specs.some(s => match(s, r))) { + console.error(`Error: Requested spec '${r}' not found in ${argv.spec}`); + process.exitCode = 1; + } +} + +if (process.exitCode) { + process.exit(process.exitCode); +} + +for (const { spec, contract, files, options = [] } of specs) { + limit( + runCertora, + spec, + contract, + files, + [...options, ...argv.options].flatMap(opt => opt.split(' ')), + ); +} + +// Run certora, aggregate the output and print it at the end +async function runCertora(spec, contract, files, options = []) { + const args = [...files, '--verify', `${contract}:certora/specs/${spec}.spec`, ...options]; + if (argv.verbose) { + console.log('Running:', args.join(' ')); + } + const child = proc.spawn('certoraRun', args); + + const stream = new PassThrough(); + const output = collect(stream); + + child.stdout.pipe(stream, { end: false }); + child.stderr.pipe(stream, { end: false }); + + // as soon as we have a job id, print the output link + stream.on('data', function logStatusUrl(data) { + const { '-DjobId': jobId, '-DuserId': userId } = Object.fromEntries( + data + .toString('utf8') + .match(/-D\S+=\S+/g) + ?.map(s => s.split('=')) || [], + ); + + if (jobId && userId) { + console.error(`[${spec}] https://prover.certora.com/output/${userId}/${jobId}/`); + stream.off('data', logStatusUrl); + } + }); + + // wait for process end + const [code, signal] = await events.once(child, 'exit'); + + // error + if (code || signal) { + console.error(`[${spec}] Exited with code ${code || signal}`); + process.exitCode = 1; + } + + // get all output + stream.end(); + + // write results in markdown format + writeEntry(spec, contract, code || signal, (await output).match(/https:\/\/prover.certora.com\/output\/\S*/)?.[0]); + + // write all details + console.error(`+ certoraRun ${args.join(' ')}\n` + (await output)); +} + +// Collects stream data into a string +async function collect(stream) { + const buffers = []; + for await (const data of stream) { + const buf = Buffer.isBuffer(data) ? data : Buffer.from(data); + buffers.push(buf); + } + return Buffer.concat(buffers).toString('utf8'); +} + +// Formatting +let hasHeader = false; + +function formatRow(...array) { + return ['', ...array, ''].join(' | '); +} + +function writeHeader() { + console.log(formatRow('spec', 'contract', 'result', 'status', 'output')); + console.log(formatRow('-', '-', '-', '-', '-')); +} + +function writeEntry(spec, contract, success, url) { + if (!hasHeader) { + hasHeader = true; + writeHeader(); + } + console.log( + formatRow( + spec, + contract, + success ? ':x:' : ':heavy_check_mark:', + url ? `[link](${url?.replace('/output/', '/jobStatus/')})` : 'error', + url ? `[link](${url})` : 'error', + ), + ); +} diff --git a/certora/specs.json b/certora/specs.json new file mode 100644 index 000000000..3e5acb568 --- /dev/null +++ b/certora/specs.json @@ -0,0 +1,86 @@ +[ + { + "spec": "Pausable", + "contract": "PausableHarness", + "files": ["certora/harnesses/PausableHarness.sol"] + }, + { + "spec": "AccessControl", + "contract": "AccessControlHarness", + "files": ["certora/harnesses/AccessControlHarness.sol"] + }, + { + "spec": "AccessControlDefaultAdminRules", + "contract": "AccessControlDefaultAdminRulesHarness", + "files": ["certora/harnesses/AccessControlDefaultAdminRulesHarness.sol"] + }, + { + "spec": "DoubleEndedQueue", + "contract": "DoubleEndedQueueHarness", + "files": ["certora/harnesses/DoubleEndedQueueHarness.sol"] + }, + { + "spec": "Ownable", + "contract": "OwnableHarness", + "files": ["certora/harnesses/OwnableHarness.sol"] + }, + { + "spec": "Ownable2Step", + "contract": "Ownable2StepHarness", + "files": ["certora/harnesses/Ownable2StepHarness.sol"] + }, + { + "spec": "ERC20", + "contract": "ERC20PermitHarness", + "files": ["certora/harnesses/ERC20PermitHarness.sol"], + "options": ["--optimistic_loop"] + }, + { + "spec": "ERC20FlashMint", + "contract": "ERC20FlashMintHarness", + "files": [ + "certora/harnesses/ERC20FlashMintHarness.sol", + "certora/harnesses/ERC3156FlashBorrowerHarness.sol" + ], + "options": ["--optimistic_loop"] + }, + { + "spec": "ERC20Wrapper", + "contract": "ERC20WrapperHarness", + "files": [ + "certora/harnesses/ERC20PermitHarness.sol", + "certora/harnesses/ERC20WrapperHarness.sol" + ], + "options": [ + "--link ERC20WrapperHarness:_underlying=ERC20PermitHarness", + "--optimistic_loop" + ] + }, + { + "spec": "ERC721", + "contract": "ERC721Harness", + "files": ["certora/harnesses/ERC721Harness.sol", "certora/harnesses/ERC721ReceiverHarness.sol"], + "options": ["--optimistic_loop"] + }, + { + "spec": "Initializable", + "contract": "InitializableHarness", + "files": ["certora/harnesses/InitializableHarness.sol"] + }, + { + "spec": "EnumerableSet", + "contract": "EnumerableSetHarness", + "files": ["certora/harnesses/EnumerableSetHarness.sol"] + }, + { + "spec": "EnumerableMap", + "contract": "EnumerableMapHarness", + "files": ["certora/harnesses/EnumerableMapHarness.sol"] + }, + { + "spec": "TimelockController", + "contract": "TimelockControllerHarness", + "files": ["certora/harnesses/TimelockControllerHarness.sol"], + "options": ["--optimistic_hashing", "--optimistic_loop"] + } +] diff --git a/certora/specs/AccessControl.spec b/certora/specs/AccessControl.spec new file mode 100644 index 000000000..70b067218 --- /dev/null +++ b/certora/specs/AccessControl.spec @@ -0,0 +1,119 @@ +import "helpers/helpers.spec"; +import "methods/IAccessControl.spec"; + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Identify entrypoints: only grantRole, revokeRole and renounceRole can alter permissions │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +rule onlyGrantCanGrant(env e, method f, bytes32 role, address account) { + calldataarg args; + + bool hasRoleBefore = hasRole(role, account); + f(e, args); + bool hasRoleAfter = hasRole(role, account); + + assert ( + !hasRoleBefore && + hasRoleAfter + ) => ( + f.selector == sig:grantRole(bytes32, address).selector + ); + + assert ( + hasRoleBefore && + !hasRoleAfter + ) => ( + f.selector == sig:revokeRole(bytes32, address).selector || + f.selector == sig:renounceRole(bytes32, address).selector + ); +} + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Function correctness: grantRole only affects the specified user/role combo │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +rule grantRoleEffect(env e, bytes32 role) { + require nonpayable(e); + + bytes32 otherRole; + address account; + address otherAccount; + + bool isCallerAdmin = hasRole(getRoleAdmin(role), e.msg.sender); + bool hasOtherRoleBefore = hasRole(otherRole, otherAccount); + + grantRole@withrevert(e, role, account); + bool success = !lastReverted; + + bool hasOtherRoleAfter = hasRole(otherRole, otherAccount); + + // liveness + assert success <=> isCallerAdmin; + + // effect + assert success => hasRole(role, account); + + // no side effect + assert hasOtherRoleBefore != hasOtherRoleAfter => (role == otherRole && account == otherAccount); +} + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Function correctness: revokeRole only affects the specified user/role combo │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +rule revokeRoleEffect(env e, bytes32 role) { + require nonpayable(e); + + bytes32 otherRole; + address account; + address otherAccount; + + bool isCallerAdmin = hasRole(getRoleAdmin(role), e.msg.sender); + bool hasOtherRoleBefore = hasRole(otherRole, otherAccount); + + revokeRole@withrevert(e, role, account); + bool success = !lastReverted; + + bool hasOtherRoleAfter = hasRole(otherRole, otherAccount); + + // liveness + assert success <=> isCallerAdmin; + + // effect + assert success => !hasRole(role, account); + + // no side effect + assert hasOtherRoleBefore != hasOtherRoleAfter => (role == otherRole && account == otherAccount); +} + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Function correctness: renounceRole only affects the specified user/role combo │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +rule renounceRoleEffect(env e, bytes32 role) { + require nonpayable(e); + + bytes32 otherRole; + address account; + address otherAccount; + + bool hasOtherRoleBefore = hasRole(otherRole, otherAccount); + + renounceRole@withrevert(e, role, account); + bool success = !lastReverted; + + bool hasOtherRoleAfter = hasRole(otherRole, otherAccount); + + // liveness + assert success <=> account == e.msg.sender; + + // effect + assert success => !hasRole(role, account); + + // no side effect + assert hasOtherRoleBefore != hasOtherRoleAfter => (role == otherRole && account == otherAccount); +} diff --git a/certora/specs/AccessControlDefaultAdminRules.spec b/certora/specs/AccessControlDefaultAdminRules.spec new file mode 100644 index 000000000..2f5bb9d45 --- /dev/null +++ b/certora/specs/AccessControlDefaultAdminRules.spec @@ -0,0 +1,464 @@ +import "helpers/helpers.spec"; +import "methods/IAccessControlDefaultAdminRules.spec"; +import "methods/IAccessControl.spec"; +import "AccessControl.spec"; + +use rule onlyGrantCanGrant filtered { + f -> f.selector != sig:acceptDefaultAdminTransfer().selector +} + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Definitions │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +definition timeSanity(env e) returns bool = + e.block.timestamp > 0 && e.block.timestamp + defaultAdminDelay(e) < max_uint48; + +definition delayChangeWaitSanity(env e, uint48 newDelay) returns bool = + e.block.timestamp + delayChangeWait_(e, newDelay) < max_uint48; + +definition isSet(uint48 schedule) returns bool = + schedule != 0; + +definition hasPassed(env e, uint48 schedule) returns bool = + assert_uint256(schedule) < e.block.timestamp; + +definition increasingDelaySchedule(env e, uint48 newDelay) returns mathint = + e.block.timestamp + min(newDelay, defaultAdminDelayIncreaseWait()); + +definition decreasingDelaySchedule(env e, uint48 newDelay) returns mathint = + e.block.timestamp + defaultAdminDelay(e) - newDelay; + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Invariant: defaultAdmin holds the DEFAULT_ADMIN_ROLE │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +invariant defaultAdminConsistency(address account) + (account == defaultAdmin() && account != 0) <=> hasRole(DEFAULT_ADMIN_ROLE(), account) + { + preserved with (env e) { + require nonzerosender(e); + } + } + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Invariant: Only one account holds the DEFAULT_ADMIN_ROLE │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +invariant singleDefaultAdmin(address account, address another) + hasRole(DEFAULT_ADMIN_ROLE(), account) && hasRole(DEFAULT_ADMIN_ROLE(), another) => another == account + { + preserved { + requireInvariant defaultAdminConsistency(account); + requireInvariant defaultAdminConsistency(another); + } + } + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Invariant: DEFAULT_ADMIN_ROLE's admin is always DEFAULT_ADMIN_ROLE │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +invariant defaultAdminRoleAdminConsistency() + getRoleAdmin(DEFAULT_ADMIN_ROLE()) == DEFAULT_ADMIN_ROLE(); + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Invariant: owner is the defaultAdmin │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +invariant ownerConsistency() + defaultAdmin() == owner(); + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Function correctness: revokeRole only affects the specified user/role combo │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +rule revokeRoleEffect(env e, bytes32 role) { + require nonpayable(e); + + bytes32 otherRole; + address account; + address otherAccount; + + bool isCallerAdmin = hasRole(getRoleAdmin(role), e.msg.sender); + bool hasOtherRoleBefore = hasRole(otherRole, otherAccount); + + revokeRole@withrevert(e, role, account); + bool success = !lastReverted; + + bool hasOtherRoleAfter = hasRole(otherRole, otherAccount); + + // liveness + assert success <=> isCallerAdmin && role != DEFAULT_ADMIN_ROLE(), + "roles can only be revoked by their owner except for the default admin role"; + + // effect + assert success => !hasRole(role, account), + "role is revoked"; + + // no side effect + assert hasOtherRoleBefore != hasOtherRoleAfter => (role == otherRole && account == otherAccount), + "no other role is affected"; +} + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Function correctness: renounceRole only affects the specified user/role combo │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +rule renounceRoleEffect(env e, bytes32 role) { + require nonpayable(e); + + bytes32 otherRole; + address account; + address otherAccount; + + bool hasOtherRoleBefore = hasRole(otherRole, otherAccount); + address adminBefore = defaultAdmin(); + address pendingAdminBefore = pendingDefaultAdmin_(); + uint48 scheduleBefore = pendingDefaultAdminSchedule_(); + + renounceRole@withrevert(e, role, account); + bool success = !lastReverted; + + bool hasOtherRoleAfter = hasRole(otherRole, otherAccount); + address adminAfter = defaultAdmin(); + address pendingAdminAfter = pendingDefaultAdmin_(); + uint48 scheduleAfter = pendingDefaultAdminSchedule_(); + + // liveness + assert success <=> ( + account == e.msg.sender && + ( + role != DEFAULT_ADMIN_ROLE() || + account != adminBefore || + ( + pendingAdminBefore == 0 && + isSet(scheduleBefore) && + hasPassed(e, scheduleBefore) + ) + ) + ), + "an account only can renounce by itself with a delay for the default admin role"; + + // effect + assert success => !hasRole(role, account), + "role is renounced"; + + assert success => ( + ( + role == DEFAULT_ADMIN_ROLE() && + account == adminBefore + ) ? ( + adminAfter == 0 && + pendingAdminAfter == 0 && + scheduleAfter == 0 + ) : ( + adminAfter == adminBefore && + pendingAdminAfter == pendingAdminBefore && + scheduleAfter == scheduleBefore + ) + ), + "renouncing default admin role cleans state iff called by previous admin"; + + // no side effect + assert hasOtherRoleBefore != hasOtherRoleAfter => ( + role == otherRole && + account == otherAccount + ), + "no other role is affected"; +} + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Rule: defaultAdmin is only affected by accepting an admin transfer or renoucing │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +rule noDefaultAdminChange(env e, method f, calldataarg args) { + address adminBefore = defaultAdmin(); + f(e, args); + address adminAfter = defaultAdmin(); + + assert adminBefore != adminAfter => ( + f.selector == sig:acceptDefaultAdminTransfer().selector || + f.selector == sig:renounceRole(bytes32,address).selector + ), + "default admin is only affected by accepting an admin transfer or renoucing"; +} + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Rule: pendingDefaultAdmin is only affected by beginning, completing (accept or renounce), or canceling an admin │ +│ transfer │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +rule noPendingDefaultAdminChange(env e, method f, calldataarg args) { + address pendingAdminBefore = pendingDefaultAdmin_(); + uint48 scheduleBefore = pendingDefaultAdminSchedule_(); + f(e, args); + address pendingAdminAfter = pendingDefaultAdmin_(); + uint48 scheduleAfter = pendingDefaultAdminSchedule_(); + + assert ( + pendingAdminBefore != pendingAdminAfter || + scheduleBefore != scheduleAfter + ) => ( + f.selector == sig:beginDefaultAdminTransfer(address).selector || + f.selector == sig:acceptDefaultAdminTransfer().selector || + f.selector == sig:cancelDefaultAdminTransfer().selector || + f.selector == sig:renounceRole(bytes32,address).selector + ), + "pending admin and its schedule is only affected by beginning, completing, or cancelling an admin transfer"; +} + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Rule: defaultAdminDelay can't be changed atomically by any function │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +rule noDefaultAdminDelayChange(env e, method f, calldataarg args) { + uint48 delayBefore = defaultAdminDelay(e); + f(e, args); + uint48 delayAfter = defaultAdminDelay(e); + + assert delayBefore == delayAfter, + "delay can't be changed atomically by any function"; +} + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Rule: pendingDefaultAdminDelay is only affected by changeDefaultAdminDelay or rollbackDefaultAdminDelay │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +rule noPendingDefaultAdminDelayChange(env e, method f, calldataarg args) { + uint48 pendingDelayBefore = pendingDelay_(e); + f(e, args); + uint48 pendingDelayAfter = pendingDelay_(e); + + assert pendingDelayBefore != pendingDelayAfter => ( + f.selector == sig:changeDefaultAdminDelay(uint48).selector || + f.selector == sig:rollbackDefaultAdminDelay().selector + ), + "pending delay is only affected by changeDefaultAdminDelay or rollbackDefaultAdminDelay"; +} + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Rule: defaultAdminDelayIncreaseWait can't be changed atomically by any function │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +rule noDefaultAdminDelayIncreaseWaitChange(env e, method f, calldataarg args) { + uint48 delayIncreaseWaitBefore = defaultAdminDelayIncreaseWait(); + f(e, args); + uint48 delayIncreaseWaitAfter = defaultAdminDelayIncreaseWait(); + + assert delayIncreaseWaitBefore == delayIncreaseWaitAfter, + "delay increase wait can't be changed atomically by any function"; +} + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Function correctness: beginDefaultAdminTransfer sets a pending default admin and its schedule │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +rule beginDefaultAdminTransfer(env e, address newAdmin) { + require timeSanity(e); + require nonpayable(e); + require nonzerosender(e); + requireInvariant defaultAdminConsistency(e.msg.sender); + + beginDefaultAdminTransfer@withrevert(e, newAdmin); + bool success = !lastReverted; + + // liveness + assert success <=> e.msg.sender == defaultAdmin(), + "only the current default admin can begin a transfer"; + + // effect + assert success => pendingDefaultAdmin_() == newAdmin, + "pending default admin is set"; + assert success => to_mathint(pendingDefaultAdminSchedule_()) == e.block.timestamp + defaultAdminDelay(e), + "pending default admin delay is set"; +} + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Rule: A default admin can't change in less than the applied schedule │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +rule pendingDefaultAdminDelayEnforced(env e1, env e2, method f, calldataarg args, address newAdmin) { + require e1.block.timestamp <= e2.block.timestamp; + + uint48 delayBefore = defaultAdminDelay(e1); + address adminBefore = defaultAdmin(); + + // There might be a better way to generalize this without requiring `beginDefaultAdminTransfer`, but currently + // it's the only way in which we can attest that only `delayBefore` has passed before a change. + beginDefaultAdminTransfer(e1, newAdmin); + f(e2, args); + + address adminAfter = defaultAdmin(); + + // change can only happen towards the newAdmin, with the delay + assert adminAfter != adminBefore => ( + adminAfter == newAdmin && + to_mathint(e2.block.timestamp) >= e1.block.timestamp + delayBefore + ), + "The admin can only change after the enforced delay and to the previously scheduled new admin"; +} + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Function correctness: acceptDefaultAdminTransfer updates defaultAdmin resetting the pending admin and its schedule │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +rule acceptDefaultAdminTransfer(env e) { + require nonpayable(e); + + address pendingAdminBefore = pendingDefaultAdmin_(); + uint48 scheduleBefore = pendingDefaultAdminSchedule_(); + + acceptDefaultAdminTransfer@withrevert(e); + bool success = !lastReverted; + + // liveness + assert success <=> ( + e.msg.sender == pendingAdminBefore && + isSet(scheduleBefore) && + hasPassed(e, scheduleBefore) + ), + "only the pending default admin can accept the role after the schedule has been set and passed"; + + // effect + assert success => defaultAdmin() == pendingAdminBefore, + "Default admin is set to the previous pending default admin"; + assert success => pendingDefaultAdmin_() == 0, + "Pending default admin is reset"; + assert success => pendingDefaultAdminSchedule_() == 0, + "Pending default admin delay is reset"; +} + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Function correctness: cancelDefaultAdminTransfer resets pending default admin and its schedule │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +rule cancelDefaultAdminTransfer(env e) { + require nonpayable(e); + require nonzerosender(e); + requireInvariant defaultAdminConsistency(e.msg.sender); + + cancelDefaultAdminTransfer@withrevert(e); + bool success = !lastReverted; + + // liveness + assert success <=> e.msg.sender == defaultAdmin(), + "only the current default admin can cancel a transfer"; + + // effect + assert success => pendingDefaultAdmin_() == 0, + "Pending default admin is reset"; + assert success => pendingDefaultAdminSchedule_() == 0, + "Pending default admin delay is reset"; +} + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Function correctness: changeDefaultAdminDelay sets a pending default admin delay and its schedule │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +rule changeDefaultAdminDelay(env e, uint48 newDelay) { + require timeSanity(e); + require nonpayable(e); + require nonzerosender(e); + require delayChangeWaitSanity(e, newDelay); + requireInvariant defaultAdminConsistency(e.msg.sender); + + uint48 delayBefore = defaultAdminDelay(e); + + changeDefaultAdminDelay@withrevert(e, newDelay); + bool success = !lastReverted; + + // liveness + assert success <=> e.msg.sender == defaultAdmin(), + "only the current default admin can begin a delay change"; + + // effect + assert success => pendingDelay_(e) == newDelay, + "pending delay is set"; + + assert success => ( + assert_uint256(pendingDelaySchedule_(e)) > e.block.timestamp || + delayBefore == newDelay || // Interpreted as decreasing, x - x = 0 + defaultAdminDelayIncreaseWait() == 0 + ), + "pending delay schedule is set in the future unless accepted edge cases"; +} + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Rule: A delay can't change in less than the applied schedule │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +rule pendingDelayWaitEnforced(env e1, env e2, method f, calldataarg args, uint48 newDelay) { + require e1.block.timestamp <= e2.block.timestamp; + + uint48 delayBefore = defaultAdminDelay(e1); + + changeDefaultAdminDelay(e1, newDelay); + f(e2, args); + + uint48 delayAfter = defaultAdminDelay(e2); + + mathint delayWait = newDelay > delayBefore ? increasingDelaySchedule(e1, newDelay) : decreasingDelaySchedule(e1, newDelay); + + assert delayAfter != delayBefore => ( + delayAfter == newDelay && + to_mathint(e2.block.timestamp) >= delayWait + ), + "A delay can only change after the applied schedule"; +} + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Rule: pending delay wait is set depending on increasing or decreasing the delay │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +rule pendingDelayWait(env e, uint48 newDelay) { + uint48 oldDelay = defaultAdminDelay(e); + changeDefaultAdminDelay(e, newDelay); + + assert newDelay > oldDelay => to_mathint(pendingDelaySchedule_(e)) == increasingDelaySchedule(e, newDelay), + "Delay wait is the minimum between the new delay and a threshold when the delay is increased"; + assert newDelay <= oldDelay => to_mathint(pendingDelaySchedule_(e)) == decreasingDelaySchedule(e, newDelay), + "Delay wait is the difference between the current and the new delay when the delay is decreased"; +} + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Function correctness: rollbackDefaultAdminDelay resets the delay and its schedule │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +rule rollbackDefaultAdminDelay(env e) { + require nonpayable(e); + require nonzerosender(e); + requireInvariant defaultAdminConsistency(e.msg.sender); + + rollbackDefaultAdminDelay@withrevert(e); + bool success = !lastReverted; + + // liveness + assert success <=> e.msg.sender == defaultAdmin(), + "only the current default admin can rollback a delay change"; + + // effect + assert success => pendingDelay_(e) == 0, + "Pending default admin is reset"; + assert success => pendingDelaySchedule_(e) == 0, + "Pending default admin delay is reset"; +} diff --git a/certora/specs/DoubleEndedQueue.spec b/certora/specs/DoubleEndedQueue.spec new file mode 100644 index 000000000..3b71bb4c7 --- /dev/null +++ b/certora/specs/DoubleEndedQueue.spec @@ -0,0 +1,300 @@ +import "helpers/helpers.spec"; + +methods { + function pushFront(bytes32) external envfree; + function pushBack(bytes32) external envfree; + function popFront() external returns (bytes32) envfree; + function popBack() external returns (bytes32) envfree; + function clear() external envfree; + + // exposed for FV + function begin() external returns (uint128) envfree; + function end() external returns (uint128) envfree; + + // view + function length() external returns (uint256) envfree; + function empty() external returns (bool) envfree; + function front() external returns (bytes32) envfree; + function back() external returns (bytes32) envfree; + function at_(uint256) external returns (bytes32) envfree; // at is a reserved word +} + +definition full() returns bool = length() == max_uint128; + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Invariant: empty() is length 0 and no element exists │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +invariant emptiness() + empty() <=> length() == 0 + filtered { f -> !f.isView } + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Invariant: front points to the first index and back points to the last one │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +invariant queueFront() + at_(0) == front() + filtered { f -> !f.isView } + +invariant queueBack() + at_(require_uint256(length() - 1)) == back() + filtered { f -> !f.isView } + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Function correctness: pushFront adds an element at the beginning of the queue │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +rule pushFront(bytes32 value) { + uint256 lengthBefore = length(); + bool fullBefore = full(); + + pushFront@withrevert(value); + bool success = !lastReverted; + + // liveness + assert success <=> !fullBefore, "never revert if not previously full"; + + // effect + assert success => front() == value, "front set to value"; + assert success => to_mathint(length()) == lengthBefore + 1, "queue extended"; +} + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Rule: pushFront preserves the previous values in the queue with a +1 offset │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +rule pushFrontConsistency(uint256 index) { + bytes32 beforeAt = at_(index); + + bytes32 value; + pushFront(value); + + // try to read value + bytes32 afterAt = at_@withrevert(require_uint256(index + 1)); + + assert !lastReverted, "value still there"; + assert afterAt == beforeAt, "data is preserved"; +} + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Function correctness: pushBack adds an element at the end of the queue │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +rule pushBack(bytes32 value) { + uint256 lengthBefore = length(); + bool fullBefore = full(); + + pushBack@withrevert(value); + bool success = !lastReverted; + + // liveness + assert success <=> !fullBefore, "never revert if not previously full"; + + // effect + assert success => back() == value, "back set to value"; + assert success => to_mathint(length()) == lengthBefore + 1, "queue increased"; +} + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Rule: pushBack preserves the previous values in the queue │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +rule pushBackConsistency(uint256 index) { + bytes32 beforeAt = at_(index); + + bytes32 value; + pushBack(value); + + // try to read value + bytes32 afterAt = at_@withrevert(index); + + assert !lastReverted, "value still there"; + assert afterAt == beforeAt, "data is preserved"; +} + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Function correctness: popFront removes an element from the beginning of the queue │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +rule popFront { + uint256 lengthBefore = length(); + bytes32 frontBefore = front@withrevert(); + + bytes32 popped = popFront@withrevert(); + bool success = !lastReverted; + + // liveness + assert success <=> lengthBefore != 0, "never reverts if not previously empty"; + + // effect + assert success => frontBefore == popped, "previous front is returned"; + assert success => to_mathint(length()) == lengthBefore - 1, "queue decreased"; +} + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Rule: at(x) is preserved and offset to at(x - 1) after calling popFront | +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +rule popFrontConsistency(uint256 index) { + // Read (any) value that is not the front (this asserts the value exists / the queue is long enough) + require index > 1; + bytes32 before = at_(index); + + popFront(); + + // try to read value + bytes32 after = at_@withrevert(require_uint256(index - 1)); + + assert !lastReverted, "value still exists in the queue"; + assert before == after, "values are offset and not modified"; +} + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Function correctness: popBack removes an element from the end of the queue │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +rule popBack { + uint256 lengthBefore = length(); + bytes32 backBefore = back@withrevert(); + + bytes32 popped = popBack@withrevert(); + bool success = !lastReverted; + + // liveness + assert success <=> lengthBefore != 0, "never reverts if not previously empty"; + + // effect + assert success => backBefore == popped, "previous back is returned"; + assert success => to_mathint(length()) == lengthBefore - 1, "queue decreased"; +} + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Rule: at(x) is preserved after calling popBack | +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +rule popBackConsistency(uint256 index) { + // Read (any) value that is not the back (this asserts the value exists / the queue is long enough) + require to_mathint(index) < length() - 1; + bytes32 before = at_(index); + + popBack(); + + // try to read value + bytes32 after = at_@withrevert(index); + + assert !lastReverted, "value still exists in the queue"; + assert before == after, "values are offset and not modified"; +} + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Function correctness: clear sets length to 0 │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +rule clear { + clear@withrevert(); + + // liveness + assert !lastReverted, "never reverts"; + + // effect + assert length() == 0, "sets length to 0"; +} + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Rule: front/back access reverts only if the queue is empty or querying out of bounds │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +rule onlyEmptyOrFullRevert(env e) { + require nonpayable(e); + + method f; + calldataarg args; + + bool emptyBefore = empty(); + bool fullBefore = full(); + + f@withrevert(e, args); + + assert lastReverted => ( + (f.selector == sig:front().selector && emptyBefore) || + (f.selector == sig:back().selector && emptyBefore) || + (f.selector == sig:popFront().selector && emptyBefore) || + (f.selector == sig:popBack().selector && emptyBefore) || + (f.selector == sig:pushFront(bytes32).selector && fullBefore ) || + (f.selector == sig:pushBack(bytes32).selector && fullBefore ) || + f.selector == sig:at_(uint256).selector // revert conditions are verified in onlyOutOfBoundsRevert + ), "only revert if empty or out of bounds"; +} + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Rule: at(index) only reverts if index is out of bounds | +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +rule onlyOutOfBoundsRevert(uint256 index) { + at_@withrevert(index); + + assert lastReverted <=> index >= length(), "only reverts if index is out of bounds"; +} + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Rule: only clear/push/pop operations can change the length of the queue │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +rule noLengthChange(env e) { + method f; + calldataarg args; + + uint256 lengthBefore = length(); + f(e, args); + uint256 lengthAfter = length(); + + assert lengthAfter != lengthBefore => ( + (f.selector == sig:pushFront(bytes32).selector && to_mathint(lengthAfter) == lengthBefore + 1) || + (f.selector == sig:pushBack(bytes32).selector && to_mathint(lengthAfter) == lengthBefore + 1) || + (f.selector == sig:popBack().selector && to_mathint(lengthAfter) == lengthBefore - 1) || + (f.selector == sig:popFront().selector && to_mathint(lengthAfter) == lengthBefore - 1) || + (f.selector == sig:clear().selector && lengthAfter == 0) + ), "length is only affected by clear/pop/push operations"; +} + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Rule: only push/pop can change values bounded in the queue (outside values aren't cleared) │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +rule noDataChange(env e) { + method f; + calldataarg args; + + uint256 index; + bytes32 atBefore = at_(index); + f(e, args); + bytes32 atAfter = at_@withrevert(index); + bool atAfterSuccess = !lastReverted; + + assert !atAfterSuccess <=> ( + (f.selector == sig:clear().selector ) || + (f.selector == sig:popBack().selector && index == length()) || + (f.selector == sig:popFront().selector && index == length()) + ), "indexes of the queue are only removed by clear or pop"; + + assert atAfterSuccess && atAfter != atBefore => ( + f.selector == sig:popFront().selector || + f.selector == sig:pushFront(bytes32).selector + ), "values of the queue are only changed by popFront or pushFront"; +} diff --git a/certora/specs/ERC20.spec b/certora/specs/ERC20.spec new file mode 100644 index 000000000..21a033585 --- /dev/null +++ b/certora/specs/ERC20.spec @@ -0,0 +1,352 @@ +import "helpers/helpers.spec"; +import "methods/IERC20.spec"; +import "methods/IERC2612.spec"; + +methods { + // exposed for FV + function mint(address,uint256) external; + function burn(address,uint256) external; +} + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Ghost & hooks: sum of all balances │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +ghost mathint sumOfBalances { + init_state axiom sumOfBalances == 0; +} + +// Because `balance` has a uint256 type, any balance addition in CVL1 behaved as a `require_uint256()` casting, +// leaving out the possibility of overflow. This is not the case in CVL2 where casting became more explicit. +// A counterexample in CVL2 is having an initial state where Alice initial balance is larger than totalSupply, which +// overflows Alice's balance when receiving a transfer. This is not possible unless the contract is deployed into an +// already used address (or upgraded from corrupted state). +// We restrict such behavior by making sure no balance is greater than the sum of balances. +hook Sload uint256 balance _balances[KEY address addr] STORAGE { + require sumOfBalances >= to_mathint(balance); +} + +hook Sstore _balances[KEY address addr] uint256 newValue (uint256 oldValue) STORAGE { + sumOfBalances = sumOfBalances - oldValue + newValue; +} + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Invariant: totalSupply is the sum of all balances │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +invariant totalSupplyIsSumOfBalances() + to_mathint(totalSupply()) == sumOfBalances; + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Invariant: balance of address(0) is 0 │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +invariant zeroAddressNoBalance() + balanceOf(0) == 0; + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Rules: only mint and burn can change total supply │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +rule noChangeTotalSupply(env e) { + requireInvariant totalSupplyIsSumOfBalances(); + + method f; + calldataarg args; + + uint256 totalSupplyBefore = totalSupply(); + f(e, args); + uint256 totalSupplyAfter = totalSupply(); + + assert totalSupplyAfter > totalSupplyBefore => f.selector == sig:mint(address,uint256).selector; + assert totalSupplyAfter < totalSupplyBefore => f.selector == sig:burn(address,uint256).selector; +} + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Rules: only the token holder or an approved third party can reduce an account's balance │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +rule onlyAuthorizedCanTransfer(env e) { + requireInvariant totalSupplyIsSumOfBalances(); + + method f; + calldataarg args; + address account; + + uint256 allowanceBefore = allowance(account, e.msg.sender); + uint256 balanceBefore = balanceOf(account); + f(e, args); + uint256 balanceAfter = balanceOf(account); + + assert ( + balanceAfter < balanceBefore + ) => ( + f.selector == sig:burn(address,uint256).selector || + e.msg.sender == account || + balanceBefore - balanceAfter <= to_mathint(allowanceBefore) + ); +} + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Rules: only the token holder (or a permit) can increase allowance. The spender can decrease it by using it │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +rule onlyHolderOfSpenderCanChangeAllowance(env e) { + requireInvariant totalSupplyIsSumOfBalances(); + + method f; + calldataarg args; + address holder; + address spender; + + uint256 allowanceBefore = allowance(holder, spender); + f(e, args); + uint256 allowanceAfter = allowance(holder, spender); + + assert ( + allowanceAfter > allowanceBefore + ) => ( + (f.selector == sig:approve(address,uint256).selector && e.msg.sender == holder) || + (f.selector == sig:permit(address,address,uint256,uint256,uint8,bytes32,bytes32).selector) + ); + + assert ( + allowanceAfter < allowanceBefore + ) => ( + (f.selector == sig:transferFrom(address,address,uint256).selector && e.msg.sender == spender) || + (f.selector == sig:approve(address,uint256).selector && e.msg.sender == holder ) || + (f.selector == sig:permit(address,address,uint256,uint256,uint8,bytes32,bytes32).selector) + ); +} + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Rules: mint behavior and side effects │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +rule mint(env e) { + requireInvariant totalSupplyIsSumOfBalances(); + require nonpayable(e); + + address to; + address other; + uint256 amount; + + // cache state + uint256 toBalanceBefore = balanceOf(to); + uint256 otherBalanceBefore = balanceOf(other); + uint256 totalSupplyBefore = totalSupply(); + + // run transaction + mint@withrevert(e, to, amount); + + // check outcome + if (lastReverted) { + assert to == 0 || totalSupplyBefore + amount > max_uint256; + } else { + // updates balance and totalSupply + assert to_mathint(balanceOf(to)) == toBalanceBefore + amount; + assert to_mathint(totalSupply()) == totalSupplyBefore + amount; + + // no other balance is modified + assert balanceOf(other) != otherBalanceBefore => other == to; + } +} + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Rules: burn behavior and side effects │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +rule burn(env e) { + requireInvariant totalSupplyIsSumOfBalances(); + require nonpayable(e); + + address from; + address other; + uint256 amount; + + // cache state + uint256 fromBalanceBefore = balanceOf(from); + uint256 otherBalanceBefore = balanceOf(other); + uint256 totalSupplyBefore = totalSupply(); + + // run transaction + burn@withrevert(e, from, amount); + + // check outcome + if (lastReverted) { + assert from == 0 || fromBalanceBefore < amount; + } else { + // updates balance and totalSupply + assert to_mathint(balanceOf(from)) == fromBalanceBefore - amount; + assert to_mathint(totalSupply()) == totalSupplyBefore - amount; + + // no other balance is modified + assert balanceOf(other) != otherBalanceBefore => other == from; + } +} + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Rule: transfer behavior and side effects │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +rule transfer(env e) { + requireInvariant totalSupplyIsSumOfBalances(); + require nonpayable(e); + + address holder = e.msg.sender; + address recipient; + address other; + uint256 amount; + + // cache state + uint256 holderBalanceBefore = balanceOf(holder); + uint256 recipientBalanceBefore = balanceOf(recipient); + uint256 otherBalanceBefore = balanceOf(other); + + // run transaction + transfer@withrevert(e, recipient, amount); + + // check outcome + if (lastReverted) { + assert holder == 0 || recipient == 0 || amount > holderBalanceBefore; + } else { + // balances of holder and recipient are updated + assert to_mathint(balanceOf(holder)) == holderBalanceBefore - (holder == recipient ? 0 : amount); + assert to_mathint(balanceOf(recipient)) == recipientBalanceBefore + (holder == recipient ? 0 : amount); + + // no other balance is modified + assert balanceOf(other) != otherBalanceBefore => (other == holder || other == recipient); + } +} + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Rule: transferFrom behavior and side effects │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +rule transferFrom(env e) { + requireInvariant totalSupplyIsSumOfBalances(); + require nonpayable(e); + + address spender = e.msg.sender; + address holder; + address recipient; + address other; + uint256 amount; + + // cache state + uint256 allowanceBefore = allowance(holder, spender); + uint256 holderBalanceBefore = balanceOf(holder); + uint256 recipientBalanceBefore = balanceOf(recipient); + uint256 otherBalanceBefore = balanceOf(other); + + // run transaction + transferFrom@withrevert(e, holder, recipient, amount); + + // check outcome + if (lastReverted) { + assert holder == 0 || recipient == 0 || spender == 0 || amount > holderBalanceBefore || amount > allowanceBefore; + } else { + // allowance is valid & updated + assert allowanceBefore >= amount; + assert to_mathint(allowance(holder, spender)) == (allowanceBefore == max_uint256 ? max_uint256 : allowanceBefore - amount); + + // balances of holder and recipient are updated + assert to_mathint(balanceOf(holder)) == holderBalanceBefore - (holder == recipient ? 0 : amount); + assert to_mathint(balanceOf(recipient)) == recipientBalanceBefore + (holder == recipient ? 0 : amount); + + // no other balance is modified + assert balanceOf(other) != otherBalanceBefore => (other == holder || other == recipient); + } +} + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Rule: approve behavior and side effects │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +rule approve(env e) { + require nonpayable(e); + + address holder = e.msg.sender; + address spender; + address otherHolder; + address otherSpender; + uint256 amount; + + // cache state + uint256 otherAllowanceBefore = allowance(otherHolder, otherSpender); + + // run transaction + approve@withrevert(e, spender, amount); + + // check outcome + if (lastReverted) { + assert holder == 0 || spender == 0; + } else { + // allowance is updated + assert allowance(holder, spender) == amount; + + // other allowances are untouched + assert allowance(otherHolder, otherSpender) != otherAllowanceBefore => (otherHolder == holder && otherSpender == spender); + } +} + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Rule: permit behavior and side effects │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +rule permit(env e) { + require nonpayable(e); + + address holder; + address spender; + uint256 amount; + uint256 deadline; + uint8 v; + bytes32 r; + bytes32 s; + + address account1; + address account2; + address account3; + + // cache state + uint256 nonceBefore = nonces(holder); + uint256 otherNonceBefore = nonces(account1); + uint256 otherAllowanceBefore = allowance(account2, account3); + + // sanity: nonce overflow, which possible in theory, is assumed to be impossible in practice + require nonceBefore < max_uint256; + require otherNonceBefore < max_uint256; + + // run transaction + permit@withrevert(e, holder, spender, amount, deadline, v, r, s); + + // check outcome + if (lastReverted) { + // Without formally checking the signature, we can't verify exactly the revert causes + assert true; + } else { + // allowance and nonce are updated + assert allowance(holder, spender) == amount; + assert to_mathint(nonces(holder)) == nonceBefore + 1; + + // deadline was respected + assert deadline >= e.block.timestamp; + + // no other allowance or nonce is modified + assert nonces(account1) != otherNonceBefore => account1 == holder; + assert allowance(account2, account3) != otherAllowanceBefore => (account2 == holder && account3 == spender); + } +} diff --git a/certora/specs/ERC20FlashMint.spec b/certora/specs/ERC20FlashMint.spec new file mode 100644 index 000000000..5c87f0ded --- /dev/null +++ b/certora/specs/ERC20FlashMint.spec @@ -0,0 +1,55 @@ +import "helpers/helpers.spec"; +import "methods/IERC20.spec"; +import "methods/IERC3156FlashLender.spec"; +import "methods/IERC3156FlashBorrower.spec"; + +methods { + // non standard ERC3156 functions + function flashFeeReceiver() external returns (address) envfree; + + // function summaries below + function _._update(address from, address to, uint256 amount) internal => specUpdate(from, to, amount) expect void ALL; +} + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Ghost: track mint and burns in the CVL │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +ghost mapping(address => mathint) trackedMintAmount; +ghost mapping(address => mathint) trackedBurnAmount; +ghost mapping(address => mapping(address => mathint)) trackedTransferedAmount; + +function specUpdate(address from, address to, uint256 amount) { + if (from == 0 && to == 0) { assert(false); } // defensive + + if (from == 0) { + trackedMintAmount[to] = amount; + } else if (to == 0) { + trackedBurnAmount[from] = amount; + } else { + trackedTransferedAmount[from][to] = amount; + } +} + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Rule: When doing a flashLoan, "amount" is minted and burnt, additionally, the fee is either burnt │ +│ (if the fee recipient is 0) or transferred (if the fee recipient is not 0) │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +rule checkMintAndBurn(env e) { + address receiver; + address token; + uint256 amount; + bytes data; + + uint256 fees = flashFee(token, amount); + address recipient = flashFeeReceiver(); + + flashLoan(e, receiver, token, amount, data); + + assert trackedMintAmount[receiver] == to_mathint(amount); + assert trackedBurnAmount[receiver] == amount + to_mathint(recipient == 0 ? fees : 0); + assert (fees > 0 && recipient != 0) => trackedTransferedAmount[receiver][recipient] == to_mathint(fees); +} diff --git a/certora/specs/ERC20Wrapper.spec b/certora/specs/ERC20Wrapper.spec new file mode 100644 index 000000000..04e67042a --- /dev/null +++ b/certora/specs/ERC20Wrapper.spec @@ -0,0 +1,198 @@ +import "helpers/helpers.spec"; +import "ERC20.spec"; + +methods { + function underlying() external returns(address) envfree; + function underlyingTotalSupply() external returns(uint256) envfree; + function underlyingBalanceOf(address) external returns(uint256) envfree; + function underlyingAllowanceToThis(address) external returns(uint256) envfree; + + function depositFor(address, uint256) external returns(bool); + function withdrawTo(address, uint256) external returns(bool); + function recover(address) external returns(uint256); +} + +use invariant totalSupplyIsSumOfBalances; + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Helper: consequence of `totalSupplyIsSumOfBalances` applied to underlying │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +definition underlyingBalancesLowerThanUnderlyingSupply(address a) returns bool = + underlyingBalanceOf(a) <= underlyingTotalSupply(); + +definition sumOfUnderlyingBalancesLowerThanUnderlyingSupply(address a, address b) returns bool = + a != b => underlyingBalanceOf(a) + underlyingBalanceOf(b) <= to_mathint(underlyingTotalSupply()); + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Invariant: wrapped token can't be undercollateralized (solvency of the wrapper) │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +invariant totalSupplyIsSmallerThanUnderlyingBalance() + totalSupply() <= underlyingBalanceOf(currentContract) && + underlyingBalanceOf(currentContract) <= underlyingTotalSupply() && + underlyingTotalSupply() <= max_uint256 + { + preserved { + requireInvariant totalSupplyIsSumOfBalances; + require underlyingBalancesLowerThanUnderlyingSupply(currentContract); + } + preserved depositFor(address account, uint256 amount) with (env e) { + require sumOfUnderlyingBalancesLowerThanUnderlyingSupply(e.msg.sender, currentContract); + } + } + +invariant noSelfWrap() + currentContract != underlying(); + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Rule: depositFor liveness and effects │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +rule depositFor(env e) { + require nonpayable(e); + + address sender = e.msg.sender; + address receiver; + address other; + uint256 amount; + + // sanity + requireInvariant noSelfWrap; + requireInvariant totalSupplyIsSumOfBalances; + requireInvariant totalSupplyIsSmallerThanUnderlyingBalance; + require sumOfUnderlyingBalancesLowerThanUnderlyingSupply(currentContract, sender); + + uint256 balanceBefore = balanceOf(receiver); + uint256 supplyBefore = totalSupply(); + uint256 senderUnderlyingBalanceBefore = underlyingBalanceOf(sender); + uint256 senderUnderlyingAllowanceBefore = underlyingAllowanceToThis(sender); + uint256 wrapperUnderlyingBalanceBefore = underlyingBalanceOf(currentContract); + uint256 underlyingSupplyBefore = underlyingTotalSupply(); + + uint256 otherBalanceBefore = balanceOf(other); + uint256 otherUnderlyingBalanceBefore = underlyingBalanceOf(other); + + depositFor@withrevert(e, receiver, amount); + bool success = !lastReverted; + + // liveness + assert success <=> ( + sender != currentContract && // invalid sender + sender != 0 && // invalid sender + receiver != currentContract && // invalid receiver + receiver != 0 && // invalid receiver + amount <= senderUnderlyingBalanceBefore && // deposit doesn't exceed balance + amount <= senderUnderlyingAllowanceBefore // deposit doesn't exceed allowance + ); + + // effects + assert success => ( + to_mathint(balanceOf(receiver)) == balanceBefore + amount && + to_mathint(totalSupply()) == supplyBefore + amount && + to_mathint(underlyingBalanceOf(currentContract)) == wrapperUnderlyingBalanceBefore + amount && + to_mathint(underlyingBalanceOf(sender)) == senderUnderlyingBalanceBefore - amount + ); + + // no side effect + assert underlyingTotalSupply() == underlyingSupplyBefore; + assert balanceOf(other) != otherBalanceBefore => other == receiver; + assert underlyingBalanceOf(other) != otherUnderlyingBalanceBefore => (other == sender || other == currentContract); +} + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Rule: withdrawTo liveness and effects │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +rule withdrawTo(env e) { + require nonpayable(e); + + address sender = e.msg.sender; + address receiver; + address other; + uint256 amount; + + // sanity + requireInvariant noSelfWrap; + requireInvariant totalSupplyIsSumOfBalances; + requireInvariant totalSupplyIsSmallerThanUnderlyingBalance; + require sumOfUnderlyingBalancesLowerThanUnderlyingSupply(currentContract, receiver); + + uint256 balanceBefore = balanceOf(sender); + uint256 supplyBefore = totalSupply(); + uint256 receiverUnderlyingBalanceBefore = underlyingBalanceOf(receiver); + uint256 wrapperUnderlyingBalanceBefore = underlyingBalanceOf(currentContract); + uint256 underlyingSupplyBefore = underlyingTotalSupply(); + + uint256 otherBalanceBefore = balanceOf(other); + uint256 otherUnderlyingBalanceBefore = underlyingBalanceOf(other); + + withdrawTo@withrevert(e, receiver, amount); + bool success = !lastReverted; + + // liveness + assert success <=> ( + sender != 0 && // invalid sender + receiver != currentContract && // invalid receiver + receiver != 0 && // invalid receiver + amount <= balanceBefore // withdraw doesn't exceed balance + ); + + // effects + assert success => ( + to_mathint(balanceOf(sender)) == balanceBefore - amount && + to_mathint(totalSupply()) == supplyBefore - amount && + to_mathint(underlyingBalanceOf(currentContract)) == wrapperUnderlyingBalanceBefore - (currentContract != receiver ? amount : 0) && + to_mathint(underlyingBalanceOf(receiver)) == receiverUnderlyingBalanceBefore + (currentContract != receiver ? amount : 0) + ); + + // no side effect + assert underlyingTotalSupply() == underlyingSupplyBefore; + assert balanceOf(other) != otherBalanceBefore => other == sender; + assert underlyingBalanceOf(other) != otherUnderlyingBalanceBefore => (other == receiver || other == currentContract); +} + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Rule: recover liveness and effects │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +rule recover(env e) { + require nonpayable(e); + + address receiver; + address other; + + // sanity + requireInvariant noSelfWrap; + requireInvariant totalSupplyIsSumOfBalances; + requireInvariant totalSupplyIsSmallerThanUnderlyingBalance; + + mathint value = underlyingBalanceOf(currentContract) - totalSupply(); + uint256 supplyBefore = totalSupply(); + uint256 balanceBefore = balanceOf(receiver); + + uint256 otherBalanceBefore = balanceOf(other); + uint256 otherUnderlyingBalanceBefore = underlyingBalanceOf(other); + + recover@withrevert(e, receiver); + bool success = !lastReverted; + + // liveness + assert success <=> receiver != 0; + + // effect + assert success => ( + to_mathint(balanceOf(receiver)) == balanceBefore + value && + to_mathint(totalSupply()) == supplyBefore + value && + totalSupply() == underlyingBalanceOf(currentContract) + ); + + // no side effect + assert underlyingBalanceOf(other) == otherUnderlyingBalanceBefore; + assert balanceOf(other) != otherBalanceBefore => other == receiver; +} diff --git a/certora/specs/ERC721.spec b/certora/specs/ERC721.spec new file mode 100644 index 000000000..bad4c4737 --- /dev/null +++ b/certora/specs/ERC721.spec @@ -0,0 +1,679 @@ +import "helpers/helpers.spec"; +import "methods/IERC721.spec"; +import "methods/IERC721Receiver.spec"; + +methods { + // exposed for FV + function mint(address,uint256) external; + function safeMint(address,uint256) external; + function safeMint(address,uint256,bytes) external; + function burn(uint256) external; + + function unsafeOwnerOf(uint256) external returns (address) envfree; + function unsafeGetApproved(uint256) external returns (address) envfree; +} + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Helpers │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ + +definition authSanity(env e) returns bool = e.msg.sender != 0; + +// Could be broken in theory, but not in practice +definition balanceLimited(address account) returns bool = balanceOf(account) < max_uint256; + +function helperTransferWithRevert(env e, method f, address from, address to, uint256 tokenId) { + if (f.selector == sig:transferFrom(address,address,uint256).selector) { + transferFrom@withrevert(e, from, to, tokenId); + } else if (f.selector == sig:safeTransferFrom(address,address,uint256).selector) { + safeTransferFrom@withrevert(e, from, to, tokenId); + } else if (f.selector == sig:safeTransferFrom(address,address,uint256,bytes).selector) { + bytes params; + require params.length < 0xffff; + safeTransferFrom@withrevert(e, from, to, tokenId, params); + } else { + calldataarg args; + f@withrevert(e, args); + } +} + +function helperMintWithRevert(env e, method f, address to, uint256 tokenId) { + if (f.selector == sig:mint(address,uint256).selector) { + mint@withrevert(e, to, tokenId); + } else if (f.selector == sig:safeMint(address,uint256).selector) { + safeMint@withrevert(e, to, tokenId); + } else if (f.selector == sig:safeMint(address,uint256,bytes).selector) { + bytes params; + require params.length < 0xffff; + safeMint@withrevert(e, to, tokenId, params); + } else { + require false; + } +} + +function helperSoundFnCall(env e, method f) { + if (f.selector == sig:mint(address,uint256).selector) { + address to; uint256 tokenId; + require balanceLimited(to); + requireInvariant notMintedUnset(tokenId); + mint(e, to, tokenId); + } else if (f.selector == sig:safeMint(address,uint256).selector) { + address to; uint256 tokenId; + require balanceLimited(to); + requireInvariant notMintedUnset(tokenId); + safeMint(e, to, tokenId); + } else if (f.selector == sig:safeMint(address,uint256,bytes).selector) { + address to; uint256 tokenId; bytes data; + require data.length < 0xffff; + require balanceLimited(to); + requireInvariant notMintedUnset(tokenId); + safeMint(e, to, tokenId, data); + } else if (f.selector == sig:burn(uint256).selector) { + uint256 tokenId; + requireInvariant ownerHasBalance(tokenId); + requireInvariant notMintedUnset(tokenId); + burn(e, tokenId); + } else if (f.selector == sig:transferFrom(address,address,uint256).selector) { + address from; address to; uint256 tokenId; + require balanceLimited(to); + requireInvariant ownerHasBalance(tokenId); + requireInvariant notMintedUnset(tokenId); + transferFrom(e, from, to, tokenId); + } else if (f.selector == sig:safeTransferFrom(address,address,uint256).selector) { + address from; address to; uint256 tokenId; + require balanceLimited(to); + requireInvariant ownerHasBalance(tokenId); + requireInvariant notMintedUnset(tokenId); + safeTransferFrom(e, from, to, tokenId); + } else if (f.selector == sig:safeTransferFrom(address,address,uint256,bytes).selector) { + address from; address to; uint256 tokenId; bytes data; + require data.length < 0xffff; + require balanceLimited(to); + requireInvariant ownerHasBalance(tokenId); + requireInvariant notMintedUnset(tokenId); + safeTransferFrom(e, from, to, tokenId, data); + } else { + calldataarg args; + f(e, args); + } +} + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Ghost & hooks: ownership count │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +ghost mathint _ownedTotal { + init_state axiom _ownedTotal == 0; +} + +ghost mapping(address => mathint) _ownedByUser { + init_state axiom forall address a. _ownedByUser[a] == 0; +} + +hook Sstore _owners[KEY uint256 tokenId] address newOwner (address oldOwner) STORAGE { + _ownedByUser[newOwner] = _ownedByUser[newOwner] + to_mathint(newOwner != 0 ? 1 : 0); + _ownedByUser[oldOwner] = _ownedByUser[oldOwner] - to_mathint(oldOwner != 0 ? 1 : 0); + _ownedTotal = _ownedTotal + to_mathint(newOwner != 0 ? 1 : 0) - to_mathint(oldOwner != 0 ? 1 : 0); +} + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Ghost & hooks: sum of all balances │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +ghost mathint _supply { + init_state axiom _supply == 0; +} + +ghost mapping(address => mathint) _balances { + init_state axiom forall address a. _balances[a] == 0; +} + +hook Sstore _balances[KEY address addr] uint256 newValue (uint256 oldValue) STORAGE { + _supply = _supply - oldValue + newValue; +} + +// TODO: This used to not be necessary. We should try to remove it. In order to do so, we will probably need to add +// many "preserved" directive that require the "balanceOfConsistency" invariant on the accounts involved. +hook Sload uint256 value _balances[KEY address user] STORAGE { + require _balances[user] == to_mathint(value); +} + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Invariant: number of owned tokens is the sum of all balances │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +invariant ownedTotalIsSumOfBalances() + _ownedTotal == _supply + { + preserved mint(address to, uint256 tokenId) with (env e) { + require balanceLimited(to); + } + preserved safeMint(address to, uint256 tokenId) with (env e) { + require balanceLimited(to); + } + preserved safeMint(address to, uint256 tokenId, bytes data) with (env e) { + require balanceLimited(to); + } + preserved burn(uint256 tokenId) with (env e) { + requireInvariant ownerHasBalance(tokenId); + requireInvariant balanceOfConsistency(ownerOf(tokenId)); + } + preserved transferFrom(address from, address to, uint256 tokenId) with (env e) { + require balanceLimited(to); + requireInvariant ownerHasBalance(tokenId); + requireInvariant balanceOfConsistency(from); + requireInvariant balanceOfConsistency(to); + } + preserved safeTransferFrom(address from, address to, uint256 tokenId) with (env e) { + require balanceLimited(to); + requireInvariant ownerHasBalance(tokenId); + requireInvariant balanceOfConsistency(from); + requireInvariant balanceOfConsistency(to); + } + preserved safeTransferFrom(address from, address to, uint256 tokenId, bytes data) with (env e) { + require balanceLimited(to); + requireInvariant ownerHasBalance(tokenId); + requireInvariant balanceOfConsistency(from); + requireInvariant balanceOfConsistency(to); + } + } + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Invariant: balanceOf is the number of tokens owned │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +invariant balanceOfConsistency(address user) + to_mathint(balanceOf(user)) == _ownedByUser[user] && + to_mathint(balanceOf(user)) == _balances[user] + { + preserved { + require balanceLimited(user); + } + } + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Invariant: owner of a token must have some balance │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +invariant ownerHasBalance(uint256 tokenId) + balanceOf(ownerOf(tokenId)) > 0 + { + preserved { + requireInvariant balanceOfConsistency(ownerOf(tokenId)); + require balanceLimited(ownerOf(tokenId)); + } + } + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Rule: balance of address(0) is 0 │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +rule zeroAddressBalanceRevert() { + balanceOf@withrevert(0); + assert lastReverted; +} + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Invariant: address(0) has no authorized operator │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +invariant zeroAddressHasNoApprovedOperator(address a) + !isApprovedForAll(0, a) + { + preserved with (env e) { + require nonzerosender(e); + } + } + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Invariant: tokens that do not exist are not owned and not approved │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +invariant notMintedUnset(uint256 tokenId) + unsafeOwnerOf(tokenId) == 0 => unsafeGetApproved(tokenId) == 0; + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Rule: unsafeOwnerOf and unsafeGetApproved don't revert + ownerOf and getApproved revert if token does not exist │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +rule notMintedRevert(uint256 tokenId) { + requireInvariant notMintedUnset(tokenId); + + address _owner = unsafeOwnerOf@withrevert(tokenId); + assert !lastReverted; + + address _approved = unsafeGetApproved@withrevert(tokenId); + assert !lastReverted; + + address owner = ownerOf@withrevert(tokenId); + assert lastReverted <=> _owner == 0; + assert !lastReverted => _owner == owner; + + address approved = getApproved@withrevert(tokenId); + assert lastReverted <=> _owner == 0; + assert !lastReverted => _approved == approved; +} + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Rules: total supply can only change through mint and burn │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +rule supplyChange(env e) { + require nonzerosender(e); + requireInvariant zeroAddressHasNoApprovedOperator(e.msg.sender); + + mathint supplyBefore = _supply; + method f; helperSoundFnCall(e, f); + mathint supplyAfter = _supply; + + assert supplyAfter > supplyBefore => ( + supplyAfter == supplyBefore + 1 && + ( + f.selector == sig:mint(address,uint256).selector || + f.selector == sig:safeMint(address,uint256).selector || + f.selector == sig:safeMint(address,uint256,bytes).selector + ) + ); + assert supplyAfter < supplyBefore => ( + supplyAfter == supplyBefore - 1 && + f.selector == sig:burn(uint256).selector + ); +} + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Rules: balanceOf can only change through mint, burn or transfers. balanceOf cannot change by more than 1. │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +rule balanceChange(env e, address account) { + requireInvariant balanceOfConsistency(account); + require balanceLimited(account); + + mathint balanceBefore = balanceOf(account); + method f; helperSoundFnCall(e, f); + mathint balanceAfter = balanceOf(account); + + // balance can change by at most 1 + assert balanceBefore != balanceAfter => ( + balanceAfter == balanceBefore - 1 || + balanceAfter == balanceBefore + 1 + ); + + // only selected function can change balances + assert balanceBefore != balanceAfter => ( + f.selector == sig:transferFrom(address,address,uint256).selector || + f.selector == sig:safeTransferFrom(address,address,uint256).selector || + f.selector == sig:safeTransferFrom(address,address,uint256,bytes).selector || + f.selector == sig:mint(address,uint256).selector || + f.selector == sig:safeMint(address,uint256).selector || + f.selector == sig:safeMint(address,uint256,bytes).selector || + f.selector == sig:burn(uint256).selector + ); +} + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Rules: ownership can only change through mint, burn or transfers. │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +rule ownershipChange(env e, uint256 tokenId) { + require nonzerosender(e); + requireInvariant zeroAddressHasNoApprovedOperator(e.msg.sender); + + address ownerBefore = unsafeOwnerOf(tokenId); + method f; helperSoundFnCall(e, f); + address ownerAfter = unsafeOwnerOf(tokenId); + + assert ownerBefore == 0 && ownerAfter != 0 => ( + f.selector == sig:mint(address,uint256).selector || + f.selector == sig:safeMint(address,uint256).selector || + f.selector == sig:safeMint(address,uint256,bytes).selector + ); + + assert ownerBefore != 0 && ownerAfter == 0 => ( + f.selector == sig:burn(uint256).selector + ); + + assert (ownerBefore != ownerAfter && ownerBefore != 0 && ownerAfter != 0) => ( + f.selector == sig:transferFrom(address,address,uint256).selector || + f.selector == sig:safeTransferFrom(address,address,uint256).selector || + f.selector == sig:safeTransferFrom(address,address,uint256,bytes).selector + ); +} + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Rules: token approval can only change through approve or transfers (implicitly). │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +rule approvalChange(env e, uint256 tokenId) { + address approvalBefore = unsafeGetApproved(tokenId); + method f; helperSoundFnCall(e, f); + address approvalAfter = unsafeGetApproved(tokenId); + + // approve can set any value, other functions reset + assert approvalBefore != approvalAfter => ( + f.selector == sig:approve(address,uint256).selector || + ( + ( + f.selector == sig:transferFrom(address,address,uint256).selector || + f.selector == sig:safeTransferFrom(address,address,uint256).selector || + f.selector == sig:safeTransferFrom(address,address,uint256,bytes).selector || + f.selector == sig:burn(uint256).selector + ) && approvalAfter == 0 + ) + ); +} + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Rules: approval for all tokens can only change through isApprovedForAll. │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +rule approvedForAllChange(env e, address owner, address spender) { + bool approvedForAllBefore = isApprovedForAll(owner, spender); + method f; helperSoundFnCall(e, f); + bool approvedForAllAfter = isApprovedForAll(owner, spender); + + assert approvedForAllBefore != approvedForAllAfter => f.selector == sig:setApprovalForAll(address,bool).selector; +} + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Rule: transferFrom behavior and side effects │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +rule transferFrom(env e, address from, address to, uint256 tokenId) { + require nonpayable(e); + require authSanity(e); + + address operator = e.msg.sender; + uint256 otherTokenId; + address otherAccount; + + requireInvariant ownerHasBalance(tokenId); + require balanceLimited(to); + + uint256 balanceOfFromBefore = balanceOf(from); + uint256 balanceOfToBefore = balanceOf(to); + uint256 balanceOfOtherBefore = balanceOf(otherAccount); + address ownerBefore = unsafeOwnerOf(tokenId); + address otherOwnerBefore = unsafeOwnerOf(otherTokenId); + address approvalBefore = unsafeGetApproved(tokenId); + address otherApprovalBefore = unsafeGetApproved(otherTokenId); + + transferFrom@withrevert(e, from, to, tokenId); + bool success = !lastReverted; + + // liveness + assert success <=> ( + from == ownerBefore && + from != 0 && + to != 0 && + (operator == from || operator == approvalBefore || isApprovedForAll(ownerBefore, operator)) + ); + + // effect + assert success => ( + to_mathint(balanceOf(from)) == balanceOfFromBefore - assert_uint256(from != to ? 1 : 0) && + to_mathint(balanceOf(to)) == balanceOfToBefore + assert_uint256(from != to ? 1 : 0) && + unsafeOwnerOf(tokenId) == to && + unsafeGetApproved(tokenId) == 0 + ); + + // no side effect + assert balanceOf(otherAccount) != balanceOfOtherBefore => (otherAccount == from || otherAccount == to); + assert unsafeOwnerOf(otherTokenId) != otherOwnerBefore => otherTokenId == tokenId; + assert unsafeGetApproved(otherTokenId) != otherApprovalBefore => otherTokenId == tokenId; +} + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Rule: safeTransferFrom behavior and side effects │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +rule safeTransferFrom(env e, method f, address from, address to, uint256 tokenId) filtered { f -> + f.selector == sig:safeTransferFrom(address,address,uint256).selector || + f.selector == sig:safeTransferFrom(address,address,uint256,bytes).selector +} { + require nonpayable(e); + require authSanity(e); + + address operator = e.msg.sender; + uint256 otherTokenId; + address otherAccount; + + requireInvariant ownerHasBalance(tokenId); + require balanceLimited(to); + + uint256 balanceOfFromBefore = balanceOf(from); + uint256 balanceOfToBefore = balanceOf(to); + uint256 balanceOfOtherBefore = balanceOf(otherAccount); + address ownerBefore = unsafeOwnerOf(tokenId); + address otherOwnerBefore = unsafeOwnerOf(otherTokenId); + address approvalBefore = unsafeGetApproved(tokenId); + address otherApprovalBefore = unsafeGetApproved(otherTokenId); + + helperTransferWithRevert(e, f, from, to, tokenId); + bool success = !lastReverted; + + assert success <=> ( + from == ownerBefore && + from != 0 && + to != 0 && + (operator == from || operator == approvalBefore || isApprovedForAll(ownerBefore, operator)) + ); + + // effect + assert success => ( + to_mathint(balanceOf(from)) == balanceOfFromBefore - assert_uint256(from != to ? 1: 0) && + to_mathint(balanceOf(to)) == balanceOfToBefore + assert_uint256(from != to ? 1: 0) && + unsafeOwnerOf(tokenId) == to && + unsafeGetApproved(tokenId) == 0 + ); + + // no side effect + assert balanceOf(otherAccount) != balanceOfOtherBefore => (otherAccount == from || otherAccount == to); + assert unsafeOwnerOf(otherTokenId) != otherOwnerBefore => otherTokenId == tokenId; + assert unsafeGetApproved(otherTokenId) != otherApprovalBefore => otherTokenId == tokenId; +} + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Rule: mint behavior and side effects │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +rule mint(env e, address to, uint256 tokenId) { + require nonpayable(e); + requireInvariant notMintedUnset(tokenId); + + uint256 otherTokenId; + address otherAccount; + + require balanceLimited(to); + + mathint supplyBefore = _supply; + uint256 balanceOfToBefore = balanceOf(to); + uint256 balanceOfOtherBefore = balanceOf(otherAccount); + address ownerBefore = unsafeOwnerOf(tokenId); + address otherOwnerBefore = unsafeOwnerOf(otherTokenId); + + mint@withrevert(e, to, tokenId); + bool success = !lastReverted; + + // liveness + assert success <=> ( + ownerBefore == 0 && + to != 0 + ); + + // effect + assert success => ( + _supply == supplyBefore + 1 && + to_mathint(balanceOf(to)) == balanceOfToBefore + 1 && + unsafeOwnerOf(tokenId) == to + ); + + // no side effect + assert balanceOf(otherAccount) != balanceOfOtherBefore => otherAccount == to; + assert unsafeOwnerOf(otherTokenId) != otherOwnerBefore => otherTokenId == tokenId; +} + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Rule: safeMint behavior and side effects │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +rule safeMint(env e, method f, address to, uint256 tokenId) filtered { f -> + f.selector == sig:safeMint(address,uint256).selector || + f.selector == sig:safeMint(address,uint256,bytes).selector +} { + require nonpayable(e); + requireInvariant notMintedUnset(tokenId); + + uint256 otherTokenId; + address otherAccount; + + require balanceLimited(to); + + mathint supplyBefore = _supply; + uint256 balanceOfToBefore = balanceOf(to); + uint256 balanceOfOtherBefore = balanceOf(otherAccount); + address ownerBefore = unsafeOwnerOf(tokenId); + address otherOwnerBefore = unsafeOwnerOf(otherTokenId); + + helperMintWithRevert(e, f, to, tokenId); + bool success = !lastReverted; + + assert success <=> ( + ownerBefore == 0 && + to != 0 + ); + + // effect + assert success => ( + _supply == supplyBefore + 1 && + to_mathint(balanceOf(to)) == balanceOfToBefore + 1 && + unsafeOwnerOf(tokenId) == to + ); + + // no side effect + assert balanceOf(otherAccount) != balanceOfOtherBefore => otherAccount == to; + assert unsafeOwnerOf(otherTokenId) != otherOwnerBefore => otherTokenId == tokenId; +} + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Rule: burn behavior and side effects │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +rule burn(env e, uint256 tokenId) { + require nonpayable(e); + + address from = unsafeOwnerOf(tokenId); + uint256 otherTokenId; + address otherAccount; + + requireInvariant ownerHasBalance(tokenId); + + mathint supplyBefore = _supply; + uint256 balanceOfFromBefore = balanceOf(from); + uint256 balanceOfOtherBefore = balanceOf(otherAccount); + address ownerBefore = unsafeOwnerOf(tokenId); + address otherOwnerBefore = unsafeOwnerOf(otherTokenId); + address otherApprovalBefore = unsafeGetApproved(otherTokenId); + + burn@withrevert(e, tokenId); + bool success = !lastReverted; + + // liveness + assert success <=> ( + ownerBefore != 0 + ); + + // effect + assert success => ( + _supply == supplyBefore - 1 && + to_mathint(balanceOf(from)) == balanceOfFromBefore - 1 && + unsafeOwnerOf(tokenId) == 0 && + unsafeGetApproved(tokenId) == 0 + ); + + // no side effect + assert balanceOf(otherAccount) != balanceOfOtherBefore => otherAccount == from; + assert unsafeOwnerOf(otherTokenId) != otherOwnerBefore => otherTokenId == tokenId; + assert unsafeGetApproved(otherTokenId) != otherApprovalBefore => otherTokenId == tokenId; +} + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Rule: approve behavior and side effects │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +rule approve(env e, address spender, uint256 tokenId) { + require nonpayable(e); + require authSanity(e); + + address caller = e.msg.sender; + address owner = unsafeOwnerOf(tokenId); + uint256 otherTokenId; + + address otherApprovalBefore = unsafeGetApproved(otherTokenId); + + approve@withrevert(e, spender, tokenId); + bool success = !lastReverted; + + // liveness + assert success <=> ( + owner != 0 && + (owner == caller || isApprovedForAll(owner, caller)) + ); + + // effect + assert success => unsafeGetApproved(tokenId) == spender; + + // no side effect + assert unsafeGetApproved(otherTokenId) != otherApprovalBefore => otherTokenId == tokenId; +} + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Rule: setApprovalForAll behavior and side effects │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +rule setApprovalForAll(env e, address operator, bool approved) { + require nonpayable(e); + + address owner = e.msg.sender; + address otherOwner; + address otherOperator; + + bool otherIsApprovedForAllBefore = isApprovedForAll(otherOwner, otherOperator); + + setApprovalForAll@withrevert(e, operator, approved); + bool success = !lastReverted; + + // liveness + assert success <=> operator != 0; + + // effect + assert success => isApprovedForAll(owner, operator) == approved; + + // no side effect + assert isApprovedForAll(otherOwner, otherOperator) != otherIsApprovedForAllBefore => ( + otherOwner == owner && + otherOperator == operator + ); +} diff --git a/certora/specs/EnumerableMap.spec b/certora/specs/EnumerableMap.spec new file mode 100644 index 000000000..7b503031f --- /dev/null +++ b/certora/specs/EnumerableMap.spec @@ -0,0 +1,333 @@ +import "helpers/helpers.spec"; + +methods { + // library + function set(bytes32,bytes32) external returns (bool) envfree; + function remove(bytes32) external returns (bool) envfree; + function contains(bytes32) external returns (bool) envfree; + function length() external returns (uint256) envfree; + function key_at(uint256) external returns (bytes32) envfree; + function value_at(uint256) external returns (bytes32) envfree; + function tryGet_contains(bytes32) external returns (bool) envfree; + function tryGet_value(bytes32) external returns (bytes32) envfree; + function get(bytes32) external returns (bytes32) envfree; + + // FV + function _indexOf(bytes32) external returns (uint256) envfree; +} + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Helpers │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +definition sanity() returns bool = + length() < max_uint256; + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Invariant: the value mapping is empty for keys that are not in the EnumerableMap. │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +invariant noValueIfNotContained(bytes32 key) + !contains(key) => tryGet_value(key) == to_bytes32(0) + { + preserved set(bytes32 otherKey, bytes32 someValue) { + require sanity(); + } + } + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Invariant: All indexed keys are contained │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +invariant indexedContained(uint256 index) + index < length() => contains(key_at(index)) + { + preserved { + requireInvariant consistencyIndex(index); + requireInvariant consistencyIndex(require_uint256(length() - 1)); + } + } + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Invariant: A value can only be stored at a single location │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +invariant atUniqueness(uint256 index1, uint256 index2) + index1 == index2 <=> key_at(index1) == key_at(index2) + { + preserved remove(bytes32 key) { + requireInvariant atUniqueness(index1, require_uint256(length() - 1)); + requireInvariant atUniqueness(index2, require_uint256(length() - 1)); + } + } + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Invariant: index <> value relationship is consistent │ +│ │ +│ Note that the two consistencyXxx invariants, put together, prove that at_ and _indexOf are inverse of one another. │ +│ This proves that we have a bijection between indices (the enumerability part) and keys (the entries that are set │ +│ and removed from the EnumerableMap). │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +invariant consistencyIndex(uint256 index) + index < length() => to_mathint(_indexOf(key_at(index))) == index + 1 + { + preserved remove(bytes32 key) { + requireInvariant consistencyIndex(require_uint256(length() - 1)); + } + } + +invariant consistencyKey(bytes32 key) + contains(key) => ( + _indexOf(key) > 0 && + _indexOf(key) <= length() && + key_at(require_uint256(_indexOf(key) - 1)) == key + ) + { + preserved remove(bytes32 otherKey) { + requireInvariant consistencyKey(otherKey); + requireInvariant atUniqueness( + require_uint256(_indexOf(key) - 1), + require_uint256(_indexOf(otherKey) - 1) + ); + } + } + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Rule: state only changes by setting or removing elements │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +rule stateChange(env e, bytes32 key) { + require sanity(); + requireInvariant consistencyKey(key); + + uint256 lengthBefore = length(); + bool containsBefore = contains(key); + bytes32 valueBefore = tryGet_value(key); + + method f; + calldataarg args; + f(e, args); + + uint256 lengthAfter = length(); + bool containsAfter = contains(key); + bytes32 valueAfter = tryGet_value(key); + + assert lengthBefore != lengthAfter => ( + (f.selector == sig:set(bytes32,bytes32).selector && to_mathint(lengthAfter) == lengthBefore + 1) || + (f.selector == sig:remove(bytes32).selector && to_mathint(lengthAfter) == lengthBefore - 1) + ); + + assert containsBefore != containsAfter => ( + (f.selector == sig:set(bytes32,bytes32).selector && containsAfter) || + (f.selector == sig:remove(bytes32).selector && !containsAfter) + ); + + assert valueBefore != valueAfter => ( + (f.selector == sig:set(bytes32,bytes32).selector && containsAfter) || + (f.selector == sig:remove(bytes32).selector && !containsAfter && valueAfter == to_bytes32(0)) + ); +} + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Rule: check liveness of view functions. │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +rule liveness_1(bytes32 key) { + requireInvariant consistencyKey(key); + + // contains never revert + bool contains = contains@withrevert(key); + assert !lastReverted; + + // tryGet never reverts (key) + tryGet_contains@withrevert(key); + assert !lastReverted; + + // tryGet never reverts (value) + tryGet_value@withrevert(key); + assert !lastReverted; + + // get reverts iff the key is not in the map + get@withrevert(key); + assert !lastReverted <=> contains; +} + +rule liveness_2(uint256 index) { + requireInvariant consistencyIndex(index); + + // length never revert + uint256 length = length@withrevert(); + assert !lastReverted; + + // key_at reverts iff the index is out of bound + key_at@withrevert(index); + assert !lastReverted <=> index < length; + + // value_at reverts iff the index is out of bound + value_at@withrevert(index); + assert !lastReverted <=> index < length; +} + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Rule: get and tryGet return the expected values. │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +rule getAndTryGet(bytes32 key) { + requireInvariant noValueIfNotContained(key); + + bool contained = contains(key); + bool tryContained = tryGet_contains(key); + bytes32 tryValue = tryGet_value(key); + bytes32 value = get@withrevert(key); // revert is not contained + + assert contained == tryContained; + assert contained => tryValue == value; + assert !contained => tryValue == to_bytes32(0); +} + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Rule: set key-value in EnumerableMap │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +rule set(bytes32 key, bytes32 value, bytes32 otherKey) { + require sanity(); + + uint256 lengthBefore = length(); + bool containsBefore = contains(key); + bool containsOtherBefore = contains(otherKey); + bytes32 otherValueBefore = tryGet_value(otherKey); + + bool added = set@withrevert(key, value); + bool success = !lastReverted; + + assert success && contains(key) && get(key) == value, + "liveness & immediate effect"; + + assert added <=> !containsBefore, + "return value: added iff not contained"; + + assert to_mathint(length()) == lengthBefore + to_mathint(added ? 1 : 0), + "effect: length increases iff added"; + + assert added => (key_at(lengthBefore) == key && value_at(lengthBefore) == value), + "effect: add at the end"; + + assert containsOtherBefore != contains(otherKey) => (added && key == otherKey), + "side effect: other keys are not affected"; + + assert otherValueBefore != tryGet_value(otherKey) => key == otherKey, + "side effect: values attached to other keys are not affected"; +} + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Rule: remove key from EnumerableMap │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +rule remove(bytes32 key, bytes32 otherKey) { + requireInvariant consistencyKey(key); + requireInvariant consistencyKey(otherKey); + + uint256 lengthBefore = length(); + bool containsBefore = contains(key); + bool containsOtherBefore = contains(otherKey); + bytes32 otherValueBefore = tryGet_value(otherKey); + + bool removed = remove@withrevert(key); + bool success = !lastReverted; + + assert success && !contains(key), + "liveness & immediate effect"; + + assert removed <=> containsBefore, + "return value: removed iff contained"; + + assert to_mathint(length()) == lengthBefore - to_mathint(removed ? 1 : 0), + "effect: length decreases iff removed"; + + assert containsOtherBefore != contains(otherKey) => (removed && key == otherKey), + "side effect: other keys are not affected"; + + assert otherValueBefore != tryGet_value(otherKey) => key == otherKey, + "side effect: values attached to other keys are not affected"; +} + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Rule: when adding a new key, the other keys remain in set, at the same index. │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +rule setEnumerability(bytes32 key, bytes32 value, uint256 index) { + require sanity(); + + bytes32 atKeyBefore = key_at(index); + bytes32 atValueBefore = value_at(index); + + set(key, value); + + bytes32 atKeyAfter = key_at@withrevert(index); + assert !lastReverted; + + bytes32 atValueAfter = value_at@withrevert(index); + assert !lastReverted; + + assert atKeyAfter == atKeyBefore; + assert atValueAfter != atValueBefore => ( + key == atKeyBefore && + value == atValueAfter + ); +} + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Rule: when removing a existing key, the other keys remain in set, at the same index (except for the last one). │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +rule removeEnumerability(bytes32 key, uint256 index) { + uint256 last = require_uint256(length() - 1); + + requireInvariant consistencyKey(key); + requireInvariant consistencyIndex(index); + requireInvariant consistencyIndex(last); + + bytes32 atKeyBefore = key_at(index); + bytes32 atValueBefore = value_at(index); + bytes32 lastKeyBefore = key_at(last); + bytes32 lastValueBefore = value_at(last); + + remove(key); + + // can't read last value & keys (length decreased) + bytes32 atKeyAfter = key_at@withrevert(index); + assert lastReverted <=> index == last; + + bytes32 atValueAfter = value_at@withrevert(index); + assert lastReverted <=> index == last; + + // One value that is allowed to change is if previous value was removed, + // in that case the last value before took its place. + assert ( + index != last && + atKeyBefore != atKeyAfter + ) => ( + atKeyBefore == key && + atKeyAfter == lastKeyBefore + ); + + assert ( + index != last && + atValueBefore != atValueAfter + ) => ( + atValueAfter == lastValueBefore + ); +} diff --git a/certora/specs/EnumerableSet.spec b/certora/specs/EnumerableSet.spec new file mode 100644 index 000000000..3db515838 --- /dev/null +++ b/certora/specs/EnumerableSet.spec @@ -0,0 +1,246 @@ +import "helpers/helpers.spec"; + +methods { + // library + function add(bytes32) external returns (bool) envfree; + function remove(bytes32) external returns (bool) envfree; + function contains(bytes32) external returns (bool) envfree; + function length() external returns (uint256) envfree; + function at_(uint256) external returns (bytes32) envfree; + + // FV + function _indexOf(bytes32) external returns (uint256) envfree; +} + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Helpers │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +definition sanity() returns bool = + length() < max_uint256; + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Invariant: All indexed keys are contained │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +invariant indexedContained(uint256 index) + index < length() => contains(at_(index)) + { + preserved { + requireInvariant consistencyIndex(index); + requireInvariant consistencyIndex(require_uint256(length() - 1)); + } + } + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Invariant: A value can only be stored at a single location │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +invariant atUniqueness(uint256 index1, uint256 index2) + index1 == index2 <=> at_(index1) == at_(index2) + { + preserved remove(bytes32 key) { + requireInvariant atUniqueness(index1, require_uint256(length() - 1)); + requireInvariant atUniqueness(index2, require_uint256(length() - 1)); + } + } + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Invariant: index <> key relationship is consistent │ +│ │ +│ Note that the two consistencyXxx invariants, put together, prove that at_ and _indexOf are inverse of one another. │ +│ This proves that we have a bijection between indices (the enumerability part) and keys (the entries that are added │ +│ and removed from the EnumerableSet). │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +invariant consistencyIndex(uint256 index) + index < length() => _indexOf(at_(index)) == require_uint256(index + 1) + { + preserved remove(bytes32 key) { + requireInvariant consistencyIndex(require_uint256(length() - 1)); + } + } + +invariant consistencyKey(bytes32 key) + contains(key) => ( + _indexOf(key) > 0 && + _indexOf(key) <= length() && + at_(require_uint256(_indexOf(key) - 1)) == key + ) + { + preserved remove(bytes32 otherKey) { + requireInvariant consistencyKey(otherKey); + requireInvariant atUniqueness( + require_uint256(_indexOf(key) - 1), + require_uint256(_indexOf(otherKey) - 1) + ); + } + } + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Rule: state only changes by adding or removing elements │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +rule stateChange(env e, bytes32 key) { + require sanity(); + requireInvariant consistencyKey(key); + + uint256 lengthBefore = length(); + bool containsBefore = contains(key); + + method f; + calldataarg args; + f(e, args); + + uint256 lengthAfter = length(); + bool containsAfter = contains(key); + + assert lengthBefore != lengthAfter => ( + (f.selector == sig:add(bytes32).selector && lengthAfter == require_uint256(lengthBefore + 1)) || + (f.selector == sig:remove(bytes32).selector && lengthAfter == require_uint256(lengthBefore - 1)) + ); + + assert containsBefore != containsAfter => ( + (f.selector == sig:add(bytes32).selector && containsAfter) || + (f.selector == sig:remove(bytes32).selector && containsBefore) + ); +} + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Rule: check liveness of view functions. │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +rule liveness_1(bytes32 key) { + requireInvariant consistencyKey(key); + + // contains never revert + contains@withrevert(key); + assert !lastReverted; +} + +rule liveness_2(uint256 index) { + requireInvariant consistencyIndex(index); + + // length never revert + uint256 length = length@withrevert(); + assert !lastReverted; + + // at reverts iff the index is out of bound + at_@withrevert(index); + assert !lastReverted <=> index < length; +} + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Rule: add key to EnumerableSet if not already contained │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +rule add(bytes32 key, bytes32 otherKey) { + require sanity(); + + uint256 lengthBefore = length(); + bool containsBefore = contains(key); + bool containsOtherBefore = contains(otherKey); + + bool added = add@withrevert(key); + bool success = !lastReverted; + + assert success && contains(key), + "liveness & immediate effect"; + + assert added <=> !containsBefore, + "return value: added iff not contained"; + + assert length() == require_uint256(lengthBefore + to_mathint(added ? 1 : 0)), + "effect: length increases iff added"; + + assert added => at_(lengthBefore) == key, + "effect: add at the end"; + + assert containsOtherBefore != contains(otherKey) => (added && key == otherKey), + "side effect: other keys are not affected"; +} + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Rule: remove key from EnumerableSet if already contained │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +rule remove(bytes32 key, bytes32 otherKey) { + requireInvariant consistencyKey(key); + requireInvariant consistencyKey(otherKey); + + uint256 lengthBefore = length(); + bool containsBefore = contains(key); + bool containsOtherBefore = contains(otherKey); + + bool removed = remove@withrevert(key); + bool success = !lastReverted; + + assert success && !contains(key), + "liveness & immediate effect"; + + assert removed <=> containsBefore, + "return value: removed iff contained"; + + assert length() == require_uint256(lengthBefore - to_mathint(removed ? 1 : 0)), + "effect: length decreases iff removed"; + + assert containsOtherBefore != contains(otherKey) => (removed && key == otherKey), + "side effect: other keys are not affected"; +} + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Rule: when adding a new key, the other keys remain in set, at the same index. │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +rule addEnumerability(bytes32 key, uint256 index) { + require sanity(); + + bytes32 atBefore = at_(index); + add(key); + bytes32 atAfter = at_@withrevert(index); + bool atAfterSuccess = !lastReverted; + + assert atAfterSuccess; + assert atBefore == atAfter; +} + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Rule: when removing a existing key, the other keys remain in set, at the same index (except for the last one). │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +rule removeEnumerability(bytes32 key, uint256 index) { + uint256 last = require_uint256(length() - 1); + + requireInvariant consistencyKey(key); + requireInvariant consistencyIndex(index); + requireInvariant consistencyIndex(last); + + bytes32 atBefore = at_(index); + bytes32 lastBefore = at_(last); + + remove(key); + + // can't read last value (length decreased) + bytes32 atAfter = at_@withrevert(index); + assert lastReverted <=> index == last; + + // One value that is allowed to change is if previous value was removed, + // in that case the last value before took its place. + assert ( + index != last && + atBefore != atAfter + ) => ( + atBefore == key && + atAfter == lastBefore + ); +} diff --git a/certora/specs/Initializable.spec b/certora/specs/Initializable.spec new file mode 100644 index 000000000..07c2930c2 --- /dev/null +++ b/certora/specs/Initializable.spec @@ -0,0 +1,165 @@ +import "helpers/helpers.spec"; + +methods { + // initialize, reinitialize, disable + function initialize() external envfree; + function reinitialize(uint64) external envfree; + function disable() external envfree; + + function nested_init_init() external envfree; + function nested_init_reinit(uint64) external envfree; + function nested_reinit_init(uint64) external envfree; + function nested_reinit_reinit(uint64,uint64) external envfree; + + // view + function version() external returns uint64 envfree; + function initializing() external returns bool envfree; +} + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Definitions │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +definition isUninitialized() returns bool = version() == 0; +definition isInitialized() returns bool = version() > 0; +definition isDisabled() returns bool = version() == max_uint64; + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Invariant: A contract must only ever be in an initializing state while in the middle of a transaction execution. │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +invariant notInitializing() + !initializing(); + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Rule: The version cannot decrease & disable state is irrevocable. │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +rule increasingVersion(env e) { + uint64 versionBefore = version(); + bool disabledBefore = isDisabled(); + + method f; calldataarg args; + f(e, args); + + assert versionBefore <= version(), "_initialized must only increase"; + assert disabledBefore => isDisabled(), "a disabled initializer must stay disabled"; +} + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Rule: Cannot initialize a contract that is already initialized. │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +rule cannotInitializeTwice() { + require isInitialized(); + + initialize@withrevert(); + + assert lastReverted, "contract must only be initialized once"; +} + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Rule: Cannot initialize once disabled. │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +rule cannotInitializeOnceDisabled() { + require isDisabled(); + + initialize@withrevert(); + + assert lastReverted, "contract is disabled"; +} + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Rule: Cannot reinitialize once disabled. │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +rule cannotReinitializeOnceDisabled() { + require isDisabled(); + + uint64 n; + reinitialize@withrevert(n); + + assert lastReverted, "contract is disabled"; +} + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Rule: Cannot nest initializers (after construction). │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +rule cannotNestInitializers_init_init() { + nested_init_init@withrevert(); + assert lastReverted, "nested initializers"; +} + +rule cannotNestInitializers_init_reinit(uint64 m) { + nested_init_reinit@withrevert(m); + assert lastReverted, "nested initializers"; +} + +rule cannotNestInitializers_reinit_init(uint64 n) { + nested_reinit_init@withrevert(n); + assert lastReverted, "nested initializers"; +} + +rule cannotNestInitializers_reinit_reinit(uint64 n, uint64 m) { + nested_reinit_reinit@withrevert(n, m); + assert lastReverted, "nested initializers"; +} + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Rule: Initialize correctly sets the version. │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +rule initializeEffects() { + requireInvariant notInitializing(); + + bool isUninitializedBefore = isUninitialized(); + + initialize@withrevert(); + bool success = !lastReverted; + + assert success <=> isUninitializedBefore, "can only initialize uninitialized contracts"; + assert success => version() == 1, "initialize must set version() to 1"; +} + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Rule: Reinitialize correctly sets the version. │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +rule reinitializeEffects() { + requireInvariant notInitializing(); + + uint64 versionBefore = version(); + + uint64 n; + reinitialize@withrevert(n); + bool success = !lastReverted; + + assert success <=> versionBefore < n, "can only reinitialize to a latter versions"; + assert success => version() == n, "reinitialize must set version() to n"; +} + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Rule: Can disable. │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +rule disableEffect() { + requireInvariant notInitializing(); + + disable@withrevert(); + bool success = !lastReverted; + + assert success, "call to _disableInitializers failed"; + assert isDisabled(), "disable state not set"; +} diff --git a/certora/specs/Ownable.spec b/certora/specs/Ownable.spec new file mode 100644 index 000000000..0d50813cf --- /dev/null +++ b/certora/specs/Ownable.spec @@ -0,0 +1,77 @@ +import "helpers/helpers.spec"; +import "methods/IOwnable.spec"; + +methods { + function restricted() external; +} + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Function correctness: transferOwnership changes ownership │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +rule transferOwnership(env e) { + require nonpayable(e); + + address newOwner; + address current = owner(); + + transferOwnership@withrevert(e, newOwner); + bool success = !lastReverted; + + assert success <=> (e.msg.sender == current && newOwner != 0), "unauthorized caller or invalid arg"; + assert success => owner() == newOwner, "current owner changed"; +} + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Function correctness: renounceOwnership removes the owner │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +rule renounceOwnership(env e) { + require nonpayable(e); + + address current = owner(); + + renounceOwnership@withrevert(e); + bool success = !lastReverted; + + assert success <=> e.msg.sender == current, "unauthorized caller"; + assert success => owner() == 0, "owner not cleared"; +} + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Access control: only current owner can call restricted functions │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +rule onlyCurrentOwnerCanCallOnlyOwner(env e) { + require nonpayable(e); + + address current = owner(); + + calldataarg args; + restricted@withrevert(e, args); + + assert !lastReverted <=> e.msg.sender == current, "access control failed"; +} + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Rule: ownership can only change in specific ways │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +rule onlyOwnerOrPendingOwnerCanChangeOwnership(env e) { + address oldCurrent = owner(); + + method f; calldataarg args; + f(e, args); + + address newCurrent = owner(); + + // If owner changes, must be either transferOwnership or renounceOwnership + assert oldCurrent != newCurrent => ( + (e.msg.sender == oldCurrent && newCurrent != 0 && f.selector == sig:transferOwnership(address).selector) || + (e.msg.sender == oldCurrent && newCurrent == 0 && f.selector == sig:renounceOwnership().selector) + ); +} diff --git a/certora/specs/Ownable2Step.spec b/certora/specs/Ownable2Step.spec new file mode 100644 index 000000000..d13c6d3e6 --- /dev/null +++ b/certora/specs/Ownable2Step.spec @@ -0,0 +1,108 @@ +import "helpers/helpers.spec"; +import "methods/IOwnable2Step.spec"; + +methods { + function restricted() external; +} + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Function correctness: transferOwnership sets the pending owner │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +rule transferOwnership(env e) { + require nonpayable(e); + + address newOwner; + address current = owner(); + + transferOwnership@withrevert(e, newOwner); + bool success = !lastReverted; + + assert success <=> e.msg.sender == current, "unauthorized caller"; + assert success => pendingOwner() == newOwner, "pending owner not set"; + assert success => owner() == current, "current owner changed"; +} + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Function correctness: renounceOwnership removes the owner and the pendingOwner │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +rule renounceOwnership(env e) { + require nonpayable(e); + + address current = owner(); + + renounceOwnership@withrevert(e); + bool success = !lastReverted; + + assert success <=> e.msg.sender == current, "unauthorized caller"; + assert success => pendingOwner() == 0, "pending owner not cleared"; + assert success => owner() == 0, "owner not cleared"; +} + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Function correctness: acceptOwnership changes owner and reset pending owner │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +rule acceptOwnership(env e) { + + require nonpayable(e); + + address current = owner(); + address pending = pendingOwner(); + + acceptOwnership@withrevert(e); + bool success = !lastReverted; + + assert success <=> e.msg.sender == pending, "unauthorized caller"; + assert success => pendingOwner() == 0, "pending owner not cleared"; + assert success => owner() == pending, "owner not transferred"; +} + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Access control: only current owner can call restricted functions │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +rule onlyCurrentOwnerCanCallOnlyOwner(env e) { + require nonpayable(e); + + address current = owner(); + + calldataarg args; + restricted@withrevert(e, args); + + assert !lastReverted <=> e.msg.sender == current, "access control failed"; +} + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Rule: ownership and pending ownership can only change in specific ways │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +rule ownerOrPendingOwnerChange(env e, method f) { + address oldCurrent = owner(); + address oldPending = pendingOwner(); + + calldataarg args; + f(e, args); + + address newCurrent = owner(); + address newPending = pendingOwner(); + + // If owner changes, must be either acceptOwnership or renounceOwnership + assert oldCurrent != newCurrent => ( + (e.msg.sender == oldPending && newCurrent == oldPending && newPending == 0 && f.selector == sig:acceptOwnership().selector) || + (e.msg.sender == oldCurrent && newCurrent == 0 && newPending == 0 && f.selector == sig:renounceOwnership().selector) + ); + + // If pending changes, must be either acceptance or reset + assert oldPending != newPending => ( + (e.msg.sender == oldCurrent && newCurrent == oldCurrent && f.selector == sig:transferOwnership(address).selector) || + (e.msg.sender == oldPending && newCurrent == oldPending && newPending == 0 && f.selector == sig:acceptOwnership().selector) || + (e.msg.sender == oldCurrent && newCurrent == 0 && newPending == 0 && f.selector == sig:renounceOwnership().selector) + ); +} diff --git a/certora/specs/Pausable.spec b/certora/specs/Pausable.spec new file mode 100644 index 000000000..a7aff9cc1 --- /dev/null +++ b/certora/specs/Pausable.spec @@ -0,0 +1,96 @@ +import "helpers/helpers.spec"; + +methods { + function paused() external returns (bool) envfree; + function pause() external; + function unpause() external; + function onlyWhenPaused() external; + function onlyWhenNotPaused() external; +} + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Function correctness: _pause pauses the contract │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +rule pause(env e) { + require nonpayable(e); + + bool pausedBefore = paused(); + + pause@withrevert(e); + bool success = !lastReverted; + + bool pausedAfter = paused(); + + // liveness + assert success <=> !pausedBefore, "works if and only if the contract was not paused before"; + + // effect + assert success => pausedAfter, "contract must be paused after a successful call"; +} + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Function correctness: _unpause unpauses the contract │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +rule unpause(env e) { + require nonpayable(e); + + bool pausedBefore = paused(); + + unpause@withrevert(e); + bool success = !lastReverted; + + bool pausedAfter = paused(); + + // liveness + assert success <=> pausedBefore, "works if and only if the contract was paused before"; + + // effect + assert success => !pausedAfter, "contract must be unpaused after a successful call"; +} + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Function correctness: whenPaused modifier can only be called if the contract is paused │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +rule whenPaused(env e) { + require nonpayable(e); + + onlyWhenPaused@withrevert(e); + assert !lastReverted <=> paused(), "works if and only if the contract is paused"; +} + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Function correctness: whenNotPaused modifier can only be called if the contract is not paused │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +rule whenNotPaused(env e) { + require nonpayable(e); + + onlyWhenNotPaused@withrevert(e); + assert !lastReverted <=> !paused(), "works if and only if the contract is not paused"; +} + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Rules: only _pause and _unpause can change paused status │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +rule noPauseChange(env e) { + method f; + calldataarg args; + + bool pausedBefore = paused(); + f(e, args); + bool pausedAfter = paused(); + + assert pausedBefore != pausedAfter => ( + (!pausedAfter && f.selector == sig:unpause().selector) || + (pausedAfter && f.selector == sig:pause().selector) + ), "contract's paused status can only be changed by _pause() or _unpause()"; +} diff --git a/certora/specs/TimelockController.spec b/certora/specs/TimelockController.spec new file mode 100644 index 000000000..5123768da --- /dev/null +++ b/certora/specs/TimelockController.spec @@ -0,0 +1,274 @@ +import "helpers/helpers.spec"; +import "methods/IAccessControl.spec"; + +methods { + function PROPOSER_ROLE() external returns (bytes32) envfree; + function EXECUTOR_ROLE() external returns (bytes32) envfree; + function CANCELLER_ROLE() external returns (bytes32) envfree; + function isOperation(bytes32) external returns (bool); + function isOperationPending(bytes32) external returns (bool); + function isOperationReady(bytes32) external returns (bool); + function isOperationDone(bytes32) external returns (bool); + function getTimestamp(bytes32) external returns (uint256) envfree; + function getMinDelay() external returns (uint256) envfree; + + function hashOperation(address, uint256, bytes, bytes32, bytes32) external returns(bytes32) envfree; + function hashOperationBatch(address[], uint256[], bytes[], bytes32, bytes32) external returns(bytes32) envfree; + + function schedule(address, uint256, bytes, bytes32, bytes32, uint256) external; + function scheduleBatch(address[], uint256[], bytes[], bytes32, bytes32, uint256) external; + function execute(address, uint256, bytes, bytes32, bytes32) external; + function executeBatch(address[], uint256[], bytes[], bytes32, bytes32) external; + function cancel(bytes32) external; + + function updateDelay(uint256) external; +} + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Helpers │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +// Uniformly handle scheduling of batched and non-batched operations. +function helperScheduleWithRevert(env e, method f, bytes32 id, uint256 delay) { + if (f.selector == sig:schedule(address, uint256, bytes, bytes32, bytes32, uint256).selector) { + address target; uint256 value; bytes data; bytes32 predecessor; bytes32 salt; + require hashOperation(target, value, data, predecessor, salt) == id; // Correlation + schedule@withrevert(e, target, value, data, predecessor, salt, delay); + } else if (f.selector == sig:scheduleBatch(address[], uint256[], bytes[], bytes32, bytes32, uint256).selector) { + address[] targets; uint256[] values; bytes[] payloads; bytes32 predecessor; bytes32 salt; + require hashOperationBatch(targets, values, payloads, predecessor, salt) == id; // Correlation + scheduleBatch@withrevert(e, targets, values, payloads, predecessor, salt, delay); + } else { + calldataarg args; + f@withrevert(e, args); + } +} + +// Uniformly handle execution of batched and non-batched operations. +function helperExecuteWithRevert(env e, method f, bytes32 id, bytes32 predecessor) { + if (f.selector == sig:execute(address, uint256, bytes, bytes32, bytes32).selector) { + address target; uint256 value; bytes data; bytes32 salt; + require hashOperation(target, value, data, predecessor, salt) == id; // Correlation + execute@withrevert(e, target, value, data, predecessor, salt); + } else if (f.selector == sig:executeBatch(address[], uint256[], bytes[], bytes32, bytes32).selector) { + address[] targets; uint256[] values; bytes[] payloads; bytes32 salt; + require hashOperationBatch(targets, values, payloads, predecessor, salt) == id; // Correlation + executeBatch@withrevert(e, targets, values, payloads, predecessor, salt); + } else { + calldataarg args; + f@withrevert(e, args); + } +} + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Definitions │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +definition DONE_TIMESTAMP() returns uint256 = 1; +definition UNSET() returns uint8 = 0x1; +definition PENDING() returns uint8 = 0x2; +definition DONE() returns uint8 = 0x4; + +definition isUnset(env e, bytes32 id) returns bool = !isOperation(e, id); +definition isPending(env e, bytes32 id) returns bool = isOperationPending(e, id); +definition isDone(env e, bytes32 id) returns bool = isOperationDone(e, id); +definition state(env e, bytes32 id) returns uint8 = (isUnset(e, id) ? UNSET() : 0) | (isPending(e, id) ? PENDING() : 0) | (isDone(e, id) ? DONE() : 0); + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Invariants: consistency of accessors │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +invariant isOperationCheck(env e, bytes32 id) + isOperation(e, id) <=> getTimestamp(id) > 0 + filtered { f -> !f.isView } + +invariant isOperationPendingCheck(env e, bytes32 id) + isOperationPending(e, id) <=> getTimestamp(id) > DONE_TIMESTAMP() + filtered { f -> !f.isView } + +invariant isOperationDoneCheck(env e, bytes32 id) + isOperationDone(e, id) <=> getTimestamp(id) == DONE_TIMESTAMP() + filtered { f -> !f.isView } + +invariant isOperationReadyCheck(env e, bytes32 id) + isOperationReady(e, id) <=> (isOperationPending(e, id) && getTimestamp(id) <= e.block.timestamp) + filtered { f -> !f.isView } + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Invariant: a proposal id is either unset, pending or done │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +invariant stateConsistency(bytes32 id, env e) + // Check states are mutually exclusive + (isUnset(e, id) <=> (!isPending(e, id) && !isDone(e, id) )) && + (isPending(e, id) <=> (!isUnset(e, id) && !isDone(e, id) )) && + (isDone(e, id) <=> (!isUnset(e, id) && !isPending(e, id))) && + // Check that the state helper behaves as expected: + (isUnset(e, id) <=> state(e, id) == UNSET() ) && + (isPending(e, id) <=> state(e, id) == PENDING() ) && + (isDone(e, id) <=> state(e, id) == DONE() ) && + // Check substate + isOperationReady(e, id) => isPending(e, id) + filtered { f -> !f.isView } + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Rule: state transition rules │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +rule stateTransition(bytes32 id, env e, method f, calldataarg args) { + require e.block.timestamp > 1; // Sanity + + uint8 stateBefore = state(e, id); + f(e, args); + uint8 stateAfter = state(e, id); + + // Cannot jump from UNSET to DONE + assert stateBefore == UNSET() => stateAfter != DONE(); + + // UNSET → PENDING: schedule or scheduleBatch + assert stateBefore == UNSET() && stateAfter == PENDING() => ( + f.selector == sig:schedule(address, uint256, bytes, bytes32, bytes32, uint256).selector || + f.selector == sig:scheduleBatch(address[], uint256[], bytes[], bytes32, bytes32, uint256).selector + ); + + // PENDING → UNSET: cancel + assert stateBefore == PENDING() && stateAfter == UNSET() => ( + f.selector == sig:cancel(bytes32).selector + ); + + // PENDING → DONE: execute or executeBatch + assert stateBefore == PENDING() && stateAfter == DONE() => ( + f.selector == sig:execute(address, uint256, bytes, bytes32, bytes32).selector || + f.selector == sig:executeBatch(address[], uint256[], bytes[], bytes32, bytes32).selector + ); + + // DONE is final + assert stateBefore == DONE() => stateAfter == DONE(); +} + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Rule: minimum delay can only be updated through a timelock execution │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +rule minDelayOnlyChange(env e) { + uint256 delayBefore = getMinDelay(); + + method f; calldataarg args; + f(e, args); + + assert delayBefore != getMinDelay() => (e.msg.sender == currentContract && f.selector == sig:updateDelay(uint256).selector), "Unauthorized delay update"; +} + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Rule: schedule liveness and effects │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +rule schedule(env e, method f, bytes32 id, uint256 delay) filtered { f -> + f.selector == sig:schedule(address, uint256, bytes, bytes32, bytes32, uint256).selector || + f.selector == sig:scheduleBatch(address[], uint256[], bytes[], bytes32, bytes32, uint256).selector +} { + require nonpayable(e); + + // Basic timestamp assumptions + require e.block.timestamp > 1; + require e.block.timestamp + delay < max_uint256; + require e.block.timestamp + getMinDelay() < max_uint256; + + bytes32 otherId; uint256 otherTimestamp = getTimestamp(otherId); + + uint8 stateBefore = state(e, id); + bool isDelaySufficient = delay >= getMinDelay(); + bool isProposerBefore = hasRole(PROPOSER_ROLE(), e.msg.sender); + + helperScheduleWithRevert(e, f, id, delay); + bool success = !lastReverted; + + // liveness + assert success <=> ( + stateBefore == UNSET() && + isDelaySufficient && + isProposerBefore + ); + + // effect + assert success => state(e, id) == PENDING(), "State transition violation"; + assert success => getTimestamp(id) == require_uint256(e.block.timestamp + delay), "Proposal timestamp not correctly set"; + + // no side effect + assert otherTimestamp != getTimestamp(otherId) => id == otherId, "Other proposal affected"; +} + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Rule: execute liveness and effects │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +rule execute(env e, method f, bytes32 id, bytes32 predecessor) filtered { f -> + f.selector == sig:execute(address, uint256, bytes, bytes32, bytes32).selector || + f.selector == sig:executeBatch(address[], uint256[], bytes[], bytes32, bytes32).selector +} { + bytes32 otherId; uint256 otherTimestamp = getTimestamp(otherId); + + uint8 stateBefore = state(e, id); + bool isOperationReadyBefore = isOperationReady(e, id); + bool isExecutorOrOpen = hasRole(EXECUTOR_ROLE(), e.msg.sender) || hasRole(EXECUTOR_ROLE(), 0); + bool predecessorDependency = predecessor == to_bytes32(0) || isDone(e, predecessor); + + helperExecuteWithRevert(e, f, id, predecessor); + bool success = !lastReverted; + + // The underlying transaction can revert, and that would cause the execution to revert. We can check that all non + // reverting calls meet the requirements in terms of proposal readiness, access control and predecessor dependency. + // We can't however guarantee that these requirements being meet ensure liveness of the proposal, because the + // proposal can revert for reasons beyond our control. + + // liveness, should be `<=>` but can only check `=>` (see comment above) + assert success => ( + stateBefore == PENDING() && + isOperationReadyBefore && + predecessorDependency && + isExecutorOrOpen + ); + + // effect + assert success => state(e, id) == DONE(), "State transition violation"; + + // no side effect + assert otherTimestamp != getTimestamp(otherId) => id == otherId, "Other proposal affected"; +} + +/* +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Rule: cancel liveness and effects │ +└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +*/ +rule cancel(env e, bytes32 id) { + require nonpayable(e); + + bytes32 otherId; uint256 otherTimestamp = getTimestamp(otherId); + + uint8 stateBefore = state(e, id); + bool isCanceller = hasRole(CANCELLER_ROLE(), e.msg.sender); + + cancel@withrevert(e, id); + bool success = !lastReverted; + + // liveness + assert success <=> ( + stateBefore == PENDING() && + isCanceller + ); + + // effect + assert success => state(e, id) == UNSET(), "State transition violation"; + + // no side effect + assert otherTimestamp != getTimestamp(otherId) => id == otherId, "Other proposal affected"; +} diff --git a/certora/specs/helpers/helpers.spec b/certora/specs/helpers/helpers.spec new file mode 100644 index 000000000..a6c1e2302 --- /dev/null +++ b/certora/specs/helpers/helpers.spec @@ -0,0 +1,7 @@ +// environment +definition nonpayable(env e) returns bool = e.msg.value == 0; +definition nonzerosender(env e) returns bool = e.msg.sender != 0; + +// math +definition min(mathint a, mathint b) returns mathint = a < b ? a : b; +definition max(mathint a, mathint b) returns mathint = a > b ? a : b; diff --git a/certora/specs/methods/IAccessControl.spec b/certora/specs/methods/IAccessControl.spec new file mode 100644 index 000000000..5c395b088 --- /dev/null +++ b/certora/specs/methods/IAccessControl.spec @@ -0,0 +1,8 @@ +methods { + function DEFAULT_ADMIN_ROLE() external returns (bytes32) envfree; + function hasRole(bytes32, address) external returns(bool) envfree; + function getRoleAdmin(bytes32) external returns(bytes32) envfree; + function grantRole(bytes32, address) external; + function revokeRole(bytes32, address) external; + function renounceRole(bytes32, address) external; +} diff --git a/certora/specs/methods/IAccessControlDefaultAdminRules.spec b/certora/specs/methods/IAccessControlDefaultAdminRules.spec new file mode 100644 index 000000000..d02db180d --- /dev/null +++ b/certora/specs/methods/IAccessControlDefaultAdminRules.spec @@ -0,0 +1,36 @@ +import "./IERC5313.spec"; + +methods { + // === View == + + // Default Admin + function defaultAdmin() external returns(address) envfree; + function pendingDefaultAdmin() external returns(address, uint48) envfree; + + // Default Admin Delay + function defaultAdminDelay() external returns(uint48); + function pendingDefaultAdminDelay() external returns(uint48, uint48); + function defaultAdminDelayIncreaseWait() external returns(uint48) envfree; + + // === Mutations == + + // Default Admin + function beginDefaultAdminTransfer(address) external; + function cancelDefaultAdminTransfer() external; + function acceptDefaultAdminTransfer() external; + + // Default Admin Delay + function changeDefaultAdminDelay(uint48) external; + function rollbackDefaultAdminDelay() external; + + // == FV == + + // Default Admin + function pendingDefaultAdmin_() external returns (address) envfree; + function pendingDefaultAdminSchedule_() external returns (uint48) envfree; + + // Default Admin Delay + function pendingDelay_() external returns (uint48); + function pendingDelaySchedule_() external returns (uint48); + function delayChangeWait_(uint48) external returns (uint48); +} diff --git a/certora/specs/methods/IERC20.spec b/certora/specs/methods/IERC20.spec new file mode 100644 index 000000000..100901a04 --- /dev/null +++ b/certora/specs/methods/IERC20.spec @@ -0,0 +1,11 @@ +methods { + function name() external returns (string) envfree; + function symbol() external returns (string) envfree; + function decimals() external returns (uint8) envfree; + function totalSupply() external returns (uint256) envfree; + function balanceOf(address) external returns (uint256) envfree; + function allowance(address,address) external returns (uint256) envfree; + function approve(address,uint256) external returns (bool); + function transfer(address,uint256) external returns (bool); + function transferFrom(address,address,uint256) external returns (bool); +} diff --git a/certora/specs/methods/IERC2612.spec b/certora/specs/methods/IERC2612.spec new file mode 100644 index 000000000..4ecc17b49 --- /dev/null +++ b/certora/specs/methods/IERC2612.spec @@ -0,0 +1,5 @@ +methods { + function permit(address,address,uint256,uint256,uint8,bytes32,bytes32) external; + function nonces(address) external returns (uint256) envfree; + function DOMAIN_SEPARATOR() external returns (bytes32) envfree; +} diff --git a/certora/specs/methods/IERC3156FlashBorrower.spec b/certora/specs/methods/IERC3156FlashBorrower.spec new file mode 100644 index 000000000..733c168c7 --- /dev/null +++ b/certora/specs/methods/IERC3156FlashBorrower.spec @@ -0,0 +1,3 @@ +methods { + function _.onFlashLoan(address,address,uint256,uint256,bytes) external => DISPATCHER(true); +} diff --git a/certora/specs/methods/IERC3156FlashLender.spec b/certora/specs/methods/IERC3156FlashLender.spec new file mode 100644 index 000000000..66ed14cd1 --- /dev/null +++ b/certora/specs/methods/IERC3156FlashLender.spec @@ -0,0 +1,5 @@ +methods { + function maxFlashLoan(address) external returns (uint256) envfree; + function flashFee(address,uint256) external returns (uint256) envfree; + function flashLoan(address,address,uint256,bytes) external returns (bool); +} diff --git a/certora/specs/methods/IERC5313.spec b/certora/specs/methods/IERC5313.spec new file mode 100644 index 000000000..f1d469faf --- /dev/null +++ b/certora/specs/methods/IERC5313.spec @@ -0,0 +1,3 @@ +methods { + function owner() external returns (address) envfree; +} diff --git a/certora/specs/methods/IERC721.spec b/certora/specs/methods/IERC721.spec new file mode 100644 index 000000000..34ff50bd1 --- /dev/null +++ b/certora/specs/methods/IERC721.spec @@ -0,0 +1,17 @@ +methods { + // IERC721 + function balanceOf(address) external returns (uint256) envfree; + function ownerOf(uint256) external returns (address) envfree; + function getApproved(uint256) external returns (address) envfree; + function isApprovedForAll(address,address) external returns (bool) envfree; + function safeTransferFrom(address,address,uint256,bytes) external; + function safeTransferFrom(address,address,uint256) external; + function transferFrom(address,address,uint256) external; + function approve(address,uint256) external; + function setApprovalForAll(address,bool) external; + + // IERC721Metadata + function name() external returns (string); + function symbol() external returns (string); + function tokenURI(uint256) external returns (string); +} diff --git a/certora/specs/methods/IERC721Receiver.spec b/certora/specs/methods/IERC721Receiver.spec new file mode 100644 index 000000000..e6bdf4283 --- /dev/null +++ b/certora/specs/methods/IERC721Receiver.spec @@ -0,0 +1,3 @@ +methods { + function _.onERC721Received(address,address,uint256,bytes) external => DISPATCHER(true); +} diff --git a/certora/specs/methods/IOwnable.spec b/certora/specs/methods/IOwnable.spec new file mode 100644 index 000000000..4d7c925c5 --- /dev/null +++ b/certora/specs/methods/IOwnable.spec @@ -0,0 +1,5 @@ +methods { + function owner() external returns (address) envfree; + function transferOwnership(address) external; + function renounceOwnership() external; +} diff --git a/certora/specs/methods/IOwnable2Step.spec b/certora/specs/methods/IOwnable2Step.spec new file mode 100644 index 000000000..e6a99570a --- /dev/null +++ b/certora/specs/methods/IOwnable2Step.spec @@ -0,0 +1,7 @@ +methods { + function owner() external returns (address) envfree; + function pendingOwner() external returns (address) envfree; + function transferOwnership(address) external; + function acceptOwnership() external; + function renounceOwnership() external; +} diff --git a/contracts/access/AccessControl.sol b/contracts/access/AccessControl.sol new file mode 100644 index 000000000..47ce7d863 --- /dev/null +++ b/contracts/access/AccessControl.sol @@ -0,0 +1,209 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (access/AccessControl.sol) + +pragma solidity ^0.8.20; + +import {IAccessControl} from "./IAccessControl.sol"; +import {Context} from "../utils/Context.sol"; +import {ERC165} from "../utils/introspection/ERC165.sol"; + +/** + * @dev Contract module that allows children to implement role-based access + * control mechanisms. This is a lightweight version that doesn't allow enumerating role + * members except through off-chain means by accessing the contract event logs. Some + * applications may benefit from on-chain enumerability, for those cases see + * {AccessControlEnumerable}. + * + * Roles are referred to by their `bytes32` identifier. These should be exposed + * in the external API and be unique. The best way to achieve this is by + * using `public constant` hash digests: + * + * ```solidity + * bytes32 public constant MY_ROLE = keccak256("MY_ROLE"); + * ``` + * + * Roles can be used to represent a set of permissions. To restrict access to a + * function call, use {hasRole}: + * + * ```solidity + * function foo() public { + * require(hasRole(MY_ROLE, msg.sender)); + * ... + * } + * ``` + * + * Roles can be granted and revoked dynamically via the {grantRole} and + * {revokeRole} functions. Each role has an associated admin role, and only + * accounts that have a role's admin role can call {grantRole} and {revokeRole}. + * + * By default, the admin role for all roles is `DEFAULT_ADMIN_ROLE`, which means + * that only accounts with this role will be able to grant or revoke other + * roles. More complex role relationships can be created by using + * {_setRoleAdmin}. + * + * WARNING: The `DEFAULT_ADMIN_ROLE` is also its own admin: it has permission to + * grant and revoke this role. Extra precautions should be taken to secure + * accounts that have been granted it. We recommend using {AccessControlDefaultAdminRules} + * to enforce additional security measures for this role. + */ +abstract contract AccessControl is Context, IAccessControl, ERC165 { + struct RoleData { + mapping(address account => bool) hasRole; + bytes32 adminRole; + } + + mapping(bytes32 role => RoleData) private _roles; + + bytes32 public constant DEFAULT_ADMIN_ROLE = 0x00; + + /** + * @dev Modifier that checks that an account has a specific role. Reverts + * with an {AccessControlUnauthorizedAccount} error including the required role. + */ + modifier onlyRole(bytes32 role) { + _checkRole(role); + _; + } + + /** + * @dev See {IERC165-supportsInterface}. + */ + function supportsInterface(bytes4 interfaceId) public view virtual override returns (bool) { + return interfaceId == type(IAccessControl).interfaceId || super.supportsInterface(interfaceId); + } + + /** + * @dev Returns `true` if `account` has been granted `role`. + */ + function hasRole(bytes32 role, address account) public view virtual returns (bool) { + return _roles[role].hasRole[account]; + } + + /** + * @dev Reverts with an {AccessControlUnauthorizedAccount} error if `_msgSender()` + * is missing `role`. Overriding this function changes the behavior of the {onlyRole} modifier. + */ + function _checkRole(bytes32 role) internal view virtual { + _checkRole(role, _msgSender()); + } + + /** + * @dev Reverts with an {AccessControlUnauthorizedAccount} error if `account` + * is missing `role`. + */ + function _checkRole(bytes32 role, address account) internal view virtual { + if (!hasRole(role, account)) { + revert AccessControlUnauthorizedAccount(account, role); + } + } + + /** + * @dev Returns the admin role that controls `role`. See {grantRole} and + * {revokeRole}. + * + * To change a role's admin, use {_setRoleAdmin}. + */ + function getRoleAdmin(bytes32 role) public view virtual returns (bytes32) { + return _roles[role].adminRole; + } + + /** + * @dev Grants `role` to `account`. + * + * If `account` had not been already granted `role`, emits a {RoleGranted} + * event. + * + * Requirements: + * + * - the caller must have ``role``'s admin role. + * + * May emit a {RoleGranted} event. + */ + function grantRole(bytes32 role, address account) public virtual onlyRole(getRoleAdmin(role)) { + _grantRole(role, account); + } + + /** + * @dev Revokes `role` from `account`. + * + * If `account` had been granted `role`, emits a {RoleRevoked} event. + * + * Requirements: + * + * - the caller must have ``role``'s admin role. + * + * May emit a {RoleRevoked} event. + */ + function revokeRole(bytes32 role, address account) public virtual onlyRole(getRoleAdmin(role)) { + _revokeRole(role, account); + } + + /** + * @dev Revokes `role` from the calling account. + * + * Roles are often managed via {grantRole} and {revokeRole}: this function's + * purpose is to provide a mechanism for accounts to lose their privileges + * if they are compromised (such as when a trusted device is misplaced). + * + * If the calling account had been revoked `role`, emits a {RoleRevoked} + * event. + * + * Requirements: + * + * - the caller must be `callerConfirmation`. + * + * May emit a {RoleRevoked} event. + */ + function renounceRole(bytes32 role, address callerConfirmation) public virtual { + if (callerConfirmation != _msgSender()) { + revert AccessControlBadConfirmation(); + } + + _revokeRole(role, callerConfirmation); + } + + /** + * @dev Sets `adminRole` as ``role``'s admin role. + * + * Emits a {RoleAdminChanged} event. + */ + function _setRoleAdmin(bytes32 role, bytes32 adminRole) internal virtual { + bytes32 previousAdminRole = getRoleAdmin(role); + _roles[role].adminRole = adminRole; + emit RoleAdminChanged(role, previousAdminRole, adminRole); + } + + /** + * @dev Attempts to grant `role` to `account` and returns a boolean indicating if `role` was granted. + * + * Internal function without access restriction. + * + * May emit a {RoleGranted} event. + */ + function _grantRole(bytes32 role, address account) internal virtual returns (bool) { + if (!hasRole(role, account)) { + _roles[role].hasRole[account] = true; + emit RoleGranted(role, account, _msgSender()); + return true; + } else { + return false; + } + } + + /** + * @dev Attempts to revoke `role` to `account` and returns a boolean indicating if `role` was revoked. + * + * Internal function without access restriction. + * + * May emit a {RoleRevoked} event. + */ + function _revokeRole(bytes32 role, address account) internal virtual returns (bool) { + if (hasRole(role, account)) { + _roles[role].hasRole[account] = false; + emit RoleRevoked(role, account, _msgSender()); + return true; + } else { + return false; + } + } +} diff --git a/contracts/access/IAccessControl.sol b/contracts/access/IAccessControl.sol new file mode 100644 index 000000000..35c5ff519 --- /dev/null +++ b/contracts/access/IAccessControl.sol @@ -0,0 +1,98 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (access/IAccessControl.sol) + +pragma solidity ^0.8.20; + +/** + * @dev External interface of AccessControl declared to support ERC165 detection. + */ +interface IAccessControl { + /** + * @dev The `account` is missing a role. + */ + error AccessControlUnauthorizedAccount(address account, bytes32 neededRole); + + /** + * @dev The caller of a function is not the expected one. + * + * NOTE: Don't confuse with {AccessControlUnauthorizedAccount}. + */ + error AccessControlBadConfirmation(); + + /** + * @dev Emitted when `newAdminRole` is set as ``role``'s admin role, replacing `previousAdminRole` + * + * `DEFAULT_ADMIN_ROLE` is the starting admin for all roles, despite + * {RoleAdminChanged} not being emitted signaling this. + */ + event RoleAdminChanged(bytes32 indexed role, bytes32 indexed previousAdminRole, bytes32 indexed newAdminRole); + + /** + * @dev Emitted when `account` is granted `role`. + * + * `sender` is the account that originated the contract call, an admin role + * bearer except when using {AccessControl-_setupRole}. + */ + event RoleGranted(bytes32 indexed role, address indexed account, address indexed sender); + + /** + * @dev Emitted when `account` is revoked `role`. + * + * `sender` is the account that originated the contract call: + * - if using `revokeRole`, it is the admin role bearer + * - if using `renounceRole`, it is the role bearer (i.e. `account`) + */ + event RoleRevoked(bytes32 indexed role, address indexed account, address indexed sender); + + /** + * @dev Returns `true` if `account` has been granted `role`. + */ + function hasRole(bytes32 role, address account) external view returns (bool); + + /** + * @dev Returns the admin role that controls `role`. See {grantRole} and + * {revokeRole}. + * + * To change a role's admin, use {AccessControl-_setRoleAdmin}. + */ + function getRoleAdmin(bytes32 role) external view returns (bytes32); + + /** + * @dev Grants `role` to `account`. + * + * If `account` had not been already granted `role`, emits a {RoleGranted} + * event. + * + * Requirements: + * + * - the caller must have ``role``'s admin role. + */ + function grantRole(bytes32 role, address account) external; + + /** + * @dev Revokes `role` from `account`. + * + * If `account` had been granted `role`, emits a {RoleRevoked} event. + * + * Requirements: + * + * - the caller must have ``role``'s admin role. + */ + function revokeRole(bytes32 role, address account) external; + + /** + * @dev Revokes `role` from the calling account. + * + * Roles are often managed via {grantRole} and {revokeRole}: this function's + * purpose is to provide a mechanism for accounts to lose their privileges + * if they are compromised (such as when a trusted device is misplaced). + * + * If the calling account had been granted `role`, emits a {RoleRevoked} + * event. + * + * Requirements: + * + * - the caller must be `callerConfirmation`. + */ + function renounceRole(bytes32 role, address callerConfirmation) external; +} diff --git a/contracts/access/Ownable.sol b/contracts/access/Ownable.sol new file mode 100644 index 000000000..6738b7297 --- /dev/null +++ b/contracts/access/Ownable.sol @@ -0,0 +1,100 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (access/Ownable.sol) + +pragma solidity ^0.8.20; + +import {Context} from "../utils/Context.sol"; + +/** + * @dev Contract module which provides a basic access control mechanism, where + * there is an account (an owner) that can be granted exclusive access to + * specific functions. + * + * The initial owner is set to the address provided by the deployer. This can + * later be changed with {transferOwnership}. + * + * This module is used through inheritance. It will make available the modifier + * `onlyOwner`, which can be applied to your functions to restrict their use to + * the owner. + */ +abstract contract Ownable is Context { + address private _owner; + + /** + * @dev The caller account is not authorized to perform an operation. + */ + error OwnableUnauthorizedAccount(address account); + + /** + * @dev The owner is not a valid owner account. (eg. `address(0)`) + */ + error OwnableInvalidOwner(address owner); + + event OwnershipTransferred(address indexed previousOwner, address indexed newOwner); + + /** + * @dev Initializes the contract setting the address provided by the deployer as the initial owner. + */ + constructor(address initialOwner) { + if (initialOwner == address(0)) { + revert OwnableInvalidOwner(address(0)); + } + _transferOwnership(initialOwner); + } + + /** + * @dev Throws if called by any account other than the owner. + */ + modifier onlyOwner() { + _checkOwner(); + _; + } + + /** + * @dev Returns the address of the current owner. + */ + function owner() public view virtual returns (address) { + return _owner; + } + + /** + * @dev Throws if the sender is not the owner. + */ + function _checkOwner() internal view virtual { + if (owner() != _msgSender()) { + revert OwnableUnauthorizedAccount(_msgSender()); + } + } + + /** + * @dev Leaves the contract without owner. It will not be possible to call + * `onlyOwner` functions. Can only be called by the current owner. + * + * NOTE: Renouncing ownership will leave the contract without an owner, + * thereby disabling any functionality that is only available to the owner. + */ + function renounceOwnership() public virtual onlyOwner { + _transferOwnership(address(0)); + } + + /** + * @dev Transfers ownership of the contract to a new account (`newOwner`). + * Can only be called by the current owner. + */ + function transferOwnership(address newOwner) public virtual onlyOwner { + if (newOwner == address(0)) { + revert OwnableInvalidOwner(address(0)); + } + _transferOwnership(newOwner); + } + + /** + * @dev Transfers ownership of the contract to a new account (`newOwner`). + * Internal function without access restriction. + */ + function _transferOwnership(address newOwner) internal virtual { + address oldOwner = _owner; + _owner = newOwner; + emit OwnershipTransferred(oldOwner, newOwner); + } +} diff --git a/contracts/access/Ownable2Step.sol b/contracts/access/Ownable2Step.sol new file mode 100644 index 000000000..90ad840cc --- /dev/null +++ b/contracts/access/Ownable2Step.sol @@ -0,0 +1,59 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (access/Ownable2Step.sol) + +pragma solidity ^0.8.20; + +import {Ownable} from "./Ownable.sol"; + +/** + * @dev Contract module which provides access control mechanism, where + * there is an account (an owner) that can be granted exclusive access to + * specific functions. + * + * The initial owner is specified at deployment time in the constructor for `Ownable`. This + * can later be changed with {transferOwnership} and {acceptOwnership}. + * + * This module is used through inheritance. It will make available all functions + * from parent (Ownable). + */ +abstract contract Ownable2Step is Ownable { + address private _pendingOwner; + + event OwnershipTransferStarted(address indexed previousOwner, address indexed newOwner); + + /** + * @dev Returns the address of the pending owner. + */ + function pendingOwner() public view virtual returns (address) { + return _pendingOwner; + } + + /** + * @dev Starts the ownership transfer of the contract to a new account. Replaces the pending transfer if there is one. + * Can only be called by the current owner. + */ + function transferOwnership(address newOwner) public virtual override onlyOwner { + _pendingOwner = newOwner; + emit OwnershipTransferStarted(owner(), newOwner); + } + + /** + * @dev Transfers ownership of the contract to a new account (`newOwner`) and deletes any pending owner. + * Internal function without access restriction. + */ + function _transferOwnership(address newOwner) internal virtual override { + delete _pendingOwner; + super._transferOwnership(newOwner); + } + + /** + * @dev The new owner accepts the ownership transfer. + */ + function acceptOwnership() public virtual { + address sender = _msgSender(); + if (pendingOwner() != sender) { + revert OwnableUnauthorizedAccount(sender); + } + _transferOwnership(sender); + } +} diff --git a/contracts/access/README.adoc b/contracts/access/README.adoc new file mode 100644 index 000000000..c40b8dbee --- /dev/null +++ b/contracts/access/README.adoc @@ -0,0 +1,39 @@ += Access Control + +[.readme-notice] +NOTE: This document is better viewed at https://docs.openzeppelin.com/contracts/api/access + +This directory provides ways to restrict who can access the functions of a contract or when they can do it. + +- {AccessControl} provides a general role based access control mechanism. Multiple hierarchical roles can be created and assigned each to multiple accounts. +- {Ownable} is a simpler mechanism with a single owner "role" that can be assigned to a single account. This simpler mechanism can be useful for quick tests but projects with production concerns are likely to outgrow it. + +== Core + +{{Ownable}} + +{{Ownable2Step}} + +{{IAccessControl}} + +{{AccessControl}} + +== Extensions + +{{IAccessControlEnumerable}} + +{{AccessControlEnumerable}} + +{{IAccessControlDefaultAdminRules}} + +{{AccessControlDefaultAdminRules}} + +== AccessManager + +{{IAuthority}} + +{{AccessManager}} + +{{AccessManaged}} + +{{AccessManagerAdapter}} diff --git a/contracts/access/extensions/AccessControlDefaultAdminRules.sol b/contracts/access/extensions/AccessControlDefaultAdminRules.sol new file mode 100644 index 000000000..f0f63bd23 --- /dev/null +++ b/contracts/access/extensions/AccessControlDefaultAdminRules.sol @@ -0,0 +1,396 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (access/extensions/AccessControlDefaultAdminRules.sol) + +pragma solidity ^0.8.20; + +import {IAccessControlDefaultAdminRules} from "./IAccessControlDefaultAdminRules.sol"; +import {AccessControl, IAccessControl} from "../AccessControl.sol"; +import {SafeCast} from "../../utils/math/SafeCast.sol"; +import {Math} from "../../utils/math/Math.sol"; +import {IERC5313} from "../../interfaces/IERC5313.sol"; + +/** + * @dev Extension of {AccessControl} that allows specifying special rules to manage + * the `DEFAULT_ADMIN_ROLE` holder, which is a sensitive role with special permissions + * over other roles that may potentially have privileged rights in the system. + * + * If a specific role doesn't have an admin role assigned, the holder of the + * `DEFAULT_ADMIN_ROLE` will have the ability to grant it and revoke it. + * + * This contract implements the following risk mitigations on top of {AccessControl}: + * + * * Only one account holds the `DEFAULT_ADMIN_ROLE` since deployment until it's potentially renounced. + * * Enforces a 2-step process to transfer the `DEFAULT_ADMIN_ROLE` to another account. + * * Enforces a configurable delay between the two steps, with the ability to cancel before the transfer is accepted. + * * The delay can be changed by scheduling, see {changeDefaultAdminDelay}. + * * It is not possible to use another role to manage the `DEFAULT_ADMIN_ROLE`. + * + * Example usage: + * + * ```solidity + * contract MyToken is AccessControlDefaultAdminRules { + * constructor() AccessControlDefaultAdminRules( + * 3 days, + * msg.sender // Explicit initial `DEFAULT_ADMIN_ROLE` holder + * ) {} + * } + * ``` + */ +abstract contract AccessControlDefaultAdminRules is IAccessControlDefaultAdminRules, IERC5313, AccessControl { + // pending admin pair read/written together frequently + address private _pendingDefaultAdmin; + uint48 private _pendingDefaultAdminSchedule; // 0 == unset + + uint48 private _currentDelay; + address private _currentDefaultAdmin; + + // pending delay pair read/written together frequently + uint48 private _pendingDelay; + uint48 private _pendingDelaySchedule; // 0 == unset + + /** + * @dev Sets the initial values for {defaultAdminDelay} and {defaultAdmin} address. + */ + constructor(uint48 initialDelay, address initialDefaultAdmin) { + if (initialDefaultAdmin == address(0)) { + revert AccessControlInvalidDefaultAdmin(address(0)); + } + _currentDelay = initialDelay; + _grantRole(DEFAULT_ADMIN_ROLE, initialDefaultAdmin); + } + + /** + * @dev See {IERC165-supportsInterface}. + */ + function supportsInterface(bytes4 interfaceId) public view virtual override returns (bool) { + return interfaceId == type(IAccessControlDefaultAdminRules).interfaceId || super.supportsInterface(interfaceId); + } + + /** + * @dev See {IERC5313-owner}. + */ + function owner() public view virtual returns (address) { + return defaultAdmin(); + } + + /// + /// Override AccessControl role management + /// + + /** + * @dev See {AccessControl-grantRole}. Reverts for `DEFAULT_ADMIN_ROLE`. + */ + function grantRole(bytes32 role, address account) public virtual override(AccessControl, IAccessControl) { + if (role == DEFAULT_ADMIN_ROLE) { + revert AccessControlEnforcedDefaultAdminRules(); + } + super.grantRole(role, account); + } + + /** + * @dev See {AccessControl-revokeRole}. Reverts for `DEFAULT_ADMIN_ROLE`. + */ + function revokeRole(bytes32 role, address account) public virtual override(AccessControl, IAccessControl) { + if (role == DEFAULT_ADMIN_ROLE) { + revert AccessControlEnforcedDefaultAdminRules(); + } + super.revokeRole(role, account); + } + + /** + * @dev See {AccessControl-renounceRole}. + * + * For the `DEFAULT_ADMIN_ROLE`, it only allows renouncing in two steps by first calling + * {beginDefaultAdminTransfer} to the `address(0)`, so it's required that the {pendingDefaultAdmin} schedule + * has also passed when calling this function. + * + * After its execution, it will not be possible to call `onlyRole(DEFAULT_ADMIN_ROLE)` functions. + * + * NOTE: Renouncing `DEFAULT_ADMIN_ROLE` will leave the contract without a {defaultAdmin}, + * thereby disabling any functionality that is only available for it, and the possibility of reassigning a + * non-administrated role. + */ + function renounceRole(bytes32 role, address account) public virtual override(AccessControl, IAccessControl) { + if (role == DEFAULT_ADMIN_ROLE && account == defaultAdmin()) { + (address newDefaultAdmin, uint48 schedule) = pendingDefaultAdmin(); + if (newDefaultAdmin != address(0) || !_isScheduleSet(schedule) || !_hasSchedulePassed(schedule)) { + revert AccessControlEnforcedDefaultAdminDelay(schedule); + } + delete _pendingDefaultAdminSchedule; + } + super.renounceRole(role, account); + } + + /** + * @dev See {AccessControl-_grantRole}. + * + * For `DEFAULT_ADMIN_ROLE`, it only allows granting if there isn't already a {defaultAdmin} or if the + * role has been previously renounced. + * + * NOTE: Exposing this function through another mechanism may make the `DEFAULT_ADMIN_ROLE` + * assignable again. Make sure to guarantee this is the expected behavior in your implementation. + */ + function _grantRole(bytes32 role, address account) internal virtual override returns (bool) { + if (role == DEFAULT_ADMIN_ROLE) { + if (defaultAdmin() != address(0)) { + revert AccessControlEnforcedDefaultAdminRules(); + } + _currentDefaultAdmin = account; + } + return super._grantRole(role, account); + } + + /** + * @dev See {AccessControl-_revokeRole}. + */ + function _revokeRole(bytes32 role, address account) internal virtual override returns (bool) { + if (role == DEFAULT_ADMIN_ROLE && account == defaultAdmin()) { + delete _currentDefaultAdmin; + } + return super._revokeRole(role, account); + } + + /** + * @dev See {AccessControl-_setRoleAdmin}. Reverts for `DEFAULT_ADMIN_ROLE`. + */ + function _setRoleAdmin(bytes32 role, bytes32 adminRole) internal virtual override { + if (role == DEFAULT_ADMIN_ROLE) { + revert AccessControlEnforcedDefaultAdminRules(); + } + super._setRoleAdmin(role, adminRole); + } + + /// + /// AccessControlDefaultAdminRules accessors + /// + + /** + * @inheritdoc IAccessControlDefaultAdminRules + */ + function defaultAdmin() public view virtual returns (address) { + return _currentDefaultAdmin; + } + + /** + * @inheritdoc IAccessControlDefaultAdminRules + */ + function pendingDefaultAdmin() public view virtual returns (address newAdmin, uint48 schedule) { + return (_pendingDefaultAdmin, _pendingDefaultAdminSchedule); + } + + /** + * @inheritdoc IAccessControlDefaultAdminRules + */ + function defaultAdminDelay() public view virtual returns (uint48) { + uint48 schedule = _pendingDelaySchedule; + return (_isScheduleSet(schedule) && _hasSchedulePassed(schedule)) ? _pendingDelay : _currentDelay; + } + + /** + * @inheritdoc IAccessControlDefaultAdminRules + */ + function pendingDefaultAdminDelay() public view virtual returns (uint48 newDelay, uint48 schedule) { + schedule = _pendingDelaySchedule; + return (_isScheduleSet(schedule) && !_hasSchedulePassed(schedule)) ? (_pendingDelay, schedule) : (0, 0); + } + + /** + * @inheritdoc IAccessControlDefaultAdminRules + */ + function defaultAdminDelayIncreaseWait() public view virtual returns (uint48) { + return 5 days; + } + + /// + /// AccessControlDefaultAdminRules public and internal setters for defaultAdmin/pendingDefaultAdmin + /// + + /** + * @inheritdoc IAccessControlDefaultAdminRules + */ + function beginDefaultAdminTransfer(address newAdmin) public virtual onlyRole(DEFAULT_ADMIN_ROLE) { + _beginDefaultAdminTransfer(newAdmin); + } + + /** + * @dev See {beginDefaultAdminTransfer}. + * + * Internal function without access restriction. + */ + function _beginDefaultAdminTransfer(address newAdmin) internal virtual { + uint48 newSchedule = SafeCast.toUint48(block.timestamp) + defaultAdminDelay(); + _setPendingDefaultAdmin(newAdmin, newSchedule); + emit DefaultAdminTransferScheduled(newAdmin, newSchedule); + } + + /** + * @inheritdoc IAccessControlDefaultAdminRules + */ + function cancelDefaultAdminTransfer() public virtual onlyRole(DEFAULT_ADMIN_ROLE) { + _cancelDefaultAdminTransfer(); + } + + /** + * @dev See {cancelDefaultAdminTransfer}. + * + * Internal function without access restriction. + */ + function _cancelDefaultAdminTransfer() internal virtual { + _setPendingDefaultAdmin(address(0), 0); + } + + /** + * @inheritdoc IAccessControlDefaultAdminRules + */ + function acceptDefaultAdminTransfer() public virtual { + (address newDefaultAdmin, ) = pendingDefaultAdmin(); + if (_msgSender() != newDefaultAdmin) { + // Enforce newDefaultAdmin explicit acceptance. + revert AccessControlInvalidDefaultAdmin(_msgSender()); + } + _acceptDefaultAdminTransfer(); + } + + /** + * @dev See {acceptDefaultAdminTransfer}. + * + * Internal function without access restriction. + */ + function _acceptDefaultAdminTransfer() internal virtual { + (address newAdmin, uint48 schedule) = pendingDefaultAdmin(); + if (!_isScheduleSet(schedule) || !_hasSchedulePassed(schedule)) { + revert AccessControlEnforcedDefaultAdminDelay(schedule); + } + _revokeRole(DEFAULT_ADMIN_ROLE, defaultAdmin()); + _grantRole(DEFAULT_ADMIN_ROLE, newAdmin); + delete _pendingDefaultAdmin; + delete _pendingDefaultAdminSchedule; + } + + /// + /// AccessControlDefaultAdminRules public and internal setters for defaultAdminDelay/pendingDefaultAdminDelay + /// + + /** + * @inheritdoc IAccessControlDefaultAdminRules + */ + function changeDefaultAdminDelay(uint48 newDelay) public virtual onlyRole(DEFAULT_ADMIN_ROLE) { + _changeDefaultAdminDelay(newDelay); + } + + /** + * @dev See {changeDefaultAdminDelay}. + * + * Internal function without access restriction. + */ + function _changeDefaultAdminDelay(uint48 newDelay) internal virtual { + uint48 newSchedule = SafeCast.toUint48(block.timestamp) + _delayChangeWait(newDelay); + _setPendingDelay(newDelay, newSchedule); + emit DefaultAdminDelayChangeScheduled(newDelay, newSchedule); + } + + /** + * @inheritdoc IAccessControlDefaultAdminRules + */ + function rollbackDefaultAdminDelay() public virtual onlyRole(DEFAULT_ADMIN_ROLE) { + _rollbackDefaultAdminDelay(); + } + + /** + * @dev See {rollbackDefaultAdminDelay}. + * + * Internal function without access restriction. + */ + function _rollbackDefaultAdminDelay() internal virtual { + _setPendingDelay(0, 0); + } + + /** + * @dev Returns the amount of seconds to wait after the `newDelay` will + * become the new {defaultAdminDelay}. + * + * The value returned guarantees that if the delay is reduced, it will go into effect + * after a wait that honors the previously set delay. + * + * See {defaultAdminDelayIncreaseWait}. + */ + function _delayChangeWait(uint48 newDelay) internal view virtual returns (uint48) { + uint48 currentDelay = defaultAdminDelay(); + + // When increasing the delay, we schedule the delay change to occur after a period of "new delay" has passed, up + // to a maximum given by defaultAdminDelayIncreaseWait, by default 5 days. For example, if increasing from 1 day + // to 3 days, the new delay will come into effect after 3 days. If increasing from 1 day to 10 days, the new + // delay will come into effect after 5 days. The 5 day wait period is intended to be able to fix an error like + // using milliseconds instead of seconds. + // + // When decreasing the delay, we wait the difference between "current delay" and "new delay". This guarantees + // that an admin transfer cannot be made faster than "current delay" at the time the delay change is scheduled. + // For example, if decreasing from 10 days to 3 days, the new delay will come into effect after 7 days. + return + newDelay > currentDelay + ? uint48(Math.min(newDelay, defaultAdminDelayIncreaseWait())) // no need to safecast, both inputs are uint48 + : currentDelay - newDelay; + } + + /// + /// Private setters + /// + + /** + * @dev Setter of the tuple for pending admin and its schedule. + * + * May emit a DefaultAdminTransferCanceled event. + */ + function _setPendingDefaultAdmin(address newAdmin, uint48 newSchedule) private { + (, uint48 oldSchedule) = pendingDefaultAdmin(); + + _pendingDefaultAdmin = newAdmin; + _pendingDefaultAdminSchedule = newSchedule; + + // An `oldSchedule` from `pendingDefaultAdmin()` is only set if it hasn't been accepted. + if (_isScheduleSet(oldSchedule)) { + // Emit for implicit cancellations when another default admin was scheduled. + emit DefaultAdminTransferCanceled(); + } + } + + /** + * @dev Setter of the tuple for pending delay and its schedule. + * + * May emit a DefaultAdminDelayChangeCanceled event. + */ + function _setPendingDelay(uint48 newDelay, uint48 newSchedule) private { + uint48 oldSchedule = _pendingDelaySchedule; + + if (_isScheduleSet(oldSchedule)) { + if (_hasSchedulePassed(oldSchedule)) { + // Materialize a virtual delay + _currentDelay = _pendingDelay; + } else { + // Emit for implicit cancellations when another delay was scheduled. + emit DefaultAdminDelayChangeCanceled(); + } + } + + _pendingDelay = newDelay; + _pendingDelaySchedule = newSchedule; + } + + /// + /// Private helpers + /// + + /** + * @dev Defines if an `schedule` is considered set. For consistency purposes. + */ + function _isScheduleSet(uint48 schedule) private pure returns (bool) { + return schedule != 0; + } + + /** + * @dev Defines if an `schedule` is considered passed. For consistency purposes. + */ + function _hasSchedulePassed(uint48 schedule) private view returns (bool) { + return schedule < block.timestamp; + } +} diff --git a/contracts/access/extensions/AccessControlEnumerable.sol b/contracts/access/extensions/AccessControlEnumerable.sol new file mode 100644 index 000000000..39ab221c4 --- /dev/null +++ b/contracts/access/extensions/AccessControlEnumerable.sol @@ -0,0 +1,70 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (access/extensions/AccessControlEnumerable.sol) + +pragma solidity ^0.8.20; + +import {IAccessControlEnumerable} from "./IAccessControlEnumerable.sol"; +import {AccessControl} from "../AccessControl.sol"; +import {EnumerableSet} from "../../utils/structs/EnumerableSet.sol"; + +/** + * @dev Extension of {AccessControl} that allows enumerating the members of each role. + */ +abstract contract AccessControlEnumerable is IAccessControlEnumerable, AccessControl { + using EnumerableSet for EnumerableSet.AddressSet; + + mapping(bytes32 role => EnumerableSet.AddressSet) private _roleMembers; + + /** + * @dev See {IERC165-supportsInterface}. + */ + function supportsInterface(bytes4 interfaceId) public view virtual override returns (bool) { + return interfaceId == type(IAccessControlEnumerable).interfaceId || super.supportsInterface(interfaceId); + } + + /** + * @dev Returns one of the accounts that have `role`. `index` must be a + * value between 0 and {getRoleMemberCount}, non-inclusive. + * + * Role bearers are not sorted in any particular way, and their ordering may + * change at any point. + * + * WARNING: When using {getRoleMember} and {getRoleMemberCount}, make sure + * you perform all queries on the same block. See the following + * https://forum.openzeppelin.com/t/iterating-over-elements-on-enumerableset-in-openzeppelin-contracts/2296[forum post] + * for more information. + */ + function getRoleMember(bytes32 role, uint256 index) public view virtual returns (address) { + return _roleMembers[role].at(index); + } + + /** + * @dev Returns the number of accounts that have `role`. Can be used + * together with {getRoleMember} to enumerate all bearers of a role. + */ + function getRoleMemberCount(bytes32 role) public view virtual returns (uint256) { + return _roleMembers[role].length(); + } + + /** + * @dev Overload {AccessControl-_grantRole} to track enumerable memberships + */ + function _grantRole(bytes32 role, address account) internal virtual override returns (bool) { + bool granted = super._grantRole(role, account); + if (granted) { + _roleMembers[role].add(account); + } + return granted; + } + + /** + * @dev Overload {AccessControl-_revokeRole} to track enumerable memberships + */ + function _revokeRole(bytes32 role, address account) internal virtual override returns (bool) { + bool revoked = super._revokeRole(role, account); + if (revoked) { + _roleMembers[role].remove(account); + } + return revoked; + } +} diff --git a/contracts/access/extensions/IAccessControlDefaultAdminRules.sol b/contracts/access/extensions/IAccessControlDefaultAdminRules.sol new file mode 100644 index 000000000..b2c6fc831 --- /dev/null +++ b/contracts/access/extensions/IAccessControlDefaultAdminRules.sol @@ -0,0 +1,192 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (access/extensions/IAccessControlDefaultAdminRules.sol) + +pragma solidity ^0.8.20; + +import {IAccessControl} from "../IAccessControl.sol"; + +/** + * @dev External interface of AccessControlDefaultAdminRules declared to support ERC165 detection. + */ +interface IAccessControlDefaultAdminRules is IAccessControl { + /** + * @dev The new default admin is not a valid default admin. + */ + error AccessControlInvalidDefaultAdmin(address defaultAdmin); + + /** + * @dev At least one of the following rules was violated: + * + * - The `DEFAULT_ADMIN_ROLE` must only be managed by itself. + * - The `DEFAULT_ADMIN_ROLE` must only be held by one account at the time. + * - Any `DEFAULT_ADMIN_ROLE` transfer must be in two delayed steps. + */ + error AccessControlEnforcedDefaultAdminRules(); + + /** + * @dev The delay for transferring the default admin delay is enforced and + * the operation must wait until `schedule`. + * + * NOTE: `schedule` can be 0 indicating there's no transfer scheduled. + */ + error AccessControlEnforcedDefaultAdminDelay(uint48 schedule); + + /** + * @dev Emitted when a {defaultAdmin} transfer is started, setting `newAdmin` as the next + * address to become the {defaultAdmin} by calling {acceptDefaultAdminTransfer} only after `acceptSchedule` + * passes. + */ + event DefaultAdminTransferScheduled(address indexed newAdmin, uint48 acceptSchedule); + + /** + * @dev Emitted when a {pendingDefaultAdmin} is reset if it was never accepted, regardless of its schedule. + */ + event DefaultAdminTransferCanceled(); + + /** + * @dev Emitted when a {defaultAdminDelay} change is started, setting `newDelay` as the next + * delay to be applied between default admin transfer after `effectSchedule` has passed. + */ + event DefaultAdminDelayChangeScheduled(uint48 newDelay, uint48 effectSchedule); + + /** + * @dev Emitted when a {pendingDefaultAdminDelay} is reset if its schedule didn't pass. + */ + event DefaultAdminDelayChangeCanceled(); + + /** + * @dev Returns the address of the current `DEFAULT_ADMIN_ROLE` holder. + */ + function defaultAdmin() external view returns (address); + + /** + * @dev Returns a tuple of a `newAdmin` and an accept schedule. + * + * After the `schedule` passes, the `newAdmin` will be able to accept the {defaultAdmin} role + * by calling {acceptDefaultAdminTransfer}, completing the role transfer. + * + * A zero value only in `acceptSchedule` indicates no pending admin transfer. + * + * NOTE: A zero address `newAdmin` means that {defaultAdmin} is being renounced. + */ + function pendingDefaultAdmin() external view returns (address newAdmin, uint48 acceptSchedule); + + /** + * @dev Returns the delay required to schedule the acceptance of a {defaultAdmin} transfer started. + * + * This delay will be added to the current timestamp when calling {beginDefaultAdminTransfer} to set + * the acceptance schedule. + * + * NOTE: If a delay change has been scheduled, it will take effect as soon as the schedule passes, making this + * function returns the new delay. See {changeDefaultAdminDelay}. + */ + function defaultAdminDelay() external view returns (uint48); + + /** + * @dev Returns a tuple of `newDelay` and an effect schedule. + * + * After the `schedule` passes, the `newDelay` will get into effect immediately for every + * new {defaultAdmin} transfer started with {beginDefaultAdminTransfer}. + * + * A zero value only in `effectSchedule` indicates no pending delay change. + * + * NOTE: A zero value only for `newDelay` means that the next {defaultAdminDelay} + * will be zero after the effect schedule. + */ + function pendingDefaultAdminDelay() external view returns (uint48 newDelay, uint48 effectSchedule); + + /** + * @dev Starts a {defaultAdmin} transfer by setting a {pendingDefaultAdmin} scheduled for acceptance + * after the current timestamp plus a {defaultAdminDelay}. + * + * Requirements: + * + * - Only can be called by the current {defaultAdmin}. + * + * Emits a DefaultAdminRoleChangeStarted event. + */ + function beginDefaultAdminTransfer(address newAdmin) external; + + /** + * @dev Cancels a {defaultAdmin} transfer previously started with {beginDefaultAdminTransfer}. + * + * A {pendingDefaultAdmin} not yet accepted can also be cancelled with this function. + * + * Requirements: + * + * - Only can be called by the current {defaultAdmin}. + * + * May emit a DefaultAdminTransferCanceled event. + */ + function cancelDefaultAdminTransfer() external; + + /** + * @dev Completes a {defaultAdmin} transfer previously started with {beginDefaultAdminTransfer}. + * + * After calling the function: + * + * - `DEFAULT_ADMIN_ROLE` should be granted to the caller. + * - `DEFAULT_ADMIN_ROLE` should be revoked from the previous holder. + * - {pendingDefaultAdmin} should be reset to zero values. + * + * Requirements: + * + * - Only can be called by the {pendingDefaultAdmin}'s `newAdmin`. + * - The {pendingDefaultAdmin}'s `acceptSchedule` should've passed. + */ + function acceptDefaultAdminTransfer() external; + + /** + * @dev Initiates a {defaultAdminDelay} update by setting a {pendingDefaultAdminDelay} scheduled for getting + * into effect after the current timestamp plus a {defaultAdminDelay}. + * + * This function guarantees that any call to {beginDefaultAdminTransfer} done between the timestamp this + * method is called and the {pendingDefaultAdminDelay} effect schedule will use the current {defaultAdminDelay} + * set before calling. + * + * The {pendingDefaultAdminDelay}'s effect schedule is defined in a way that waiting until the schedule and then + * calling {beginDefaultAdminTransfer} with the new delay will take at least the same as another {defaultAdmin} + * complete transfer (including acceptance). + * + * The schedule is designed for two scenarios: + * + * - When the delay is changed for a larger one the schedule is `block.timestamp + newDelay` capped by + * {defaultAdminDelayIncreaseWait}. + * - When the delay is changed for a shorter one, the schedule is `block.timestamp + (current delay - new delay)`. + * + * A {pendingDefaultAdminDelay} that never got into effect will be canceled in favor of a new scheduled change. + * + * Requirements: + * + * - Only can be called by the current {defaultAdmin}. + * + * Emits a DefaultAdminDelayChangeScheduled event and may emit a DefaultAdminDelayChangeCanceled event. + */ + function changeDefaultAdminDelay(uint48 newDelay) external; + + /** + * @dev Cancels a scheduled {defaultAdminDelay} change. + * + * Requirements: + * + * - Only can be called by the current {defaultAdmin}. + * + * May emit a DefaultAdminDelayChangeCanceled event. + */ + function rollbackDefaultAdminDelay() external; + + /** + * @dev Maximum time in seconds for an increase to {defaultAdminDelay} (that is scheduled using {changeDefaultAdminDelay}) + * to take effect. Default to 5 days. + * + * When the {defaultAdminDelay} is scheduled to be increased, it goes into effect after the new delay has passed with + * the purpose of giving enough time for reverting any accidental change (i.e. using milliseconds instead of seconds) + * that may lock the contract. However, to avoid excessive schedules, the wait is capped by this function and it can + * be overrode for a custom {defaultAdminDelay} increase scheduling. + * + * IMPORTANT: Make sure to add a reasonable amount of time while overriding this value, otherwise, + * there's a risk of setting a high new delay that goes into effect almost immediately without the + * possibility of human intervention in the case of an input error (eg. set milliseconds instead of seconds). + */ + function defaultAdminDelayIncreaseWait() external view returns (uint48); +} diff --git a/contracts/access/extensions/IAccessControlEnumerable.sol b/contracts/access/extensions/IAccessControlEnumerable.sol new file mode 100644 index 000000000..4dc8da478 --- /dev/null +++ b/contracts/access/extensions/IAccessControlEnumerable.sol @@ -0,0 +1,31 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (access/extensions/IAccessControlEnumerable.sol) + +pragma solidity ^0.8.20; + +import {IAccessControl} from "../IAccessControl.sol"; + +/** + * @dev External interface of AccessControlEnumerable declared to support ERC165 detection. + */ +interface IAccessControlEnumerable is IAccessControl { + /** + * @dev Returns one of the accounts that have `role`. `index` must be a + * value between 0 and {getRoleMemberCount}, non-inclusive. + * + * Role bearers are not sorted in any particular way, and their ordering may + * change at any point. + * + * WARNING: When using {getRoleMember} and {getRoleMemberCount}, make sure + * you perform all queries on the same block. See the following + * https://forum.openzeppelin.com/t/iterating-over-elements-on-enumerableset-in-openzeppelin-contracts/2296[forum post] + * for more information. + */ + function getRoleMember(bytes32 role, uint256 index) external view returns (address); + + /** + * @dev Returns the number of accounts that have `role`. Can be used + * together with {getRoleMember} to enumerate all bearers of a role. + */ + function getRoleMemberCount(bytes32 role) external view returns (uint256); +} diff --git a/contracts/access/manager/AccessManaged.sol b/contracts/access/manager/AccessManaged.sol new file mode 100644 index 000000000..6d10d6aa3 --- /dev/null +++ b/contracts/access/manager/AccessManaged.sol @@ -0,0 +1,122 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (access/manager/AccessManaged.sol) + +pragma solidity ^0.8.20; + +import {IAuthority} from "./IAuthority.sol"; +import {AuthorityUtils} from "./AuthorityUtils.sol"; +import {IAccessManager} from "./IAccessManager.sol"; +import {IAccessManaged} from "./IAccessManaged.sol"; +import {Context} from "../../utils/Context.sol"; + +/** + * @dev This contract module makes available a {restricted} modifier. Functions decorated with this modifier will be + * permissioned according to an "authority": a contract like {AccessManager} that follows the {IAuthority} interface, + * implementing a policy that allows certain callers to access certain functions. + * + * IMPORTANT: The `restricted` modifier should never be used on `internal` functions, judiciously used in `public` + * functions, and ideally only used in `external` functions. See {restricted}. + */ +abstract contract AccessManaged is Context, IAccessManaged { + address private _authority; + + bool private _consumingSchedule; + + /** + * @dev Initializes the contract connected to an initial authority. + */ + constructor(address initialAuthority) { + _setAuthority(initialAuthority); + } + + /** + * @dev Restricts access to a function as defined by the connected Authority for this contract and the + * caller and selector of the function that entered the contract. + * + * [IMPORTANT] + * ==== + * In general, this modifier should only be used on `external` functions. It is okay to use it on `public` + * functions that are used as external entry points and are not called internally. Unless you know what you're + * doing, it should never be used on `internal` functions. Failure to follow these rules can have critical security + * implications! This is because the permissions are determined by the function that entered the contract, i.e. the + * function at the bottom of the call stack, and not the function where the modifier is visible in the source code. + * ==== + * + * [NOTE] + * ==== + * Selector collisions are mitigated by scoping permissions per contract, but some edge cases must be considered: + * + * * If the https://docs.soliditylang.org/en/v0.8.20/contracts.html#receive-ether-function[`receive()`] function + * is restricted, any other function with a `0x00000000` selector will share permissions with `receive()`. + * * Similarly, if there's no `receive()` function but a `fallback()` instead, the fallback might be called with + * empty `calldata`, sharing the `0x00000000` selector permissions as well. + * * For any other selector, if the restricted function is set on an upgradeable contract, an upgrade may remove + * the restricted function and replace it with a new method whose selector replaces the last one, keeping the + * previous permissions. + * ==== + */ + modifier restricted() { + _checkCanCall(_msgSender(), _msgData()); + _; + } + + /** + * @dev Returns the current authority. + */ + function authority() public view virtual returns (address) { + return _authority; + } + + /** + * @dev Transfers control to a new authority. The caller must be the current authority. + */ + function setAuthority(address newAuthority) public virtual { + address caller = _msgSender(); + if (caller != authority()) { + revert AccessManagedUnauthorized(caller); + } + if (newAuthority.code.length == 0) { + revert AccessManagedInvalidAuthority(newAuthority); + } + _setAuthority(newAuthority); + } + + /** + * @dev Returns true only in the context of a delayed restricted call, at the moment that the scheduled operation is + * being consumed. Prevents denial of service for delayed restricted calls in the case that the contract performs + * attacker controlled calls. + */ + function isConsumingScheduledOp() public view returns (bytes4) { + return _consumingSchedule ? this.isConsumingScheduledOp.selector : bytes4(0); + } + + /** + * @dev Transfers control to a new authority. Internal function with no access restriction. Allows bypassing the + * permissions set by the current authority. + */ + function _setAuthority(address newAuthority) internal virtual { + _authority = newAuthority; + emit AuthorityUpdated(newAuthority); + } + + /** + * @dev Reverts if the caller is not allowed to call the function identified by a selector. + */ + function _checkCanCall(address caller, bytes calldata data) internal virtual { + (bool immediate, uint32 delay) = AuthorityUtils.canCallWithDelay( + authority(), + caller, + address(this), + bytes4(data) + ); + if (!immediate) { + if (delay > 0) { + _consumingSchedule = true; + IAccessManager(authority()).consumeScheduledOp(caller, data); + _consumingSchedule = false; + } else { + revert AccessManagedUnauthorized(caller); + } + } + } +} diff --git a/contracts/access/manager/AccessManager.sol b/contracts/access/manager/AccessManager.sol new file mode 100644 index 000000000..3ae74764a --- /dev/null +++ b/contracts/access/manager/AccessManager.sol @@ -0,0 +1,882 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (access/manager/AccessManager.sol) + +pragma solidity ^0.8.20; + +import {IAccessManager} from "./IAccessManager.sol"; +import {IAccessManaged} from "./IAccessManaged.sol"; +import {Address} from "../../utils/Address.sol"; +import {Context} from "../../utils/Context.sol"; +import {Multicall} from "../../utils/Multicall.sol"; +import {Math} from "../../utils/math/Math.sol"; +import {Time} from "../../utils/types/Time.sol"; + +/** + * @dev AccessManager is a central contract to store the permissions of a system. + * + * The smart contracts under the control of an AccessManager instance will have a set of "restricted" functions, and the + * exact details of how access is restricted for each of those functions is configurable by the admins of the instance. + * These restrictions are expressed in terms of "roles". + * + * An AccessManager instance will define a set of roles. Accounts can be added into any number of these roles. Each of + * them defines a role, and may confer access to some of the restricted functions in the system, as configured by admins + * through the use of {setFunctionAllowedRoles}. + * + * Note that a function in a target contract may become permissioned in this way only when: 1) said contract is + * {AccessManaged} and is connected to this contract as its manager, and 2) said function is decorated with the + * `restricted` modifier. + * + * There is a special role defined by default named "public" which all accounts automatically have. + * + * In addition to the access rules defined by each target's functions being assigned to roles, then entire target can + * be "closed". This "closed" mode is set/unset by the admin using {setTargetClosed} and can be used to lock a contract + * while permissions are being (re-)configured. + * + * Since all the permissions of the managed system can be modified by the admins of this instance, it is expected that + * they will be highly secured (e.g., a multisig or a well-configured DAO). + * + * NOTE: This contract implements a form of the {IAuthority} interface, but {canCall} has additional return data so it + * doesn't inherit `IAuthority`. It is however compatible with the `IAuthority` interface since the first 32 bytes of + * the return data are a boolean as expected by that interface. + * + * NOTE: Systems that implement other access control mechanisms (for example using {Ownable}) can be paired with an + * {AccessManager} by transferring permissions (ownership in the case of {Ownable}) directly to the {AccessManager}. + * Users will be able to interact with these contracts through the {execute} function, following the access rules + * registered in the {AccessManager}. Keep in mind that in that context, the msg.sender seen by restricted functions + * will be {AccessManager} itself. + * + * WARNING: When granting permissions over an {Ownable} or {AccessControl} contract to an {AccessManager}, be very + * mindful of the danger associated with functions such as {{Ownable-renounceOwnership}} or + * {{AccessControl-renounceRole}}. + */ +contract AccessManager is Context, Multicall, IAccessManager { + using Time for *; + + // Structure that stores the details for a target contract. + struct TargetConfig { + mapping(bytes4 selector => uint64 roleId) allowedRoles; + Time.Delay adminDelay; + bool closed; + } + + // Structure that stores the details for a role/account pair. This structures fit into a single slot. + struct Access { + // Timepoint at which the user gets the permission. If this is either 0, or in the future, the role + // permission is not available. + uint48 since; + // Delay for execution. Only applies to restricted() / execute() calls. + Time.Delay delay; + } + + // Structure that stores the details of a role, including: + // - the members of the role + // - the admin role (that can grant or revoke permissions) + // - the guardian role (that can cancel operations targeting functions that need this role) + // - the grand delay + struct Role { + mapping(address user => Access access) members; + uint64 admin; + uint64 guardian; + Time.Delay grantDelay; + } + + // Structure that stores the details for a scheduled operation. This structure fits into a single slot. + struct Schedule { + uint48 timepoint; + uint32 nonce; + } + + uint64 public constant ADMIN_ROLE = type(uint64).min; // 0 + uint64 public constant PUBLIC_ROLE = type(uint64).max; // 2**64-1 + + mapping(address target => TargetConfig mode) private _targets; + mapping(uint64 roleId => Role) private _roles; + mapping(bytes32 operationId => Schedule) private _schedules; + + // This should be transient storage when supported by the EVM. + bytes32 private _executionId; + + /** + * @dev Check that the caller is authorized to perform the operation, following the restrictions encoded in + * {_getAdminRestrictions}. + */ + modifier onlyAuthorized() { + _checkAuthorized(); + _; + } + + constructor(address initialAdmin) { + if (initialAdmin == address(0)) { + revert AccessManagerInvalidInitialAdmin(address(0)); + } + + // admin is active immediately and without any execution delay. + _grantRole(ADMIN_ROLE, initialAdmin, 0, 0); + } + + // =================================================== GETTERS ==================================================== + /** + * @dev Check if an address (`caller`) is authorised to call a given function on a given contract directly (with + * no restriction). Additionally, it returns the delay needed to perform the call indirectly through the {schedule} + * & {execute} workflow. + * + * This function is usually called by the targeted contract to control immediate execution of restricted functions. + * Therefore we only return true is the call can be performed without any delay. If the call is subject to a delay, + * then the function should return false, and the caller should schedule the operation for future execution. + * + * We may be able to hash the operation, and check if the call was scheduled, but we would not be able to cleanup + * the schedule, leaving the possibility of multiple executions. Maybe this function should not be view? + * + * NOTE: The IAuthority interface does not include the `uint32` delay. This is an extension of that interface that + * is backward compatible. Some contracts may thus ignore the second return argument. In that case they will fail + * to identify the indirect workflow, and will consider calls that require a delay to be forbidden. + */ + function canCall(address caller, address target, bytes4 selector) public view virtual returns (bool, uint32) { + if (isTargetClosed(target)) { + return (false, 0); + } else if (caller == address(this)) { + // Caller is AccessManager, this means the call was sent through {execute} and it already checked + // permissions. We verify that the call "identifier", which is set during {execute}, is correct. + return (_isExecuting(target, selector), 0); + } else { + uint64 roleId = getTargetFunctionRole(target, selector); + (bool isMember, uint32 currentDelay) = hasRole(roleId, caller); + return isMember ? (currentDelay == 0, currentDelay) : (false, 0); + } + } + + /** + * @dev Expiration delay for scheduled proposals. Defaults to 1 week. + */ + function expiration() public view virtual returns (uint32) { + return 1 weeks; + } + + /** + * @dev Minimum setback for all delay updates, with the exception of execution delays, which + * can be increased without setback (and in the event of an accidental increase can be reset + * via {revokeRole}). Defaults to 5 days. + */ + function minSetback() public view virtual returns (uint32) { + return 5 days; + } + + /** + * @dev Get the mode under which a contract is operating. + */ + function isTargetClosed(address target) public view virtual returns (bool) { + return _targets[target].closed; + } + + /** + * @dev Get the role required to call a function. + */ + function getTargetFunctionRole(address target, bytes4 selector) public view virtual returns (uint64) { + return _targets[target].allowedRoles[selector]; + } + + /** + * @dev Get the admin delay for a target contract. Changes to contract configuration are subject to this delay. + */ + function getTargetAdminDelay(address target) public view virtual returns (uint32) { + return _targets[target].adminDelay.get(); + } + + /** + * @dev Get the id of the role that acts as an admin for given role. + * + * The admin permission is required to grant the role, revoke the role and update the execution delay to execute + * an operation that is restricted to this role. + */ + function getRoleAdmin(uint64 roleId) public view virtual returns (uint64) { + return _roles[roleId].admin; + } + + /** + * @dev Get the role that acts as a guardian for a given role. + * + * The guardian permission allows canceling operations that have been scheduled under the role. + */ + function getRoleGuardian(uint64 roleId) public view virtual returns (uint64) { + return _roles[roleId].guardian; + } + + /** + * @dev Get the role current grant delay, that value may change at any point, without an event emitted, following + * a call to {setGrantDelay}. Changes to this value, including effect timepoint are notified by the + * {RoleGrantDelayChanged} event. + */ + function getRoleGrantDelay(uint64 roleId) public view virtual returns (uint32) { + return _roles[roleId].grantDelay.get(); + } + + /** + * @dev Get the access details for a given account for a given role. These details include the timepoint at which + * membership becomes active, and the delay applied to all operation by this user that requires this permission + * level. + * + * Returns: + * [0] Timestamp at which the account membership becomes valid. 0 means role is not granted. + * [1] Current execution delay for the account. + * [2] Pending execution delay for the account. + * [3] Timestamp at which the pending execution delay will become active. 0 means no delay update is scheduled. + */ + function getAccess(uint64 roleId, address account) public view virtual returns (uint48, uint32, uint32, uint48) { + Access storage access = _roles[roleId].members[account]; + + uint48 since = access.since; + (uint32 currentDelay, uint32 pendingDelay, uint48 effect) = access.delay.getFull(); + + return (since, currentDelay, pendingDelay, effect); + } + + /** + * @dev Check if a given account currently had the permission level corresponding to a given role. Note that this + * permission might be associated with a delay. {getAccess} can provide more details. + */ + function hasRole(uint64 roleId, address account) public view virtual returns (bool, uint32) { + if (roleId == PUBLIC_ROLE) { + return (true, 0); + } else { + (uint48 hasRoleSince, uint32 currentDelay, , ) = getAccess(roleId, account); + return (hasRoleSince != 0 && hasRoleSince <= Time.timestamp(), currentDelay); + } + } + + // =============================================== ROLE MANAGEMENT =============================================== + /** + * @dev Give a label to a role, for improved role discoverabily by UIs. + * + * Emits a {RoleLabel} event. + */ + function labelRole(uint64 roleId, string calldata label) public virtual onlyAuthorized { + if (roleId == ADMIN_ROLE || roleId == PUBLIC_ROLE) { + revert AccessManagerLockedRole(roleId); + } + emit RoleLabel(roleId, label); + } + + /** + * @dev Add `account` to `roleId`, or change its execution delay. + * + * This gives the account the authorization to call any function that is restricted to this role. An optional + * execution delay (in seconds) can be set. If that delay is non 0, the user is required to schedule any operation + * that is restricted to members this role. The user will only be able to execute the operation after the delay has + * passed, before it has expired. During this period, admin and guardians can cancel the operation (see {cancel}). + * + * If the account has already been granted this role, the execution delay will be updated. This update is not + * immediate and follows the delay rules. For example, If a user currently has a delay of 3 hours, and this is + * called to reduce that delay to 1 hour, the new delay will take some time to take effect, enforcing that any + * operation executed in the 3 hours that follows this update was indeed scheduled before this update. + * + * Requirements: + * + * - the caller must be an admin for the role (see {getRoleAdmin}) + * + * Emits a {RoleGranted} event + */ + function grantRole(uint64 roleId, address account, uint32 executionDelay) public virtual onlyAuthorized { + _grantRole(roleId, account, getRoleGrantDelay(roleId), executionDelay); + } + + /** + * @dev Remove an account from a role, with immediate effect. If the account does not have the role, this call has + * no effect. + * + * Requirements: + * + * - the caller must be an admin for the role (see {getRoleAdmin}) + * + * Emits a {RoleRevoked} event if the account had the role. + */ + function revokeRole(uint64 roleId, address account) public virtual onlyAuthorized { + _revokeRole(roleId, account); + } + + /** + * @dev Renounce role permissions for the calling account, with immediate effect. If the sender is not in + * the role, this call has no effect. + * + * Requirements: + * + * - the caller must be `callerConfirmation`. + * + * Emits a {RoleRevoked} event if the account had the role. + */ + function renounceRole(uint64 roleId, address callerConfirmation) public virtual { + if (callerConfirmation != _msgSender()) { + revert AccessManagerBadConfirmation(); + } + _revokeRole(roleId, callerConfirmation); + } + + /** + * @dev Change admin role for a given role. + * + * Requirements: + * + * - the caller must be a global admin + * + * Emits a {RoleAdminChanged} event + */ + function setRoleAdmin(uint64 roleId, uint64 admin) public virtual onlyAuthorized { + _setRoleAdmin(roleId, admin); + } + + /** + * @dev Change guardian role for a given role. + * + * Requirements: + * + * - the caller must be a global admin + * + * Emits a {RoleGuardianChanged} event + */ + function setRoleGuardian(uint64 roleId, uint64 guardian) public virtual onlyAuthorized { + _setRoleGuardian(roleId, guardian); + } + + /** + * @dev Update the delay for granting a `roleId`. + * + * Requirements: + * + * - the caller must be a global admin + * + * Emits a {RoleGrantDelayChanged} event. + */ + function setGrantDelay(uint64 roleId, uint32 newDelay) public virtual onlyAuthorized { + _setGrantDelay(roleId, newDelay); + } + + /** + * @dev Internal version of {grantRole} without access control. Returns true if the role was newly granted. + * + * Emits a {RoleGranted} event. + */ + function _grantRole( + uint64 roleId, + address account, + uint32 grantDelay, + uint32 executionDelay + ) internal virtual returns (bool) { + if (roleId == PUBLIC_ROLE) { + revert AccessManagerLockedRole(roleId); + } + + bool newMember = _roles[roleId].members[account].since == 0; + uint48 since; + + if (newMember) { + since = Time.timestamp() + grantDelay; + _roles[roleId].members[account] = Access({since: since, delay: executionDelay.toDelay()}); + } else { + // No setback here. Value can be reset by doing revoke + grant, effectively allowing the admin to perform + // any change to the execution delay within the duration of the role admin delay. + (_roles[roleId].members[account].delay, since) = _roles[roleId].members[account].delay.withUpdate( + executionDelay, + 0 + ); + } + + emit RoleGranted(roleId, account, executionDelay, since, newMember); + return newMember; + } + + /** + * @dev Internal version of {revokeRole} without access control. This logic is also used by {renounceRole}. + * Returns true if the role was previously granted. + * + * Emits a {RoleRevoked} event if the account had the role. + */ + function _revokeRole(uint64 roleId, address account) internal virtual returns (bool) { + if (roleId == PUBLIC_ROLE) { + revert AccessManagerLockedRole(roleId); + } + + if (_roles[roleId].members[account].since == 0) { + return false; + } + + delete _roles[roleId].members[account]; + + emit RoleRevoked(roleId, account); + return true; + } + + /** + * @dev Internal version of {setRoleAdmin} without access control. + * + * Emits a {RoleAdminChanged} event + */ + function _setRoleAdmin(uint64 roleId, uint64 admin) internal virtual { + if (roleId == ADMIN_ROLE || roleId == PUBLIC_ROLE) { + revert AccessManagerLockedRole(roleId); + } + + _roles[roleId].admin = admin; + + emit RoleAdminChanged(roleId, admin); + } + + /** + * @dev Internal version of {setRoleGuardian} without access control. + * + * Emits a {RoleGuardianChanged} event + */ + function _setRoleGuardian(uint64 roleId, uint64 guardian) internal virtual { + if (roleId == ADMIN_ROLE || roleId == PUBLIC_ROLE) { + revert AccessManagerLockedRole(roleId); + } + + _roles[roleId].guardian = guardian; + + emit RoleGuardianChanged(roleId, guardian); + } + + /** + * @dev Internal version of {setGrantDelay} without access control. + * + * Emits a {RoleGrantDelayChanged} event + */ + function _setGrantDelay(uint64 roleId, uint32 newDelay) internal virtual { + if (roleId == PUBLIC_ROLE) { + revert AccessManagerLockedRole(roleId); + } + + uint48 effect; + (_roles[roleId].grantDelay, effect) = _roles[roleId].grantDelay.withUpdate(newDelay, minSetback()); + + emit RoleGrantDelayChanged(roleId, newDelay, effect); + } + + // ============================================= FUNCTION MANAGEMENT ============================================== + /** + * @dev Set the role required to call functions identified by the `selectors` in the `target` contract. + * + * Requirements: + * + * - the caller must be a global admin + * + * Emits a {TargetFunctionRoleUpdated} event per selector. + */ + function setTargetFunctionRole( + address target, + bytes4[] calldata selectors, + uint64 roleId + ) public virtual onlyAuthorized { + for (uint256 i = 0; i < selectors.length; ++i) { + _setTargetFunctionRole(target, selectors[i], roleId); + } + } + + /** + * @dev Internal version of {setFunctionAllowedRole} without access control. + * + * Emits a {TargetFunctionRoleUpdated} event + */ + function _setTargetFunctionRole(address target, bytes4 selector, uint64 roleId) internal virtual { + _targets[target].allowedRoles[selector] = roleId; + emit TargetFunctionRoleUpdated(target, selector, roleId); + } + + /** + * @dev Set the delay for changing the configuration of a given target contract. + * + * Requirements: + * + * - the caller must be a global admin + * + * Emits a {TargetAdminDelayUpdated} event per selector + */ + function setTargetAdminDelay(address target, uint32 newDelay) public virtual onlyAuthorized { + _setTargetAdminDelay(target, newDelay); + } + + /** + * @dev Internal version of {setTargetAdminDelay} without access control. + * + * Emits a {TargetAdminDelayUpdated} event + */ + function _setTargetAdminDelay(address target, uint32 newDelay) internal virtual { + uint48 effect; + (_targets[target].adminDelay, effect) = _targets[target].adminDelay.withUpdate(newDelay, minSetback()); + + emit TargetAdminDelayUpdated(target, newDelay, effect); + } + + // =============================================== MODE MANAGEMENT ================================================ + /** + * @dev Set the closed flag for a contract. + * + * Requirements: + * + * - the caller must be a global admin + * + * Emits a {TargetClosed} event. + */ + function setTargetClosed(address target, bool closed) public virtual onlyAuthorized { + _setTargetClosed(target, closed); + } + + /** + * @dev Set the closed flag for a contract. This is an internal setter with no access restrictions. + * + * Emits a {TargetClosed} event. + */ + function _setTargetClosed(address target, bool closed) internal virtual { + if (target == address(this)) { + revert AccessManagerLockedAccount(target); + } + _targets[target].closed = closed; + emit TargetClosed(target, closed); + } + + // ============================================== DELAYED OPERATIONS ============================================== + /** + * @dev Return the timepoint at which a scheduled operation will be ready for execution. This returns 0 if the + * operation is not yet scheduled, has expired, was executed, or was canceled. + */ + function getSchedule(bytes32 id) public view virtual returns (uint48) { + uint48 timepoint = _schedules[id].timepoint; + return _isExpired(timepoint) ? 0 : timepoint; + } + + /** + * @dev Return the nonce for the latest scheduled operation with a given id. Returns 0 if the operation has never + * been scheduled. + */ + function getNonce(bytes32 id) public view virtual returns (uint32) { + return _schedules[id].nonce; + } + + /** + * @dev Schedule a delayed operation for future execution, and return the operation identifier. It is possible to + * choose the timestamp at which the operation becomes executable as long as it satisfies the execution delays + * required for the caller. The special value zero will automatically set the earliest possible time. + * + * Returns the `operationId` that was scheduled. Since this value is a hash of the parameters, it can reoccur when + * the same parameters are used; if this is relevant, the returned `nonce` can be used to uniquely identify this + * scheduled operation from other occurrences of the same `operationId` in invocations of {execute} and {cancel}. + * + * Emits a {OperationScheduled} event. + * + * NOTE: It is not possible to concurrently schedule more than one operation with the same `target` and `data`. If + * this is necessary, a random byte can be appended to `data` to act as a salt that will be ignored by the target + * contract if it is using standard Solidity ABI encoding. + */ + function schedule( + address target, + bytes calldata data, + uint48 when + ) public virtual returns (bytes32 operationId, uint32 nonce) { + address caller = _msgSender(); + + // Fetch restrictions that apply to the caller on the targeted function + (bool immediate, uint32 setback) = _canCallExtended(caller, target, data); + + uint48 minWhen = Time.timestamp() + setback; + + // if call is not authorized, or if requested timing is too soon + if ((!immediate && setback == 0) || (when > 0 && when < minWhen)) { + revert AccessManagerUnauthorizedCall(caller, target, bytes4(data[0:4])); + } + + // Reuse variable due to stack too deep + when = uint48(Math.max(when, minWhen)); // cast is safe: both inputs are uint48 + + // If caller is authorised, schedule operation + operationId = hashOperation(caller, target, data); + + _checkNotScheduled(operationId); + + unchecked { + // It's not feasible to overflow the nonce in less than 1000 years + nonce = _schedules[operationId].nonce + 1; + } + _schedules[operationId].timepoint = when; + _schedules[operationId].nonce = nonce; + emit OperationScheduled(operationId, nonce, when, caller, target, data); + + // Using named return values because otherwise we get stack too deep + } + + /** + * @dev Reverts if the operation is currently scheduled and has not expired. + * (Note: This function was introduced due to stack too deep errors in schedule.) + */ + function _checkNotScheduled(bytes32 operationId) private view { + uint48 prevTimepoint = _schedules[operationId].timepoint; + if (prevTimepoint != 0 && !_isExpired(prevTimepoint)) { + revert AccessManagerAlreadyScheduled(operationId); + } + } + + /** + * @dev Execute a function that is delay restricted, provided it was properly scheduled beforehand, or the + * execution delay is 0. + * + * Returns the nonce that identifies the previously scheduled operation that is executed, or 0 if the + * operation wasn't previously scheduled (if the caller doesn't have an execution delay). + * + * Emits an {OperationExecuted} event only if the call was scheduled and delayed. + */ + // Reentrancy is not an issue because permissions are checked on msg.sender. Additionally, + // _consumeScheduledOp guarantees a scheduled operation is only executed once. + // slither-disable-next-line reentrancy-no-eth + function execute(address target, bytes calldata data) public payable virtual returns (uint32) { + address caller = _msgSender(); + + // Fetch restrictions that apply to the caller on the targeted function + (bool immediate, uint32 setback) = _canCallExtended(caller, target, data); + + // If caller is not authorised, revert + if (!immediate && setback == 0) { + revert AccessManagerUnauthorizedCall(caller, target, bytes4(data)); + } + + // If caller is authorised, check operation was scheduled early enough + bytes32 operationId = hashOperation(caller, target, data); + uint32 nonce; + + if (setback != 0) { + nonce = _consumeScheduledOp(operationId); + } + + // Mark the target and selector as authorised + bytes32 executionIdBefore = _executionId; + _executionId = _hashExecutionId(target, bytes4(data)); + + // Perform call + Address.functionCallWithValue(target, data, msg.value); + + // Reset execute identifier + _executionId = executionIdBefore; + + return nonce; + } + + /** + * @dev Consume a scheduled operation targeting the caller. If such an operation exists, mark it as consumed + * (emit an {OperationExecuted} event and clean the state). Otherwise, throw an error. + * + * This is useful for contract that want to enforce that calls targeting them were scheduled on the manager, + * with all the verifications that it implies. + * + * Emit a {OperationExecuted} event + */ + function consumeScheduledOp(address caller, bytes calldata data) public virtual { + address target = _msgSender(); + if (IAccessManaged(target).isConsumingScheduledOp() != IAccessManaged.isConsumingScheduledOp.selector) { + revert AccessManagerUnauthorizedConsume(target); + } + _consumeScheduledOp(hashOperation(caller, target, data)); + } + + /** + * @dev Internal variant of {consumeScheduledOp} that operates on bytes32 operationId. + * + * Returns the nonce of the scheduled operation that is consumed. + */ + function _consumeScheduledOp(bytes32 operationId) internal virtual returns (uint32) { + uint48 timepoint = _schedules[operationId].timepoint; + uint32 nonce = _schedules[operationId].nonce; + + if (timepoint == 0) { + revert AccessManagerNotScheduled(operationId); + } else if (timepoint > Time.timestamp()) { + revert AccessManagerNotReady(operationId); + } else if (_isExpired(timepoint)) { + revert AccessManagerExpired(operationId); + } + + delete _schedules[operationId].timepoint; // reset the timepoint, keep the nonce + emit OperationExecuted(operationId, nonce); + + return nonce; + } + + /** + * @dev Cancel a scheduled (delayed) operation. Returns the nonce that identifies the previously scheduled + * operation that is cancelled. + * + * Requirements: + * + * - the caller must be the proposer, a guardian of the targeted function, or a global admin + * + * Emits a {OperationCanceled} event. + */ + function cancel(address caller, address target, bytes calldata data) public virtual returns (uint32) { + address msgsender = _msgSender(); + bytes4 selector = bytes4(data[0:4]); + + bytes32 operationId = hashOperation(caller, target, data); + if (_schedules[operationId].timepoint == 0) { + revert AccessManagerNotScheduled(operationId); + } else if (caller != msgsender) { + // calls can only be canceled by the account that scheduled them, a global admin, or by a guardian of the required role. + (bool isAdmin, ) = hasRole(ADMIN_ROLE, msgsender); + (bool isGuardian, ) = hasRole(getRoleGuardian(getTargetFunctionRole(target, selector)), msgsender); + if (!isAdmin && !isGuardian) { + revert AccessManagerUnauthorizedCancel(msgsender, caller, target, selector); + } + } + + delete _schedules[operationId].timepoint; // reset the timepoint, keep the nonce + uint32 nonce = _schedules[operationId].nonce; + emit OperationCanceled(operationId, nonce); + + return nonce; + } + + /** + * @dev Hashing function for delayed operations + */ + function hashOperation(address caller, address target, bytes calldata data) public view virtual returns (bytes32) { + return keccak256(abi.encode(caller, target, data)); + } + + /** + * @dev Hashing function for execute protection + */ + function _hashExecutionId(address target, bytes4 selector) private pure returns (bytes32) { + return keccak256(abi.encode(target, selector)); + } + + // ==================================================== OTHERS ==================================================== + /** + * @dev Change the AccessManager instance used by a contract that correctly uses this instance. + * + * Requirements: + * + * - the caller must be a global admin + */ + function updateAuthority(address target, address newAuthority) public virtual onlyAuthorized { + IAccessManaged(target).setAuthority(newAuthority); + } + + // ================================================= ADMIN LOGIC ================================================== + /** + * @dev Check if the current call is authorized according to admin logic. + */ + function _checkAuthorized() private { + address caller = _msgSender(); + (bool immediate, uint32 delay) = _canCallSelf(caller, _msgData()); + if (!immediate) { + if (delay == 0) { + (, uint64 requiredRole, ) = _getAdminRestrictions(_msgData()); + revert AccessManagerUnauthorizedAccount(caller, requiredRole); + } else { + _consumeScheduledOp(hashOperation(caller, address(this), _msgData())); + } + } + } + + /** + * @dev Get the admin restrictions of a given function call based on the function and arguments involved. + * + * Returns: + * - bool restricted: does this data match a restricted operation + * - uint64: which role is this operation restricted to + * - uint32: minimum delay to enforce for that operation (on top of the admin's execution delay) + */ + function _getAdminRestrictions(bytes calldata data) private view returns (bool, uint64, uint32) { + bytes4 selector = bytes4(data); + + if (data.length < 4) { + return (false, 0, 0); + } + + // Restricted to ADMIN with no delay beside any execution delay the caller may have + if ( + selector == this.labelRole.selector || + selector == this.setRoleAdmin.selector || + selector == this.setRoleGuardian.selector || + selector == this.setGrantDelay.selector || + selector == this.setTargetAdminDelay.selector + ) { + return (true, ADMIN_ROLE, 0); + } + + // Restricted to ADMIN with the admin delay corresponding to the target + if ( + selector == this.updateAuthority.selector || + selector == this.setTargetClosed.selector || + selector == this.setTargetFunctionRole.selector + ) { + // First argument is a target. + address target = abi.decode(data[0x04:0x24], (address)); + uint32 delay = getTargetAdminDelay(target); + return (true, ADMIN_ROLE, delay); + } + + // Restricted to that role's admin with no delay beside any execution delay the caller may have. + if (selector == this.grantRole.selector || selector == this.revokeRole.selector) { + // First argument is a roleId. + uint64 roleId = abi.decode(data[0x04:0x24], (uint64)); + uint64 roleAdminId = getRoleAdmin(roleId); + return (true, roleAdminId, 0); + } + + return (false, 0, 0); + } + + // =================================================== HELPERS ==================================================== + /** + * @dev An extended version of {canCall} for internal use that considers restrictions for admin functions. + * + * Returns: + * - bool immediate: whether the operation can be executed immediately (with no delay) + * - uint32 delay: the execution delay + * + * If immediate is true, the delay can be disregarded and the operation can be immediately executed. + * If immediate is false, the operation can be executed if and only if delay is greater than 0. + */ + function _canCallExtended(address caller, address target, bytes calldata data) private view returns (bool, uint32) { + if (target == address(this)) { + return _canCallSelf(caller, data); + } else { + bytes4 selector = bytes4(data); + return canCall(caller, target, selector); + } + } + + /** + * @dev A version of {canCall} that checks for admin restrictions in this contract. + */ + function _canCallSelf(address caller, bytes calldata data) private view returns (bool immediate, uint32 delay) { + if (caller == address(this)) { + // Caller is AccessManager, this means the call was sent through {execute} and it already checked + // permissions. We verify that the call "identifier", which is set during {execute}, is correct. + return (_isExecuting(address(this), bytes4(data)), 0); + } + + (bool enabled, uint64 roleId, uint32 operationDelay) = _getAdminRestrictions(data); + if (!enabled) { + return (false, 0); + } + + (bool inRole, uint32 executionDelay) = hasRole(roleId, caller); + if (!inRole) { + return (false, 0); + } + + // downcast is safe because both options are uint32 + delay = uint32(Math.max(operationDelay, executionDelay)); + return (delay == 0, delay); + } + + /** + * @dev Returns true if a call with `target` and `selector` is being executed via {executed}. + */ + function _isExecuting(address target, bytes4 selector) private view returns (bool) { + return _executionId == _hashExecutionId(target, selector); + } + + /** + * @dev Returns true if a schedule timepoint is past its expiration deadline. + */ + function _isExpired(uint48 timepoint) private view returns (bool) { + return timepoint + expiration() <= Time.timestamp(); + } +} diff --git a/contracts/access/manager/AuthorityUtils.sol b/contracts/access/manager/AuthorityUtils.sol new file mode 100644 index 000000000..c2a118e80 --- /dev/null +++ b/contracts/access/manager/AuthorityUtils.sol @@ -0,0 +1,32 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (access/manager/AuthorityUtils.sol) + +pragma solidity ^0.8.20; + +import {IAuthority} from "./IAuthority.sol"; + +library AuthorityUtils { + /** + * @dev Since `AccessManager` implements an extended IAuthority interface, invoking `canCall` with backwards compatibility + * for the preexisting `IAuthority` interface requires special care to avoid reverting on insufficient return data. + * This helper function takes care of invoking `canCall` in a backwards compatible way without reverting. + */ + function canCallWithDelay( + address authority, + address caller, + address target, + bytes4 selector + ) internal view returns (bool immediate, uint32 delay) { + (bool success, bytes memory data) = authority.staticcall( + abi.encodeCall(IAuthority.canCall, (caller, target, selector)) + ); + if (success) { + if (data.length >= 0x40) { + (immediate, delay) = abi.decode(data, (bool, uint32)); + } else if (data.length >= 0x20) { + immediate = abi.decode(data, (bool)); + } + } + return (immediate, delay); + } +} diff --git a/contracts/access/manager/IAccessManaged.sol b/contracts/access/manager/IAccessManaged.sol new file mode 100644 index 000000000..fad7c5df9 --- /dev/null +++ b/contracts/access/manager/IAccessManaged.sol @@ -0,0 +1,18 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (access/manager/IAccessManaged.sol) + +pragma solidity ^0.8.20; + +interface IAccessManaged { + event AuthorityUpdated(address authority); + + error AccessManagedUnauthorized(address caller); + error AccessManagedRequiredDelay(address caller, uint32 delay); + error AccessManagedInvalidAuthority(address authority); + + function authority() external view returns (address); + + function setAuthority(address) external; + + function isConsumingScheduledOp() external view returns (bytes4); +} diff --git a/contracts/access/manager/IAccessManager.sol b/contracts/access/manager/IAccessManager.sol new file mode 100644 index 000000000..01ecedd1c --- /dev/null +++ b/contracts/access/manager/IAccessManager.sol @@ -0,0 +1,114 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (access/manager/IAccessManager.sol) + +pragma solidity ^0.8.20; + +import {IAccessManaged} from "./IAccessManaged.sol"; +import {Time} from "../../utils/types/Time.sol"; + +interface IAccessManager { + /** + * @dev A delayed operation was scheduled. + */ + event OperationScheduled( + bytes32 indexed operationId, + uint32 indexed nonce, + uint48 schedule, + address caller, + address target, + bytes data + ); + + /** + * @dev A scheduled operation was executed. + */ + event OperationExecuted(bytes32 indexed operationId, uint32 indexed nonce); + + /** + * @dev A scheduled operation was canceled. + */ + event OperationCanceled(bytes32 indexed operationId, uint32 indexed nonce); + + event RoleLabel(uint64 indexed roleId, string label); + event RoleGranted(uint64 indexed roleId, address indexed account, uint32 delay, uint48 since, bool newMember); + event RoleRevoked(uint64 indexed roleId, address indexed account); + event RoleAdminChanged(uint64 indexed roleId, uint64 indexed admin); + event RoleGuardianChanged(uint64 indexed roleId, uint64 indexed guardian); + event RoleGrantDelayChanged(uint64 indexed roleId, uint32 delay, uint48 since); + event TargetClosed(address indexed target, bool closed); + event TargetFunctionRoleUpdated(address indexed target, bytes4 selector, uint64 indexed roleId); + event TargetAdminDelayUpdated(address indexed target, uint32 delay, uint48 since); + + error AccessManagerAlreadyScheduled(bytes32 operationId); + error AccessManagerNotScheduled(bytes32 operationId); + error AccessManagerNotReady(bytes32 operationId); + error AccessManagerExpired(bytes32 operationId); + error AccessManagerLockedAccount(address account); + error AccessManagerLockedRole(uint64 roleId); + error AccessManagerBadConfirmation(); + error AccessManagerUnauthorizedAccount(address msgsender, uint64 roleId); + error AccessManagerUnauthorizedCall(address caller, address target, bytes4 selector); + error AccessManagerUnauthorizedConsume(address target); + error AccessManagerUnauthorizedCancel(address msgsender, address caller, address target, bytes4 selector); + error AccessManagerInvalidInitialAdmin(address initialAdmin); + + function canCall( + address caller, + address target, + bytes4 selector + ) external view returns (bool allowed, uint32 delay); + + function hashOperation(address caller, address target, bytes calldata data) external view returns (bytes32); + + function expiration() external view returns (uint32); + + function isTargetClosed(address target) external view returns (bool); + + function getTargetFunctionRole(address target, bytes4 selector) external view returns (uint64); + + function getTargetAdminDelay(address target) external view returns (uint32); + + function getRoleAdmin(uint64 roleId) external view returns (uint64); + + function getRoleGuardian(uint64 roleId) external view returns (uint64); + + function getRoleGrantDelay(uint64 roleId) external view returns (uint32); + + function getAccess(uint64 roleId, address account) external view returns (uint48, uint32, uint32, uint48); + + function hasRole(uint64 roleId, address account) external view returns (bool, uint32); + + function labelRole(uint64 roleId, string calldata label) external; + + function grantRole(uint64 roleId, address account, uint32 executionDelay) external; + + function revokeRole(uint64 roleId, address account) external; + + function renounceRole(uint64 roleId, address callerConfirmation) external; + + function setRoleAdmin(uint64 roleId, uint64 admin) external; + + function setRoleGuardian(uint64 roleId, uint64 guardian) external; + + function setGrantDelay(uint64 roleId, uint32 newDelay) external; + + function setTargetFunctionRole(address target, bytes4[] calldata selectors, uint64 roleId) external; + + function setTargetAdminDelay(address target, uint32 newDelay) external; + + function setTargetClosed(address target, bool closed) external; + + function getSchedule(bytes32 id) external view returns (uint48); + + function getNonce(bytes32 id) external view returns (uint32); + + function schedule(address target, bytes calldata data, uint48 when) external returns (bytes32, uint32); + + function execute(address target, bytes calldata data) external payable returns (uint32); + + function cancel(address caller, address target, bytes calldata data) external returns (uint32); + + function consumeScheduledOp(address caller, bytes calldata data) external; + + function updateAuthority(address target, address newAuthority) external; +} diff --git a/contracts/access/manager/IAuthority.sol b/contracts/access/manager/IAuthority.sol new file mode 100644 index 000000000..78d610415 --- /dev/null +++ b/contracts/access/manager/IAuthority.sol @@ -0,0 +1,14 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (access/manager/IAuthority.sol) + +pragma solidity ^0.8.20; + +/** + * @dev Standard interface for permissioning originally defined in Dappsys. + */ +interface IAuthority { + /** + * @dev Returns true if the caller can invoke on a target the function identified by a function selector. + */ + function canCall(address caller, address target, bytes4 selector) external view returns (bool allowed); +} diff --git a/contracts/finance/README.adoc b/contracts/finance/README.adoc new file mode 100644 index 000000000..ac7e4f015 --- /dev/null +++ b/contracts/finance/README.adoc @@ -0,0 +1,14 @@ += Finance + +[.readme-notice] +NOTE: This document is better viewed at https://docs.openzeppelin.com/contracts/api/finance + +This directory includes primitives for financial systems: + +- {VestingWallet} handles the vesting of Ether and ERC20 tokens for a given beneficiary. Custody of multiple tokens can + be given to this contract, which will release the token to the beneficiary following a given, customizable, vesting + schedule. + +== Contracts + +{{VestingWallet}} diff --git a/contracts/finance/VestingWallet.sol b/contracts/finance/VestingWallet.sol new file mode 100644 index 000000000..f6373a617 --- /dev/null +++ b/contracts/finance/VestingWallet.sol @@ -0,0 +1,154 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (finance/VestingWallet.sol) +pragma solidity ^0.8.20; + +import {IERC20} from "../token/ERC20/IERC20.sol"; +import {SafeERC20} from "../token/ERC20/utils/SafeERC20.sol"; +import {Address} from "../utils/Address.sol"; +import {Context} from "../utils/Context.sol"; +import {Ownable} from "../access/Ownable.sol"; + +/** + * @dev A vesting wallet is an ownable contract that can receive native currency and ERC20 tokens, and release these + * assets to the wallet owner, also referred to as "beneficiary", according to a vesting schedule. + * + * Any assets transferred to this contract will follow the vesting schedule as if they were locked from the beginning. + * Consequently, if the vesting has already started, any amount of tokens sent to this contract will (at least partly) + * be immediately releasable. + * + * By setting the duration to 0, one can configure this contract to behave like an asset timelock that hold tokens for + * a beneficiary until a specified time. + * + * NOTE: Since the wallet is {Ownable}, and ownership can be transferred, it is possible to sell unvested tokens. + * Preventing this in a smart contract is difficult, considering that: 1) a beneficiary address could be a + * counterfactually deployed contract, 2) there is likely to be a migration path for EOAs to become contracts in the + * near future. + * + * NOTE: When using this contract with any token whose balance is adjusted automatically (i.e. a rebase token), make + * sure to account the supply/balance adjustment in the vesting schedule to ensure the vested amount is as intended. + */ +contract VestingWallet is Context, Ownable { + event EtherReleased(uint256 amount); + event ERC20Released(address indexed token, uint256 amount); + + uint256 private _released; + mapping(address token => uint256) private _erc20Released; + uint64 private immutable _start; + uint64 private immutable _duration; + + /** + * @dev Sets the sender as the initial owner, the beneficiary as the pending owner, the start timestamp and the + * vesting duration of the vesting wallet. + */ + constructor(address beneficiary, uint64 startTimestamp, uint64 durationSeconds) payable Ownable(beneficiary) { + _start = startTimestamp; + _duration = durationSeconds; + } + + /** + * @dev The contract should be able to receive Eth. + */ + receive() external payable virtual {} + + /** + * @dev Getter for the start timestamp. + */ + function start() public view virtual returns (uint256) { + return _start; + } + + /** + * @dev Getter for the vesting duration. + */ + function duration() public view virtual returns (uint256) { + return _duration; + } + + /** + * @dev Getter for the end timestamp. + */ + function end() public view virtual returns (uint256) { + return start() + duration(); + } + + /** + * @dev Amount of eth already released + */ + function released() public view virtual returns (uint256) { + return _released; + } + + /** + * @dev Amount of token already released + */ + function released(address token) public view virtual returns (uint256) { + return _erc20Released[token]; + } + + /** + * @dev Getter for the amount of releasable eth. + */ + function releasable() public view virtual returns (uint256) { + return vestedAmount(uint64(block.timestamp)) - released(); + } + + /** + * @dev Getter for the amount of releasable `token` tokens. `token` should be the address of an + * IERC20 contract. + */ + function releasable(address token) public view virtual returns (uint256) { + return vestedAmount(token, uint64(block.timestamp)) - released(token); + } + + /** + * @dev Release the native token (ether) that have already vested. + * + * Emits a {EtherReleased} event. + */ + function release() public virtual { + uint256 amount = releasable(); + _released += amount; + emit EtherReleased(amount); + Address.sendValue(payable(owner()), amount); + } + + /** + * @dev Release the tokens that have already vested. + * + * Emits a {ERC20Released} event. + */ + function release(address token) public virtual { + uint256 amount = releasable(token); + _erc20Released[token] += amount; + emit ERC20Released(token, amount); + SafeERC20.safeTransfer(IERC20(token), owner(), amount); + } + + /** + * @dev Calculates the amount of ether that has already vested. Default implementation is a linear vesting curve. + */ + function vestedAmount(uint64 timestamp) public view virtual returns (uint256) { + return _vestingSchedule(address(this).balance + released(), timestamp); + } + + /** + * @dev Calculates the amount of tokens that has already vested. Default implementation is a linear vesting curve. + */ + function vestedAmount(address token, uint64 timestamp) public view virtual returns (uint256) { + return _vestingSchedule(IERC20(token).balanceOf(address(this)) + released(token), timestamp); + } + + /** + * @dev Virtual implementation of the vesting formula. This returns the amount vested, as a function of time, for + * an asset given its total historical allocation. + */ + function _vestingSchedule(uint256 totalAllocation, uint64 timestamp) internal view virtual returns (uint256) { + if (timestamp < start()) { + return 0; + } else if (timestamp >= end()) { + return totalAllocation; + } else { + return (totalAllocation * (timestamp - start())) / duration(); + } + } +} diff --git a/contracts/governance/Governor.sol b/contracts/governance/Governor.sol new file mode 100644 index 000000000..9c65483ce --- /dev/null +++ b/contracts/governance/Governor.sol @@ -0,0 +1,850 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (governance/Governor.sol) + +pragma solidity ^0.8.20; + +import {IERC721Receiver} from "../token/ERC721/IERC721Receiver.sol"; +import {IERC1155Receiver} from "../token/ERC1155/IERC1155Receiver.sol"; +import {EIP712} from "../utils/cryptography/EIP712.sol"; +import {SignatureChecker} from "../utils/cryptography/SignatureChecker.sol"; +import {IERC165, ERC165} from "../utils/introspection/ERC165.sol"; +import {SafeCast} from "../utils/math/SafeCast.sol"; +import {DoubleEndedQueue} from "../utils/structs/DoubleEndedQueue.sol"; +import {Address} from "../utils/Address.sol"; +import {Context} from "../utils/Context.sol"; +import {Nonces} from "../utils/Nonces.sol"; +import {IGovernor, IERC6372} from "./IGovernor.sol"; + +/** + * @dev Core of the governance system, designed to be extended through various modules. + * + * This contract is abstract and requires several functions to be implemented in various modules: + * + * - A counting module must implement {quorum}, {_quorumReached}, {_voteSucceeded} and {_countVote} + * - A voting module must implement {_getVotes} + * - Additionally, {votingPeriod} must also be implemented + */ +abstract contract Governor is Context, ERC165, EIP712, Nonces, IGovernor, IERC721Receiver, IERC1155Receiver { + using DoubleEndedQueue for DoubleEndedQueue.Bytes32Deque; + + bytes32 public constant BALLOT_TYPEHASH = + keccak256("Ballot(uint256 proposalId,uint8 support,address voter,uint256 nonce)"); + bytes32 public constant EXTENDED_BALLOT_TYPEHASH = + keccak256( + "ExtendedBallot(uint256 proposalId,uint8 support,address voter,uint256 nonce,string reason,bytes params)" + ); + + struct ProposalCore { + address proposer; + uint48 voteStart; + uint32 voteDuration; + bool executed; + bool canceled; + uint48 etaSeconds; + } + + bytes32 private constant ALL_PROPOSAL_STATES_BITMAP = bytes32((2 ** (uint8(type(ProposalState).max) + 1)) - 1); + string private _name; + + mapping(uint256 proposalId => ProposalCore) private _proposals; + + // This queue keeps track of the governor operating on itself. Calls to functions protected by the {onlyGovernance} + // modifier needs to be whitelisted in this queue. Whitelisting is set in {execute}, consumed by the + // {onlyGovernance} modifier and eventually reset after {_executeOperations} completes. This ensures that the + // execution of {onlyGovernance} protected calls can only be achieved through successful proposals. + DoubleEndedQueue.Bytes32Deque private _governanceCall; + + /** + * @dev Restricts a function so it can only be executed through governance proposals. For example, governance + * parameter setters in {GovernorSettings} are protected using this modifier. + * + * The governance executing address may be different from the Governor's own address, for example it could be a + * timelock. This can be customized by modules by overriding {_executor}. The executor is only able to invoke these + * functions during the execution of the governor's {execute} function, and not under any other circumstances. Thus, + * for example, additional timelock proposers are not able to change governance parameters without going through the + * governance protocol (since v4.6). + */ + modifier onlyGovernance() { + _checkGovernance(); + _; + } + + /** + * @dev Sets the value for {name} and {version} + */ + constructor(string memory name_) EIP712(name_, version()) { + _name = name_; + } + + /** + * @dev Function to receive ETH that will be handled by the governor (disabled if executor is a third party contract) + */ + receive() external payable virtual { + if (_executor() != address(this)) { + revert GovernorDisabledDeposit(); + } + } + + /** + * @dev See {IERC165-supportsInterface}. + */ + function supportsInterface(bytes4 interfaceId) public view virtual override(IERC165, ERC165) returns (bool) { + return + interfaceId == type(IGovernor).interfaceId || + interfaceId == type(IERC1155Receiver).interfaceId || + super.supportsInterface(interfaceId); + } + + /** + * @dev See {IGovernor-name}. + */ + function name() public view virtual returns (string memory) { + return _name; + } + + /** + * @dev See {IGovernor-version}. + */ + function version() public view virtual returns (string memory) { + return "1"; + } + + /** + * @dev See {IGovernor-hashProposal}. + * + * The proposal id is produced by hashing the ABI encoded `targets` array, the `values` array, the `calldatas` array + * and the descriptionHash (bytes32 which itself is the keccak256 hash of the description string). This proposal id + * can be produced from the proposal data which is part of the {ProposalCreated} event. It can even be computed in + * advance, before the proposal is submitted. + * + * Note that the chainId and the governor address are not part of the proposal id computation. Consequently, the + * same proposal (with same operation and same description) will have the same id if submitted on multiple governors + * across multiple networks. This also means that in order to execute the same operation twice (on the same + * governor) the proposer will have to change the description in order to avoid proposal id conflicts. + */ + function hashProposal( + address[] memory targets, + uint256[] memory values, + bytes[] memory calldatas, + bytes32 descriptionHash + ) public pure virtual returns (uint256) { + return uint256(keccak256(abi.encode(targets, values, calldatas, descriptionHash))); + } + + /** + * @dev See {IGovernor-state}. + */ + function state(uint256 proposalId) public view virtual returns (ProposalState) { + // We read the struct fields into the stack at once so Solidity emits a single SLOAD + ProposalCore storage proposal = _proposals[proposalId]; + bool proposalExecuted = proposal.executed; + bool proposalCanceled = proposal.canceled; + + if (proposalExecuted) { + return ProposalState.Executed; + } + + if (proposalCanceled) { + return ProposalState.Canceled; + } + + uint256 snapshot = proposalSnapshot(proposalId); + + if (snapshot == 0) { + revert GovernorNonexistentProposal(proposalId); + } + + uint256 currentTimepoint = clock(); + + if (snapshot >= currentTimepoint) { + return ProposalState.Pending; + } + + uint256 deadline = proposalDeadline(proposalId); + + if (deadline >= currentTimepoint) { + return ProposalState.Active; + } else if (!_quorumReached(proposalId) || !_voteSucceeded(proposalId)) { + return ProposalState.Defeated; + } else if (proposalEta(proposalId) == 0) { + return ProposalState.Succeeded; + } else { + return ProposalState.Queued; + } + } + + /** + * @dev See {IGovernor-proposalThreshold}. + */ + function proposalThreshold() public view virtual returns (uint256) { + return 0; + } + + /** + * @dev See {IGovernor-proposalSnapshot}. + */ + function proposalSnapshot(uint256 proposalId) public view virtual returns (uint256) { + return _proposals[proposalId].voteStart; + } + + /** + * @dev See {IGovernor-proposalDeadline}. + */ + function proposalDeadline(uint256 proposalId) public view virtual returns (uint256) { + return _proposals[proposalId].voteStart + _proposals[proposalId].voteDuration; + } + + /** + * @dev See {IGovernor-proposalProposer}. + */ + function proposalProposer(uint256 proposalId) public view virtual returns (address) { + return _proposals[proposalId].proposer; + } + + /** + * @dev See {IGovernor-proposalEta}. + */ + function proposalEta(uint256 proposalId) public view virtual returns (uint256) { + return _proposals[proposalId].etaSeconds; + } + + /** + * @dev See {IGovernor-proposalNeedsQueuing}. + */ + function proposalNeedsQueuing(uint256) public view virtual returns (bool) { + return false; + } + + /** + * @dev Reverts if the `msg.sender` is not the executor. In case the executor is not this contract + * itself, the function reverts if `msg.data` is not whitelisted as a result of an {execute} + * operation. See {onlyGovernance}. + */ + function _checkGovernance() internal virtual { + if (_executor() != _msgSender()) { + revert GovernorOnlyExecutor(_msgSender()); + } + if (_executor() != address(this)) { + bytes32 msgDataHash = keccak256(_msgData()); + // loop until popping the expected operation - throw if deque is empty (operation not authorized) + while (_governanceCall.popFront() != msgDataHash) {} + } + } + + /** + * @dev Amount of votes already cast passes the threshold limit. + */ + function _quorumReached(uint256 proposalId) internal view virtual returns (bool); + + /** + * @dev Is the proposal successful or not. + */ + function _voteSucceeded(uint256 proposalId) internal view virtual returns (bool); + + /** + * @dev Get the voting weight of `account` at a specific `timepoint`, for a vote as described by `params`. + */ + function _getVotes(address account, uint256 timepoint, bytes memory params) internal view virtual returns (uint256); + + /** + * @dev Register a vote for `proposalId` by `account` with a given `support`, voting `weight` and voting `params`. + * + * Note: Support is generic and can represent various things depending on the voting system used. + */ + function _countVote( + uint256 proposalId, + address account, + uint8 support, + uint256 weight, + bytes memory params + ) internal virtual; + + /** + * @dev Default additional encoded parameters used by castVote methods that don't include them + * + * Note: Should be overridden by specific implementations to use an appropriate value, the + * meaning of the additional params, in the context of that implementation + */ + function _defaultParams() internal view virtual returns (bytes memory) { + return ""; + } + + /** + * @dev See {IGovernor-propose}. This function has opt-in frontrunning protection, described in {_isValidDescriptionForProposer}. + */ + function propose( + address[] memory targets, + uint256[] memory values, + bytes[] memory calldatas, + string memory description + ) public virtual returns (uint256) { + address proposer = _msgSender(); + + // check description restriction + if (!_isValidDescriptionForProposer(proposer, description)) { + revert GovernorRestrictedProposer(proposer); + } + + // check proposal threshold + uint256 proposerVotes = getVotes(proposer, clock() - 1); + uint256 votesThreshold = proposalThreshold(); + if (proposerVotes < votesThreshold) { + revert GovernorInsufficientProposerVotes(proposer, proposerVotes, votesThreshold); + } + + return _propose(targets, values, calldatas, description, proposer); + } + + /** + * @dev Internal propose mechanism. Can be overridden to add more logic on proposal creation. + * + * Emits a {IGovernor-ProposalCreated} event. + */ + function _propose( + address[] memory targets, + uint256[] memory values, + bytes[] memory calldatas, + string memory description, + address proposer + ) internal virtual returns (uint256 proposalId) { + proposalId = hashProposal(targets, values, calldatas, keccak256(bytes(description))); + + if (targets.length != values.length || targets.length != calldatas.length || targets.length == 0) { + revert GovernorInvalidProposalLength(targets.length, calldatas.length, values.length); + } + if (_proposals[proposalId].voteStart != 0) { + revert GovernorUnexpectedProposalState(proposalId, state(proposalId), bytes32(0)); + } + + uint256 snapshot = clock() + votingDelay(); + uint256 duration = votingPeriod(); + + ProposalCore storage proposal = _proposals[proposalId]; + proposal.proposer = proposer; + proposal.voteStart = SafeCast.toUint48(snapshot); + proposal.voteDuration = SafeCast.toUint32(duration); + + emit ProposalCreated( + proposalId, + proposer, + targets, + values, + new string[](targets.length), + calldatas, + snapshot, + snapshot + duration, + description + ); + + // Using a named return variable to avoid stack too deep errors + } + + /** + * @dev See {IGovernor-queue}. + */ + function queue( + address[] memory targets, + uint256[] memory values, + bytes[] memory calldatas, + bytes32 descriptionHash + ) public virtual returns (uint256) { + uint256 proposalId = hashProposal(targets, values, calldatas, descriptionHash); + + _validateStateBitmap(proposalId, _encodeStateBitmap(ProposalState.Succeeded)); + + uint48 etaSeconds = _queueOperations(proposalId, targets, values, calldatas, descriptionHash); + + if (etaSeconds != 0) { + _proposals[proposalId].etaSeconds = etaSeconds; + emit ProposalQueued(proposalId, etaSeconds); + } else { + revert GovernorQueueNotImplemented(); + } + + return proposalId; + } + + /** + * @dev Internal queuing mechanism. Can be overridden (without a super call) to modify the way queuing is + * performed (for example adding a vault/timelock). + * + * This is empty by default, and must be overridden to implement queuing. + * + * This function returns a timestamp that describes the expected ETA for execution. If the returned value is 0 + * (which is the default value), the core will consider queueing did not succeed, and the public {queue} function + * will revert. + * + * NOTE: Calling this function directly will NOT check the current state of the proposal, or emit the + * `ProposalQueued` event. Queuing a proposal should be done using {queue}. + */ + function _queueOperations( + uint256 /*proposalId*/, + address[] memory /*targets*/, + uint256[] memory /*values*/, + bytes[] memory /*calldatas*/, + bytes32 /*descriptionHash*/ + ) internal virtual returns (uint48) { + return 0; + } + + /** + * @dev See {IGovernor-execute}. + */ + function execute( + address[] memory targets, + uint256[] memory values, + bytes[] memory calldatas, + bytes32 descriptionHash + ) public payable virtual returns (uint256) { + uint256 proposalId = hashProposal(targets, values, calldatas, descriptionHash); + + _validateStateBitmap( + proposalId, + _encodeStateBitmap(ProposalState.Succeeded) | _encodeStateBitmap(ProposalState.Queued) + ); + + // mark as executed before calls to avoid reentrancy + _proposals[proposalId].executed = true; + + // before execute: register governance call in queue. + if (_executor() != address(this)) { + for (uint256 i = 0; i < targets.length; ++i) { + if (targets[i] == address(this)) { + _governanceCall.pushBack(keccak256(calldatas[i])); + } + } + } + + _executeOperations(proposalId, targets, values, calldatas, descriptionHash); + + // after execute: cleanup governance call queue. + if (_executor() != address(this) && !_governanceCall.empty()) { + _governanceCall.clear(); + } + + emit ProposalExecuted(proposalId); + + return proposalId; + } + + /** + * @dev Internal execution mechanism. Can be overridden (without a super call) to modify the way execution is + * performed (for example adding a vault/timelock). + * + * NOTE: Calling this function directly will NOT check the current state of the proposal, set the executed flag to + * true or emit the `ProposalExecuted` event. Executing a proposal should be done using {execute} or {_execute}. + */ + function _executeOperations( + uint256 /* proposalId */, + address[] memory targets, + uint256[] memory values, + bytes[] memory calldatas, + bytes32 /*descriptionHash*/ + ) internal virtual { + for (uint256 i = 0; i < targets.length; ++i) { + (bool success, bytes memory returndata) = targets[i].call{value: values[i]}(calldatas[i]); + Address.verifyCallResult(success, returndata); + } + } + + /** + * @dev See {IGovernor-cancel}. + */ + function cancel( + address[] memory targets, + uint256[] memory values, + bytes[] memory calldatas, + bytes32 descriptionHash + ) public virtual returns (uint256) { + // The proposalId will be recomputed in the `_cancel` call further down. However we need the value before we + // do the internal call, because we need to check the proposal state BEFORE the internal `_cancel` call + // changes it. The `hashProposal` duplication has a cost that is limited, and that we accept. + uint256 proposalId = hashProposal(targets, values, calldatas, descriptionHash); + + // public cancel restrictions (on top of existing _cancel restrictions). + _validateStateBitmap(proposalId, _encodeStateBitmap(ProposalState.Pending)); + if (_msgSender() != proposalProposer(proposalId)) { + revert GovernorOnlyProposer(_msgSender()); + } + + return _cancel(targets, values, calldatas, descriptionHash); + } + + /** + * @dev Internal cancel mechanism with minimal restrictions. A proposal can be cancelled in any state other than + * Canceled, Expired, or Executed. Once cancelled a proposal can't be re-submitted. + * + * Emits a {IGovernor-ProposalCanceled} event. + */ + function _cancel( + address[] memory targets, + uint256[] memory values, + bytes[] memory calldatas, + bytes32 descriptionHash + ) internal virtual returns (uint256) { + uint256 proposalId = hashProposal(targets, values, calldatas, descriptionHash); + + _validateStateBitmap( + proposalId, + ALL_PROPOSAL_STATES_BITMAP ^ + _encodeStateBitmap(ProposalState.Canceled) ^ + _encodeStateBitmap(ProposalState.Expired) ^ + _encodeStateBitmap(ProposalState.Executed) + ); + + _proposals[proposalId].canceled = true; + emit ProposalCanceled(proposalId); + + return proposalId; + } + + /** + * @dev See {IGovernor-getVotes}. + */ + function getVotes(address account, uint256 timepoint) public view virtual returns (uint256) { + return _getVotes(account, timepoint, _defaultParams()); + } + + /** + * @dev See {IGovernor-getVotesWithParams}. + */ + function getVotesWithParams( + address account, + uint256 timepoint, + bytes memory params + ) public view virtual returns (uint256) { + return _getVotes(account, timepoint, params); + } + + /** + * @dev See {IGovernor-castVote}. + */ + function castVote(uint256 proposalId, uint8 support) public virtual returns (uint256) { + address voter = _msgSender(); + return _castVote(proposalId, voter, support, ""); + } + + /** + * @dev See {IGovernor-castVoteWithReason}. + */ + function castVoteWithReason( + uint256 proposalId, + uint8 support, + string calldata reason + ) public virtual returns (uint256) { + address voter = _msgSender(); + return _castVote(proposalId, voter, support, reason); + } + + /** + * @dev See {IGovernor-castVoteWithReasonAndParams}. + */ + function castVoteWithReasonAndParams( + uint256 proposalId, + uint8 support, + string calldata reason, + bytes memory params + ) public virtual returns (uint256) { + address voter = _msgSender(); + return _castVote(proposalId, voter, support, reason, params); + } + + /** + * @dev See {IGovernor-castVoteBySig}. + */ + function castVoteBySig( + uint256 proposalId, + uint8 support, + address voter, + bytes memory signature + ) public virtual returns (uint256) { + bool valid = SignatureChecker.isValidSignatureNow( + voter, + _hashTypedDataV4(keccak256(abi.encode(BALLOT_TYPEHASH, proposalId, support, voter, _useNonce(voter)))), + signature + ); + + if (!valid) { + revert GovernorInvalidSignature(voter); + } + + return _castVote(proposalId, voter, support, ""); + } + + /** + * @dev See {IGovernor-castVoteWithReasonAndParamsBySig}. + */ + function castVoteWithReasonAndParamsBySig( + uint256 proposalId, + uint8 support, + address voter, + string calldata reason, + bytes memory params, + bytes memory signature + ) public virtual returns (uint256) { + bool valid = SignatureChecker.isValidSignatureNow( + voter, + _hashTypedDataV4( + keccak256( + abi.encode( + EXTENDED_BALLOT_TYPEHASH, + proposalId, + support, + voter, + _useNonce(voter), + keccak256(bytes(reason)), + keccak256(params) + ) + ) + ), + signature + ); + + if (!valid) { + revert GovernorInvalidSignature(voter); + } + + return _castVote(proposalId, voter, support, reason, params); + } + + /** + * @dev Internal vote casting mechanism: Check that the vote is pending, that it has not been cast yet, retrieve + * voting weight using {IGovernor-getVotes} and call the {_countVote} internal function. Uses the _defaultParams(). + * + * Emits a {IGovernor-VoteCast} event. + */ + function _castVote( + uint256 proposalId, + address account, + uint8 support, + string memory reason + ) internal virtual returns (uint256) { + return _castVote(proposalId, account, support, reason, _defaultParams()); + } + + /** + * @dev Internal vote casting mechanism: Check that the vote is pending, that it has not been cast yet, retrieve + * voting weight using {IGovernor-getVotes} and call the {_countVote} internal function. + * + * Emits a {IGovernor-VoteCast} event. + */ + function _castVote( + uint256 proposalId, + address account, + uint8 support, + string memory reason, + bytes memory params + ) internal virtual returns (uint256) { + _validateStateBitmap(proposalId, _encodeStateBitmap(ProposalState.Active)); + + uint256 weight = _getVotes(account, proposalSnapshot(proposalId), params); + _countVote(proposalId, account, support, weight, params); + + if (params.length == 0) { + emit VoteCast(account, proposalId, support, weight, reason); + } else { + emit VoteCastWithParams(account, proposalId, support, weight, reason, params); + } + + return weight; + } + + /** + * @dev Relays a transaction or function call to an arbitrary target. In cases where the governance executor + * is some contract other than the governor itself, like when using a timelock, this function can be invoked + * in a governance proposal to recover tokens or Ether that was sent to the governor contract by mistake. + * Note that if the executor is simply the governor itself, use of `relay` is redundant. + */ + function relay(address target, uint256 value, bytes calldata data) external payable virtual onlyGovernance { + (bool success, bytes memory returndata) = target.call{value: value}(data); + Address.verifyCallResult(success, returndata); + } + + /** + * @dev Address through which the governor executes action. Will be overloaded by module that execute actions + * through another contract such as a timelock. + */ + function _executor() internal view virtual returns (address) { + return address(this); + } + + /** + * @dev See {IERC721Receiver-onERC721Received}. + * Receiving tokens is disabled if the governance executor is other than the governor itself (eg. when using with a timelock). + */ + function onERC721Received(address, address, uint256, bytes memory) public virtual returns (bytes4) { + if (_executor() != address(this)) { + revert GovernorDisabledDeposit(); + } + return this.onERC721Received.selector; + } + + /** + * @dev See {IERC1155Receiver-onERC1155Received}. + * Receiving tokens is disabled if the governance executor is other than the governor itself (eg. when using with a timelock). + */ + function onERC1155Received(address, address, uint256, uint256, bytes memory) public virtual returns (bytes4) { + if (_executor() != address(this)) { + revert GovernorDisabledDeposit(); + } + return this.onERC1155Received.selector; + } + + /** + * @dev See {IERC1155Receiver-onERC1155BatchReceived}. + * Receiving tokens is disabled if the governance executor is other than the governor itself (eg. when using with a timelock). + */ + function onERC1155BatchReceived( + address, + address, + uint256[] memory, + uint256[] memory, + bytes memory + ) public virtual returns (bytes4) { + if (_executor() != address(this)) { + revert GovernorDisabledDeposit(); + } + return this.onERC1155BatchReceived.selector; + } + + /** + * @dev Encodes a `ProposalState` into a `bytes32` representation where each bit enabled corresponds to + * the underlying position in the `ProposalState` enum. For example: + * + * 0x000...10000 + * ^^^^^^------ ... + * ^----- Succeeded + * ^---- Defeated + * ^--- Canceled + * ^-- Active + * ^- Pending + */ + function _encodeStateBitmap(ProposalState proposalState) internal pure returns (bytes32) { + return bytes32(1 << uint8(proposalState)); + } + + /** + * @dev Check that the current state of a proposal matches the requirements described by the `allowedStates` bitmap. + * This bitmap should be built using `_encodeStateBitmap`. + * + * If requirements are not met, reverts with a {GovernorUnexpectedProposalState} error. + */ + function _validateStateBitmap(uint256 proposalId, bytes32 allowedStates) private view returns (ProposalState) { + ProposalState currentState = state(proposalId); + if (_encodeStateBitmap(currentState) & allowedStates == bytes32(0)) { + revert GovernorUnexpectedProposalState(proposalId, currentState, allowedStates); + } + return currentState; + } + + /* + * @dev Check if the proposer is authorized to submit a proposal with the given description. + * + * If the proposal description ends with `#proposer=0x???`, where `0x???` is an address written as a hex string + * (case insensitive), then the submission of this proposal will only be authorized to said address. + * + * This is used for frontrunning protection. By adding this pattern at the end of their proposal, one can ensure + * that no other address can submit the same proposal. An attacker would have to either remove or change that part, + * which would result in a different proposal id. + * + * If the description does not match this pattern, it is unrestricted and anyone can submit it. This includes: + * - If the `0x???` part is not a valid hex string. + * - If the `0x???` part is a valid hex string, but does not contain exactly 40 hex digits. + * - If it ends with the expected suffix followed by newlines or other whitespace. + * - If it ends with some other similar suffix, e.g. `#other=abc`. + * - If it does not end with any such suffix. + */ + function _isValidDescriptionForProposer( + address proposer, + string memory description + ) internal view virtual returns (bool) { + uint256 len = bytes(description).length; + + // Length is too short to contain a valid proposer suffix + if (len < 52) { + return true; + } + + // Extract what would be the `#proposer=0x` marker beginning the suffix + bytes12 marker; + assembly { + // - Start of the string contents in memory = description + 32 + // - First character of the marker = len - 52 + // - Length of "#proposer=0x0000000000000000000000000000000000000000" = 52 + // - We read the memory word starting at the first character of the marker: + // - (description + 32) + (len - 52) = description + (len - 20) + // - Note: Solidity will ignore anything past the first 12 bytes + marker := mload(add(description, sub(len, 20))) + } + + // If the marker is not found, there is no proposer suffix to check + if (marker != bytes12("#proposer=0x")) { + return true; + } + + // Parse the 40 characters following the marker as uint160 + uint160 recovered = 0; + for (uint256 i = len - 40; i < len; ++i) { + (bool isHex, uint8 value) = _tryHexToUint(bytes(description)[i]); + // If any of the characters is not a hex digit, ignore the suffix entirely + if (!isHex) { + return true; + } + recovered = (recovered << 4) | value; + } + + return recovered == uint160(proposer); + } + + /** + * @dev Try to parse a character from a string as a hex value. Returns `(true, value)` if the char is in + * `[0-9a-fA-F]` and `(false, 0)` otherwise. Value is guaranteed to be in the range `0 <= value < 16` + */ + function _tryHexToUint(bytes1 char) private pure returns (bool, uint8) { + uint8 c = uint8(char); + unchecked { + // Case 0-9 + if (47 < c && c < 58) { + return (true, c - 48); + } + // Case A-F + else if (64 < c && c < 71) { + return (true, c - 55); + } + // Case a-f + else if (96 < c && c < 103) { + return (true, c - 87); + } + // Else: not a hex char + else { + return (false, 0); + } + } + } + + /** + * @inheritdoc IERC6372 + */ + function clock() public view virtual returns (uint48); + + /** + * @inheritdoc IERC6372 + */ + // solhint-disable-next-line func-name-mixedcase + function CLOCK_MODE() public view virtual returns (string memory); + + /** + * @inheritdoc IGovernor + */ + function votingDelay() public view virtual returns (uint256); + + /** + * @inheritdoc IGovernor + */ + function votingPeriod() public view virtual returns (uint256); + + /** + * @inheritdoc IGovernor + */ + function quorum(uint256 timepoint) public view virtual returns (uint256); +} diff --git a/contracts/governance/IGovernor.sol b/contracts/governance/IGovernor.sol new file mode 100644 index 000000000..e0fcc8f78 --- /dev/null +++ b/contracts/governance/IGovernor.sol @@ -0,0 +1,427 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (governance/IGovernor.sol) + +pragma solidity ^0.8.20; + +import {IERC165} from "../interfaces/IERC165.sol"; +import {IERC6372} from "../interfaces/IERC6372.sol"; + +/** + * @dev Interface of the {Governor} core. + */ +interface IGovernor is IERC165, IERC6372 { + enum ProposalState { + Pending, + Active, + Canceled, + Defeated, + Succeeded, + Queued, + Expired, + Executed + } + + /** + * @dev Empty proposal or a mismatch between the parameters length for a proposal call. + */ + error GovernorInvalidProposalLength(uint256 targets, uint256 calldatas, uint256 values); + + /** + * @dev The vote was already cast. + */ + error GovernorAlreadyCastVote(address voter); + + /** + * @dev Token deposits are disabled in this contract. + */ + error GovernorDisabledDeposit(); + + /** + * @dev The `account` is not a proposer. + */ + error GovernorOnlyProposer(address account); + + /** + * @dev The `account` is not the governance executor. + */ + error GovernorOnlyExecutor(address account); + + /** + * @dev The `proposalId` doesn't exist. + */ + error GovernorNonexistentProposal(uint256 proposalId); + + /** + * @dev The current state of a proposal is not the required for performing an operation. + * The `expectedStates` is a bitmap with the bits enabled for each ProposalState enum position + * counting from right to left. + * + * NOTE: If `expectedState` is `bytes32(0)`, the proposal is expected to not be in any state (i.e. not exist). + * This is the case when a proposal that is expected to be unset is already initiated (the proposal is duplicated). + * + * See {Governor-_encodeStateBitmap}. + */ + error GovernorUnexpectedProposalState(uint256 proposalId, ProposalState current, bytes32 expectedStates); + + /** + * @dev The voting period set is not a valid period. + */ + error GovernorInvalidVotingPeriod(uint256 votingPeriod); + + /** + * @dev The `proposer` does not have the required votes to create a proposal. + */ + error GovernorInsufficientProposerVotes(address proposer, uint256 votes, uint256 threshold); + + /** + * @dev The `proposer` is not allowed to create a proposal. + */ + error GovernorRestrictedProposer(address proposer); + + /** + * @dev The vote type used is not valid for the corresponding counting module. + */ + error GovernorInvalidVoteType(); + + /** + * @dev Queue operation is not implemented for this governor. Execute should be called directly. + */ + error GovernorQueueNotImplemented(); + + /** + * @dev The proposal hasn't been queued yet. + */ + error GovernorNotQueuedProposal(uint256 proposalId); + + /** + * @dev The proposal has already been queued. + */ + error GovernorAlreadyQueuedProposal(uint256 proposalId); + + /** + * @dev The provided signature is not valid for the expected `voter`. + * If the `voter` is a contract, the signature is not valid using {IERC1271-isValidSignature}. + */ + error GovernorInvalidSignature(address voter); + + /** + * @dev Emitted when a proposal is created. + */ + event ProposalCreated( + uint256 proposalId, + address proposer, + address[] targets, + uint256[] values, + string[] signatures, + bytes[] calldatas, + uint256 voteStart, + uint256 voteEnd, + string description + ); + + /** + * @dev Emitted when a proposal is queued. + */ + event ProposalQueued(uint256 proposalId, uint256 etaSeconds); + + /** + * @dev Emitted when a proposal is executed. + */ + event ProposalExecuted(uint256 proposalId); + + /** + * @dev Emitted when a proposal is canceled. + */ + event ProposalCanceled(uint256 proposalId); + + /** + * @dev Emitted when a vote is cast without params. + * + * Note: `support` values should be seen as buckets. Their interpretation depends on the voting module used. + */ + event VoteCast(address indexed voter, uint256 proposalId, uint8 support, uint256 weight, string reason); + + /** + * @dev Emitted when a vote is cast with params. + * + * Note: `support` values should be seen as buckets. Their interpretation depends on the voting module used. + * `params` are additional encoded parameters. Their interpepretation also depends on the voting module used. + */ + event VoteCastWithParams( + address indexed voter, + uint256 proposalId, + uint8 support, + uint256 weight, + string reason, + bytes params + ); + + /** + * @notice module:core + * @dev Name of the governor instance (used in building the ERC712 domain separator). + */ + function name() external view returns (string memory); + + /** + * @notice module:core + * @dev Version of the governor instance (used in building the ERC712 domain separator). Default: "1" + */ + function version() external view returns (string memory); + + /** + * @notice module:voting + * @dev A description of the possible `support` values for {castVote} and the way these votes are counted, meant to + * be consumed by UIs to show correct vote options and interpret the results. The string is a URL-encoded sequence of + * key-value pairs that each describe one aspect, for example `support=bravo&quorum=for,abstain`. + * + * There are 2 standard keys: `support` and `quorum`. + * + * - `support=bravo` refers to the vote options 0 = Against, 1 = For, 2 = Abstain, as in `GovernorBravo`. + * - `quorum=bravo` means that only For votes are counted towards quorum. + * - `quorum=for,abstain` means that both For and Abstain votes are counted towards quorum. + * + * If a counting module makes use of encoded `params`, it should include this under a `params` key with a unique + * name that describes the behavior. For example: + * + * - `params=fractional` might refer to a scheme where votes are divided fractionally between for/against/abstain. + * - `params=erc721` might refer to a scheme where specific NFTs are delegated to vote. + * + * NOTE: The string can be decoded by the standard + * https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams[`URLSearchParams`] + * JavaScript class. + */ + // solhint-disable-next-line func-name-mixedcase + function COUNTING_MODE() external view returns (string memory); + + /** + * @notice module:core + * @dev Hashing function used to (re)build the proposal id from the proposal details.. + */ + function hashProposal( + address[] memory targets, + uint256[] memory values, + bytes[] memory calldatas, + bytes32 descriptionHash + ) external pure returns (uint256); + + /** + * @notice module:core + * @dev Current state of a proposal, following Compound's convention + */ + function state(uint256 proposalId) external view returns (ProposalState); + + /** + * @notice module:core + * @dev The number of votes required in order for a voter to become a proposer. + */ + function proposalThreshold() external view returns (uint256); + + /** + * @notice module:core + * @dev Timepoint used to retrieve user's votes and quorum. If using block number (as per Compound's Comp), the + * snapshot is performed at the end of this block. Hence, voting for this proposal starts at the beginning of the + * following block. + */ + function proposalSnapshot(uint256 proposalId) external view returns (uint256); + + /** + * @notice module:core + * @dev Timepoint at which votes close. If using block number, votes close at the end of this block, so it is + * possible to cast a vote during this block. + */ + function proposalDeadline(uint256 proposalId) external view returns (uint256); + + /** + * @notice module:core + * @dev The account that created a proposal. + */ + function proposalProposer(uint256 proposalId) external view returns (address); + + /** + * @notice module:core + * @dev The time when a queued proposal becomes executable ("ETA"). Unlike {proposalSnapshot} and + * {proposalDeadline}, this doesn't use the governor clock, and instead relies on the executor's clock which may be + * different. In most cases this will be a timestamp. + */ + function proposalEta(uint256 proposalId) external view returns (uint256); + + /** + * @notice module:core + * @dev Whether a proposal needs to be queued before execution. + */ + function proposalNeedsQueuing(uint256 proposalId) external view returns (bool); + + /** + * @notice module:user-config + * @dev Delay, between the proposal is created and the vote starts. The unit this duration is expressed in depends + * on the clock (see EIP-6372) this contract uses. + * + * This can be increased to leave time for users to buy voting power, or delegate it, before the voting of a + * proposal starts. + * + * NOTE: While this interface returns a uint256, timepoints are stored as uint48 following the ERC-6372 clock type. + * Consequently this value must fit in a uint48 (when added to the current clock). See {IERC6372-clock}. + */ + function votingDelay() external view returns (uint256); + + /** + * @notice module:user-config + * @dev Delay between the vote start and vote end. The unit this duration is expressed in depends on the clock + * (see EIP-6372) this contract uses. + * + * NOTE: The {votingDelay} can delay the start of the vote. This must be considered when setting the voting + * duration compared to the voting delay. + * + * NOTE: This value is stored when the proposal is submitted so that possible changes to the value do not affect + * proposals that have already been submitted. The type used to save it is a uint32. Consequently, while this + * interface returns a uint256, the value it returns should fit in a uint32. + */ + function votingPeriod() external view returns (uint256); + + /** + * @notice module:user-config + * @dev Minimum number of cast voted required for a proposal to be successful. + * + * NOTE: The `timepoint` parameter corresponds to the snapshot used for counting vote. This allows to scale the + * quorum depending on values such as the totalSupply of a token at this timepoint (see {ERC20Votes}). + */ + function quorum(uint256 timepoint) external view returns (uint256); + + /** + * @notice module:reputation + * @dev Voting power of an `account` at a specific `timepoint`. + * + * Note: this can be implemented in a number of ways, for example by reading the delegated balance from one (or + * multiple), {ERC20Votes} tokens. + */ + function getVotes(address account, uint256 timepoint) external view returns (uint256); + + /** + * @notice module:reputation + * @dev Voting power of an `account` at a specific `timepoint` given additional encoded parameters. + */ + function getVotesWithParams( + address account, + uint256 timepoint, + bytes memory params + ) external view returns (uint256); + + /** + * @notice module:voting + * @dev Returns whether `account` has cast a vote on `proposalId`. + */ + function hasVoted(uint256 proposalId, address account) external view returns (bool); + + /** + * @dev Create a new proposal. Vote start after a delay specified by {IGovernor-votingDelay} and lasts for a + * duration specified by {IGovernor-votingPeriod}. + * + * Emits a {ProposalCreated} event. + */ + function propose( + address[] memory targets, + uint256[] memory values, + bytes[] memory calldatas, + string memory description + ) external returns (uint256 proposalId); + + /** + * @dev Queue a proposal. Some governors require this step to be performed before execution can happen. If queuing + * is not necessary, this function may revert. + * Queuing a proposal requires the quorum to be reached, the vote to be successful, and the deadline to be reached. + * + * Emits a {ProposalQueued} event. + */ + function queue( + address[] memory targets, + uint256[] memory values, + bytes[] memory calldatas, + bytes32 descriptionHash + ) external returns (uint256 proposalId); + + /** + * @dev Execute a successful proposal. This requires the quorum to be reached, the vote to be successful, and the + * deadline to be reached. Depending on the governor it might also be required that the proposal was queued and + * that some delay passed. + * + * Emits a {ProposalExecuted} event. + * + * NOTE: Some modules can modify the requirements for execution, for example by adding an additional timelock. + */ + function execute( + address[] memory targets, + uint256[] memory values, + bytes[] memory calldatas, + bytes32 descriptionHash + ) external payable returns (uint256 proposalId); + + /** + * @dev Cancel a proposal. A proposal is cancellable by the proposer, but only while it is Pending state, i.e. + * before the vote starts. + * + * Emits a {ProposalCanceled} event. + */ + function cancel( + address[] memory targets, + uint256[] memory values, + bytes[] memory calldatas, + bytes32 descriptionHash + ) external returns (uint256 proposalId); + + /** + * @dev Cast a vote + * + * Emits a {VoteCast} event. + */ + function castVote(uint256 proposalId, uint8 support) external returns (uint256 balance); + + /** + * @dev Cast a vote with a reason + * + * Emits a {VoteCast} event. + */ + function castVoteWithReason( + uint256 proposalId, + uint8 support, + string calldata reason + ) external returns (uint256 balance); + + /** + * @dev Cast a vote with a reason and additional encoded parameters + * + * Emits a {VoteCast} or {VoteCastWithParams} event depending on the length of params. + */ + function castVoteWithReasonAndParams( + uint256 proposalId, + uint8 support, + string calldata reason, + bytes memory params + ) external returns (uint256 balance); + + /** + * @dev Cast a vote using the voter's signature, including ERC-1271 signature support. + * + * Emits a {VoteCast} event. + */ + function castVoteBySig( + uint256 proposalId, + uint8 support, + address voter, + bytes memory signature + ) external returns (uint256 balance); + + /** + * @dev Cast a vote with a reason and additional encoded parameters using the voter's signature, + * including ERC-1271 signature support. + * + * Emits a {VoteCast} or {VoteCastWithParams} event depending on the length of params. + */ + function castVoteWithReasonAndParamsBySig( + uint256 proposalId, + uint8 support, + address voter, + string calldata reason, + bytes memory params, + bytes memory signature + ) external returns (uint256 balance); +} diff --git a/contracts/governance/README.adoc b/contracts/governance/README.adoc new file mode 100644 index 000000000..5b38c4d53 --- /dev/null +++ b/contracts/governance/README.adoc @@ -0,0 +1,167 @@ += Governance + +[.readme-notice] +NOTE: This document is better viewed at https://docs.openzeppelin.com/contracts/api/governance + +This directory includes primitives for on-chain governance. + +== Governor + +This modular system of Governor contracts allows the deployment on-chain voting protocols similar to https://compound.finance/docs/governance[Compound's Governor Alpha & Bravo] and beyond, through the ability to easily customize multiple aspects of the protocol. + +[TIP] +==== +For a guided experience, set up your Governor contract using https://wizard.openzeppelin.com/#governor[Contracts Wizard]. + +For a written walkthrough, check out our guide on xref:ROOT:governance.adoc[How to set up on-chain governance]. +==== + +* {Governor}: The core contract that contains all the logic and primitives. It is abstract and requires choosing one of each of the modules below, or custom ones. + +Votes modules determine the source of voting power, and sometimes quorum number. + +* {GovernorVotes}: Extracts voting weight from an {ERC20Votes}, or since v4.5 an {ERC721Votes} token. + +* {GovernorVotesQuorumFraction}: Combines with `GovernorVotes` to set the quorum as a fraction of the total token supply. + +Counting modules determine valid voting options. + +* {GovernorCountingSimple}: Simple voting mechanism with 3 voting options: Against, For and Abstain. + +Timelock extensions add a delay for governance decisions to be executed. The workflow is extended to require a `queue` step before execution. With these modules, proposals are executed by the external timelock contract, thus it is the timelock that has to hold the assets that are being governed. + +* {GovernorTimelockControl}: Connects with an instance of {TimelockController}. Allows multiple proposers and executors, in addition to the Governor itself. + +* {GovernorTimelockCompound}: Connects with an instance of Compound's https://github.com/compound-finance/compound-protocol/blob/master/contracts/Timelock.sol[`Timelock`] contract. + +Other extensions can customize the behavior or interface in multiple ways. + +* {GovernorStorage}: Stores the proposal details onchain and provides enumerability of the proposals. This can be useful for some L2 chains where storage is cheap compared to calldata. + +* {GovernorSettings}: Manages some of the settings (voting delay, voting period duration, and proposal threshold) in a way that can be updated through a governance proposal, without requiring an upgrade. + +* {GovernorPreventLateQuorum}: Ensures there is a minimum voting period after quorum is reached as a security protection against large voters. + +In addition to modules and extensions, the core contract requires a few virtual functions to be implemented to your particular specifications: + +* <>: Delay (in EIP-6372 clock) since the proposal is submitted until voting power is fixed and voting starts. This can be used to enforce a delay after a proposal is published for users to buy tokens, or delegate their votes. +* <>: Delay (in EIP-6372 clock) since the proposal starts until voting ends. +* <>: Quorum required for a proposal to be successful. This function includes a `timepoint` argument (see EIP-6372) so the quorum can adapt through time, for example, to follow a token's `totalSupply`. + +NOTE: Functions of the `Governor` contract do not include access control. If you want to restrict access, you should add these checks by overloading the particular functions. Among these, {Governor-_cancel} is internal by default, and you will have to expose it (with the right access control mechanism) yourself if this function is needed. + +=== Core + +{{IGovernor}} + +{{Governor}} + +=== Modules + +{{GovernorCountingSimple}} + +{{GovernorVotes}} + +{{GovernorVotesQuorumFraction}} + +=== Extensions + +{{GovernorTimelockControl}} + +{{GovernorTimelockCompound}} + +{{GovernorSettings}} + +{{GovernorPreventLateQuorum}} + +{{GovernorStorage}} + +== Utils + +{{Votes}} + +== Timelock + +In a governance system, the {TimelockController} contract is in charge of introducing a delay between a proposal and its execution. It can be used with or without a {Governor}. + +{{TimelockController}} + +[[timelock-terminology]] +==== Terminology + +* *Operation:* A transaction (or a set of transactions) that is the subject of the timelock. It has to be scheduled by a proposer and executed by an executor. The timelock enforces a minimum delay between the proposition and the execution (see xref:access-control.adoc#operation_lifecycle[operation lifecycle]). If the operation contains multiple transactions (batch mode), they are executed atomically. Operations are identified by the hash of their content. +* *Operation status:* +** *Unset:* An operation that is not part of the timelock mechanism. +** *Waiting:* An operation that has been scheduled, before the timer expires. +** *Ready:* An operation that has been scheduled, after the timer expires. +** *Pending:* An operation that is either waiting or ready. +** *Done:* An operation that has been executed. +* *Predecessor*: An (optional) dependency between operations. An operation can depend on another operation (its predecessor), forcing the execution order of these two operations. +* *Role*: +** *Admin:* An address (smart contract or EOA) that is in charge of granting the roles of Proposer and Executor. +** *Proposer:* An address (smart contract or EOA) that is in charge of scheduling (and cancelling) operations. +** *Executor:* An address (smart contract or EOA) that is in charge of executing operations once the timelock has expired. This role can be given to the zero address to allow anyone to execute operations. + +[[timelock-operation]] +==== Operation structure + +Operation executed by the xref:api:governance.adoc#TimelockController[`TimelockController`] can contain one or multiple subsequent calls. Depending on whether you need to multiple calls to be executed atomically, you can either use simple or batched operations. + +Both operations contain: + +* *Target*, the address of the smart contract that the timelock should operate on. +* *Value*, in wei, that should be sent with the transaction. Most of the time this will be 0. Ether can be deposited before-end or passed along when executing the transaction. +* *Data*, containing the encoded function selector and parameters of the call. This can be produced using a number of tools. For example, a maintenance operation granting role `ROLE` to `ACCOUNT` can be encoded using web3js as follows: + +```javascript +const data = timelock.contract.methods.grantRole(ROLE, ACCOUNT).encodeABI() +``` + +* *Predecessor*, that specifies a dependency between operations. This dependency is optional. Use `bytes32(0)` if the operation does not have any dependency. +* *Salt*, used to disambiguate two otherwise identical operations. This can be any random value. + +In the case of batched operations, `target`, `value` and `data` are specified as arrays, which must be of the same length. + +[[timelock-operation-lifecycle]] +==== Operation lifecycle + +Timelocked operations are identified by a unique id (their hash) and follow a specific lifecycle: + +`Unset` -> `Pending` -> `Pending` + `Ready` -> `Done` + +* By calling xref:api:governance.adoc#TimelockController-schedule-address-uint256-bytes-bytes32-bytes32-uint256-[`schedule`] (or xref:api:governance.adoc#TimelockController-scheduleBatch-address---uint256---bytes---bytes32-bytes32-uint256-[`scheduleBatch`]), a proposer moves the operation from the `Unset` to the `Pending` state. This starts a timer that must be longer than the minimum delay. The timer expires at a timestamp accessible through the xref:api:governance.adoc#TimelockController-getTimestamp-bytes32-[`getTimestamp`] method. +* Once the timer expires, the operation automatically gets the `Ready` state. At this point, it can be executed. +* By calling xref:api:governance.adoc#TimelockController-TimelockController-execute-address-uint256-bytes-bytes32-bytes32-[`execute`] (or xref:api:governance.adoc#TimelockController-executeBatch-address---uint256---bytes---bytes32-bytes32-[`executeBatch`]), an executor triggers the operation's underlying transactions and moves it to the `Done` state. If the operation has a predecessor, it has to be in the `Done` state for this transition to succeed. +* xref:api:governance.adoc#TimelockController-TimelockController-cancel-bytes32-[`cancel`] allows proposers to cancel any `Pending` operation. This resets the operation to the `Unset` state. It is thus possible for a proposer to re-schedule an operation that has been cancelled. In this case, the timer restarts when the operation is re-scheduled. + +Operations status can be queried using the functions: + +* xref:api:governance.adoc#TimelockController-isOperationPending-bytes32-[`isOperationPending(bytes32)`] +* xref:api:governance.adoc#TimelockController-isOperationReady-bytes32-[`isOperationReady(bytes32)`] +* xref:api:governance.adoc#TimelockController-isOperationDone-bytes32-[`isOperationDone(bytes32)`] + +[[timelock-roles]] +==== Roles + +[[timelock-admin]] +===== Admin + +The admins are in charge of managing proposers and executors. For the timelock to be self-governed, this role should only be given to the timelock itself. Upon deployment, the admin role can be granted to any address (in addition to the timelock itself). After further configuration and testing, this optional admin should renounce its role such that all further maintenance operations have to go through the timelock process. + +[[timelock-proposer]] +===== Proposer + +The proposers are in charge of scheduling (and cancelling) operations. This is a critical role, that should be given to governing entities. This could be an EOA, a multisig, or a DAO. + +WARNING: *Proposer fight:* Having multiple proposers, while providing redundancy in case one becomes unavailable, can be dangerous. As proposer have their say on all operations, they could cancel operations they disagree with, including operations to remove them for the proposers. + +This role is identified by the *PROPOSER_ROLE* value: `0xb09aa5aeb3702cfd50b6b62bc4532604938f21248a27a1d5ca736082b6819cc1` + +[[timelock-executor]] +===== Executor + +The executors are in charge of executing the operations scheduled by the proposers once the timelock expires. Logic dictates that multisig or DAO that are proposers should also be executors in order to guarantee operations that have been scheduled will eventually be executed. However, having additional executors can reduce the cost (the executing transaction does not require validation by the multisig or DAO that proposed it), while ensuring whoever is in charge of execution cannot trigger actions that have not been scheduled by the proposers. Alternatively, it is possible to allow _any_ address to execute a proposal once the timelock has expired by granting the executor role to the zero address. + +This role is identified by the *EXECUTOR_ROLE* value: `0xd8aa0f3194971a2a116679f7c2090f6939c8d4e01a2a8d7e41d55e5351469e63` + +WARNING: A live contract without at least one proposer and one executor is locked. Make sure these roles are filled by reliable entities before the deployer renounces its administrative rights in favour of the timelock contract itself. See the {AccessControl} documentation to learn more about role management. diff --git a/contracts/governance/TimelockController.sol b/contracts/governance/TimelockController.sol new file mode 100644 index 000000000..53596d396 --- /dev/null +++ b/contracts/governance/TimelockController.sol @@ -0,0 +1,472 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (governance/TimelockController.sol) + +pragma solidity ^0.8.20; + +import {AccessControl} from "../access/AccessControl.sol"; +import {ERC721Holder} from "../token/ERC721/utils/ERC721Holder.sol"; +import {ERC1155Holder} from "../token/ERC1155/utils/ERC1155Holder.sol"; +import {Address} from "../utils/Address.sol"; + +/** + * @dev Contract module which acts as a timelocked controller. When set as the + * owner of an `Ownable` smart contract, it enforces a timelock on all + * `onlyOwner` maintenance operations. This gives time for users of the + * controlled contract to exit before a potentially dangerous maintenance + * operation is applied. + * + * By default, this contract is self administered, meaning administration tasks + * have to go through the timelock process. The proposer (resp executor) role + * is in charge of proposing (resp executing) operations. A common use case is + * to position this {TimelockController} as the owner of a smart contract, with + * a multisig or a DAO as the sole proposer. + */ +contract TimelockController is AccessControl, ERC721Holder, ERC1155Holder { + bytes32 public constant PROPOSER_ROLE = keccak256("PROPOSER_ROLE"); + bytes32 public constant EXECUTOR_ROLE = keccak256("EXECUTOR_ROLE"); + bytes32 public constant CANCELLER_ROLE = keccak256("CANCELLER_ROLE"); + uint256 internal constant _DONE_TIMESTAMP = uint256(1); + + mapping(bytes32 id => uint256) private _timestamps; + uint256 private _minDelay; + + enum OperationState { + Unset, + Waiting, + Ready, + Done + } + + /** + * @dev Mismatch between the parameters length for an operation call. + */ + error TimelockInvalidOperationLength(uint256 targets, uint256 payloads, uint256 values); + + /** + * @dev The schedule operation doesn't meet the minimum delay. + */ + error TimelockInsufficientDelay(uint256 delay, uint256 minDelay); + + /** + * @dev The current state of an operation is not as required. + * The `expectedStates` is a bitmap with the bits enabled for each OperationState enum position + * counting from right to left. + * + * See {_encodeStateBitmap}. + */ + error TimelockUnexpectedOperationState(bytes32 operationId, bytes32 expectedStates); + + /** + * @dev The predecessor to an operation not yet done. + */ + error TimelockUnexecutedPredecessor(bytes32 predecessorId); + + /** + * @dev The caller account is not authorized. + */ + error TimelockUnauthorizedCaller(address caller); + + /** + * @dev Emitted when a call is scheduled as part of operation `id`. + */ + event CallScheduled( + bytes32 indexed id, + uint256 indexed index, + address target, + uint256 value, + bytes data, + bytes32 predecessor, + uint256 delay + ); + + /** + * @dev Emitted when a call is performed as part of operation `id`. + */ + event CallExecuted(bytes32 indexed id, uint256 indexed index, address target, uint256 value, bytes data); + + /** + * @dev Emitted when new proposal is scheduled with non-zero salt. + */ + event CallSalt(bytes32 indexed id, bytes32 salt); + + /** + * @dev Emitted when operation `id` is cancelled. + */ + event Cancelled(bytes32 indexed id); + + /** + * @dev Emitted when the minimum delay for future operations is modified. + */ + event MinDelayChange(uint256 oldDuration, uint256 newDuration); + + /** + * @dev Initializes the contract with the following parameters: + * + * - `minDelay`: initial minimum delay in seconds for operations + * - `proposers`: accounts to be granted proposer and canceller roles + * - `executors`: accounts to be granted executor role + * - `admin`: optional account to be granted admin role; disable with zero address + * + * IMPORTANT: The optional admin can aid with initial configuration of roles after deployment + * without being subject to delay, but this role should be subsequently renounced in favor of + * administration through timelocked proposals. Previous versions of this contract would assign + * this admin to the deployer automatically and should be renounced as well. + */ + constructor(uint256 minDelay, address[] memory proposers, address[] memory executors, address admin) { + // self administration + _grantRole(DEFAULT_ADMIN_ROLE, address(this)); + + // optional admin + if (admin != address(0)) { + _grantRole(DEFAULT_ADMIN_ROLE, admin); + } + + // register proposers and cancellers + for (uint256 i = 0; i < proposers.length; ++i) { + _grantRole(PROPOSER_ROLE, proposers[i]); + _grantRole(CANCELLER_ROLE, proposers[i]); + } + + // register executors + for (uint256 i = 0; i < executors.length; ++i) { + _grantRole(EXECUTOR_ROLE, executors[i]); + } + + _minDelay = minDelay; + emit MinDelayChange(0, minDelay); + } + + /** + * @dev Modifier to make a function callable only by a certain role. In + * addition to checking the sender's role, `address(0)` 's role is also + * considered. Granting a role to `address(0)` is equivalent to enabling + * this role for everyone. + */ + modifier onlyRoleOrOpenRole(bytes32 role) { + if (!hasRole(role, address(0))) { + _checkRole(role, _msgSender()); + } + _; + } + + /** + * @dev Contract might receive/hold ETH as part of the maintenance process. + */ + receive() external payable {} + + /** + * @dev See {IERC165-supportsInterface}. + */ + function supportsInterface( + bytes4 interfaceId + ) public view virtual override(AccessControl, ERC1155Holder) returns (bool) { + return super.supportsInterface(interfaceId); + } + + /** + * @dev Returns whether an id corresponds to a registered operation. This + * includes both Waiting, Ready, and Done operations. + */ + function isOperation(bytes32 id) public view returns (bool) { + return getOperationState(id) != OperationState.Unset; + } + + /** + * @dev Returns whether an operation is pending or not. Note that a "pending" operation may also be "ready". + */ + function isOperationPending(bytes32 id) public view returns (bool) { + OperationState state = getOperationState(id); + return state == OperationState.Waiting || state == OperationState.Ready; + } + + /** + * @dev Returns whether an operation is ready for execution. Note that a "ready" operation is also "pending". + */ + function isOperationReady(bytes32 id) public view returns (bool) { + return getOperationState(id) == OperationState.Ready; + } + + /** + * @dev Returns whether an operation is done or not. + */ + function isOperationDone(bytes32 id) public view returns (bool) { + return getOperationState(id) == OperationState.Done; + } + + /** + * @dev Returns the timestamp at which an operation becomes ready (0 for + * unset operations, 1 for done operations). + */ + function getTimestamp(bytes32 id) public view virtual returns (uint256) { + return _timestamps[id]; + } + + /** + * @dev Returns operation state. + */ + function getOperationState(bytes32 id) public view virtual returns (OperationState) { + uint256 timestamp = getTimestamp(id); + if (timestamp == 0) { + return OperationState.Unset; + } else if (timestamp == _DONE_TIMESTAMP) { + return OperationState.Done; + } else if (timestamp > block.timestamp) { + return OperationState.Waiting; + } else { + return OperationState.Ready; + } + } + + /** + * @dev Returns the minimum delay in seconds for an operation to become valid. + * + * This value can be changed by executing an operation that calls `updateDelay`. + */ + function getMinDelay() public view virtual returns (uint256) { + return _minDelay; + } + + /** + * @dev Returns the identifier of an operation containing a single + * transaction. + */ + function hashOperation( + address target, + uint256 value, + bytes calldata data, + bytes32 predecessor, + bytes32 salt + ) public pure virtual returns (bytes32) { + return keccak256(abi.encode(target, value, data, predecessor, salt)); + } + + /** + * @dev Returns the identifier of an operation containing a batch of + * transactions. + */ + function hashOperationBatch( + address[] calldata targets, + uint256[] calldata values, + bytes[] calldata payloads, + bytes32 predecessor, + bytes32 salt + ) public pure virtual returns (bytes32) { + return keccak256(abi.encode(targets, values, payloads, predecessor, salt)); + } + + /** + * @dev Schedule an operation containing a single transaction. + * + * Emits {CallSalt} if salt is nonzero, and {CallScheduled}. + * + * Requirements: + * + * - the caller must have the 'proposer' role. + */ + function schedule( + address target, + uint256 value, + bytes calldata data, + bytes32 predecessor, + bytes32 salt, + uint256 delay + ) public virtual onlyRole(PROPOSER_ROLE) { + bytes32 id = hashOperation(target, value, data, predecessor, salt); + _schedule(id, delay); + emit CallScheduled(id, 0, target, value, data, predecessor, delay); + if (salt != bytes32(0)) { + emit CallSalt(id, salt); + } + } + + /** + * @dev Schedule an operation containing a batch of transactions. + * + * Emits {CallSalt} if salt is nonzero, and one {CallScheduled} event per transaction in the batch. + * + * Requirements: + * + * - the caller must have the 'proposer' role. + */ + function scheduleBatch( + address[] calldata targets, + uint256[] calldata values, + bytes[] calldata payloads, + bytes32 predecessor, + bytes32 salt, + uint256 delay + ) public virtual onlyRole(PROPOSER_ROLE) { + if (targets.length != values.length || targets.length != payloads.length) { + revert TimelockInvalidOperationLength(targets.length, payloads.length, values.length); + } + + bytes32 id = hashOperationBatch(targets, values, payloads, predecessor, salt); + _schedule(id, delay); + for (uint256 i = 0; i < targets.length; ++i) { + emit CallScheduled(id, i, targets[i], values[i], payloads[i], predecessor, delay); + } + if (salt != bytes32(0)) { + emit CallSalt(id, salt); + } + } + + /** + * @dev Schedule an operation that is to become valid after a given delay. + */ + function _schedule(bytes32 id, uint256 delay) private { + if (isOperation(id)) { + revert TimelockUnexpectedOperationState(id, _encodeStateBitmap(OperationState.Unset)); + } + uint256 minDelay = getMinDelay(); + if (delay < minDelay) { + revert TimelockInsufficientDelay(delay, minDelay); + } + _timestamps[id] = block.timestamp + delay; + } + + /** + * @dev Cancel an operation. + * + * Requirements: + * + * - the caller must have the 'canceller' role. + */ + function cancel(bytes32 id) public virtual onlyRole(CANCELLER_ROLE) { + if (!isOperationPending(id)) { + revert TimelockUnexpectedOperationState( + id, + _encodeStateBitmap(OperationState.Waiting) | _encodeStateBitmap(OperationState.Ready) + ); + } + delete _timestamps[id]; + + emit Cancelled(id); + } + + /** + * @dev Execute an (ready) operation containing a single transaction. + * + * Emits a {CallExecuted} event. + * + * Requirements: + * + * - the caller must have the 'executor' role. + */ + // This function can reenter, but it doesn't pose a risk because _afterCall checks that the proposal is pending, + // thus any modifications to the operation during reentrancy should be caught. + // slither-disable-next-line reentrancy-eth + function execute( + address target, + uint256 value, + bytes calldata payload, + bytes32 predecessor, + bytes32 salt + ) public payable virtual onlyRoleOrOpenRole(EXECUTOR_ROLE) { + bytes32 id = hashOperation(target, value, payload, predecessor, salt); + + _beforeCall(id, predecessor); + _execute(target, value, payload); + emit CallExecuted(id, 0, target, value, payload); + _afterCall(id); + } + + /** + * @dev Execute an (ready) operation containing a batch of transactions. + * + * Emits one {CallExecuted} event per transaction in the batch. + * + * Requirements: + * + * - the caller must have the 'executor' role. + */ + // This function can reenter, but it doesn't pose a risk because _afterCall checks that the proposal is pending, + // thus any modifications to the operation during reentrancy should be caught. + // slither-disable-next-line reentrancy-eth + function executeBatch( + address[] calldata targets, + uint256[] calldata values, + bytes[] calldata payloads, + bytes32 predecessor, + bytes32 salt + ) public payable virtual onlyRoleOrOpenRole(EXECUTOR_ROLE) { + if (targets.length != values.length || targets.length != payloads.length) { + revert TimelockInvalidOperationLength(targets.length, payloads.length, values.length); + } + + bytes32 id = hashOperationBatch(targets, values, payloads, predecessor, salt); + + _beforeCall(id, predecessor); + for (uint256 i = 0; i < targets.length; ++i) { + address target = targets[i]; + uint256 value = values[i]; + bytes calldata payload = payloads[i]; + _execute(target, value, payload); + emit CallExecuted(id, i, target, value, payload); + } + _afterCall(id); + } + + /** + * @dev Execute an operation's call. + */ + function _execute(address target, uint256 value, bytes calldata data) internal virtual { + (bool success, bytes memory returndata) = target.call{value: value}(data); + Address.verifyCallResult(success, returndata); + } + + /** + * @dev Checks before execution of an operation's calls. + */ + function _beforeCall(bytes32 id, bytes32 predecessor) private view { + if (!isOperationReady(id)) { + revert TimelockUnexpectedOperationState(id, _encodeStateBitmap(OperationState.Ready)); + } + if (predecessor != bytes32(0) && !isOperationDone(predecessor)) { + revert TimelockUnexecutedPredecessor(predecessor); + } + } + + /** + * @dev Checks after execution of an operation's calls. + */ + function _afterCall(bytes32 id) private { + if (!isOperationReady(id)) { + revert TimelockUnexpectedOperationState(id, _encodeStateBitmap(OperationState.Ready)); + } + _timestamps[id] = _DONE_TIMESTAMP; + } + + /** + * @dev Changes the minimum timelock duration for future operations. + * + * Emits a {MinDelayChange} event. + * + * Requirements: + * + * - the caller must be the timelock itself. This can only be achieved by scheduling and later executing + * an operation where the timelock is the target and the data is the ABI-encoded call to this function. + */ + function updateDelay(uint256 newDelay) external virtual { + address sender = _msgSender(); + if (sender != address(this)) { + revert TimelockUnauthorizedCaller(sender); + } + emit MinDelayChange(_minDelay, newDelay); + _minDelay = newDelay; + } + + /** + * @dev Encodes a `OperationState` into a `bytes32` representation where each bit enabled corresponds to + * the underlying position in the `OperationState` enum. For example: + * + * 0x000...1000 + * ^^^^^^----- ... + * ^---- Done + * ^--- Ready + * ^-- Waiting + * ^- Unset + */ + function _encodeStateBitmap(OperationState operationState) internal pure returns (bytes32) { + return bytes32(1 << uint8(operationState)); + } +} diff --git a/contracts/governance/extensions/GovernorCountingSimple.sol b/contracts/governance/extensions/GovernorCountingSimple.sol new file mode 100644 index 000000000..44e71848c --- /dev/null +++ b/contracts/governance/extensions/GovernorCountingSimple.sol @@ -0,0 +1,100 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (governance/extensions/GovernorCountingSimple.sol) + +pragma solidity ^0.8.20; + +import {Governor} from "../Governor.sol"; + +/** + * @dev Extension of {Governor} for simple, 3 options, vote counting. + */ +abstract contract GovernorCountingSimple is Governor { + /** + * @dev Supported vote types. Matches Governor Bravo ordering. + */ + enum VoteType { + Against, + For, + Abstain + } + + struct ProposalVote { + uint256 againstVotes; + uint256 forVotes; + uint256 abstainVotes; + mapping(address voter => bool) hasVoted; + } + + mapping(uint256 proposalId => ProposalVote) private _proposalVotes; + + /** + * @dev See {IGovernor-COUNTING_MODE}. + */ + // solhint-disable-next-line func-name-mixedcase + function COUNTING_MODE() public pure virtual override returns (string memory) { + return "support=bravo&quorum=for,abstain"; + } + + /** + * @dev See {IGovernor-hasVoted}. + */ + function hasVoted(uint256 proposalId, address account) public view virtual override returns (bool) { + return _proposalVotes[proposalId].hasVoted[account]; + } + + /** + * @dev Accessor to the internal vote counts. + */ + function proposalVotes( + uint256 proposalId + ) public view virtual returns (uint256 againstVotes, uint256 forVotes, uint256 abstainVotes) { + ProposalVote storage proposalVote = _proposalVotes[proposalId]; + return (proposalVote.againstVotes, proposalVote.forVotes, proposalVote.abstainVotes); + } + + /** + * @dev See {Governor-_quorumReached}. + */ + function _quorumReached(uint256 proposalId) internal view virtual override returns (bool) { + ProposalVote storage proposalVote = _proposalVotes[proposalId]; + + return quorum(proposalSnapshot(proposalId)) <= proposalVote.forVotes + proposalVote.abstainVotes; + } + + /** + * @dev See {Governor-_voteSucceeded}. In this module, the forVotes must be strictly over the againstVotes. + */ + function _voteSucceeded(uint256 proposalId) internal view virtual override returns (bool) { + ProposalVote storage proposalVote = _proposalVotes[proposalId]; + + return proposalVote.forVotes > proposalVote.againstVotes; + } + + /** + * @dev See {Governor-_countVote}. In this module, the support follows the `VoteType` enum (from Governor Bravo). + */ + function _countVote( + uint256 proposalId, + address account, + uint8 support, + uint256 weight, + bytes memory // params + ) internal virtual override { + ProposalVote storage proposalVote = _proposalVotes[proposalId]; + + if (proposalVote.hasVoted[account]) { + revert GovernorAlreadyCastVote(account); + } + proposalVote.hasVoted[account] = true; + + if (support == uint8(VoteType.Against)) { + proposalVote.againstVotes += weight; + } else if (support == uint8(VoteType.For)) { + proposalVote.forVotes += weight; + } else if (support == uint8(VoteType.Abstain)) { + proposalVote.abstainVotes += weight; + } else { + revert GovernorInvalidVoteType(); + } + } +} diff --git a/contracts/governance/extensions/GovernorPreventLateQuorum.sol b/contracts/governance/extensions/GovernorPreventLateQuorum.sol new file mode 100644 index 000000000..6dd3f9458 --- /dev/null +++ b/contracts/governance/extensions/GovernorPreventLateQuorum.sol @@ -0,0 +1,102 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (governance/extensions/GovernorPreventLateQuorum.sol) + +pragma solidity ^0.8.20; + +import {Governor} from "../Governor.sol"; +import {Math} from "../../utils/math/Math.sol"; + +/** + * @dev A module that ensures there is a minimum voting period after quorum is reached. This prevents a large voter from + * swaying a vote and triggering quorum at the last minute, by ensuring there is always time for other voters to react + * and try to oppose the decision. + * + * If a vote causes quorum to be reached, the proposal's voting period may be extended so that it does not end before at + * least a specified time has passed (the "vote extension" parameter). This parameter can be set through a governance + * proposal. + */ +abstract contract GovernorPreventLateQuorum is Governor { + uint48 private _voteExtension; + + mapping(uint256 proposalId => uint48) private _extendedDeadlines; + + /// @dev Emitted when a proposal deadline is pushed back due to reaching quorum late in its voting period. + event ProposalExtended(uint256 indexed proposalId, uint64 extendedDeadline); + + /// @dev Emitted when the {lateQuorumVoteExtension} parameter is changed. + event LateQuorumVoteExtensionSet(uint64 oldVoteExtension, uint64 newVoteExtension); + + /** + * @dev Initializes the vote extension parameter: the time in either number of blocks or seconds (depending on the + * governor clock mode) that is required to pass since the moment a proposal reaches quorum until its voting period + * ends. If necessary the voting period will be extended beyond the one set during proposal creation. + */ + constructor(uint48 initialVoteExtension) { + _setLateQuorumVoteExtension(initialVoteExtension); + } + + /** + * @dev Returns the proposal deadline, which may have been extended beyond that set at proposal creation, if the + * proposal reached quorum late in the voting period. See {Governor-proposalDeadline}. + */ + function proposalDeadline(uint256 proposalId) public view virtual override returns (uint256) { + return Math.max(super.proposalDeadline(proposalId), _extendedDeadlines[proposalId]); + } + + /** + * @dev Casts a vote and detects if it caused quorum to be reached, potentially extending the voting period. See + * {Governor-_castVote}. + * + * May emit a {ProposalExtended} event. + */ + function _castVote( + uint256 proposalId, + address account, + uint8 support, + string memory reason, + bytes memory params + ) internal virtual override returns (uint256) { + uint256 result = super._castVote(proposalId, account, support, reason, params); + + if (_extendedDeadlines[proposalId] == 0 && _quorumReached(proposalId)) { + uint48 extendedDeadline = clock() + lateQuorumVoteExtension(); + + if (extendedDeadline > proposalDeadline(proposalId)) { + emit ProposalExtended(proposalId, extendedDeadline); + } + + _extendedDeadlines[proposalId] = extendedDeadline; + } + + return result; + } + + /** + * @dev Returns the current value of the vote extension parameter: the number of blocks that are required to pass + * from the time a proposal reaches quorum until its voting period ends. + */ + function lateQuorumVoteExtension() public view virtual returns (uint48) { + return _voteExtension; + } + + /** + * @dev Changes the {lateQuorumVoteExtension}. This operation can only be performed by the governance executor, + * generally through a governance proposal. + * + * Emits a {LateQuorumVoteExtensionSet} event. + */ + function setLateQuorumVoteExtension(uint48 newVoteExtension) public virtual onlyGovernance { + _setLateQuorumVoteExtension(newVoteExtension); + } + + /** + * @dev Changes the {lateQuorumVoteExtension}. This is an internal function that can be exposed in a public function + * like {setLateQuorumVoteExtension} if another access control mechanism is needed. + * + * Emits a {LateQuorumVoteExtensionSet} event. + */ + function _setLateQuorumVoteExtension(uint48 newVoteExtension) internal virtual { + emit LateQuorumVoteExtensionSet(_voteExtension, newVoteExtension); + _voteExtension = newVoteExtension; + } +} diff --git a/contracts/governance/extensions/GovernorSettings.sol b/contracts/governance/extensions/GovernorSettings.sol new file mode 100644 index 000000000..82ce646be --- /dev/null +++ b/contracts/governance/extensions/GovernorSettings.sol @@ -0,0 +1,112 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (governance/extensions/GovernorSettings.sol) + +pragma solidity ^0.8.20; + +import {Governor} from "../Governor.sol"; + +/** + * @dev Extension of {Governor} for settings updatable through governance. + */ +abstract contract GovernorSettings is Governor { + // amount of token + uint256 private _proposalThreshold; + // timepoint: limited to uint48 in core (same as clock() type) + uint48 private _votingDelay; + // duration: limited to uint32 in core + uint32 private _votingPeriod; + + event VotingDelaySet(uint256 oldVotingDelay, uint256 newVotingDelay); + event VotingPeriodSet(uint256 oldVotingPeriod, uint256 newVotingPeriod); + event ProposalThresholdSet(uint256 oldProposalThreshold, uint256 newProposalThreshold); + + /** + * @dev Initialize the governance parameters. + */ + constructor(uint48 initialVotingDelay, uint32 initialVotingPeriod, uint256 initialProposalThreshold) { + _setVotingDelay(initialVotingDelay); + _setVotingPeriod(initialVotingPeriod); + _setProposalThreshold(initialProposalThreshold); + } + + /** + * @dev See {IGovernor-votingDelay}. + */ + function votingDelay() public view virtual override returns (uint256) { + return _votingDelay; + } + + /** + * @dev See {IGovernor-votingPeriod}. + */ + function votingPeriod() public view virtual override returns (uint256) { + return _votingPeriod; + } + + /** + * @dev See {Governor-proposalThreshold}. + */ + function proposalThreshold() public view virtual override returns (uint256) { + return _proposalThreshold; + } + + /** + * @dev Update the voting delay. This operation can only be performed through a governance proposal. + * + * Emits a {VotingDelaySet} event. + */ + function setVotingDelay(uint48 newVotingDelay) public virtual onlyGovernance { + _setVotingDelay(newVotingDelay); + } + + /** + * @dev Update the voting period. This operation can only be performed through a governance proposal. + * + * Emits a {VotingPeriodSet} event. + */ + function setVotingPeriod(uint32 newVotingPeriod) public virtual onlyGovernance { + _setVotingPeriod(newVotingPeriod); + } + + /** + * @dev Update the proposal threshold. This operation can only be performed through a governance proposal. + * + * Emits a {ProposalThresholdSet} event. + */ + function setProposalThreshold(uint256 newProposalThreshold) public virtual onlyGovernance { + _setProposalThreshold(newProposalThreshold); + } + + /** + * @dev Internal setter for the voting delay. + * + * Emits a {VotingDelaySet} event. + */ + function _setVotingDelay(uint48 newVotingDelay) internal virtual { + emit VotingDelaySet(_votingDelay, newVotingDelay); + _votingDelay = newVotingDelay; + } + + /** + * @dev Internal setter for the voting period. + * + * Emits a {VotingPeriodSet} event. + */ + function _setVotingPeriod(uint32 newVotingPeriod) internal virtual { + if (newVotingPeriod == 0) { + revert GovernorInvalidVotingPeriod(0); + } + emit VotingPeriodSet(_votingPeriod, newVotingPeriod); + _votingPeriod = newVotingPeriod; + } + + /** + * @dev Internal setter for the proposal threshold. + * + * Emits a {ProposalThresholdSet} event. + */ + function _setProposalThreshold(uint256 newProposalThreshold) internal virtual { + emit ProposalThresholdSet(_proposalThreshold, newProposalThreshold); + _proposalThreshold = newProposalThreshold; + } +} diff --git a/contracts/governance/extensions/GovernorStorage.sol b/contracts/governance/extensions/GovernorStorage.sol new file mode 100644 index 000000000..a90f13a74 --- /dev/null +++ b/contracts/governance/extensions/GovernorStorage.sol @@ -0,0 +1,115 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (governance/extensions/GovernorStorage.sol) + +pragma solidity ^0.8.20; + +import {Governor} from "../Governor.sol"; + +/** + * @dev Extension of {Governor} that implements storage of proposal details. This modules also provides primitives for + * the enumerability of proposals. + * + * Use cases for this module include: + * - UIs that explore the proposal state without relying on event indexing. + * - Using only the proposalId as an argument in the {Governor-queue} and {Governor-execute} functions for L2 chains + * where storage is cheap compared to calldata. + */ +abstract contract GovernorStorage is Governor { + struct ProposalDetails { + address[] targets; + uint256[] values; + bytes[] calldatas; + bytes32 descriptionHash; + } + + uint256[] private _proposalIds; + mapping(uint256 proposalId => ProposalDetails) private _proposalDetails; + + /** + * @dev Hook into the proposing mechanism + */ + function _propose( + address[] memory targets, + uint256[] memory values, + bytes[] memory calldatas, + string memory description, + address proposer + ) internal virtual override returns (uint256) { + uint256 proposalId = super._propose(targets, values, calldatas, description, proposer); + + // store + _proposalIds.push(proposalId); + _proposalDetails[proposalId] = ProposalDetails({ + targets: targets, + values: values, + calldatas: calldatas, + descriptionHash: keccak256(bytes(description)) + }); + + return proposalId; + } + + /** + * @dev Version of {IGovernorTimelock-queue} with only `proposalId` as an argument. + */ + function queue(uint256 proposalId) public virtual { + // here, using storage is more efficient than memory + ProposalDetails storage details = _proposalDetails[proposalId]; + queue(details.targets, details.values, details.calldatas, details.descriptionHash); + } + + /** + * @dev Version of {IGovernor-execute} with only `proposalId` as an argument. + */ + function execute(uint256 proposalId) public payable virtual { + // here, using storage is more efficient than memory + ProposalDetails storage details = _proposalDetails[proposalId]; + execute(details.targets, details.values, details.calldatas, details.descriptionHash); + } + + /** + * @dev ProposalId version of {IGovernor-cancel}. + */ + function cancel(uint256 proposalId) public virtual { + // here, using storage is more efficient than memory + ProposalDetails storage details = _proposalDetails[proposalId]; + cancel(details.targets, details.values, details.calldatas, details.descriptionHash); + } + + /** + * @dev Returns the number of stored proposals. + */ + function proposalCount() public view virtual returns (uint256) { + return _proposalIds.length; + } + + /** + * @dev Returns the details of a proposalId. Reverts if `proposalId` is not a known proposal. + */ + function proposalDetails( + uint256 proposalId + ) public view virtual returns (address[] memory, uint256[] memory, bytes[] memory, bytes32) { + // here, using memory is more efficient than storage + ProposalDetails memory details = _proposalDetails[proposalId]; + if (details.descriptionHash == 0) { + revert GovernorNonexistentProposal(proposalId); + } + return (details.targets, details.values, details.calldatas, details.descriptionHash); + } + + /** + * @dev Returns the details (including the proposalId) of a proposal given its sequential index. + */ + function proposalDetailsAt( + uint256 index + ) public view virtual returns (uint256, address[] memory, uint256[] memory, bytes[] memory, bytes32) { + uint256 proposalId = _proposalIds[index]; + ( + address[] memory targets, + uint256[] memory values, + bytes[] memory calldatas, + bytes32 descriptionHash + ) = proposalDetails(proposalId); + return (proposalId, targets, values, calldatas, descriptionHash); + } +} diff --git a/contracts/governance/extensions/GovernorTimelockAccess.sol b/contracts/governance/extensions/GovernorTimelockAccess.sol new file mode 100644 index 000000000..007e0c6f9 --- /dev/null +++ b/contracts/governance/extensions/GovernorTimelockAccess.sol @@ -0,0 +1,343 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (governance/extensions/GovernorTimelockAccess.sol) + +pragma solidity ^0.8.20; + +import {Governor} from "../Governor.sol"; +import {AuthorityUtils} from "../../access/manager/AuthorityUtils.sol"; +import {IAccessManager} from "../../access/manager/IAccessManager.sol"; +import {Address} from "../../utils/Address.sol"; +import {Math} from "../../utils/math/Math.sol"; +import {SafeCast} from "../../utils/math/SafeCast.sol"; +import {Time} from "../../utils/types/Time.sol"; + +/** + * @dev This module connects a {Governor} instance to an {AccessManager} instance, allowing the governor to make calls + * that are delay-restricted by the manager using the normal {queue} workflow. An optional base delay is applied to + * operations that are not delayed externally by the manager. Execution of a proposal will be delayed as much as + * necessary to meet the required delays of all of its operations. + * + * This extension allows the governor to hold and use its own assets and permissions, unlike {GovernorTimelockControl} + * and {GovernorTimelockCompound}, where the timelock is a separate contract that must be the one to hold assets and + * permissions. Operations that are delay-restricted by the manager, however, will be executed through the + * {AccessManager-execute} function. + * + * ==== Security Considerations + * + * Some operations may be cancelable in the `AccessManager` by the admin or a set of guardians, depending on the + * restricted function being invoked. Since proposals are atomic, the cancellation by a guardian of a single operation + * in a proposal will cause all of the proposal to become unable to execute. Consider proposing cancellable operations + * separately. + * + * By default, function calls will be routed through the associated `AccessManager` whenever it claims the target + * function to be restricted by it. However, admins may configure the manager to make that claim for functions that a + * governor would want to call directly (e.g., token transfers) in an attempt to deny it access to those functions. To + * mitigate this attack vector, the governor is able to ignore the restrictions claimed by the `AccessManager` using + * {setAccessManagerIgnored}. While permanent denial of service is mitigated, temporary DoS may still be technically + * possible. All of the governor's own functions (e.g., {setBaseDelaySeconds}) ignore the `AccessManager` by default. + */ +abstract contract GovernorTimelockAccess is Governor { + // An execution plan is produced at the moment a proposal is created, in order to fix at that point the exact + // execution semantics of the proposal, namely whether a call will go through {AccessManager-execute}. + struct ExecutionPlan { + uint16 length; + uint32 delay; + // We use mappings instead of arrays because it allows us to pack values in storage more tightly without + // storing the length redundantly. + // We pack 8 operations' data in each bucket. Each uint32 value is set to 1 upon proposal creation if it has + // to be scheduled and executed through the manager. Upon queuing, the value is set to nonce + 2, where the + // nonce is received from the manager when scheduling the operation. + mapping(uint256 operationBucket => uint32[8]) managerData; + } + + // The meaning of the "toggle" set to true depends on the target contract. + // If target == address(this), the manager is ignored by default, and a true toggle means it won't be ignored. + // For all other target contracts, the manager is used by default, and a true toggle means it will be ignored. + mapping(address target => mapping(bytes4 selector => bool)) private _ignoreToggle; + + mapping(uint256 proposalId => ExecutionPlan) private _executionPlan; + + uint32 private _baseDelay; + + IAccessManager private immutable _manager; + + error GovernorUnmetDelay(uint256 proposalId, uint256 neededTimestamp); + error GovernorMismatchedNonce(uint256 proposalId, uint256 expectedNonce, uint256 actualNonce); + error GovernorLockedIgnore(); + + event BaseDelaySet(uint32 oldBaseDelaySeconds, uint32 newBaseDelaySeconds); + event AccessManagerIgnoredSet(address target, bytes4 selector, bool ignored); + + /** + * @dev Initialize the governor with an {AccessManager} and initial base delay. + */ + constructor(address manager, uint32 initialBaseDelay) { + _manager = IAccessManager(manager); + _setBaseDelaySeconds(initialBaseDelay); + } + + /** + * @dev Returns the {AccessManager} instance associated to this governor. + */ + function accessManager() public view virtual returns (IAccessManager) { + return _manager; + } + + /** + * @dev Base delay that will be applied to all function calls. Some may be further delayed by their associated + * `AccessManager` authority; in this case the final delay will be the maximum of the base delay and the one + * demanded by the authority. + * + * NOTE: Execution delays are processed by the `AccessManager` contracts, and according to that contract are + * expressed in seconds. Therefore, the base delay is also in seconds, regardless of the governor's clock mode. + */ + function baseDelaySeconds() public view virtual returns (uint32) { + return _baseDelay; + } + + /** + * @dev Change the value of {baseDelaySeconds}. This operation can only be invoked through a governance proposal. + */ + function setBaseDelaySeconds(uint32 newBaseDelay) public virtual onlyGovernance { + _setBaseDelaySeconds(newBaseDelay); + } + + /** + * @dev Change the value of {baseDelaySeconds}. Internal function without access control. + */ + function _setBaseDelaySeconds(uint32 newBaseDelay) internal virtual { + emit BaseDelaySet(_baseDelay, newBaseDelay); + _baseDelay = newBaseDelay; + } + + /** + * @dev Check if restrictions from the associated {AccessManager} are ignored for a target function. Returns true + * when the target function will be invoked directly regardless of `AccessManager` settings for the function. + * See {setAccessManagerIgnored} and Security Considerations above. + */ + function isAccessManagerIgnored(address target, bytes4 selector) public view virtual returns (bool) { + bool isGovernor = target == address(this); + return _ignoreToggle[target][selector] != isGovernor; // equivalent to: isGovernor ? !toggle : toggle + } + + /** + * @dev Configure whether restrictions from the associated {AccessManager} are ignored for a target function. + * See Security Considerations above. + */ + function setAccessManagerIgnored( + address target, + bytes4[] calldata selectors, + bool ignored + ) public virtual onlyGovernance { + for (uint256 i = 0; i < selectors.length; ++i) { + _setAccessManagerIgnored(target, selectors[i], ignored); + } + } + + /** + * @dev Internal version of {setAccessManagerIgnored} without access restriction. + */ + function _setAccessManagerIgnored(address target, bytes4 selector, bool ignored) internal virtual { + bool isGovernor = target == address(this); + if (isGovernor && selector == this.setAccessManagerIgnored.selector) { + revert GovernorLockedIgnore(); + } + _ignoreToggle[target][selector] = ignored != isGovernor; // equivalent to: isGovernor ? !ignored : ignored + emit AccessManagerIgnoredSet(target, selector, ignored); + } + + /** + * @dev Public accessor to check the execution plan, including the number of seconds that the proposal will be + * delayed since queuing, an array indicating which of the proposal actions will be executed indirectly through + * the associated {AccessManager}, and another indicating which will be scheduled in {queue}. Note that + * those that must be scheduled are cancellable by `AccessManager` guardians. + */ + function proposalExecutionPlan( + uint256 proposalId + ) public view returns (uint32 delay, bool[] memory indirect, bool[] memory withDelay) { + ExecutionPlan storage plan = _executionPlan[proposalId]; + + uint32 length = plan.length; + delay = plan.delay; + indirect = new bool[](length); + withDelay = new bool[](length); + for (uint256 i = 0; i < length; ++i) { + (indirect[i], withDelay[i], ) = _getManagerData(plan, i); + } + + return (delay, indirect, withDelay); + } + + /** + * @dev See {IGovernor-proposalNeedsQueuing}. + */ + function proposalNeedsQueuing(uint256 proposalId) public view virtual override returns (bool) { + return _executionPlan[proposalId].delay > 0; + } + + /** + * @dev See {IGovernor-propose} + */ + function propose( + address[] memory targets, + uint256[] memory values, + bytes[] memory calldatas, + string memory description + ) public virtual override returns (uint256) { + uint256 proposalId = super.propose(targets, values, calldatas, description); + + uint32 neededDelay = baseDelaySeconds(); + + ExecutionPlan storage plan = _executionPlan[proposalId]; + plan.length = SafeCast.toUint16(targets.length); + + for (uint256 i = 0; i < targets.length; ++i) { + address target = targets[i]; + bytes4 selector = bytes4(calldatas[i]); + (bool immediate, uint32 delay) = AuthorityUtils.canCallWithDelay( + address(_manager), + address(this), + target, + selector + ); + if ((immediate || delay > 0) && !isAccessManagerIgnored(target, selector)) { + _setManagerData(plan, i, !immediate, 0); + // downcast is safe because both arguments are uint32 + neededDelay = uint32(Math.max(delay, neededDelay)); + } + } + + plan.delay = neededDelay; + + return proposalId; + } + + /** + * @dev Mechanism to queue a proposal, potentially scheduling some of its operations in the AccessManager. + * + * NOTE: The execution delay is chosen based on the delay information retrieved in {propose}. This value may be + * off if the delay was updated since proposal creation. In this case, the proposal needs to be recreated. + */ + function _queueOperations( + uint256 proposalId, + address[] memory targets, + uint256[] memory /* values */, + bytes[] memory calldatas, + bytes32 /* descriptionHash */ + ) internal virtual override returns (uint48) { + ExecutionPlan storage plan = _executionPlan[proposalId]; + uint48 etaSeconds = Time.timestamp() + plan.delay; + + for (uint256 i = 0; i < targets.length; ++i) { + (, bool withDelay, ) = _getManagerData(plan, i); + if (withDelay) { + (, uint32 nonce) = _manager.schedule(targets[i], calldatas[i], etaSeconds); + _setManagerData(plan, i, true, nonce); + } + } + + return etaSeconds; + } + + /** + * @dev Mechanism to execute a proposal, potentially going through {AccessManager-execute} for delayed operations. + */ + function _executeOperations( + uint256 proposalId, + address[] memory targets, + uint256[] memory values, + bytes[] memory calldatas, + bytes32 /* descriptionHash */ + ) internal virtual override { + uint48 etaSeconds = SafeCast.toUint48(proposalEta(proposalId)); + if (block.timestamp < etaSeconds) { + revert GovernorUnmetDelay(proposalId, etaSeconds); + } + + ExecutionPlan storage plan = _executionPlan[proposalId]; + + for (uint256 i = 0; i < targets.length; ++i) { + (bool controlled, bool withDelay, uint32 nonce) = _getManagerData(plan, i); + if (controlled) { + uint32 executedNonce = _manager.execute{value: values[i]}(targets[i], calldatas[i]); + if (withDelay && executedNonce != nonce) { + revert GovernorMismatchedNonce(proposalId, nonce, executedNonce); + } + } else { + (bool success, bytes memory returndata) = targets[i].call{value: values[i]}(calldatas[i]); + Address.verifyCallResult(success, returndata); + } + } + } + + /** + * @dev See {IGovernor-_cancel} + */ + function _cancel( + address[] memory targets, + uint256[] memory values, + bytes[] memory calldatas, + bytes32 descriptionHash + ) internal virtual override returns (uint256) { + uint256 proposalId = super._cancel(targets, values, calldatas, descriptionHash); + + uint48 etaSeconds = SafeCast.toUint48(proposalEta(proposalId)); + + ExecutionPlan storage plan = _executionPlan[proposalId]; + + // If the proposal has been scheduled it will have an ETA and we may have to externally cancel + if (etaSeconds != 0) { + for (uint256 i = 0; i < targets.length; ++i) { + (, bool withDelay, uint32 nonce) = _getManagerData(plan, i); + // Only attempt to cancel if the execution plan included a delay + if (withDelay) { + bytes32 operationId = _manager.hashOperation(address(this), targets[i], calldatas[i]); + // Check first if the current operation nonce is the one that we observed previously. It could + // already have been cancelled and rescheduled. We don't want to cancel unless it is exactly the + // instance that we previously scheduled. + if (nonce == _manager.getNonce(operationId)) { + // It is important that all calls have an opportunity to be cancelled. We chose to ignore + // potential failures of some of the cancel operations to give the other operations a chance to + // be properly cancelled. In particular cancel might fail if the operation was already cancelled + // by guardians previously. We don't match on the revert reason to avoid encoding assumptions + // about specific errors. + try _manager.cancel(address(this), targets[i], calldatas[i]) {} catch {} + } + } + } + } + + return proposalId; + } + + /** + * @dev Returns whether the operation at an index is delayed by the manager, and its scheduling nonce once queued. + */ + function _getManagerData( + ExecutionPlan storage plan, + uint256 index + ) private view returns (bool controlled, bool withDelay, uint32 nonce) { + (uint256 bucket, uint256 subindex) = _getManagerDataIndices(index); + uint32 value = plan.managerData[bucket][subindex]; + unchecked { + return (value > 0, value > 1, value > 1 ? value - 2 : 0); + } + } + + /** + * @dev Marks an operation at an index as permissioned by the manager, potentially delayed, and + * when delayed sets its scheduling nonce. + */ + function _setManagerData(ExecutionPlan storage plan, uint256 index, bool withDelay, uint32 nonce) private { + (uint256 bucket, uint256 subindex) = _getManagerDataIndices(index); + plan.managerData[bucket][subindex] = withDelay ? nonce + 2 : 1; + } + + /** + * @dev Returns bucket and subindex for reading manager data from the packed array mapping. + */ + function _getManagerDataIndices(uint256 index) private pure returns (uint256 bucket, uint256 subindex) { + bucket = index >> 3; // index / 8 + subindex = index & 7; // index % 8 + } +} diff --git a/contracts/governance/extensions/GovernorTimelockCompound.sol b/contracts/governance/extensions/GovernorTimelockCompound.sol new file mode 100644 index 000000000..8f2ec1863 --- /dev/null +++ b/contracts/governance/extensions/GovernorTimelockCompound.sol @@ -0,0 +1,167 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (governance/extensions/GovernorTimelockCompound.sol) + +pragma solidity ^0.8.20; + +import {IGovernor, Governor} from "../Governor.sol"; +import {ICompoundTimelock} from "../../vendor/compound/ICompoundTimelock.sol"; +import {Address} from "../../utils/Address.sol"; +import {SafeCast} from "../../utils/math/SafeCast.sol"; + +/** + * @dev Extension of {Governor} that binds the execution process to a Compound Timelock. This adds a delay, enforced by + * the external timelock to all successful proposal (in addition to the voting duration). The {Governor} needs to be + * the admin of the timelock for any operation to be performed. A public, unrestricted, + * {GovernorTimelockCompound-__acceptAdmin} is available to accept ownership of the timelock. + * + * Using this model means the proposal will be operated by the {TimelockController} and not by the {Governor}. Thus, + * the assets and permissions must be attached to the {TimelockController}. Any asset sent to the {Governor} will be + * inaccessible. + */ +abstract contract GovernorTimelockCompound is Governor { + ICompoundTimelock private _timelock; + + /** + * @dev Emitted when the timelock controller used for proposal execution is modified. + */ + event TimelockChange(address oldTimelock, address newTimelock); + + /** + * @dev Set the timelock. + */ + constructor(ICompoundTimelock timelockAddress) { + _updateTimelock(timelockAddress); + } + + /** + * @dev Overridden version of the {Governor-state} function with added support for the `Expired` state. + */ + function state(uint256 proposalId) public view virtual override returns (ProposalState) { + ProposalState currentState = super.state(proposalId); + + return + (currentState == ProposalState.Queued && + block.timestamp >= proposalEta(proposalId) + _timelock.GRACE_PERIOD()) + ? ProposalState.Expired + : currentState; + } + + /** + * @dev Public accessor to check the address of the timelock + */ + function timelock() public view virtual returns (address) { + return address(_timelock); + } + + /** + * @dev See {IGovernor-proposalNeedsQueuing}. + */ + function proposalNeedsQueuing(uint256) public view virtual override returns (bool) { + return true; + } + + /** + * @dev Function to queue a proposal to the timelock. + */ + function _queueOperations( + uint256 proposalId, + address[] memory targets, + uint256[] memory values, + bytes[] memory calldatas, + bytes32 /*descriptionHash*/ + ) internal virtual override returns (uint48) { + uint48 etaSeconds = SafeCast.toUint48(block.timestamp + _timelock.delay()); + + for (uint256 i = 0; i < targets.length; ++i) { + if ( + _timelock.queuedTransactions(keccak256(abi.encode(targets[i], values[i], "", calldatas[i], etaSeconds))) + ) { + revert GovernorAlreadyQueuedProposal(proposalId); + } + _timelock.queueTransaction(targets[i], values[i], "", calldatas[i], etaSeconds); + } + + return etaSeconds; + } + + /** + * @dev Overridden version of the {Governor-_executeOperations} function that run the already queued proposal + * through the timelock. + */ + function _executeOperations( + uint256 proposalId, + address[] memory targets, + uint256[] memory values, + bytes[] memory calldatas, + bytes32 /*descriptionHash*/ + ) internal virtual override { + uint256 etaSeconds = proposalEta(proposalId); + if (etaSeconds == 0) { + revert GovernorNotQueuedProposal(proposalId); + } + Address.sendValue(payable(_timelock), msg.value); + for (uint256 i = 0; i < targets.length; ++i) { + _timelock.executeTransaction(targets[i], values[i], "", calldatas[i], etaSeconds); + } + } + + /** + * @dev Overridden version of the {Governor-_cancel} function to cancel the timelocked proposal if it has already + * been queued. + */ + function _cancel( + address[] memory targets, + uint256[] memory values, + bytes[] memory calldatas, + bytes32 descriptionHash + ) internal virtual override returns (uint256) { + uint256 proposalId = super._cancel(targets, values, calldatas, descriptionHash); + + uint256 etaSeconds = proposalEta(proposalId); + if (etaSeconds > 0) { + // do external call later + for (uint256 i = 0; i < targets.length; ++i) { + _timelock.cancelTransaction(targets[i], values[i], "", calldatas[i], etaSeconds); + } + } + + return proposalId; + } + + /** + * @dev Address through which the governor executes action. In this case, the timelock. + */ + function _executor() internal view virtual override returns (address) { + return address(_timelock); + } + + /** + * @dev Accept admin right over the timelock. + */ + // solhint-disable-next-line private-vars-leading-underscore + function __acceptAdmin() public { + _timelock.acceptAdmin(); + } + + /** + * @dev Public endpoint to update the underlying timelock instance. Restricted to the timelock itself, so updates + * must be proposed, scheduled, and executed through governance proposals. + * + * For security reasons, the timelock must be handed over to another admin before setting up a new one. The two + * operations (hand over the timelock) and do the update can be batched in a single proposal. + * + * Note that if the timelock admin has been handed over in a previous operation, we refuse updates made through the + * timelock if admin of the timelock has already been accepted and the operation is executed outside the scope of + * governance. + + * CAUTION: It is not recommended to change the timelock while there are other queued governance proposals. + */ + function updateTimelock(ICompoundTimelock newTimelock) external virtual onlyGovernance { + _updateTimelock(newTimelock); + } + + function _updateTimelock(ICompoundTimelock newTimelock) private { + emit TimelockChange(address(_timelock), address(newTimelock)); + _timelock = newTimelock; + } +} diff --git a/contracts/governance/extensions/GovernorTimelockControl.sol b/contracts/governance/extensions/GovernorTimelockControl.sol new file mode 100644 index 000000000..c41eb7ee0 --- /dev/null +++ b/contracts/governance/extensions/GovernorTimelockControl.sol @@ -0,0 +1,173 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (governance/extensions/GovernorTimelockControl.sol) + +pragma solidity ^0.8.20; + +import {IGovernor, Governor} from "../Governor.sol"; +import {TimelockController} from "../TimelockController.sol"; +import {IERC165} from "../../interfaces/IERC165.sol"; +import {SafeCast} from "../../utils/math/SafeCast.sol"; + +/** + * @dev Extension of {Governor} that binds the execution process to an instance of {TimelockController}. This adds a + * delay, enforced by the {TimelockController} to all successful proposal (in addition to the voting duration). The + * {Governor} needs the proposer (and ideally the executor) roles for the {Governor} to work properly. + * + * Using this model means the proposal will be operated by the {TimelockController} and not by the {Governor}. Thus, + * the assets and permissions must be attached to the {TimelockController}. Any asset sent to the {Governor} will be + * inaccessible from a proposal, unless executed via {Governor-relay}. + * + * WARNING: Setting up the TimelockController to have additional proposers or cancellers besides the governor is very + * risky, as it grants them the ability to: 1) execute operations as the timelock, and thus possibly performing + * operations or accessing funds that are expected to only be accessible through a vote, and 2) block governance + * proposals that have been approved by the voters, effectively executing a Denial of Service attack. + * + * NOTE: `AccessManager` does not support scheduling more than one operation with the same target and calldata at + * the same time. See {AccessManager-schedule} for a workaround. + */ +abstract contract GovernorTimelockControl is Governor { + TimelockController private _timelock; + mapping(uint256 proposalId => bytes32) private _timelockIds; + + /** + * @dev Emitted when the timelock controller used for proposal execution is modified. + */ + event TimelockChange(address oldTimelock, address newTimelock); + + /** + * @dev Set the timelock. + */ + constructor(TimelockController timelockAddress) { + _updateTimelock(timelockAddress); + } + + /** + * @dev Overridden version of the {Governor-state} function that considers the status reported by the timelock. + */ + function state(uint256 proposalId) public view virtual override returns (ProposalState) { + ProposalState currentState = super.state(proposalId); + + if (currentState != ProposalState.Queued) { + return currentState; + } + + bytes32 queueid = _timelockIds[proposalId]; + if (_timelock.isOperationPending(queueid)) { + return ProposalState.Queued; + } else if (_timelock.isOperationDone(queueid)) { + // This can happen if the proposal is executed directly on the timelock. + return ProposalState.Executed; + } else { + // This can happen if the proposal is canceled directly on the timelock. + return ProposalState.Canceled; + } + } + + /** + * @dev Public accessor to check the address of the timelock + */ + function timelock() public view virtual returns (address) { + return address(_timelock); + } + + /** + * @dev See {IGovernor-proposalNeedsQueuing}. + */ + function proposalNeedsQueuing(uint256) public view virtual override returns (bool) { + return true; + } + + /** + * @dev Function to queue a proposal to the timelock. + */ + function _queueOperations( + uint256 proposalId, + address[] memory targets, + uint256[] memory values, + bytes[] memory calldatas, + bytes32 descriptionHash + ) internal virtual override returns (uint48) { + uint256 delay = _timelock.getMinDelay(); + + bytes32 salt = _timelockSalt(descriptionHash); + _timelockIds[proposalId] = _timelock.hashOperationBatch(targets, values, calldatas, 0, salt); + _timelock.scheduleBatch(targets, values, calldatas, 0, salt, delay); + + return SafeCast.toUint48(block.timestamp + delay); + } + + /** + * @dev Overridden version of the {Governor-_executeOperations} function that runs the already queued proposal + * through the timelock. + */ + function _executeOperations( + uint256 proposalId, + address[] memory targets, + uint256[] memory values, + bytes[] memory calldatas, + bytes32 descriptionHash + ) internal virtual override { + // execute + _timelock.executeBatch{value: msg.value}(targets, values, calldatas, 0, _timelockSalt(descriptionHash)); + // cleanup for refund + delete _timelockIds[proposalId]; + } + + /** + * @dev Overridden version of the {Governor-_cancel} function to cancel the timelocked proposal if it has already + * been queued. + */ + // This function can reenter through the external call to the timelock, but we assume the timelock is trusted and + // well behaved (according to TimelockController) and this will not happen. + // slither-disable-next-line reentrancy-no-eth + function _cancel( + address[] memory targets, + uint256[] memory values, + bytes[] memory calldatas, + bytes32 descriptionHash + ) internal virtual override returns (uint256) { + uint256 proposalId = super._cancel(targets, values, calldatas, descriptionHash); + + bytes32 timelockId = _timelockIds[proposalId]; + if (timelockId != 0) { + // cancel + _timelock.cancel(timelockId); + // cleanup + delete _timelockIds[proposalId]; + } + + return proposalId; + } + + /** + * @dev Address through which the governor executes action. In this case, the timelock. + */ + function _executor() internal view virtual override returns (address) { + return address(_timelock); + } + + /** + * @dev Public endpoint to update the underlying timelock instance. Restricted to the timelock itself, so updates + * must be proposed, scheduled, and executed through governance proposals. + * + * CAUTION: It is not recommended to change the timelock while there are other queued governance proposals. + */ + function updateTimelock(TimelockController newTimelock) external virtual onlyGovernance { + _updateTimelock(newTimelock); + } + + function _updateTimelock(TimelockController newTimelock) private { + emit TimelockChange(address(_timelock), address(newTimelock)); + _timelock = newTimelock; + } + + /** + * @dev Computes the {TimelockController} operation salt. + * + * It is computed with the governor address itself to avoid collisions across governor instances using the + * same timelock. + */ + function _timelockSalt(bytes32 descriptionHash) private view returns (bytes32) { + return bytes20(address(this)) ^ descriptionHash; + } +} diff --git a/contracts/governance/extensions/GovernorVotes.sol b/contracts/governance/extensions/GovernorVotes.sol new file mode 100644 index 000000000..d95fee1bc --- /dev/null +++ b/contracts/governance/extensions/GovernorVotes.sol @@ -0,0 +1,64 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (governance/extensions/GovernorVotes.sol) + +pragma solidity ^0.8.20; + +import {Governor} from "../Governor.sol"; +import {IVotes} from "../utils/IVotes.sol"; +import {IERC5805} from "../../interfaces/IERC5805.sol"; +import {SafeCast} from "../../utils/math/SafeCast.sol"; +import {Time} from "../../utils/types/Time.sol"; + +/** + * @dev Extension of {Governor} for voting weight extraction from an {ERC20Votes} token, or since v4.5 an {ERC721Votes} + * token. + */ +abstract contract GovernorVotes is Governor { + IERC5805 private immutable _token; + + constructor(IVotes tokenAddress) { + _token = IERC5805(address(tokenAddress)); + } + + /** + * @dev The token that voting power is sourced from. + */ + function token() public view virtual returns (IERC5805) { + return _token; + } + + /** + * @dev Clock (as specified in EIP-6372) is set to match the token's clock. Fallback to block numbers if the token + * does not implement EIP-6372. + */ + function clock() public view virtual override returns (uint48) { + try token().clock() returns (uint48 timepoint) { + return timepoint; + } catch { + return Time.blockNumber(); + } + } + + /** + * @dev Machine-readable description of the clock as specified in EIP-6372. + */ + // solhint-disable-next-line func-name-mixedcase + function CLOCK_MODE() public view virtual override returns (string memory) { + try token().CLOCK_MODE() returns (string memory clockmode) { + return clockmode; + } catch { + return "mode=blocknumber&from=default"; + } + } + + /** + * Read the voting weight from the token's built in snapshot mechanism (see {Governor-_getVotes}). + */ + function _getVotes( + address account, + uint256 timepoint, + bytes memory /*params*/ + ) internal view virtual override returns (uint256) { + return token().getPastVotes(account, timepoint); + } +} diff --git a/contracts/governance/extensions/GovernorVotesQuorumFraction.sol b/contracts/governance/extensions/GovernorVotesQuorumFraction.sol new file mode 100644 index 000000000..4a433889d --- /dev/null +++ b/contracts/governance/extensions/GovernorVotesQuorumFraction.sol @@ -0,0 +1,110 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (governance/extensions/GovernorVotesQuorumFraction.sol) + +pragma solidity ^0.8.20; + +import {GovernorVotes} from "./GovernorVotes.sol"; +import {SafeCast} from "../../utils/math/SafeCast.sol"; +import {Checkpoints} from "../../utils/structs/Checkpoints.sol"; + +/** + * @dev Extension of {Governor} for voting weight extraction from an {ERC20Votes} token and a quorum expressed as a + * fraction of the total supply. + */ +abstract contract GovernorVotesQuorumFraction is GovernorVotes { + using Checkpoints for Checkpoints.Trace208; + + Checkpoints.Trace208 private _quorumNumeratorHistory; + + event QuorumNumeratorUpdated(uint256 oldQuorumNumerator, uint256 newQuorumNumerator); + + /** + * @dev The quorum set is not a valid fraction. + */ + error GovernorInvalidQuorumFraction(uint256 quorumNumerator, uint256 quorumDenominator); + + /** + * @dev Initialize quorum as a fraction of the token's total supply. + * + * The fraction is specified as `numerator / denominator`. By default the denominator is 100, so quorum is + * specified as a percent: a numerator of 10 corresponds to quorum being 10% of total supply. The denominator can be + * customized by overriding {quorumDenominator}. + */ + constructor(uint256 quorumNumeratorValue) { + _updateQuorumNumerator(quorumNumeratorValue); + } + + /** + * @dev Returns the current quorum numerator. See {quorumDenominator}. + */ + function quorumNumerator() public view virtual returns (uint256) { + return _quorumNumeratorHistory.latest(); + } + + /** + * @dev Returns the quorum numerator at a specific timepoint. See {quorumDenominator}. + */ + function quorumNumerator(uint256 timepoint) public view virtual returns (uint256) { + uint256 length = _quorumNumeratorHistory._checkpoints.length; + + // Optimistic search, check the latest checkpoint + Checkpoints.Checkpoint208 storage latest = _quorumNumeratorHistory._checkpoints[length - 1]; + uint48 latestKey = latest._key; + uint208 latestValue = latest._value; + if (latestKey <= timepoint) { + return latestValue; + } + + // Otherwise, do the binary search + return _quorumNumeratorHistory.upperLookupRecent(SafeCast.toUint48(timepoint)); + } + + /** + * @dev Returns the quorum denominator. Defaults to 100, but may be overridden. + */ + function quorumDenominator() public view virtual returns (uint256) { + return 100; + } + + /** + * @dev Returns the quorum for a timepoint, in terms of number of votes: `supply * numerator / denominator`. + */ + function quorum(uint256 timepoint) public view virtual override returns (uint256) { + return (token().getPastTotalSupply(timepoint) * quorumNumerator(timepoint)) / quorumDenominator(); + } + + /** + * @dev Changes the quorum numerator. + * + * Emits a {QuorumNumeratorUpdated} event. + * + * Requirements: + * + * - Must be called through a governance proposal. + * - New numerator must be smaller or equal to the denominator. + */ + function updateQuorumNumerator(uint256 newQuorumNumerator) external virtual onlyGovernance { + _updateQuorumNumerator(newQuorumNumerator); + } + + /** + * @dev Changes the quorum numerator. + * + * Emits a {QuorumNumeratorUpdated} event. + * + * Requirements: + * + * - New numerator must be smaller or equal to the denominator. + */ + function _updateQuorumNumerator(uint256 newQuorumNumerator) internal virtual { + uint256 denominator = quorumDenominator(); + if (newQuorumNumerator > denominator) { + revert GovernorInvalidQuorumFraction(newQuorumNumerator, denominator); + } + + uint256 oldQuorumNumerator = quorumNumerator(); + _quorumNumeratorHistory.push(clock(), SafeCast.toUint208(newQuorumNumerator)); + + emit QuorumNumeratorUpdated(oldQuorumNumerator, newQuorumNumerator); + } +} diff --git a/contracts/governance/utils/IVotes.sol b/contracts/governance/utils/IVotes.sol new file mode 100644 index 000000000..7131ecf09 --- /dev/null +++ b/contracts/governance/utils/IVotes.sol @@ -0,0 +1,59 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (governance/utils/IVotes.sol) +pragma solidity ^0.8.20; + +/** + * @dev Common interface for {ERC20Votes}, {ERC721Votes}, and other {Votes}-enabled contracts. + */ +interface IVotes { + /** + * @dev The signature used has expired. + */ + error VotesExpiredSignature(uint256 expiry); + + /** + * @dev Emitted when an account changes their delegate. + */ + event DelegateChanged(address indexed delegator, address indexed fromDelegate, address indexed toDelegate); + + /** + * @dev Emitted when a token transfer or delegate change results in changes to a delegate's number of voting units. + */ + event DelegateVotesChanged(address indexed delegate, uint256 previousVotes, uint256 newVotes); + + /** + * @dev Returns the current amount of votes that `account` has. + */ + function getVotes(address account) external view returns (uint256); + + /** + * @dev Returns the amount of votes that `account` had at a specific moment in the past. If the `clock()` is + * configured to use block numbers, this will return the value at the end of the corresponding block. + */ + function getPastVotes(address account, uint256 timepoint) external view returns (uint256); + + /** + * @dev Returns the total supply of votes available at a specific moment in the past. If the `clock()` is + * configured to use block numbers, this will return the value at the end of the corresponding block. + * + * NOTE: This value is the sum of all available votes, which is not necessarily the sum of all delegated votes. + * Votes that have not been delegated are still part of total supply, even though they would not participate in a + * vote. + */ + function getPastTotalSupply(uint256 timepoint) external view returns (uint256); + + /** + * @dev Returns the delegate that `account` has chosen. + */ + function delegates(address account) external view returns (address); + + /** + * @dev Delegates votes from the sender to `delegatee`. + */ + function delegate(address delegatee) external; + + /** + * @dev Delegates votes from signer to `delegatee`. + */ + function delegateBySig(address delegatee, uint256 nonce, uint256 expiry, uint8 v, bytes32 r, bytes32 s) external; +} diff --git a/contracts/governance/utils/Votes.sol b/contracts/governance/utils/Votes.sol new file mode 100644 index 000000000..56c8772f9 --- /dev/null +++ b/contracts/governance/utils/Votes.sol @@ -0,0 +1,251 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (governance/utils/Votes.sol) +pragma solidity ^0.8.20; + +import {IERC5805} from "../../interfaces/IERC5805.sol"; +import {Context} from "../../utils/Context.sol"; +import {Nonces} from "../../utils/Nonces.sol"; +import {EIP712} from "../../utils/cryptography/EIP712.sol"; +import {Checkpoints} from "../../utils/structs/Checkpoints.sol"; +import {SafeCast} from "../../utils/math/SafeCast.sol"; +import {ECDSA} from "../../utils/cryptography/ECDSA.sol"; +import {Time} from "../../utils/types/Time.sol"; + +/** + * @dev This is a base abstract contract that tracks voting units, which are a measure of voting power that can be + * transferred, and provides a system of vote delegation, where an account can delegate its voting units to a sort of + * "representative" that will pool delegated voting units from different accounts and can then use it to vote in + * decisions. In fact, voting units _must_ be delegated in order to count as actual votes, and an account has to + * delegate those votes to itself if it wishes to participate in decisions and does not have a trusted representative. + * + * This contract is often combined with a token contract such that voting units correspond to token units. For an + * example, see {ERC721Votes}. + * + * The full history of delegate votes is tracked on-chain so that governance protocols can consider votes as distributed + * at a particular block number to protect against flash loans and double voting. The opt-in delegate system makes the + * cost of this history tracking optional. + * + * When using this module the derived contract must implement {_getVotingUnits} (for example, make it return + * {ERC721-balanceOf}), and can use {_transferVotingUnits} to track a change in the distribution of those units (in the + * previous example, it would be included in {ERC721-_beforeTokenTransfer}). + */ +abstract contract Votes is Context, EIP712, Nonces, IERC5805 { + using Checkpoints for Checkpoints.Trace208; + + bytes32 private constant DELEGATION_TYPEHASH = + keccak256("Delegation(address delegatee,uint256 nonce,uint256 expiry)"); + + mapping(address account => address) private _delegatee; + + mapping(address delegatee => Checkpoints.Trace208) private _delegateCheckpoints; + + Checkpoints.Trace208 private _totalCheckpoints; + + /** + * @dev The clock was incorrectly modified. + */ + error ERC6372InconsistentClock(); + + /** + * @dev Lookup to future votes is not available. + */ + error ERC5805FutureLookup(uint256 timepoint, uint48 clock); + + /** + * @dev Clock used for flagging checkpoints. Can be overridden to implement timestamp based + * checkpoints (and voting), in which case {CLOCK_MODE} should be overridden as well to match. + */ + function clock() public view virtual returns (uint48) { + return Time.blockNumber(); + } + + /** + * @dev Machine-readable description of the clock as specified in EIP-6372. + */ + // solhint-disable-next-line func-name-mixedcase + function CLOCK_MODE() public view virtual returns (string memory) { + // Check that the clock was not modified + if (clock() != Time.blockNumber()) { + revert ERC6372InconsistentClock(); + } + return "mode=blocknumber&from=default"; + } + + /** + * @dev Returns the current amount of votes that `account` has. + */ + function getVotes(address account) public view virtual returns (uint256) { + return _delegateCheckpoints[account].latest(); + } + + /** + * @dev Returns the amount of votes that `account` had at a specific moment in the past. If the `clock()` is + * configured to use block numbers, this will return the value at the end of the corresponding block. + * + * Requirements: + * + * - `timepoint` must be in the past. If operating using block numbers, the block must be already mined. + */ + function getPastVotes(address account, uint256 timepoint) public view virtual returns (uint256) { + uint48 currentTimepoint = clock(); + if (timepoint >= currentTimepoint) { + revert ERC5805FutureLookup(timepoint, currentTimepoint); + } + return _delegateCheckpoints[account].upperLookupRecent(SafeCast.toUint48(timepoint)); + } + + /** + * @dev Returns the total supply of votes available at a specific moment in the past. If the `clock()` is + * configured to use block numbers, this will return the value at the end of the corresponding block. + * + * NOTE: This value is the sum of all available votes, which is not necessarily the sum of all delegated votes. + * Votes that have not been delegated are still part of total supply, even though they would not participate in a + * vote. + * + * Requirements: + * + * - `timepoint` must be in the past. If operating using block numbers, the block must be already mined. + */ + function getPastTotalSupply(uint256 timepoint) public view virtual returns (uint256) { + uint48 currentTimepoint = clock(); + if (timepoint >= currentTimepoint) { + revert ERC5805FutureLookup(timepoint, currentTimepoint); + } + return _totalCheckpoints.upperLookupRecent(SafeCast.toUint48(timepoint)); + } + + /** + * @dev Returns the current total supply of votes. + */ + function _getTotalSupply() internal view virtual returns (uint256) { + return _totalCheckpoints.latest(); + } + + /** + * @dev Returns the delegate that `account` has chosen. + */ + function delegates(address account) public view virtual returns (address) { + return _delegatee[account]; + } + + /** + * @dev Delegates votes from the sender to `delegatee`. + */ + function delegate(address delegatee) public virtual { + address account = _msgSender(); + _delegate(account, delegatee); + } + + /** + * @dev Delegates votes from signer to `delegatee`. + */ + function delegateBySig( + address delegatee, + uint256 nonce, + uint256 expiry, + uint8 v, + bytes32 r, + bytes32 s + ) public virtual { + if (block.timestamp > expiry) { + revert VotesExpiredSignature(expiry); + } + address signer = ECDSA.recover( + _hashTypedDataV4(keccak256(abi.encode(DELEGATION_TYPEHASH, delegatee, nonce, expiry))), + v, + r, + s + ); + _useCheckedNonce(signer, nonce); + _delegate(signer, delegatee); + } + + /** + * @dev Delegate all of `account`'s voting units to `delegatee`. + * + * Emits events {IVotes-DelegateChanged} and {IVotes-DelegateVotesChanged}. + */ + function _delegate(address account, address delegatee) internal virtual { + address oldDelegate = delegates(account); + _delegatee[account] = delegatee; + + emit DelegateChanged(account, oldDelegate, delegatee); + _moveDelegateVotes(oldDelegate, delegatee, _getVotingUnits(account)); + } + + /** + * @dev Transfers, mints, or burns voting units. To register a mint, `from` should be zero. To register a burn, `to` + * should be zero. Total supply of voting units will be adjusted with mints and burns. + */ + function _transferVotingUnits(address from, address to, uint256 amount) internal virtual { + if (from == address(0)) { + _push(_totalCheckpoints, _add, SafeCast.toUint208(amount)); + } + if (to == address(0)) { + _push(_totalCheckpoints, _subtract, SafeCast.toUint208(amount)); + } + _moveDelegateVotes(delegates(from), delegates(to), amount); + } + + /** + * @dev Moves delegated votes from one delegate to another. + */ + function _moveDelegateVotes(address from, address to, uint256 amount) private { + if (from != to && amount > 0) { + if (from != address(0)) { + (uint256 oldValue, uint256 newValue) = _push( + _delegateCheckpoints[from], + _subtract, + SafeCast.toUint208(amount) + ); + emit DelegateVotesChanged(from, oldValue, newValue); + } + if (to != address(0)) { + (uint256 oldValue, uint256 newValue) = _push( + _delegateCheckpoints[to], + _add, + SafeCast.toUint208(amount) + ); + emit DelegateVotesChanged(to, oldValue, newValue); + } + } + } + + /** + * @dev Get number of checkpoints for `account`. + */ + function _numCheckpoints(address account) internal view virtual returns (uint32) { + return SafeCast.toUint32(_delegateCheckpoints[account].length()); + } + + /** + * @dev Get the `pos`-th checkpoint for `account`. + */ + function _checkpoints( + address account, + uint32 pos + ) internal view virtual returns (Checkpoints.Checkpoint208 memory) { + return _delegateCheckpoints[account].at(pos); + } + + function _push( + Checkpoints.Trace208 storage store, + function(uint208, uint208) view returns (uint208) op, + uint208 delta + ) private returns (uint208, uint208) { + return store.push(clock(), op(store.latest(), delta)); + } + + function _add(uint208 a, uint208 b) private pure returns (uint208) { + return a + b; + } + + function _subtract(uint208 a, uint208 b) private pure returns (uint208) { + return a - b; + } + + /** + * @dev Must return the voting units held by an account. + */ + function _getVotingUnits(address) internal view virtual returns (uint256); +} diff --git a/contracts/interfaces/IERC1155.sol b/contracts/interfaces/IERC1155.sol new file mode 100644 index 000000000..4375627cb --- /dev/null +++ b/contracts/interfaces/IERC1155.sol @@ -0,0 +1,6 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (interfaces/IERC1155.sol) + +pragma solidity ^0.8.20; + +import {IERC1155} from "../token/ERC1155/IERC1155.sol"; diff --git a/contracts/interfaces/IERC1155MetadataURI.sol b/contracts/interfaces/IERC1155MetadataURI.sol new file mode 100644 index 000000000..72448a2a8 --- /dev/null +++ b/contracts/interfaces/IERC1155MetadataURI.sol @@ -0,0 +1,6 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (interfaces/IERC1155MetadataURI.sol) + +pragma solidity ^0.8.20; + +import {IERC1155MetadataURI} from "../token/ERC1155/extensions/IERC1155MetadataURI.sol"; diff --git a/contracts/interfaces/IERC1155Receiver.sol b/contracts/interfaces/IERC1155Receiver.sol new file mode 100644 index 000000000..ec3aa3919 --- /dev/null +++ b/contracts/interfaces/IERC1155Receiver.sol @@ -0,0 +1,6 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (interfaces/IERC1155Receiver.sol) + +pragma solidity ^0.8.20; + +import {IERC1155Receiver} from "../token/ERC1155/IERC1155Receiver.sol"; diff --git a/contracts/interfaces/IERC1271.sol b/contracts/interfaces/IERC1271.sol new file mode 100644 index 000000000..52a1ef2e1 --- /dev/null +++ b/contracts/interfaces/IERC1271.sol @@ -0,0 +1,17 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (interfaces/IERC1271.sol) + +pragma solidity ^0.8.20; + +/** + * @dev Interface of the ERC1271 standard signature validation method for + * contracts as defined in https://eips.ethereum.org/EIPS/eip-1271[ERC-1271]. + */ +interface IERC1271 { + /** + * @dev Should return whether the signature provided is valid for the provided data + * @param hash Hash of the data to be signed + * @param signature Signature byte array associated with _data + */ + function isValidSignature(bytes32 hash, bytes memory signature) external view returns (bytes4 magicValue); +} diff --git a/contracts/interfaces/IERC1363.sol b/contracts/interfaces/IERC1363.sol new file mode 100644 index 000000000..6f32a6dcb --- /dev/null +++ b/contracts/interfaces/IERC1363.sol @@ -0,0 +1,80 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (interfaces/IERC1363.sol) + +pragma solidity ^0.8.20; + +import {IERC20} from "./IERC20.sol"; +import {IERC165} from "./IERC165.sol"; + +/** + * @dev Interface of an ERC1363 compliant contract, as defined in the + * https://eips.ethereum.org/EIPS/eip-1363[EIP]. + * + * Defines a interface for ERC20 tokens that supports executing recipient + * code after `transfer` or `transferFrom`, or spender code after `approve`. + */ +interface IERC1363 is IERC165, IERC20 { + /* + * Note: the ERC-165 identifier for this interface is 0xb0202a11. + * 0xb0202a11 === + * bytes4(keccak256('transferAndCall(address,uint256)')) ^ + * bytes4(keccak256('transferAndCall(address,uint256,bytes)')) ^ + * bytes4(keccak256('transferFromAndCall(address,address,uint256)')) ^ + * bytes4(keccak256('transferFromAndCall(address,address,uint256,bytes)')) ^ + * bytes4(keccak256('approveAndCall(address,uint256)')) ^ + * bytes4(keccak256('approveAndCall(address,uint256,bytes)')) + */ + + /** + * @dev Transfer tokens from `msg.sender` to another address and then call `onTransferReceived` on receiver + * @param to address The address which you want to transfer to + * @param amount uint256 The amount of tokens to be transferred + * @return true unless throwing + */ + function transferAndCall(address to, uint256 amount) external returns (bool); + + /** + * @dev Transfer tokens from `msg.sender` to another address and then call `onTransferReceived` on receiver + * @param to address The address which you want to transfer to + * @param amount uint256 The amount of tokens to be transferred + * @param data bytes Additional data with no specified format, sent in call to `to` + * @return true unless throwing + */ + function transferAndCall(address to, uint256 amount, bytes memory data) external returns (bool); + + /** + * @dev Transfer tokens from one address to another and then call `onTransferReceived` on receiver + * @param from address The address which you want to send tokens from + * @param to address The address which you want to transfer to + * @param amount uint256 The amount of tokens to be transferred + * @return true unless throwing + */ + function transferFromAndCall(address from, address to, uint256 amount) external returns (bool); + + /** + * @dev Transfer tokens from one address to another and then call `onTransferReceived` on receiver + * @param from address The address which you want to send tokens from + * @param to address The address which you want to transfer to + * @param amount uint256 The amount of tokens to be transferred + * @param data bytes Additional data with no specified format, sent in call to `to` + * @return true unless throwing + */ + function transferFromAndCall(address from, address to, uint256 amount, bytes memory data) external returns (bool); + + /** + * @dev Approve the passed address to spend the specified amount of tokens on behalf of msg.sender + * and then call `onApprovalReceived` on spender. + * @param spender address The address which will spend the funds + * @param amount uint256 The amount of tokens to be spent + */ + function approveAndCall(address spender, uint256 amount) external returns (bool); + + /** + * @dev Approve the passed address to spend the specified amount of tokens on behalf of msg.sender + * and then call `onApprovalReceived` on spender. + * @param spender address The address which will spend the funds + * @param amount uint256 The amount of tokens to be spent + * @param data bytes Additional data with no specified format, sent in call to `spender` + */ + function approveAndCall(address spender, uint256 amount, bytes memory data) external returns (bool); +} diff --git a/contracts/interfaces/IERC1363Receiver.sol b/contracts/interfaces/IERC1363Receiver.sol new file mode 100644 index 000000000..875fc60cc --- /dev/null +++ b/contracts/interfaces/IERC1363Receiver.sol @@ -0,0 +1,35 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (interfaces/IERC1363Receiver.sol) + +pragma solidity ^0.8.20; + +/** + * @dev Interface for any contract that wants to support {IERC1363-transferAndCall} + * or {IERC1363-transferFromAndCall} from {ERC1363} token contracts. + */ +interface IERC1363Receiver { + /* + * Note: the ERC-165 identifier for this interface is 0x88a7ca5c. + * 0x88a7ca5c === bytes4(keccak256("onTransferReceived(address,address,uint256,bytes)")) + */ + + /** + * @notice Handle the receipt of ERC1363 tokens + * @dev Any ERC1363 smart contract calls this function on the recipient + * after a `transfer` or a `transferFrom`. This function MAY throw to revert and reject the + * transfer. Return of other than the magic value MUST result in the + * transaction being reverted. + * Note: the token contract address is always the message sender. + * @param operator address The address which called `transferAndCall` or `transferFromAndCall` function + * @param from address The address which are token transferred from + * @param amount uint256 The amount of tokens transferred + * @param data bytes Additional data with no specified format + * @return `bytes4(keccak256("onTransferReceived(address,address,uint256,bytes)"))` unless throwing + */ + function onTransferReceived( + address operator, + address from, + uint256 amount, + bytes memory data + ) external returns (bytes4); +} diff --git a/contracts/interfaces/IERC1363Spender.sol b/contracts/interfaces/IERC1363Spender.sol new file mode 100644 index 000000000..b68d9b534 --- /dev/null +++ b/contracts/interfaces/IERC1363Spender.sol @@ -0,0 +1,29 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (interfaces/IERC1363Spender.sol) + +pragma solidity ^0.8.20; + +/** + * @dev Interface for any contract that wants to support {IERC1363-approveAndCall} + * from {ERC1363} token contracts. + */ +interface IERC1363Spender { + /* + * Note: the ERC-165 identifier for this interface is 0x7b04a2d0. + * 0x7b04a2d0 === bytes4(keccak256("onApprovalReceived(address,uint256,bytes)")) + */ + + /** + * @notice Handle the approval of ERC1363 tokens + * @dev Any ERC1363 smart contract calls this function on the recipient + * after an `approve`. This function MAY throw to revert and reject the + * approval. Return of other than the magic value MUST result in the + * transaction being reverted. + * Note: the token contract address is always the message sender. + * @param owner address The address which called `approveAndCall` function + * @param amount uint256 The amount of tokens to be spent + * @param data bytes Additional data with no specified format + * @return `bytes4(keccak256("onApprovalReceived(address,uint256,bytes)"))`unless throwing + */ + function onApprovalReceived(address owner, uint256 amount, bytes memory data) external returns (bytes4); +} diff --git a/contracts/interfaces/IERC165.sol b/contracts/interfaces/IERC165.sol new file mode 100644 index 000000000..e3cc30c37 --- /dev/null +++ b/contracts/interfaces/IERC165.sol @@ -0,0 +1,6 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (interfaces/IERC165.sol) + +pragma solidity ^0.8.20; + +import {IERC165} from "../utils/introspection/IERC165.sol"; diff --git a/contracts/interfaces/IERC1820Implementer.sol b/contracts/interfaces/IERC1820Implementer.sol new file mode 100644 index 000000000..debe03c4e --- /dev/null +++ b/contracts/interfaces/IERC1820Implementer.sol @@ -0,0 +1,20 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (interfaces/IERC1820Implementer.sol) + +pragma solidity ^0.8.20; + +/** + * @dev Interface for an ERC1820 implementer, as defined in the + * https://eips.ethereum.org/EIPS/eip-1820#interface-implementation-erc1820implementerinterface[EIP]. + * Used by contracts that will be registered as implementers in the + * {IERC1820Registry}. + */ +interface IERC1820Implementer { + /** + * @dev Returns a special value (`ERC1820_ACCEPT_MAGIC`) if this contract + * implements `interfaceHash` for `account`. + * + * See {IERC1820Registry-setInterfaceImplementer}. + */ + function canImplementInterfaceForAddress(bytes32 interfaceHash, address account) external view returns (bytes32); +} diff --git a/contracts/interfaces/IERC1820Registry.sol b/contracts/interfaces/IERC1820Registry.sol new file mode 100644 index 000000000..7e7a96276 --- /dev/null +++ b/contracts/interfaces/IERC1820Registry.sol @@ -0,0 +1,112 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (interfaces/IERC1820Registry.sol) + +pragma solidity ^0.8.20; + +/** + * @dev Interface of the global ERC1820 Registry, as defined in the + * https://eips.ethereum.org/EIPS/eip-1820[EIP]. Accounts may register + * implementers for interfaces in this registry, as well as query support. + * + * Implementers may be shared by multiple accounts, and can also implement more + * than a single interface for each account. Contracts can implement interfaces + * for themselves, but externally-owned accounts (EOA) must delegate this to a + * contract. + * + * {IERC165} interfaces can also be queried via the registry. + * + * For an in-depth explanation and source code analysis, see the EIP text. + */ +interface IERC1820Registry { + event InterfaceImplementerSet(address indexed account, bytes32 indexed interfaceHash, address indexed implementer); + + event ManagerChanged(address indexed account, address indexed newManager); + + /** + * @dev Sets `newManager` as the manager for `account`. A manager of an + * account is able to set interface implementers for it. + * + * By default, each account is its own manager. Passing a value of `0x0` in + * `newManager` will reset the manager to this initial state. + * + * Emits a {ManagerChanged} event. + * + * Requirements: + * + * - the caller must be the current manager for `account`. + */ + function setManager(address account, address newManager) external; + + /** + * @dev Returns the manager for `account`. + * + * See {setManager}. + */ + function getManager(address account) external view returns (address); + + /** + * @dev Sets the `implementer` contract as ``account``'s implementer for + * `interfaceHash`. + * + * `account` being the zero address is an alias for the caller's address. + * The zero address can also be used in `implementer` to remove an old one. + * + * See {interfaceHash} to learn how these are created. + * + * Emits an {InterfaceImplementerSet} event. + * + * Requirements: + * + * - the caller must be the current manager for `account`. + * - `interfaceHash` must not be an {IERC165} interface id (i.e. it must not + * end in 28 zeroes). + * - `implementer` must implement {IERC1820Implementer} and return true when + * queried for support, unless `implementer` is the caller. See + * {IERC1820Implementer-canImplementInterfaceForAddress}. + */ + function setInterfaceImplementer(address account, bytes32 _interfaceHash, address implementer) external; + + /** + * @dev Returns the implementer of `interfaceHash` for `account`. If no such + * implementer is registered, returns the zero address. + * + * If `interfaceHash` is an {IERC165} interface id (i.e. it ends with 28 + * zeroes), `account` will be queried for support of it. + * + * `account` being the zero address is an alias for the caller's address. + */ + function getInterfaceImplementer(address account, bytes32 _interfaceHash) external view returns (address); + + /** + * @dev Returns the interface hash for an `interfaceName`, as defined in the + * corresponding + * https://eips.ethereum.org/EIPS/eip-1820#interface-name[section of the EIP]. + */ + function interfaceHash(string calldata interfaceName) external pure returns (bytes32); + + /** + * @notice Updates the cache with whether the contract implements an ERC165 interface or not. + * @param account Address of the contract for which to update the cache. + * @param interfaceId ERC165 interface for which to update the cache. + */ + function updateERC165Cache(address account, bytes4 interfaceId) external; + + /** + * @notice Checks whether a contract implements an ERC165 interface or not. + * If the result is not cached a direct lookup on the contract address is performed. + * If the result is not cached or the cached value is out-of-date, the cache MUST be updated manually by calling + * {updateERC165Cache} with the contract address. + * @param account Address of the contract to check. + * @param interfaceId ERC165 interface to check. + * @return True if `account` implements `interfaceId`, false otherwise. + */ + function implementsERC165Interface(address account, bytes4 interfaceId) external view returns (bool); + + /** + * @notice Checks whether a contract implements an ERC165 interface or not without using or updating the cache. + * @param account Address of the contract to check. + * @param interfaceId ERC165 interface to check. + * @return True if `account` implements `interfaceId`, false otherwise. + */ + function implementsERC165InterfaceNoCache(address account, bytes4 interfaceId) external view returns (bool); +} diff --git a/contracts/interfaces/IERC1967.sol b/contracts/interfaces/IERC1967.sol new file mode 100644 index 000000000..9af812c1c --- /dev/null +++ b/contracts/interfaces/IERC1967.sol @@ -0,0 +1,24 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (interfaces/IERC1967.sol) + +pragma solidity ^0.8.20; + +/** + * @dev ERC-1967: Proxy Storage Slots. This interface contains the events defined in the ERC. + */ +interface IERC1967 { + /** + * @dev Emitted when the implementation is upgraded. + */ + event Upgraded(address indexed implementation); + + /** + * @dev Emitted when the admin account has changed. + */ + event AdminChanged(address previousAdmin, address newAdmin); + + /** + * @dev Emitted when the beacon is changed. + */ + event BeaconUpgraded(address indexed beacon); +} diff --git a/contracts/interfaces/IERC20.sol b/contracts/interfaces/IERC20.sol new file mode 100644 index 000000000..d97be9f3d --- /dev/null +++ b/contracts/interfaces/IERC20.sol @@ -0,0 +1,6 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (interfaces/IERC20.sol) + +pragma solidity ^0.8.20; + +import {IERC20} from "../token/ERC20/IERC20.sol"; diff --git a/contracts/interfaces/IERC20Metadata.sol b/contracts/interfaces/IERC20Metadata.sol new file mode 100644 index 000000000..b8b33bf3e --- /dev/null +++ b/contracts/interfaces/IERC20Metadata.sol @@ -0,0 +1,6 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (interfaces/IERC20Metadata.sol) + +pragma solidity ^0.8.20; + +import {IERC20Metadata} from "../token/ERC20/extensions/IERC20Metadata.sol"; diff --git a/contracts/interfaces/IERC2309.sol b/contracts/interfaces/IERC2309.sol new file mode 100644 index 000000000..49d9be1fc --- /dev/null +++ b/contracts/interfaces/IERC2309.sol @@ -0,0 +1,19 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (interfaces/IERC2309.sol) + +pragma solidity ^0.8.20; + +/** + * @dev ERC-2309: ERC-721 Consecutive Transfer Extension. + */ +interface IERC2309 { + /** + * @dev Emitted when the tokens from `fromTokenId` to `toTokenId` are transferred from `fromAddress` to `toAddress`. + */ + event ConsecutiveTransfer( + uint256 indexed fromTokenId, + uint256 toTokenId, + address indexed fromAddress, + address indexed toAddress + ); +} diff --git a/contracts/interfaces/IERC2612.sol b/contracts/interfaces/IERC2612.sol new file mode 100644 index 000000000..626eb00b1 --- /dev/null +++ b/contracts/interfaces/IERC2612.sol @@ -0,0 +1,8 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (interfaces/IERC2612.sol) + +pragma solidity ^0.8.20; + +import {IERC20Permit} from "../token/ERC20/extensions/IERC20Permit.sol"; + +interface IERC2612 is IERC20Permit {} diff --git a/contracts/interfaces/IERC2981.sol b/contracts/interfaces/IERC2981.sol new file mode 100644 index 000000000..16244ab82 --- /dev/null +++ b/contracts/interfaces/IERC2981.sol @@ -0,0 +1,23 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (interfaces/IERC2981.sol) + +pragma solidity ^0.8.20; + +import {IERC165} from "../utils/introspection/IERC165.sol"; + +/** + * @dev Interface for the NFT Royalty Standard. + * + * A standardized way to retrieve royalty payment information for non-fungible tokens (NFTs) to enable universal + * support for royalty payments across all NFT marketplaces and ecosystem participants. + */ +interface IERC2981 is IERC165 { + /** + * @dev Returns how much royalty is owed and to whom, based on a sale price that may be denominated in any unit of + * exchange. The royalty amount is denominated and should be paid in that same unit of exchange. + */ + function royaltyInfo( + uint256 tokenId, + uint256 salePrice + ) external view returns (address receiver, uint256 royaltyAmount); +} diff --git a/contracts/interfaces/IERC3156.sol b/contracts/interfaces/IERC3156.sol new file mode 100644 index 000000000..1446e040d --- /dev/null +++ b/contracts/interfaces/IERC3156.sol @@ -0,0 +1,7 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (interfaces/IERC3156.sol) + +pragma solidity ^0.8.20; + +import {IERC3156FlashBorrower} from "./IERC3156FlashBorrower.sol"; +import {IERC3156FlashLender} from "./IERC3156FlashLender.sol"; diff --git a/contracts/interfaces/IERC3156FlashBorrower.sol b/contracts/interfaces/IERC3156FlashBorrower.sol new file mode 100644 index 000000000..ded8ef2f4 --- /dev/null +++ b/contracts/interfaces/IERC3156FlashBorrower.sol @@ -0,0 +1,27 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (interfaces/IERC3156FlashBorrower.sol) + +pragma solidity ^0.8.20; + +/** + * @dev Interface of the ERC3156 FlashBorrower, as defined in + * https://eips.ethereum.org/EIPS/eip-3156[ERC-3156]. + */ +interface IERC3156FlashBorrower { + /** + * @dev Receive a flash loan. + * @param initiator The initiator of the loan. + * @param token The loan currency. + * @param amount The amount of tokens lent. + * @param fee The additional amount of tokens to repay. + * @param data Arbitrary data structure, intended to contain user-defined parameters. + * @return The keccak256 hash of "ERC3156FlashBorrower.onFlashLoan" + */ + function onFlashLoan( + address initiator, + address token, + uint256 amount, + uint256 fee, + bytes calldata data + ) external returns (bytes32); +} diff --git a/contracts/interfaces/IERC3156FlashLender.sol b/contracts/interfaces/IERC3156FlashLender.sol new file mode 100644 index 000000000..1ad0decac --- /dev/null +++ b/contracts/interfaces/IERC3156FlashLender.sol @@ -0,0 +1,41 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (interfaces/IERC3156FlashLender.sol) + +pragma solidity ^0.8.20; + +import {IERC3156FlashBorrower} from "./IERC3156FlashBorrower.sol"; + +/** + * @dev Interface of the ERC3156 FlashLender, as defined in + * https://eips.ethereum.org/EIPS/eip-3156[ERC-3156]. + */ +interface IERC3156FlashLender { + /** + * @dev The amount of currency available to be lended. + * @param token The loan currency. + * @return The amount of `token` that can be borrowed. + */ + function maxFlashLoan(address token) external view returns (uint256); + + /** + * @dev The fee to be charged for a given loan. + * @param token The loan currency. + * @param amount The amount of tokens lent. + * @return The amount of `token` to be charged for the loan, on top of the returned principal. + */ + function flashFee(address token, uint256 amount) external view returns (uint256); + + /** + * @dev Initiate a flash loan. + * @param receiver The receiver of the tokens in the loan, and the receiver of the callback. + * @param token The loan currency. + * @param amount The amount of tokens lent. + * @param data Arbitrary data structure, intended to contain user-defined parameters. + */ + function flashLoan( + IERC3156FlashBorrower receiver, + address token, + uint256 amount, + bytes calldata data + ) external returns (bool); +} diff --git a/contracts/interfaces/IERC4626.sol b/contracts/interfaces/IERC4626.sol new file mode 100644 index 000000000..bd76c8427 --- /dev/null +++ b/contracts/interfaces/IERC4626.sol @@ -0,0 +1,230 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (interfaces/IERC4626.sol) + +pragma solidity ^0.8.20; + +import {IERC20} from "../token/ERC20/IERC20.sol"; +import {IERC20Metadata} from "../token/ERC20/extensions/IERC20Metadata.sol"; + +/** + * @dev Interface of the ERC4626 "Tokenized Vault Standard", as defined in + * https://eips.ethereum.org/EIPS/eip-4626[ERC-4626]. + */ +interface IERC4626 is IERC20, IERC20Metadata { + event Deposit(address indexed sender, address indexed owner, uint256 assets, uint256 shares); + + event Withdraw( + address indexed sender, + address indexed receiver, + address indexed owner, + uint256 assets, + uint256 shares + ); + + /** + * @dev Returns the address of the underlying token used for the Vault for accounting, depositing, and withdrawing. + * + * - MUST be an ERC-20 token contract. + * - MUST NOT revert. + */ + function asset() external view returns (address assetTokenAddress); + + /** + * @dev Returns the total amount of the underlying asset that is “managed” by Vault. + * + * - SHOULD include any compounding that occurs from yield. + * - MUST be inclusive of any fees that are charged against assets in the Vault. + * - MUST NOT revert. + */ + function totalAssets() external view returns (uint256 totalManagedAssets); + + /** + * @dev Returns the amount of shares that the Vault would exchange for the amount of assets provided, in an ideal + * scenario where all the conditions are met. + * + * - MUST NOT be inclusive of any fees that are charged against assets in the Vault. + * - MUST NOT show any variations depending on the caller. + * - MUST NOT reflect slippage or other on-chain conditions, when performing the actual exchange. + * - MUST NOT revert. + * + * NOTE: This calculation MAY NOT reflect the “per-user” price-per-share, and instead should reflect the + * “average-user’s” price-per-share, meaning what the average user should expect to see when exchanging to and + * from. + */ + function convertToShares(uint256 assets) external view returns (uint256 shares); + + /** + * @dev Returns the amount of assets that the Vault would exchange for the amount of shares provided, in an ideal + * scenario where all the conditions are met. + * + * - MUST NOT be inclusive of any fees that are charged against assets in the Vault. + * - MUST NOT show any variations depending on the caller. + * - MUST NOT reflect slippage or other on-chain conditions, when performing the actual exchange. + * - MUST NOT revert. + * + * NOTE: This calculation MAY NOT reflect the “per-user” price-per-share, and instead should reflect the + * “average-user’s” price-per-share, meaning what the average user should expect to see when exchanging to and + * from. + */ + function convertToAssets(uint256 shares) external view returns (uint256 assets); + + /** + * @dev Returns the maximum amount of the underlying asset that can be deposited into the Vault for the receiver, + * through a deposit call. + * + * - MUST return a limited value if receiver is subject to some deposit limit. + * - MUST return 2 ** 256 - 1 if there is no limit on the maximum amount of assets that may be deposited. + * - MUST NOT revert. + */ + function maxDeposit(address receiver) external view returns (uint256 maxAssets); + + /** + * @dev Allows an on-chain or off-chain user to simulate the effects of their deposit at the current block, given + * current on-chain conditions. + * + * - MUST return as close to and no more than the exact amount of Vault shares that would be minted in a deposit + * call in the same transaction. I.e. deposit should return the same or more shares as previewDeposit if called + * in the same transaction. + * - MUST NOT account for deposit limits like those returned from maxDeposit and should always act as though the + * deposit would be accepted, regardless if the user has enough tokens approved, etc. + * - MUST be inclusive of deposit fees. Integrators should be aware of the existence of deposit fees. + * - MUST NOT revert. + * + * NOTE: any unfavorable discrepancy between convertToShares and previewDeposit SHOULD be considered slippage in + * share price or some other type of condition, meaning the depositor will lose assets by depositing. + */ + function previewDeposit(uint256 assets) external view returns (uint256 shares); + + /** + * @dev Mints shares Vault shares to receiver by depositing exactly amount of underlying tokens. + * + * - MUST emit the Deposit event. + * - MAY support an additional flow in which the underlying tokens are owned by the Vault contract before the + * deposit execution, and are accounted for during deposit. + * - MUST revert if all of assets cannot be deposited (due to deposit limit being reached, slippage, the user not + * approving enough underlying tokens to the Vault contract, etc). + * + * NOTE: most implementations will require pre-approval of the Vault with the Vault’s underlying asset token. + */ + function deposit(uint256 assets, address receiver) external returns (uint256 shares); + + /** + * @dev Returns the maximum amount of the Vault shares that can be minted for the receiver, through a mint call. + * - MUST return a limited value if receiver is subject to some mint limit. + * - MUST return 2 ** 256 - 1 if there is no limit on the maximum amount of shares that may be minted. + * - MUST NOT revert. + */ + function maxMint(address receiver) external view returns (uint256 maxShares); + + /** + * @dev Allows an on-chain or off-chain user to simulate the effects of their mint at the current block, given + * current on-chain conditions. + * + * - MUST return as close to and no fewer than the exact amount of assets that would be deposited in a mint call + * in the same transaction. I.e. mint should return the same or fewer assets as previewMint if called in the + * same transaction. + * - MUST NOT account for mint limits like those returned from maxMint and should always act as though the mint + * would be accepted, regardless if the user has enough tokens approved, etc. + * - MUST be inclusive of deposit fees. Integrators should be aware of the existence of deposit fees. + * - MUST NOT revert. + * + * NOTE: any unfavorable discrepancy between convertToAssets and previewMint SHOULD be considered slippage in + * share price or some other type of condition, meaning the depositor will lose assets by minting. + */ + function previewMint(uint256 shares) external view returns (uint256 assets); + + /** + * @dev Mints exactly shares Vault shares to receiver by depositing amount of underlying tokens. + * + * - MUST emit the Deposit event. + * - MAY support an additional flow in which the underlying tokens are owned by the Vault contract before the mint + * execution, and are accounted for during mint. + * - MUST revert if all of shares cannot be minted (due to deposit limit being reached, slippage, the user not + * approving enough underlying tokens to the Vault contract, etc). + * + * NOTE: most implementations will require pre-approval of the Vault with the Vault’s underlying asset token. + */ + function mint(uint256 shares, address receiver) external returns (uint256 assets); + + /** + * @dev Returns the maximum amount of the underlying asset that can be withdrawn from the owner balance in the + * Vault, through a withdraw call. + * + * - MUST return a limited value if owner is subject to some withdrawal limit or timelock. + * - MUST NOT revert. + */ + function maxWithdraw(address owner) external view returns (uint256 maxAssets); + + /** + * @dev Allows an on-chain or off-chain user to simulate the effects of their withdrawal at the current block, + * given current on-chain conditions. + * + * - MUST return as close to and no fewer than the exact amount of Vault shares that would be burned in a withdraw + * call in the same transaction. I.e. withdraw should return the same or fewer shares as previewWithdraw if + * called + * in the same transaction. + * - MUST NOT account for withdrawal limits like those returned from maxWithdraw and should always act as though + * the withdrawal would be accepted, regardless if the user has enough shares, etc. + * - MUST be inclusive of withdrawal fees. Integrators should be aware of the existence of withdrawal fees. + * - MUST NOT revert. + * + * NOTE: any unfavorable discrepancy between convertToShares and previewWithdraw SHOULD be considered slippage in + * share price or some other type of condition, meaning the depositor will lose assets by depositing. + */ + function previewWithdraw(uint256 assets) external view returns (uint256 shares); + + /** + * @dev Burns shares from owner and sends exactly assets of underlying tokens to receiver. + * + * - MUST emit the Withdraw event. + * - MAY support an additional flow in which the underlying tokens are owned by the Vault contract before the + * withdraw execution, and are accounted for during withdraw. + * - MUST revert if all of assets cannot be withdrawn (due to withdrawal limit being reached, slippage, the owner + * not having enough shares, etc). + * + * Note that some implementations will require pre-requesting to the Vault before a withdrawal may be performed. + * Those methods should be performed separately. + */ + function withdraw(uint256 assets, address receiver, address owner) external returns (uint256 shares); + + /** + * @dev Returns the maximum amount of Vault shares that can be redeemed from the owner balance in the Vault, + * through a redeem call. + * + * - MUST return a limited value if owner is subject to some withdrawal limit or timelock. + * - MUST return balanceOf(owner) if owner is not subject to any withdrawal limit or timelock. + * - MUST NOT revert. + */ + function maxRedeem(address owner) external view returns (uint256 maxShares); + + /** + * @dev Allows an on-chain or off-chain user to simulate the effects of their redeemption at the current block, + * given current on-chain conditions. + * + * - MUST return as close to and no more than the exact amount of assets that would be withdrawn in a redeem call + * in the same transaction. I.e. redeem should return the same or more assets as previewRedeem if called in the + * same transaction. + * - MUST NOT account for redemption limits like those returned from maxRedeem and should always act as though the + * redemption would be accepted, regardless if the user has enough shares, etc. + * - MUST be inclusive of withdrawal fees. Integrators should be aware of the existence of withdrawal fees. + * - MUST NOT revert. + * + * NOTE: any unfavorable discrepancy between convertToAssets and previewRedeem SHOULD be considered slippage in + * share price or some other type of condition, meaning the depositor will lose assets by redeeming. + */ + function previewRedeem(uint256 shares) external view returns (uint256 assets); + + /** + * @dev Burns exactly shares from owner and sends assets of underlying tokens to receiver. + * + * - MUST emit the Withdraw event. + * - MAY support an additional flow in which the underlying tokens are owned by the Vault contract before the + * redeem execution, and are accounted for during redeem. + * - MUST revert if all of shares cannot be redeemed (due to withdrawal limit being reached, slippage, the owner + * not having enough shares, etc). + * + * NOTE: some implementations will require pre-requesting to the Vault before a withdrawal may be performed. + * Those methods should be performed separately. + */ + function redeem(uint256 shares, address receiver, address owner) external returns (uint256 assets); +} diff --git a/contracts/interfaces/IERC4906.sol b/contracts/interfaces/IERC4906.sol new file mode 100644 index 000000000..ba7fbd3a6 --- /dev/null +++ b/contracts/interfaces/IERC4906.sol @@ -0,0 +1,20 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (interfaces/IERC4906.sol) + +pragma solidity ^0.8.20; + +import {IERC165} from "./IERC165.sol"; +import {IERC721} from "./IERC721.sol"; + +/// @title EIP-721 Metadata Update Extension +interface IERC4906 is IERC165, IERC721 { + /// @dev This event emits when the metadata of a token is changed. + /// So that the third-party platforms such as NFT market could + /// timely update the images and related attributes of the NFT. + event MetadataUpdate(uint256 _tokenId); + + /// @dev This event emits when the metadata of a range of tokens is changed. + /// So that the third-party platforms such as NFT market could + /// timely update the images and related attributes of the NFTs. + event BatchMetadataUpdate(uint256 _fromTokenId, uint256 _toTokenId); +} diff --git a/contracts/interfaces/IERC5267.sol b/contracts/interfaces/IERC5267.sol new file mode 100644 index 000000000..6e0a9bc23 --- /dev/null +++ b/contracts/interfaces/IERC5267.sol @@ -0,0 +1,28 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (interfaces/IERC5267.sol) + +pragma solidity ^0.8.20; + +interface IERC5267 { + /** + * @dev MAY be emitted to signal that the domain could have changed. + */ + event EIP712DomainChanged(); + + /** + * @dev returns the fields and values that describe the domain separator used by this contract for EIP-712 + * signature. + */ + function eip712Domain() + external + view + returns ( + bytes1 fields, + string memory name, + string memory version, + uint256 chainId, + address verifyingContract, + bytes32 salt, + uint256[] memory extensions + ); +} diff --git a/contracts/interfaces/IERC5313.sol b/contracts/interfaces/IERC5313.sol new file mode 100644 index 000000000..61556dd08 --- /dev/null +++ b/contracts/interfaces/IERC5313.sol @@ -0,0 +1,16 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (interfaces/IERC5313.sol) + +pragma solidity ^0.8.20; + +/** + * @dev Interface for the Light Contract Ownership Standard. + * + * A standardized minimal interface required to identify an account that controls a contract + */ +interface IERC5313 { + /** + * @dev Gets the address of the owner. + */ + function owner() external view returns (address); +} diff --git a/contracts/interfaces/IERC5805.sol b/contracts/interfaces/IERC5805.sol new file mode 100644 index 000000000..1d7451d0a --- /dev/null +++ b/contracts/interfaces/IERC5805.sol @@ -0,0 +1,9 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (interfaces/IERC5805.sol) + +pragma solidity ^0.8.20; + +import {IVotes} from "../governance/utils/IVotes.sol"; +import {IERC6372} from "./IERC6372.sol"; + +interface IERC5805 is IERC6372, IVotes {} diff --git a/contracts/interfaces/IERC6372.sol b/contracts/interfaces/IERC6372.sol new file mode 100644 index 000000000..f4973ecb1 --- /dev/null +++ b/contracts/interfaces/IERC6372.sol @@ -0,0 +1,17 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (interfaces/IERC6372.sol) + +pragma solidity ^0.8.20; + +interface IERC6372 { + /** + * @dev Clock used for flagging checkpoints. Can be overridden to implement timestamp based checkpoints (and voting). + */ + function clock() external view returns (uint48); + + /** + * @dev Description of the clock + */ + // solhint-disable-next-line func-name-mixedcase + function CLOCK_MODE() external view returns (string memory); +} diff --git a/contracts/interfaces/IERC721.sol b/contracts/interfaces/IERC721.sol new file mode 100644 index 000000000..d671eca40 --- /dev/null +++ b/contracts/interfaces/IERC721.sol @@ -0,0 +1,6 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (interfaces/IERC721.sol) + +pragma solidity ^0.8.20; + +import {IERC721} from "../token/ERC721/IERC721.sol"; diff --git a/contracts/interfaces/IERC721Enumerable.sol b/contracts/interfaces/IERC721Enumerable.sol new file mode 100644 index 000000000..4134593f4 --- /dev/null +++ b/contracts/interfaces/IERC721Enumerable.sol @@ -0,0 +1,6 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (interfaces/IERC721Enumerable.sol) + +pragma solidity ^0.8.20; + +import {IERC721Enumerable} from "../token/ERC721/extensions/IERC721Enumerable.sol"; diff --git a/contracts/interfaces/IERC721Metadata.sol b/contracts/interfaces/IERC721Metadata.sol new file mode 100644 index 000000000..6d8452e8e --- /dev/null +++ b/contracts/interfaces/IERC721Metadata.sol @@ -0,0 +1,6 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (interfaces/IERC721Metadata.sol) + +pragma solidity ^0.8.20; + +import {IERC721Metadata} from "../token/ERC721/extensions/IERC721Metadata.sol"; diff --git a/contracts/interfaces/IERC721Receiver.sol b/contracts/interfaces/IERC721Receiver.sol new file mode 100644 index 000000000..950e0a410 --- /dev/null +++ b/contracts/interfaces/IERC721Receiver.sol @@ -0,0 +1,6 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (interfaces/IERC721Receiver.sol) + +pragma solidity ^0.8.20; + +import {IERC721Receiver} from "../token/ERC721/IERC721Receiver.sol"; diff --git a/contracts/interfaces/IERC777.sol b/contracts/interfaces/IERC777.sol new file mode 100644 index 000000000..a432ca69a --- /dev/null +++ b/contracts/interfaces/IERC777.sol @@ -0,0 +1,200 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (interfaces/IERC777.sol) + +pragma solidity ^0.8.20; + +/** + * @dev Interface of the ERC777Token standard as defined in the EIP. + * + * This contract uses the + * https://eips.ethereum.org/EIPS/eip-1820[ERC1820 registry standard] to let + * token holders and recipients react to token movements by using setting implementers + * for the associated interfaces in said registry. See {IERC1820Registry} and + * {IERC1820Implementer}. + */ +interface IERC777 { + /** + * @dev Emitted when `amount` tokens are created by `operator` and assigned to `to`. + * + * Note that some additional user `data` and `operatorData` can be logged in the event. + */ + event Minted(address indexed operator, address indexed to, uint256 amount, bytes data, bytes operatorData); + + /** + * @dev Emitted when `operator` destroys `amount` tokens from `account`. + * + * Note that some additional user `data` and `operatorData` can be logged in the event. + */ + event Burned(address indexed operator, address indexed from, uint256 amount, bytes data, bytes operatorData); + + /** + * @dev Emitted when `operator` is made operator for `tokenHolder`. + */ + event AuthorizedOperator(address indexed operator, address indexed tokenHolder); + + /** + * @dev Emitted when `operator` is revoked its operator status for `tokenHolder`. + */ + event RevokedOperator(address indexed operator, address indexed tokenHolder); + + /** + * @dev Returns the name of the token. + */ + function name() external view returns (string memory); + + /** + * @dev Returns the symbol of the token, usually a shorter version of the + * name. + */ + function symbol() external view returns (string memory); + + /** + * @dev Returns the smallest part of the token that is not divisible. This + * means all token operations (creation, movement and destruction) must have + * amounts that are a multiple of this number. + * + * For most token contracts, this value will equal 1. + */ + function granularity() external view returns (uint256); + + /** + * @dev Returns the amount of tokens in existence. + */ + function totalSupply() external view returns (uint256); + + /** + * @dev Returns the amount of tokens owned by an account (`owner`). + */ + function balanceOf(address owner) external view returns (uint256); + + /** + * @dev Moves `amount` tokens from the caller's account to `recipient`. + * + * If send or receive hooks are registered for the caller and `recipient`, + * the corresponding functions will be called with `data` and empty + * `operatorData`. See {IERC777Sender} and {IERC777Recipient}. + * + * Emits a {Sent} event. + * + * Requirements + * + * - the caller must have at least `amount` tokens. + * - `recipient` cannot be the zero address. + * - if `recipient` is a contract, it must implement the {IERC777Recipient} + * interface. + */ + function send(address recipient, uint256 amount, bytes calldata data) external; + + /** + * @dev Destroys `amount` tokens from the caller's account, reducing the + * total supply. + * + * If a send hook is registered for the caller, the corresponding function + * will be called with `data` and empty `operatorData`. See {IERC777Sender}. + * + * Emits a {Burned} event. + * + * Requirements + * + * - the caller must have at least `amount` tokens. + */ + function burn(uint256 amount, bytes calldata data) external; + + /** + * @dev Returns true if an account is an operator of `tokenHolder`. + * Operators can send and burn tokens on behalf of their owners. All + * accounts are their own operator. + * + * See {operatorSend} and {operatorBurn}. + */ + function isOperatorFor(address operator, address tokenHolder) external view returns (bool); + + /** + * @dev Make an account an operator of the caller. + * + * See {isOperatorFor}. + * + * Emits an {AuthorizedOperator} event. + * + * Requirements + * + * - `operator` cannot be calling address. + */ + function authorizeOperator(address operator) external; + + /** + * @dev Revoke an account's operator status for the caller. + * + * See {isOperatorFor} and {defaultOperators}. + * + * Emits a {RevokedOperator} event. + * + * Requirements + * + * - `operator` cannot be calling address. + */ + function revokeOperator(address operator) external; + + /** + * @dev Returns the list of default operators. These accounts are operators + * for all token holders, even if {authorizeOperator} was never called on + * them. + * + * This list is immutable, but individual holders may revoke these via + * {revokeOperator}, in which case {isOperatorFor} will return false. + */ + function defaultOperators() external view returns (address[] memory); + + /** + * @dev Moves `amount` tokens from `sender` to `recipient`. The caller must + * be an operator of `sender`. + * + * If send or receive hooks are registered for `sender` and `recipient`, + * the corresponding functions will be called with `data` and + * `operatorData`. See {IERC777Sender} and {IERC777Recipient}. + * + * Emits a {Sent} event. + * + * Requirements + * + * - `sender` cannot be the zero address. + * - `sender` must have at least `amount` tokens. + * - the caller must be an operator for `sender`. + * - `recipient` cannot be the zero address. + * - if `recipient` is a contract, it must implement the {IERC777Recipient} + * interface. + */ + function operatorSend( + address sender, + address recipient, + uint256 amount, + bytes calldata data, + bytes calldata operatorData + ) external; + + /** + * @dev Destroys `amount` tokens from `account`, reducing the total supply. + * The caller must be an operator of `account`. + * + * If a send hook is registered for `account`, the corresponding function + * will be called with `data` and `operatorData`. See {IERC777Sender}. + * + * Emits a {Burned} event. + * + * Requirements + * + * - `account` cannot be the zero address. + * - `account` must have at least `amount` tokens. + * - the caller must be an operator for `account`. + */ + function operatorBurn(address account, uint256 amount, bytes calldata data, bytes calldata operatorData) external; + + event Sent( + address indexed operator, + address indexed from, + address indexed to, + uint256 amount, + bytes data, + bytes operatorData + ); +} diff --git a/contracts/interfaces/IERC777Recipient.sol b/contracts/interfaces/IERC777Recipient.sol new file mode 100644 index 000000000..2a937f5cd --- /dev/null +++ b/contracts/interfaces/IERC777Recipient.sol @@ -0,0 +1,35 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (interfaces/IERC777Recipient.sol) + +pragma solidity ^0.8.20; + +/** + * @dev Interface of the ERC777TokensRecipient standard as defined in the EIP. + * + * Accounts can be notified of {IERC777} tokens being sent to them by having a + * contract implement this interface (contract holders can be their own + * implementer) and registering it on the + * https://eips.ethereum.org/EIPS/eip-1820[ERC1820 global registry]. + * + * See {IERC1820Registry} and {IERC1820Implementer}. + */ +interface IERC777Recipient { + /** + * @dev Called by an {IERC777} token contract whenever tokens are being + * moved or created into a registered account (`to`). The type of operation + * is conveyed by `from` being the zero address or not. + * + * This call occurs _after_ the token contract's state is updated, so + * {IERC777-balanceOf}, etc., can be used to query the post-operation state. + * + * This function may revert to prevent the operation from being executed. + */ + function tokensReceived( + address operator, + address from, + address to, + uint256 amount, + bytes calldata userData, + bytes calldata operatorData + ) external; +} diff --git a/contracts/interfaces/IERC777Sender.sol b/contracts/interfaces/IERC777Sender.sol new file mode 100644 index 000000000..5c10973f5 --- /dev/null +++ b/contracts/interfaces/IERC777Sender.sol @@ -0,0 +1,35 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (interfaces/IERC777Sender.sol) + +pragma solidity ^0.8.20; + +/** + * @dev Interface of the ERC777TokensSender standard as defined in the EIP. + * + * {IERC777} Token holders can be notified of operations performed on their + * tokens by having a contract implement this interface (contract holders can be + * their own implementer) and registering it on the + * https://eips.ethereum.org/EIPS/eip-1820[ERC1820 global registry]. + * + * See {IERC1820Registry} and {IERC1820Implementer}. + */ +interface IERC777Sender { + /** + * @dev Called by an {IERC777} token contract whenever a registered holder's + * (`from`) tokens are about to be moved or destroyed. The type of operation + * is conveyed by `to` being the zero address or not. + * + * This call occurs _before_ the token contract's state is updated, so + * {IERC777-balanceOf}, etc., can be used to query the pre-operation state. + * + * This function may revert to prevent the operation from being executed. + */ + function tokensToSend( + address operator, + address from, + address to, + uint256 amount, + bytes calldata userData, + bytes calldata operatorData + ) external; +} diff --git a/contracts/interfaces/README.adoc b/contracts/interfaces/README.adoc new file mode 100644 index 000000000..379a24a1e --- /dev/null +++ b/contracts/interfaces/README.adoc @@ -0,0 +1,82 @@ += Interfaces + +[.readme-notice] +NOTE: This document is better viewed at https://docs.openzeppelin.com/contracts/api/interfaces + +== List of standardized interfaces +These interfaces are available as `.sol` files, and also as compiler `.json` ABI files (through the npm package). These +are useful to interact with third party contracts that implement them. + +- {IERC20} +- {IERC20Errors} +- {IERC20Metadata} +- {IERC165} +- {IERC721} +- {IERC721Receiver} +- {IERC721Enumerable} +- {IERC721Metadata} +- {IERC721Errors} +- {IERC777} +- {IERC777Recipient} +- {IERC777Sender} +- {IERC1155} +- {IERC1155Receiver} +- {IERC1155MetadataURI} +- {IERC1155Errors} +- {IERC1271} +- {IERC1363} +- {IERC1363Receiver} +- {IERC1363Spender} +- {IERC1820Implementer} +- {IERC1820Registry} +- {IERC1822Proxiable} +- {IERC2612} +- {IERC2981} +- {IERC3156FlashLender} +- {IERC3156FlashBorrower} +- {IERC4626} +- {IERC4906} +- {IERC5267} +- {IERC5313} +- {IERC5805} +- {IERC6372} + +== Detailed ABI + +{{IERC20Errors}} + +{{IERC721Errors}} + +{{IERC1155Errors}} + +{{IERC1271}} + +{{IERC1363}} + +{{IERC1363Receiver}} + +{{IERC1363Spender}} + +{{IERC1820Implementer}} + +{{IERC1820Registry}} + +{{IERC1822Proxiable}} + +{{IERC2612}} + +{{IERC2981}} + +{{IERC3156FlashLender}} + +{{IERC3156FlashBorrower}} + +{{IERC4626}} + +{{IERC5313}} + +{{IERC5267}} + +{{IERC5805}} + +{{IERC6372}} diff --git a/contracts/interfaces/draft-IERC1822.sol b/contracts/interfaces/draft-IERC1822.sol new file mode 100644 index 000000000..c3679a6e6 --- /dev/null +++ b/contracts/interfaces/draft-IERC1822.sol @@ -0,0 +1,20 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (interfaces/draft-IERC1822.sol) + +pragma solidity ^0.8.20; + +/** + * @dev ERC1822: Universal Upgradeable Proxy Standard (UUPS) documents a method for upgradeability through a simplified + * proxy whose upgrades are fully controlled by the current implementation. + */ +interface IERC1822Proxiable { + /** + * @dev Returns the storage slot that the proxiable contract assumes is being used to store the implementation + * address. + * + * IMPORTANT: A proxy pointing at a proxiable contract should not be considered proxiable itself, because this risks + * bricking a proxy that upgrades to it, by delegating to itself until out of gas. Thus it is critical that this + * function revert if invoked through a proxy. + */ + function proxiableUUID() external view returns (bytes32); +} diff --git a/contracts/interfaces/draft-IERC6093.sol b/contracts/interfaces/draft-IERC6093.sol new file mode 100644 index 000000000..c6bcfff58 --- /dev/null +++ b/contracts/interfaces/draft-IERC6093.sol @@ -0,0 +1,161 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (interfaces/draft-IERC6093.sol) +pragma solidity ^0.8.20; + +/** + * @dev Standard ERC20 Errors + * Interface of the https://eips.ethereum.org/EIPS/eip-6093[ERC-6093] custom errors for ERC20 tokens. + */ +interface IERC20Errors { + /** + * @dev Indicates an error related to the current `balance` of a `sender`. Used in transfers. + * @param sender Address whose tokens are being transferred. + * @param balance Current balance for the interacting account. + * @param needed Minimum amount required to perform a transfer. + */ + error ERC20InsufficientBalance(address sender, uint256 balance, uint256 needed); + + /** + * @dev Indicates a failure with the token `sender`. Used in transfers. + * @param sender Address whose tokens are being transferred. + */ + error ERC20InvalidSender(address sender); + + /** + * @dev Indicates a failure with the token `receiver`. Used in transfers. + * @param receiver Address to which tokens are being transferred. + */ + error ERC20InvalidReceiver(address receiver); + + /** + * @dev Indicates a failure with the `spender`’s `allowance`. Used in transfers. + * @param spender Address that may be allowed to operate on tokens without being their owner. + * @param allowance Amount of tokens a `spender` is allowed to operate with. + * @param needed Minimum amount required to perform a transfer. + */ + error ERC20InsufficientAllowance(address spender, uint256 allowance, uint256 needed); + + /** + * @dev Indicates a failure with the `approver` of a token to be approved. Used in approvals. + * @param approver Address initiating an approval operation. + */ + error ERC20InvalidApprover(address approver); + + /** + * @dev Indicates a failure with the `spender` to be approved. Used in approvals. + * @param spender Address that may be allowed to operate on tokens without being their owner. + */ + error ERC20InvalidSpender(address spender); +} + +/** + * @dev Standard ERC721 Errors + * Interface of the https://eips.ethereum.org/EIPS/eip-6093[ERC-6093] custom errors for ERC721 tokens. + */ +interface IERC721Errors { + /** + * @dev Indicates that an address can't be an owner. For example, `address(0)` is a forbidden owner in EIP-20. + * Used in balance queries. + * @param owner Address of the current owner of a token. + */ + error ERC721InvalidOwner(address owner); + + /** + * @dev Indicates a `tokenId` whose `owner` is the zero address. + * @param tokenId Identifier number of a token. + */ + error ERC721NonexistentToken(uint256 tokenId); + + /** + * @dev Indicates an error related to the ownership over a particular token. Used in transfers. + * @param sender Address whose tokens are being transferred. + * @param tokenId Identifier number of a token. + * @param owner Address of the current owner of a token. + */ + error ERC721IncorrectOwner(address sender, uint256 tokenId, address owner); + + /** + * @dev Indicates a failure with the token `sender`. Used in transfers. + * @param sender Address whose tokens are being transferred. + */ + error ERC721InvalidSender(address sender); + + /** + * @dev Indicates a failure with the token `receiver`. Used in transfers. + * @param receiver Address to which tokens are being transferred. + */ + error ERC721InvalidReceiver(address receiver); + + /** + * @dev Indicates a failure with the `operator`’s approval. Used in transfers. + * @param operator Address that may be allowed to operate on tokens without being their owner. + * @param tokenId Identifier number of a token. + */ + error ERC721InsufficientApproval(address operator, uint256 tokenId); + + /** + * @dev Indicates a failure with the `approver` of a token to be approved. Used in approvals. + * @param approver Address initiating an approval operation. + */ + error ERC721InvalidApprover(address approver); + + /** + * @dev Indicates a failure with the `operator` to be approved. Used in approvals. + * @param operator Address that may be allowed to operate on tokens without being their owner. + */ + error ERC721InvalidOperator(address operator); +} + +/** + * @dev Standard ERC1155 Errors + * Interface of the https://eips.ethereum.org/EIPS/eip-6093[ERC-6093] custom errors for ERC1155 tokens. + */ +interface IERC1155Errors { + /** + * @dev Indicates an error related to the current `balance` of a `sender`. Used in transfers. + * @param sender Address whose tokens are being transferred. + * @param balance Current balance for the interacting account. + * @param needed Minimum amount required to perform a transfer. + * @param tokenId Identifier number of a token. + */ + error ERC1155InsufficientBalance(address sender, uint256 balance, uint256 needed, uint256 tokenId); + + /** + * @dev Indicates a failure with the token `sender`. Used in transfers. + * @param sender Address whose tokens are being transferred. + */ + error ERC1155InvalidSender(address sender); + + /** + * @dev Indicates a failure with the token `receiver`. Used in transfers. + * @param receiver Address to which tokens are being transferred. + */ + error ERC1155InvalidReceiver(address receiver); + + /** + * @dev Indicates a failure with the `operator`’s approval. Used in transfers. + * @param operator Address that may be allowed to operate on tokens without being their owner. + * @param owner Address of the current owner of a token. + */ + error ERC1155MissingApprovalForAll(address operator, address owner); + + /** + * @dev Indicates a failure with the `approver` of a token to be approved. Used in approvals. + * @param approver Address initiating an approval operation. + */ + error ERC1155InvalidApprover(address approver); + + /** + * @dev Indicates a failure with the `operator` to be approved. Used in approvals. + * @param operator Address that may be allowed to operate on tokens without being their owner. + */ + error ERC1155InvalidOperator(address operator); + + /** + * @dev Indicates an array length mismatch between ids and values in a safeBatchTransferFrom operation. + * Used in batch transfers. + * @param idsLength Length of the array of token identifiers + * @param valuesLength Length of the array of token amounts + */ + error ERC1155InvalidArrayLength(uint256 idsLength, uint256 valuesLength); +} diff --git a/contracts/metatx/ERC2771Context.sol b/contracts/metatx/ERC2771Context.sol new file mode 100644 index 000000000..5b5954e6a --- /dev/null +++ b/contracts/metatx/ERC2771Context.sol @@ -0,0 +1,75 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (metatx/ERC2771Context.sol) + +pragma solidity ^0.8.20; + +import {Context} from "../utils/Context.sol"; + +/** + * @dev Context variant with ERC2771 support. + * + * WARNING: Avoid using this pattern in contracts that rely in a specific calldata length as they'll + * be affected by any forwarder whose `msg.data` is suffixed with the `from` address according to the ERC2771 + * specification adding the address size in bytes (20) to the calldata size. An example of an unexpected + * behavior could be an unintended fallback (or another function) invocation while trying to invoke the `receive` + * function only accessible if `msg.data.length == 0`. + */ +abstract contract ERC2771Context is Context { + /// @custom:oz-upgrades-unsafe-allow state-variable-immutable + address private immutable _trustedForwarder; + + /** + * @dev Initializes the contract with a trusted forwarder, which will be able to + * invoke functions on this contract on behalf of other accounts. + * + * NOTE: The trusted forwarder can be replaced by overriding {trustedForwarder}. + */ + /// @custom:oz-upgrades-unsafe-allow constructor + constructor(address trustedForwarder_) { + _trustedForwarder = trustedForwarder_; + } + + /** + * @dev Returns the address of the trusted forwarder. + */ + function trustedForwarder() public view virtual returns (address) { + return _trustedForwarder; + } + + /** + * @dev Indicates whether any particular address is the trusted forwarder. + */ + function isTrustedForwarder(address forwarder) public view virtual returns (bool) { + return forwarder == trustedForwarder(); + } + + /** + * @dev Override for `msg.sender`. Defaults to the original `msg.sender` whenever + * a call is not performed by the trusted forwarder or the calldata length is less than + * 20 bytes (an address length). + */ + function _msgSender() internal view virtual override returns (address sender) { + if (isTrustedForwarder(msg.sender) && msg.data.length >= 20) { + // The assembly code is more direct than the Solidity version using `abi.decode`. + /// @solidity memory-safe-assembly + assembly { + sender := shr(96, calldataload(sub(calldatasize(), 20))) + } + } else { + return super._msgSender(); + } + } + + /** + * @dev Override for `msg.data`. Defaults to the original `msg.data` whenever + * a call is not performed by the trusted forwarder or the calldata length is less than + * 20 bytes (an address length). + */ + function _msgData() internal view virtual override returns (bytes calldata) { + if (isTrustedForwarder(msg.sender) && msg.data.length >= 20) { + return msg.data[:msg.data.length - 20]; + } else { + return super._msgData(); + } + } +} diff --git a/contracts/metatx/ERC2771Forwarder.sol b/contracts/metatx/ERC2771Forwarder.sol new file mode 100644 index 000000000..52984057f --- /dev/null +++ b/contracts/metatx/ERC2771Forwarder.sol @@ -0,0 +1,370 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (metatx/ERC2771Forwarder.sol) + +pragma solidity ^0.8.20; + +import {ERC2771Context} from "./ERC2771Context.sol"; +import {ECDSA} from "../utils/cryptography/ECDSA.sol"; +import {EIP712} from "../utils/cryptography/EIP712.sol"; +import {Nonces} from "../utils/Nonces.sol"; +import {Address} from "../utils/Address.sol"; + +/** + * @dev A forwarder compatible with ERC2771 contracts. See {ERC2771Context}. + * + * This forwarder operates on forward requests that include: + * + * * `from`: An address to operate on behalf of. It is required to be equal to the request signer. + * * `to`: The address that should be called. + * * `value`: The amount of native token to attach with the requested call. + * * `gas`: The amount of gas limit that will be forwarded with the requested call. + * * `nonce`: A unique transaction ordering identifier to avoid replayability and request invalidation. + * * `deadline`: A timestamp after which the request is not executable anymore. + * * `data`: Encoded `msg.data` to send with the requested call. + * + * Relayers are able to submit batches if they are processing a high volume of requests. With high + * throughput, relayers may run into limitations of the chain such as limits on the number of + * transactions in the mempool. In these cases the recommendation is to distribute the load among + * multiple accounts. + * + * NOTE: Batching requests includes an optional refund for unused `msg.value` that is achieved by + * performing a call with empty calldata. While this is within the bounds of ERC-2771 compliance, + * if the refund receiver happens to consider the forwarder a trusted forwarder, it MUST properly + * handle `msg.data.length == 0`. `ERC2771Context` in OpenZeppelin Contracts versions prior to 4.9.3 + * do not handle this properly. + * + * ==== Security Considerations + * + * If a relayer submits a forward request, it should be willing to pay up to 100% of the gas amount + * specified in the request. This contract does not implement any kind of retribution for this gas, + * and it is assumed that there is an out of band incentive for relayers to pay for execution on + * behalf of signers. Often, the relayer is operated by a project that will consider it a user + * acquisition cost. + * + * By offering to pay for gas, relayers are at risk of having that gas used by an attacker toward + * some other purpose that is not aligned with the expected out of band incentives. If you operate a + * relayer, consider whitelisting target contracts and function selectors. When relaying ERC-721 or + * ERC-1155 transfers specifically, consider rejecting the use of the `data` field, since it can be + * used to execute arbitrary code. + */ +contract ERC2771Forwarder is EIP712, Nonces { + using ECDSA for bytes32; + + struct ForwardRequestData { + address from; + address to; + uint256 value; + uint256 gas; + uint48 deadline; + bytes data; + bytes signature; + } + + bytes32 internal constant _FORWARD_REQUEST_TYPEHASH = + keccak256( + "ForwardRequest(address from,address to,uint256 value,uint256 gas,uint256 nonce,uint48 deadline,bytes data)" + ); + + /** + * @dev Emitted when a `ForwardRequest` is executed. + * + * NOTE: An unsuccessful forward request could be due to an invalid signature, an expired deadline, + * or simply a revert in the requested call. The contract guarantees that the relayer is not able to force + * the requested call to run out of gas. + */ + event ExecutedForwardRequest(address indexed signer, uint256 nonce, bool success); + + /** + * @dev The request `from` doesn't match with the recovered `signer`. + */ + error ERC2771ForwarderInvalidSigner(address signer, address from); + + /** + * @dev The `requestedValue` doesn't match with the available `msgValue`. + */ + error ERC2771ForwarderMismatchedValue(uint256 requestedValue, uint256 msgValue); + + /** + * @dev The request `deadline` has expired. + */ + error ERC2771ForwarderExpiredRequest(uint48 deadline); + + /** + * @dev The request target doesn't trust the `forwarder`. + */ + error ERC2771UntrustfulTarget(address target, address forwarder); + + /** + * @dev See {EIP712-constructor}. + */ + constructor(string memory name) EIP712(name, "1") {} + + /** + * @dev Returns `true` if a request is valid for a provided `signature` at the current block timestamp. + * + * A transaction is considered valid when the target trusts this forwarder, the request hasn't expired + * (deadline is not met), and the signer matches the `from` parameter of the signed request. + * + * NOTE: A request may return false here but it won't cause {executeBatch} to revert if a refund + * receiver is provided. + */ + function verify(ForwardRequestData calldata request) public view virtual returns (bool) { + (bool isTrustedForwarder, bool active, bool signerMatch, ) = _validate(request); + return isTrustedForwarder && active && signerMatch; + } + + /** + * @dev Executes a `request` on behalf of `signature`'s signer using the ERC-2771 protocol. The gas + * provided to the requested call may not be exactly the amount requested, but the call will not run + * out of gas. Will revert if the request is invalid or the call reverts, in this case the nonce is not consumed. + * + * Requirements: + * + * - The request value should be equal to the provided `msg.value`. + * - The request should be valid according to {verify}. + */ + function execute(ForwardRequestData calldata request) public payable virtual { + // We make sure that msg.value and request.value match exactly. + // If the request is invalid or the call reverts, this whole function + // will revert, ensuring value isn't stuck. + if (msg.value != request.value) { + revert ERC2771ForwarderMismatchedValue(request.value, msg.value); + } + + if (!_execute(request, true)) { + revert Address.FailedInnerCall(); + } + } + + /** + * @dev Batch version of {execute} with optional refunding and atomic execution. + * + * In case a batch contains at least one invalid request (see {verify}), the + * request will be skipped and the `refundReceiver` parameter will receive back the + * unused requested value at the end of the execution. This is done to prevent reverting + * the entire batch when a request is invalid or has already been submitted. + * + * If the `refundReceiver` is the `address(0)`, this function will revert when at least + * one of the requests was not valid instead of skipping it. This could be useful if + * a batch is required to get executed atomically (at least at the top-level). For example, + * refunding (and thus atomicity) can be opt-out if the relayer is using a service that avoids + * including reverted transactions. + * + * Requirements: + * + * - The sum of the requests' values should be equal to the provided `msg.value`. + * - All of the requests should be valid (see {verify}) when `refundReceiver` is the zero address. + * + * NOTE: Setting a zero `refundReceiver` guarantees an all-or-nothing requests execution only for + * the first-level forwarded calls. In case a forwarded request calls to a contract with another + * subcall, the second-level call may revert without the top-level call reverting. + */ + function executeBatch( + ForwardRequestData[] calldata requests, + address payable refundReceiver + ) public payable virtual { + bool atomic = refundReceiver == address(0); + + uint256 requestsValue; + uint256 refundValue; + + for (uint256 i; i < requests.length; ++i) { + requestsValue += requests[i].value; + bool success = _execute(requests[i], atomic); + if (!success) { + refundValue += requests[i].value; + } + } + + // The batch should revert if there's a mismatched msg.value provided + // to avoid request value tampering + if (requestsValue != msg.value) { + revert ERC2771ForwarderMismatchedValue(requestsValue, msg.value); + } + + // Some requests with value were invalid (possibly due to frontrunning). + // To avoid leaving ETH in the contract this value is refunded. + if (refundValue != 0) { + // We know refundReceiver != address(0) && requestsValue == msg.value + // meaning we can ensure refundValue is not taken from the original contract's balance + // and refundReceiver is a known account. + Address.sendValue(refundReceiver, refundValue); + } + } + + /** + * @dev Validates if the provided request can be executed at current block timestamp with + * the given `request.signature` on behalf of `request.signer`. + */ + function _validate( + ForwardRequestData calldata request + ) internal view virtual returns (bool isTrustedForwarder, bool active, bool signerMatch, address signer) { + (bool isValid, address recovered) = _recoverForwardRequestSigner(request); + + return ( + _isTrustedByTarget(request.to), + request.deadline >= block.timestamp, + isValid && recovered == request.from, + recovered + ); + } + + /** + * @dev Returns a tuple with the recovered the signer of an EIP712 forward request message hash + * and a boolean indicating if the signature is valid. + * + * NOTE: The signature is considered valid if {ECDSA-tryRecover} indicates no recover error for it. + */ + function _recoverForwardRequestSigner( + ForwardRequestData calldata request + ) internal view virtual returns (bool, address) { + (address recovered, ECDSA.RecoverError err, ) = _hashTypedDataV4( + keccak256( + abi.encode( + _FORWARD_REQUEST_TYPEHASH, + request.from, + request.to, + request.value, + request.gas, + nonces(request.from), + request.deadline, + keccak256(request.data) + ) + ) + ).tryRecover(request.signature); + + return (err == ECDSA.RecoverError.NoError, recovered); + } + + /** + * @dev Validates and executes a signed request returning the request call `success` value. + * + * Internal function without msg.value validation. + * + * Requirements: + * + * - The caller must have provided enough gas to forward with the call. + * - The request must be valid (see {verify}) if the `requireValidRequest` is true. + * + * Emits an {ExecutedForwardRequest} event. + * + * IMPORTANT: Using this function doesn't check that all the `msg.value` was sent, potentially + * leaving value stuck in the contract. + */ + function _execute( + ForwardRequestData calldata request, + bool requireValidRequest + ) internal virtual returns (bool success) { + (bool isTrustedForwarder, bool active, bool signerMatch, address signer) = _validate(request); + + // Need to explicitly specify if a revert is required since non-reverting is default for + // batches and reversion is opt-in since it could be useful in some scenarios + if (requireValidRequest) { + if (!isTrustedForwarder) { + revert ERC2771UntrustfulTarget(request.to, address(this)); + } + + if (!active) { + revert ERC2771ForwarderExpiredRequest(request.deadline); + } + + if (!signerMatch) { + revert ERC2771ForwarderInvalidSigner(signer, request.from); + } + } + + // Ignore an invalid request because requireValidRequest = false + if (isTrustedForwarder && signerMatch && active) { + // Nonce should be used before the call to prevent reusing by reentrancy + uint256 currentNonce = _useNonce(signer); + + uint256 reqGas = request.gas; + address to = request.to; + uint256 value = request.value; + bytes memory data = abi.encodePacked(request.data, request.from); + + uint256 gasLeft; + + assembly { + success := call(reqGas, to, value, add(data, 0x20), mload(data), 0, 0) + gasLeft := gas() + } + + _checkForwardedGas(gasLeft, request); + + emit ExecutedForwardRequest(signer, currentNonce, success); + } + } + + /** + * @dev Returns whether the target trusts this forwarder. + * + * This function performs a static call to the target contract calling the + * {ERC2771Context-isTrustedForwarder} function. + */ + function _isTrustedByTarget(address target) private view returns (bool) { + bytes memory encodedParams = abi.encodeCall(ERC2771Context.isTrustedForwarder, (address(this))); + + bool success; + uint256 returnSize; + uint256 returnValue; + /// @solidity memory-safe-assembly + assembly { + // Perform the staticcal and save the result in the scratch space. + // | Location | Content | Content (Hex) | + // |-----------|----------|--------------------------------------------------------------------| + // | | | result ↓ | + // | 0x00:0x1F | selector | 0x0000000000000000000000000000000000000000000000000000000000000001 | + success := staticcall(gas(), target, add(encodedParams, 0x20), mload(encodedParams), 0, 0x20) + returnSize := returndatasize() + returnValue := mload(0) + } + + return success && returnSize >= 0x20 && returnValue > 0; + } + + /** + * @dev Checks if the requested gas was correctly forwarded to the callee. + * + * As a consequence of https://eips.ethereum.org/EIPS/eip-150[EIP-150]: + * - At most `gasleft() - floor(gasleft() / 64)` is forwarded to the callee. + * - At least `floor(gasleft() / 64)` is kept in the caller. + * + * It reverts consuming all the available gas if the forwarded gas is not the requested gas. + * + * IMPORTANT: The `gasLeft` parameter should be measured exactly at the end of the forwarded call. + * Any gas consumed in between will make room for bypassing this check. + */ + function _checkForwardedGas(uint256 gasLeft, ForwardRequestData calldata request) private pure { + // To avoid insufficient gas griefing attacks, as referenced in https://ronan.eth.limo/blog/ethereum-gas-dangers/ + // + // A malicious relayer can attempt to shrink the gas forwarded so that the underlying call reverts out-of-gas + // but the forwarding itself still succeeds. In order to make sure that the subcall received sufficient gas, + // we will inspect gasleft() after the forwarding. + // + // Let X be the gas available before the subcall, such that the subcall gets at most X * 63 / 64. + // We can't know X after CALL dynamic costs, but we want it to be such that X * 63 / 64 >= req.gas. + // Let Y be the gas used in the subcall. gasleft() measured immediately after the subcall will be gasleft() = X - Y. + // If the subcall ran out of gas, then Y = X * 63 / 64 and gasleft() = X - Y = X / 64. + // Under this assumption req.gas / 63 > gasleft() is true is true if and only if + // req.gas / 63 > X / 64, or equivalently req.gas > X * 63 / 64. + // This means that if the subcall runs out of gas we are able to detect that insufficient gas was passed. + // + // We will now also see that req.gas / 63 > gasleft() implies that req.gas >= X * 63 / 64. + // The contract guarantees Y <= req.gas, thus gasleft() = X - Y >= X - req.gas. + // - req.gas / 63 > gasleft() + // - req.gas / 63 >= X - req.gas + // - req.gas >= X * 63 / 64 + // In other words if req.gas < X * 63 / 64 then req.gas / 63 <= gasleft(), thus if the relayer behaves honestly + // the forwarding does not revert. + if (gasLeft < request.gas / 63) { + // We explicitly trigger invalid opcode to consume all gas and bubble-up the effects, since + // neither revert or assert consume all gas since Solidity 0.8.20 + // https://docs.soliditylang.org/en/v0.8.20/control-structures.html#panic-via-assert-and-error-via-require + /// @solidity memory-safe-assembly + assembly { + invalid() + } + } + } +} diff --git a/contracts/metatx/README.adoc b/contracts/metatx/README.adoc new file mode 100644 index 000000000..9f25802e4 --- /dev/null +++ b/contracts/metatx/README.adoc @@ -0,0 +1,12 @@ += Meta Transactions + +[.readme-notice] +NOTE: This document is better viewed at https://docs.openzeppelin.com/contracts/api/metatx + +== Core + +{{ERC2771Context}} + +== Utils + +{{ERC2771Forwarder}} diff --git a/contracts/mocks/AccessManagedTarget.sol b/contracts/mocks/AccessManagedTarget.sol new file mode 100644 index 000000000..305c989f6 --- /dev/null +++ b/contracts/mocks/AccessManagedTarget.sol @@ -0,0 +1,18 @@ +// SPDX-License-Identifier: MIT + +pragma solidity ^0.8.20; + +import {AccessManaged} from "../access/manager/AccessManaged.sol"; + +abstract contract AccessManagedTarget is AccessManaged { + event CalledRestricted(address caller); + event CalledUnrestricted(address caller); + + function fnRestricted() public restricted { + emit CalledRestricted(msg.sender); + } + + function fnUnrestricted() public { + emit CalledUnrestricted(msg.sender); + } +} diff --git a/contracts/mocks/ArraysMock.sol b/contracts/mocks/ArraysMock.sol new file mode 100644 index 000000000..a00def29c --- /dev/null +++ b/contracts/mocks/ArraysMock.sol @@ -0,0 +1,51 @@ +// SPDX-License-Identifier: MIT + +pragma solidity ^0.8.20; + +import {Arrays} from "../utils/Arrays.sol"; + +contract Uint256ArraysMock { + using Arrays for uint256[]; + + uint256[] private _array; + + constructor(uint256[] memory array) { + _array = array; + } + + function findUpperBound(uint256 element) external view returns (uint256) { + return _array.findUpperBound(element); + } + + function unsafeAccess(uint256 pos) external view returns (uint256) { + return _array.unsafeAccess(pos).value; + } +} + +contract AddressArraysMock { + using Arrays for address[]; + + address[] private _array; + + constructor(address[] memory array) { + _array = array; + } + + function unsafeAccess(uint256 pos) external view returns (address) { + return _array.unsafeAccess(pos).value; + } +} + +contract Bytes32ArraysMock { + using Arrays for bytes32[]; + + bytes32[] private _array; + + constructor(bytes32[] memory array) { + _array = array; + } + + function unsafeAccess(uint256 pos) external view returns (bytes32) { + return _array.unsafeAccess(pos).value; + } +} diff --git a/contracts/mocks/CallReceiverMock.sol b/contracts/mocks/CallReceiverMock.sol new file mode 100644 index 000000000..e371c7db8 --- /dev/null +++ b/contracts/mocks/CallReceiverMock.sol @@ -0,0 +1,73 @@ +// SPDX-License-Identifier: MIT + +pragma solidity ^0.8.20; + +contract CallReceiverMock { + event MockFunctionCalled(); + event MockFunctionCalledWithArgs(uint256 a, uint256 b); + + uint256[] private _array; + + function mockFunction() public payable returns (string memory) { + emit MockFunctionCalled(); + + return "0x1234"; + } + + function mockFunctionEmptyReturn() public payable { + emit MockFunctionCalled(); + } + + function mockFunctionWithArgs(uint256 a, uint256 b) public payable returns (string memory) { + emit MockFunctionCalledWithArgs(a, b); + + return "0x1234"; + } + + function mockFunctionNonPayable() public returns (string memory) { + emit MockFunctionCalled(); + + return "0x1234"; + } + + function mockStaticFunction() public pure returns (string memory) { + return "0x1234"; + } + + function mockFunctionRevertsNoReason() public payable { + revert(); + } + + function mockFunctionRevertsReason() public payable { + revert("CallReceiverMock: reverting"); + } + + function mockFunctionThrows() public payable { + assert(false); + } + + function mockFunctionOutOfGas() public payable { + for (uint256 i = 0; ; ++i) { + _array.push(i); + } + } + + function mockFunctionWritesStorage(bytes32 slot, bytes32 value) public returns (string memory) { + assembly { + sstore(slot, value) + } + return "0x1234"; + } +} + +contract CallReceiverMockTrustingForwarder is CallReceiverMock { + address private _trustedForwarder; + + constructor(address trustedForwarder_) { + _trustedForwarder = trustedForwarder_; + } + + function isTrustedForwarder(address forwarder) public view virtual returns (bool) { + return forwarder == _trustedForwarder; + } +} diff --git a/contracts/mocks/ContextMock.sol b/contracts/mocks/ContextMock.sol new file mode 100644 index 000000000..199b2a978 --- /dev/null +++ b/contracts/mocks/ContextMock.sol @@ -0,0 +1,35 @@ +// SPDX-License-Identifier: MIT + +pragma solidity ^0.8.20; + +import {Context} from "../utils/Context.sol"; + +contract ContextMock is Context { + event Sender(address sender); + + function msgSender() public { + emit Sender(_msgSender()); + } + + event Data(bytes data, uint256 integerValue, string stringValue); + + function msgData(uint256 integerValue, string memory stringValue) public { + emit Data(_msgData(), integerValue, stringValue); + } + + event DataShort(bytes data); + + function msgDataShort() public { + emit DataShort(_msgData()); + } +} + +contract ContextMockCaller { + function callSender(ContextMock context) public { + context.msgSender(); + } + + function callData(ContextMock context, uint256 integerValue, string memory stringValue) public { + context.msgData(integerValue, stringValue); + } +} diff --git a/contracts/mocks/DummyImplementation.sol b/contracts/mocks/DummyImplementation.sol new file mode 100644 index 000000000..4925c89df --- /dev/null +++ b/contracts/mocks/DummyImplementation.sol @@ -0,0 +1,65 @@ +// SPDX-License-Identifier: MIT + +pragma solidity ^0.8.20; + +import {ERC1967Utils} from "../proxy/ERC1967/ERC1967Utils.sol"; +import {StorageSlot} from "../utils/StorageSlot.sol"; + +abstract contract Impl { + function version() public pure virtual returns (string memory); +} + +contract DummyImplementation { + uint256 public value; + string public text; + uint256[] public values; + + function initializeNonPayable() public { + value = 10; + } + + function initializePayable() public payable { + value = 100; + } + + function initializeNonPayableWithValue(uint256 _value) public { + value = _value; + } + + function initializePayableWithValue(uint256 _value) public payable { + value = _value; + } + + function initialize(uint256 _value, string memory _text, uint256[] memory _values) public { + value = _value; + text = _text; + values = _values; + } + + function get() public pure returns (bool) { + return true; + } + + function version() public pure virtual returns (string memory) { + return "V1"; + } + + function reverts() public pure { + require(false, "DummyImplementation reverted"); + } + + // Use for forcing an unsafe TransparentUpgradeableProxy admin override + function unsafeOverrideAdmin(address newAdmin) public { + StorageSlot.getAddressSlot(ERC1967Utils.ADMIN_SLOT).value = newAdmin; + } +} + +contract DummyImplementationV2 is DummyImplementation { + function migrate(uint256 newVal) public payable { + value = newVal; + } + + function version() public pure override returns (string memory) { + return "V2"; + } +} diff --git a/contracts/mocks/EIP712Verifier.sol b/contracts/mocks/EIP712Verifier.sol new file mode 100644 index 000000000..fe32a2189 --- /dev/null +++ b/contracts/mocks/EIP712Verifier.sol @@ -0,0 +1,16 @@ +// SPDX-License-Identifier: MIT + +pragma solidity ^0.8.20; + +import {ECDSA} from "../utils/cryptography/ECDSA.sol"; +import {EIP712} from "../utils/cryptography/EIP712.sol"; + +abstract contract EIP712Verifier is EIP712 { + function verify(bytes memory signature, address signer, address mailTo, string memory mailContents) external view { + bytes32 digest = _hashTypedDataV4( + keccak256(abi.encode(keccak256("Mail(address to,string contents)"), mailTo, keccak256(bytes(mailContents)))) + ); + address recoveredSigner = ECDSA.recover(digest, signature); + require(recoveredSigner == signer); + } +} diff --git a/contracts/mocks/ERC1271WalletMock.sol b/contracts/mocks/ERC1271WalletMock.sol new file mode 100644 index 000000000..cba7d47d7 --- /dev/null +++ b/contracts/mocks/ERC1271WalletMock.sol @@ -0,0 +1,24 @@ +// SPDX-License-Identifier: MIT + +pragma solidity ^0.8.20; + +import {Ownable} from "../access/Ownable.sol"; +import {IERC1271} from "../interfaces/IERC1271.sol"; +import {ECDSA} from "../utils/cryptography/ECDSA.sol"; + +contract ERC1271WalletMock is Ownable, IERC1271 { + constructor(address originalOwner) Ownable(originalOwner) {} + + function isValidSignature(bytes32 hash, bytes memory signature) public view returns (bytes4 magicValue) { + return ECDSA.recover(hash, signature) == owner() ? this.isValidSignature.selector : bytes4(0); + } +} + +contract ERC1271MaliciousMock is IERC1271 { + function isValidSignature(bytes32, bytes memory) public pure returns (bytes4) { + assembly { + mstore(0, 0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff) + return(0, 32) + } + } +} diff --git a/contracts/mocks/ERC165/ERC165InterfacesSupported.sol b/contracts/mocks/ERC165/ERC165InterfacesSupported.sol new file mode 100644 index 000000000..4010b2103 --- /dev/null +++ b/contracts/mocks/ERC165/ERC165InterfacesSupported.sol @@ -0,0 +1,58 @@ +// SPDX-License-Identifier: MIT + +pragma solidity ^0.8.20; + +import {IERC165} from "../../utils/introspection/IERC165.sol"; + +/** + * https://eips.ethereum.org/EIPS/eip-214#specification + * From the specification: + * > Any attempts to make state-changing operations inside an execution instance with STATIC set to true will instead + * throw an exception. + * > These operations include [...], LOG0, LOG1, LOG2, [...] + * + * therefore, because this contract is staticcall'd we need to not emit events (which is how solidity-coverage works) + * solidity-coverage ignores the /mocks folder, so we duplicate its implementation here to avoid instrumenting it + */ +contract SupportsInterfaceWithLookupMock is IERC165 { + /* + * bytes4(keccak256('supportsInterface(bytes4)')) == 0x01ffc9a7 + */ + bytes4 public constant INTERFACE_ID_ERC165 = 0x01ffc9a7; + + /** + * @dev A mapping of interface id to whether or not it's supported. + */ + mapping(bytes4 interfaceId => bool) private _supportedInterfaces; + + /** + * @dev A contract implementing SupportsInterfaceWithLookup + * implement ERC165 itself. + */ + constructor() { + _registerInterface(INTERFACE_ID_ERC165); + } + + /** + * @dev Implement supportsInterface(bytes4) using a lookup table. + */ + function supportsInterface(bytes4 interfaceId) public view override returns (bool) { + return _supportedInterfaces[interfaceId]; + } + + /** + * @dev Private method for registering an interface. + */ + function _registerInterface(bytes4 interfaceId) internal { + require(interfaceId != 0xffffffff, "ERC165InterfacesSupported: invalid interface id"); + _supportedInterfaces[interfaceId] = true; + } +} + +contract ERC165InterfacesSupported is SupportsInterfaceWithLookupMock { + constructor(bytes4[] memory interfaceIds) { + for (uint256 i = 0; i < interfaceIds.length; i++) { + _registerInterface(interfaceIds[i]); + } + } +} diff --git a/contracts/mocks/ERC165/ERC165MaliciousData.sol b/contracts/mocks/ERC165/ERC165MaliciousData.sol new file mode 100644 index 000000000..35427567d --- /dev/null +++ b/contracts/mocks/ERC165/ERC165MaliciousData.sol @@ -0,0 +1,12 @@ +// SPDX-License-Identifier: MIT + +pragma solidity ^0.8.20; + +contract ERC165MaliciousData { + function supportsInterface(bytes4) public pure returns (bool) { + assembly { + mstore(0, 0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff) + return(0, 32) + } + } +} diff --git a/contracts/mocks/ERC165/ERC165MissingData.sol b/contracts/mocks/ERC165/ERC165MissingData.sol new file mode 100644 index 000000000..fec43391b --- /dev/null +++ b/contracts/mocks/ERC165/ERC165MissingData.sol @@ -0,0 +1,7 @@ +// SPDX-License-Identifier: MIT + +pragma solidity ^0.8.20; + +contract ERC165MissingData { + function supportsInterface(bytes4 interfaceId) public view {} // missing return +} diff --git a/contracts/mocks/ERC165/ERC165NotSupported.sol b/contracts/mocks/ERC165/ERC165NotSupported.sol new file mode 100644 index 000000000..78ef9c8e0 --- /dev/null +++ b/contracts/mocks/ERC165/ERC165NotSupported.sol @@ -0,0 +1,5 @@ +// SPDX-License-Identifier: MIT + +pragma solidity ^0.8.20; + +contract ERC165NotSupported {} diff --git a/contracts/mocks/ERC165/ERC165ReturnBomb.sol b/contracts/mocks/ERC165/ERC165ReturnBomb.sol new file mode 100644 index 000000000..4bfacfd66 --- /dev/null +++ b/contracts/mocks/ERC165/ERC165ReturnBomb.sol @@ -0,0 +1,18 @@ +// SPDX-License-Identifier: MIT + +pragma solidity ^0.8.20; + +import {IERC165} from "../../utils/introspection/IERC165.sol"; + +contract ERC165ReturnBombMock is IERC165 { + function supportsInterface(bytes4 interfaceId) public pure override returns (bool) { + if (interfaceId == type(IERC165).interfaceId) { + assembly { + mstore(0, 1) + } + } + assembly { + return(0, 101500) + } + } +} diff --git a/contracts/mocks/ERC2771ContextMock.sol b/contracts/mocks/ERC2771ContextMock.sol new file mode 100644 index 000000000..22b9203e7 --- /dev/null +++ b/contracts/mocks/ERC2771ContextMock.sol @@ -0,0 +1,23 @@ +// SPDX-License-Identifier: MIT + +pragma solidity ^0.8.20; + +import {ContextMock} from "./ContextMock.sol"; +import {Context} from "../utils/Context.sol"; +import {ERC2771Context} from "../metatx/ERC2771Context.sol"; + +// By inheriting from ERC2771Context, Context's internal functions are overridden automatically +contract ERC2771ContextMock is ContextMock, ERC2771Context { + /// @custom:oz-upgrades-unsafe-allow constructor + constructor(address trustedForwarder) ERC2771Context(trustedForwarder) { + emit Sender(_msgSender()); // _msgSender() should be accessible during construction + } + + function _msgSender() internal view override(Context, ERC2771Context) returns (address) { + return ERC2771Context._msgSender(); + } + + function _msgData() internal view override(Context, ERC2771Context) returns (bytes calldata) { + return ERC2771Context._msgData(); + } +} diff --git a/contracts/mocks/ERC3156FlashBorrowerMock.sol b/contracts/mocks/ERC3156FlashBorrowerMock.sol new file mode 100644 index 000000000..261fea177 --- /dev/null +++ b/contracts/mocks/ERC3156FlashBorrowerMock.sol @@ -0,0 +1,53 @@ +// SPDX-License-Identifier: MIT + +pragma solidity ^0.8.20; + +import {IERC20} from "../token/ERC20/IERC20.sol"; +import {IERC3156FlashBorrower} from "../interfaces/IERC3156.sol"; +import {Address} from "../utils/Address.sol"; + +/** + * @dev WARNING: this IERC3156FlashBorrower mock implementation is for testing purposes ONLY. + * Writing a secure flash lock borrower is not an easy task, and should be done with the utmost care. + * This is not an example of how it should be done, and no pattern present in this mock should be considered secure. + * Following best practices, always have your contract properly audited before using them to manipulate important funds on + * live networks. + */ +contract ERC3156FlashBorrowerMock is IERC3156FlashBorrower { + bytes32 internal constant _RETURN_VALUE = keccak256("ERC3156FlashBorrower.onFlashLoan"); + + bool immutable _enableApprove; + bool immutable _enableReturn; + + event BalanceOf(address token, address account, uint256 value); + event TotalSupply(address token, uint256 value); + + constructor(bool enableReturn, bool enableApprove) { + _enableApprove = enableApprove; + _enableReturn = enableReturn; + } + + function onFlashLoan( + address /*initiator*/, + address token, + uint256 amount, + uint256 fee, + bytes calldata data + ) public returns (bytes32) { + require(msg.sender == token); + + emit BalanceOf(token, address(this), IERC20(token).balanceOf(address(this))); + emit TotalSupply(token, IERC20(token).totalSupply()); + + if (data.length > 0) { + // WARNING: This code is for testing purposes only! Do not use. + Address.functionCall(token, data); + } + + if (_enableApprove) { + IERC20(token).approve(token, amount + fee); + } + + return _enableReturn ? _RETURN_VALUE : bytes32(0); + } +} diff --git a/contracts/mocks/EtherReceiverMock.sol b/contracts/mocks/EtherReceiverMock.sol new file mode 100644 index 000000000..1b1c9363a --- /dev/null +++ b/contracts/mocks/EtherReceiverMock.sol @@ -0,0 +1,17 @@ +// SPDX-License-Identifier: MIT + +pragma solidity ^0.8.20; + +contract EtherReceiverMock { + bool private _acceptEther; + + function setAcceptEther(bool acceptEther) public { + _acceptEther = acceptEther; + } + + receive() external payable { + if (!_acceptEther) { + revert(); + } + } +} diff --git a/contracts/mocks/InitializableMock.sol b/contracts/mocks/InitializableMock.sol new file mode 100644 index 000000000..7f76caacd --- /dev/null +++ b/contracts/mocks/InitializableMock.sol @@ -0,0 +1,130 @@ +// SPDX-License-Identifier: MIT + +pragma solidity ^0.8.20; + +import {Initializable} from "../proxy/utils/Initializable.sol"; + +/** + * @title InitializableMock + * @dev This contract is a mock to test initializable functionality + */ +contract InitializableMock is Initializable { + bool public initializerRan; + bool public onlyInitializingRan; + uint256 public x; + + function isInitializing() public view returns (bool) { + return _isInitializing(); + } + + function initialize() public initializer { + initializerRan = true; + } + + function initializeOnlyInitializing() public onlyInitializing { + onlyInitializingRan = true; + } + + function initializerNested() public initializer { + initialize(); + } + + function onlyInitializingNested() public initializer { + initializeOnlyInitializing(); + } + + function initializeWithX(uint256 _x) public payable initializer { + x = _x; + } + + function nonInitializable(uint256 _x) public payable { + x = _x; + } + + function fail() public pure { + require(false, "InitializableMock forced failure"); + } +} + +contract ConstructorInitializableMock is Initializable { + bool public initializerRan; + bool public onlyInitializingRan; + + constructor() initializer { + initialize(); + initializeOnlyInitializing(); + } + + function initialize() public initializer { + initializerRan = true; + } + + function initializeOnlyInitializing() public onlyInitializing { + onlyInitializingRan = true; + } +} + +contract ChildConstructorInitializableMock is ConstructorInitializableMock { + bool public childInitializerRan; + + constructor() initializer { + childInitialize(); + } + + function childInitialize() public initializer { + childInitializerRan = true; + } +} + +contract ReinitializerMock is Initializable { + uint256 public counter; + + function getInitializedVersion() public view returns (uint64) { + return _getInitializedVersion(); + } + + function initialize() public initializer { + doStuff(); + } + + function reinitialize(uint64 i) public reinitializer(i) { + doStuff(); + } + + function nestedReinitialize(uint64 i, uint64 j) public reinitializer(i) { + reinitialize(j); + } + + function chainReinitialize(uint64 i, uint64 j) public { + reinitialize(i); + reinitialize(j); + } + + function disableInitializers() public { + _disableInitializers(); + } + + function doStuff() public onlyInitializing { + counter++; + } +} + +contract DisableNew is Initializable { + constructor() { + _disableInitializers(); + } +} + +contract DisableOld is Initializable { + constructor() initializer {} +} + +contract DisableBad1 is DisableNew, DisableOld {} + +contract DisableBad2 is Initializable { + constructor() initializer { + _disableInitializers(); + } +} + +contract DisableOk is DisableOld, DisableNew {} diff --git a/contracts/mocks/MulticallTest.sol b/contracts/mocks/MulticallTest.sol new file mode 100644 index 000000000..74be7d8b4 --- /dev/null +++ b/contracts/mocks/MulticallTest.sol @@ -0,0 +1,23 @@ +// SPDX-License-Identifier: MIT + +pragma solidity ^0.8.20; + +import {ERC20MulticallMock} from "./token/ERC20MulticallMock.sol"; + +contract MulticallTest { + function checkReturnValues( + ERC20MulticallMock multicallToken, + address[] calldata recipients, + uint256[] calldata amounts + ) external { + bytes[] memory calls = new bytes[](recipients.length); + for (uint256 i = 0; i < recipients.length; i++) { + calls[i] = abi.encodeCall(multicallToken.transfer, (recipients[i], amounts[i])); + } + + bytes[] memory results = multicallToken.multicall(calls); + for (uint256 i = 0; i < results.length; i++) { + require(abi.decode(results[i], (bool))); + } + } +} diff --git a/contracts/mocks/MultipleInheritanceInitializableMocks.sol b/contracts/mocks/MultipleInheritanceInitializableMocks.sol new file mode 100644 index 000000000..51030acd6 --- /dev/null +++ b/contracts/mocks/MultipleInheritanceInitializableMocks.sol @@ -0,0 +1,131 @@ +// SPDX-License-Identifier: MIT + +pragma solidity ^0.8.20; + +import {Initializable} from "../proxy/utils/Initializable.sol"; + +// Sample contracts showing upgradeability with multiple inheritance. +// Child contract inherits from Father and Mother contracts, and Father extends from Gramps. +// +// Human +// / \ +// | Gramps +// | | +// Mother Father +// | | +// -- Child -- + +/** + * Sample base initializable contract that is a human + */ +contract SampleHuman is Initializable { + bool public isHuman; + + function initialize() public initializer { + __SampleHuman_init(); + } + + // solhint-disable-next-line func-name-mixedcase + function __SampleHuman_init() internal onlyInitializing { + __SampleHuman_init_unchained(); + } + + // solhint-disable-next-line func-name-mixedcase + function __SampleHuman_init_unchained() internal onlyInitializing { + isHuman = true; + } +} + +/** + * Sample base initializable contract that defines a field mother + */ +contract SampleMother is Initializable, SampleHuman { + uint256 public mother; + + function initialize(uint256 value) public initializer { + __SampleMother_init(value); + } + + // solhint-disable-next-line func-name-mixedcase + function __SampleMother_init(uint256 value) internal onlyInitializing { + __SampleHuman_init(); + __SampleMother_init_unchained(value); + } + + // solhint-disable-next-line func-name-mixedcase + function __SampleMother_init_unchained(uint256 value) internal onlyInitializing { + mother = value; + } +} + +/** + * Sample base initializable contract that defines a field gramps + */ +contract SampleGramps is Initializable, SampleHuman { + string public gramps; + + function initialize(string memory value) public initializer { + __SampleGramps_init(value); + } + + // solhint-disable-next-line func-name-mixedcase + function __SampleGramps_init(string memory value) internal onlyInitializing { + __SampleHuman_init(); + __SampleGramps_init_unchained(value); + } + + // solhint-disable-next-line func-name-mixedcase + function __SampleGramps_init_unchained(string memory value) internal onlyInitializing { + gramps = value; + } +} + +/** + * Sample base initializable contract that defines a field father and extends from gramps + */ +contract SampleFather is Initializable, SampleGramps { + uint256 public father; + + function initialize(string memory _gramps, uint256 _father) public initializer { + __SampleFather_init(_gramps, _father); + } + + // solhint-disable-next-line func-name-mixedcase + function __SampleFather_init(string memory _gramps, uint256 _father) internal onlyInitializing { + __SampleGramps_init(_gramps); + __SampleFather_init_unchained(_father); + } + + // solhint-disable-next-line func-name-mixedcase + function __SampleFather_init_unchained(uint256 _father) internal onlyInitializing { + father = _father; + } +} + +/** + * Child extends from mother, father (gramps) + */ +contract SampleChild is Initializable, SampleMother, SampleFather { + uint256 public child; + + function initialize(uint256 _mother, string memory _gramps, uint256 _father, uint256 _child) public initializer { + __SampleChild_init(_mother, _gramps, _father, _child); + } + + // solhint-disable-next-line func-name-mixedcase + function __SampleChild_init( + uint256 _mother, + string memory _gramps, + uint256 _father, + uint256 _child + ) internal onlyInitializing { + __SampleMother_init(_mother); + __SampleFather_init(_gramps, _father); + __SampleChild_init_unchained(_child); + } + + // solhint-disable-next-line func-name-mixedcase + function __SampleChild_init_unchained(uint256 _child) internal onlyInitializing { + child = _child; + } +} diff --git a/contracts/mocks/PausableMock.sol b/contracts/mocks/PausableMock.sol new file mode 100644 index 000000000..fa701e2c7 --- /dev/null +++ b/contracts/mocks/PausableMock.sol @@ -0,0 +1,31 @@ +// SPDX-License-Identifier: MIT + +pragma solidity ^0.8.20; + +import {Pausable} from "../utils/Pausable.sol"; + +contract PausableMock is Pausable { + bool public drasticMeasureTaken; + uint256 public count; + + constructor() { + drasticMeasureTaken = false; + count = 0; + } + + function normalProcess() external whenNotPaused { + count++; + } + + function drasticMeasure() external whenPaused { + drasticMeasureTaken = true; + } + + function pause() external { + _pause(); + } + + function unpause() external { + _unpause(); + } +} diff --git a/contracts/mocks/ReentrancyAttack.sol b/contracts/mocks/ReentrancyAttack.sol new file mode 100644 index 000000000..3df2d1c2b --- /dev/null +++ b/contracts/mocks/ReentrancyAttack.sol @@ -0,0 +1,12 @@ +// SPDX-License-Identifier: MIT + +pragma solidity ^0.8.20; + +import {Context} from "../utils/Context.sol"; + +contract ReentrancyAttack is Context { + function callSender(bytes calldata data) public { + (bool success, ) = _msgSender().call(data); + require(success, "ReentrancyAttack: failed call"); + } +} diff --git a/contracts/mocks/ReentrancyMock.sol b/contracts/mocks/ReentrancyMock.sol new file mode 100644 index 000000000..39e2d5ed8 --- /dev/null +++ b/contracts/mocks/ReentrancyMock.sol @@ -0,0 +1,50 @@ +// SPDX-License-Identifier: MIT + +pragma solidity ^0.8.20; + +import {ReentrancyGuard} from "../utils/ReentrancyGuard.sol"; +import {ReentrancyAttack} from "./ReentrancyAttack.sol"; + +contract ReentrancyMock is ReentrancyGuard { + uint256 public counter; + + constructor() { + counter = 0; + } + + function callback() external nonReentrant { + _count(); + } + + function countLocalRecursive(uint256 n) public nonReentrant { + if (n > 0) { + _count(); + countLocalRecursive(n - 1); + } + } + + function countThisRecursive(uint256 n) public nonReentrant { + if (n > 0) { + _count(); + (bool success, ) = address(this).call(abi.encodeCall(this.countThisRecursive, (n - 1))); + require(success, "ReentrancyMock: failed call"); + } + } + + function countAndCall(ReentrancyAttack attacker) public nonReentrant { + _count(); + attacker.callSender(abi.encodeCall(this.callback, ())); + } + + function _count() private { + counter += 1; + } + + function guardedCheckEntered() public nonReentrant { + require(_reentrancyGuardEntered()); + } + + function unguardedCheckNotEntered() public view { + require(!_reentrancyGuardEntered()); + } +} diff --git a/contracts/mocks/RegressionImplementation.sol b/contracts/mocks/RegressionImplementation.sol new file mode 100644 index 000000000..19b9706d4 --- /dev/null +++ b/contracts/mocks/RegressionImplementation.sol @@ -0,0 +1,61 @@ +// SPDX-License-Identifier: MIT + +pragma solidity ^0.8.20; + +import {Initializable} from "../proxy/utils/Initializable.sol"; + +contract Implementation1 is Initializable { + uint256 internal _value; + + function initialize() public initializer {} + + function setValue(uint256 _number) public { + _value = _number; + } +} + +contract Implementation2 is Initializable { + uint256 internal _value; + + function initialize() public initializer {} + + function setValue(uint256 _number) public { + _value = _number; + } + + function getValue() public view returns (uint256) { + return _value; + } +} + +contract Implementation3 is Initializable { + uint256 internal _value; + + function initialize() public initializer {} + + function setValue(uint256 _number) public { + _value = _number; + } + + function getValue(uint256 _number) public view returns (uint256) { + return _value + _number; + } +} + +contract Implementation4 is Initializable { + uint256 internal _value; + + function initialize() public initializer {} + + function setValue(uint256 _number) public { + _value = _number; + } + + function getValue() public view returns (uint256) { + return _value; + } + + fallback() external { + _value = 1; + } +} diff --git a/contracts/mocks/SingleInheritanceInitializableMocks.sol b/contracts/mocks/SingleInheritanceInitializableMocks.sol new file mode 100644 index 000000000..0bd3c614f --- /dev/null +++ b/contracts/mocks/SingleInheritanceInitializableMocks.sol @@ -0,0 +1,49 @@ +// SPDX-License-Identifier: MIT + +pragma solidity ^0.8.20; + +import {Initializable} from "../proxy/utils/Initializable.sol"; + +/** + * @title MigratableMockV1 + * @dev This contract is a mock to test initializable functionality through migrations + */ +contract MigratableMockV1 is Initializable { + uint256 public x; + + function initialize(uint256 value) public payable initializer { + x = value; + } +} + +/** + * @title MigratableMockV2 + * @dev This contract is a mock to test migratable functionality with params + */ +contract MigratableMockV2 is MigratableMockV1 { + bool internal _migratedV2; + uint256 public y; + + function migrate(uint256 value, uint256 anotherValue) public payable { + require(!_migratedV2); + x = value; + y = anotherValue; + _migratedV2 = true; + } +} + +/** + * @title MigratableMockV3 + * @dev This contract is a mock to test migratable functionality without params + */ +contract MigratableMockV3 is MigratableMockV2 { + bool internal _migratedV3; + + function migrate() public payable { + require(!_migratedV3); + uint256 oldX = x; + x = y; + y = oldX; + _migratedV3 = true; + } +} diff --git a/contracts/mocks/StorageSlotMock.sol b/contracts/mocks/StorageSlotMock.sol new file mode 100644 index 000000000..dbdad7a2a --- /dev/null +++ b/contracts/mocks/StorageSlotMock.sol @@ -0,0 +1,77 @@ +// SPDX-License-Identifier: MIT + +pragma solidity ^0.8.20; + +import {StorageSlot} from "../utils/StorageSlot.sol"; + +contract StorageSlotMock { + using StorageSlot for *; + + function setBoolean(bytes32 slot, bool value) public { + slot.getBooleanSlot().value = value; + } + + function setAddress(bytes32 slot, address value) public { + slot.getAddressSlot().value = value; + } + + function setBytes32(bytes32 slot, bytes32 value) public { + slot.getBytes32Slot().value = value; + } + + function setUint256(bytes32 slot, uint256 value) public { + slot.getUint256Slot().value = value; + } + + function getBoolean(bytes32 slot) public view returns (bool) { + return slot.getBooleanSlot().value; + } + + function getAddress(bytes32 slot) public view returns (address) { + return slot.getAddressSlot().value; + } + + function getBytes32(bytes32 slot) public view returns (bytes32) { + return slot.getBytes32Slot().value; + } + + function getUint256(bytes32 slot) public view returns (uint256) { + return slot.getUint256Slot().value; + } + + mapping(uint256 key => string) public stringMap; + + function setString(bytes32 slot, string calldata value) public { + slot.getStringSlot().value = value; + } + + function setStringStorage(uint256 key, string calldata value) public { + stringMap[key].getStringSlot().value = value; + } + + function getString(bytes32 slot) public view returns (string memory) { + return slot.getStringSlot().value; + } + + function getStringStorage(uint256 key) public view returns (string memory) { + return stringMap[key].getStringSlot().value; + } + + mapping(uint256 key => bytes) public bytesMap; + + function setBytes(bytes32 slot, bytes calldata value) public { + slot.getBytesSlot().value = value; + } + + function setBytesStorage(uint256 key, bytes calldata value) public { + bytesMap[key].getBytesSlot().value = value; + } + + function getBytes(bytes32 slot) public view returns (bytes memory) { + return slot.getBytesSlot().value; + } + + function getBytesStorage(uint256 key) public view returns (bytes memory) { + return bytesMap[key].getBytesSlot().value; + } +} diff --git a/contracts/mocks/TimelockReentrant.sol b/contracts/mocks/TimelockReentrant.sol new file mode 100644 index 000000000..aab676a50 --- /dev/null +++ b/contracts/mocks/TimelockReentrant.sol @@ -0,0 +1,26 @@ +// SPDX-License-Identifier: MIT +pragma solidity ^0.8.20; + +import {Address} from "../utils/Address.sol"; + +contract TimelockReentrant { + address private _reenterTarget; + bytes private _reenterData; + bool _reentered; + + function disableReentrancy() external { + _reentered = true; + } + + function enableRentrancy(address target, bytes calldata data) external { + _reenterTarget = target; + _reenterData = data; + } + + function reenter() external { + if (!_reentered) { + _reentered = true; + Address.functionCall(_reenterTarget, _reenterData); + } + } +} diff --git a/contracts/mocks/UpgradeableBeaconMock.sol b/contracts/mocks/UpgradeableBeaconMock.sol new file mode 100644 index 000000000..354ac02f0 --- /dev/null +++ b/contracts/mocks/UpgradeableBeaconMock.sol @@ -0,0 +1,27 @@ +// SPDX-License-Identifier: MIT +pragma solidity ^0.8.20; + +import {IBeacon} from "../proxy/beacon/IBeacon.sol"; + +contract UpgradeableBeaconMock is IBeacon { + address public implementation; + + constructor(address impl) { + implementation = impl; + } +} + +interface IProxyExposed { + // solhint-disable-next-line func-name-mixedcase + function $getBeacon() external view returns (address); +} + +contract UpgradeableBeaconReentrantMock is IBeacon { + error BeaconProxyBeaconSlotAddress(address beacon); + + function implementation() external view override returns (address) { + // Revert with the beacon seen in the proxy at the moment of calling to check if it's + // set before the call. + revert BeaconProxyBeaconSlotAddress(IProxyExposed(msg.sender).$getBeacon()); + } +} diff --git a/contracts/mocks/VotesMock.sol b/contracts/mocks/VotesMock.sol new file mode 100644 index 000000000..e28d6b557 --- /dev/null +++ b/contracts/mocks/VotesMock.sol @@ -0,0 +1,42 @@ +// SPDX-License-Identifier: MIT + +pragma solidity ^0.8.20; + +import {Votes} from "../governance/utils/Votes.sol"; + +abstract contract VotesMock is Votes { + mapping(address voter => uint256) private _votingUnits; + + function getTotalSupply() public view returns (uint256) { + return _getTotalSupply(); + } + + function delegate(address account, address newDelegation) public { + return _delegate(account, newDelegation); + } + + function _getVotingUnits(address account) internal view override returns (uint256) { + return _votingUnits[account]; + } + + function _mint(address account, uint256 votes) internal { + _votingUnits[account] += votes; + _transferVotingUnits(address(0), account, votes); + } + + function _burn(address account, uint256 votes) internal { + _votingUnits[account] += votes; + _transferVotingUnits(account, address(0), votes); + } +} + +abstract contract VotesTimestampMock is VotesMock { + function clock() public view override returns (uint48) { + return uint48(block.timestamp); + } + + // solhint-disable-next-line func-name-mixedcase + function CLOCK_MODE() public view virtual override returns (string memory) { + return "mode=timestamp"; + } +} diff --git a/contracts/mocks/compound/CompTimelock.sol b/contracts/mocks/compound/CompTimelock.sol new file mode 100644 index 000000000..c72ed0833 --- /dev/null +++ b/contracts/mocks/compound/CompTimelock.sol @@ -0,0 +1,174 @@ +// SPDX-License-Identifier: BSD-3-Clause +// solhint-disable private-vars-leading-underscore +/** + * Copyright 2020 Compound Labs, Inc. + * + * Redistribution and use in source and binary forms, with or without modification, are permitted provided that the + * following conditions are met: + * + * 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following + * disclaimer. + * + * 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the + * following disclaimer in the documentation and/or other materials provided with the distribution. + * + * 3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote + * products derived from this software without specific prior written permission. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, + * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE + * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, + * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR + * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, + * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE + * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + */ + +pragma solidity ^0.8.20; + +contract CompTimelock { + event NewAdmin(address indexed newAdmin); + event NewPendingAdmin(address indexed newPendingAdmin); + event NewDelay(uint256 indexed newDelay); + event CancelTransaction( + bytes32 indexed txHash, + address indexed target, + uint256 value, + string signature, + bytes data, + uint256 eta + ); + event ExecuteTransaction( + bytes32 indexed txHash, + address indexed target, + uint256 value, + string signature, + bytes data, + uint256 eta + ); + event QueueTransaction( + bytes32 indexed txHash, + address indexed target, + uint256 value, + string signature, + bytes data, + uint256 eta + ); + + uint256 public constant GRACE_PERIOD = 14 days; + uint256 public constant MINIMUM_DELAY = 2 days; + uint256 public constant MAXIMUM_DELAY = 30 days; + + address public admin; + address public pendingAdmin; + uint256 public delay; + + mapping(bytes32 => bool) public queuedTransactions; + + constructor(address admin_, uint256 delay_) { + require(delay_ >= MINIMUM_DELAY, "Timelock::constructor: Delay must exceed minimum delay."); + require(delay_ <= MAXIMUM_DELAY, "Timelock::setDelay: Delay must not exceed maximum delay."); + + admin = admin_; + delay = delay_; + } + + receive() external payable {} + + function setDelay(uint256 delay_) public { + require(msg.sender == address(this), "Timelock::setDelay: Call must come from Timelock."); + require(delay_ >= MINIMUM_DELAY, "Timelock::setDelay: Delay must exceed minimum delay."); + require(delay_ <= MAXIMUM_DELAY, "Timelock::setDelay: Delay must not exceed maximum delay."); + delay = delay_; + + emit NewDelay(delay); + } + + function acceptAdmin() public { + require(msg.sender == pendingAdmin, "Timelock::acceptAdmin: Call must come from pendingAdmin."); + admin = msg.sender; + pendingAdmin = address(0); + + emit NewAdmin(admin); + } + + function setPendingAdmin(address pendingAdmin_) public { + require(msg.sender == address(this), "Timelock::setPendingAdmin: Call must come from Timelock."); + pendingAdmin = pendingAdmin_; + + emit NewPendingAdmin(pendingAdmin); + } + + function queueTransaction( + address target, + uint256 value, + string memory signature, + bytes memory data, + uint256 eta + ) public returns (bytes32) { + require(msg.sender == admin, "Timelock::queueTransaction: Call must come from admin."); + require( + eta >= getBlockTimestamp() + delay, + "Timelock::queueTransaction: Estimated execution block must satisfy delay." + ); + + bytes32 txHash = keccak256(abi.encode(target, value, signature, data, eta)); + queuedTransactions[txHash] = true; + + emit QueueTransaction(txHash, target, value, signature, data, eta); + return txHash; + } + + function cancelTransaction( + address target, + uint256 value, + string memory signature, + bytes memory data, + uint256 eta + ) public { + require(msg.sender == admin, "Timelock::cancelTransaction: Call must come from admin."); + + bytes32 txHash = keccak256(abi.encode(target, value, signature, data, eta)); + queuedTransactions[txHash] = false; + + emit CancelTransaction(txHash, target, value, signature, data, eta); + } + + function executeTransaction( + address target, + uint256 value, + string memory signature, + bytes memory data, + uint256 eta + ) public payable returns (bytes memory) { + require(msg.sender == admin, "Timelock::executeTransaction: Call must come from admin."); + + bytes32 txHash = keccak256(abi.encode(target, value, signature, data, eta)); + require(queuedTransactions[txHash], "Timelock::executeTransaction: Transaction hasn't been queued."); + require(getBlockTimestamp() >= eta, "Timelock::executeTransaction: Transaction hasn't surpassed time lock."); + require(getBlockTimestamp() <= eta + GRACE_PERIOD, "Timelock::executeTransaction: Transaction is stale."); + + queuedTransactions[txHash] = false; + + bytes memory callData; + + if (bytes(signature).length == 0) { + callData = data; + } else { + callData = abi.encodePacked(bytes4(keccak256(bytes(signature))), data); + } + + // solium-disable-next-line security/no-call-value + (bool success, bytes memory returnData) = target.call{value: value}(callData); + require(success, "Timelock::executeTransaction: Transaction execution reverted."); + + emit ExecuteTransaction(txHash, target, value, signature, data, eta); + + return returnData; + } + + function getBlockTimestamp() internal view returns (uint256) { + // solium-disable-next-line security/no-block-members + return block.timestamp; + } +} diff --git a/contracts/mocks/docs/ERC4626Fees.sol b/contracts/mocks/docs/ERC4626Fees.sol new file mode 100644 index 000000000..17bc92d7c --- /dev/null +++ b/contracts/mocks/docs/ERC4626Fees.sol @@ -0,0 +1,103 @@ +// SPDX-License-Identifier: MIT + +pragma solidity ^0.8.20; + +import {IERC20} from "../../token/ERC20/IERC20.sol"; +import {ERC4626} from "../../token/ERC20/extensions/ERC4626.sol"; +import {SafeERC20} from "../../token/ERC20/utils/SafeERC20.sol"; +import {Math} from "../../utils/math/Math.sol"; + +/// @dev ERC4626 vault with entry/exit fees expressed in https://en.wikipedia.org/wiki/Basis_point[basis point (bp)]. +abstract contract ERC4626Fees is ERC4626 { + using Math for uint256; + + uint256 private constant _BASIS_POINT_SCALE = 1e4; + + // === Overrides === + + /// @dev Preview taking an entry fee on deposit. See {IERC4626-previewDeposit}. + function previewDeposit(uint256 assets) public view virtual override returns (uint256) { + uint256 fee = _feeOnTotal(assets, _entryFeeBasisPoints()); + return super.previewDeposit(assets - fee); + } + + /// @dev Preview adding an entry fee on mint. See {IERC4626-previewMint}. + function previewMint(uint256 shares) public view virtual override returns (uint256) { + uint256 assets = super.previewMint(shares); + return assets + _feeOnRaw(assets, _entryFeeBasisPoints()); + } + + /// @dev Preview adding an exit fee on withdraw. See {IERC4626-previewWithdraw}. + function previewWithdraw(uint256 assets) public view virtual override returns (uint256) { + uint256 fee = _feeOnRaw(assets, _exitFeeBasisPoints()); + return super.previewWithdraw(assets + fee); + } + + /// @dev Preview taking an exit fee on redeem. See {IERC4626-previewRedeem}. + function previewRedeem(uint256 shares) public view virtual override returns (uint256) { + uint256 assets = super.previewRedeem(shares); + return assets - _feeOnTotal(assets, _exitFeeBasisPoints()); + } + + /// @dev Send entry fee to {_entryFeeRecipient}. See {IERC4626-_deposit}. + function _deposit(address caller, address receiver, uint256 assets, uint256 shares) internal virtual override { + uint256 fee = _feeOnTotal(assets, _entryFeeBasisPoints()); + address recipient = _entryFeeRecipient(); + + super._deposit(caller, receiver, assets, shares); + + if (fee > 0 && recipient != address(this)) { + SafeERC20.safeTransfer(IERC20(asset()), recipient, fee); + } + } + + /// @dev Send exit fee to {_exitFeeRecipient}. See {IERC4626-_deposit}. + function _withdraw( + address caller, + address receiver, + address owner, + uint256 assets, + uint256 shares + ) internal virtual override { + uint256 fee = _feeOnRaw(assets, _exitFeeBasisPoints()); + address recipient = _exitFeeRecipient(); + + super._withdraw(caller, receiver, owner, assets, shares); + + if (fee > 0 && recipient != address(this)) { + SafeERC20.safeTransfer(IERC20(asset()), recipient, fee); + } + } + + // === Fee configuration === + + function _entryFeeBasisPoints() internal view virtual returns (uint256) { + return 0; // replace with e.g. 100 for 1% + } + + function _exitFeeBasisPoints() internal view virtual returns (uint256) { + return 0; // replace with e.g. 100 for 1% + } + + function _entryFeeRecipient() internal view virtual returns (address) { + return address(0); // replace with e.g. a treasury address + } + + function _exitFeeRecipient() internal view virtual returns (address) { + return address(0); // replace with e.g. a treasury address + } + + // === Fee operations === + + /// @dev Calculates the fees that should be added to an amount `assets` that does not already include fees. + /// Used in {IERC4626-mint} and {IERC4626-withdraw} operations. + function _feeOnRaw(uint256 assets, uint256 feeBasisPoints) private pure returns (uint256) { + return assets.mulDiv(feeBasisPoints, _BASIS_POINT_SCALE, Math.Rounding.Ceil); + } + + /// @dev Calculates the fee part of an amount `assets` that already includes fees. + /// Used in {IERC4626-deposit} and {IERC4626-redeem} operations. + function _feeOnTotal(uint256 assets, uint256 feeBasisPoints) private pure returns (uint256) { + return assets.mulDiv(feeBasisPoints, feeBasisPoints + _BASIS_POINT_SCALE, Math.Rounding.Ceil); + } +} diff --git a/contracts/mocks/docs/governance/MyGovernor.sol b/contracts/mocks/docs/governance/MyGovernor.sol new file mode 100644 index 000000000..d898fc715 --- /dev/null +++ b/contracts/mocks/docs/governance/MyGovernor.sol @@ -0,0 +1,81 @@ +// SPDX-License-Identifier: MIT +pragma solidity ^0.8.20; + +import {IGovernor, Governor} from "../../../governance/Governor.sol"; +import {GovernorCountingSimple} from "../../../governance/extensions/GovernorCountingSimple.sol"; +import {GovernorVotes} from "../../../governance/extensions/GovernorVotes.sol"; +import {GovernorVotesQuorumFraction} from "../../../governance/extensions/GovernorVotesQuorumFraction.sol"; +import {GovernorTimelockControl} from "../../../governance/extensions/GovernorTimelockControl.sol"; +import {TimelockController} from "../../../governance/TimelockController.sol"; +import {IVotes} from "../../../governance/utils/IVotes.sol"; +import {IERC165} from "../../../interfaces/IERC165.sol"; + +contract MyGovernor is + Governor, + GovernorCountingSimple, + GovernorVotes, + GovernorVotesQuorumFraction, + GovernorTimelockControl +{ + constructor( + IVotes _token, + TimelockController _timelock + ) Governor("MyGovernor") GovernorVotes(_token) GovernorVotesQuorumFraction(4) GovernorTimelockControl(_timelock) {} + + function votingDelay() public pure override returns (uint256) { + return 7200; // 1 day + } + + function votingPeriod() public pure override returns (uint256) { + return 50400; // 1 week + } + + function proposalThreshold() public pure override returns (uint256) { + return 0; + } + + // The functions below are overrides required by Solidity. + + function state(uint256 proposalId) public view override(Governor, GovernorTimelockControl) returns (ProposalState) { + return super.state(proposalId); + } + + function proposalNeedsQueuing( + uint256 proposalId + ) public view virtual override(Governor, GovernorTimelockControl) returns (bool) { + return super.proposalNeedsQueuing(proposalId); + } + + function _queueOperations( + uint256 proposalId, + address[] memory targets, + uint256[] memory values, + bytes[] memory calldatas, + bytes32 descriptionHash + ) internal override(Governor, GovernorTimelockControl) returns (uint48) { + return super._queueOperations(proposalId, targets, values, calldatas, descriptionHash); + } + + function _executeOperations( + uint256 proposalId, + address[] memory targets, + uint256[] memory values, + bytes[] memory calldatas, + bytes32 descriptionHash + ) internal override(Governor, GovernorTimelockControl) { + super._executeOperations(proposalId, targets, values, calldatas, descriptionHash); + } + + function _cancel( + address[] memory targets, + uint256[] memory values, + bytes[] memory calldatas, + bytes32 descriptionHash + ) internal override(Governor, GovernorTimelockControl) returns (uint256) { + return super._cancel(targets, values, calldatas, descriptionHash); + } + + function _executor() internal view override(Governor, GovernorTimelockControl) returns (address) { + return super._executor(); + } +} diff --git a/contracts/mocks/docs/governance/MyToken.sol b/contracts/mocks/docs/governance/MyToken.sol new file mode 100644 index 000000000..cfb167557 --- /dev/null +++ b/contracts/mocks/docs/governance/MyToken.sol @@ -0,0 +1,21 @@ +// SPDX-License-Identifier: MIT +pragma solidity ^0.8.20; + +import {ERC20} from "../../../token/ERC20/ERC20.sol"; +import {ERC20Permit} from "../../../token/ERC20/extensions/ERC20Permit.sol"; +import {ERC20Votes} from "../../../token/ERC20/extensions/ERC20Votes.sol"; +import {Nonces} from "../../../utils/Nonces.sol"; + +contract MyToken is ERC20, ERC20Permit, ERC20Votes { + constructor() ERC20("MyToken", "MTK") ERC20Permit("MyToken") {} + + // The functions below are overrides required by Solidity. + + function _update(address from, address to, uint256 amount) internal override(ERC20, ERC20Votes) { + super._update(from, to, amount); + } + + function nonces(address owner) public view virtual override(ERC20Permit, Nonces) returns (uint256) { + return super.nonces(owner); + } +} diff --git a/contracts/mocks/docs/governance/MyTokenTimestampBased.sol b/contracts/mocks/docs/governance/MyTokenTimestampBased.sol new file mode 100644 index 000000000..7c0d32956 --- /dev/null +++ b/contracts/mocks/docs/governance/MyTokenTimestampBased.sol @@ -0,0 +1,32 @@ +// SPDX-License-Identifier: MIT +pragma solidity ^0.8.20; + +import {ERC20} from "../../../token/ERC20/ERC20.sol"; +import {ERC20Permit} from "../../../token/ERC20/extensions/ERC20Permit.sol"; +import {ERC20Votes} from "../../../token/ERC20/extensions/ERC20Votes.sol"; +import {Nonces} from "../../../utils/Nonces.sol"; + +contract MyTokenTimestampBased is ERC20, ERC20Permit, ERC20Votes { + constructor() ERC20("MyTokenTimestampBased", "MTK") ERC20Permit("MyTokenTimestampBased") {} + + // Overrides IERC6372 functions to make the token & governor timestamp-based + + function clock() public view override returns (uint48) { + return uint48(block.timestamp); + } + + // solhint-disable-next-line func-name-mixedcase + function CLOCK_MODE() public pure override returns (string memory) { + return "mode=timestamp"; + } + + // The functions below are overrides required by Solidity. + + function _update(address from, address to, uint256 amount) internal override(ERC20, ERC20Votes) { + super._update(from, to, amount); + } + + function nonces(address owner) public view virtual override(ERC20Permit, Nonces) returns (uint256) { + return super.nonces(owner); + } +} diff --git a/contracts/mocks/docs/governance/MyTokenWrapped.sol b/contracts/mocks/docs/governance/MyTokenWrapped.sol new file mode 100644 index 000000000..c9d567dc5 --- /dev/null +++ b/contracts/mocks/docs/governance/MyTokenWrapped.sol @@ -0,0 +1,28 @@ +// SPDX-License-Identifier: MIT +pragma solidity ^0.8.20; + +import {IERC20, ERC20} from "../../../token/ERC20/ERC20.sol"; +import {ERC20Permit} from "../../../token/ERC20/extensions/ERC20Permit.sol"; +import {ERC20Votes} from "../../../token/ERC20/extensions/ERC20Votes.sol"; +import {ERC20Wrapper} from "../../../token/ERC20/extensions/ERC20Wrapper.sol"; +import {Nonces} from "../../../utils/Nonces.sol"; + +contract MyTokenWrapped is ERC20, ERC20Permit, ERC20Votes, ERC20Wrapper { + constructor( + IERC20 wrappedToken + ) ERC20("MyTokenWrapped", "MTK") ERC20Permit("MyTokenWrapped") ERC20Wrapper(wrappedToken) {} + + // The functions below are overrides required by Solidity. + + function decimals() public view override(ERC20, ERC20Wrapper) returns (uint8) { + return super.decimals(); + } + + function _update(address from, address to, uint256 amount) internal override(ERC20, ERC20Votes) { + super._update(from, to, amount); + } + + function nonces(address owner) public view virtual override(ERC20Permit, Nonces) returns (uint256) { + return super.nonces(owner); + } +} diff --git a/contracts/mocks/governance/GovernorMock.sol b/contracts/mocks/governance/GovernorMock.sol new file mode 100644 index 000000000..69668d285 --- /dev/null +++ b/contracts/mocks/governance/GovernorMock.sol @@ -0,0 +1,14 @@ +// SPDX-License-Identifier: MIT + +pragma solidity ^0.8.20; + +import {Governor} from "../../governance/Governor.sol"; +import {GovernorSettings} from "../../governance/extensions/GovernorSettings.sol"; +import {GovernorCountingSimple} from "../../governance/extensions/GovernorCountingSimple.sol"; +import {GovernorVotesQuorumFraction} from "../../governance/extensions/GovernorVotesQuorumFraction.sol"; + +abstract contract GovernorMock is GovernorSettings, GovernorVotesQuorumFraction, GovernorCountingSimple { + function proposalThreshold() public view override(Governor, GovernorSettings) returns (uint256) { + return super.proposalThreshold(); + } +} diff --git a/contracts/mocks/governance/GovernorPreventLateQuorumMock.sol b/contracts/mocks/governance/GovernorPreventLateQuorumMock.sol new file mode 100644 index 000000000..fde0863ce --- /dev/null +++ b/contracts/mocks/governance/GovernorPreventLateQuorumMock.sol @@ -0,0 +1,46 @@ +// SPDX-License-Identifier: MIT + +pragma solidity ^0.8.20; + +import {Governor} from "../../governance/Governor.sol"; +import {GovernorPreventLateQuorum} from "../../governance/extensions/GovernorPreventLateQuorum.sol"; +import {GovernorSettings} from "../../governance/extensions/GovernorSettings.sol"; +import {GovernorCountingSimple} from "../../governance/extensions/GovernorCountingSimple.sol"; +import {GovernorVotes} from "../../governance/extensions/GovernorVotes.sol"; + +abstract contract GovernorPreventLateQuorumMock is + GovernorSettings, + GovernorVotes, + GovernorCountingSimple, + GovernorPreventLateQuorum +{ + uint256 private _quorum; + + constructor(uint256 quorum_) { + _quorum = quorum_; + } + + function quorum(uint256) public view override returns (uint256) { + return _quorum; + } + + function proposalDeadline( + uint256 proposalId + ) public view override(Governor, GovernorPreventLateQuorum) returns (uint256) { + return super.proposalDeadline(proposalId); + } + + function proposalThreshold() public view override(Governor, GovernorSettings) returns (uint256) { + return super.proposalThreshold(); + } + + function _castVote( + uint256 proposalId, + address account, + uint8 support, + string memory reason, + bytes memory params + ) internal override(Governor, GovernorPreventLateQuorum) returns (uint256) { + return super._castVote(proposalId, account, support, reason, params); + } +} diff --git a/contracts/mocks/governance/GovernorStorageMock.sol b/contracts/mocks/governance/GovernorStorageMock.sol new file mode 100644 index 000000000..88c6bf906 --- /dev/null +++ b/contracts/mocks/governance/GovernorStorageMock.sol @@ -0,0 +1,79 @@ +// SPDX-License-Identifier: MIT + +pragma solidity ^0.8.19; + +import {IGovernor, Governor} from "../../governance/Governor.sol"; +import {GovernorTimelockControl} from "../../governance/extensions/GovernorTimelockControl.sol"; +import {GovernorSettings} from "../../governance/extensions/GovernorSettings.sol"; +import {GovernorCountingSimple} from "../../governance/extensions/GovernorCountingSimple.sol"; +import {GovernorVotesQuorumFraction} from "../../governance/extensions/GovernorVotesQuorumFraction.sol"; +import {GovernorStorage} from "../../governance/extensions/GovernorStorage.sol"; + +abstract contract GovernorStorageMock is + GovernorSettings, + GovernorTimelockControl, + GovernorVotesQuorumFraction, + GovernorCountingSimple, + GovernorStorage +{ + function quorum(uint256 blockNumber) public view override(Governor, GovernorVotesQuorumFraction) returns (uint256) { + return super.quorum(blockNumber); + } + + function state(uint256 proposalId) public view override(Governor, GovernorTimelockControl) returns (ProposalState) { + return super.state(proposalId); + } + + function proposalThreshold() public view override(Governor, GovernorSettings) returns (uint256) { + return super.proposalThreshold(); + } + + function proposalNeedsQueuing( + uint256 proposalId + ) public view virtual override(Governor, GovernorTimelockControl) returns (bool) { + return super.proposalNeedsQueuing(proposalId); + } + + function _propose( + address[] memory targets, + uint256[] memory values, + bytes[] memory calldatas, + string memory description, + address proposer + ) internal virtual override(Governor, GovernorStorage) returns (uint256) { + return super._propose(targets, values, calldatas, description, proposer); + } + + function _queueOperations( + uint256 proposalId, + address[] memory targets, + uint256[] memory values, + bytes[] memory calldatas, + bytes32 descriptionHash + ) internal override(Governor, GovernorTimelockControl) returns (uint48) { + return super._queueOperations(proposalId, targets, values, calldatas, descriptionHash); + } + + function _executeOperations( + uint256 proposalId, + address[] memory targets, + uint256[] memory values, + bytes[] memory calldatas, + bytes32 descriptionHash + ) internal override(Governor, GovernorTimelockControl) { + super._executeOperations(proposalId, targets, values, calldatas, descriptionHash); + } + + function _cancel( + address[] memory targets, + uint256[] memory values, + bytes[] memory calldatas, + bytes32 descriptionHash + ) internal override(Governor, GovernorTimelockControl) returns (uint256) { + return super._cancel(targets, values, calldatas, descriptionHash); + } + + function _executor() internal view override(Governor, GovernorTimelockControl) returns (address) { + return super._executor(); + } +} diff --git a/contracts/mocks/governance/GovernorTimelockAccessMock.sol b/contracts/mocks/governance/GovernorTimelockAccessMock.sol new file mode 100644 index 000000000..3d1bbeeef --- /dev/null +++ b/contracts/mocks/governance/GovernorTimelockAccessMock.sol @@ -0,0 +1,70 @@ +// SPDX-License-Identifier: MIT + +pragma solidity ^0.8.20; + +import {IGovernor, Governor} from "../../governance/Governor.sol"; +import {GovernorTimelockAccess} from "../../governance/extensions/GovernorTimelockAccess.sol"; +import {GovernorSettings} from "../../governance/extensions/GovernorSettings.sol"; +import {GovernorCountingSimple} from "../../governance/extensions/GovernorCountingSimple.sol"; +import {GovernorVotesQuorumFraction} from "../../governance/extensions/GovernorVotesQuorumFraction.sol"; + +abstract contract GovernorTimelockAccessMock is + GovernorSettings, + GovernorTimelockAccess, + GovernorVotesQuorumFraction, + GovernorCountingSimple +{ + function nonGovernanceFunction() external {} + + function quorum(uint256 blockNumber) public view override(Governor, GovernorVotesQuorumFraction) returns (uint256) { + return super.quorum(blockNumber); + } + + function proposalThreshold() public view override(Governor, GovernorSettings) returns (uint256) { + return super.proposalThreshold(); + } + + function proposalNeedsQueuing( + uint256 proposalId + ) public view virtual override(Governor, GovernorTimelockAccess) returns (bool) { + return super.proposalNeedsQueuing(proposalId); + } + + function propose( + address[] memory targets, + uint256[] memory values, + bytes[] memory calldatas, + string memory description + ) public override(Governor, GovernorTimelockAccess) returns (uint256) { + return super.propose(targets, values, calldatas, description); + } + + function _queueOperations( + uint256 proposalId, + address[] memory targets, + uint256[] memory values, + bytes[] memory calldatas, + bytes32 descriptionHash + ) internal override(Governor, GovernorTimelockAccess) returns (uint48) { + return super._queueOperations(proposalId, targets, values, calldatas, descriptionHash); + } + + function _executeOperations( + uint256 proposalId, + address[] memory targets, + uint256[] memory values, + bytes[] memory calldatas, + bytes32 descriptionHash + ) internal override(Governor, GovernorTimelockAccess) { + super._executeOperations(proposalId, targets, values, calldatas, descriptionHash); + } + + function _cancel( + address[] memory targets, + uint256[] memory values, + bytes[] memory calldatas, + bytes32 descriptionHash + ) internal override(Governor, GovernorTimelockAccess) returns (uint256) { + return super._cancel(targets, values, calldatas, descriptionHash); + } +} diff --git a/contracts/mocks/governance/GovernorTimelockCompoundMock.sol b/contracts/mocks/governance/GovernorTimelockCompoundMock.sol new file mode 100644 index 000000000..03ef62510 --- /dev/null +++ b/contracts/mocks/governance/GovernorTimelockCompoundMock.sol @@ -0,0 +1,69 @@ +// SPDX-License-Identifier: MIT + +pragma solidity ^0.8.20; + +import {IGovernor, Governor} from "../../governance/Governor.sol"; +import {GovernorTimelockCompound} from "../../governance/extensions/GovernorTimelockCompound.sol"; +import {GovernorSettings} from "../../governance/extensions/GovernorSettings.sol"; +import {GovernorCountingSimple} from "../../governance/extensions/GovernorCountingSimple.sol"; +import {GovernorVotesQuorumFraction} from "../../governance/extensions/GovernorVotesQuorumFraction.sol"; + +abstract contract GovernorTimelockCompoundMock is + GovernorSettings, + GovernorTimelockCompound, + GovernorVotesQuorumFraction, + GovernorCountingSimple +{ + function quorum(uint256 blockNumber) public view override(Governor, GovernorVotesQuorumFraction) returns (uint256) { + return super.quorum(blockNumber); + } + + function state( + uint256 proposalId + ) public view override(Governor, GovernorTimelockCompound) returns (ProposalState) { + return super.state(proposalId); + } + + function proposalThreshold() public view override(Governor, GovernorSettings) returns (uint256) { + return super.proposalThreshold(); + } + + function proposalNeedsQueuing( + uint256 proposalId + ) public view virtual override(Governor, GovernorTimelockCompound) returns (bool) { + return super.proposalNeedsQueuing(proposalId); + } + + function _queueOperations( + uint256 proposalId, + address[] memory targets, + uint256[] memory values, + bytes[] memory calldatas, + bytes32 descriptionHash + ) internal override(Governor, GovernorTimelockCompound) returns (uint48) { + return super._queueOperations(proposalId, targets, values, calldatas, descriptionHash); + } + + function _executeOperations( + uint256 proposalId, + address[] memory targets, + uint256[] memory values, + bytes[] memory calldatas, + bytes32 descriptionHash + ) internal override(Governor, GovernorTimelockCompound) { + super._executeOperations(proposalId, targets, values, calldatas, descriptionHash); + } + + function _cancel( + address[] memory targets, + uint256[] memory values, + bytes[] memory calldatas, + bytes32 descriptionHash + ) internal override(Governor, GovernorTimelockCompound) returns (uint256) { + return super._cancel(targets, values, calldatas, descriptionHash); + } + + function _executor() internal view override(Governor, GovernorTimelockCompound) returns (address) { + return super._executor(); + } +} diff --git a/contracts/mocks/governance/GovernorTimelockControlMock.sol b/contracts/mocks/governance/GovernorTimelockControlMock.sol new file mode 100644 index 000000000..edaccc0b7 --- /dev/null +++ b/contracts/mocks/governance/GovernorTimelockControlMock.sol @@ -0,0 +1,69 @@ +// SPDX-License-Identifier: MIT + +pragma solidity ^0.8.20; + +import {IGovernor, Governor} from "../../governance/Governor.sol"; +import {GovernorTimelockControl} from "../../governance/extensions/GovernorTimelockControl.sol"; +import {GovernorSettings} from "../../governance/extensions/GovernorSettings.sol"; +import {GovernorCountingSimple} from "../../governance/extensions/GovernorCountingSimple.sol"; +import {GovernorVotesQuorumFraction} from "../../governance/extensions/GovernorVotesQuorumFraction.sol"; + +abstract contract GovernorTimelockControlMock is + GovernorSettings, + GovernorTimelockControl, + GovernorVotesQuorumFraction, + GovernorCountingSimple +{ + function quorum(uint256 blockNumber) public view override(Governor, GovernorVotesQuorumFraction) returns (uint256) { + return super.quorum(blockNumber); + } + + function state(uint256 proposalId) public view override(Governor, GovernorTimelockControl) returns (ProposalState) { + return super.state(proposalId); + } + + function proposalThreshold() public view override(Governor, GovernorSettings) returns (uint256) { + return super.proposalThreshold(); + } + + function proposalNeedsQueuing( + uint256 proposalId + ) public view virtual override(Governor, GovernorTimelockControl) returns (bool) { + return super.proposalNeedsQueuing(proposalId); + } + + function _queueOperations( + uint256 proposalId, + address[] memory targets, + uint256[] memory values, + bytes[] memory calldatas, + bytes32 descriptionHash + ) internal override(Governor, GovernorTimelockControl) returns (uint48) { + return super._queueOperations(proposalId, targets, values, calldatas, descriptionHash); + } + + function _executeOperations( + uint256 proposalId, + address[] memory targets, + uint256[] memory values, + bytes[] memory calldatas, + bytes32 descriptionHash + ) internal override(Governor, GovernorTimelockControl) { + super._executeOperations(proposalId, targets, values, calldatas, descriptionHash); + } + + function _cancel( + address[] memory targets, + uint256[] memory values, + bytes[] memory calldatas, + bytes32 descriptionHash + ) internal override(Governor, GovernorTimelockControl) returns (uint256) { + return super._cancel(targets, values, calldatas, descriptionHash); + } + + function _executor() internal view override(Governor, GovernorTimelockControl) returns (address) { + return super._executor(); + } + + function nonGovernanceFunction() external {} +} diff --git a/contracts/mocks/governance/GovernorVoteMock.sol b/contracts/mocks/governance/GovernorVoteMock.sol new file mode 100644 index 000000000..e6949b5b2 --- /dev/null +++ b/contracts/mocks/governance/GovernorVoteMock.sol @@ -0,0 +1,20 @@ +// SPDX-License-Identifier: MIT + +pragma solidity ^0.8.20; + +import {GovernorCountingSimple} from "../../governance/extensions/GovernorCountingSimple.sol"; +import {GovernorVotes} from "../../governance/extensions/GovernorVotes.sol"; + +abstract contract GovernorVoteMocks is GovernorVotes, GovernorCountingSimple { + function quorum(uint256) public pure override returns (uint256) { + return 0; + } + + function votingDelay() public pure override returns (uint256) { + return 4; + } + + function votingPeriod() public pure override returns (uint256) { + return 16; + } +} diff --git a/contracts/mocks/governance/GovernorWithParamsMock.sol b/contracts/mocks/governance/GovernorWithParamsMock.sol new file mode 100644 index 000000000..d535f811c --- /dev/null +++ b/contracts/mocks/governance/GovernorWithParamsMock.sol @@ -0,0 +1,51 @@ +// SPDX-License-Identifier: MIT + +pragma solidity ^0.8.20; + +import {Governor} from "../../governance/Governor.sol"; +import {GovernorCountingSimple} from "../../governance/extensions/GovernorCountingSimple.sol"; +import {GovernorVotes} from "../../governance/extensions/GovernorVotes.sol"; + +abstract contract GovernorWithParamsMock is GovernorVotes, GovernorCountingSimple { + event CountParams(uint256 uintParam, string strParam); + + function quorum(uint256) public pure override returns (uint256) { + return 0; + } + + function votingDelay() public pure override returns (uint256) { + return 4; + } + + function votingPeriod() public pure override returns (uint256) { + return 16; + } + + function _getVotes( + address account, + uint256 blockNumber, + bytes memory params + ) internal view override(Governor, GovernorVotes) returns (uint256) { + uint256 reduction = 0; + // If the user provides parameters, we reduce the voting weight by the amount of the integer param + if (params.length > 0) { + (reduction, ) = abi.decode(params, (uint256, string)); + } + // reverts on overflow + return super._getVotes(account, blockNumber, params) - reduction; + } + + function _countVote( + uint256 proposalId, + address account, + uint8 support, + uint256 weight, + bytes memory params + ) internal override(Governor, GovernorCountingSimple) { + if (params.length > 0) { + (uint256 _uintParam, string memory _strParam) = abi.decode(params, (uint256, string)); + emit CountParams(_uintParam, _strParam); + } + return super._countVote(proposalId, account, support, weight, params); + } +} diff --git a/contracts/mocks/proxy/BadBeacon.sol b/contracts/mocks/proxy/BadBeacon.sol new file mode 100644 index 000000000..f3153a843 --- /dev/null +++ b/contracts/mocks/proxy/BadBeacon.sol @@ -0,0 +1,11 @@ +// SPDX-License-Identifier: MIT + +pragma solidity ^0.8.20; + +contract BadBeaconNoImpl {} + +contract BadBeaconNotContract { + function implementation() external pure returns (address) { + return address(0x1); + } +} diff --git a/contracts/mocks/proxy/ClashingImplementation.sol b/contracts/mocks/proxy/ClashingImplementation.sol new file mode 100644 index 000000000..43d5a34f2 --- /dev/null +++ b/contracts/mocks/proxy/ClashingImplementation.sol @@ -0,0 +1,19 @@ +// SPDX-License-Identifier: MIT + +pragma solidity ^0.8.20; + +/** + * @dev Implementation contract with a payable changeAdmin(address) function made to clash with + * TransparentUpgradeableProxy's to test correct functioning of the Transparent Proxy feature. + */ +contract ClashingImplementation { + event ClashingImplementationCall(); + + function upgradeToAndCall(address, bytes calldata) external payable { + emit ClashingImplementationCall(); + } + + function delegatedFunction() external pure returns (bool) { + return true; + } +} diff --git a/contracts/mocks/proxy/UUPSUpgradeableMock.sol b/contracts/mocks/proxy/UUPSUpgradeableMock.sol new file mode 100644 index 000000000..a5f2d4a25 --- /dev/null +++ b/contracts/mocks/proxy/UUPSUpgradeableMock.sol @@ -0,0 +1,35 @@ +// SPDX-License-Identifier: MIT + +pragma solidity ^0.8.20; + +import {UUPSUpgradeable} from "../../proxy/utils/UUPSUpgradeable.sol"; +import {ERC1967Utils} from "../../proxy/ERC1967/ERC1967Utils.sol"; + +contract NonUpgradeableMock { + uint256 internal _counter; + + function current() external view returns (uint256) { + return _counter; + } + + function increment() external { + ++_counter; + } +} + +contract UUPSUpgradeableMock is NonUpgradeableMock, UUPSUpgradeable { + // Not having any checks in this function is dangerous! Do not do this outside tests! + function _authorizeUpgrade(address) internal override {} +} + +contract UUPSUpgradeableUnsafeMock is UUPSUpgradeableMock { + function upgradeToAndCall(address newImplementation, bytes memory data) public payable override { + ERC1967Utils.upgradeToAndCall(newImplementation, data); + } +} + +contract UUPSUnsupportedProxiableUUID is UUPSUpgradeableMock { + function proxiableUUID() external pure override returns (bytes32) { + return keccak256("invalid UUID"); + } +} diff --git a/contracts/mocks/token/ERC1155ReceiverMock.sol b/contracts/mocks/token/ERC1155ReceiverMock.sol new file mode 100644 index 000000000..2a85d1dfa --- /dev/null +++ b/contracts/mocks/token/ERC1155ReceiverMock.sol @@ -0,0 +1,74 @@ +// SPDX-License-Identifier: MIT + +pragma solidity ^0.8.20; + +import {IERC1155Receiver} from "../../token/ERC1155/IERC1155Receiver.sol"; +import {ERC165} from "../../utils/introspection/ERC165.sol"; + +contract ERC1155ReceiverMock is ERC165, IERC1155Receiver { + enum RevertType { + None, + RevertWithoutMessage, + RevertWithMessage, + RevertWithCustomError, + Panic + } + + bytes4 private immutable _recRetval; + bytes4 private immutable _batRetval; + RevertType private immutable _error; + + event Received(address operator, address from, uint256 id, uint256 value, bytes data, uint256 gas); + event BatchReceived(address operator, address from, uint256[] ids, uint256[] values, bytes data, uint256 gas); + error CustomError(bytes4); + + constructor(bytes4 recRetval, bytes4 batRetval, RevertType error) { + _recRetval = recRetval; + _batRetval = batRetval; + _error = error; + } + + function onERC1155Received( + address operator, + address from, + uint256 id, + uint256 value, + bytes calldata data + ) external returns (bytes4) { + if (_error == RevertType.RevertWithoutMessage) { + revert(); + } else if (_error == RevertType.RevertWithMessage) { + revert("ERC1155ReceiverMock: reverting on receive"); + } else if (_error == RevertType.RevertWithCustomError) { + revert CustomError(_recRetval); + } else if (_error == RevertType.Panic) { + uint256 a = uint256(0) / uint256(0); + a; + } + + emit Received(operator, from, id, value, data, gasleft()); + return _recRetval; + } + + function onERC1155BatchReceived( + address operator, + address from, + uint256[] calldata ids, + uint256[] calldata values, + bytes calldata data + ) external returns (bytes4) { + if (_error == RevertType.RevertWithoutMessage) { + revert(); + } else if (_error == RevertType.RevertWithMessage) { + revert("ERC1155ReceiverMock: reverting on batch receive"); + } else if (_error == RevertType.RevertWithCustomError) { + revert CustomError(_recRetval); + } else if (_error == RevertType.Panic) { + uint256 a = uint256(0) / uint256(0); + a; + } + + emit BatchReceived(operator, from, ids, values, data, gasleft()); + return _batRetval; + } +} diff --git a/contracts/mocks/token/ERC20ApprovalMock.sol b/contracts/mocks/token/ERC20ApprovalMock.sol new file mode 100644 index 000000000..ff33a36df --- /dev/null +++ b/contracts/mocks/token/ERC20ApprovalMock.sol @@ -0,0 +1,10 @@ +// SPDX-License-Identifier: MIT +pragma solidity ^0.8.20; + +import {ERC20} from "../../token/ERC20/ERC20.sol"; + +abstract contract ERC20ApprovalMock is ERC20 { + function _approve(address owner, address spender, uint256 amount, bool) internal virtual override { + super._approve(owner, spender, amount, true); + } +} diff --git a/contracts/mocks/token/ERC20DecimalsMock.sol b/contracts/mocks/token/ERC20DecimalsMock.sol new file mode 100644 index 000000000..a26e1f52b --- /dev/null +++ b/contracts/mocks/token/ERC20DecimalsMock.sol @@ -0,0 +1,17 @@ +// SPDX-License-Identifier: MIT + +pragma solidity ^0.8.20; + +import {ERC20} from "../../token/ERC20/ERC20.sol"; + +abstract contract ERC20DecimalsMock is ERC20 { + uint8 private immutable _decimals; + + constructor(uint8 decimals_) { + _decimals = decimals_; + } + + function decimals() public view override returns (uint8) { + return _decimals; + } +} diff --git a/contracts/mocks/token/ERC20ExcessDecimalsMock.sol b/contracts/mocks/token/ERC20ExcessDecimalsMock.sol new file mode 100644 index 000000000..4627efd37 --- /dev/null +++ b/contracts/mocks/token/ERC20ExcessDecimalsMock.sol @@ -0,0 +1,9 @@ +// SPDX-License-Identifier: MIT + +pragma solidity ^0.8.20; + +contract ERC20ExcessDecimalsMock { + function decimals() public pure returns (uint256) { + return type(uint256).max; + } +} diff --git a/contracts/mocks/token/ERC20FlashMintMock.sol b/contracts/mocks/token/ERC20FlashMintMock.sol new file mode 100644 index 000000000..508573c2b --- /dev/null +++ b/contracts/mocks/token/ERC20FlashMintMock.sol @@ -0,0 +1,26 @@ +// SPDX-License-Identifier: MIT + +pragma solidity ^0.8.20; + +import {ERC20FlashMint} from "../../token/ERC20/extensions/ERC20FlashMint.sol"; + +abstract contract ERC20FlashMintMock is ERC20FlashMint { + uint256 _flashFeeAmount; + address _flashFeeReceiverAddress; + + function setFlashFee(uint256 amount) public { + _flashFeeAmount = amount; + } + + function _flashFee(address, uint256) internal view override returns (uint256) { + return _flashFeeAmount; + } + + function setFlashFeeReceiver(address receiver) public { + _flashFeeReceiverAddress = receiver; + } + + function _flashFeeReceiver() internal view override returns (address) { + return _flashFeeReceiverAddress; + } +} diff --git a/contracts/mocks/token/ERC20ForceApproveMock.sol b/contracts/mocks/token/ERC20ForceApproveMock.sol new file mode 100644 index 000000000..9fbca9727 --- /dev/null +++ b/contracts/mocks/token/ERC20ForceApproveMock.sol @@ -0,0 +1,13 @@ +// SPDX-License-Identifier: MIT + +pragma solidity ^0.8.20; + +import {ERC20} from "../../token/ERC20/ERC20.sol"; + +// contract that replicate USDT (0xdac17f958d2ee523a2206206994597c13d831ec7) approval beavior +abstract contract ERC20ForceApproveMock is ERC20 { + function approve(address spender, uint256 amount) public virtual override returns (bool) { + require(amount == 0 || allowance(msg.sender, spender) == 0, "USDT approval failure"); + return super.approve(spender, amount); + } +} diff --git a/contracts/mocks/token/ERC20Mock.sol b/contracts/mocks/token/ERC20Mock.sol new file mode 100644 index 000000000..39ab12952 --- /dev/null +++ b/contracts/mocks/token/ERC20Mock.sol @@ -0,0 +1,16 @@ +// SPDX-License-Identifier: MIT +pragma solidity ^0.8.20; + +import {ERC20} from "../../token/ERC20/ERC20.sol"; + +contract ERC20Mock is ERC20 { + constructor() ERC20("ERC20Mock", "E20M") {} + + function mint(address account, uint256 amount) external { + _mint(account, amount); + } + + function burn(address account, uint256 amount) external { + _burn(account, amount); + } +} diff --git a/contracts/mocks/token/ERC20MulticallMock.sol b/contracts/mocks/token/ERC20MulticallMock.sol new file mode 100644 index 000000000..dce3e7056 --- /dev/null +++ b/contracts/mocks/token/ERC20MulticallMock.sol @@ -0,0 +1,8 @@ +// SPDX-License-Identifier: MIT + +pragma solidity ^0.8.20; + +import {ERC20} from "../../token/ERC20/ERC20.sol"; +import {Multicall} from "../../utils/Multicall.sol"; + +abstract contract ERC20MulticallMock is ERC20, Multicall {} diff --git a/contracts/mocks/token/ERC20NoReturnMock.sol b/contracts/mocks/token/ERC20NoReturnMock.sol new file mode 100644 index 000000000..2129537b5 --- /dev/null +++ b/contracts/mocks/token/ERC20NoReturnMock.sol @@ -0,0 +1,28 @@ +// SPDX-License-Identifier: MIT + +pragma solidity ^0.8.20; + +import {ERC20} from "../../token/ERC20/ERC20.sol"; + +abstract contract ERC20NoReturnMock is ERC20 { + function transfer(address to, uint256 amount) public override returns (bool) { + super.transfer(to, amount); + assembly { + return(0, 0) + } + } + + function transferFrom(address from, address to, uint256 amount) public override returns (bool) { + super.transferFrom(from, to, amount); + assembly { + return(0, 0) + } + } + + function approve(address spender, uint256 amount) public override returns (bool) { + super.approve(spender, amount); + assembly { + return(0, 0) + } + } +} diff --git a/contracts/mocks/token/ERC20Reentrant.sol b/contracts/mocks/token/ERC20Reentrant.sol new file mode 100644 index 000000000..813913f75 --- /dev/null +++ b/contracts/mocks/token/ERC20Reentrant.sol @@ -0,0 +1,39 @@ +// SPDX-License-Identifier: MIT +pragma solidity ^0.8.20; + +import {ERC20} from "../../token/ERC20/ERC20.sol"; +import {Address} from "../../utils/Address.sol"; + +contract ERC20Reentrant is ERC20("TEST", "TST") { + enum Type { + No, + Before, + After + } + + Type private _reenterType; + address private _reenterTarget; + bytes private _reenterData; + + function scheduleReenter(Type when, address target, bytes calldata data) external { + _reenterType = when; + _reenterTarget = target; + _reenterData = data; + } + + function functionCall(address target, bytes memory data) public returns (bytes memory) { + return Address.functionCall(target, data); + } + + function _update(address from, address to, uint256 amount) internal override { + if (_reenterType == Type.Before) { + _reenterType = Type.No; + functionCall(_reenterTarget, _reenterData); + } + super._update(from, to, amount); + if (_reenterType == Type.After) { + _reenterType = Type.No; + functionCall(_reenterTarget, _reenterData); + } + } +} diff --git a/contracts/mocks/token/ERC20ReturnFalseMock.sol b/contracts/mocks/token/ERC20ReturnFalseMock.sol new file mode 100644 index 000000000..94bff32f1 --- /dev/null +++ b/contracts/mocks/token/ERC20ReturnFalseMock.sol @@ -0,0 +1,19 @@ +// SPDX-License-Identifier: MIT + +pragma solidity ^0.8.20; + +import {ERC20} from "../../token/ERC20/ERC20.sol"; + +abstract contract ERC20ReturnFalseMock is ERC20 { + function transfer(address, uint256) public pure override returns (bool) { + return false; + } + + function transferFrom(address, address, uint256) public pure override returns (bool) { + return false; + } + + function approve(address, uint256) public pure override returns (bool) { + return false; + } +} diff --git a/contracts/mocks/token/ERC20VotesLegacyMock.sol b/contracts/mocks/token/ERC20VotesLegacyMock.sol new file mode 100644 index 000000000..3246fd42e --- /dev/null +++ b/contracts/mocks/token/ERC20VotesLegacyMock.sol @@ -0,0 +1,253 @@ +// SPDX-License-Identifier: MIT + +pragma solidity ^0.8.20; + +import {ERC20Permit} from "../../token/ERC20/extensions/ERC20Permit.sol"; +import {Math} from "../../utils/math/Math.sol"; +import {IVotes} from "../../governance/utils/IVotes.sol"; +import {SafeCast} from "../../utils/math/SafeCast.sol"; +import {ECDSA} from "../../utils/cryptography/ECDSA.sol"; + +/** + * @dev Copied from the master branch at commit 86de1e8b6c3fa6b4efa4a5435869d2521be0f5f5 + */ +abstract contract ERC20VotesLegacyMock is IVotes, ERC20Permit { + struct Checkpoint { + uint32 fromBlock; + uint224 votes; + } + + bytes32 private constant _DELEGATION_TYPEHASH = + keccak256("Delegation(address delegatee,uint256 nonce,uint256 expiry)"); + + mapping(address account => address) private _delegatee; + mapping(address delegatee => Checkpoint[]) private _checkpoints; + Checkpoint[] private _totalSupplyCheckpoints; + + /** + * @dev Get the `pos`-th checkpoint for `account`. + */ + function checkpoints(address account, uint32 pos) public view virtual returns (Checkpoint memory) { + return _checkpoints[account][pos]; + } + + /** + * @dev Get number of checkpoints for `account`. + */ + function numCheckpoints(address account) public view virtual returns (uint32) { + return SafeCast.toUint32(_checkpoints[account].length); + } + + /** + * @dev Get the address `account` is currently delegating to. + */ + function delegates(address account) public view virtual returns (address) { + return _delegatee[account]; + } + + /** + * @dev Gets the current votes balance for `account` + */ + function getVotes(address account) public view virtual returns (uint256) { + uint256 pos = _checkpoints[account].length; + unchecked { + return pos == 0 ? 0 : _checkpoints[account][pos - 1].votes; + } + } + + /** + * @dev Retrieve the number of votes for `account` at the end of `blockNumber`. + * + * Requirements: + * + * - `blockNumber` must have been already mined + */ + function getPastVotes(address account, uint256 blockNumber) public view virtual returns (uint256) { + require(blockNumber < block.number, "ERC20Votes: block not yet mined"); + return _checkpointsLookup(_checkpoints[account], blockNumber); + } + + /** + * @dev Retrieve the `totalSupply` at the end of `blockNumber`. Note, this value is the sum of all balances. + * It is NOT the sum of all the delegated votes! + * + * Requirements: + * + * - `blockNumber` must have been already mined + */ + function getPastTotalSupply(uint256 blockNumber) public view virtual returns (uint256) { + require(blockNumber < block.number, "ERC20Votes: block not yet mined"); + return _checkpointsLookup(_totalSupplyCheckpoints, blockNumber); + } + + /** + * @dev Lookup a value in a list of (sorted) checkpoints. + */ + function _checkpointsLookup(Checkpoint[] storage ckpts, uint256 blockNumber) private view returns (uint256) { + // We run a binary search to look for the earliest checkpoint taken after `blockNumber`. + // + // Initially we check if the block is recent to narrow the search range. + // During the loop, the index of the wanted checkpoint remains in the range [low-1, high). + // With each iteration, either `low` or `high` is moved towards the middle of the range to maintain the + // invariant. + // - If the middle checkpoint is after `blockNumber`, we look in [low, mid) + // - If the middle checkpoint is before or equal to `blockNumber`, we look in [mid+1, high) + // Once we reach a single value (when low == high), we've found the right checkpoint at the index high-1, if not + // out of bounds (in which case we're looking too far in the past and the result is 0). + // Note that if the latest checkpoint available is exactly for `blockNumber`, we end up with an index that is + // past the end of the array, so we technically don't find a checkpoint after `blockNumber`, but it works out + // the same. + uint256 length = ckpts.length; + + uint256 low = 0; + uint256 high = length; + + if (length > 5) { + uint256 mid = length - Math.sqrt(length); + if (_unsafeAccess(ckpts, mid).fromBlock > blockNumber) { + high = mid; + } else { + low = mid + 1; + } + } + + while (low < high) { + uint256 mid = Math.average(low, high); + if (_unsafeAccess(ckpts, mid).fromBlock > blockNumber) { + high = mid; + } else { + low = mid + 1; + } + } + + unchecked { + return high == 0 ? 0 : _unsafeAccess(ckpts, high - 1).votes; + } + } + + /** + * @dev Delegate votes from the sender to `delegatee`. + */ + function delegate(address delegatee) public virtual { + _delegate(_msgSender(), delegatee); + } + + /** + * @dev Delegates votes from signer to `delegatee` + */ + function delegateBySig( + address delegatee, + uint256 nonce, + uint256 expiry, + uint8 v, + bytes32 r, + bytes32 s + ) public virtual { + require(block.timestamp <= expiry, "ERC20Votes: signature expired"); + address signer = ECDSA.recover( + _hashTypedDataV4(keccak256(abi.encode(_DELEGATION_TYPEHASH, delegatee, nonce, expiry))), + v, + r, + s + ); + require(nonce == _useNonce(signer), "ERC20Votes: invalid nonce"); + _delegate(signer, delegatee); + } + + /** + * @dev Maximum token supply. Defaults to `type(uint224).max` (2^224^ - 1). + */ + function _maxSupply() internal view virtual returns (uint224) { + return type(uint224).max; + } + + /** + * @dev Move voting power when tokens are transferred. + * + * Emits a {IVotes-DelegateVotesChanged} event. + */ + function _update(address from, address to, uint256 amount) internal virtual override { + super._update(from, to, amount); + + if (from == address(0)) { + require(totalSupply() <= _maxSupply(), "ERC20Votes: total supply risks overflowing votes"); + _writeCheckpoint(_totalSupplyCheckpoints, _add, amount); + } + + if (to == address(0)) { + _writeCheckpoint(_totalSupplyCheckpoints, _subtract, amount); + } + + _moveVotingPower(delegates(from), delegates(to), amount); + } + + /** + * @dev Change delegation for `delegator` to `delegatee`. + * + * Emits events {IVotes-DelegateChanged} and {IVotes-DelegateVotesChanged}. + */ + function _delegate(address delegator, address delegatee) internal virtual { + address currentDelegate = delegates(delegator); + uint256 delegatorBalance = balanceOf(delegator); + _delegatee[delegator] = delegatee; + + emit DelegateChanged(delegator, currentDelegate, delegatee); + + _moveVotingPower(currentDelegate, delegatee, delegatorBalance); + } + + function _moveVotingPower(address src, address dst, uint256 amount) private { + if (src != dst && amount > 0) { + if (src != address(0)) { + (uint256 oldWeight, uint256 newWeight) = _writeCheckpoint(_checkpoints[src], _subtract, amount); + emit DelegateVotesChanged(src, oldWeight, newWeight); + } + + if (dst != address(0)) { + (uint256 oldWeight, uint256 newWeight) = _writeCheckpoint(_checkpoints[dst], _add, amount); + emit DelegateVotesChanged(dst, oldWeight, newWeight); + } + } + } + + function _writeCheckpoint( + Checkpoint[] storage ckpts, + function(uint256, uint256) view returns (uint256) op, + uint256 delta + ) private returns (uint256 oldWeight, uint256 newWeight) { + uint256 pos = ckpts.length; + + unchecked { + Checkpoint memory oldCkpt = pos == 0 ? Checkpoint(0, 0) : _unsafeAccess(ckpts, pos - 1); + + oldWeight = oldCkpt.votes; + newWeight = op(oldWeight, delta); + + if (pos > 0 && oldCkpt.fromBlock == block.number) { + _unsafeAccess(ckpts, pos - 1).votes = SafeCast.toUint224(newWeight); + } else { + ckpts.push( + Checkpoint({fromBlock: SafeCast.toUint32(block.number), votes: SafeCast.toUint224(newWeight)}) + ); + } + } + } + + function _add(uint256 a, uint256 b) private pure returns (uint256) { + return a + b; + } + + function _subtract(uint256 a, uint256 b) private pure returns (uint256) { + return a - b; + } + + /** + * @dev Access an element of the array without performing bounds check. The position is assumed to be within bounds. + */ + function _unsafeAccess(Checkpoint[] storage ckpts, uint256 pos) private pure returns (Checkpoint storage result) { + assembly { + mstore(0, ckpts.slot) + result.slot := add(keccak256(0, 0x20), pos) + } + } +} diff --git a/contracts/mocks/token/ERC4626LimitsMock.sol b/contracts/mocks/token/ERC4626LimitsMock.sol new file mode 100644 index 000000000..a845365af --- /dev/null +++ b/contracts/mocks/token/ERC4626LimitsMock.sol @@ -0,0 +1,23 @@ +// SPDX-License-Identifier: MIT + +pragma solidity ^0.8.20; + +import {ERC4626} from "../../token/ERC20/extensions/ERC4626.sol"; + +abstract contract ERC4626LimitsMock is ERC4626 { + uint256 _maxDeposit; + uint256 _maxMint; + + constructor() { + _maxDeposit = 100 ether; + _maxMint = 100 ether; + } + + function maxDeposit(address) public view override returns (uint256) { + return _maxDeposit; + } + + function maxMint(address) public view override returns (uint256) { + return _maxMint; + } +} diff --git a/contracts/mocks/token/ERC4626Mock.sol b/contracts/mocks/token/ERC4626Mock.sol new file mode 100644 index 000000000..22ac5e8c7 --- /dev/null +++ b/contracts/mocks/token/ERC4626Mock.sol @@ -0,0 +1,17 @@ +// SPDX-License-Identifier: MIT +pragma solidity ^0.8.20; + +import {IERC20, ERC20} from "../../token/ERC20/ERC20.sol"; +import {ERC4626} from "../../token/ERC20/extensions/ERC4626.sol"; + +contract ERC4626Mock is ERC4626 { + constructor(address underlying) ERC20("ERC4626Mock", "E4626M") ERC4626(IERC20(underlying)) {} + + function mint(address account, uint256 amount) external { + _mint(account, amount); + } + + function burn(address account, uint256 amount) external { + _burn(account, amount); + } +} diff --git a/contracts/mocks/token/ERC4626OffsetMock.sol b/contracts/mocks/token/ERC4626OffsetMock.sol new file mode 100644 index 000000000..3dde0952c --- /dev/null +++ b/contracts/mocks/token/ERC4626OffsetMock.sol @@ -0,0 +1,17 @@ +// SPDX-License-Identifier: MIT + +pragma solidity ^0.8.20; + +import {ERC4626} from "../../token/ERC20/extensions/ERC4626.sol"; + +abstract contract ERC4626OffsetMock is ERC4626 { + uint8 private immutable _offset; + + constructor(uint8 offset_) { + _offset = offset_; + } + + function _decimalsOffset() internal view virtual override returns (uint8) { + return _offset; + } +} diff --git a/contracts/mocks/token/ERC4646FeesMock.sol b/contracts/mocks/token/ERC4646FeesMock.sol new file mode 100644 index 000000000..368b078ec --- /dev/null +++ b/contracts/mocks/token/ERC4646FeesMock.sol @@ -0,0 +1,40 @@ +// SPDX-License-Identifier: MIT + +pragma solidity ^0.8.20; + +import {ERC4626Fees} from "../docs/ERC4626Fees.sol"; + +abstract contract ERC4626FeesMock is ERC4626Fees { + uint256 private immutable _entryFeeBasisPointValue; + address private immutable _entryFeeRecipientValue; + uint256 private immutable _exitFeeBasisPointValue; + address private immutable _exitFeeRecipientValue; + + constructor( + uint256 entryFeeBasisPoints, + address entryFeeRecipient, + uint256 exitFeeBasisPoints, + address exitFeeRecipient + ) { + _entryFeeBasisPointValue = entryFeeBasisPoints; + _entryFeeRecipientValue = entryFeeRecipient; + _exitFeeBasisPointValue = exitFeeBasisPoints; + _exitFeeRecipientValue = exitFeeRecipient; + } + + function _entryFeeBasisPoints() internal view virtual override returns (uint256) { + return _entryFeeBasisPointValue; + } + + function _entryFeeRecipient() internal view virtual override returns (address) { + return _entryFeeRecipientValue; + } + + function _exitFeeBasisPoints() internal view virtual override returns (uint256) { + return _exitFeeBasisPointValue; + } + + function _exitFeeRecipient() internal view virtual override returns (address) { + return _exitFeeRecipientValue; + } +} diff --git a/contracts/mocks/token/ERC721ConsecutiveEnumerableMock.sol b/contracts/mocks/token/ERC721ConsecutiveEnumerableMock.sol new file mode 100644 index 000000000..7732ae4a5 --- /dev/null +++ b/contracts/mocks/token/ERC721ConsecutiveEnumerableMock.sol @@ -0,0 +1,42 @@ +// SPDX-License-Identifier: MIT + +pragma solidity ^0.8.20; + +import {ERC721} from "../../token/ERC721/ERC721.sol"; +import {ERC721Consecutive} from "../../token/ERC721/extensions/ERC721Consecutive.sol"; +import {ERC721Enumerable} from "../../token/ERC721/extensions/ERC721Enumerable.sol"; + +contract ERC721ConsecutiveEnumerableMock is ERC721Consecutive, ERC721Enumerable { + constructor( + string memory name, + string memory symbol, + address[] memory receivers, + uint96[] memory amounts + ) ERC721(name, symbol) { + for (uint256 i = 0; i < receivers.length; ++i) { + _mintConsecutive(receivers[i], amounts[i]); + } + } + + function supportsInterface( + bytes4 interfaceId + ) public view virtual override(ERC721, ERC721Enumerable) returns (bool) { + return super.supportsInterface(interfaceId); + } + + function _ownerOf(uint256 tokenId) internal view virtual override(ERC721, ERC721Consecutive) returns (address) { + return super._ownerOf(tokenId); + } + + function _update( + address to, + uint256 tokenId, + address auth + ) internal virtual override(ERC721Consecutive, ERC721Enumerable) returns (address) { + return super._update(to, tokenId, auth); + } + + function _increaseBalance(address account, uint128 amount) internal virtual override(ERC721, ERC721Enumerable) { + super._increaseBalance(account, amount); + } +} diff --git a/contracts/mocks/token/ERC721ConsecutiveMock.sol b/contracts/mocks/token/ERC721ConsecutiveMock.sol new file mode 100644 index 000000000..109864718 --- /dev/null +++ b/contracts/mocks/token/ERC721ConsecutiveMock.sol @@ -0,0 +1,61 @@ +// SPDX-License-Identifier: MIT + +pragma solidity ^0.8.20; + +import {ERC721} from "../../token/ERC721/ERC721.sol"; +import {ERC721Consecutive} from "../../token/ERC721/extensions/ERC721Consecutive.sol"; +import {ERC721Pausable} from "../../token/ERC721/extensions/ERC721Pausable.sol"; +import {ERC721Votes} from "../../token/ERC721/extensions/ERC721Votes.sol"; +import {EIP712} from "../../utils/cryptography/EIP712.sol"; + +/** + * @title ERC721ConsecutiveMock + */ +contract ERC721ConsecutiveMock is ERC721Consecutive, ERC721Pausable, ERC721Votes { + uint96 private immutable _offset; + + constructor( + string memory name, + string memory symbol, + uint96 offset, + address[] memory delegates, + address[] memory receivers, + uint96[] memory amounts + ) ERC721(name, symbol) EIP712(name, "1") { + _offset = offset; + + for (uint256 i = 0; i < delegates.length; ++i) { + _delegate(delegates[i], delegates[i]); + } + + for (uint256 i = 0; i < receivers.length; ++i) { + _mintConsecutive(receivers[i], amounts[i]); + } + } + + function _firstConsecutiveId() internal view virtual override returns (uint96) { + return _offset; + } + + function _ownerOf(uint256 tokenId) internal view virtual override(ERC721, ERC721Consecutive) returns (address) { + return super._ownerOf(tokenId); + } + + function _update( + address to, + uint256 tokenId, + address auth + ) internal virtual override(ERC721Consecutive, ERC721Pausable, ERC721Votes) returns (address) { + return super._update(to, tokenId, auth); + } + + function _increaseBalance(address account, uint128 amount) internal virtual override(ERC721, ERC721Votes) { + super._increaseBalance(account, amount); + } +} + +contract ERC721ConsecutiveNoConstructorMintMock is ERC721Consecutive { + constructor(string memory name, string memory symbol) ERC721(name, symbol) { + _mint(msg.sender, 0); + } +} diff --git a/contracts/mocks/token/ERC721ReceiverMock.sol b/contracts/mocks/token/ERC721ReceiverMock.sol new file mode 100644 index 000000000..14120f5d1 --- /dev/null +++ b/contracts/mocks/token/ERC721ReceiverMock.sol @@ -0,0 +1,47 @@ +// SPDX-License-Identifier: MIT + +pragma solidity ^0.8.20; + +import {IERC721Receiver} from "../../token/ERC721/IERC721Receiver.sol"; + +contract ERC721ReceiverMock is IERC721Receiver { + enum RevertType { + None, + RevertWithoutMessage, + RevertWithMessage, + RevertWithCustomError, + Panic + } + + bytes4 private immutable _retval; + RevertType private immutable _error; + + event Received(address operator, address from, uint256 tokenId, bytes data, uint256 gas); + error CustomError(bytes4); + + constructor(bytes4 retval, RevertType error) { + _retval = retval; + _error = error; + } + + function onERC721Received( + address operator, + address from, + uint256 tokenId, + bytes memory data + ) public returns (bytes4) { + if (_error == RevertType.RevertWithoutMessage) { + revert(); + } else if (_error == RevertType.RevertWithMessage) { + revert("ERC721ReceiverMock: reverting"); + } else if (_error == RevertType.RevertWithCustomError) { + revert CustomError(_retval); + } else if (_error == RevertType.Panic) { + uint256 a = uint256(0) / uint256(0); + a; + } + + emit Received(operator, from, tokenId, data, gasleft()); + return _retval; + } +} diff --git a/contracts/mocks/token/ERC721URIStorageMock.sol b/contracts/mocks/token/ERC721URIStorageMock.sol new file mode 100644 index 000000000..254435e07 --- /dev/null +++ b/contracts/mocks/token/ERC721URIStorageMock.sol @@ -0,0 +1,17 @@ +// SPDX-License-Identifier: MIT + +pragma solidity ^0.8.20; + +import {ERC721URIStorage} from "../../token/ERC721/extensions/ERC721URIStorage.sol"; + +abstract contract ERC721URIStorageMock is ERC721URIStorage { + string private _baseTokenURI; + + function _baseURI() internal view virtual override returns (string memory) { + return _baseTokenURI; + } + + function setBaseURI(string calldata newBaseTokenURI) public { + _baseTokenURI = newBaseTokenURI; + } +} diff --git a/contracts/mocks/token/VotesTimestamp.sol b/contracts/mocks/token/VotesTimestamp.sol new file mode 100644 index 000000000..78fdfae9c --- /dev/null +++ b/contracts/mocks/token/VotesTimestamp.sol @@ -0,0 +1,29 @@ +// SPDX-License-Identifier: MIT + +pragma solidity ^0.8.20; + +import {ERC20Votes} from "../../token/ERC20/extensions/ERC20Votes.sol"; +import {ERC721Votes} from "../../token/ERC721/extensions/ERC721Votes.sol"; +import {SafeCast} from "../../utils/math/SafeCast.sol"; + +abstract contract ERC20VotesTimestampMock is ERC20Votes { + function clock() public view virtual override returns (uint48) { + return SafeCast.toUint48(block.timestamp); + } + + // solhint-disable-next-line func-name-mixedcase + function CLOCK_MODE() public view virtual override returns (string memory) { + return "mode=timestamp"; + } +} + +abstract contract ERC721VotesTimestampMock is ERC721Votes { + function clock() public view virtual override returns (uint48) { + return SafeCast.toUint48(block.timestamp); + } + + // solhint-disable-next-line func-name-mixedcase + function CLOCK_MODE() public view virtual override returns (string memory) { + return "mode=timestamp"; + } +} diff --git a/contracts/package.json b/contracts/package.json new file mode 100644 index 000000000..e2cd89d91 --- /dev/null +++ b/contracts/package.json @@ -0,0 +1,32 @@ +{ + "name": "@openzeppelin/contracts", + "description": "Secure Smart Contract library for Solidity", + "version": "5.0.0-rc.0", + "files": [ + "**/*.sol", + "/build/contracts/*.json", + "!/mocks/**/*" + ], + "scripts": { + "prepare": "bash ../scripts/prepare-contracts-package.sh", + "prepare-docs": "cd ..; npm run prepare-docs" + }, + "repository": { + "type": "git", + "url": "https://github.com/OpenZeppelin/openzeppelin-contracts.git" + }, + "keywords": [ + "solidity", + "ethereum", + "smart", + "contracts", + "security", + "zeppelin" + ], + "author": "OpenZeppelin Community ", + "license": "MIT", + "bugs": { + "url": "https://github.com/OpenZeppelin/openzeppelin-contracts/issues" + }, + "homepage": "https://openzeppelin.com/contracts/" +} diff --git a/contracts/proxy/Clones.sol b/contracts/proxy/Clones.sol new file mode 100644 index 000000000..1e35a55b7 --- /dev/null +++ b/contracts/proxy/Clones.sol @@ -0,0 +1,95 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (proxy/Clones.sol) + +pragma solidity ^0.8.20; + +/** + * @dev https://eips.ethereum.org/EIPS/eip-1167[EIP 1167] is a standard for + * deploying minimal proxy contracts, also known as "clones". + * + * > To simply and cheaply clone contract functionality in an immutable way, this standard specifies + * > a minimal bytecode implementation that delegates all calls to a known, fixed address. + * + * The library includes functions to deploy a proxy using either `create` (traditional deployment) or `create2` + * (salted deterministic deployment). It also includes functions to predict the addresses of clones deployed using the + * deterministic method. + */ +library Clones { + /** + * @dev A clone instance deployment failed. + */ + error ERC1167FailedCreateClone(); + + /** + * @dev Deploys and returns the address of a clone that mimics the behaviour of `implementation`. + * + * This function uses the create opcode, which should never revert. + */ + function clone(address implementation) internal returns (address instance) { + /// @solidity memory-safe-assembly + assembly { + // Cleans the upper 96 bits of the `implementation` word, then packs the first 3 bytes + // of the `implementation` address with the bytecode before the address. + mstore(0x00, or(shr(0xe8, shl(0x60, implementation)), 0x3d602d80600a3d3981f3363d3d373d3d3d363d73000000)) + // Packs the remaining 17 bytes of `implementation` with the bytecode after the address. + mstore(0x20, or(shl(0x78, implementation), 0x5af43d82803e903d91602b57fd5bf3)) + instance := create(0, 0x09, 0x37) + } + if (instance == address(0)) { + revert ERC1167FailedCreateClone(); + } + } + + /** + * @dev Deploys and returns the address of a clone that mimics the behaviour of `implementation`. + * + * This function uses the create2 opcode and a `salt` to deterministically deploy + * the clone. Using the same `implementation` and `salt` multiple time will revert, since + * the clones cannot be deployed twice at the same address. + */ + function cloneDeterministic(address implementation, bytes32 salt) internal returns (address instance) { + /// @solidity memory-safe-assembly + assembly { + // Cleans the upper 96 bits of the `implementation` word, then packs the first 3 bytes + // of the `implementation` address with the bytecode before the address. + mstore(0x00, or(shr(0xe8, shl(0x60, implementation)), 0x3d602d80600a3d3981f3363d3d373d3d3d363d73000000)) + // Packs the remaining 17 bytes of `implementation` with the bytecode after the address. + mstore(0x20, or(shl(0x78, implementation), 0x5af43d82803e903d91602b57fd5bf3)) + instance := create2(0, 0x09, 0x37, salt) + } + if (instance == address(0)) { + revert ERC1167FailedCreateClone(); + } + } + + /** + * @dev Computes the address of a clone deployed using {Clones-cloneDeterministic}. + */ + function predictDeterministicAddress( + address implementation, + bytes32 salt, + address deployer + ) internal pure returns (address predicted) { + /// @solidity memory-safe-assembly + assembly { + let ptr := mload(0x40) + mstore(add(ptr, 0x38), deployer) + mstore(add(ptr, 0x24), 0x5af43d82803e903d91602b57fd5bf3ff) + mstore(add(ptr, 0x14), implementation) + mstore(ptr, 0x3d602d80600a3d3981f3363d3d373d3d3d363d73) + mstore(add(ptr, 0x58), salt) + mstore(add(ptr, 0x78), keccak256(add(ptr, 0x0c), 0x37)) + predicted := keccak256(add(ptr, 0x43), 0x55) + } + } + + /** + * @dev Computes the address of a clone deployed using {Clones-cloneDeterministic}. + */ + function predictDeterministicAddress( + address implementation, + bytes32 salt + ) internal view returns (address predicted) { + return predictDeterministicAddress(implementation, salt, address(this)); + } +} diff --git a/contracts/proxy/ERC1967/ERC1967Proxy.sol b/contracts/proxy/ERC1967/ERC1967Proxy.sol new file mode 100644 index 000000000..0f49f5034 --- /dev/null +++ b/contracts/proxy/ERC1967/ERC1967Proxy.sol @@ -0,0 +1,40 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (proxy/ERC1967/ERC1967Proxy.sol) + +pragma solidity ^0.8.20; + +import {Proxy} from "../Proxy.sol"; +import {ERC1967Utils} from "./ERC1967Utils.sol"; + +/** + * @dev This contract implements an upgradeable proxy. It is upgradeable because calls are delegated to an + * implementation address that can be changed. This address is stored in storage in the location specified by + * https://eips.ethereum.org/EIPS/eip-1967[EIP1967], so that it doesn't conflict with the storage layout of the + * implementation behind the proxy. + */ +contract ERC1967Proxy is Proxy { + /** + * @dev Initializes the upgradeable proxy with an initial implementation specified by `implementation`. + * + * If `_data` is nonempty, it's used as data in a delegate call to `implementation`. This will typically be an + * encoded function call, and allows initializing the storage of the proxy like a Solidity constructor. + * + * Requirements: + * + * - If `data` is empty, `msg.value` must be zero. + */ + constructor(address implementation, bytes memory _data) payable { + ERC1967Utils.upgradeToAndCall(implementation, _data); + } + + /** + * @dev Returns the current implementation address. + * + * TIP: To get this value clients can read directly from the storage slot shown below (specified by EIP1967) using + * the https://eth.wiki/json-rpc/API#eth_getstorageat[`eth_getStorageAt`] RPC call. + * `0x360894a13ba1a3210667c828492db98dca3e2076cc3735a920a3ca505d382bbc` + */ + function _implementation() internal view virtual override returns (address) { + return ERC1967Utils.getImplementation(); + } +} diff --git a/contracts/proxy/ERC1967/ERC1967Utils.sol b/contracts/proxy/ERC1967/ERC1967Utils.sol new file mode 100644 index 000000000..e0689c672 --- /dev/null +++ b/contracts/proxy/ERC1967/ERC1967Utils.sol @@ -0,0 +1,193 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (proxy/ERC1967/ERC1967Utils.sol) + +pragma solidity ^0.8.20; + +import {IBeacon} from "../beacon/IBeacon.sol"; +import {Address} from "../../utils/Address.sol"; +import {StorageSlot} from "../../utils/StorageSlot.sol"; + +/** + * @dev This abstract contract provides getters and event emitting update functions for + * https://eips.ethereum.org/EIPS/eip-1967[EIP1967] slots. + */ +library ERC1967Utils { + // We re-declare ERC-1967 events here because they can't be used directly from IERC1967. + // This will be fixed in Solidity 0.8.21. At that point we should remove these events. + /** + * @dev Emitted when the implementation is upgraded. + */ + event Upgraded(address indexed implementation); + + /** + * @dev Emitted when the admin account has changed. + */ + event AdminChanged(address previousAdmin, address newAdmin); + + /** + * @dev Emitted when the beacon is changed. + */ + event BeaconUpgraded(address indexed beacon); + + /** + * @dev Storage slot with the address of the current implementation. + * This is the keccak-256 hash of "eip1967.proxy.implementation" subtracted by 1. + */ + // solhint-disable-next-line private-vars-leading-underscore + bytes32 internal constant IMPLEMENTATION_SLOT = 0x360894a13ba1a3210667c828492db98dca3e2076cc3735a920a3ca505d382bbc; + + /** + * @dev The `implementation` of the proxy is invalid. + */ + error ERC1967InvalidImplementation(address implementation); + + /** + * @dev The `admin` of the proxy is invalid. + */ + error ERC1967InvalidAdmin(address admin); + + /** + * @dev The `beacon` of the proxy is invalid. + */ + error ERC1967InvalidBeacon(address beacon); + + /** + * @dev An upgrade function sees `msg.value > 0` that may be lost. + */ + error ERC1967NonPayable(); + + /** + * @dev Returns the current implementation address. + */ + function getImplementation() internal view returns (address) { + return StorageSlot.getAddressSlot(IMPLEMENTATION_SLOT).value; + } + + /** + * @dev Stores a new address in the EIP1967 implementation slot. + */ + function _setImplementation(address newImplementation) private { + if (newImplementation.code.length == 0) { + revert ERC1967InvalidImplementation(newImplementation); + } + StorageSlot.getAddressSlot(IMPLEMENTATION_SLOT).value = newImplementation; + } + + /** + * @dev Performs implementation upgrade with additional setup call if data is nonempty. + * This function is payable only if the setup call is performed, otherwise `msg.value` is rejected + * to avoid stuck value in the contract. + * + * Emits an {IERC1967-Upgraded} event. + */ + function upgradeToAndCall(address newImplementation, bytes memory data) internal { + _setImplementation(newImplementation); + emit Upgraded(newImplementation); + + if (data.length > 0) { + Address.functionDelegateCall(newImplementation, data); + } else { + _checkNonPayable(); + } + } + + /** + * @dev Storage slot with the admin of the contract. + * This is the keccak-256 hash of "eip1967.proxy.admin" subtracted by 1. + */ + // solhint-disable-next-line private-vars-leading-underscore + bytes32 internal constant ADMIN_SLOT = 0xb53127684a568b3173ae13b9f8a6016e243e63b6e8ee1178d6a717850b5d6103; + + /** + * @dev Returns the current admin. + * + * TIP: To get this value clients can read directly from the storage slot shown below (specified by EIP1967) using + * the https://eth.wiki/json-rpc/API#eth_getstorageat[`eth_getStorageAt`] RPC call. + * `0xb53127684a568b3173ae13b9f8a6016e243e63b6e8ee1178d6a717850b5d6103` + */ + function getAdmin() internal view returns (address) { + return StorageSlot.getAddressSlot(ADMIN_SLOT).value; + } + + /** + * @dev Stores a new address in the EIP1967 admin slot. + */ + function _setAdmin(address newAdmin) private { + if (newAdmin == address(0)) { + revert ERC1967InvalidAdmin(address(0)); + } + StorageSlot.getAddressSlot(ADMIN_SLOT).value = newAdmin; + } + + /** + * @dev Changes the admin of the proxy. + * + * Emits an {IERC1967-AdminChanged} event. + */ + function changeAdmin(address newAdmin) internal { + emit AdminChanged(getAdmin(), newAdmin); + _setAdmin(newAdmin); + } + + /** + * @dev The storage slot of the UpgradeableBeacon contract which defines the implementation for this proxy. + * This is the keccak-256 hash of "eip1967.proxy.beacon" subtracted by 1. + */ + // solhint-disable-next-line private-vars-leading-underscore + bytes32 internal constant BEACON_SLOT = 0xa3f0ad74e5423aebfd80d3ef4346578335a9a72aeaee59ff6cb3582b35133d50; + + /** + * @dev Returns the current beacon. + */ + function getBeacon() internal view returns (address) { + return StorageSlot.getAddressSlot(BEACON_SLOT).value; + } + + /** + * @dev Stores a new beacon in the EIP1967 beacon slot. + */ + function _setBeacon(address newBeacon) private { + if (newBeacon.code.length == 0) { + revert ERC1967InvalidBeacon(newBeacon); + } + + StorageSlot.getAddressSlot(BEACON_SLOT).value = newBeacon; + + address beaconImplementation = IBeacon(newBeacon).implementation(); + if (beaconImplementation.code.length == 0) { + revert ERC1967InvalidImplementation(beaconImplementation); + } + } + + /** + * @dev Change the beacon and trigger a setup call if data is nonempty. + * This function is payable only if the setup call is performed, otherwise `msg.value` is rejected + * to avoid stuck value in the contract. + * + * Emits an {IERC1967-BeaconUpgraded} event. + * + * CAUTION: Invoking this function has no effect on an instance of {BeaconProxy} since v5, since + * it uses an immutable beacon without looking at the value of the ERC-1967 beacon slot for + * efficiency. + */ + function upgradeBeaconToAndCall(address newBeacon, bytes memory data) internal { + _setBeacon(newBeacon); + emit BeaconUpgraded(newBeacon); + + if (data.length > 0) { + Address.functionDelegateCall(IBeacon(newBeacon).implementation(), data); + } else { + _checkNonPayable(); + } + } + + /** + * @dev Reverts if `msg.value` is not zero. It can be used to avoid `msg.value` stuck in the contract + * if an upgrade doesn't perform an initialization call. + */ + function _checkNonPayable() private { + if (msg.value > 0) { + revert ERC1967NonPayable(); + } + } +} diff --git a/contracts/proxy/Proxy.sol b/contracts/proxy/Proxy.sol new file mode 100644 index 000000000..8a59ff348 --- /dev/null +++ b/contracts/proxy/Proxy.sol @@ -0,0 +1,69 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (proxy/Proxy.sol) + +pragma solidity ^0.8.20; + +/** + * @dev This abstract contract provides a fallback function that delegates all calls to another contract using the EVM + * instruction `delegatecall`. We refer to the second contract as the _implementation_ behind the proxy, and it has to + * be specified by overriding the virtual {_implementation} function. + * + * Additionally, delegation to the implementation can be triggered manually through the {_fallback} function, or to a + * different contract through the {_delegate} function. + * + * The success and return data of the delegated call will be returned back to the caller of the proxy. + */ +abstract contract Proxy { + /** + * @dev Delegates the current call to `implementation`. + * + * This function does not return to its internal call site, it will return directly to the external caller. + */ + function _delegate(address implementation) internal virtual { + assembly { + // Copy msg.data. We take full control of memory in this inline assembly + // block because it will not return to Solidity code. We overwrite the + // Solidity scratch pad at memory position 0. + calldatacopy(0, 0, calldatasize()) + + // Call the implementation. + // out and outsize are 0 because we don't know the size yet. + let result := delegatecall(gas(), implementation, 0, calldatasize(), 0, 0) + + // Copy the returned data. + returndatacopy(0, 0, returndatasize()) + + switch result + // delegatecall returns 0 on error. + case 0 { + revert(0, returndatasize()) + } + default { + return(0, returndatasize()) + } + } + } + + /** + * @dev This is a virtual function that should be overridden so it returns the address to which the fallback + * function and {_fallback} should delegate. + */ + function _implementation() internal view virtual returns (address); + + /** + * @dev Delegates the current call to the address returned by `_implementation()`. + * + * This function does not return to its internal call site, it will return directly to the external caller. + */ + function _fallback() internal virtual { + _delegate(_implementation()); + } + + /** + * @dev Fallback function that delegates calls to the address returned by `_implementation()`. Will run if no other + * function in the contract matches the call data. + */ + fallback() external payable virtual { + _fallback(); + } +} diff --git a/contracts/proxy/README.adoc b/contracts/proxy/README.adoc new file mode 100644 index 000000000..3c4a78d19 --- /dev/null +++ b/contracts/proxy/README.adoc @@ -0,0 +1,87 @@ += Proxies + +[.readme-notice] +NOTE: This document is better viewed at https://docs.openzeppelin.com/contracts/api/proxy + +This is a low-level set of contracts implementing different proxy patterns with and without upgradeability. For an in-depth overview of this pattern check out the xref:upgrades-plugins::proxies.adoc[Proxy Upgrade Pattern] page. + +Most of the proxies below are built on an abstract base contract. + +- {Proxy}: Abstract contract implementing the core delegation functionality. + +In order to avoid clashes with the storage variables of the implementation contract behind a proxy, we use https://eips.ethereum.org/EIPS/eip-1967[EIP1967] storage slots. + +- {ERC1967Utils}: Internal functions to get and set the storage slots defined in EIP1967. +- {ERC1967Proxy}: A proxy using EIP1967 storage slots. Not upgradeable by default. + +There are two alternative ways to add upgradeability to an ERC1967 proxy. Their differences are explained below in <>. + +- {TransparentUpgradeableProxy}: A proxy with a built-in immutable admin and upgrade interface. +- {UUPSUpgradeable}: An upgradeability mechanism to be included in the implementation contract. + +CAUTION: Using upgradeable proxies correctly and securely is a difficult task that requires deep knowledge of the proxy pattern, Solidity, and the EVM. Unless you want a lot of low level control, we recommend using the xref:upgrades-plugins::index.adoc[OpenZeppelin Upgrades Plugins] for Truffle and Hardhat. + +A different family of proxies are beacon proxies. This pattern, popularized by Dharma, allows multiple proxies to be upgraded to a different implementation in a single transaction. + +- {BeaconProxy}: A proxy that retrieves its implementation from a beacon contract. +- {UpgradeableBeacon}: A beacon contract with a built in admin that can upgrade the {BeaconProxy} pointing to it. + +In this pattern, the proxy contract doesn't hold the implementation address in storage like an ERC1967 proxy. Instead, the address is stored in a separate beacon contract. The `upgrade` operations are sent to the beacon instead of to the proxy contract, and all proxies that follow that beacon are automatically upgraded. + +Outside the realm of upgradeability, proxies can also be useful to make cheap contract clones, such as those created by an on-chain factory contract that creates many instances of the same contract. These instances are designed to be both cheap to deploy, and cheap to call. + +- {Clones}: A library that can deploy cheap minimal non-upgradeable proxies. + +[[transparent-vs-uups]] +== Transparent vs UUPS Proxies + +The original proxies included in OpenZeppelin followed the https://blog.openzeppelin.com/the-transparent-proxy-pattern/[Transparent Proxy Pattern]. While this pattern is still provided, our recommendation is now shifting towards UUPS proxies, which are both lightweight and versatile. The name UUPS comes from https://eips.ethereum.org/EIPS/eip-1822[EIP1822], which first documented the pattern. + +While both of these share the same interface for upgrades, in UUPS proxies the upgrade is handled by the implementation, and can eventually be removed. Transparent proxies, on the other hand, include the upgrade and admin logic in the proxy itself. This means {TransparentUpgradeableProxy} is more expensive to deploy than what is possible with UUPS proxies. + +UUPS proxies are implemented using an {ERC1967Proxy}. Note that this proxy is not by itself upgradeable. It is the role of the implementation to include, alongside the contract's logic, all the code necessary to update the implementation's address that is stored at a specific slot in the proxy's storage space. This is where the {UUPSUpgradeable} contract comes in. Inheriting from it (and overriding the {xref-UUPSUpgradeable-_authorizeUpgrade-address-}[`_authorizeUpgrade`] function with the relevant access control mechanism) will turn your contract into a UUPS compliant implementation. + +Note that since both proxies use the same storage slot for the implementation address, using a UUPS compliant implementation with a {TransparentUpgradeableProxy} might allow non-admins to perform upgrade operations. + +By default, the upgrade functionality included in {UUPSUpgradeable} contains a security mechanism that will prevent any upgrades to a non UUPS compliant implementation. This prevents upgrades to an implementation contract that wouldn't contain the necessary upgrade mechanism, as it would lock the upgradeability of the proxy forever. This security mechanism can be bypassed by either of: + +- Adding a flag mechanism in the implementation that will disable the upgrade function when triggered. +- Upgrading to an implementation that features an upgrade mechanism without the additional security check, and then upgrading again to another implementation without the upgrade mechanism. + +The current implementation of this security mechanism uses https://eips.ethereum.org/EIPS/eip-1822[EIP1822] to detect the storage slot used by the implementation. A previous implementation, now deprecated, relied on a rollback check. It is possible to upgrade from a contract using the old mechanism to a new one. The inverse is however not possible, as old implementations (before version 4.5) did not include the `ERC1822` interface. + +== Core + +{{Proxy}} + +== ERC1967 + +{{IERC1967}} + +{{ERC1967Proxy}} + +{{ERC1967Utils}} + +== Transparent Proxy + +{{TransparentUpgradeableProxy}} + +{{ProxyAdmin}} + +== Beacon + +{{BeaconProxy}} + +{{IBeacon}} + +{{UpgradeableBeacon}} + +== Minimal Clones + +{{Clones}} + +== Utils + +{{Initializable}} + +{{UUPSUpgradeable}} diff --git a/contracts/proxy/beacon/BeaconProxy.sol b/contracts/proxy/beacon/BeaconProxy.sol new file mode 100644 index 000000000..b9d7d0034 --- /dev/null +++ b/contracts/proxy/beacon/BeaconProxy.sol @@ -0,0 +1,57 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (proxy/beacon/BeaconProxy.sol) + +pragma solidity ^0.8.20; + +import {IBeacon} from "./IBeacon.sol"; +import {Proxy} from "../Proxy.sol"; +import {ERC1967Utils} from "../ERC1967/ERC1967Utils.sol"; + +/** + * @dev This contract implements a proxy that gets the implementation address for each call from an {UpgradeableBeacon}. + * + * The beacon address can only be set once during construction, and cannot be changed afterwards. It is stored in an + * immutable variable to avoid unnecessary storage reads, and also in the beacon storage slot specified by + * https://eips.ethereum.org/EIPS/eip-1967[EIP1967] so that it can be accessed externally. + * + * CAUTION: Since the beacon address can never be changed, you must ensure that you either control the beacon, or trust + * the beacon to not upgrade the implementation maliciously. + * + * IMPORTANT: Do not use the implementation logic to modify the beacon storage slot. Doing so would leave the proxy in + * an inconsistent state where the beacon storage slot does not match the beacon address. + */ +contract BeaconProxy is Proxy { + // An immutable address for the beacon to avoid unnecessary SLOADs before each delegate call. + address private immutable _beacon; + + /** + * @dev Initializes the proxy with `beacon`. + * + * If `data` is nonempty, it's used as data in a delegate call to the implementation returned by the beacon. This + * will typically be an encoded function call, and allows initializing the storage of the proxy like a Solidity + * constructor. + * + * Requirements: + * + * - `beacon` must be a contract with the interface {IBeacon}. + * - If `data` is empty, `msg.value` must be zero. + */ + constructor(address beacon, bytes memory data) payable { + ERC1967Utils.upgradeBeaconToAndCall(beacon, data); + _beacon = beacon; + } + + /** + * @dev Returns the current implementation address of the associated beacon. + */ + function _implementation() internal view virtual override returns (address) { + return IBeacon(_getBeacon()).implementation(); + } + + /** + * @dev Returns the beacon. + */ + function _getBeacon() internal view virtual returns (address) { + return _beacon; + } +} diff --git a/contracts/proxy/beacon/IBeacon.sol b/contracts/proxy/beacon/IBeacon.sol new file mode 100644 index 000000000..bdc38e124 --- /dev/null +++ b/contracts/proxy/beacon/IBeacon.sol @@ -0,0 +1,16 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (proxy/beacon/IBeacon.sol) + +pragma solidity ^0.8.20; + +/** + * @dev This is the interface that {BeaconProxy} expects of its beacon. + */ +interface IBeacon { + /** + * @dev Must return an address that can be used as a delegate call target. + * + * {UpgradeableBeacon} will check that this address is a contract. + */ + function implementation() external view returns (address); +} diff --git a/contracts/proxy/beacon/UpgradeableBeacon.sol b/contracts/proxy/beacon/UpgradeableBeacon.sol new file mode 100644 index 000000000..db3caf91f --- /dev/null +++ b/contracts/proxy/beacon/UpgradeableBeacon.sol @@ -0,0 +1,70 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (proxy/beacon/UpgradeableBeacon.sol) + +pragma solidity ^0.8.20; + +import {IBeacon} from "./IBeacon.sol"; +import {Ownable} from "../../access/Ownable.sol"; + +/** + * @dev This contract is used in conjunction with one or more instances of {BeaconProxy} to determine their + * implementation contract, which is where they will delegate all function calls. + * + * An owner is able to change the implementation the beacon points to, thus upgrading the proxies that use this beacon. + */ +contract UpgradeableBeacon is IBeacon, Ownable { + address private _implementation; + + /** + * @dev The `implementation` of the beacon is invalid. + */ + error BeaconInvalidImplementation(address implementation); + + /** + * @dev Emitted when the implementation returned by the beacon is changed. + */ + event Upgraded(address indexed implementation); + + /** + * @dev Sets the address of the initial implementation, and the initial owner who can upgrade the beacon. + */ + constructor(address implementation_, address initialOwner) Ownable(initialOwner) { + _setImplementation(implementation_); + } + + /** + * @dev Returns the current implementation address. + */ + function implementation() public view virtual returns (address) { + return _implementation; + } + + /** + * @dev Upgrades the beacon to a new implementation. + * + * Emits an {Upgraded} event. + * + * Requirements: + * + * - msg.sender must be the owner of the contract. + * - `newImplementation` must be a contract. + */ + function upgradeTo(address newImplementation) public virtual onlyOwner { + _setImplementation(newImplementation); + } + + /** + * @dev Sets the implementation contract address for this beacon + * + * Requirements: + * + * - `newImplementation` must be a contract. + */ + function _setImplementation(address newImplementation) private { + if (newImplementation.code.length == 0) { + revert BeaconInvalidImplementation(newImplementation); + } + _implementation = newImplementation; + emit Upgraded(newImplementation); + } +} diff --git a/contracts/proxy/transparent/ProxyAdmin.sol b/contracts/proxy/transparent/ProxyAdmin.sol new file mode 100644 index 000000000..e546293d0 --- /dev/null +++ b/contracts/proxy/transparent/ProxyAdmin.sol @@ -0,0 +1,45 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (proxy/transparent/ProxyAdmin.sol) + +pragma solidity ^0.8.20; + +import {ITransparentUpgradeableProxy} from "./TransparentUpgradeableProxy.sol"; +import {Ownable} from "../../access/Ownable.sol"; + +/** + * @dev This is an auxiliary contract meant to be assigned as the admin of a {TransparentUpgradeableProxy}. For an + * explanation of why you would want to use this see the documentation for {TransparentUpgradeableProxy}. + */ +contract ProxyAdmin is Ownable { + /** + * @dev The version of the upgrade interface of the contract. If this getter is missing, both `upgrade(address)` + * and `upgradeAndCall(address,bytes)` are present, and `upgradeTo` must be used if no function should be called, + * while `upgradeAndCall` will invoke the `receive` function if the second argument is the empty byte string. + * If the getter returns `"5.0.0"`, only `upgradeAndCall(address,bytes)` is present, and the second argument must + * be the empty byte string if no function should be called, making it impossible to invoke the `receive` function + * during an upgrade. + */ + string public constant UPGRADE_INTERFACE_VERSION = "5.0.0"; + + /** + * @dev Sets the initial owner who can perform upgrades. + */ + constructor(address initialOwner) Ownable(initialOwner) {} + + /** + * @dev Upgrades `proxy` to `implementation` and calls a function on the new implementation. + * See {TransparentUpgradeableProxy-_dispatchUpgradeToAndCall}. + * + * Requirements: + * + * - This contract must be the admin of `proxy`. + * - If `data` is empty, `msg.value` must be zero. + */ + function upgradeAndCall( + ITransparentUpgradeableProxy proxy, + address implementation, + bytes memory data + ) public payable virtual onlyOwner { + proxy.upgradeToAndCall{value: msg.value}(implementation, data); + } +} diff --git a/contracts/proxy/transparent/TransparentUpgradeableProxy.sol b/contracts/proxy/transparent/TransparentUpgradeableProxy.sol new file mode 100644 index 000000000..ba23a603f --- /dev/null +++ b/contracts/proxy/transparent/TransparentUpgradeableProxy.sol @@ -0,0 +1,116 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (proxy/transparent/TransparentUpgradeableProxy.sol) + +pragma solidity ^0.8.20; + +import {ERC1967Utils} from "../ERC1967/ERC1967Utils.sol"; +import {ERC1967Proxy} from "../ERC1967/ERC1967Proxy.sol"; +import {IERC1967} from "../../interfaces/IERC1967.sol"; +import {ProxyAdmin} from "./ProxyAdmin.sol"; + +/** + * @dev Interface for {TransparentUpgradeableProxy}. In order to implement transparency, {TransparentUpgradeableProxy} + * does not implement this interface directly, and its upgradeability mechanism is implemented by an internal dispatch + * mechanism. The compiler is unaware that these functions are implemented by {TransparentUpgradeableProxy} and will not + * include them in the ABI so this interface must be used to interact with it. + */ +interface ITransparentUpgradeableProxy is IERC1967 { + function upgradeToAndCall(address, bytes calldata) external payable; +} + +/** + * @dev This contract implements a proxy that is upgradeable through an associated {ProxyAdmin} instance. + * + * To avoid https://medium.com/nomic-labs-blog/malicious-backdoors-in-ethereum-proxies-62629adf3357[proxy selector + * clashing], which can potentially be used in an attack, this contract uses the + * https://blog.openzeppelin.com/the-transparent-proxy-pattern/[transparent proxy pattern]. This pattern implies two + * things that go hand in hand: + * + * 1. If any account other than the admin calls the proxy, the call will be forwarded to the implementation, even if + * that call matches the {ITransparentUpgradeableProxy-upgradeToAndCall} function exposed by the proxy itself. + * 2. If the admin calls the proxy, it can call the `upgradeToAndCall` function but any other call won't be forwarded to + * the implementation. If the admin tries to call a function on the implementation it will fail with an error indicating + * the proxy admin cannot fallback to the target implementation. + * + * These properties mean that the admin account can only be used for upgrading the proxy, so it's best if it's a + * dedicated account that is not used for anything else. This will avoid headaches due to sudden errors when trying to + * call a function from the proxy implementation. For this reason, the proxy deploys an instance of {ProxyAdmin} and + * allows upgrades only if they come through it. You should think of the `ProxyAdmin` instance as the administrative + * interface of the proxy, including the ability to change who can trigger upgrades by transferring ownership. + * + * NOTE: The real interface of this proxy is that defined in `ITransparentUpgradeableProxy`. This contract does not + * inherit from that interface, and instead `upgradeToAndCall` is implicitly implemented using a custom dispatch + * mechanism in `_fallback`. Consequently, the compiler will not produce an ABI for this contract. This is necessary to + * fully implement transparency without decoding reverts caused by selector clashes between the proxy and the + * implementation. + * + * NOTE: This proxy does not inherit from {Context} deliberately. The {ProxyAdmin} of this contract won't send a + * meta-transaction in any way, and any other meta-transaction setup should be made in the implementation contract. + * + * IMPORTANT: This contract avoids unnecessary storage reads by setting the admin only during construction as an + * immutable variable, preventing any changes thereafter. However, the admin slot defined in ERC-1967 can still be + * overwritten by the implementation logic pointed to by this proxy. In such cases, the contract may end up in an + * undesirable state where the admin slot is different from the actual admin. + * + * WARNING: It is not recommended to extend this contract to add additional external functions. If you do so, the + * compiler will not check that there are no selector conflicts, due to the note above. A selector clash between any new + * function and the functions declared in {ITransparentUpgradeableProxy} will be resolved in favor of the new one. This + * could render the `upgradeToAndCall` function inaccessible, preventing upgradeability and compromising transparency. + */ +contract TransparentUpgradeableProxy is ERC1967Proxy { + // An immutable address for the admin to avoid unnecessary SLOADs before each call + // at the expense of removing the ability to change the admin once it's set. + // This is acceptable if the admin is always a ProxyAdmin instance or similar contract + // with its own ability to transfer the permissions to another account. + address private immutable _admin; + + /** + * @dev The proxy caller is the current admin, and can't fallback to the proxy target. + */ + error ProxyDeniedAdminAccess(); + + /** + * @dev Initializes an upgradeable proxy managed by an instance of a {ProxyAdmin} with an `initialOwner`, + * backed by the implementation at `_logic`, and optionally initialized with `_data` as explained in + * {ERC1967Proxy-constructor}. + */ + constructor(address _logic, address initialOwner, bytes memory _data) payable ERC1967Proxy(_logic, _data) { + _admin = address(new ProxyAdmin(initialOwner)); + // Set the storage value and emit an event for ERC-1967 compatibility + ERC1967Utils.changeAdmin(_proxyAdmin()); + } + + /** + * @dev Returns the admin of this proxy. + */ + function _proxyAdmin() internal virtual returns (address) { + return _admin; + } + + /** + * @dev If caller is the admin process the call internally, otherwise transparently fallback to the proxy behavior. + */ + function _fallback() internal virtual override { + if (msg.sender == _proxyAdmin()) { + if (msg.sig != ITransparentUpgradeableProxy.upgradeToAndCall.selector) { + revert ProxyDeniedAdminAccess(); + } else { + _dispatchUpgradeToAndCall(); + } + } else { + super._fallback(); + } + } + + /** + * @dev Upgrade the implementation of the proxy. See {ERC1967Utils-upgradeToAndCall}. + * + * Requirements: + * + * - If `data` is empty, `msg.value` must be zero. + */ + function _dispatchUpgradeToAndCall() private { + (address newImplementation, bytes memory data) = abi.decode(msg.data[4:], (address, bytes)); + ERC1967Utils.upgradeToAndCall(newImplementation, data); + } +} diff --git a/contracts/proxy/utils/Initializable.sol b/contracts/proxy/utils/Initializable.sol new file mode 100644 index 000000000..955c264b4 --- /dev/null +++ b/contracts/proxy/utils/Initializable.sol @@ -0,0 +1,228 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (proxy/utils/Initializable.sol) + +pragma solidity ^0.8.20; + +/** + * @dev This is a base contract to aid in writing upgradeable contracts, or any kind of contract that will be deployed + * behind a proxy. Since proxied contracts do not make use of a constructor, it's common to move constructor logic to an + * external initializer function, usually called `initialize`. It then becomes necessary to protect this initializer + * function so it can only be called once. The {initializer} modifier provided by this contract will have this effect. + * + * The initialization functions use a version number. Once a version number is used, it is consumed and cannot be + * reused. This mechanism prevents re-execution of each "step" but allows the creation of new initialization steps in + * case an upgrade adds a module that needs to be initialized. + * + * For example: + * + * [.hljs-theme-light.nopadding] + * ```solidity + * contract MyToken is ERC20Upgradeable { + * function initialize() initializer public { + * __ERC20_init("MyToken", "MTK"); + * } + * } + * + * contract MyTokenV2 is MyToken, ERC20PermitUpgradeable { + * function initializeV2() reinitializer(2) public { + * __ERC20Permit_init("MyToken"); + * } + * } + * ``` + * + * TIP: To avoid leaving the proxy in an uninitialized state, the initializer function should be called as early as + * possible by providing the encoded function call as the `_data` argument to {ERC1967Proxy-constructor}. + * + * CAUTION: When used with inheritance, manual care must be taken to not invoke a parent initializer twice, or to ensure + * that all initializers are idempotent. This is not verified automatically as constructors are by Solidity. + * + * [CAUTION] + * ==== + * Avoid leaving a contract uninitialized. + * + * An uninitialized contract can be taken over by an attacker. This applies to both a proxy and its implementation + * contract, which may impact the proxy. To prevent the implementation contract from being used, you should invoke + * the {_disableInitializers} function in the constructor to automatically lock it when it is deployed: + * + * [.hljs-theme-light.nopadding] + * ``` + * /// @custom:oz-upgrades-unsafe-allow constructor + * constructor() { + * _disableInitializers(); + * } + * ``` + * ==== + */ +abstract contract Initializable { + /** + * @dev Storage of the initializable contract. + * + * It's implemented on a custom ERC-7201 namespace to reduce the risk of storage collisions + * when using with upgradeable contracts. + * + * @custom:storage-location erc7201:openzeppelin.storage.Initializable + */ + struct InitializableStorage { + /** + * @dev Indicates that the contract has been initialized. + */ + uint64 _initialized; + /** + * @dev Indicates that the contract is in the process of being initialized. + */ + bool _initializing; + } + + // keccak256(abi.encode(uint256(keccak256("openzeppelin.storage.Initializable")) - 1)) & ~bytes32(uint256(0xff)) + bytes32 private constant INITIALIZABLE_STORAGE = 0xf0c57e16840df040f15088dc2f81fe391c3923bec73e23a9662efc9c229c6a00; + + /** + * @dev The contract is already initialized. + */ + error InvalidInitialization(); + + /** + * @dev The contract is not initializing. + */ + error NotInitializing(); + + /** + * @dev Triggered when the contract has been initialized or reinitialized. + */ + event Initialized(uint64 version); + + /** + * @dev A modifier that defines a protected initializer function that can be invoked at most once. In its scope, + * `onlyInitializing` functions can be used to initialize parent contracts. + * + * Similar to `reinitializer(1)`, except that in the context of a constructor an `initializer` may be invoked any + * number of times. This behavior in the constructor can be useful during testing and is not expected to be used in + * production. + * + * Emits an {Initialized} event. + */ + modifier initializer() { + // solhint-disable-next-line var-name-mixedcase + InitializableStorage storage $ = _getInitializableStorage(); + + // Cache values to avoid duplicated sloads + bool isTopLevelCall = !$._initializing; + uint64 initialized = $._initialized; + + // Allowed calls: + // - initialSetup: the contract is not in the initializing state and no previous version was + // initialized + // - construction: the contract is initialized at version 1 (no reininitialization) and the + // current contract is just being deployed + bool initialSetup = initialized == 0 && isTopLevelCall; + bool construction = initialized == 1 && address(this).code.length == 0; + + if (!initialSetup && !construction) { + revert InvalidInitialization(); + } + $._initialized = 1; + if (isTopLevelCall) { + $._initializing = true; + } + _; + if (isTopLevelCall) { + $._initializing = false; + emit Initialized(1); + } + } + + /** + * @dev A modifier that defines a protected reinitializer function that can be invoked at most once, and only if the + * contract hasn't been initialized to a greater version before. In its scope, `onlyInitializing` functions can be + * used to initialize parent contracts. + * + * A reinitializer may be used after the original initialization step. This is essential to configure modules that + * are added through upgrades and that require initialization. + * + * When `version` is 1, this modifier is similar to `initializer`, except that functions marked with `reinitializer` + * cannot be nested. If one is invoked in the context of another, execution will revert. + * + * Note that versions can jump in increments greater than 1; this implies that if multiple reinitializers coexist in + * a contract, executing them in the right order is up to the developer or operator. + * + * WARNING: Setting the version to 2**64 - 1 will prevent any future reinitialization. + * + * Emits an {Initialized} event. + */ + modifier reinitializer(uint64 version) { + // solhint-disable-next-line var-name-mixedcase + InitializableStorage storage $ = _getInitializableStorage(); + + if ($._initializing || $._initialized >= version) { + revert InvalidInitialization(); + } + $._initialized = version; + $._initializing = true; + _; + $._initializing = false; + emit Initialized(version); + } + + /** + * @dev Modifier to protect an initialization function so that it can only be invoked by functions with the + * {initializer} and {reinitializer} modifiers, directly or indirectly. + */ + modifier onlyInitializing() { + _checkInitializing(); + _; + } + + /** + * @dev Reverts if the contract is not in an initializing state. See {onlyInitializing}. + */ + function _checkInitializing() internal view virtual { + if (!_isInitializing()) { + revert NotInitializing(); + } + } + + /** + * @dev Locks the contract, preventing any future reinitialization. This cannot be part of an initializer call. + * Calling this in the constructor of a contract will prevent that contract from being initialized or reinitialized + * to any version. It is recommended to use this to lock implementation contracts that are designed to be called + * through proxies. + * + * Emits an {Initialized} event the first time it is successfully executed. + */ + function _disableInitializers() internal virtual { + // solhint-disable-next-line var-name-mixedcase + InitializableStorage storage $ = _getInitializableStorage(); + + if ($._initializing) { + revert InvalidInitialization(); + } + if ($._initialized != type(uint64).max) { + $._initialized = type(uint64).max; + emit Initialized(type(uint64).max); + } + } + + /** + * @dev Returns the highest version that has been initialized. See {reinitializer}. + */ + function _getInitializedVersion() internal view returns (uint64) { + return _getInitializableStorage()._initialized; + } + + /** + * @dev Returns `true` if the contract is currently initializing. See {onlyInitializing}. + */ + function _isInitializing() internal view returns (bool) { + return _getInitializableStorage()._initializing; + } + + /** + * @dev Returns a pointer to the storage namespace. + */ + // solhint-disable-next-line var-name-mixedcase + function _getInitializableStorage() private pure returns (InitializableStorage storage $) { + assembly { + $.slot := INITIALIZABLE_STORAGE + } + } +} diff --git a/contracts/proxy/utils/UUPSUpgradeable.sol b/contracts/proxy/utils/UUPSUpgradeable.sol new file mode 100644 index 000000000..8fad1f711 --- /dev/null +++ b/contracts/proxy/utils/UUPSUpgradeable.sol @@ -0,0 +1,147 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (proxy/utils/UUPSUpgradeable.sol) + +pragma solidity ^0.8.20; + +import {IERC1822Proxiable} from "../../interfaces/draft-IERC1822.sol"; +import {ERC1967Utils} from "../ERC1967/ERC1967Utils.sol"; + +/** + * @dev An upgradeability mechanism designed for UUPS proxies. The functions included here can perform an upgrade of an + * {ERC1967Proxy}, when this contract is set as the implementation behind such a proxy. + * + * A security mechanism ensures that an upgrade does not turn off upgradeability accidentally, although this risk is + * reinstated if the upgrade retains upgradeability but removes the security mechanism, e.g. by replacing + * `UUPSUpgradeable` with a custom implementation of upgrades. + * + * The {_authorizeUpgrade} function must be overridden to include access restriction to the upgrade mechanism. + */ +abstract contract UUPSUpgradeable is IERC1822Proxiable { + /// @custom:oz-upgrades-unsafe-allow state-variable-immutable + address private immutable __self = address(this); + + /** + * @dev The version of the upgrade interface of the contract. If this getter is missing, both `upgradeTo(address)` + * and `upgradeToAndCall(address,bytes)` are present, and `upgradeTo` must be used if no function should be called, + * while `upgradeToAndCall` will invoke the `receive` function if the second argument is the empty byte string. + * If the getter returns `"5.0.0"`, only `upgradeToAndCall(address,bytes)` is present, and the second argument must + * be the empty byte string if no function should be called, making it impossible to invoke the `receive` function + * during an upgrade. + */ + string public constant UPGRADE_INTERFACE_VERSION = "5.0.0"; + + /** + * @dev The call is from an unauthorized context. + */ + error UUPSUnauthorizedCallContext(); + + /** + * @dev The storage `slot` is unsupported as a UUID. + */ + error UUPSUnsupportedProxiableUUID(bytes32 slot); + + /** + * @dev Check that the execution is being performed through a delegatecall call and that the execution context is + * a proxy contract with an implementation (as defined in ERC1967) pointing to self. This should only be the case + * for UUPS and transparent proxies that are using the current contract as their implementation. Execution of a + * function through ERC1167 minimal proxies (clones) would not normally pass this test, but is not guaranteed to + * fail. + */ + modifier onlyProxy() { + _checkProxy(); + _; + } + + /** + * @dev Check that the execution is not being performed through a delegate call. This allows a function to be + * callable on the implementing contract but not through proxies. + */ + modifier notDelegated() { + _checkNotDelegated(); + _; + } + + /** + * @dev Implementation of the ERC1822 {proxiableUUID} function. This returns the storage slot used by the + * implementation. It is used to validate the implementation's compatibility when performing an upgrade. + * + * IMPORTANT: A proxy pointing at a proxiable contract should not be considered proxiable itself, because this risks + * bricking a proxy that upgrades to it, by delegating to itself until out of gas. Thus it is critical that this + * function revert if invoked through a proxy. This is guaranteed by the `notDelegated` modifier. + */ + function proxiableUUID() external view virtual notDelegated returns (bytes32) { + return ERC1967Utils.IMPLEMENTATION_SLOT; + } + + /** + * @dev Upgrade the implementation of the proxy to `newImplementation`, and subsequently execute the function call + * encoded in `data`. + * + * Calls {_authorizeUpgrade}. + * + * Emits an {Upgraded} event. + * + * @custom:oz-upgrades-unsafe-allow-reachable delegatecall + */ + function upgradeToAndCall(address newImplementation, bytes memory data) public payable virtual onlyProxy { + _authorizeUpgrade(newImplementation); + _upgradeToAndCallUUPS(newImplementation, data); + } + + /** + * @dev Reverts if the execution is not performed via delegatecall or the execution + * context is not of a proxy with an ERC1967-compliant implementation pointing to self. + * See {_onlyProxy}. + */ + function _checkProxy() internal view virtual { + if ( + address(this) == __self || // Must be called through delegatecall + ERC1967Utils.getImplementation() != __self // Must be called through an active proxy + ) { + revert UUPSUnauthorizedCallContext(); + } + } + + /** + * @dev Reverts if the execution is performed via delegatecall. + * See {notDelegated}. + */ + function _checkNotDelegated() internal view virtual { + if (address(this) != __self) { + // Must not be called through delegatecall + revert UUPSUnauthorizedCallContext(); + } + } + + /** + * @dev Function that should revert when `msg.sender` is not authorized to upgrade the contract. Called by + * {upgradeToAndCall}. + * + * Normally, this function will use an xref:access.adoc[access control] modifier such as {Ownable-onlyOwner}. + * + * ```solidity + * function _authorizeUpgrade(address) internal onlyOwner {} + * ``` + */ + function _authorizeUpgrade(address newImplementation) internal virtual; + + /** + * @dev Performs an implementation upgrade with a security check for UUPS proxies, and additional setup call. + * + * As a security check, {proxiableUUID} is invoked in the new implementation, and the return value + * is expected to be the implementation slot in ERC1967. + * + * Emits an {IERC1967-Upgraded} event. + */ + function _upgradeToAndCallUUPS(address newImplementation, bytes memory data) private { + try IERC1822Proxiable(newImplementation).proxiableUUID() returns (bytes32 slot) { + if (slot != ERC1967Utils.IMPLEMENTATION_SLOT) { + revert UUPSUnsupportedProxiableUUID(slot); + } + ERC1967Utils.upgradeToAndCall(newImplementation, data); + } catch { + // The implementation is not UUPS + revert ERC1967Utils.ERC1967InvalidImplementation(newImplementation); + } + } +} diff --git a/contracts/token/ERC1155/ERC1155.sol b/contracts/token/ERC1155/ERC1155.sol new file mode 100644 index 000000000..b88381e7b --- /dev/null +++ b/contracts/token/ERC1155/ERC1155.sol @@ -0,0 +1,468 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (token/ERC1155/ERC1155.sol) + +pragma solidity ^0.8.20; + +import {IERC1155} from "./IERC1155.sol"; +import {IERC1155Receiver} from "./IERC1155Receiver.sol"; +import {IERC1155MetadataURI} from "./extensions/IERC1155MetadataURI.sol"; +import {Context} from "../../utils/Context.sol"; +import {IERC165, ERC165} from "../../utils/introspection/ERC165.sol"; +import {Arrays} from "../../utils/Arrays.sol"; +import {IERC1155Errors} from "../../interfaces/draft-IERC6093.sol"; + +/** + * @dev Implementation of the basic standard multi-token. + * See https://eips.ethereum.org/EIPS/eip-1155 + * Originally based on code by Enjin: https://github.com/enjin/erc-1155 + */ +abstract contract ERC1155 is Context, ERC165, IERC1155, IERC1155MetadataURI, IERC1155Errors { + using Arrays for uint256[]; + using Arrays for address[]; + + mapping(uint256 id => mapping(address account => uint256)) private _balances; + + mapping(address account => mapping(address operator => bool)) private _operatorApprovals; + + // Used as the URI for all token types by relying on ID substitution, e.g. https://token-cdn-domain/{id}.json + string private _uri; + + /** + * @dev See {_setURI}. + */ + constructor(string memory uri_) { + _setURI(uri_); + } + + /** + * @dev See {IERC165-supportsInterface}. + */ + function supportsInterface(bytes4 interfaceId) public view virtual override(ERC165, IERC165) returns (bool) { + return + interfaceId == type(IERC1155).interfaceId || + interfaceId == type(IERC1155MetadataURI).interfaceId || + super.supportsInterface(interfaceId); + } + + /** + * @dev See {IERC1155MetadataURI-uri}. + * + * This implementation returns the same URI for *all* token types. It relies + * on the token type ID substitution mechanism + * https://eips.ethereum.org/EIPS/eip-1155#metadata[defined in the EIP]. + * + * Clients calling this function must replace the `\{id\}` substring with the + * actual token type ID. + */ + function uri(uint256 /* id */) public view virtual returns (string memory) { + return _uri; + } + + /** + * @dev See {IERC1155-balanceOf}. + */ + function balanceOf(address account, uint256 id) public view virtual returns (uint256) { + return _balances[id][account]; + } + + /** + * @dev See {IERC1155-balanceOfBatch}. + * + * Requirements: + * + * - `accounts` and `ids` must have the same length. + */ + function balanceOfBatch( + address[] memory accounts, + uint256[] memory ids + ) public view virtual returns (uint256[] memory) { + if (accounts.length != ids.length) { + revert ERC1155InvalidArrayLength(ids.length, accounts.length); + } + + uint256[] memory batchBalances = new uint256[](accounts.length); + + for (uint256 i = 0; i < accounts.length; ++i) { + batchBalances[i] = balanceOf(accounts.unsafeMemoryAccess(i), ids.unsafeMemoryAccess(i)); + } + + return batchBalances; + } + + /** + * @dev See {IERC1155-setApprovalForAll}. + */ + function setApprovalForAll(address operator, bool approved) public virtual { + _setApprovalForAll(_msgSender(), operator, approved); + } + + /** + * @dev See {IERC1155-isApprovedForAll}. + */ + function isApprovedForAll(address account, address operator) public view virtual returns (bool) { + return _operatorApprovals[account][operator]; + } + + /** + * @dev See {IERC1155-safeTransferFrom}. + */ + function safeTransferFrom(address from, address to, uint256 id, uint256 value, bytes memory data) public virtual { + address sender = _msgSender(); + if (from != sender && !isApprovedForAll(from, sender)) { + revert ERC1155MissingApprovalForAll(sender, from); + } + _safeTransferFrom(from, to, id, value, data); + } + + /** + * @dev See {IERC1155-safeBatchTransferFrom}. + */ + function safeBatchTransferFrom( + address from, + address to, + uint256[] memory ids, + uint256[] memory values, + bytes memory data + ) public virtual { + address sender = _msgSender(); + if (from != sender && !isApprovedForAll(from, sender)) { + revert ERC1155MissingApprovalForAll(sender, from); + } + _safeBatchTransferFrom(from, to, ids, values, data); + } + + /** + * @dev Transfers a `value` amount of tokens of type `id` from `from` to `to`. Will mint (or burn) if `from` + * (or `to`) is the zero address. + * + * Emits a {TransferSingle} event if the arrays contain one element, and {TransferBatch} otherwise. + * + * Requirements: + * + * - If `to` refers to a smart contract, it must implement either {IERC1155Receiver-onERC1155Received} + * or {IERC1155Receiver-onERC1155BatchReceived} and return the acceptance magic value. + * - `ids` and `values` must have the same length. + * + * NOTE: The ERC-1155 acceptance check is not performed in this function. See {_updateWithAcceptanceCheck} instead. + */ + function _update(address from, address to, uint256[] memory ids, uint256[] memory values) internal virtual { + if (ids.length != values.length) { + revert ERC1155InvalidArrayLength(ids.length, values.length); + } + + address operator = _msgSender(); + + for (uint256 i = 0; i < ids.length; ++i) { + uint256 id = ids.unsafeMemoryAccess(i); + uint256 value = values.unsafeMemoryAccess(i); + + if (from != address(0)) { + uint256 fromBalance = _balances[id][from]; + if (fromBalance < value) { + revert ERC1155InsufficientBalance(from, fromBalance, value, id); + } + unchecked { + // Overflow not possible: value <= fromBalance + _balances[id][from] = fromBalance - value; + } + } + + if (to != address(0)) { + _balances[id][to] += value; + } + } + + if (ids.length == 1) { + uint256 id = ids.unsafeMemoryAccess(0); + uint256 value = values.unsafeMemoryAccess(0); + emit TransferSingle(operator, from, to, id, value); + } else { + emit TransferBatch(operator, from, to, ids, values); + } + } + + /** + * @dev Version of {_update} that performs the token acceptance check by calling + * {IERC1155Receiver-onERC1155Received} or {IERC1155Receiver-onERC1155BatchReceived} on the receiver address if it + * contains code (eg. is a smart contract at the moment of execution). + * + * IMPORTANT: Overriding this function is discouraged because it poses a reentrancy risk from the receiver. So any + * update to the contract state after this function would break the check-effect-interaction pattern. Consider + * overriding {_update} instead. + */ + function _updateWithAcceptanceCheck( + address from, + address to, + uint256[] memory ids, + uint256[] memory values, + bytes memory data + ) internal virtual { + _update(from, to, ids, values); + if (to != address(0)) { + address operator = _msgSender(); + if (ids.length == 1) { + uint256 id = ids.unsafeMemoryAccess(0); + uint256 value = values.unsafeMemoryAccess(0); + _doSafeTransferAcceptanceCheck(operator, from, to, id, value, data); + } else { + _doSafeBatchTransferAcceptanceCheck(operator, from, to, ids, values, data); + } + } + } + + /** + * @dev Transfers a `value` tokens of token type `id` from `from` to `to`. + * + * Emits a {TransferSingle} event. + * + * Requirements: + * + * - `to` cannot be the zero address. + * - `from` must have a balance of tokens of type `id` of at least `value` amount. + * - If `to` refers to a smart contract, it must implement {IERC1155Receiver-onERC1155Received} and return the + * acceptance magic value. + */ + function _safeTransferFrom(address from, address to, uint256 id, uint256 value, bytes memory data) internal { + if (to == address(0)) { + revert ERC1155InvalidReceiver(address(0)); + } + if (from == address(0)) { + revert ERC1155InvalidSender(address(0)); + } + (uint256[] memory ids, uint256[] memory values) = _asSingletonArrays(id, value); + _updateWithAcceptanceCheck(from, to, ids, values, data); + } + + /** + * @dev xref:ROOT:erc1155.adoc#batch-operations[Batched] version of {_safeTransferFrom}. + * + * Emits a {TransferBatch} event. + * + * Requirements: + * + * - If `to` refers to a smart contract, it must implement {IERC1155Receiver-onERC1155BatchReceived} and return the + * acceptance magic value. + * - `ids` and `values` must have the same length. + */ + function _safeBatchTransferFrom( + address from, + address to, + uint256[] memory ids, + uint256[] memory values, + bytes memory data + ) internal { + if (to == address(0)) { + revert ERC1155InvalidReceiver(address(0)); + } + if (from == address(0)) { + revert ERC1155InvalidSender(address(0)); + } + _updateWithAcceptanceCheck(from, to, ids, values, data); + } + + /** + * @dev Sets a new URI for all token types, by relying on the token type ID + * substitution mechanism + * https://eips.ethereum.org/EIPS/eip-1155#metadata[defined in the EIP]. + * + * By this mechanism, any occurrence of the `\{id\}` substring in either the + * URI or any of the values in the JSON file at said URI will be replaced by + * clients with the token type ID. + * + * For example, the `https://token-cdn-domain/\{id\}.json` URI would be + * interpreted by clients as + * `https://token-cdn-domain/000000000000000000000000000000000000000000000000000000000004cce0.json` + * for token type ID 0x4cce0. + * + * See {uri}. + * + * Because these URIs cannot be meaningfully represented by the {URI} event, + * this function emits no events. + */ + function _setURI(string memory newuri) internal virtual { + _uri = newuri; + } + + /** + * @dev Creates a `value` amount of tokens of type `id`, and assigns them to `to`. + * + * Emits a {TransferSingle} event. + * + * Requirements: + * + * - `to` cannot be the zero address. + * - If `to` refers to a smart contract, it must implement {IERC1155Receiver-onERC1155Received} and return the + * acceptance magic value. + */ + function _mint(address to, uint256 id, uint256 value, bytes memory data) internal { + if (to == address(0)) { + revert ERC1155InvalidReceiver(address(0)); + } + (uint256[] memory ids, uint256[] memory values) = _asSingletonArrays(id, value); + _updateWithAcceptanceCheck(address(0), to, ids, values, data); + } + + /** + * @dev xref:ROOT:erc1155.adoc#batch-operations[Batched] version of {_mint}. + * + * Emits a {TransferBatch} event. + * + * Requirements: + * + * - `ids` and `values` must have the same length. + * - `to` cannot be the zero address. + * - If `to` refers to a smart contract, it must implement {IERC1155Receiver-onERC1155BatchReceived} and return the + * acceptance magic value. + */ + function _mintBatch(address to, uint256[] memory ids, uint256[] memory values, bytes memory data) internal { + if (to == address(0)) { + revert ERC1155InvalidReceiver(address(0)); + } + _updateWithAcceptanceCheck(address(0), to, ids, values, data); + } + + /** + * @dev Destroys a `value` amount of tokens of type `id` from `from` + * + * Emits a {TransferSingle} event. + * + * Requirements: + * + * - `from` cannot be the zero address. + * - `from` must have at least `value` amount of tokens of type `id`. + */ + function _burn(address from, uint256 id, uint256 value) internal { + if (from == address(0)) { + revert ERC1155InvalidSender(address(0)); + } + (uint256[] memory ids, uint256[] memory values) = _asSingletonArrays(id, value); + _updateWithAcceptanceCheck(from, address(0), ids, values, ""); + } + + /** + * @dev xref:ROOT:erc1155.adoc#batch-operations[Batched] version of {_burn}. + * + * Emits a {TransferBatch} event. + * + * Requirements: + * + * - `from` cannot be the zero address. + * - `from` must have at least `value` amount of tokens of type `id`. + * - `ids` and `values` must have the same length. + */ + function _burnBatch(address from, uint256[] memory ids, uint256[] memory values) internal { + if (from == address(0)) { + revert ERC1155InvalidSender(address(0)); + } + _updateWithAcceptanceCheck(from, address(0), ids, values, ""); + } + + /** + * @dev Approve `operator` to operate on all of `owner` tokens + * + * Emits an {ApprovalForAll} event. + * + * Requirements: + * + * - `operator` cannot be the zero address. + */ + function _setApprovalForAll(address owner, address operator, bool approved) internal virtual { + if (operator == address(0)) { + revert ERC1155InvalidOperator(address(0)); + } + _operatorApprovals[owner][operator] = approved; + emit ApprovalForAll(owner, operator, approved); + } + + /** + * @dev Performs an acceptance check by calling {IERC1155-onERC1155Received} on the `to` address + * if it contains code at the moment of execution. + */ + function _doSafeTransferAcceptanceCheck( + address operator, + address from, + address to, + uint256 id, + uint256 value, + bytes memory data + ) private { + if (to.code.length > 0) { + try IERC1155Receiver(to).onERC1155Received(operator, from, id, value, data) returns (bytes4 response) { + if (response != IERC1155Receiver.onERC1155Received.selector) { + // Tokens rejected + revert ERC1155InvalidReceiver(to); + } + } catch (bytes memory reason) { + if (reason.length == 0) { + // non-ERC1155Receiver implementer + revert ERC1155InvalidReceiver(to); + } else { + /// @solidity memory-safe-assembly + assembly { + revert(add(32, reason), mload(reason)) + } + } + } + } + } + + /** + * @dev Performs a batch acceptance check by calling {IERC1155-onERC1155BatchReceived} on the `to` address + * if it contains code at the moment of execution. + */ + function _doSafeBatchTransferAcceptanceCheck( + address operator, + address from, + address to, + uint256[] memory ids, + uint256[] memory values, + bytes memory data + ) private { + if (to.code.length > 0) { + try IERC1155Receiver(to).onERC1155BatchReceived(operator, from, ids, values, data) returns ( + bytes4 response + ) { + if (response != IERC1155Receiver.onERC1155BatchReceived.selector) { + // Tokens rejected + revert ERC1155InvalidReceiver(to); + } + } catch (bytes memory reason) { + if (reason.length == 0) { + // non-ERC1155Receiver implementer + revert ERC1155InvalidReceiver(to); + } else { + /// @solidity memory-safe-assembly + assembly { + revert(add(32, reason), mload(reason)) + } + } + } + } + } + + /** + * @dev Creates an array in memory with only one value for each of the elements provided. + */ + function _asSingletonArrays( + uint256 element1, + uint256 element2 + ) private pure returns (uint256[] memory array1, uint256[] memory array2) { + /// @solidity memory-safe-assembly + assembly { + // Load the free memory pointer + array1 := mload(0x40) + // Set array length to 1 + mstore(array1, 1) + // Store the single element at the next word after the length (where content starts) + mstore(add(array1, 0x20), element1) + + // Repeat for next array locating it right after the first array + array2 := add(array1, 0x40) + mstore(array2, 1) + mstore(add(array2, 0x20), element2) + + // Update the free memory pointer by pointing after the second array + mstore(0x40, add(array2, 0x40)) + } + } +} diff --git a/contracts/token/ERC1155/IERC1155.sol b/contracts/token/ERC1155/IERC1155.sol new file mode 100644 index 000000000..7e86df9a8 --- /dev/null +++ b/contracts/token/ERC1155/IERC1155.sol @@ -0,0 +1,128 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (token/ERC1155/IERC1155.sol) + +pragma solidity ^0.8.20; + +import {IERC165} from "../../utils/introspection/IERC165.sol"; + +/** + * @dev Required interface of an ERC1155 compliant contract, as defined in the + * https://eips.ethereum.org/EIPS/eip-1155[EIP]. + */ +interface IERC1155 is IERC165 { + /** + * @dev Emitted when `value` amount of tokens of type `id` are transferred from `from` to `to` by `operator`. + */ + event TransferSingle(address indexed operator, address indexed from, address indexed to, uint256 id, uint256 value); + + /** + * @dev Equivalent to multiple {TransferSingle} events, where `operator`, `from` and `to` are the same for all + * transfers. + */ + event TransferBatch( + address indexed operator, + address indexed from, + address indexed to, + uint256[] ids, + uint256[] values + ); + + /** + * @dev Emitted when `account` grants or revokes permission to `operator` to transfer their tokens, according to + * `approved`. + */ + event ApprovalForAll(address indexed account, address indexed operator, bool approved); + + /** + * @dev Emitted when the URI for token type `id` changes to `value`, if it is a non-programmatic URI. + * + * If an {URI} event was emitted for `id`, the standard + * https://eips.ethereum.org/EIPS/eip-1155#metadata-extensions[guarantees] that `value` will equal the value + * returned by {IERC1155MetadataURI-uri}. + */ + event URI(string value, uint256 indexed id); + + /** + * @dev Returns the value of tokens of token type `id` owned by `account`. + * + * Requirements: + * + * - `account` cannot be the zero address. + */ + function balanceOf(address account, uint256 id) external view returns (uint256); + + /** + * @dev xref:ROOT:erc1155.adoc#batch-operations[Batched] version of {balanceOf}. + * + * Requirements: + * + * - `accounts` and `ids` must have the same length. + */ + function balanceOfBatch( + address[] calldata accounts, + uint256[] calldata ids + ) external view returns (uint256[] memory); + + /** + * @dev Grants or revokes permission to `operator` to transfer the caller's tokens, according to `approved`, + * + * Emits an {ApprovalForAll} event. + * + * Requirements: + * + * - `operator` cannot be the caller. + */ + function setApprovalForAll(address operator, bool approved) external; + + /** + * @dev Returns true if `operator` is approved to transfer ``account``'s tokens. + * + * See {setApprovalForAll}. + */ + function isApprovedForAll(address account, address operator) external view returns (bool); + + /** + * @dev Transfers a `value` amount of tokens of type `id` from `from` to `to`. + * + * WARNING: This function can potentially allow a reentrancy attack when transferring tokens + * to an untrusted contract, when invoking {onERC1155Received} on the receiver. + * Ensure to follow the checks-effects-interactions pattern and consider employing + * reentrancy guards when interacting with untrusted contracts. + * + * Emits a {TransferSingle} event. + * + * Requirements: + * + * - `to` cannot be the zero address. + * - If the caller is not `from`, it must have been approved to spend ``from``'s tokens via {setApprovalForAll}. + * - `from` must have a balance of tokens of type `id` of at least `value` amount. + * - If `to` refers to a smart contract, it must implement {IERC1155Receiver-onERC1155Received} and return the + * acceptance magic value. + */ + function safeTransferFrom(address from, address to, uint256 id, uint256 value, bytes calldata data) external; + + /** + * @dev xref:ROOT:erc1155.adoc#batch-operations[Batched] version of {safeTransferFrom}. + * + * + * WARNING: This function can potentially allow a reentrancy attack when transferring tokens + * to an untrusted contract, when invoking {onERC1155BatchReceived} on the receiver. + * Ensure to follow the checks-effects-interactions pattern and consider employing + * reentrancy guards when interacting with untrusted contracts. + * + * Emits a {TransferBatch} event. + * + * Requirements: + * + * - `ids` and `values` must have the same length. + * - If `to` refers to a smart contract, it must implement {IERC1155Receiver-onERC1155BatchReceived} and return the + * acceptance magic value. + */ + function safeBatchTransferFrom( + address from, + address to, + uint256[] calldata ids, + uint256[] calldata values, + bytes calldata data + ) external; +} diff --git a/contracts/token/ERC1155/IERC1155Receiver.sol b/contracts/token/ERC1155/IERC1155Receiver.sol new file mode 100644 index 000000000..4abe83469 --- /dev/null +++ b/contracts/token/ERC1155/IERC1155Receiver.sol @@ -0,0 +1,59 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (token/ERC1155/IERC1155Receiver.sol) + +pragma solidity ^0.8.20; + +import {IERC165} from "../../utils/introspection/IERC165.sol"; + +/** + * @dev Interface that must be implemented by smart contracts in order to receive + * ERC-1155 token transfers. + */ +interface IERC1155Receiver is IERC165 { + /** + * @dev Handles the receipt of a single ERC1155 token type. This function is + * called at the end of a `safeTransferFrom` after the balance has been updated. + * + * NOTE: To accept the transfer, this must return + * `bytes4(keccak256("onERC1155Received(address,address,uint256,uint256,bytes)"))` + * (i.e. 0xf23a6e61, or its own function selector). + * + * @param operator The address which initiated the transfer (i.e. msg.sender) + * @param from The address which previously owned the token + * @param id The ID of the token being transferred + * @param value The amount of tokens being transferred + * @param data Additional data with no specified format + * @return `bytes4(keccak256("onERC1155Received(address,address,uint256,uint256,bytes)"))` if transfer is allowed + */ + function onERC1155Received( + address operator, + address from, + uint256 id, + uint256 value, + bytes calldata data + ) external returns (bytes4); + + /** + * @dev Handles the receipt of a multiple ERC1155 token types. This function + * is called at the end of a `safeBatchTransferFrom` after the balances have + * been updated. + * + * NOTE: To accept the transfer(s), this must return + * `bytes4(keccak256("onERC1155BatchReceived(address,address,uint256[],uint256[],bytes)"))` + * (i.e. 0xbc197c81, or its own function selector). + * + * @param operator The address which initiated the batch transfer (i.e. msg.sender) + * @param from The address which previously owned the token + * @param ids An array containing ids of each token being transferred (order and length must match values array) + * @param values An array containing amounts of each token being transferred (order and length must match ids array) + * @param data Additional data with no specified format + * @return `bytes4(keccak256("onERC1155BatchReceived(address,address,uint256[],uint256[],bytes)"))` if transfer is allowed + */ + function onERC1155BatchReceived( + address operator, + address from, + uint256[] calldata ids, + uint256[] calldata values, + bytes calldata data + ) external returns (bytes4); +} diff --git a/contracts/token/ERC1155/README.adoc b/contracts/token/ERC1155/README.adoc new file mode 100644 index 000000000..1a56358ef --- /dev/null +++ b/contracts/token/ERC1155/README.adoc @@ -0,0 +1,41 @@ += ERC 1155 + +[.readme-notice] +NOTE: This document is better viewed at https://docs.openzeppelin.com/contracts/api/token/erc1155 + +This set of interfaces and contracts are all related to the https://eips.ethereum.org/EIPS/eip-1155[ERC1155 Multi Token Standard]. + +The EIP consists of three interfaces which fulfill different roles, found here as {IERC1155}, {IERC1155MetadataURI} and {IERC1155Receiver}. + +{ERC1155} implements the mandatory {IERC1155} interface, as well as the optional extension {IERC1155MetadataURI}, by relying on the substitution mechanism to use the same URI for all token types, dramatically reducing gas costs. + +Additionally there are multiple custom extensions, including: + +* designation of addresses that can pause token transfers for all users ({ERC1155Pausable}). +* destruction of own tokens ({ERC1155Burnable}). + +NOTE: This core set of contracts is designed to be unopinionated, allowing developers to access the internal functions in ERC1155 (such as <>) and expose them as external functions in the way they prefer. + +== Core + +{{IERC1155}} + +{{IERC1155MetadataURI}} + +{{ERC1155}} + +{{IERC1155Receiver}} + +== Extensions + +{{ERC1155Pausable}} + +{{ERC1155Burnable}} + +{{ERC1155Supply}} + +{{ERC1155URIStorage}} + +== Utilities + +{{ERC1155Holder}} diff --git a/contracts/token/ERC1155/extensions/ERC1155Burnable.sol b/contracts/token/ERC1155/extensions/ERC1155Burnable.sol new file mode 100644 index 000000000..a6264f880 --- /dev/null +++ b/contracts/token/ERC1155/extensions/ERC1155Burnable.sol @@ -0,0 +1,28 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (token/ERC1155/extensions/ERC1155Burnable.sol) + +pragma solidity ^0.8.20; + +import {ERC1155} from "../ERC1155.sol"; + +/** + * @dev Extension of {ERC1155} that allows token holders to destroy both their + * own tokens and those that they have been approved to use. + */ +abstract contract ERC1155Burnable is ERC1155 { + function burn(address account, uint256 id, uint256 value) public virtual { + if (account != _msgSender() && !isApprovedForAll(account, _msgSender())) { + revert ERC1155MissingApprovalForAll(_msgSender(), account); + } + + _burn(account, id, value); + } + + function burnBatch(address account, uint256[] memory ids, uint256[] memory values) public virtual { + if (account != _msgSender() && !isApprovedForAll(account, _msgSender())) { + revert ERC1155MissingApprovalForAll(_msgSender(), account); + } + + _burnBatch(account, ids, values); + } +} diff --git a/contracts/token/ERC1155/extensions/ERC1155Pausable.sol b/contracts/token/ERC1155/extensions/ERC1155Pausable.sol new file mode 100644 index 000000000..6d2e79811 --- /dev/null +++ b/contracts/token/ERC1155/extensions/ERC1155Pausable.sol @@ -0,0 +1,38 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (token/ERC1155/extensions/ERC1155Pausable.sol) + +pragma solidity ^0.8.20; + +import {ERC1155} from "../ERC1155.sol"; +import {Pausable} from "../../../utils/Pausable.sol"; + +/** + * @dev ERC1155 token with pausable token transfers, minting and burning. + * + * Useful for scenarios such as preventing trades until the end of an evaluation + * period, or having an emergency switch for freezing all token transfers in the + * event of a large bug. + * + * IMPORTANT: This contract does not include public pause and unpause functions. In + * addition to inheriting this contract, you must define both functions, invoking the + * {Pausable-_pause} and {Pausable-_unpause} internal functions, with appropriate + * access control, e.g. using {AccessControl} or {Ownable}. Not doing so will + * make the contract pause mechanism of the contract unreachable, and thus unusable. + */ +abstract contract ERC1155Pausable is ERC1155, Pausable { + /** + * @dev See {ERC1155-_update}. + * + * Requirements: + * + * - the contract must not be paused. + */ + function _update( + address from, + address to, + uint256[] memory ids, + uint256[] memory values + ) internal virtual override whenNotPaused { + super._update(from, to, ids, values); + } +} diff --git a/contracts/token/ERC1155/extensions/ERC1155Supply.sol b/contracts/token/ERC1155/extensions/ERC1155Supply.sol new file mode 100644 index 000000000..7f5b16316 --- /dev/null +++ b/contracts/token/ERC1155/extensions/ERC1155Supply.sol @@ -0,0 +1,87 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (token/ERC1155/extensions/ERC1155Supply.sol) + +pragma solidity ^0.8.20; + +import {ERC1155} from "../ERC1155.sol"; + +/** + * @dev Extension of ERC1155 that adds tracking of total supply per id. + * + * Useful for scenarios where Fungible and Non-fungible tokens have to be + * clearly identified. Note: While a totalSupply of 1 might mean the + * corresponding is an NFT, there is no guarantees that no other token with the + * same id are not going to be minted. + * + * NOTE: This contract implies a global limit of 2**256 - 1 to the number of tokens + * that can be minted. + * + * CAUTION: This extension should not be added in an upgrade to an already deployed contract. + */ +abstract contract ERC1155Supply is ERC1155 { + mapping(uint256 id => uint256) private _totalSupply; + uint256 private _totalSupplyAll; + + /** + * @dev Total value of tokens in with a given id. + */ + function totalSupply(uint256 id) public view virtual returns (uint256) { + return _totalSupply[id]; + } + + /** + * @dev Total value of tokens. + */ + function totalSupply() public view virtual returns (uint256) { + return _totalSupplyAll; + } + + /** + * @dev Indicates whether any token exist with a given id, or not. + */ + function exists(uint256 id) public view virtual returns (bool) { + return totalSupply(id) > 0; + } + + /** + * @dev See {ERC1155-_update}. + */ + function _update( + address from, + address to, + uint256[] memory ids, + uint256[] memory values + ) internal virtual override { + super._update(from, to, ids, values); + + if (from == address(0)) { + uint256 totalMintValue = 0; + for (uint256 i = 0; i < ids.length; ++i) { + uint256 value = values[i]; + // Overflow check required: The rest of the code assumes that totalSupply never overflows + _totalSupply[ids[i]] += value; + totalMintValue += value; + } + // Overflow check required: The rest of the code assumes that totalSupplyAll never overflows + _totalSupplyAll += totalMintValue; + } + + if (to == address(0)) { + uint256 totalBurnValue = 0; + for (uint256 i = 0; i < ids.length; ++i) { + uint256 value = values[i]; + + unchecked { + // Overflow not possible: values[i] <= balanceOf(from, ids[i]) <= totalSupply(ids[i]) + _totalSupply[ids[i]] -= value; + // Overflow not possible: sum_i(values[i]) <= sum_i(totalSupply(ids[i])) <= totalSupplyAll + totalBurnValue += value; + } + } + unchecked { + // Overflow not possible: totalBurnValue = sum_i(values[i]) <= sum_i(totalSupply(ids[i])) <= totalSupplyAll + _totalSupplyAll -= totalBurnValue; + } + } + } +} diff --git a/contracts/token/ERC1155/extensions/ERC1155URIStorage.sol b/contracts/token/ERC1155/extensions/ERC1155URIStorage.sol new file mode 100644 index 000000000..dfbde20c9 --- /dev/null +++ b/contracts/token/ERC1155/extensions/ERC1155URIStorage.sol @@ -0,0 +1,61 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (token/ERC1155/extensions/ERC1155URIStorage.sol) + +pragma solidity ^0.8.20; + +import {Strings} from "../../../utils/Strings.sol"; +import {ERC1155} from "../ERC1155.sol"; + +/** + * @dev ERC1155 token with storage based token URI management. + * Inspired by the ERC721URIStorage extension + */ +abstract contract ERC1155URIStorage is ERC1155 { + using Strings for uint256; + + // Optional base URI + string private _baseURI = ""; + + // Optional mapping for token URIs + mapping(uint256 tokenId => string) private _tokenURIs; + + /** + * @dev See {IERC1155MetadataURI-uri}. + * + * This implementation returns the concatenation of the `_baseURI` + * and the token-specific uri if the latter is set + * + * This enables the following behaviors: + * + * - if `_tokenURIs[tokenId]` is set, then the result is the concatenation + * of `_baseURI` and `_tokenURIs[tokenId]` (keep in mind that `_baseURI` + * is empty per default); + * + * - if `_tokenURIs[tokenId]` is NOT set then we fallback to `super.uri()` + * which in most cases will contain `ERC1155._uri`; + * + * - if `_tokenURIs[tokenId]` is NOT set, and if the parents do not have a + * uri value set, then the result is empty. + */ + function uri(uint256 tokenId) public view virtual override returns (string memory) { + string memory tokenURI = _tokenURIs[tokenId]; + + // If token URI is set, concatenate base URI and tokenURI (via string.concat). + return bytes(tokenURI).length > 0 ? string.concat(_baseURI, tokenURI) : super.uri(tokenId); + } + + /** + * @dev Sets `tokenURI` as the tokenURI of `tokenId`. + */ + function _setURI(uint256 tokenId, string memory tokenURI) internal virtual { + _tokenURIs[tokenId] = tokenURI; + emit URI(uri(tokenId), tokenId); + } + + /** + * @dev Sets `baseURI` as the `_baseURI` for all tokens + */ + function _setBaseURI(string memory baseURI) internal virtual { + _baseURI = baseURI; + } +} diff --git a/contracts/token/ERC1155/extensions/IERC1155MetadataURI.sol b/contracts/token/ERC1155/extensions/IERC1155MetadataURI.sol new file mode 100644 index 000000000..c21848645 --- /dev/null +++ b/contracts/token/ERC1155/extensions/IERC1155MetadataURI.sol @@ -0,0 +1,20 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (token/ERC1155/extensions/IERC1155MetadataURI.sol) + +pragma solidity ^0.8.20; + +import {IERC1155} from "../IERC1155.sol"; + +/** + * @dev Interface of the optional ERC1155MetadataExtension interface, as defined + * in the https://eips.ethereum.org/EIPS/eip-1155#metadata-extensions[EIP]. + */ +interface IERC1155MetadataURI is IERC1155 { + /** + * @dev Returns the URI for token type `id`. + * + * If the `\{id\}` substring is present in the URI, it must be replaced by + * clients with the actual token type ID. + */ + function uri(uint256 id) external view returns (string memory); +} diff --git a/contracts/token/ERC1155/utils/ERC1155Holder.sol b/contracts/token/ERC1155/utils/ERC1155Holder.sol new file mode 100644 index 000000000..98787225b --- /dev/null +++ b/contracts/token/ERC1155/utils/ERC1155Holder.sol @@ -0,0 +1,42 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (token/ERC1155/utils/ERC1155Holder.sol) + +pragma solidity ^0.8.20; + +import {IERC165, ERC165} from "../../../utils/introspection/ERC165.sol"; +import {IERC1155Receiver} from "../IERC1155Receiver.sol"; + +/** + * @dev Simple implementation of `IERC1155Receiver` that will allow a contract to hold ERC1155 tokens. + * + * IMPORTANT: When inheriting this contract, you must include a way to use the received tokens, otherwise they will be + * stuck. + */ +abstract contract ERC1155Holder is ERC165, IERC1155Receiver { + /** + * @dev See {IERC165-supportsInterface}. + */ + function supportsInterface(bytes4 interfaceId) public view virtual override(ERC165, IERC165) returns (bool) { + return interfaceId == type(IERC1155Receiver).interfaceId || super.supportsInterface(interfaceId); + } + + function onERC1155Received( + address, + address, + uint256, + uint256, + bytes memory + ) public virtual override returns (bytes4) { + return this.onERC1155Received.selector; + } + + function onERC1155BatchReceived( + address, + address, + uint256[] memory, + uint256[] memory, + bytes memory + ) public virtual override returns (bytes4) { + return this.onERC1155BatchReceived.selector; + } +} diff --git a/contracts/token/ERC20/ERC20.sol b/contracts/token/ERC20/ERC20.sol new file mode 100644 index 000000000..e45639193 --- /dev/null +++ b/contracts/token/ERC20/ERC20.sol @@ -0,0 +1,316 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (token/ERC20/ERC20.sol) + +pragma solidity ^0.8.20; + +import {IERC20} from "./IERC20.sol"; +import {IERC20Metadata} from "./extensions/IERC20Metadata.sol"; +import {Context} from "../../utils/Context.sol"; +import {IERC20Errors} from "../../interfaces/draft-IERC6093.sol"; + +/** + * @dev Implementation of the {IERC20} interface. + * + * This implementation is agnostic to the way tokens are created. This means + * that a supply mechanism has to be added in a derived contract using {_mint}. + * + * TIP: For a detailed writeup see our guide + * https://forum.openzeppelin.com/t/how-to-implement-erc20-supply-mechanisms/226[How + * to implement supply mechanisms]. + * + * The default value of {decimals} is 18. To change this, you should override + * this function so it returns a different value. + * + * We have followed general OpenZeppelin Contracts guidelines: functions revert + * instead returning `false` on failure. This behavior is nonetheless + * conventional and does not conflict with the expectations of ERC20 + * applications. + * + * Additionally, an {Approval} event is emitted on calls to {transferFrom}. + * This allows applications to reconstruct the allowance for all accounts just + * by listening to said events. Other implementations of the EIP may not emit + * these events, as it isn't required by the specification. + */ +abstract contract ERC20 is Context, IERC20, IERC20Metadata, IERC20Errors { + mapping(address account => uint256) private _balances; + + mapping(address account => mapping(address spender => uint256)) private _allowances; + + uint256 private _totalSupply; + + string private _name; + string private _symbol; + + /** + * @dev Sets the values for {name} and {symbol}. + * + * All two of these values are immutable: they can only be set once during + * construction. + */ + constructor(string memory name_, string memory symbol_) { + _name = name_; + _symbol = symbol_; + } + + /** + * @dev Returns the name of the token. + */ + function name() public view virtual returns (string memory) { + return _name; + } + + /** + * @dev Returns the symbol of the token, usually a shorter version of the + * name. + */ + function symbol() public view virtual returns (string memory) { + return _symbol; + } + + /** + * @dev Returns the number of decimals used to get its user representation. + * For example, if `decimals` equals `2`, a balance of `505` tokens should + * be displayed to a user as `5.05` (`505 / 10 ** 2`). + * + * Tokens usually opt for a value of 18, imitating the relationship between + * Ether and Wei. This is the default value returned by this function, unless + * it's overridden. + * + * NOTE: This information is only used for _display_ purposes: it in + * no way affects any of the arithmetic of the contract, including + * {IERC20-balanceOf} and {IERC20-transfer}. + */ + function decimals() public view virtual returns (uint8) { + return 18; + } + + /** + * @dev See {IERC20-totalSupply}. + */ + function totalSupply() public view virtual returns (uint256) { + return _totalSupply; + } + + /** + * @dev See {IERC20-balanceOf}. + */ + function balanceOf(address account) public view virtual returns (uint256) { + return _balances[account]; + } + + /** + * @dev See {IERC20-transfer}. + * + * Requirements: + * + * - `to` cannot be the zero address. + * - the caller must have a balance of at least `value`. + */ + function transfer(address to, uint256 value) public virtual returns (bool) { + address owner = _msgSender(); + _transfer(owner, to, value); + return true; + } + + /** + * @dev See {IERC20-allowance}. + */ + function allowance(address owner, address spender) public view virtual returns (uint256) { + return _allowances[owner][spender]; + } + + /** + * @dev See {IERC20-approve}. + * + * NOTE: If `value` is the maximum `uint256`, the allowance is not updated on + * `transferFrom`. This is semantically equivalent to an infinite approval. + * + * Requirements: + * + * - `spender` cannot be the zero address. + */ + function approve(address spender, uint256 value) public virtual returns (bool) { + address owner = _msgSender(); + _approve(owner, spender, value); + return true; + } + + /** + * @dev See {IERC20-transferFrom}. + * + * Emits an {Approval} event indicating the updated allowance. This is not + * required by the EIP. See the note at the beginning of {ERC20}. + * + * NOTE: Does not update the allowance if the current allowance + * is the maximum `uint256`. + * + * Requirements: + * + * - `from` and `to` cannot be the zero address. + * - `from` must have a balance of at least `value`. + * - the caller must have allowance for ``from``'s tokens of at least + * `value`. + */ + function transferFrom(address from, address to, uint256 value) public virtual returns (bool) { + address spender = _msgSender(); + _spendAllowance(from, spender, value); + _transfer(from, to, value); + return true; + } + + /** + * @dev Moves a `value` amount of tokens from `from` to `to`. + * + * This internal function is equivalent to {transfer}, and can be used to + * e.g. implement automatic token fees, slashing mechanisms, etc. + * + * Emits a {Transfer} event. + * + * NOTE: This function is not virtual, {_update} should be overridden instead. + */ + function _transfer(address from, address to, uint256 value) internal { + if (from == address(0)) { + revert ERC20InvalidSender(address(0)); + } + if (to == address(0)) { + revert ERC20InvalidReceiver(address(0)); + } + _update(from, to, value); + } + + /** + * @dev Transfers a `value` amount of tokens from `from` to `to`, or alternatively mints (or burns) if `from` + * (or `to`) is the zero address. All customizations to transfers, mints, and burns should be done by overriding + * this function. + * + * Emits a {Transfer} event. + */ + function _update(address from, address to, uint256 value) internal virtual { + if (from == address(0)) { + // Overflow check required: The rest of the code assumes that totalSupply never overflows + _totalSupply += value; + } else { + uint256 fromBalance = _balances[from]; + if (fromBalance < value) { + revert ERC20InsufficientBalance(from, fromBalance, value); + } + unchecked { + // Overflow not possible: value <= fromBalance <= totalSupply. + _balances[from] = fromBalance - value; + } + } + + if (to == address(0)) { + unchecked { + // Overflow not possible: value <= totalSupply or value <= fromBalance <= totalSupply. + _totalSupply -= value; + } + } else { + unchecked { + // Overflow not possible: balance + value is at most totalSupply, which we know fits into a uint256. + _balances[to] += value; + } + } + + emit Transfer(from, to, value); + } + + /** + * @dev Creates a `value` amount of tokens and assigns them to `account`, by transferring it from address(0). + * Relies on the `_update` mechanism + * + * Emits a {Transfer} event with `from` set to the zero address. + * + * NOTE: This function is not virtual, {_update} should be overridden instead. + */ + function _mint(address account, uint256 value) internal { + if (account == address(0)) { + revert ERC20InvalidReceiver(address(0)); + } + _update(address(0), account, value); + } + + /** + * @dev Destroys a `value` amount of tokens from `account`, lowering the total supply. + * Relies on the `_update` mechanism. + * + * Emits a {Transfer} event with `to` set to the zero address. + * + * NOTE: This function is not virtual, {_update} should be overridden instead + */ + function _burn(address account, uint256 value) internal { + if (account == address(0)) { + revert ERC20InvalidSender(address(0)); + } + _update(account, address(0), value); + } + + /** + * @dev Sets `value` as the allowance of `spender` over the `owner` s tokens. + * + * This internal function is equivalent to `approve`, and can be used to + * e.g. set automatic allowances for certain subsystems, etc. + * + * Emits an {Approval} event. + * + * Requirements: + * + * - `owner` cannot be the zero address. + * - `spender` cannot be the zero address. + * + * Overrides to this logic should be done to the variant with an additional `bool emitEvent` argument. + */ + function _approve(address owner, address spender, uint256 value) internal { + _approve(owner, spender, value, true); + } + + /** + * @dev Variant of {_approve} with an optional flag to enable or disable the {Approval} event. + * + * By default (when calling {_approve}) the flag is set to true. On the other hand, approval changes made by + * `_spendAllowance` during the `transferFrom` operation set the flag to false. This saves gas by not emitting any + * `Approval` event during `transferFrom` operations. + * + * Anyone who wishes to continue emitting `Approval` events on the`transferFrom` operation can force the flag to + * true using the following override: + * ``` + * function _approve(address owner, address spender, uint256 value, bool) internal virtual override { + * super._approve(owner, spender, value, true); + * } + * ``` + * + * Requirements are the same as {_approve}. + */ + function _approve(address owner, address spender, uint256 value, bool emitEvent) internal virtual { + if (owner == address(0)) { + revert ERC20InvalidApprover(address(0)); + } + if (spender == address(0)) { + revert ERC20InvalidSpender(address(0)); + } + _allowances[owner][spender] = value; + if (emitEvent) { + emit Approval(owner, spender, value); + } + } + + /** + * @dev Updates `owner` s allowance for `spender` based on spent `value`. + * + * Does not update the allowance value in case of infinite allowance. + * Revert if not enough allowance is available. + * + * Does not emit an {Approval} event. + */ + function _spendAllowance(address owner, address spender, uint256 value) internal virtual { + uint256 currentAllowance = allowance(owner, spender); + if (currentAllowance != type(uint256).max) { + if (currentAllowance < value) { + revert ERC20InsufficientAllowance(spender, currentAllowance, value); + } + unchecked { + _approve(owner, spender, currentAllowance - value, false); + } + } + } +} diff --git a/contracts/token/ERC20/IERC20.sol b/contracts/token/ERC20/IERC20.sol new file mode 100644 index 000000000..8b00999bf --- /dev/null +++ b/contracts/token/ERC20/IERC20.sol @@ -0,0 +1,79 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (token/ERC20/IERC20.sol) + +pragma solidity ^0.8.20; + +/** + * @dev Interface of the ERC20 standard as defined in the EIP. + */ +interface IERC20 { + /** + * @dev Emitted when `value` tokens are moved from one account (`from`) to + * another (`to`). + * + * Note that `value` may be zero. + */ + event Transfer(address indexed from, address indexed to, uint256 value); + + /** + * @dev Emitted when the allowance of a `spender` for an `owner` is set by + * a call to {approve}. `value` is the new allowance. + */ + event Approval(address indexed owner, address indexed spender, uint256 value); + + /** + * @dev Returns the value of tokens in existence. + */ + function totalSupply() external view returns (uint256); + + /** + * @dev Returns the value of tokens owned by `account`. + */ + function balanceOf(address account) external view returns (uint256); + + /** + * @dev Moves a `value` amount of tokens from the caller's account to `to`. + * + * Returns a boolean value indicating whether the operation succeeded. + * + * Emits a {Transfer} event. + */ + function transfer(address to, uint256 value) external returns (bool); + + /** + * @dev Returns the remaining number of tokens that `spender` will be + * allowed to spend on behalf of `owner` through {transferFrom}. This is + * zero by default. + * + * This value changes when {approve} or {transferFrom} are called. + */ + function allowance(address owner, address spender) external view returns (uint256); + + /** + * @dev Sets a `value` amount of tokens as the allowance of `spender` over the + * caller's tokens. + * + * Returns a boolean value indicating whether the operation succeeded. + * + * IMPORTANT: Beware that changing an allowance with this method brings the risk + * that someone may use both the old and the new allowance by unfortunate + * transaction ordering. One possible solution to mitigate this race + * condition is to first reduce the spender's allowance to 0 and set the + * desired value afterwards: + * https://github.com/ethereum/EIPs/issues/20#issuecomment-263524729 + * + * Emits an {Approval} event. + */ + function approve(address spender, uint256 value) external returns (bool); + + /** + * @dev Moves a `value` amount of tokens from `from` to `to` using the + * allowance mechanism. `value` is then deducted from the caller's + * allowance. + * + * Returns a boolean value indicating whether the operation succeeded. + * + * Emits a {Transfer} event. + */ + function transferFrom(address from, address to, uint256 value) external returns (bool); +} diff --git a/contracts/token/ERC20/README.adoc b/contracts/token/ERC20/README.adoc new file mode 100644 index 000000000..2c508802d --- /dev/null +++ b/contracts/token/ERC20/README.adoc @@ -0,0 +1,67 @@ += ERC 20 + +[.readme-notice] +NOTE: This document is better viewed at https://docs.openzeppelin.com/contracts/api/token/erc20 + +This set of interfaces, contracts, and utilities are all related to the https://eips.ethereum.org/EIPS/eip-20[ERC20 Token Standard]. + +TIP: For an overview of ERC20 tokens and a walk through on how to create a token contract read our xref:ROOT:erc20.adoc[ERC20 guide]. + +There are a few core contracts that implement the behavior specified in the EIP: + +* {IERC20}: the interface all ERC20 implementations should conform to. +* {IERC20Metadata}: the extended ERC20 interface including the <>, <> and <> functions. +* {ERC20}: the implementation of the ERC20 interface, including the <>, <> and <> optional standard extension to the base interface. + +Additionally there are multiple custom extensions, including: + +* {ERC20Permit}: gasless approval of tokens (standardized as ERC2612). +* {ERC20Burnable}: destruction of own tokens. +* {ERC20Capped}: enforcement of a cap to the total supply when minting tokens. +* {ERC20Pausable}: ability to pause token transfers. +* {ERC20FlashMint}: token level support for flash loans through the minting and burning of ephemeral tokens (standardized as ERC3156). +* {ERC20Votes}: support for voting and vote delegation. +* {ERC20Wrapper}: wrapper to create an ERC20 backed by another ERC20, with deposit and withdraw methods. Useful in conjunction with {ERC20Votes}. +* {ERC4626}: tokenized vault that manages shares (represented as ERC20) that are backed by assets (another ERC20). + +Finally, there are some utilities to interact with ERC20 contracts in various ways: + +* {SafeERC20}: a wrapper around the interface that eliminates the need to handle boolean return values. + +Other utilities that support ERC20 assets can be found in codebase: + +* ERC20 tokens can be timelocked (held tokens for a beneficiary until a specified time) or vested (released following a given schedule) using a {VestingWallet}. + +NOTE: This core set of contracts is designed to be unopinionated, allowing developers to access the internal functions in ERC20 (such as <>) and expose them as external functions in the way they prefer. + +== Core + +{{IERC20}} + +{{IERC20Metadata}} + +{{ERC20}} + +== Extensions + +{{IERC20Permit}} + +{{ERC20Permit}} + +{{ERC20Burnable}} + +{{ERC20Capped}} + +{{ERC20Pausable}} + +{{ERC20Votes}} + +{{ERC20Wrapper}} + +{{ERC20FlashMint}} + +{{ERC4626}} + +== Utilities + +{{SafeERC20}} diff --git a/contracts/token/ERC20/extensions/ERC20Burnable.sol b/contracts/token/ERC20/extensions/ERC20Burnable.sol new file mode 100644 index 000000000..05008641b --- /dev/null +++ b/contracts/token/ERC20/extensions/ERC20Burnable.sol @@ -0,0 +1,39 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (token/ERC20/extensions/ERC20Burnable.sol) + +pragma solidity ^0.8.20; + +import {ERC20} from "../ERC20.sol"; +import {Context} from "../../../utils/Context.sol"; + +/** + * @dev Extension of {ERC20} that allows token holders to destroy both their own + * tokens and those that they have an allowance for, in a way that can be + * recognized off-chain (via event analysis). + */ +abstract contract ERC20Burnable is Context, ERC20 { + /** + * @dev Destroys a `value` amount of tokens from the caller. + * + * See {ERC20-_burn}. + */ + function burn(uint256 value) public virtual { + _burn(_msgSender(), value); + } + + /** + * @dev Destroys a `value` amount of tokens from `account`, deducting from + * the caller's allowance. + * + * See {ERC20-_burn} and {ERC20-allowance}. + * + * Requirements: + * + * - the caller must have allowance for ``accounts``'s tokens of at least + * `value`. + */ + function burnFrom(address account, uint256 value) public virtual { + _spendAllowance(account, _msgSender(), value); + _burn(account, value); + } +} diff --git a/contracts/token/ERC20/extensions/ERC20Capped.sol b/contracts/token/ERC20/extensions/ERC20Capped.sol new file mode 100644 index 000000000..765f9c18e --- /dev/null +++ b/contracts/token/ERC20/extensions/ERC20Capped.sol @@ -0,0 +1,56 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (token/ERC20/extensions/ERC20Capped.sol) + +pragma solidity ^0.8.20; + +import {ERC20} from "../ERC20.sol"; + +/** + * @dev Extension of {ERC20} that adds a cap to the supply of tokens. + */ +abstract contract ERC20Capped is ERC20 { + uint256 private immutable _cap; + + /** + * @dev Total supply cap has been exceeded. + */ + error ERC20ExceededCap(uint256 increasedSupply, uint256 cap); + + /** + * @dev The supplied cap is not a valid cap. + */ + error ERC20InvalidCap(uint256 cap); + + /** + * @dev Sets the value of the `cap`. This value is immutable, it can only be + * set once during construction. + */ + constructor(uint256 cap_) { + if (cap_ == 0) { + revert ERC20InvalidCap(0); + } + _cap = cap_; + } + + /** + * @dev Returns the cap on the token's total supply. + */ + function cap() public view virtual returns (uint256) { + return _cap; + } + + /** + * @dev See {ERC20-_update}. + */ + function _update(address from, address to, uint256 value) internal virtual override { + super._update(from, to, value); + + if (from == address(0)) { + uint256 maxSupply = cap(); + uint256 supply = totalSupply(); + if (supply > maxSupply) { + revert ERC20ExceededCap(supply, maxSupply); + } + } + } +} diff --git a/contracts/token/ERC20/extensions/ERC20FlashMint.sol b/contracts/token/ERC20/extensions/ERC20FlashMint.sol new file mode 100644 index 000000000..1b9a53ca0 --- /dev/null +++ b/contracts/token/ERC20/extensions/ERC20FlashMint.sol @@ -0,0 +1,134 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (token/ERC20/extensions/ERC20FlashMint.sol) + +pragma solidity ^0.8.20; + +import {IERC3156FlashBorrower} from "../../../interfaces/IERC3156FlashBorrower.sol"; +import {IERC3156FlashLender} from "../../../interfaces/IERC3156FlashLender.sol"; +import {ERC20} from "../ERC20.sol"; + +/** + * @dev Implementation of the ERC3156 Flash loans extension, as defined in + * https://eips.ethereum.org/EIPS/eip-3156[ERC-3156]. + * + * Adds the {flashLoan} method, which provides flash loan support at the token + * level. By default there is no fee, but this can be changed by overriding {flashFee}. + * + * NOTE: When this extension is used along with the {ERC20Capped} or {ERC20Votes} extensions, + * {maxFlashLoan} will not correctly reflect the maximum that can be flash minted. We recommend + * overriding {maxFlashLoan} so that it correctly reflects the supply cap. + */ +abstract contract ERC20FlashMint is ERC20, IERC3156FlashLender { + bytes32 private constant RETURN_VALUE = keccak256("ERC3156FlashBorrower.onFlashLoan"); + + /** + * @dev The loan token is not valid. + */ + error ERC3156UnsupportedToken(address token); + + /** + * @dev The requested loan exceeds the max loan value for `token`. + */ + error ERC3156ExceededMaxLoan(uint256 maxLoan); + + /** + * @dev The receiver of a flashloan is not a valid {onFlashLoan} implementer. + */ + error ERC3156InvalidReceiver(address receiver); + + /** + * @dev Returns the maximum amount of tokens available for loan. + * @param token The address of the token that is requested. + * @return The amount of token that can be loaned. + * + * NOTE: This function does not consider any form of supply cap, so in case + * it's used in a token with a cap like {ERC20Capped}, make sure to override this + * function to integrate the cap instead of `type(uint256).max`. + */ + function maxFlashLoan(address token) public view virtual returns (uint256) { + return token == address(this) ? type(uint256).max - totalSupply() : 0; + } + + /** + * @dev Returns the fee applied when doing flash loans. This function calls + * the {_flashFee} function which returns the fee applied when doing flash + * loans. + * @param token The token to be flash loaned. + * @param value The amount of tokens to be loaned. + * @return The fees applied to the corresponding flash loan. + */ + function flashFee(address token, uint256 value) public view virtual returns (uint256) { + if (token != address(this)) { + revert ERC3156UnsupportedToken(token); + } + return _flashFee(token, value); + } + + /** + * @dev Returns the fee applied when doing flash loans. By default this + * implementation has 0 fees. This function can be overloaded to make + * the flash loan mechanism deflationary. + * @param token The token to be flash loaned. + * @param value The amount of tokens to be loaned. + * @return The fees applied to the corresponding flash loan. + */ + function _flashFee(address token, uint256 value) internal view virtual returns (uint256) { + // silence warning about unused variable without the addition of bytecode. + token; + value; + return 0; + } + + /** + * @dev Returns the receiver address of the flash fee. By default this + * implementation returns the address(0) which means the fee amount will be burnt. + * This function can be overloaded to change the fee receiver. + * @return The address for which the flash fee will be sent to. + */ + function _flashFeeReceiver() internal view virtual returns (address) { + return address(0); + } + + /** + * @dev Performs a flash loan. New tokens are minted and sent to the + * `receiver`, who is required to implement the {IERC3156FlashBorrower} + * interface. By the end of the flash loan, the receiver is expected to own + * value + fee tokens and have them approved back to the token contract itself so + * they can be burned. + * @param receiver The receiver of the flash loan. Should implement the + * {IERC3156FlashBorrower-onFlashLoan} interface. + * @param token The token to be flash loaned. Only `address(this)` is + * supported. + * @param value The amount of tokens to be loaned. + * @param data An arbitrary datafield that is passed to the receiver. + * @return `true` if the flash loan was successful. + */ + // This function can reenter, but it doesn't pose a risk because it always preserves the property that the amount + // minted at the beginning is always recovered and burned at the end, or else the entire function will revert. + // slither-disable-next-line reentrancy-no-eth + function flashLoan( + IERC3156FlashBorrower receiver, + address token, + uint256 value, + bytes calldata data + ) public virtual returns (bool) { + uint256 maxLoan = maxFlashLoan(token); + if (value > maxLoan) { + revert ERC3156ExceededMaxLoan(maxLoan); + } + uint256 fee = flashFee(token, value); + _mint(address(receiver), value); + if (receiver.onFlashLoan(_msgSender(), token, value, fee, data) != RETURN_VALUE) { + revert ERC3156InvalidReceiver(address(receiver)); + } + address flashFeeReceiver = _flashFeeReceiver(); + _spendAllowance(address(receiver), address(this), value + fee); + if (fee == 0 || flashFeeReceiver == address(0)) { + _burn(address(receiver), value + fee); + } else { + _burn(address(receiver), value); + _transfer(address(receiver), flashFeeReceiver, fee); + } + return true; + } +} diff --git a/contracts/token/ERC20/extensions/ERC20Pausable.sol b/contracts/token/ERC20/extensions/ERC20Pausable.sol new file mode 100644 index 000000000..db0c0a535 --- /dev/null +++ b/contracts/token/ERC20/extensions/ERC20Pausable.sol @@ -0,0 +1,33 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (token/ERC20/extensions/ERC20Pausable.sol) + +pragma solidity ^0.8.20; + +import {ERC20} from "../ERC20.sol"; +import {Pausable} from "../../../utils/Pausable.sol"; + +/** + * @dev ERC20 token with pausable token transfers, minting and burning. + * + * Useful for scenarios such as preventing trades until the end of an evaluation + * period, or having an emergency switch for freezing all token transfers in the + * event of a large bug. + * + * IMPORTANT: This contract does not include public pause and unpause functions. In + * addition to inheriting this contract, you must define both functions, invoking the + * {Pausable-_pause} and {Pausable-_unpause} internal functions, with appropriate + * access control, e.g. using {AccessControl} or {Ownable}. Not doing so will + * make the contract pause mechanism of the contract unreachable, and thus unusable. + */ +abstract contract ERC20Pausable is ERC20, Pausable { + /** + * @dev See {ERC20-_update}. + * + * Requirements: + * + * - the contract must not be paused. + */ + function _update(address from, address to, uint256 value) internal virtual override whenNotPaused { + super._update(from, to, value); + } +} diff --git a/contracts/token/ERC20/extensions/ERC20Permit.sol b/contracts/token/ERC20/extensions/ERC20Permit.sol new file mode 100644 index 000000000..f9d1b49e7 --- /dev/null +++ b/contracts/token/ERC20/extensions/ERC20Permit.sol @@ -0,0 +1,83 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (token/ERC20/extensions/ERC20Permit.sol) + +pragma solidity ^0.8.20; + +import {IERC20Permit} from "./IERC20Permit.sol"; +import {ERC20} from "../ERC20.sol"; +import {ECDSA} from "../../../utils/cryptography/ECDSA.sol"; +import {EIP712} from "../../../utils/cryptography/EIP712.sol"; +import {Nonces} from "../../../utils/Nonces.sol"; + +/** + * @dev Implementation of the ERC20 Permit extension allowing approvals to be made via signatures, as defined in + * https://eips.ethereum.org/EIPS/eip-2612[EIP-2612]. + * + * Adds the {permit} method, which can be used to change an account's ERC20 allowance (see {IERC20-allowance}) by + * presenting a message signed by the account. By not relying on `{IERC20-approve}`, the token holder account doesn't + * need to send a transaction, and thus is not required to hold Ether at all. + */ +abstract contract ERC20Permit is ERC20, IERC20Permit, EIP712, Nonces { + bytes32 private constant PERMIT_TYPEHASH = + keccak256("Permit(address owner,address spender,uint256 value,uint256 nonce,uint256 deadline)"); + + /** + * @dev Permit deadline has expired. + */ + error ERC2612ExpiredSignature(uint256 deadline); + + /** + * @dev Mismatched signature. + */ + error ERC2612InvalidSigner(address signer, address owner); + + /** + * @dev Initializes the {EIP712} domain separator using the `name` parameter, and setting `version` to `"1"`. + * + * It's a good idea to use the same `name` that is defined as the ERC20 token name. + */ + constructor(string memory name) EIP712(name, "1") {} + + /** + * @inheritdoc IERC20Permit + */ + function permit( + address owner, + address spender, + uint256 value, + uint256 deadline, + uint8 v, + bytes32 r, + bytes32 s + ) public virtual { + if (block.timestamp > deadline) { + revert ERC2612ExpiredSignature(deadline); + } + + bytes32 structHash = keccak256(abi.encode(PERMIT_TYPEHASH, owner, spender, value, _useNonce(owner), deadline)); + + bytes32 hash = _hashTypedDataV4(structHash); + + address signer = ECDSA.recover(hash, v, r, s); + if (signer != owner) { + revert ERC2612InvalidSigner(signer, owner); + } + + _approve(owner, spender, value); + } + + /** + * @inheritdoc IERC20Permit + */ + function nonces(address owner) public view virtual override(IERC20Permit, Nonces) returns (uint256) { + return super.nonces(owner); + } + + /** + * @inheritdoc IERC20Permit + */ + // solhint-disable-next-line func-name-mixedcase + function DOMAIN_SEPARATOR() external view virtual returns (bytes32) { + return _domainSeparatorV4(); + } +} diff --git a/contracts/token/ERC20/extensions/ERC20Votes.sol b/contracts/token/ERC20/extensions/ERC20Votes.sol new file mode 100644 index 000000000..a3081bdce --- /dev/null +++ b/contracts/token/ERC20/extensions/ERC20Votes.sol @@ -0,0 +1,83 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (token/ERC20/extensions/ERC20Votes.sol) + +pragma solidity ^0.8.20; + +import {ERC20} from "../ERC20.sol"; +import {Votes} from "../../../governance/utils/Votes.sol"; +import {Checkpoints} from "../../../utils/structs/Checkpoints.sol"; + +/** + * @dev Extension of ERC20 to support Compound-like voting and delegation. This version is more generic than Compound's, + * and supports token supply up to 2^208^ - 1, while COMP is limited to 2^96^ - 1. + * + * NOTE: This contract does not provide interface compatibility with Compound's COMP token. + * + * This extension keeps a history (checkpoints) of each account's vote power. Vote power can be delegated either + * by calling the {delegate} function directly, or by providing a signature to be used with {delegateBySig}. Voting + * power can be queried through the public accessors {getVotes} and {getPastVotes}. + * + * By default, token balance does not account for voting power. This makes transfers cheaper. The downside is that it + * requires users to delegate to themselves in order to activate checkpoints and have their voting power tracked. + */ +abstract contract ERC20Votes is ERC20, Votes { + /** + * @dev Total supply cap has been exceeded, introducing a risk of votes overflowing. + */ + error ERC20ExceededSafeSupply(uint256 increasedSupply, uint256 cap); + + /** + * @dev Maximum token supply. Defaults to `type(uint208).max` (2^208^ - 1). + * + * This maximum is enforced in {_update}. It limits the total supply of the token, which is otherwise a uint256, + * so that checkpoints can be stored in the Trace208 structure used by {{Votes}}. Increasing this value will not + * remove the underlying limitation, and will cause {_update} to fail because of a math overflow in + * {_transferVotingUnits}. An override could be used to further restrict the total supply (to a lower value) if + * additional logic requires it. When resolving override conflicts on this function, the minimum should be + * returned. + */ + function _maxSupply() internal view virtual returns (uint256) { + return type(uint208).max; + } + + /** + * @dev Move voting power when tokens are transferred. + * + * Emits a {IVotes-DelegateVotesChanged} event. + */ + function _update(address from, address to, uint256 value) internal virtual override { + super._update(from, to, value); + if (from == address(0)) { + uint256 supply = totalSupply(); + uint256 cap = _maxSupply(); + if (supply > cap) { + revert ERC20ExceededSafeSupply(supply, cap); + } + } + _transferVotingUnits(from, to, value); + } + + /** + * @dev Returns the voting units of an `account`. + * + * WARNING: Overriding this function may compromise the internal vote accounting. + * `ERC20Votes` assumes tokens map to voting units 1:1 and this is not easy to change. + */ + function _getVotingUnits(address account) internal view virtual override returns (uint256) { + return balanceOf(account); + } + + /** + * @dev Get number of checkpoints for `account`. + */ + function numCheckpoints(address account) public view virtual returns (uint32) { + return _numCheckpoints(account); + } + + /** + * @dev Get the `pos`-th checkpoint for `account`. + */ + function checkpoints(address account, uint32 pos) public view virtual returns (Checkpoints.Checkpoint208 memory) { + return _checkpoints(account, pos); + } +} diff --git a/contracts/token/ERC20/extensions/ERC20Wrapper.sol b/contracts/token/ERC20/extensions/ERC20Wrapper.sol new file mode 100644 index 000000000..0d4ec867a --- /dev/null +++ b/contracts/token/ERC20/extensions/ERC20Wrapper.sol @@ -0,0 +1,86 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (token/ERC20/extensions/ERC20Wrapper.sol) + +pragma solidity ^0.8.20; + +import {IERC20, IERC20Metadata, ERC20} from "../ERC20.sol"; +import {SafeERC20} from "../utils/SafeERC20.sol"; + +/** + * @dev Extension of the ERC20 token contract to support token wrapping. + * + * Users can deposit and withdraw "underlying tokens" and receive a matching number of "wrapped tokens". This is useful + * in conjunction with other modules. For example, combining this wrapping mechanism with {ERC20Votes} will allow the + * wrapping of an existing "basic" ERC20 into a governance token. + */ +abstract contract ERC20Wrapper is ERC20 { + IERC20 private immutable _underlying; + + /** + * @dev The underlying token couldn't be wrapped. + */ + error ERC20InvalidUnderlying(address token); + + constructor(IERC20 underlyingToken) { + if (underlyingToken == this) { + revert ERC20InvalidUnderlying(address(this)); + } + _underlying = underlyingToken; + } + + /** + * @dev See {ERC20-decimals}. + */ + function decimals() public view virtual override returns (uint8) { + try IERC20Metadata(address(_underlying)).decimals() returns (uint8 value) { + return value; + } catch { + return super.decimals(); + } + } + + /** + * @dev Returns the address of the underlying ERC-20 token that is being wrapped. + */ + function underlying() public view returns (IERC20) { + return _underlying; + } + + /** + * @dev Allow a user to deposit underlying tokens and mint the corresponding number of wrapped tokens. + */ + function depositFor(address account, uint256 value) public virtual returns (bool) { + address sender = _msgSender(); + if (sender == address(this)) { + revert ERC20InvalidSender(address(this)); + } + if (account == address(this)) { + revert ERC20InvalidReceiver(account); + } + SafeERC20.safeTransferFrom(_underlying, sender, address(this), value); + _mint(account, value); + return true; + } + + /** + * @dev Allow a user to burn a number of wrapped tokens and withdraw the corresponding number of underlying tokens. + */ + function withdrawTo(address account, uint256 value) public virtual returns (bool) { + if (account == address(this)) { + revert ERC20InvalidReceiver(account); + } + _burn(_msgSender(), value); + SafeERC20.safeTransfer(_underlying, account, value); + return true; + } + + /** + * @dev Mint wrapped token to cover any underlyingTokens that would have been transferred by mistake. Internal + * function that can be exposed with access control if desired. + */ + function _recover(address account) internal virtual returns (uint256) { + uint256 value = _underlying.balanceOf(address(this)) - totalSupply(); + _mint(account, value); + return value; + } +} diff --git a/contracts/token/ERC20/extensions/ERC4626.sol b/contracts/token/ERC20/extensions/ERC4626.sol new file mode 100644 index 000000000..bded3b497 --- /dev/null +++ b/contracts/token/ERC20/extensions/ERC4626.sol @@ -0,0 +1,286 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (token/ERC20/extensions/ERC4626.sol) + +pragma solidity ^0.8.20; + +import {IERC20, IERC20Metadata, ERC20} from "../ERC20.sol"; +import {SafeERC20} from "../utils/SafeERC20.sol"; +import {IERC4626} from "../../../interfaces/IERC4626.sol"; +import {Math} from "../../../utils/math/Math.sol"; + +/** + * @dev Implementation of the ERC4626 "Tokenized Vault Standard" as defined in + * https://eips.ethereum.org/EIPS/eip-4626[EIP-4626]. + * + * This extension allows the minting and burning of "shares" (represented using the ERC20 inheritance) in exchange for + * underlying "assets" through standardized {deposit}, {mint}, {redeem} and {burn} workflows. This contract extends + * the ERC20 standard. Any additional extensions included along it would affect the "shares" token represented by this + * contract and not the "assets" token which is an independent contract. + * + * [CAUTION] + * ==== + * In empty (or nearly empty) ERC-4626 vaults, deposits are at high risk of being stolen through frontrunning + * with a "donation" to the vault that inflates the price of a share. This is variously known as a donation or inflation + * attack and is essentially a problem of slippage. Vault deployers can protect against this attack by making an initial + * deposit of a non-trivial amount of the asset, such that price manipulation becomes infeasible. Withdrawals may + * similarly be affected by slippage. Users can protect against this attack as well as unexpected slippage in general by + * verifying the amount received is as expected, using a wrapper that performs these checks such as + * https://github.com/fei-protocol/ERC4626#erc4626router-and-base[ERC4626Router]. + * + * Since v4.9, this implementation uses virtual assets and shares to mitigate that risk. The `_decimalsOffset()` + * corresponds to an offset in the decimal representation between the underlying asset's decimals and the vault + * decimals. This offset also determines the rate of virtual shares to virtual assets in the vault, which itself + * determines the initial exchange rate. While not fully preventing the attack, analysis shows that the default offset + * (0) makes it non-profitable, as a result of the value being captured by the virtual shares (out of the attacker's + * donation) matching the attacker's expected gains. With a larger offset, the attack becomes orders of magnitude more + * expensive than it is profitable. More details about the underlying math can be found + * xref:erc4626.adoc#inflation-attack[here]. + * + * The drawback of this approach is that the virtual shares do capture (a very small) part of the value being accrued + * to the vault. Also, if the vault experiences losses, the users try to exit the vault, the virtual shares and assets + * will cause the first user to exit to experience reduced losses in detriment to the last users that will experience + * bigger losses. Developers willing to revert back to the pre-v4.9 behavior just need to override the + * `_convertToShares` and `_convertToAssets` functions. + * + * To learn more, check out our xref:ROOT:erc4626.adoc[ERC-4626 guide]. + * ==== + */ +abstract contract ERC4626 is ERC20, IERC4626 { + using Math for uint256; + + IERC20 private immutable _asset; + uint8 private immutable _underlyingDecimals; + + /** + * @dev Attempted to deposit more assets than the max amount for `receiver`. + */ + error ERC4626ExceededMaxDeposit(address receiver, uint256 assets, uint256 max); + + /** + * @dev Attempted to mint more shares than the max amount for `receiver`. + */ + error ERC4626ExceededMaxMint(address receiver, uint256 shares, uint256 max); + + /** + * @dev Attempted to withdraw more assets than the max amount for `receiver`. + */ + error ERC4626ExceededMaxWithdraw(address owner, uint256 assets, uint256 max); + + /** + * @dev Attempted to redeem more shares than the max amount for `receiver`. + */ + error ERC4626ExceededMaxRedeem(address owner, uint256 shares, uint256 max); + + /** + * @dev Set the underlying asset contract. This must be an ERC20-compatible contract (ERC20 or ERC777). + */ + constructor(IERC20 asset_) { + (bool success, uint8 assetDecimals) = _tryGetAssetDecimals(asset_); + _underlyingDecimals = success ? assetDecimals : 18; + _asset = asset_; + } + + /** + * @dev Attempts to fetch the asset decimals. A return value of false indicates that the attempt failed in some way. + */ + function _tryGetAssetDecimals(IERC20 asset_) private view returns (bool, uint8) { + (bool success, bytes memory encodedDecimals) = address(asset_).staticcall( + abi.encodeCall(IERC20Metadata.decimals, ()) + ); + if (success && encodedDecimals.length >= 32) { + uint256 returnedDecimals = abi.decode(encodedDecimals, (uint256)); + if (returnedDecimals <= type(uint8).max) { + return (true, uint8(returnedDecimals)); + } + } + return (false, 0); + } + + /** + * @dev Decimals are computed by adding the decimal offset on top of the underlying asset's decimals. This + * "original" value is cached during construction of the vault contract. If this read operation fails (e.g., the + * asset has not been created yet), a default of 18 is used to represent the underlying asset's decimals. + * + * See {IERC20Metadata-decimals}. + */ + function decimals() public view virtual override(IERC20Metadata, ERC20) returns (uint8) { + return _underlyingDecimals + _decimalsOffset(); + } + + /** @dev See {IERC4626-asset}. */ + function asset() public view virtual returns (address) { + return address(_asset); + } + + /** @dev See {IERC4626-totalAssets}. */ + function totalAssets() public view virtual returns (uint256) { + return _asset.balanceOf(address(this)); + } + + /** @dev See {IERC4626-convertToShares}. */ + function convertToShares(uint256 assets) public view virtual returns (uint256) { + return _convertToShares(assets, Math.Rounding.Floor); + } + + /** @dev See {IERC4626-convertToAssets}. */ + function convertToAssets(uint256 shares) public view virtual returns (uint256) { + return _convertToAssets(shares, Math.Rounding.Floor); + } + + /** @dev See {IERC4626-maxDeposit}. */ + function maxDeposit(address) public view virtual returns (uint256) { + return type(uint256).max; + } + + /** @dev See {IERC4626-maxMint}. */ + function maxMint(address) public view virtual returns (uint256) { + return type(uint256).max; + } + + /** @dev See {IERC4626-maxWithdraw}. */ + function maxWithdraw(address owner) public view virtual returns (uint256) { + return _convertToAssets(balanceOf(owner), Math.Rounding.Floor); + } + + /** @dev See {IERC4626-maxRedeem}. */ + function maxRedeem(address owner) public view virtual returns (uint256) { + return balanceOf(owner); + } + + /** @dev See {IERC4626-previewDeposit}. */ + function previewDeposit(uint256 assets) public view virtual returns (uint256) { + return _convertToShares(assets, Math.Rounding.Floor); + } + + /** @dev See {IERC4626-previewMint}. */ + function previewMint(uint256 shares) public view virtual returns (uint256) { + return _convertToAssets(shares, Math.Rounding.Ceil); + } + + /** @dev See {IERC4626-previewWithdraw}. */ + function previewWithdraw(uint256 assets) public view virtual returns (uint256) { + return _convertToShares(assets, Math.Rounding.Ceil); + } + + /** @dev See {IERC4626-previewRedeem}. */ + function previewRedeem(uint256 shares) public view virtual returns (uint256) { + return _convertToAssets(shares, Math.Rounding.Floor); + } + + /** @dev See {IERC4626-deposit}. */ + function deposit(uint256 assets, address receiver) public virtual returns (uint256) { + uint256 maxAssets = maxDeposit(receiver); + if (assets > maxAssets) { + revert ERC4626ExceededMaxDeposit(receiver, assets, maxAssets); + } + + uint256 shares = previewDeposit(assets); + _deposit(_msgSender(), receiver, assets, shares); + + return shares; + } + + /** @dev See {IERC4626-mint}. + * + * As opposed to {deposit}, minting is allowed even if the vault is in a state where the price of a share is zero. + * In this case, the shares will be minted without requiring any assets to be deposited. + */ + function mint(uint256 shares, address receiver) public virtual returns (uint256) { + uint256 maxShares = maxMint(receiver); + if (shares > maxShares) { + revert ERC4626ExceededMaxMint(receiver, shares, maxShares); + } + + uint256 assets = previewMint(shares); + _deposit(_msgSender(), receiver, assets, shares); + + return assets; + } + + /** @dev See {IERC4626-withdraw}. */ + function withdraw(uint256 assets, address receiver, address owner) public virtual returns (uint256) { + uint256 maxAssets = maxWithdraw(owner); + if (assets > maxAssets) { + revert ERC4626ExceededMaxWithdraw(owner, assets, maxAssets); + } + + uint256 shares = previewWithdraw(assets); + _withdraw(_msgSender(), receiver, owner, assets, shares); + + return shares; + } + + /** @dev See {IERC4626-redeem}. */ + function redeem(uint256 shares, address receiver, address owner) public virtual returns (uint256) { + uint256 maxShares = maxRedeem(owner); + if (shares > maxShares) { + revert ERC4626ExceededMaxRedeem(owner, shares, maxShares); + } + + uint256 assets = previewRedeem(shares); + _withdraw(_msgSender(), receiver, owner, assets, shares); + + return assets; + } + + /** + * @dev Internal conversion function (from assets to shares) with support for rounding direction. + */ + function _convertToShares(uint256 assets, Math.Rounding rounding) internal view virtual returns (uint256) { + return assets.mulDiv(totalSupply() + 10 ** _decimalsOffset(), totalAssets() + 1, rounding); + } + + /** + * @dev Internal conversion function (from shares to assets) with support for rounding direction. + */ + function _convertToAssets(uint256 shares, Math.Rounding rounding) internal view virtual returns (uint256) { + return shares.mulDiv(totalAssets() + 1, totalSupply() + 10 ** _decimalsOffset(), rounding); + } + + /** + * @dev Deposit/mint common workflow. + */ + function _deposit(address caller, address receiver, uint256 assets, uint256 shares) internal virtual { + // If _asset is ERC777, `transferFrom` can trigger a reentrancy BEFORE the transfer happens through the + // `tokensToSend` hook. On the other hand, the `tokenReceived` hook, that is triggered after the transfer, + // calls the vault, which is assumed not malicious. + // + // Conclusion: we need to do the transfer before we mint so that any reentrancy would happen before the + // assets are transferred and before the shares are minted, which is a valid state. + // slither-disable-next-line reentrancy-no-eth + SafeERC20.safeTransferFrom(_asset, caller, address(this), assets); + _mint(receiver, shares); + + emit Deposit(caller, receiver, assets, shares); + } + + /** + * @dev Withdraw/redeem common workflow. + */ + function _withdraw( + address caller, + address receiver, + address owner, + uint256 assets, + uint256 shares + ) internal virtual { + if (caller != owner) { + _spendAllowance(owner, caller, shares); + } + + // If _asset is ERC777, `transfer` can trigger a reentrancy AFTER the transfer happens through the + // `tokensReceived` hook. On the other hand, the `tokensToSend` hook, that is triggered before the transfer, + // calls the vault, which is assumed not malicious. + // + // Conclusion: we need to do the transfer after the burn so that any reentrancy would happen after the + // shares are burned and after the assets are transferred, which is a valid state. + _burn(owner, shares); + SafeERC20.safeTransfer(_asset, receiver, assets); + + emit Withdraw(caller, receiver, owner, assets, shares); + } + + function _decimalsOffset() internal view virtual returns (uint8) { + return 0; + } +} diff --git a/contracts/token/ERC20/extensions/IERC20Metadata.sol b/contracts/token/ERC20/extensions/IERC20Metadata.sol new file mode 100644 index 000000000..14dd7257f --- /dev/null +++ b/contracts/token/ERC20/extensions/IERC20Metadata.sol @@ -0,0 +1,26 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (token/ERC20/extensions/IERC20Metadata.sol) + +pragma solidity ^0.8.20; + +import {IERC20} from "../IERC20.sol"; + +/** + * @dev Interface for the optional metadata functions from the ERC20 standard. + */ +interface IERC20Metadata is IERC20 { + /** + * @dev Returns the name of the token. + */ + function name() external view returns (string memory); + + /** + * @dev Returns the symbol of the token. + */ + function symbol() external view returns (string memory); + + /** + * @dev Returns the decimals places of the token. + */ + function decimals() external view returns (uint8); +} diff --git a/contracts/token/ERC20/extensions/IERC20Permit.sol b/contracts/token/ERC20/extensions/IERC20Permit.sol new file mode 100644 index 000000000..40ae7ba7b --- /dev/null +++ b/contracts/token/ERC20/extensions/IERC20Permit.sol @@ -0,0 +1,90 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (token/ERC20/extensions/IERC20Permit.sol) + +pragma solidity ^0.8.20; + +/** + * @dev Interface of the ERC20 Permit extension allowing approvals to be made via signatures, as defined in + * https://eips.ethereum.org/EIPS/eip-2612[EIP-2612]. + * + * Adds the {permit} method, which can be used to change an account's ERC20 allowance (see {IERC20-allowance}) by + * presenting a message signed by the account. By not relying on {IERC20-approve}, the token holder account doesn't + * need to send a transaction, and thus is not required to hold Ether at all. + * + * ==== Security Considerations + * + * There are two important considerations concerning the use of `permit`. The first is that a valid permit signature + * expresses an allowance, and it should not be assumed to convey additional meaning. In particular, it should not be + * considered as an intention to spend the allowance in any specific way. The second is that because permits have + * built-in replay protection and can be submitted by anyone, they can be frontrun. A protocol that uses permits should + * take this into consideration and allow a `permit` call to fail. Combining these two aspects, a pattern that may be + * generally recommended is: + * + * ```solidity + * function doThingWithPermit(..., uint256 value, uint256 deadline, uint8 v, bytes32 r, bytes32 s) public { + * try token.permit(msg.sender, address(this), value, deadline, v, r, s) {} catch {} + * doThing(..., value); + * } + * + * function doThing(..., uint256 value) public { + * token.safeTransferFrom(msg.sender, address(this), value); + * ... + * } + * ``` + * + * Observe that: 1) `msg.sender` is used as the owner, leaving no ambiguity as to the signer intent, and 2) the use of + * `try/catch` allows the permit to fail and makes the code tolerant to frontrunning. (See also + * {SafeERC20-safeTransferFrom}). + * + * Additionally, note that smart contract wallets (such as Argent or Safe) are not able to produce permit signatures, so + * contracts should have entry points that don't rely on permit. + */ +interface IERC20Permit { + /** + * @dev Sets `value` as the allowance of `spender` over ``owner``'s tokens, + * given ``owner``'s signed approval. + * + * IMPORTANT: The same issues {IERC20-approve} has related to transaction + * ordering also apply here. + * + * Emits an {Approval} event. + * + * Requirements: + * + * - `spender` cannot be the zero address. + * - `deadline` must be a timestamp in the future. + * - `v`, `r` and `s` must be a valid `secp256k1` signature from `owner` + * over the EIP712-formatted function arguments. + * - the signature must use ``owner``'s current nonce (see {nonces}). + * + * For more information on the signature format, see the + * https://eips.ethereum.org/EIPS/eip-2612#specification[relevant EIP + * section]. + * + * CAUTION: See Security Considerations above. + */ + function permit( + address owner, + address spender, + uint256 value, + uint256 deadline, + uint8 v, + bytes32 r, + bytes32 s + ) external; + + /** + * @dev Returns the current nonce for `owner`. This value must be + * included whenever a signature is generated for {permit}. + * + * Every successful call to {permit} increases ``owner``'s nonce by one. This + * prevents a signature from being used multiple times. + */ + function nonces(address owner) external view returns (uint256); + + /** + * @dev Returns the domain separator used in the encoding of the signature for {permit}, as defined by {EIP712}. + */ + // solhint-disable-next-line func-name-mixedcase + function DOMAIN_SEPARATOR() external view returns (bytes32); +} diff --git a/contracts/token/ERC20/utils/SafeERC20.sol b/contracts/token/ERC20/utils/SafeERC20.sol new file mode 100644 index 000000000..af8115957 --- /dev/null +++ b/contracts/token/ERC20/utils/SafeERC20.sol @@ -0,0 +1,118 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (token/ERC20/utils/SafeERC20.sol) + +pragma solidity ^0.8.20; + +import {IERC20} from "../IERC20.sol"; +import {IERC20Permit} from "../extensions/IERC20Permit.sol"; +import {Address} from "../../../utils/Address.sol"; + +/** + * @title SafeERC20 + * @dev Wrappers around ERC20 operations that throw on failure (when the token + * contract returns false). Tokens that return no value (and instead revert or + * throw on failure) are also supported, non-reverting calls are assumed to be + * successful. + * To use this library you can add a `using SafeERC20 for IERC20;` statement to your contract, + * which allows you to call the safe operations as `token.safeTransfer(...)`, etc. + */ +library SafeERC20 { + using Address for address; + + /** + * @dev An operation with an ERC20 token failed. + */ + error SafeERC20FailedOperation(address token); + + /** + * @dev Indicates a failed `decreaseAllowance` request. + */ + error SafeERC20FailedDecreaseAllowance(address spender, uint256 currentAllowance, uint256 requestedDecrease); + + /** + * @dev Transfer `value` amount of `token` from the calling contract to `to`. If `token` returns no value, + * non-reverting calls are assumed to be successful. + */ + function safeTransfer(IERC20 token, address to, uint256 value) internal { + _callOptionalReturn(token, abi.encodeCall(token.transfer, (to, value))); + } + + /** + * @dev Transfer `value` amount of `token` from `from` to `to`, spending the approval given by `from` to the + * calling contract. If `token` returns no value, non-reverting calls are assumed to be successful. + */ + function safeTransferFrom(IERC20 token, address from, address to, uint256 value) internal { + _callOptionalReturn(token, abi.encodeCall(token.transferFrom, (from, to, value))); + } + + /** + * @dev Increase the calling contract's allowance toward `spender` by `value`. If `token` returns no value, + * non-reverting calls are assumed to be successful. + */ + function safeIncreaseAllowance(IERC20 token, address spender, uint256 value) internal { + uint256 oldAllowance = token.allowance(address(this), spender); + forceApprove(token, spender, oldAllowance + value); + } + + /** + * @dev Decrease the calling contract's allowance toward `spender` by `requestedDecrease`. If `token` returns no + * value, non-reverting calls are assumed to be successful. + */ + function safeDecreaseAllowance(IERC20 token, address spender, uint256 requestedDecrease) internal { + unchecked { + uint256 currentAllowance = token.allowance(address(this), spender); + if (currentAllowance < requestedDecrease) { + revert SafeERC20FailedDecreaseAllowance(spender, currentAllowance, requestedDecrease); + } + forceApprove(token, spender, currentAllowance - requestedDecrease); + } + } + + /** + * @dev Set the calling contract's allowance toward `spender` to `value`. If `token` returns no value, + * non-reverting calls are assumed to be successful. Meant to be used with tokens that require the approval + * to be set to zero before setting it to a non-zero value, such as USDT. + */ + function forceApprove(IERC20 token, address spender, uint256 value) internal { + bytes memory approvalCall = abi.encodeCall(token.approve, (spender, value)); + + if (!_callOptionalReturnBool(token, approvalCall)) { + _callOptionalReturn(token, abi.encodeCall(token.approve, (spender, 0))); + _callOptionalReturn(token, approvalCall); + } + } + + /** + * @dev Imitates a Solidity high-level call (i.e. a regular function call to a contract), relaxing the requirement + * on the return value: the return value is optional (but if data is returned, it must not be false). + * @param token The token targeted by the call. + * @param data The call data (encoded using abi.encode or one of its variants). + */ + function _callOptionalReturn(IERC20 token, bytes memory data) private { + // We need to perform a low level call here, to bypass Solidity's return data size checking mechanism, since + // we're implementing it ourselves. We use {Address-functionCall} to perform this call, which verifies that + // the target address contains contract code and also asserts for success in the low-level call. + + bytes memory returndata = address(token).functionCall(data); + if (returndata.length != 0 && !abi.decode(returndata, (bool))) { + revert SafeERC20FailedOperation(address(token)); + } + } + + /** + * @dev Imitates a Solidity high-level call (i.e. a regular function call to a contract), relaxing the requirement + * on the return value: the return value is optional (but if data is returned, it must not be false). + * @param token The token targeted by the call. + * @param data The call data (encoded using abi.encode or one of its variants). + * + * This is a variant of {_callOptionalReturn} that silents catches all reverts and returns a bool instead. + */ + function _callOptionalReturnBool(IERC20 token, bytes memory data) private returns (bool) { + // We need to perform a low level call here, to bypass Solidity's return data size checking mechanism, since + // we're implementing it ourselves. We cannot use {Address-functionCall} here since this should return false + // and not revert is the subcall reverts. + + (bool success, bytes memory returndata) = address(token).call(data); + return success && (returndata.length == 0 || abi.decode(returndata, (bool))) && address(token).code.length > 0; + } +} diff --git a/contracts/token/ERC721/ERC721.sol b/contracts/token/ERC721/ERC721.sol new file mode 100644 index 000000000..b912797d3 --- /dev/null +++ b/contracts/token/ERC721/ERC721.sol @@ -0,0 +1,483 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (token/ERC721/ERC721.sol) + +pragma solidity ^0.8.20; + +import {IERC721} from "./IERC721.sol"; +import {IERC721Receiver} from "./IERC721Receiver.sol"; +import {IERC721Metadata} from "./extensions/IERC721Metadata.sol"; +import {Context} from "../../utils/Context.sol"; +import {Strings} from "../../utils/Strings.sol"; +import {IERC165, ERC165} from "../../utils/introspection/ERC165.sol"; +import {IERC721Errors} from "../../interfaces/draft-IERC6093.sol"; + +/** + * @dev Implementation of https://eips.ethereum.org/EIPS/eip-721[ERC721] Non-Fungible Token Standard, including + * the Metadata extension, but not including the Enumerable extension, which is available separately as + * {ERC721Enumerable}. + */ +abstract contract ERC721 is Context, ERC165, IERC721, IERC721Metadata, IERC721Errors { + using Strings for uint256; + + // Token name + string private _name; + + // Token symbol + string private _symbol; + + mapping(uint256 tokenId => address) private _owners; + + mapping(address owner => uint256) private _balances; + + mapping(uint256 tokenId => address) private _tokenApprovals; + + mapping(address owner => mapping(address operator => bool)) private _operatorApprovals; + + /** + * @dev Initializes the contract by setting a `name` and a `symbol` to the token collection. + */ + constructor(string memory name_, string memory symbol_) { + _name = name_; + _symbol = symbol_; + } + + /** + * @dev See {IERC165-supportsInterface}. + */ + function supportsInterface(bytes4 interfaceId) public view virtual override(ERC165, IERC165) returns (bool) { + return + interfaceId == type(IERC721).interfaceId || + interfaceId == type(IERC721Metadata).interfaceId || + super.supportsInterface(interfaceId); + } + + /** + * @dev See {IERC721-balanceOf}. + */ + function balanceOf(address owner) public view virtual returns (uint256) { + if (owner == address(0)) { + revert ERC721InvalidOwner(address(0)); + } + return _balances[owner]; + } + + /** + * @dev See {IERC721-ownerOf}. + */ + function ownerOf(uint256 tokenId) public view virtual returns (address) { + return _requireOwned(tokenId); + } + + /** + * @dev See {IERC721Metadata-name}. + */ + function name() public view virtual returns (string memory) { + return _name; + } + + /** + * @dev See {IERC721Metadata-symbol}. + */ + function symbol() public view virtual returns (string memory) { + return _symbol; + } + + /** + * @dev See {IERC721Metadata-tokenURI}. + */ + function tokenURI(uint256 tokenId) public view virtual returns (string memory) { + _requireOwned(tokenId); + + string memory baseURI = _baseURI(); + return bytes(baseURI).length > 0 ? string.concat(baseURI, tokenId.toString()) : ""; + } + + /** + * @dev Base URI for computing {tokenURI}. If set, the resulting URI for each + * token will be the concatenation of the `baseURI` and the `tokenId`. Empty + * by default, can be overridden in child contracts. + */ + function _baseURI() internal view virtual returns (string memory) { + return ""; + } + + /** + * @dev See {IERC721-approve}. + */ + function approve(address to, uint256 tokenId) public virtual { + _approve(to, tokenId, _msgSender()); + } + + /** + * @dev See {IERC721-getApproved}. + */ + function getApproved(uint256 tokenId) public view virtual returns (address) { + _requireOwned(tokenId); + + return _getApproved(tokenId); + } + + /** + * @dev See {IERC721-setApprovalForAll}. + */ + function setApprovalForAll(address operator, bool approved) public virtual { + _setApprovalForAll(_msgSender(), operator, approved); + } + + /** + * @dev See {IERC721-isApprovedForAll}. + */ + function isApprovedForAll(address owner, address operator) public view virtual returns (bool) { + return _operatorApprovals[owner][operator]; + } + + /** + * @dev See {IERC721-transferFrom}. + */ + function transferFrom(address from, address to, uint256 tokenId) public virtual { + if (to == address(0)) { + revert ERC721InvalidReceiver(address(0)); + } + // Setting an "auth" arguments enables the `_isAuthorized` check which verifies that the token exists + // (from != 0). Therefore, it is not needed to verify that the return value is not 0 here. + address previousOwner = _update(to, tokenId, _msgSender()); + if (previousOwner != from) { + revert ERC721IncorrectOwner(from, tokenId, previousOwner); + } + } + + /** + * @dev See {IERC721-safeTransferFrom}. + */ + function safeTransferFrom(address from, address to, uint256 tokenId) public { + safeTransferFrom(from, to, tokenId, ""); + } + + /** + * @dev See {IERC721-safeTransferFrom}. + */ + function safeTransferFrom(address from, address to, uint256 tokenId, bytes memory data) public virtual { + transferFrom(from, to, tokenId); + _checkOnERC721Received(from, to, tokenId, data); + } + + /** + * @dev Returns the owner of the `tokenId`. Does NOT revert if token doesn't exist + * + * IMPORTANT: Any overrides to this function that add ownership of tokens not tracked by the + * core ERC721 logic MUST be matched with the use of {_increaseBalance} to keep balances + * consistent with ownership. The invariant to preserve is that for any address `a` the value returned by + * `balanceOf(a)` must be equal to the number of tokens such that `_ownerOf(tokenId)` is `a`. + */ + function _ownerOf(uint256 tokenId) internal view virtual returns (address) { + return _owners[tokenId]; + } + + /** + * @dev Returns the approved address for `tokenId`. Returns 0 if `tokenId` is not minted. + */ + function _getApproved(uint256 tokenId) internal view virtual returns (address) { + return _tokenApprovals[tokenId]; + } + + /** + * @dev Returns whether `spender` is allowed to manage `owner`'s tokens, or `tokenId` in + * particular (ignoring whether it is owned by `owner`). + * + * WARNING: This function assumes that `owner` is the actual owner of `tokenId` and does not verify this + * assumption. + */ + function _isAuthorized(address owner, address spender, uint256 tokenId) internal view virtual returns (bool) { + return + spender != address(0) && + (owner == spender || isApprovedForAll(owner, spender) || _getApproved(tokenId) == spender); + } + + /** + * @dev Checks if `spender` can operate on `tokenId`, assuming the provided `owner` is the actual owner. + * Reverts if `spender` does not have approval from the provided `owner` for the given token or for all its assets + * the `spender` for the specific `tokenId`. + * + * WARNING: This function assumes that `owner` is the actual owner of `tokenId` and does not verify this + * assumption. + */ + function _checkAuthorized(address owner, address spender, uint256 tokenId) internal view virtual { + if (!_isAuthorized(owner, spender, tokenId)) { + if (owner == address(0)) { + revert ERC721NonexistentToken(tokenId); + } else { + revert ERC721InsufficientApproval(spender, tokenId); + } + } + } + + /** + * @dev Unsafe write access to the balances, used by extensions that "mint" tokens using an {ownerOf} override. + * + * NOTE: the value is limited to type(uint128).max. This protect against _balance overflow. It is unrealistic that + * a uint256 would ever overflow from increments when these increments are bounded to uint128 values. + * + * WARNING: Increasing an account's balance using this function tends to be paired with an override of the + * {_ownerOf} function to resolve the ownership of the corresponding tokens so that balances and ownership + * remain consistent with one another. + */ + function _increaseBalance(address account, uint128 value) internal virtual { + unchecked { + _balances[account] += value; + } + } + + /** + * @dev Transfers `tokenId` from its current owner to `to`, or alternatively mints (or burns) if the current owner + * (or `to`) is the zero address. Returns the owner of the `tokenId` before the update. + * + * The `auth` argument is optional. If the value passed is non 0, then this function will check that + * `auth` is either the owner of the token, or approved to operate on the token (by the owner). + * + * Emits a {Transfer} event. + * + * NOTE: If overriding this function in a way that tracks balances, see also {_increaseBalance}. + */ + function _update(address to, uint256 tokenId, address auth) internal virtual returns (address) { + address from = _ownerOf(tokenId); + + // Perform (optional) operator check + if (auth != address(0)) { + _checkAuthorized(from, auth, tokenId); + } + + // Execute the update + if (from != address(0)) { + // Clear approval. No need to re-authorize or emit the Approval event + _approve(address(0), tokenId, address(0), false); + + unchecked { + _balances[from] -= 1; + } + } + + if (to != address(0)) { + unchecked { + _balances[to] += 1; + } + } + + _owners[tokenId] = to; + + emit Transfer(from, to, tokenId); + + return from; + } + + /** + * @dev Mints `tokenId` and transfers it to `to`. + * + * WARNING: Usage of this method is discouraged, use {_safeMint} whenever possible + * + * Requirements: + * + * - `tokenId` must not exist. + * - `to` cannot be the zero address. + * + * Emits a {Transfer} event. + */ + function _mint(address to, uint256 tokenId) internal { + if (to == address(0)) { + revert ERC721InvalidReceiver(address(0)); + } + address previousOwner = _update(to, tokenId, address(0)); + if (previousOwner != address(0)) { + revert ERC721InvalidSender(address(0)); + } + } + + /** + * @dev Mints `tokenId`, transfers it to `to` and checks for `to` acceptance. + * + * Requirements: + * + * - `tokenId` must not exist. + * - If `to` refers to a smart contract, it must implement {IERC721Receiver-onERC721Received}, which is called upon a safe transfer. + * + * Emits a {Transfer} event. + */ + function _safeMint(address to, uint256 tokenId) internal { + _safeMint(to, tokenId, ""); + } + + /** + * @dev Same as {xref-ERC721-_safeMint-address-uint256-}[`_safeMint`], with an additional `data` parameter which is + * forwarded in {IERC721Receiver-onERC721Received} to contract recipients. + */ + function _safeMint(address to, uint256 tokenId, bytes memory data) internal virtual { + _mint(to, tokenId); + _checkOnERC721Received(address(0), to, tokenId, data); + } + + /** + * @dev Destroys `tokenId`. + * The approval is cleared when the token is burned. + * This is an internal function that does not check if the sender is authorized to operate on the token. + * + * Requirements: + * + * - `tokenId` must exist. + * + * Emits a {Transfer} event. + */ + function _burn(uint256 tokenId) internal { + address previousOwner = _update(address(0), tokenId, address(0)); + if (previousOwner == address(0)) { + revert ERC721NonexistentToken(tokenId); + } + } + + /** + * @dev Transfers `tokenId` from `from` to `to`. + * As opposed to {transferFrom}, this imposes no restrictions on msg.sender. + * + * Requirements: + * + * - `to` cannot be the zero address. + * - `tokenId` token must be owned by `from`. + * + * Emits a {Transfer} event. + */ + function _transfer(address from, address to, uint256 tokenId) internal { + if (to == address(0)) { + revert ERC721InvalidReceiver(address(0)); + } + address previousOwner = _update(to, tokenId, address(0)); + if (previousOwner == address(0)) { + revert ERC721NonexistentToken(tokenId); + } else if (previousOwner != from) { + revert ERC721IncorrectOwner(from, tokenId, previousOwner); + } + } + + /** + * @dev Safely transfers `tokenId` token from `from` to `to`, checking that contract recipients + * are aware of the ERC721 standard to prevent tokens from being forever locked. + * + * `data` is additional data, it has no specified format and it is sent in call to `to`. + * + * This internal function is like {safeTransferFrom} in the sense that it invokes + * {IERC721Receiver-onERC721Received} on the receiver, and can be used to e.g. + * implement alternative mechanisms to perform token transfer, such as signature-based. + * + * Requirements: + * + * - `tokenId` token must exist and be owned by `from`. + * - `to` cannot be the zero address. + * - `from` cannot be the zero address. + * - If `to` refers to a smart contract, it must implement {IERC721Receiver-onERC721Received}, which is called upon a safe transfer. + * + * Emits a {Transfer} event. + */ + function _safeTransfer(address from, address to, uint256 tokenId) internal { + _safeTransfer(from, to, tokenId, ""); + } + + /** + * @dev Same as {xref-ERC721-_safeTransfer-address-address-uint256-}[`_safeTransfer`], with an additional `data` parameter which is + * forwarded in {IERC721Receiver-onERC721Received} to contract recipients. + */ + function _safeTransfer(address from, address to, uint256 tokenId, bytes memory data) internal virtual { + _transfer(from, to, tokenId); + _checkOnERC721Received(from, to, tokenId, data); + } + + /** + * @dev Approve `to` to operate on `tokenId` + * + * The `auth` argument is optional. If the value passed is non 0, then this function will check that `auth` is + * either the owner of the token, or approved to operate on all tokens held by this owner. + * + * Emits an {Approval} event. + * + * Overrides to this logic should be done to the variant with an additional `bool emitEvent` argument. + */ + function _approve(address to, uint256 tokenId, address auth) internal { + _approve(to, tokenId, auth, true); + } + + /** + * @dev Variant of `_approve` with an optional flag to enable or disable the {Approval} event. The event is not + * emitted in the context of transfers. + */ + function _approve(address to, uint256 tokenId, address auth, bool emitEvent) internal virtual { + // Avoid reading the owner unless necessary + if (emitEvent || auth != address(0)) { + address owner = _requireOwned(tokenId); + + // We do not use _isAuthorized because single-token approvals should not be able to call approve + if (auth != address(0) && owner != auth && !isApprovedForAll(owner, auth)) { + revert ERC721InvalidApprover(auth); + } + + if (emitEvent) { + emit Approval(owner, to, tokenId); + } + } + + _tokenApprovals[tokenId] = to; + } + + /** + * @dev Approve `operator` to operate on all of `owner` tokens + * + * Requirements: + * - operator can't be the address zero. + * + * Emits an {ApprovalForAll} event. + */ + function _setApprovalForAll(address owner, address operator, bool approved) internal virtual { + if (operator == address(0)) { + revert ERC721InvalidOperator(operator); + } + _operatorApprovals[owner][operator] = approved; + emit ApprovalForAll(owner, operator, approved); + } + + /** + * @dev Reverts if the `tokenId` doesn't have a current owner (it hasn't been minted, or it has been burned). + * Returns the owner. + * + * Overrides to ownership logic should be done to {_ownerOf}. + */ + function _requireOwned(uint256 tokenId) internal view returns (address) { + address owner = _ownerOf(tokenId); + if (owner == address(0)) { + revert ERC721NonexistentToken(tokenId); + } + return owner; + } + + /** + * @dev Private function to invoke {IERC721Receiver-onERC721Received} on a target address. This will revert if the + * recipient doesn't accept the token transfer. The call is not executed if the target address is not a contract. + * + * @param from address representing the previous owner of the given token ID + * @param to target address that will receive the tokens + * @param tokenId uint256 ID of the token to be transferred + * @param data bytes optional data to send along with the call + */ + function _checkOnERC721Received(address from, address to, uint256 tokenId, bytes memory data) private { + if (to.code.length > 0) { + try IERC721Receiver(to).onERC721Received(_msgSender(), from, tokenId, data) returns (bytes4 retval) { + if (retval != IERC721Receiver.onERC721Received.selector) { + revert ERC721InvalidReceiver(to); + } + } catch (bytes memory reason) { + if (reason.length == 0) { + revert ERC721InvalidReceiver(to); + } else { + /// @solidity memory-safe-assembly + assembly { + revert(add(32, reason), mload(reason)) + } + } + } + } + } +} diff --git a/contracts/token/ERC721/IERC721.sol b/contracts/token/ERC721/IERC721.sol new file mode 100644 index 000000000..98a4213f9 --- /dev/null +++ b/contracts/token/ERC721/IERC721.sol @@ -0,0 +1,135 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (token/ERC721/IERC721.sol) + +pragma solidity ^0.8.20; + +import {IERC165} from "../../utils/introspection/IERC165.sol"; + +/** + * @dev Required interface of an ERC721 compliant contract. + */ +interface IERC721 is IERC165 { + /** + * @dev Emitted when `tokenId` token is transferred from `from` to `to`. + */ + event Transfer(address indexed from, address indexed to, uint256 indexed tokenId); + + /** + * @dev Emitted when `owner` enables `approved` to manage the `tokenId` token. + */ + event Approval(address indexed owner, address indexed approved, uint256 indexed tokenId); + + /** + * @dev Emitted when `owner` enables or disables (`approved`) `operator` to manage all of its assets. + */ + event ApprovalForAll(address indexed owner, address indexed operator, bool approved); + + /** + * @dev Returns the number of tokens in ``owner``'s account. + */ + function balanceOf(address owner) external view returns (uint256 balance); + + /** + * @dev Returns the owner of the `tokenId` token. + * + * Requirements: + * + * - `tokenId` must exist. + */ + function ownerOf(uint256 tokenId) external view returns (address owner); + + /** + * @dev Safely transfers `tokenId` token from `from` to `to`. + * + * Requirements: + * + * - `from` cannot be the zero address. + * - `to` cannot be the zero address. + * - `tokenId` token must exist and be owned by `from`. + * - If the caller is not `from`, it must be approved to move this token by either {approve} or {setApprovalForAll}. + * - If `to` refers to a smart contract, it must implement {IERC721Receiver-onERC721Received}, which is called upon + * a safe transfer. + * + * Emits a {Transfer} event. + */ + function safeTransferFrom(address from, address to, uint256 tokenId, bytes calldata data) external; + + /** + * @dev Safely transfers `tokenId` token from `from` to `to`, checking first that contract recipients + * are aware of the ERC721 protocol to prevent tokens from being forever locked. + * + * Requirements: + * + * - `from` cannot be the zero address. + * - `to` cannot be the zero address. + * - `tokenId` token must exist and be owned by `from`. + * - If the caller is not `from`, it must have been allowed to move this token by either {approve} or + * {setApprovalForAll}. + * - If `to` refers to a smart contract, it must implement {IERC721Receiver-onERC721Received}, which is called upon + * a safe transfer. + * + * Emits a {Transfer} event. + */ + function safeTransferFrom(address from, address to, uint256 tokenId) external; + + /** + * @dev Transfers `tokenId` token from `from` to `to`. + * + * WARNING: Note that the caller is responsible to confirm that the recipient is capable of receiving ERC721 + * or else they may be permanently lost. Usage of {safeTransferFrom} prevents loss, though the caller must + * understand this adds an external call which potentially creates a reentrancy vulnerability. + * + * Requirements: + * + * - `from` cannot be the zero address. + * - `to` cannot be the zero address. + * - `tokenId` token must be owned by `from`. + * - If the caller is not `from`, it must be approved to move this token by either {approve} or {setApprovalForAll}. + * + * Emits a {Transfer} event. + */ + function transferFrom(address from, address to, uint256 tokenId) external; + + /** + * @dev Gives permission to `to` to transfer `tokenId` token to another account. + * The approval is cleared when the token is transferred. + * + * Only a single account can be approved at a time, so approving the zero address clears previous approvals. + * + * Requirements: + * + * - The caller must own the token or be an approved operator. + * - `tokenId` must exist. + * + * Emits an {Approval} event. + */ + function approve(address to, uint256 tokenId) external; + + /** + * @dev Approve or remove `operator` as an operator for the caller. + * Operators can call {transferFrom} or {safeTransferFrom} for any token owned by the caller. + * + * Requirements: + * + * - The `operator` cannot be the address zero. + * + * Emits an {ApprovalForAll} event. + */ + function setApprovalForAll(address operator, bool approved) external; + + /** + * @dev Returns the account approved for `tokenId` token. + * + * Requirements: + * + * - `tokenId` must exist. + */ + function getApproved(uint256 tokenId) external view returns (address operator); + + /** + * @dev Returns if the `operator` is allowed to manage all of the assets of `owner`. + * + * See {setApprovalForAll} + */ + function isApprovedForAll(address owner, address operator) external view returns (bool); +} diff --git a/contracts/token/ERC721/IERC721Receiver.sol b/contracts/token/ERC721/IERC721Receiver.sol new file mode 100644 index 000000000..4d25a01d1 --- /dev/null +++ b/contracts/token/ERC721/IERC721Receiver.sol @@ -0,0 +1,28 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (token/ERC721/IERC721Receiver.sol) + +pragma solidity ^0.8.20; + +/** + * @title ERC721 token receiver interface + * @dev Interface for any contract that wants to support safeTransfers + * from ERC721 asset contracts. + */ +interface IERC721Receiver { + /** + * @dev Whenever an {IERC721} `tokenId` token is transferred to this contract via {IERC721-safeTransferFrom} + * by `operator` from `from`, this function is called. + * + * It must return its Solidity selector to confirm the token transfer. + * If any other value is returned or the interface is not implemented by the recipient, the transfer will be + * reverted. + * + * The selector can be obtained in Solidity with `IERC721Receiver.onERC721Received.selector`. + */ + function onERC721Received( + address operator, + address from, + uint256 tokenId, + bytes calldata data + ) external returns (bytes4); +} diff --git a/contracts/token/ERC721/README.adoc b/contracts/token/ERC721/README.adoc new file mode 100644 index 000000000..40ae919d9 --- /dev/null +++ b/contracts/token/ERC721/README.adoc @@ -0,0 +1,67 @@ += ERC 721 + +[.readme-notice] +NOTE: This document is better viewed at https://docs.openzeppelin.com/contracts/api/token/erc721 + +This set of interfaces, contracts, and utilities are all related to the https://eips.ethereum.org/EIPS/eip-721[ERC721 Non-Fungible Token Standard]. + +TIP: For a walk through on how to create an ERC721 token read our xref:ROOT:erc721.adoc[ERC721 guide]. + +The EIP specifies four interfaces: + +* {IERC721}: Core functionality required in all compliant implementation. +* {IERC721Metadata}: Optional extension that adds name, symbol, and token URI, almost always included. +* {IERC721Enumerable}: Optional extension that allows enumerating the tokens on chain, often not included since it requires large gas overhead. +* {IERC721Receiver}: An interface that must be implemented by contracts if they want to accept tokens through `safeTransferFrom`. + +OpenZeppelin Contracts provides implementations of all four interfaces: + +* {ERC721}: The core and metadata extensions, with a base URI mechanism. +* {ERC721Enumerable}: The enumerable extension. +* {ERC721Holder}: A bare bones implementation of the receiver interface. + +Additionally there are a few of other extensions: + +* {ERC721Consecutive}: An implementation of https://eips.ethereum.org/EIPS/eip-2309[ERC2309] for minting batchs of tokens during construction, in accordance with ERC721. +* {ERC721URIStorage}: A more flexible but more expensive way of storing metadata. +* {ERC721Votes}: Support for voting and vote delegation. +* {ERC721Royalty}: A way to signal royalty information following ERC2981. +* {ERC721Pausable}: A primitive to pause contract operation. +* {ERC721Burnable}: A way for token holders to burn their own tokens. +* {ERC721Wrapper}: Wrapper to create an ERC721 backed by another ERC721, with deposit and withdraw methods. Useful in conjunction with {ERC721Votes}. + +NOTE: This core set of contracts is designed to be unopinionated, allowing developers to access the internal functions in ERC721 (such as <>) and expose them as external functions in the way they prefer. + +== Core + +{{IERC721}} + +{{IERC721Metadata}} + +{{IERC721Enumerable}} + +{{ERC721}} + +{{ERC721Enumerable}} + +{{IERC721Receiver}} + +== Extensions + +{{ERC721Pausable}} + +{{ERC721Burnable}} + +{{ERC721Consecutive}} + +{{ERC721URIStorage}} + +{{ERC721Votes}} + +{{ERC721Royalty}} + +{{ERC721Wrapper}} + +== Utilities + +{{ERC721Holder}} diff --git a/contracts/token/ERC721/extensions/ERC721Burnable.sol b/contracts/token/ERC721/extensions/ERC721Burnable.sol new file mode 100644 index 000000000..639661e66 --- /dev/null +++ b/contracts/token/ERC721/extensions/ERC721Burnable.sol @@ -0,0 +1,26 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (token/ERC721/extensions/ERC721Burnable.sol) + +pragma solidity ^0.8.20; + +import {ERC721} from "../ERC721.sol"; +import {Context} from "../../../utils/Context.sol"; + +/** + * @title ERC721 Burnable Token + * @dev ERC721 Token that can be burned (destroyed). + */ +abstract contract ERC721Burnable is Context, ERC721 { + /** + * @dev Burns `tokenId`. See {ERC721-_burn}. + * + * Requirements: + * + * - The caller must own `tokenId` or be an approved operator. + */ + function burn(uint256 tokenId) public virtual { + // Setting an "auth" arguments enables the `_isAuthorized` check which verifies that the token exists + // (from != 0). Therefore, it is not needed to verify that the return value is not 0 here. + _update(address(0), tokenId, _msgSender()); + } +} diff --git a/contracts/token/ERC721/extensions/ERC721Consecutive.sol b/contracts/token/ERC721/extensions/ERC721Consecutive.sol new file mode 100644 index 000000000..8e670d573 --- /dev/null +++ b/contracts/token/ERC721/extensions/ERC721Consecutive.sol @@ -0,0 +1,176 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (token/ERC721/extensions/ERC721Consecutive.sol) + +pragma solidity ^0.8.20; + +import {ERC721} from "../ERC721.sol"; +import {IERC2309} from "../../../interfaces/IERC2309.sol"; +import {BitMaps} from "../../../utils/structs/BitMaps.sol"; +import {Checkpoints} from "../../../utils/structs/Checkpoints.sol"; + +/** + * @dev Implementation of the ERC2309 "Consecutive Transfer Extension" as defined in + * https://eips.ethereum.org/EIPS/eip-2309[EIP-2309]. + * + * This extension allows the minting of large batches of tokens, during contract construction only. For upgradeable + * contracts this implies that batch minting is only available during proxy deployment, and not in subsequent upgrades. + * These batches are limited to 5000 tokens at a time by default to accommodate off-chain indexers. + * + * Using this extension removes the ability to mint single tokens during contract construction. This ability is + * regained after construction. During construction, only batch minting is allowed. + * + * IMPORTANT: This extension does not call the {_update} function for tokens minted in batch. Any logic added to this + * function through overrides will not be triggered when token are minted in batch. You may want to also override + * {_increaseBalance} or {_mintConsecutive} to account for these mints. + * + * IMPORTANT: When overriding {_mintConsecutive}, be careful about call ordering. {ownerOf} may return invalid + * values during the {_mintConsecutive} execution if the super call is not called first. To be safe, execute the + * super call before your custom logic. + */ +abstract contract ERC721Consecutive is IERC2309, ERC721 { + using BitMaps for BitMaps.BitMap; + using Checkpoints for Checkpoints.Trace160; + + Checkpoints.Trace160 private _sequentialOwnership; + BitMaps.BitMap private _sequentialBurn; + + /** + * @dev Batch mint is restricted to the constructor. + * Any batch mint not emitting the {IERC721-Transfer} event outside of the constructor + * is non-ERC721 compliant. + */ + error ERC721ForbiddenBatchMint(); + + /** + * @dev Exceeds the max amount of mints per batch. + */ + error ERC721ExceededMaxBatchMint(uint256 batchSize, uint256 maxBatch); + + /** + * @dev Individual minting is not allowed. + */ + error ERC721ForbiddenMint(); + + /** + * @dev Batch burn is not supported. + */ + error ERC721ForbiddenBatchBurn(); + + /** + * @dev Maximum size of a batch of consecutive tokens. This is designed to limit stress on off-chain indexing + * services that have to record one entry per token, and have protections against "unreasonably large" batches of + * tokens. + * + * NOTE: Overriding the default value of 5000 will not cause on-chain issues, but may result in the asset not being + * correctly supported by off-chain indexing services (including marketplaces). + */ + function _maxBatchSize() internal view virtual returns (uint96) { + return 5000; + } + + /** + * @dev See {ERC721-_ownerOf}. Override that checks the sequential ownership structure for tokens that have + * been minted as part of a batch, and not yet transferred. + */ + function _ownerOf(uint256 tokenId) internal view virtual override returns (address) { + address owner = super._ownerOf(tokenId); + + // If token is owned by the core, or beyond consecutive range, return base value + if (owner != address(0) || tokenId > type(uint96).max || tokenId < _firstConsecutiveId()) { + return owner; + } + + // Otherwise, check the token was not burned, and fetch ownership from the anchors + // Note: no need for safe cast, we know that tokenId <= type(uint96).max + return _sequentialBurn.get(tokenId) ? address(0) : address(_sequentialOwnership.lowerLookup(uint96(tokenId))); + } + + /** + * @dev Mint a batch of tokens of length `batchSize` for `to`. Returns the token id of the first token minted in the + * batch; if `batchSize` is 0, returns the number of consecutive ids minted so far. + * + * Requirements: + * + * - `batchSize` must not be greater than {_maxBatchSize}. + * - The function is called in the constructor of the contract (directly or indirectly). + * + * CAUTION: Does not emit a `Transfer` event. This is ERC721 compliant as long as it is done inside of the + * constructor, which is enforced by this function. + * + * CAUTION: Does not invoke `onERC721Received` on the receiver. + * + * Emits a {IERC2309-ConsecutiveTransfer} event. + */ + function _mintConsecutive(address to, uint96 batchSize) internal virtual returns (uint96) { + uint96 next = _nextConsecutiveId(); + + // minting a batch of size 0 is a no-op + if (batchSize > 0) { + if (address(this).code.length > 0) { + revert ERC721ForbiddenBatchMint(); + } + if (to == address(0)) { + revert ERC721InvalidReceiver(address(0)); + } + + uint256 maxBatchSize = _maxBatchSize(); + if (batchSize > maxBatchSize) { + revert ERC721ExceededMaxBatchMint(batchSize, maxBatchSize); + } + + // push an ownership checkpoint & emit event + uint96 last = next + batchSize - 1; + _sequentialOwnership.push(last, uint160(to)); + + // The invariant required by this function is preserved because the new sequentialOwnership checkpoint + // is attributing ownership of `batchSize` new tokens to account `to`. + _increaseBalance(to, batchSize); + + emit ConsecutiveTransfer(next, last, address(0), to); + } + + return next; + } + + /** + * @dev See {ERC721-_update}. Override version that restricts normal minting to after construction. + * + * WARNING: Using {ERC721Consecutive} prevents minting during construction in favor of {_mintConsecutive}. + * After construction, {_mintConsecutive} is no longer available and minting through {_update} becomes available. + */ + function _update(address to, uint256 tokenId, address auth) internal virtual override returns (address) { + address previousOwner = super._update(to, tokenId, auth); + + // only mint after construction + if (previousOwner == address(0) && address(this).code.length == 0) { + revert ERC721ForbiddenMint(); + } + + // record burn + if ( + to == address(0) && // if we burn + tokenId < _nextConsecutiveId() && // and the tokenId was minted in a batch + !_sequentialBurn.get(tokenId) // and the token was never marked as burnt + ) { + _sequentialBurn.set(tokenId); + } + + return previousOwner; + } + + /** + * @dev Used to offset the first token id in {_nextConsecutiveId} + */ + function _firstConsecutiveId() internal view virtual returns (uint96) { + return 0; + } + + /** + * @dev Returns the next tokenId to mint using {_mintConsecutive}. It will return {_firstConsecutiveId} + * if no consecutive tokenId has been minted before. + */ + function _nextConsecutiveId() private view returns (uint96) { + (bool exists, uint96 latestId, ) = _sequentialOwnership.latestCheckpoint(); + return exists ? latestId + 1 : _firstConsecutiveId(); + } +} diff --git a/contracts/token/ERC721/extensions/ERC721Enumerable.sol b/contracts/token/ERC721/extensions/ERC721Enumerable.sol new file mode 100644 index 000000000..803a937f5 --- /dev/null +++ b/contracts/token/ERC721/extensions/ERC721Enumerable.sol @@ -0,0 +1,172 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (token/ERC721/extensions/ERC721Enumerable.sol) + +pragma solidity ^0.8.20; + +import {ERC721} from "../ERC721.sol"; +import {IERC721Enumerable} from "./IERC721Enumerable.sol"; +import {IERC165} from "../../../utils/introspection/ERC165.sol"; + +/** + * @dev This implements an optional extension of {ERC721} defined in the EIP that adds enumerability + * of all the token ids in the contract as well as all token ids owned by each account. + * + * CAUTION: `ERC721` extensions that implement custom `balanceOf` logic, such as `ERC721Consecutive`, + * interfere with enumerability and should not be used together with `ERC721Enumerable`. + */ +abstract contract ERC721Enumerable is ERC721, IERC721Enumerable { + mapping(address owner => mapping(uint256 index => uint256)) private _ownedTokens; + mapping(uint256 tokenId => uint256) private _ownedTokensIndex; + + uint256[] private _allTokens; + mapping(uint256 tokenId => uint256) private _allTokensIndex; + + /** + * @dev An `owner`'s token query was out of bounds for `index`. + * + * NOTE: The owner being `address(0)` indicates a global out of bounds index. + */ + error ERC721OutOfBoundsIndex(address owner, uint256 index); + + /** + * @dev Batch mint is not allowed. + */ + error ERC721EnumerableForbiddenBatchMint(); + + /** + * @dev See {IERC165-supportsInterface}. + */ + function supportsInterface(bytes4 interfaceId) public view virtual override(IERC165, ERC721) returns (bool) { + return interfaceId == type(IERC721Enumerable).interfaceId || super.supportsInterface(interfaceId); + } + + /** + * @dev See {IERC721Enumerable-tokenOfOwnerByIndex}. + */ + function tokenOfOwnerByIndex(address owner, uint256 index) public view virtual returns (uint256) { + if (index >= balanceOf(owner)) { + revert ERC721OutOfBoundsIndex(owner, index); + } + return _ownedTokens[owner][index]; + } + + /** + * @dev See {IERC721Enumerable-totalSupply}. + */ + function totalSupply() public view virtual returns (uint256) { + return _allTokens.length; + } + + /** + * @dev See {IERC721Enumerable-tokenByIndex}. + */ + function tokenByIndex(uint256 index) public view virtual returns (uint256) { + if (index >= totalSupply()) { + revert ERC721OutOfBoundsIndex(address(0), index); + } + return _allTokens[index]; + } + + /** + * @dev See {ERC721-_update}. + */ + function _update(address to, uint256 tokenId, address auth) internal virtual override returns (address) { + address previousOwner = super._update(to, tokenId, auth); + + if (previousOwner == address(0)) { + _addTokenToAllTokensEnumeration(tokenId); + } else if (previousOwner != to) { + _removeTokenFromOwnerEnumeration(previousOwner, tokenId); + } + if (to == address(0)) { + _removeTokenFromAllTokensEnumeration(tokenId); + } else if (previousOwner != to) { + _addTokenToOwnerEnumeration(to, tokenId); + } + + return previousOwner; + } + + /** + * @dev Private function to add a token to this extension's ownership-tracking data structures. + * @param to address representing the new owner of the given token ID + * @param tokenId uint256 ID of the token to be added to the tokens list of the given address + */ + function _addTokenToOwnerEnumeration(address to, uint256 tokenId) private { + uint256 length = balanceOf(to) - 1; + _ownedTokens[to][length] = tokenId; + _ownedTokensIndex[tokenId] = length; + } + + /** + * @dev Private function to add a token to this extension's token tracking data structures. + * @param tokenId uint256 ID of the token to be added to the tokens list + */ + function _addTokenToAllTokensEnumeration(uint256 tokenId) private { + _allTokensIndex[tokenId] = _allTokens.length; + _allTokens.push(tokenId); + } + + /** + * @dev Private function to remove a token from this extension's ownership-tracking data structures. Note that + * while the token is not assigned a new owner, the `_ownedTokensIndex` mapping is _not_ updated: this allows for + * gas optimizations e.g. when performing a transfer operation (avoiding double writes). + * This has O(1) time complexity, but alters the order of the _ownedTokens array. + * @param from address representing the previous owner of the given token ID + * @param tokenId uint256 ID of the token to be removed from the tokens list of the given address + */ + function _removeTokenFromOwnerEnumeration(address from, uint256 tokenId) private { + // To prevent a gap in from's tokens array, we store the last token in the index of the token to delete, and + // then delete the last slot (swap and pop). + + uint256 lastTokenIndex = balanceOf(from); + uint256 tokenIndex = _ownedTokensIndex[tokenId]; + + // When the token to delete is the last token, the swap operation is unnecessary + if (tokenIndex != lastTokenIndex) { + uint256 lastTokenId = _ownedTokens[from][lastTokenIndex]; + + _ownedTokens[from][tokenIndex] = lastTokenId; // Move the last token to the slot of the to-delete token + _ownedTokensIndex[lastTokenId] = tokenIndex; // Update the moved token's index + } + + // This also deletes the contents at the last position of the array + delete _ownedTokensIndex[tokenId]; + delete _ownedTokens[from][lastTokenIndex]; + } + + /** + * @dev Private function to remove a token from this extension's token tracking data structures. + * This has O(1) time complexity, but alters the order of the _allTokens array. + * @param tokenId uint256 ID of the token to be removed from the tokens list + */ + function _removeTokenFromAllTokensEnumeration(uint256 tokenId) private { + // To prevent a gap in the tokens array, we store the last token in the index of the token to delete, and + // then delete the last slot (swap and pop). + + uint256 lastTokenIndex = _allTokens.length - 1; + uint256 tokenIndex = _allTokensIndex[tokenId]; + + // When the token to delete is the last token, the swap operation is unnecessary. However, since this occurs so + // rarely (when the last minted token is burnt) that we still do the swap here to avoid the gas cost of adding + // an 'if' statement (like in _removeTokenFromOwnerEnumeration) + uint256 lastTokenId = _allTokens[lastTokenIndex]; + + _allTokens[tokenIndex] = lastTokenId; // Move the last token to the slot of the to-delete token + _allTokensIndex[lastTokenId] = tokenIndex; // Update the moved token's index + + // This also deletes the contents at the last position of the array + delete _allTokensIndex[tokenId]; + _allTokens.pop(); + } + + /** + * See {ERC721-_increaseBalance}. We need that to account tokens that were minted in batch + */ + function _increaseBalance(address account, uint128 amount) internal virtual override { + if (amount > 0) { + revert ERC721EnumerableForbiddenBatchMint(); + } + super._increaseBalance(account, amount); + } +} diff --git a/contracts/token/ERC721/extensions/ERC721Pausable.sol b/contracts/token/ERC721/extensions/ERC721Pausable.sol new file mode 100644 index 000000000..cc3d46bfb --- /dev/null +++ b/contracts/token/ERC721/extensions/ERC721Pausable.sol @@ -0,0 +1,37 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (token/ERC721/extensions/ERC721Pausable.sol) + +pragma solidity ^0.8.20; + +import {ERC721} from "../ERC721.sol"; +import {Pausable} from "../../../utils/Pausable.sol"; + +/** + * @dev ERC721 token with pausable token transfers, minting and burning. + * + * Useful for scenarios such as preventing trades until the end of an evaluation + * period, or having an emergency switch for freezing all token transfers in the + * event of a large bug. + * + * IMPORTANT: This contract does not include public pause and unpause functions. In + * addition to inheriting this contract, you must define both functions, invoking the + * {Pausable-_pause} and {Pausable-_unpause} internal functions, with appropriate + * access control, e.g. using {AccessControl} or {Ownable}. Not doing so will + * make the contract pause mechanism of the contract unreachable, and thus unusable. + */ +abstract contract ERC721Pausable is ERC721, Pausable { + /** + * @dev See {ERC721-_update}. + * + * Requirements: + * + * - the contract must not be paused. + */ + function _update( + address to, + uint256 tokenId, + address auth + ) internal virtual override whenNotPaused returns (address) { + return super._update(to, tokenId, auth); + } +} diff --git a/contracts/token/ERC721/extensions/ERC721Royalty.sol b/contracts/token/ERC721/extensions/ERC721Royalty.sol new file mode 100644 index 000000000..e76a5123d --- /dev/null +++ b/contracts/token/ERC721/extensions/ERC721Royalty.sol @@ -0,0 +1,27 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (token/ERC721/extensions/ERC721Royalty.sol) + +pragma solidity ^0.8.20; + +import {ERC721} from "../ERC721.sol"; +import {ERC2981} from "../../common/ERC2981.sol"; + +/** + * @dev Extension of ERC721 with the ERC2981 NFT Royalty Standard, a standardized way to retrieve royalty payment + * information. + * + * Royalty information can be specified globally for all token ids via {ERC2981-_setDefaultRoyalty}, and/or individually + * for specific token ids via {ERC2981-_setTokenRoyalty}. The latter takes precedence over the first. + * + * IMPORTANT: ERC-2981 only specifies a way to signal royalty information and does not enforce its payment. See + * https://eips.ethereum.org/EIPS/eip-2981#optional-royalty-payments[Rationale] in the EIP. Marketplaces are expected to + * voluntarily pay royalties together with sales, but note that this standard is not yet widely supported. + */ +abstract contract ERC721Royalty is ERC2981, ERC721 { + /** + * @dev See {IERC165-supportsInterface}. + */ + function supportsInterface(bytes4 interfaceId) public view virtual override(ERC721, ERC2981) returns (bool) { + return super.supportsInterface(interfaceId); + } +} diff --git a/contracts/token/ERC721/extensions/ERC721URIStorage.sol b/contracts/token/ERC721/extensions/ERC721URIStorage.sol new file mode 100644 index 000000000..d9948ea33 --- /dev/null +++ b/contracts/token/ERC721/extensions/ERC721URIStorage.sol @@ -0,0 +1,61 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (token/ERC721/extensions/ERC721URIStorage.sol) + +pragma solidity ^0.8.20; + +import {ERC721} from "../ERC721.sol"; +import {Strings} from "../../../utils/Strings.sol"; +import {IERC4906} from "../../../interfaces/IERC4906.sol"; +import {IERC165} from "../../../interfaces/IERC165.sol"; + +/** + * @dev ERC721 token with storage based token URI management. + */ +abstract contract ERC721URIStorage is IERC4906, ERC721 { + using Strings for uint256; + + // Interface ID as defined in ERC-4906. This does not correspond to a traditional interface ID as ERC-4906 only + // defines events and does not include any external function. + bytes4 private constant ERC4906_INTERFACE_ID = bytes4(0x49064906); + + // Optional mapping for token URIs + mapping(uint256 tokenId => string) private _tokenURIs; + + /** + * @dev See {IERC165-supportsInterface} + */ + function supportsInterface(bytes4 interfaceId) public view virtual override(ERC721, IERC165) returns (bool) { + return interfaceId == ERC4906_INTERFACE_ID || super.supportsInterface(interfaceId); + } + + /** + * @dev See {IERC721Metadata-tokenURI}. + */ + function tokenURI(uint256 tokenId) public view virtual override returns (string memory) { + _requireOwned(tokenId); + + string memory _tokenURI = _tokenURIs[tokenId]; + string memory base = _baseURI(); + + // If there is no base URI, return the token URI. + if (bytes(base).length == 0) { + return _tokenURI; + } + // If both are set, concatenate the baseURI and tokenURI (via string.concat). + if (bytes(_tokenURI).length > 0) { + return string.concat(base, _tokenURI); + } + + return super.tokenURI(tokenId); + } + + /** + * @dev Sets `_tokenURI` as the tokenURI of `tokenId`. + * + * Emits {MetadataUpdate}. + */ + function _setTokenURI(uint256 tokenId, string memory _tokenURI) internal virtual { + _tokenURIs[tokenId] = _tokenURI; + emit MetadataUpdate(tokenId); + } +} diff --git a/contracts/token/ERC721/extensions/ERC721Votes.sol b/contracts/token/ERC721/extensions/ERC721Votes.sol new file mode 100644 index 000000000..d87fb8fe3 --- /dev/null +++ b/contracts/token/ERC721/extensions/ERC721Votes.sol @@ -0,0 +1,47 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (token/ERC721/extensions/ERC721Votes.sol) + +pragma solidity ^0.8.20; + +import {ERC721} from "../ERC721.sol"; +import {Votes} from "../../../governance/utils/Votes.sol"; + +/** + * @dev Extension of ERC721 to support voting and delegation as implemented by {Votes}, where each individual NFT counts + * as 1 vote unit. + * + * Tokens do not count as votes until they are delegated, because votes must be tracked which incurs an additional cost + * on every transfer. Token holders can either delegate to a trusted representative who will decide how to make use of + * the votes in governance decisions, or they can delegate to themselves to be their own representative. + */ +abstract contract ERC721Votes is ERC721, Votes { + /** + * @dev See {ERC721-_update}. Adjusts votes when tokens are transferred. + * + * Emits a {IVotes-DelegateVotesChanged} event. + */ + function _update(address to, uint256 tokenId, address auth) internal virtual override returns (address) { + address previousOwner = super._update(to, tokenId, auth); + + _transferVotingUnits(previousOwner, to, 1); + + return previousOwner; + } + + /** + * @dev Returns the balance of `account`. + * + * WARNING: Overriding this function will likely result in incorrect vote tracking. + */ + function _getVotingUnits(address account) internal view virtual override returns (uint256) { + return balanceOf(account); + } + + /** + * @dev See {ERC721-_increaseBalance}. We need that to account tokens that were minted in batch. + */ + function _increaseBalance(address account, uint128 amount) internal virtual override { + super._increaseBalance(account, amount); + _transferVotingUnits(address(0), account, amount); + } +} diff --git a/contracts/token/ERC721/extensions/ERC721Wrapper.sol b/contracts/token/ERC721/extensions/ERC721Wrapper.sol new file mode 100644 index 000000000..8da6da6b6 --- /dev/null +++ b/contracts/token/ERC721/extensions/ERC721Wrapper.sol @@ -0,0 +1,102 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (token/ERC721/extensions/ERC721Wrapper.sol) + +pragma solidity ^0.8.20; + +import {IERC721, ERC721} from "../ERC721.sol"; +import {IERC721Receiver} from "../IERC721Receiver.sol"; + +/** + * @dev Extension of the ERC721 token contract to support token wrapping. + * + * Users can deposit and withdraw an "underlying token" and receive a "wrapped token" with a matching tokenId. This is + * useful in conjunction with other modules. For example, combining this wrapping mechanism with {ERC721Votes} will allow + * the wrapping of an existing "basic" ERC721 into a governance token. + */ +abstract contract ERC721Wrapper is ERC721, IERC721Receiver { + IERC721 private immutable _underlying; + + /** + * @dev The received ERC721 token couldn't be wrapped. + */ + error ERC721UnsupportedToken(address token); + + constructor(IERC721 underlyingToken) { + _underlying = underlyingToken; + } + + /** + * @dev Allow a user to deposit underlying tokens and mint the corresponding tokenIds. + */ + function depositFor(address account, uint256[] memory tokenIds) public virtual returns (bool) { + uint256 length = tokenIds.length; + for (uint256 i = 0; i < length; ++i) { + uint256 tokenId = tokenIds[i]; + + // This is an "unsafe" transfer that doesn't call any hook on the receiver. With underlying() being trusted + // (by design of this contract) and no other contracts expected to be called from there, we are safe. + // slither-disable-next-line reentrancy-no-eth + underlying().transferFrom(_msgSender(), address(this), tokenId); + _safeMint(account, tokenId); + } + + return true; + } + + /** + * @dev Allow a user to burn wrapped tokens and withdraw the corresponding tokenIds of the underlying tokens. + */ + function withdrawTo(address account, uint256[] memory tokenIds) public virtual returns (bool) { + uint256 length = tokenIds.length; + for (uint256 i = 0; i < length; ++i) { + uint256 tokenId = tokenIds[i]; + // Setting an "auth" arguments enables the `_isAuthorized` check which verifies that the token exists + // (from != 0). Therefore, it is not needed to verify that the return value is not 0 here. + _update(address(0), tokenId, _msgSender()); + // Checks were already performed at this point, and there's no way to retake ownership or approval from + // the wrapped tokenId after this point, so it's safe to remove the reentrancy check for the next line. + // slither-disable-next-line reentrancy-no-eth + underlying().safeTransferFrom(address(this), account, tokenId); + } + + return true; + } + + /** + * @dev Overrides {IERC721Receiver-onERC721Received} to allow minting on direct ERC721 transfers to + * this contract. + * + * In case there's data attached, it validates that the operator is this contract, so only trusted data + * is accepted from {depositFor}. + * + * WARNING: Doesn't work with unsafe transfers (eg. {IERC721-transferFrom}). Use {ERC721Wrapper-_recover} + * for recovering in that scenario. + */ + function onERC721Received(address, address from, uint256 tokenId, bytes memory) public virtual returns (bytes4) { + if (address(underlying()) != _msgSender()) { + revert ERC721UnsupportedToken(_msgSender()); + } + _safeMint(from, tokenId); + return IERC721Receiver.onERC721Received.selector; + } + + /** + * @dev Mint a wrapped token to cover any underlyingToken that would have been transferred by mistake. Internal + * function that can be exposed with access control if desired. + */ + function _recover(address account, uint256 tokenId) internal virtual returns (uint256) { + address owner = underlying().ownerOf(tokenId); + if (owner != address(this)) { + revert ERC721IncorrectOwner(address(this), tokenId, owner); + } + _safeMint(account, tokenId); + return tokenId; + } + + /** + * @dev Returns the underlying token. + */ + function underlying() public view virtual returns (IERC721) { + return _underlying; + } +} diff --git a/contracts/token/ERC721/extensions/IERC721Enumerable.sol b/contracts/token/ERC721/extensions/IERC721Enumerable.sol new file mode 100644 index 000000000..553a9364b --- /dev/null +++ b/contracts/token/ERC721/extensions/IERC721Enumerable.sol @@ -0,0 +1,29 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (token/ERC721/extensions/IERC721Enumerable.sol) + +pragma solidity ^0.8.20; + +import {IERC721} from "../IERC721.sol"; + +/** + * @title ERC-721 Non-Fungible Token Standard, optional enumeration extension + * @dev See https://eips.ethereum.org/EIPS/eip-721 + */ +interface IERC721Enumerable is IERC721 { + /** + * @dev Returns the total amount of tokens stored by the contract. + */ + function totalSupply() external view returns (uint256); + + /** + * @dev Returns a token ID owned by `owner` at a given `index` of its token list. + * Use along with {balanceOf} to enumerate all of ``owner``'s tokens. + */ + function tokenOfOwnerByIndex(address owner, uint256 index) external view returns (uint256); + + /** + * @dev Returns a token ID at a given `index` of all the tokens stored by the contract. + * Use along with {totalSupply} to enumerate all tokens. + */ + function tokenByIndex(uint256 index) external view returns (uint256); +} diff --git a/contracts/token/ERC721/extensions/IERC721Metadata.sol b/contracts/token/ERC721/extensions/IERC721Metadata.sol new file mode 100644 index 000000000..a2d76fd69 --- /dev/null +++ b/contracts/token/ERC721/extensions/IERC721Metadata.sol @@ -0,0 +1,27 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (token/ERC721/extensions/IERC721Metadata.sol) + +pragma solidity ^0.8.20; + +import {IERC721} from "../IERC721.sol"; + +/** + * @title ERC-721 Non-Fungible Token Standard, optional metadata extension + * @dev See https://eips.ethereum.org/EIPS/eip-721 + */ +interface IERC721Metadata is IERC721 { + /** + * @dev Returns the token collection name. + */ + function name() external view returns (string memory); + + /** + * @dev Returns the token collection symbol. + */ + function symbol() external view returns (string memory); + + /** + * @dev Returns the Uniform Resource Identifier (URI) for `tokenId` token. + */ + function tokenURI(uint256 tokenId) external view returns (string memory); +} diff --git a/contracts/token/ERC721/utils/ERC721Holder.sol b/contracts/token/ERC721/utils/ERC721Holder.sol new file mode 100644 index 000000000..3943774d3 --- /dev/null +++ b/contracts/token/ERC721/utils/ERC721Holder.sol @@ -0,0 +1,24 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (token/ERC721/utils/ERC721Holder.sol) + +pragma solidity ^0.8.20; + +import {IERC721Receiver} from "../IERC721Receiver.sol"; + +/** + * @dev Implementation of the {IERC721Receiver} interface. + * + * Accepts all token transfers. + * Make sure the contract is able to use its token with {IERC721-safeTransferFrom}, {IERC721-approve} or + * {IERC721-setApprovalForAll}. + */ +abstract contract ERC721Holder is IERC721Receiver { + /** + * @dev See {IERC721Receiver-onERC721Received}. + * + * Always returns `IERC721Receiver.onERC721Received.selector`. + */ + function onERC721Received(address, address, uint256, bytes memory) public virtual returns (bytes4) { + return this.onERC721Received.selector; + } +} diff --git a/contracts/token/common/ERC2981.sol b/contracts/token/common/ERC2981.sol new file mode 100644 index 000000000..a885e21b5 --- /dev/null +++ b/contracts/token/common/ERC2981.sol @@ -0,0 +1,137 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (token/common/ERC2981.sol) + +pragma solidity ^0.8.20; + +import {IERC2981} from "../../interfaces/IERC2981.sol"; +import {IERC165, ERC165} from "../../utils/introspection/ERC165.sol"; + +/** + * @dev Implementation of the NFT Royalty Standard, a standardized way to retrieve royalty payment information. + * + * Royalty information can be specified globally for all token ids via {_setDefaultRoyalty}, and/or individually for + * specific token ids via {_setTokenRoyalty}. The latter takes precedence over the first. + * + * Royalty is specified as a fraction of sale price. {_feeDenominator} is overridable but defaults to 10000, meaning the + * fee is specified in basis points by default. + * + * IMPORTANT: ERC-2981 only specifies a way to signal royalty information and does not enforce its payment. See + * https://eips.ethereum.org/EIPS/eip-2981#optional-royalty-payments[Rationale] in the EIP. Marketplaces are expected to + * voluntarily pay royalties together with sales, but note that this standard is not yet widely supported. + */ +abstract contract ERC2981 is IERC2981, ERC165 { + struct RoyaltyInfo { + address receiver; + uint96 royaltyFraction; + } + + RoyaltyInfo private _defaultRoyaltyInfo; + mapping(uint256 tokenId => RoyaltyInfo) private _tokenRoyaltyInfo; + + /** + * @dev The default royalty set is invalid (eg. (numerator / denominator) >= 1). + */ + error ERC2981InvalidDefaultRoyalty(uint256 numerator, uint256 denominator); + + /** + * @dev The default royalty receiver is invalid. + */ + error ERC2981InvalidDefaultRoyaltyReceiver(address receiver); + + /** + * @dev The royalty set for an specific `tokenId` is invalid (eg. (numerator / denominator) >= 1). + */ + error ERC2981InvalidTokenRoyalty(uint256 tokenId, uint256 numerator, uint256 denominator); + + /** + * @dev The royalty receiver for `tokenId` is invalid. + */ + error ERC2981InvalidTokenRoyaltyReceiver(uint256 tokenId, address receiver); + + /** + * @dev See {IERC165-supportsInterface}. + */ + function supportsInterface(bytes4 interfaceId) public view virtual override(IERC165, ERC165) returns (bool) { + return interfaceId == type(IERC2981).interfaceId || super.supportsInterface(interfaceId); + } + + /** + * @inheritdoc IERC2981 + */ + function royaltyInfo(uint256 tokenId, uint256 salePrice) public view virtual returns (address, uint256) { + RoyaltyInfo memory royalty = _tokenRoyaltyInfo[tokenId]; + + if (royalty.receiver == address(0)) { + royalty = _defaultRoyaltyInfo; + } + + uint256 royaltyAmount = (salePrice * royalty.royaltyFraction) / _feeDenominator(); + + return (royalty.receiver, royaltyAmount); + } + + /** + * @dev The denominator with which to interpret the fee set in {_setTokenRoyalty} and {_setDefaultRoyalty} as a + * fraction of the sale price. Defaults to 10000 so fees are expressed in basis points, but may be customized by an + * override. + */ + function _feeDenominator() internal pure virtual returns (uint96) { + return 10000; + } + + /** + * @dev Sets the royalty information that all ids in this contract will default to. + * + * Requirements: + * + * - `receiver` cannot be the zero address. + * - `feeNumerator` cannot be greater than the fee denominator. + */ + function _setDefaultRoyalty(address receiver, uint96 feeNumerator) internal virtual { + uint256 denominator = _feeDenominator(); + if (feeNumerator > denominator) { + // Royalty fee will exceed the sale price + revert ERC2981InvalidDefaultRoyalty(feeNumerator, denominator); + } + if (receiver == address(0)) { + revert ERC2981InvalidDefaultRoyaltyReceiver(address(0)); + } + + _defaultRoyaltyInfo = RoyaltyInfo(receiver, feeNumerator); + } + + /** + * @dev Removes default royalty information. + */ + function _deleteDefaultRoyalty() internal virtual { + delete _defaultRoyaltyInfo; + } + + /** + * @dev Sets the royalty information for a specific token id, overriding the global default. + * + * Requirements: + * + * - `receiver` cannot be the zero address. + * - `feeNumerator` cannot be greater than the fee denominator. + */ + function _setTokenRoyalty(uint256 tokenId, address receiver, uint96 feeNumerator) internal virtual { + uint256 denominator = _feeDenominator(); + if (feeNumerator > denominator) { + // Royalty fee will exceed the sale price + revert ERC2981InvalidTokenRoyalty(tokenId, feeNumerator, denominator); + } + if (receiver == address(0)) { + revert ERC2981InvalidTokenRoyaltyReceiver(tokenId, address(0)); + } + + _tokenRoyaltyInfo[tokenId] = RoyaltyInfo(receiver, feeNumerator); + } + + /** + * @dev Resets royalty information for the token id back to the global default. + */ + function _resetTokenRoyalty(uint256 tokenId) internal virtual { + delete _tokenRoyaltyInfo[tokenId]; + } +} diff --git a/contracts/token/common/README.adoc b/contracts/token/common/README.adoc new file mode 100644 index 000000000..af6167464 --- /dev/null +++ b/contracts/token/common/README.adoc @@ -0,0 +1,10 @@ += Common (Tokens) + +Functionality that is common to multiple token standards. + +* {ERC2981}: NFT Royalties compatible with both ERC721 and ERC1155. +** For ERC721 consider {ERC721Royalty} which clears the royalty information from storage on burn. + +== Contracts + +{{ERC2981}} diff --git a/contracts/utils/Address.sol b/contracts/utils/Address.sol new file mode 100644 index 000000000..f8c157a9b --- /dev/null +++ b/contracts/utils/Address.sol @@ -0,0 +1,159 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (utils/Address.sol) + +pragma solidity ^0.8.20; + +/** + * @dev Collection of functions related to the address type + */ +library Address { + /** + * @dev The ETH balance of the account is not enough to perform the operation. + */ + error AddressInsufficientBalance(address account); + + /** + * @dev There's no code at `target` (it is not a contract). + */ + error AddressEmptyCode(address target); + + /** + * @dev A call to an address target failed. The target may have reverted. + */ + error FailedInnerCall(); + + /** + * @dev Replacement for Solidity's `transfer`: sends `amount` wei to + * `recipient`, forwarding all available gas and reverting on errors. + * + * https://eips.ethereum.org/EIPS/eip-1884[EIP1884] increases the gas cost + * of certain opcodes, possibly making contracts go over the 2300 gas limit + * imposed by `transfer`, making them unable to receive funds via + * `transfer`. {sendValue} removes this limitation. + * + * https://consensys.net/diligence/blog/2019/09/stop-using-soliditys-transfer-now/[Learn more]. + * + * IMPORTANT: because control is transferred to `recipient`, care must be + * taken to not create reentrancy vulnerabilities. Consider using + * {ReentrancyGuard} or the + * https://solidity.readthedocs.io/en/v0.8.20/security-considerations.html#use-the-checks-effects-interactions-pattern[checks-effects-interactions pattern]. + */ + function sendValue(address payable recipient, uint256 amount) internal { + if (address(this).balance < amount) { + revert AddressInsufficientBalance(address(this)); + } + + (bool success, ) = recipient.call{value: amount}(""); + if (!success) { + revert FailedInnerCall(); + } + } + + /** + * @dev Performs a Solidity function call using a low level `call`. A + * plain `call` is an unsafe replacement for a function call: use this + * function instead. + * + * If `target` reverts with a revert reason or custom error, it is bubbled + * up by this function (like regular Solidity function calls). However, if + * the call reverted with no returned reason, this function reverts with a + * {FailedInnerCall} error. + * + * Returns the raw returned data. To convert to the expected return value, + * use https://solidity.readthedocs.io/en/latest/units-and-global-variables.html?highlight=abi.decode#abi-encoding-and-decoding-functions[`abi.decode`]. + * + * Requirements: + * + * - `target` must be a contract. + * - calling `target` with `data` must not revert. + */ + function functionCall(address target, bytes memory data) internal returns (bytes memory) { + return functionCallWithValue(target, data, 0); + } + + /** + * @dev Same as {xref-Address-functionCall-address-bytes-}[`functionCall`], + * but also transferring `value` wei to `target`. + * + * Requirements: + * + * - the calling contract must have an ETH balance of at least `value`. + * - the called Solidity function must be `payable`. + */ + function functionCallWithValue(address target, bytes memory data, uint256 value) internal returns (bytes memory) { + if (address(this).balance < value) { + revert AddressInsufficientBalance(address(this)); + } + (bool success, bytes memory returndata) = target.call{value: value}(data); + return verifyCallResultFromTarget(target, success, returndata); + } + + /** + * @dev Same as {xref-Address-functionCall-address-bytes-}[`functionCall`], + * but performing a static call. + */ + function functionStaticCall(address target, bytes memory data) internal view returns (bytes memory) { + (bool success, bytes memory returndata) = target.staticcall(data); + return verifyCallResultFromTarget(target, success, returndata); + } + + /** + * @dev Same as {xref-Address-functionCall-address-bytes-}[`functionCall`], + * but performing a delegate call. + */ + function functionDelegateCall(address target, bytes memory data) internal returns (bytes memory) { + (bool success, bytes memory returndata) = target.delegatecall(data); + return verifyCallResultFromTarget(target, success, returndata); + } + + /** + * @dev Tool to verify that a low level call to smart-contract was successful, and reverts if the target + * was not a contract or bubbling up the revert reason (falling back to {FailedInnerCall}) in case of an + * unsuccessful call. + */ + function verifyCallResultFromTarget( + address target, + bool success, + bytes memory returndata + ) internal view returns (bytes memory) { + if (!success) { + _revert(returndata); + } else { + // only check if target is a contract if the call was successful and the return data is empty + // otherwise we already know that it was a contract + if (returndata.length == 0 && target.code.length == 0) { + revert AddressEmptyCode(target); + } + return returndata; + } + } + + /** + * @dev Tool to verify that a low level call was successful, and reverts if it wasn't, either by bubbling the + * revert reason or with a default {FailedInnerCall} error. + */ + function verifyCallResult(bool success, bytes memory returndata) internal pure returns (bytes memory) { + if (!success) { + _revert(returndata); + } else { + return returndata; + } + } + + /** + * @dev Reverts with returndata if present. Otherwise reverts with {FailedInnerCall}. + */ + function _revert(bytes memory returndata) private pure { + // Look for revert reason and bubble it up if present + if (returndata.length > 0) { + // The easiest way to bubble the revert reason is using memory via assembly + /// @solidity memory-safe-assembly + assembly { + let returndata_size := mload(returndata) + revert(add(32, returndata), returndata_size) + } + } else { + revert FailedInnerCall(); + } + } +} diff --git a/contracts/utils/Arrays.sol b/contracts/utils/Arrays.sol new file mode 100644 index 000000000..a34d0a7d6 --- /dev/null +++ b/contracts/utils/Arrays.sol @@ -0,0 +1,127 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (utils/Arrays.sol) + +pragma solidity ^0.8.20; + +import {StorageSlot} from "./StorageSlot.sol"; +import {Math} from "./math/Math.sol"; + +/** + * @dev Collection of functions related to array types. + */ +library Arrays { + using StorageSlot for bytes32; + + /** + * @dev Searches a sorted `array` and returns the first index that contains + * a value greater or equal to `element`. If no such index exists (i.e. all + * values in the array are strictly less than `element`), the array length is + * returned. Time complexity O(log n). + * + * `array` is expected to be sorted in ascending order, and to contain no + * repeated elements. + */ + function findUpperBound(uint256[] storage array, uint256 element) internal view returns (uint256) { + uint256 low = 0; + uint256 high = array.length; + + if (high == 0) { + return 0; + } + + while (low < high) { + uint256 mid = Math.average(low, high); + + // Note that mid will always be strictly less than high (i.e. it will be a valid array index) + // because Math.average rounds towards zero (it does integer division with truncation). + if (unsafeAccess(array, mid).value > element) { + high = mid; + } else { + low = mid + 1; + } + } + + // At this point `low` is the exclusive upper bound. We will return the inclusive upper bound. + if (low > 0 && unsafeAccess(array, low - 1).value == element) { + return low - 1; + } else { + return low; + } + } + + /** + * @dev Access an array in an "unsafe" way. Skips solidity "index-out-of-range" check. + * + * WARNING: Only use if you are certain `pos` is lower than the array length. + */ + function unsafeAccess(address[] storage arr, uint256 pos) internal pure returns (StorageSlot.AddressSlot storage) { + bytes32 slot; + // We use assembly to calculate the storage slot of the element at index `pos` of the dynamic array `arr` + // following https://docs.soliditylang.org/en/v0.8.20/internals/layout_in_storage.html#mappings-and-dynamic-arrays. + + /// @solidity memory-safe-assembly + assembly { + mstore(0, arr.slot) + slot := add(keccak256(0, 0x20), pos) + } + return slot.getAddressSlot(); + } + + /** + * @dev Access an array in an "unsafe" way. Skips solidity "index-out-of-range" check. + * + * WARNING: Only use if you are certain `pos` is lower than the array length. + */ + function unsafeAccess(bytes32[] storage arr, uint256 pos) internal pure returns (StorageSlot.Bytes32Slot storage) { + bytes32 slot; + // We use assembly to calculate the storage slot of the element at index `pos` of the dynamic array `arr` + // following https://docs.soliditylang.org/en/v0.8.20/internals/layout_in_storage.html#mappings-and-dynamic-arrays. + + /// @solidity memory-safe-assembly + assembly { + mstore(0, arr.slot) + slot := add(keccak256(0, 0x20), pos) + } + return slot.getBytes32Slot(); + } + + /** + * @dev Access an array in an "unsafe" way. Skips solidity "index-out-of-range" check. + * + * WARNING: Only use if you are certain `pos` is lower than the array length. + */ + function unsafeAccess(uint256[] storage arr, uint256 pos) internal pure returns (StorageSlot.Uint256Slot storage) { + bytes32 slot; + // We use assembly to calculate the storage slot of the element at index `pos` of the dynamic array `arr` + // following https://docs.soliditylang.org/en/v0.8.20/internals/layout_in_storage.html#mappings-and-dynamic-arrays. + + /// @solidity memory-safe-assembly + assembly { + mstore(0, arr.slot) + slot := add(keccak256(0, 0x20), pos) + } + return slot.getUint256Slot(); + } + + /** + * @dev Access an array in an "unsafe" way. Skips solidity "index-out-of-range" check. + * + * WARNING: Only use if you are certain `pos` is lower than the array length. + */ + function unsafeMemoryAccess(uint256[] memory arr, uint256 pos) internal pure returns (uint256 res) { + assembly { + res := mload(add(add(arr, 0x20), mul(pos, 0x20))) + } + } + + /** + * @dev Access an array in an "unsafe" way. Skips solidity "index-out-of-range" check. + * + * WARNING: Only use if you are certain `pos` is lower than the array length. + */ + function unsafeMemoryAccess(address[] memory arr, uint256 pos) internal pure returns (address res) { + assembly { + res := mload(add(add(arr, 0x20), mul(pos, 0x20))) + } + } +} diff --git a/contracts/utils/Base64.sol b/contracts/utils/Base64.sol new file mode 100644 index 000000000..0b76284d0 --- /dev/null +++ b/contracts/utils/Base64.sol @@ -0,0 +1,90 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (utils/Base64.sol) + +pragma solidity ^0.8.20; + +/** + * @dev Provides a set of functions to operate with Base64 strings. + */ +library Base64 { + /** + * @dev Base64 Encoding/Decoding Table + */ + string internal constant _TABLE = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/"; + + /** + * @dev Converts a `bytes` to its Bytes64 `string` representation. + */ + function encode(bytes memory data) internal pure returns (string memory) { + /** + * Inspired by Brecht Devos (Brechtpd) implementation - MIT licence + * https://github.com/Brechtpd/base64/blob/e78d9fd951e7b0977ddca77d92dc85183770daf4/base64.sol + */ + if (data.length == 0) return ""; + + // Loads the table into memory + string memory table = _TABLE; + + // Encoding takes 3 bytes chunks of binary data from `bytes` data parameter + // and split into 4 numbers of 6 bits. + // The final Base64 length should be `bytes` data length multiplied by 4/3 rounded up + // - `data.length + 2` -> Round up + // - `/ 3` -> Number of 3-bytes chunks + // - `4 *` -> 4 characters for each chunk + string memory result = new string(4 * ((data.length + 2) / 3)); + + /// @solidity memory-safe-assembly + assembly { + // Prepare the lookup table (skip the first "length" byte) + let tablePtr := add(table, 1) + + // Prepare result pointer, jump over length + let resultPtr := add(result, 32) + + // Run over the input, 3 bytes at a time + for { + let dataPtr := data + let endPtr := add(data, mload(data)) + } lt(dataPtr, endPtr) { + + } { + // Advance 3 bytes + dataPtr := add(dataPtr, 3) + let input := mload(dataPtr) + + // To write each character, shift the 3 bytes (18 bits) chunk + // 4 times in blocks of 6 bits for each character (18, 12, 6, 0) + // and apply logical AND with 0x3F which is the number of + // the previous character in the ASCII table prior to the Base64 Table + // The result is then added to the table to get the character to write, + // and finally write it in the result pointer but with a left shift + // of 256 (1 byte) - 8 (1 ASCII char) = 248 bits + + mstore8(resultPtr, mload(add(tablePtr, and(shr(18, input), 0x3F)))) + resultPtr := add(resultPtr, 1) // Advance + + mstore8(resultPtr, mload(add(tablePtr, and(shr(12, input), 0x3F)))) + resultPtr := add(resultPtr, 1) // Advance + + mstore8(resultPtr, mload(add(tablePtr, and(shr(6, input), 0x3F)))) + resultPtr := add(resultPtr, 1) // Advance + + mstore8(resultPtr, mload(add(tablePtr, and(input, 0x3F)))) + resultPtr := add(resultPtr, 1) // Advance + } + + // When data `bytes` is not exactly 3 bytes long + // it is padded with `=` characters at the end + switch mod(mload(data), 3) + case 1 { + mstore8(sub(resultPtr, 1), 0x3d) + mstore8(sub(resultPtr, 2), 0x3d) + } + case 2 { + mstore8(sub(resultPtr, 1), 0x3d) + } + } + + return result; + } +} diff --git a/contracts/utils/Context.sol b/contracts/utils/Context.sol new file mode 100644 index 000000000..9c48a6b31 --- /dev/null +++ b/contracts/utils/Context.sol @@ -0,0 +1,24 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (utils/Context.sol) + +pragma solidity ^0.8.20; + +/** + * @dev Provides information about the current execution context, including the + * sender of the transaction and its data. While these are generally available + * via msg.sender and msg.data, they should not be accessed in such a direct + * manner, since when dealing with meta-transactions the account sending and + * paying for execution may not be the actual sender (as far as an application + * is concerned). + * + * This contract is only required for intermediate, library-like contracts. + */ +abstract contract Context { + function _msgSender() internal view virtual returns (address) { + return msg.sender; + } + + function _msgData() internal view virtual returns (bytes calldata) { + return msg.data; + } +} diff --git a/contracts/utils/Create2.sol b/contracts/utils/Create2.sol new file mode 100644 index 000000000..99f2242bd --- /dev/null +++ b/contracts/utils/Create2.sol @@ -0,0 +1,96 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (utils/Create2.sol) + +pragma solidity ^0.8.20; + +/** + * @dev Helper to make usage of the `CREATE2` EVM opcode easier and safer. + * `CREATE2` can be used to compute in advance the address where a smart + * contract will be deployed, which allows for interesting new mechanisms known + * as 'counterfactual interactions'. + * + * See the https://eips.ethereum.org/EIPS/eip-1014#motivation[EIP] for more + * information. + */ +library Create2 { + /** + * @dev Not enough balance for performing a CREATE2 deploy. + */ + error Create2InsufficientBalance(uint256 balance, uint256 needed); + + /** + * @dev There's no code to deploy. + */ + error Create2EmptyBytecode(); + + /** + * @dev The deployment failed. + */ + error Create2FailedDeployment(); + + /** + * @dev Deploys a contract using `CREATE2`. The address where the contract + * will be deployed can be known in advance via {computeAddress}. + * + * The bytecode for a contract can be obtained from Solidity with + * `type(contractName).creationCode`. + * + * Requirements: + * + * - `bytecode` must not be empty. + * - `salt` must have not been used for `bytecode` already. + * - the factory must have a balance of at least `amount`. + * - if `amount` is non-zero, `bytecode` must have a `payable` constructor. + */ + function deploy(uint256 amount, bytes32 salt, bytes memory bytecode) internal returns (address addr) { + if (address(this).balance < amount) { + revert Create2InsufficientBalance(address(this).balance, amount); + } + if (bytecode.length == 0) { + revert Create2EmptyBytecode(); + } + /// @solidity memory-safe-assembly + assembly { + addr := create2(amount, add(bytecode, 0x20), mload(bytecode), salt) + } + if (addr == address(0)) { + revert Create2FailedDeployment(); + } + } + + /** + * @dev Returns the address where a contract will be stored if deployed via {deploy}. Any change in the + * `bytecodeHash` or `salt` will result in a new destination address. + */ + function computeAddress(bytes32 salt, bytes32 bytecodeHash) internal view returns (address) { + return computeAddress(salt, bytecodeHash, address(this)); + } + + /** + * @dev Returns the address where a contract will be stored if deployed via {deploy} from a contract located at + * `deployer`. If `deployer` is this contract's address, returns the same value as {computeAddress}. + */ + function computeAddress(bytes32 salt, bytes32 bytecodeHash, address deployer) internal pure returns (address addr) { + /// @solidity memory-safe-assembly + assembly { + let ptr := mload(0x40) // Get free memory pointer + + // | | ↓ ptr ... ↓ ptr + 0x0B (start) ... ↓ ptr + 0x20 ... ↓ ptr + 0x40 ... | + // |-------------------|---------------------------------------------------------------------------| + // | bytecodeHash | CCCCCCCCCCCCC...CC | + // | salt | BBBBBBBBBBBBB...BB | + // | deployer | 000000...0000AAAAAAAAAAAAAAAAAAA...AA | + // | 0xFF | FF | + // |-------------------|---------------------------------------------------------------------------| + // | memory | 000000...00FFAAAAAAAAAAAAAAAAAAA...AABBBBBBBBBBBBB...BBCCCCCCCCCCCCC...CC | + // | keccak(start, 85) | ↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑ | + + mstore(add(ptr, 0x40), bytecodeHash) + mstore(add(ptr, 0x20), salt) + mstore(ptr, deployer) // Right-aligned with 12 preceding garbage bytes + let start := add(ptr, 0x0b) // The hashed data starts at the final garbage byte which we will set to 0xff + mstore8(start, 0xff) + addr := keccak256(start, 85) + } + } +} diff --git a/contracts/utils/Multicall.sol b/contracts/utils/Multicall.sol new file mode 100644 index 000000000..f6c8432d3 --- /dev/null +++ b/contracts/utils/Multicall.sol @@ -0,0 +1,23 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (utils/Multicall.sol) + +pragma solidity ^0.8.20; + +import {Address} from "./Address.sol"; + +/** + * @dev Provides a function to batch together multiple calls in a single external call. + */ +abstract contract Multicall { + /** + * @dev Receives and executes a batch of function calls on this contract. + * @custom:oz-upgrades-unsafe-allow-reachable delegatecall + */ + function multicall(bytes[] calldata data) external virtual returns (bytes[] memory results) { + results = new bytes[](data.length); + for (uint256 i = 0; i < data.length; i++) { + results[i] = Address.functionDelegateCall(address(this), data[i]); + } + return results; + } +} diff --git a/contracts/utils/Nonces.sol b/contracts/utils/Nonces.sol new file mode 100644 index 000000000..500dcd9d4 --- /dev/null +++ b/contracts/utils/Nonces.sol @@ -0,0 +1,46 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (utils/Nonces.sol) +pragma solidity ^0.8.20; + +/** + * @dev Provides tracking nonces for addresses. Nonces will only increment. + */ +abstract contract Nonces { + /** + * @dev The nonce used for an `account` is not the expected current nonce. + */ + error InvalidAccountNonce(address account, uint256 currentNonce); + + mapping(address account => uint256) private _nonces; + + /** + * @dev Returns the next unused nonce for an address. + */ + function nonces(address owner) public view virtual returns (uint256) { + return _nonces[owner]; + } + + /** + * @dev Consumes a nonce. + * + * Returns the current value and increments nonce. + */ + function _useNonce(address owner) internal virtual returns (uint256) { + // For each account, the nonce has an initial value of 0, can only be incremented by one, and cannot be + // decremented or reset. This guarantees that the nonce never overflows. + unchecked { + // It is important to do x++ and not ++x here. + return _nonces[owner]++; + } + } + + /** + * @dev Same as {_useNonce} but checking that `nonce` is the next valid for `owner`. + */ + function _useCheckedNonce(address owner, uint256 nonce) internal virtual { + uint256 current = _useNonce(owner); + if (nonce != current) { + revert InvalidAccountNonce(owner, current); + } + } +} diff --git a/contracts/utils/Pausable.sol b/contracts/utils/Pausable.sol new file mode 100644 index 000000000..5b3e72a6b --- /dev/null +++ b/contracts/utils/Pausable.sol @@ -0,0 +1,119 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (utils/Pausable.sol) + +pragma solidity ^0.8.20; + +import {Context} from "../utils/Context.sol"; + +/** + * @dev Contract module which allows children to implement an emergency stop + * mechanism that can be triggered by an authorized account. + * + * This module is used through inheritance. It will make available the + * modifiers `whenNotPaused` and `whenPaused`, which can be applied to + * the functions of your contract. Note that they will not be pausable by + * simply including this module, only once the modifiers are put in place. + */ +abstract contract Pausable is Context { + bool private _paused; + + /** + * @dev Emitted when the pause is triggered by `account`. + */ + event Paused(address account); + + /** + * @dev Emitted when the pause is lifted by `account`. + */ + event Unpaused(address account); + + /** + * @dev The operation failed because the contract is paused. + */ + error EnforcedPause(); + + /** + * @dev The operation failed because the contract is not paused. + */ + error ExpectedPause(); + + /** + * @dev Initializes the contract in unpaused state. + */ + constructor() { + _paused = false; + } + + /** + * @dev Modifier to make a function callable only when the contract is not paused. + * + * Requirements: + * + * - The contract must not be paused. + */ + modifier whenNotPaused() { + _requireNotPaused(); + _; + } + + /** + * @dev Modifier to make a function callable only when the contract is paused. + * + * Requirements: + * + * - The contract must be paused. + */ + modifier whenPaused() { + _requirePaused(); + _; + } + + /** + * @dev Returns true if the contract is paused, and false otherwise. + */ + function paused() public view virtual returns (bool) { + return _paused; + } + + /** + * @dev Throws if the contract is paused. + */ + function _requireNotPaused() internal view virtual { + if (paused()) { + revert EnforcedPause(); + } + } + + /** + * @dev Throws if the contract is not paused. + */ + function _requirePaused() internal view virtual { + if (!paused()) { + revert ExpectedPause(); + } + } + + /** + * @dev Triggers stopped state. + * + * Requirements: + * + * - The contract must not be paused. + */ + function _pause() internal virtual whenNotPaused { + _paused = true; + emit Paused(_msgSender()); + } + + /** + * @dev Returns to normal state. + * + * Requirements: + * + * - The contract must be paused. + */ + function _unpause() internal virtual whenPaused { + _paused = false; + emit Unpaused(_msgSender()); + } +} diff --git a/contracts/utils/README.adoc b/contracts/utils/README.adoc new file mode 100644 index 000000000..d88b00199 --- /dev/null +++ b/contracts/utils/README.adoc @@ -0,0 +1,88 @@ += Utilities + +[.readme-notice] +NOTE: This document is better viewed at https://docs.openzeppelin.com/contracts/api/utils + +Miscellaneous contracts and libraries containing utility functions you can use to improve security, work with new data types, or safely use low-level primitives. + + * {ReentrancyGuard}: A modifier that can prevent reentrancy during certain functions. + * {Pausable}: A common emergency response mechanism that can pause functionality while a remediation is pending. + * {SafeCast}: Checked downcasting functions to avoid silent truncation. + * {Math}, {SignedMath}: Implementation of various arithmetic functions. + * {Multicall}: Simple way to batch together multiple calls in a single external call. + * {Create2}: Wrapper around the https://blog.openzeppelin.com/getting-the-most-out-of-create2/[`CREATE2` EVM opcode] for safe use without having to deal with low-level assembly. + * {EnumerableMap}: A type like Solidity's https://solidity.readthedocs.io/en/latest/types.html#mapping-types[`mapping`], but with key-value _enumeration_: this will let you know how many entries a mapping has, and iterate over them (which is not possible with `mapping`). + * {EnumerableSet}: Like {EnumerableMap}, but for https://en.wikipedia.org/wiki/Set_(abstract_data_type)[sets]. Can be used to store privileged accounts, issued IDs, etc. + +[NOTE] +==== +Because Solidity does not support generic types, {EnumerableMap} and {EnumerableSet} are specialized to a limited number of key-value types. +==== + +== Math + +{{Math}} + +{{SignedMath}} + +{{SafeCast}} + +== Cryptography + +{{ECDSA}} + +{{MessageHashUtils}} + +{{SignatureChecker}} + +{{MerkleProof}} + +{{EIP712}} + +== Security + +{{ReentrancyGuard}} + +{{Pausable}} + +== Introspection + +This set of interfaces and contracts deal with https://en.wikipedia.org/wiki/Type_introspection[type introspection] of contracts, that is, examining which functions can be called on them. This is usually referred to as a contract's _interface_. + +Ethereum contracts have no native concept of an interface, so applications must usually simply trust they are not making an incorrect call. For trusted setups this is a non-issue, but often unknown and untrusted third-party addresses need to be interacted with. There may even not be any direct calls to them! (e.g. `ERC20` tokens may be sent to a contract that lacks a way to transfer them out of it, locking them forever). In these cases, a contract _declaring_ its interface can be very helpful in preventing errors. + +{{IERC165}} + +{{ERC165}} + +{{ERC165Checker}} + +== Data Structures + +{{BitMaps}} + +{{EnumerableMap}} + +{{EnumerableSet}} + +{{DoubleEndedQueue}} + +{{Checkpoints}} + +== Libraries + +{{Create2}} + +{{Address}} + +{{Arrays}} + +{{Base64}} + +{{Strings}} + +{{ShortStrings}} + +{{StorageSlot}} + +{{Multicall}} diff --git a/contracts/utils/ReentrancyGuard.sol b/contracts/utils/ReentrancyGuard.sol new file mode 100644 index 000000000..92108edff --- /dev/null +++ b/contracts/utils/ReentrancyGuard.sol @@ -0,0 +1,84 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (utils/ReentrancyGuard.sol) + +pragma solidity ^0.8.20; + +/** + * @dev Contract module that helps prevent reentrant calls to a function. + * + * Inheriting from `ReentrancyGuard` will make the {nonReentrant} modifier + * available, which can be applied to functions to make sure there are no nested + * (reentrant) calls to them. + * + * Note that because there is a single `nonReentrant` guard, functions marked as + * `nonReentrant` may not call one another. This can be worked around by making + * those functions `private`, and then adding `external` `nonReentrant` entry + * points to them. + * + * TIP: If you would like to learn more about reentrancy and alternative ways + * to protect against it, check out our blog post + * https://blog.openzeppelin.com/reentrancy-after-istanbul/[Reentrancy After Istanbul]. + */ +abstract contract ReentrancyGuard { + // Booleans are more expensive than uint256 or any type that takes up a full + // word because each write operation emits an extra SLOAD to first read the + // slot's contents, replace the bits taken up by the boolean, and then write + // back. This is the compiler's defense against contract upgrades and + // pointer aliasing, and it cannot be disabled. + + // The values being non-zero value makes deployment a bit more expensive, + // but in exchange the refund on every call to nonReentrant will be lower in + // amount. Since refunds are capped to a percentage of the total + // transaction's gas, it is best to keep them low in cases like this one, to + // increase the likelihood of the full refund coming into effect. + uint256 private constant NOT_ENTERED = 1; + uint256 private constant ENTERED = 2; + + uint256 private _status; + + /** + * @dev Unauthorized reentrant call. + */ + error ReentrancyGuardReentrantCall(); + + constructor() { + _status = NOT_ENTERED; + } + + /** + * @dev Prevents a contract from calling itself, directly or indirectly. + * Calling a `nonReentrant` function from another `nonReentrant` + * function is not supported. It is possible to prevent this from happening + * by making the `nonReentrant` function external, and making it call a + * `private` function that does the actual work. + */ + modifier nonReentrant() { + _nonReentrantBefore(); + _; + _nonReentrantAfter(); + } + + function _nonReentrantBefore() private { + // On the first call to nonReentrant, _status will be NOT_ENTERED + if (_status == ENTERED) { + revert ReentrancyGuardReentrantCall(); + } + + // Any calls to nonReentrant after this point will fail + _status = ENTERED; + } + + function _nonReentrantAfter() private { + // By storing the original value once again, a refund is triggered (see + // https://eips.ethereum.org/EIPS/eip-2200) + _status = NOT_ENTERED; + } + + /** + * @dev Returns true if the reentrancy guard is currently set to "entered", which indicates there is a + * `nonReentrant` function in the call stack. + */ + function _reentrancyGuardEntered() internal view returns (bool) { + return _status == ENTERED; + } +} diff --git a/contracts/utils/ShortStrings.sol b/contracts/utils/ShortStrings.sol new file mode 100644 index 000000000..87dd081bd --- /dev/null +++ b/contracts/utils/ShortStrings.sol @@ -0,0 +1,123 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (utils/ShortStrings.sol) + +pragma solidity ^0.8.20; + +import {StorageSlot} from "./StorageSlot.sol"; + +// | string | 0xAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA | +// | length | 0x BB | +type ShortString is bytes32; + +/** + * @dev This library provides functions to convert short memory strings + * into a `ShortString` type that can be used as an immutable variable. + * + * Strings of arbitrary length can be optimized using this library if + * they are short enough (up to 31 bytes) by packing them with their + * length (1 byte) in a single EVM word (32 bytes). Additionally, a + * fallback mechanism can be used for every other case. + * + * Usage example: + * + * ```solidity + * contract Named { + * using ShortStrings for *; + * + * ShortString private immutable _name; + * string private _nameFallback; + * + * constructor(string memory contractName) { + * _name = contractName.toShortStringWithFallback(_nameFallback); + * } + * + * function name() external view returns (string memory) { + * return _name.toStringWithFallback(_nameFallback); + * } + * } + * ``` + */ +library ShortStrings { + // Used as an identifier for strings longer than 31 bytes. + bytes32 private constant FALLBACK_SENTINEL = 0x00000000000000000000000000000000000000000000000000000000000000FF; + + error StringTooLong(string str); + error InvalidShortString(); + + /** + * @dev Encode a string of at most 31 chars into a `ShortString`. + * + * This will trigger a `StringTooLong` error is the input string is too long. + */ + function toShortString(string memory str) internal pure returns (ShortString) { + bytes memory bstr = bytes(str); + if (bstr.length > 31) { + revert StringTooLong(str); + } + return ShortString.wrap(bytes32(uint256(bytes32(bstr)) | bstr.length)); + } + + /** + * @dev Decode a `ShortString` back to a "normal" string. + */ + function toString(ShortString sstr) internal pure returns (string memory) { + uint256 len = byteLength(sstr); + // using `new string(len)` would work locally but is not memory safe. + string memory str = new string(32); + /// @solidity memory-safe-assembly + assembly { + mstore(str, len) + mstore(add(str, 0x20), sstr) + } + return str; + } + + /** + * @dev Return the length of a `ShortString`. + */ + function byteLength(ShortString sstr) internal pure returns (uint256) { + uint256 result = uint256(ShortString.unwrap(sstr)) & 0xFF; + if (result > 31) { + revert InvalidShortString(); + } + return result; + } + + /** + * @dev Encode a string into a `ShortString`, or write it to storage if it is too long. + */ + function toShortStringWithFallback(string memory value, string storage store) internal returns (ShortString) { + if (bytes(value).length < 32) { + return toShortString(value); + } else { + StorageSlot.getStringSlot(store).value = value; + return ShortString.wrap(FALLBACK_SENTINEL); + } + } + + /** + * @dev Decode a string that was encoded to `ShortString` or written to storage using {setWithFallback}. + */ + function toStringWithFallback(ShortString value, string storage store) internal pure returns (string memory) { + if (ShortString.unwrap(value) != FALLBACK_SENTINEL) { + return toString(value); + } else { + return store; + } + } + + /** + * @dev Return the length of a string that was encoded to `ShortString` or written to storage using + * {setWithFallback}. + * + * WARNING: This will return the "byte length" of the string. This may not reflect the actual length in terms of + * actual characters as the UTF-8 encoding of a single character can span over multiple bytes. + */ + function byteLengthWithFallback(ShortString value, string storage store) internal view returns (uint256) { + if (ShortString.unwrap(value) != FALLBACK_SENTINEL) { + return byteLength(value); + } else { + return bytes(store).length; + } + } +} diff --git a/contracts/utils/StorageSlot.sol b/contracts/utils/StorageSlot.sol new file mode 100644 index 000000000..4618c6550 --- /dev/null +++ b/contracts/utils/StorageSlot.sol @@ -0,0 +1,135 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (utils/StorageSlot.sol) +// This file was procedurally generated from scripts/generate/templates/StorageSlot.js. + +pragma solidity ^0.8.20; + +/** + * @dev Library for reading and writing primitive types to specific storage slots. + * + * Storage slots are often used to avoid storage conflict when dealing with upgradeable contracts. + * This library helps with reading and writing to such slots without the need for inline assembly. + * + * The functions in this library return Slot structs that contain a `value` member that can be used to read or write. + * + * Example usage to set ERC1967 implementation slot: + * ```solidity + * contract ERC1967 { + * bytes32 internal constant _IMPLEMENTATION_SLOT = 0x360894a13ba1a3210667c828492db98dca3e2076cc3735a920a3ca505d382bbc; + * + * function _getImplementation() internal view returns (address) { + * return StorageSlot.getAddressSlot(_IMPLEMENTATION_SLOT).value; + * } + * + * function _setImplementation(address newImplementation) internal { + * require(newImplementation.code.length > 0); + * StorageSlot.getAddressSlot(_IMPLEMENTATION_SLOT).value = newImplementation; + * } + * } + * ``` + */ +library StorageSlot { + struct AddressSlot { + address value; + } + + struct BooleanSlot { + bool value; + } + + struct Bytes32Slot { + bytes32 value; + } + + struct Uint256Slot { + uint256 value; + } + + struct StringSlot { + string value; + } + + struct BytesSlot { + bytes value; + } + + /** + * @dev Returns an `AddressSlot` with member `value` located at `slot`. + */ + function getAddressSlot(bytes32 slot) internal pure returns (AddressSlot storage r) { + /// @solidity memory-safe-assembly + assembly { + r.slot := slot + } + } + + /** + * @dev Returns an `BooleanSlot` with member `value` located at `slot`. + */ + function getBooleanSlot(bytes32 slot) internal pure returns (BooleanSlot storage r) { + /// @solidity memory-safe-assembly + assembly { + r.slot := slot + } + } + + /** + * @dev Returns an `Bytes32Slot` with member `value` located at `slot`. + */ + function getBytes32Slot(bytes32 slot) internal pure returns (Bytes32Slot storage r) { + /// @solidity memory-safe-assembly + assembly { + r.slot := slot + } + } + + /** + * @dev Returns an `Uint256Slot` with member `value` located at `slot`. + */ + function getUint256Slot(bytes32 slot) internal pure returns (Uint256Slot storage r) { + /// @solidity memory-safe-assembly + assembly { + r.slot := slot + } + } + + /** + * @dev Returns an `StringSlot` with member `value` located at `slot`. + */ + function getStringSlot(bytes32 slot) internal pure returns (StringSlot storage r) { + /// @solidity memory-safe-assembly + assembly { + r.slot := slot + } + } + + /** + * @dev Returns an `StringSlot` representation of the string storage pointer `store`. + */ + function getStringSlot(string storage store) internal pure returns (StringSlot storage r) { + /// @solidity memory-safe-assembly + assembly { + r.slot := store.slot + } + } + + /** + * @dev Returns an `BytesSlot` with member `value` located at `slot`. + */ + function getBytesSlot(bytes32 slot) internal pure returns (BytesSlot storage r) { + /// @solidity memory-safe-assembly + assembly { + r.slot := slot + } + } + + /** + * @dev Returns an `BytesSlot` representation of the bytes storage pointer `store`. + */ + function getBytesSlot(bytes storage store) internal pure returns (BytesSlot storage r) { + /// @solidity memory-safe-assembly + assembly { + r.slot := store.slot + } + } +} diff --git a/contracts/utils/Strings.sol b/contracts/utils/Strings.sol new file mode 100644 index 000000000..be42c0b13 --- /dev/null +++ b/contracts/utils/Strings.sol @@ -0,0 +1,94 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (utils/Strings.sol) + +pragma solidity ^0.8.20; + +import {Math} from "./math/Math.sol"; +import {SignedMath} from "./math/SignedMath.sol"; + +/** + * @dev String operations. + */ +library Strings { + bytes16 private constant HEX_DIGITS = "0123456789abcdef"; + uint8 private constant ADDRESS_LENGTH = 20; + + /** + * @dev The `value` string doesn't fit in the specified `length`. + */ + error StringsInsufficientHexLength(uint256 value, uint256 length); + + /** + * @dev Converts a `uint256` to its ASCII `string` decimal representation. + */ + function toString(uint256 value) internal pure returns (string memory) { + unchecked { + uint256 length = Math.log10(value) + 1; + string memory buffer = new string(length); + uint256 ptr; + /// @solidity memory-safe-assembly + assembly { + ptr := add(buffer, add(32, length)) + } + while (true) { + ptr--; + /// @solidity memory-safe-assembly + assembly { + mstore8(ptr, byte(mod(value, 10), HEX_DIGITS)) + } + value /= 10; + if (value == 0) break; + } + return buffer; + } + } + + /** + * @dev Converts a `int256` to its ASCII `string` decimal representation. + */ + function toStringSigned(int256 value) internal pure returns (string memory) { + return string.concat(value < 0 ? "-" : "", toString(SignedMath.abs(value))); + } + + /** + * @dev Converts a `uint256` to its ASCII `string` hexadecimal representation. + */ + function toHexString(uint256 value) internal pure returns (string memory) { + unchecked { + return toHexString(value, Math.log256(value) + 1); + } + } + + /** + * @dev Converts a `uint256` to its ASCII `string` hexadecimal representation with fixed length. + */ + function toHexString(uint256 value, uint256 length) internal pure returns (string memory) { + uint256 localValue = value; + bytes memory buffer = new bytes(2 * length + 2); + buffer[0] = "0"; + buffer[1] = "x"; + for (uint256 i = 2 * length + 1; i > 1; --i) { + buffer[i] = HEX_DIGITS[localValue & 0xf]; + localValue >>= 4; + } + if (localValue != 0) { + revert StringsInsufficientHexLength(value, length); + } + return string(buffer); + } + + /** + * @dev Converts an `address` with fixed length of 20 bytes to its not checksummed ASCII `string` hexadecimal + * representation. + */ + function toHexString(address addr) internal pure returns (string memory) { + return toHexString(uint256(uint160(addr)), ADDRESS_LENGTH); + } + + /** + * @dev Returns true if the two strings are equal. + */ + function equal(string memory a, string memory b) internal pure returns (bool) { + return bytes(a).length == bytes(b).length && keccak256(bytes(a)) == keccak256(bytes(b)); + } +} diff --git a/contracts/utils/cryptography/ECDSA.sol b/contracts/utils/cryptography/ECDSA.sol new file mode 100644 index 000000000..ea8127a92 --- /dev/null +++ b/contracts/utils/cryptography/ECDSA.sol @@ -0,0 +1,174 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (utils/cryptography/ECDSA.sol) + +pragma solidity ^0.8.20; + +/** + * @dev Elliptic Curve Digital Signature Algorithm (ECDSA) operations. + * + * These functions can be used to verify that a message was signed by the holder + * of the private keys of a given address. + */ +library ECDSA { + enum RecoverError { + NoError, + InvalidSignature, + InvalidSignatureLength, + InvalidSignatureS + } + + /** + * @dev The signature derives the `address(0)`. + */ + error ECDSAInvalidSignature(); + + /** + * @dev The signature has an invalid length. + */ + error ECDSAInvalidSignatureLength(uint256 length); + + /** + * @dev The signature has an S value that is in the upper half order. + */ + error ECDSAInvalidSignatureS(bytes32 s); + + /** + * @dev Returns the address that signed a hashed message (`hash`) with `signature` or an error. This will not + * return address(0) without also returning an error description. Errors are documented using an enum (error type) + * and a bytes32 providing additional information about the error. + * + * If no error is returned, then the address can be used for verification purposes. + * + * The `ecrecover` EVM precompile allows for malleable (non-unique) signatures: + * this function rejects them by requiring the `s` value to be in the lower + * half order, and the `v` value to be either 27 or 28. + * + * IMPORTANT: `hash` _must_ be the result of a hash operation for the + * verification to be secure: it is possible to craft signatures that + * recover to arbitrary addresses for non-hashed data. A safe way to ensure + * this is by receiving a hash of the original message (which may otherwise + * be too long), and then calling {MessageHashUtils-toEthSignedMessageHash} on it. + * + * Documentation for signature generation: + * - with https://web3js.readthedocs.io/en/v1.3.4/web3-eth-accounts.html#sign[Web3.js] + * - with https://docs.ethers.io/v5/api/signer/#Signer-signMessage[ethers] + */ + function tryRecover(bytes32 hash, bytes memory signature) internal pure returns (address, RecoverError, bytes32) { + if (signature.length == 65) { + bytes32 r; + bytes32 s; + uint8 v; + // ecrecover takes the signature parameters, and the only way to get them + // currently is to use assembly. + /// @solidity memory-safe-assembly + assembly { + r := mload(add(signature, 0x20)) + s := mload(add(signature, 0x40)) + v := byte(0, mload(add(signature, 0x60))) + } + return tryRecover(hash, v, r, s); + } else { + return (address(0), RecoverError.InvalidSignatureLength, bytes32(signature.length)); + } + } + + /** + * @dev Returns the address that signed a hashed message (`hash`) with + * `signature`. This address can then be used for verification purposes. + * + * The `ecrecover` EVM precompile allows for malleable (non-unique) signatures: + * this function rejects them by requiring the `s` value to be in the lower + * half order, and the `v` value to be either 27 or 28. + * + * IMPORTANT: `hash` _must_ be the result of a hash operation for the + * verification to be secure: it is possible to craft signatures that + * recover to arbitrary addresses for non-hashed data. A safe way to ensure + * this is by receiving a hash of the original message (which may otherwise + * be too long), and then calling {MessageHashUtils-toEthSignedMessageHash} on it. + */ + function recover(bytes32 hash, bytes memory signature) internal pure returns (address) { + (address recovered, RecoverError error, bytes32 errorArg) = tryRecover(hash, signature); + _throwError(error, errorArg); + return recovered; + } + + /** + * @dev Overload of {ECDSA-tryRecover} that receives the `r` and `vs` short-signature fields separately. + * + * See https://eips.ethereum.org/EIPS/eip-2098[EIP-2098 short signatures] + */ + function tryRecover(bytes32 hash, bytes32 r, bytes32 vs) internal pure returns (address, RecoverError, bytes32) { + unchecked { + bytes32 s = vs & bytes32(0x7fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff); + // We do not check for an overflow here since the shift operation results in 0 or 1. + uint8 v = uint8((uint256(vs) >> 255) + 27); + return tryRecover(hash, v, r, s); + } + } + + /** + * @dev Overload of {ECDSA-recover} that receives the `r and `vs` short-signature fields separately. + */ + function recover(bytes32 hash, bytes32 r, bytes32 vs) internal pure returns (address) { + (address recovered, RecoverError error, bytes32 errorArg) = tryRecover(hash, r, vs); + _throwError(error, errorArg); + return recovered; + } + + /** + * @dev Overload of {ECDSA-tryRecover} that receives the `v`, + * `r` and `s` signature fields separately. + */ + function tryRecover( + bytes32 hash, + uint8 v, + bytes32 r, + bytes32 s + ) internal pure returns (address, RecoverError, bytes32) { + // EIP-2 still allows signature malleability for ecrecover(). Remove this possibility and make the signature + // unique. Appendix F in the Ethereum Yellow paper (https://ethereum.github.io/yellowpaper/paper.pdf), defines + // the valid range for s in (301): 0 < s < secp256k1n ÷ 2 + 1, and for v in (302): v ∈ {27, 28}. Most + // signatures from current libraries generate a unique signature with an s-value in the lower half order. + // + // If your library generates malleable signatures, such as s-values in the upper range, calculate a new s-value + // with 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFEBAAEDCE6AF48A03BBFD25E8CD0364141 - s1 and flip v from 27 to 28 or + // vice versa. If your library also generates signatures with 0/1 for v instead 27/28, add 27 to v to accept + // these malleable signatures as well. + if (uint256(s) > 0x7FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF5D576E7357A4501DDFE92F46681B20A0) { + return (address(0), RecoverError.InvalidSignatureS, s); + } + + // If the signature is valid (and not malleable), return the signer address + address signer = ecrecover(hash, v, r, s); + if (signer == address(0)) { + return (address(0), RecoverError.InvalidSignature, bytes32(0)); + } + + return (signer, RecoverError.NoError, bytes32(0)); + } + + /** + * @dev Overload of {ECDSA-recover} that receives the `v`, + * `r` and `s` signature fields separately. + */ + function recover(bytes32 hash, uint8 v, bytes32 r, bytes32 s) internal pure returns (address) { + (address recovered, RecoverError error, bytes32 errorArg) = tryRecover(hash, v, r, s); + _throwError(error, errorArg); + return recovered; + } + + /** + * @dev Optionally reverts with the corresponding custom error according to the `error` argument provided. + */ + function _throwError(RecoverError error, bytes32 errorArg) private pure { + if (error == RecoverError.NoError) { + return; // no error: do nothing + } else if (error == RecoverError.InvalidSignature) { + revert ECDSAInvalidSignature(); + } else if (error == RecoverError.InvalidSignatureLength) { + revert ECDSAInvalidSignatureLength(uint256(errorArg)); + } else if (error == RecoverError.InvalidSignatureS) { + revert ECDSAInvalidSignatureS(errorArg); + } + } +} diff --git a/contracts/utils/cryptography/EIP712.sol b/contracts/utils/cryptography/EIP712.sol new file mode 100644 index 000000000..b29b08db6 --- /dev/null +++ b/contracts/utils/cryptography/EIP712.sol @@ -0,0 +1,160 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (utils/cryptography/EIP712.sol) + +pragma solidity ^0.8.20; + +import {MessageHashUtils} from "./MessageHashUtils.sol"; +import {ShortStrings, ShortString} from "../ShortStrings.sol"; +import {IERC5267} from "../../interfaces/IERC5267.sol"; + +/** + * @dev https://eips.ethereum.org/EIPS/eip-712[EIP 712] is a standard for hashing and signing of typed structured data. + * + * The encoding scheme specified in the EIP requires a domain separator and a hash of the typed structured data, whose + * encoding is very generic and therefore its implementation in Solidity is not feasible, thus this contract + * does not implement the encoding itself. Protocols need to implement the type-specific encoding they need in order to + * produce the hash of their typed data using a combination of `abi.encode` and `keccak256`. + * + * This contract implements the EIP 712 domain separator ({_domainSeparatorV4}) that is used as part of the encoding + * scheme, and the final step of the encoding to obtain the message digest that is then signed via ECDSA + * ({_hashTypedDataV4}). + * + * The implementation of the domain separator was designed to be as efficient as possible while still properly updating + * the chain id to protect against replay attacks on an eventual fork of the chain. + * + * NOTE: This contract implements the version of the encoding known as "v4", as implemented by the JSON RPC method + * https://docs.metamask.io/guide/signing-data.html[`eth_signTypedDataV4` in MetaMask]. + * + * NOTE: In the upgradeable version of this contract, the cached values will correspond to the address, and the domain + * separator of the implementation contract. This will cause the {_domainSeparatorV4} function to always rebuild the + * separator from the immutable values, which is cheaper than accessing a cached version in cold storage. + * + * @custom:oz-upgrades-unsafe-allow state-variable-immutable + */ +abstract contract EIP712 is IERC5267 { + using ShortStrings for *; + + bytes32 private constant TYPE_HASH = + keccak256("EIP712Domain(string name,string version,uint256 chainId,address verifyingContract)"); + + // Cache the domain separator as an immutable value, but also store the chain id that it corresponds to, in order to + // invalidate the cached domain separator if the chain id changes. + bytes32 private immutable _cachedDomainSeparator; + uint256 private immutable _cachedChainId; + address private immutable _cachedThis; + + bytes32 private immutable _hashedName; + bytes32 private immutable _hashedVersion; + + ShortString private immutable _name; + ShortString private immutable _version; + string private _nameFallback; + string private _versionFallback; + + /** + * @dev Initializes the domain separator and parameter caches. + * + * The meaning of `name` and `version` is specified in + * https://eips.ethereum.org/EIPS/eip-712#definition-of-domainseparator[EIP 712]: + * + * - `name`: the user readable name of the signing domain, i.e. the name of the DApp or the protocol. + * - `version`: the current major version of the signing domain. + * + * NOTE: These parameters cannot be changed except through a xref:learn::upgrading-smart-contracts.adoc[smart + * contract upgrade]. + */ + constructor(string memory name, string memory version) { + _name = name.toShortStringWithFallback(_nameFallback); + _version = version.toShortStringWithFallback(_versionFallback); + _hashedName = keccak256(bytes(name)); + _hashedVersion = keccak256(bytes(version)); + + _cachedChainId = block.chainid; + _cachedDomainSeparator = _buildDomainSeparator(); + _cachedThis = address(this); + } + + /** + * @dev Returns the domain separator for the current chain. + */ + function _domainSeparatorV4() internal view returns (bytes32) { + if (address(this) == _cachedThis && block.chainid == _cachedChainId) { + return _cachedDomainSeparator; + } else { + return _buildDomainSeparator(); + } + } + + function _buildDomainSeparator() private view returns (bytes32) { + return keccak256(abi.encode(TYPE_HASH, _hashedName, _hashedVersion, block.chainid, address(this))); + } + + /** + * @dev Given an already https://eips.ethereum.org/EIPS/eip-712#definition-of-hashstruct[hashed struct], this + * function returns the hash of the fully encoded EIP712 message for this domain. + * + * This hash can be used together with {ECDSA-recover} to obtain the signer of a message. For example: + * + * ```solidity + * bytes32 digest = _hashTypedDataV4(keccak256(abi.encode( + * keccak256("Mail(address to,string contents)"), + * mailTo, + * keccak256(bytes(mailContents)) + * ))); + * address signer = ECDSA.recover(digest, signature); + * ``` + */ + function _hashTypedDataV4(bytes32 structHash) internal view virtual returns (bytes32) { + return MessageHashUtils.toTypedDataHash(_domainSeparatorV4(), structHash); + } + + /** + * @dev See {IERC-5267}. + */ + function eip712Domain() + public + view + virtual + returns ( + bytes1 fields, + string memory name, + string memory version, + uint256 chainId, + address verifyingContract, + bytes32 salt, + uint256[] memory extensions + ) + { + return ( + hex"0f", // 01111 + _EIP712Name(), + _EIP712Version(), + block.chainid, + address(this), + bytes32(0), + new uint256[](0) + ); + } + + /** + * @dev The name parameter for the EIP712 domain. + * + * NOTE: By default this function reads _name which is an immutable value. + * It only reads from storage if necessary (in case the value is too large to fit in a ShortString). + */ + // solhint-disable-next-line func-name-mixedcase + function _EIP712Name() internal view returns (string memory) { + return _name.toStringWithFallback(_nameFallback); + } + + /** + * @dev The version parameter for the EIP712 domain. + * + * NOTE: By default this function reads _version which is an immutable value. + * It only reads from storage if necessary (in case the value is too large to fit in a ShortString). + */ + // solhint-disable-next-line func-name-mixedcase + function _EIP712Version() internal view returns (string memory) { + return _version.toStringWithFallback(_versionFallback); + } +} diff --git a/contracts/utils/cryptography/MerkleProof.sol b/contracts/utils/cryptography/MerkleProof.sol new file mode 100644 index 000000000..68293c4fe --- /dev/null +++ b/contracts/utils/cryptography/MerkleProof.sol @@ -0,0 +1,232 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (utils/cryptography/MerkleProof.sol) + +pragma solidity ^0.8.20; + +/** + * @dev These functions deal with verification of Merkle Tree proofs. + * + * The tree and the proofs can be generated using our + * https://github.com/OpenZeppelin/merkle-tree[JavaScript library]. + * You will find a quickstart guide in the readme. + * + * WARNING: You should avoid using leaf values that are 64 bytes long prior to + * hashing, or use a hash function other than keccak256 for hashing leaves. + * This is because the concatenation of a sorted pair of internal nodes in + * the Merkle tree could be reinterpreted as a leaf value. + * OpenZeppelin's JavaScript library generates Merkle trees that are safe + * against this attack out of the box. + */ +library MerkleProof { + /** + *@dev The multiproof provided is not valid. + */ + error MerkleProofInvalidMultiproof(); + + /** + * @dev Returns true if a `leaf` can be proved to be a part of a Merkle tree + * defined by `root`. For this, a `proof` must be provided, containing + * sibling hashes on the branch from the leaf to the root of the tree. Each + * pair of leaves and each pair of pre-images are assumed to be sorted. + */ + function verify(bytes32[] memory proof, bytes32 root, bytes32 leaf) internal pure returns (bool) { + return processProof(proof, leaf) == root; + } + + /** + * @dev Calldata version of {verify} + */ + function verifyCalldata(bytes32[] calldata proof, bytes32 root, bytes32 leaf) internal pure returns (bool) { + return processProofCalldata(proof, leaf) == root; + } + + /** + * @dev Returns the rebuilt hash obtained by traversing a Merkle tree up + * from `leaf` using `proof`. A `proof` is valid if and only if the rebuilt + * hash matches the root of the tree. When processing the proof, the pairs + * of leafs & pre-images are assumed to be sorted. + */ + function processProof(bytes32[] memory proof, bytes32 leaf) internal pure returns (bytes32) { + bytes32 computedHash = leaf; + for (uint256 i = 0; i < proof.length; i++) { + computedHash = _hashPair(computedHash, proof[i]); + } + return computedHash; + } + + /** + * @dev Calldata version of {processProof} + */ + function processProofCalldata(bytes32[] calldata proof, bytes32 leaf) internal pure returns (bytes32) { + bytes32 computedHash = leaf; + for (uint256 i = 0; i < proof.length; i++) { + computedHash = _hashPair(computedHash, proof[i]); + } + return computedHash; + } + + /** + * @dev Returns true if the `leaves` can be simultaneously proven to be a part of a Merkle tree defined by + * `root`, according to `proof` and `proofFlags` as described in {processMultiProof}. + * + * CAUTION: Not all Merkle trees admit multiproofs. See {processMultiProof} for details. + */ + function multiProofVerify( + bytes32[] memory proof, + bool[] memory proofFlags, + bytes32 root, + bytes32[] memory leaves + ) internal pure returns (bool) { + return processMultiProof(proof, proofFlags, leaves) == root; + } + + /** + * @dev Calldata version of {multiProofVerify} + * + * CAUTION: Not all Merkle trees admit multiproofs. See {processMultiProof} for details. + */ + function multiProofVerifyCalldata( + bytes32[] calldata proof, + bool[] calldata proofFlags, + bytes32 root, + bytes32[] memory leaves + ) internal pure returns (bool) { + return processMultiProofCalldata(proof, proofFlags, leaves) == root; + } + + /** + * @dev Returns the root of a tree reconstructed from `leaves` and sibling nodes in `proof`. The reconstruction + * proceeds by incrementally reconstructing all inner nodes by combining a leaf/inner node with either another + * leaf/inner node or a proof sibling node, depending on whether each `proofFlags` item is true or false + * respectively. + * + * CAUTION: Not all Merkle trees admit multiproofs. To use multiproofs, it is sufficient to ensure that: 1) the tree + * is complete (but not necessarily perfect), 2) the leaves to be proven are in the opposite order they are in the + * tree (i.e., as seen from right to left starting at the deepest layer and continuing at the next layer). + */ + function processMultiProof( + bytes32[] memory proof, + bool[] memory proofFlags, + bytes32[] memory leaves + ) internal pure returns (bytes32 merkleRoot) { + // This function rebuilds the root hash by traversing the tree up from the leaves. The root is rebuilt by + // consuming and producing values on a queue. The queue starts with the `leaves` array, then goes onto the + // `hashes` array. At the end of the process, the last hash in the `hashes` array should contain the root of + // the Merkle tree. + uint256 leavesLen = leaves.length; + uint256 proofLen = proof.length; + uint256 totalHashes = proofFlags.length; + + // Check proof validity. + if (leavesLen + proofLen != totalHashes + 1) { + revert MerkleProofInvalidMultiproof(); + } + + // The xxxPos values are "pointers" to the next value to consume in each array. All accesses are done using + // `xxx[xxxPos++]`, which return the current value and increment the pointer, thus mimicking a queue's "pop". + bytes32[] memory hashes = new bytes32[](totalHashes); + uint256 leafPos = 0; + uint256 hashPos = 0; + uint256 proofPos = 0; + // At each step, we compute the next hash using two values: + // - a value from the "main queue". If not all leaves have been consumed, we get the next leaf, otherwise we + // get the next hash. + // - depending on the flag, either another value from the "main queue" (merging branches) or an element from the + // `proof` array. + for (uint256 i = 0; i < totalHashes; i++) { + bytes32 a = leafPos < leavesLen ? leaves[leafPos++] : hashes[hashPos++]; + bytes32 b = proofFlags[i] + ? (leafPos < leavesLen ? leaves[leafPos++] : hashes[hashPos++]) + : proof[proofPos++]; + hashes[i] = _hashPair(a, b); + } + + if (totalHashes > 0) { + if (proofPos != proofLen) { + revert MerkleProofInvalidMultiproof(); + } + unchecked { + return hashes[totalHashes - 1]; + } + } else if (leavesLen > 0) { + return leaves[0]; + } else { + return proof[0]; + } + } + + /** + * @dev Calldata version of {processMultiProof}. + * + * CAUTION: Not all Merkle trees admit multiproofs. See {processMultiProof} for details. + */ + function processMultiProofCalldata( + bytes32[] calldata proof, + bool[] calldata proofFlags, + bytes32[] memory leaves + ) internal pure returns (bytes32 merkleRoot) { + // This function rebuilds the root hash by traversing the tree up from the leaves. The root is rebuilt by + // consuming and producing values on a queue. The queue starts with the `leaves` array, then goes onto the + // `hashes` array. At the end of the process, the last hash in the `hashes` array should contain the root of + // the Merkle tree. + uint256 leavesLen = leaves.length; + uint256 proofLen = proof.length; + uint256 totalHashes = proofFlags.length; + + // Check proof validity. + if (leavesLen + proofLen != totalHashes + 1) { + revert MerkleProofInvalidMultiproof(); + } + + // The xxxPos values are "pointers" to the next value to consume in each array. All accesses are done using + // `xxx[xxxPos++]`, which return the current value and increment the pointer, thus mimicking a queue's "pop". + bytes32[] memory hashes = new bytes32[](totalHashes); + uint256 leafPos = 0; + uint256 hashPos = 0; + uint256 proofPos = 0; + // At each step, we compute the next hash using two values: + // - a value from the "main queue". If not all leaves have been consumed, we get the next leaf, otherwise we + // get the next hash. + // - depending on the flag, either another value from the "main queue" (merging branches) or an element from the + // `proof` array. + for (uint256 i = 0; i < totalHashes; i++) { + bytes32 a = leafPos < leavesLen ? leaves[leafPos++] : hashes[hashPos++]; + bytes32 b = proofFlags[i] + ? (leafPos < leavesLen ? leaves[leafPos++] : hashes[hashPos++]) + : proof[proofPos++]; + hashes[i] = _hashPair(a, b); + } + + if (totalHashes > 0) { + if (proofPos != proofLen) { + revert MerkleProofInvalidMultiproof(); + } + unchecked { + return hashes[totalHashes - 1]; + } + } else if (leavesLen > 0) { + return leaves[0]; + } else { + return proof[0]; + } + } + + /** + * @dev Sorts the pair (a, b) and hashes the result. + */ + function _hashPair(bytes32 a, bytes32 b) private pure returns (bytes32) { + return a < b ? _efficientHash(a, b) : _efficientHash(b, a); + } + + /** + * @dev Implementation of keccak256(abi.encode(a, b)) that doesn't allocate or expand memory. + */ + function _efficientHash(bytes32 a, bytes32 b) private pure returns (bytes32 value) { + /// @solidity memory-safe-assembly + assembly { + mstore(0x00, a) + mstore(0x20, b) + value := keccak256(0x00, 0x40) + } + } +} diff --git a/contracts/utils/cryptography/MessageHashUtils.sol b/contracts/utils/cryptography/MessageHashUtils.sol new file mode 100644 index 000000000..ef2397749 --- /dev/null +++ b/contracts/utils/cryptography/MessageHashUtils.sol @@ -0,0 +1,86 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (utils/cryptography/MessageHashUtils.sol) + +pragma solidity ^0.8.20; + +import {Strings} from "../Strings.sol"; + +/** + * @dev Signature message hash utilities for producing digests to be consumed by {ECDSA} recovery or signing. + * + * The library provides methods for generating a hash of a message that conforms to the + * https://eips.ethereum.org/EIPS/eip-191[EIP 191] and https://eips.ethereum.org/EIPS/eip-712[EIP 712] + * specifications. + */ +library MessageHashUtils { + /** + * @dev Returns the keccak256 digest of an EIP-191 signed data with version + * `0x45` (`personal_sign` messages). + * + * The digest is calculated by prefixing a bytes32 `messageHash` with + * `"\x19Ethereum Signed Message:\n32"` and hashing the result. It corresponds with the + * hash signed when using the https://eth.wiki/json-rpc/API#eth_sign[`eth_sign`] JSON-RPC method. + * + * NOTE: The `messageHash` parameter is intended to be the result of hashing a raw message with + * keccak256, although any bytes32 value can be safely used because the final digest will + * be re-hashed. + * + * See {ECDSA-recover}. + */ + function toEthSignedMessageHash(bytes32 messageHash) internal pure returns (bytes32 digest) { + /// @solidity memory-safe-assembly + assembly { + mstore(0x00, "\x19Ethereum Signed Message:\n32") // 32 is the bytes-length of messageHash + mstore(0x1c, messageHash) // 0x1c (28) is the length of the prefix + digest := keccak256(0x00, 0x3c) // 0x3c is the length of the prefix (0x1c) + messageHash (0x20) + } + } + + /** + * @dev Returns the keccak256 digest of an EIP-191 signed data with version + * `0x45` (`personal_sign` messages). + * + * The digest is calculated by prefixing an arbitrary `message` with + * `"\x19Ethereum Signed Message:\n" + len(message)` and hashing the result. It corresponds with the + * hash signed when using the https://eth.wiki/json-rpc/API#eth_sign[`eth_sign`] JSON-RPC method. + * + * See {ECDSA-recover}. + */ + function toEthSignedMessageHash(bytes memory message) internal pure returns (bytes32) { + return + keccak256(bytes.concat("\x19Ethereum Signed Message:\n", bytes(Strings.toString(message.length)), message)); + } + + /** + * @dev Returns the keccak256 digest of an EIP-191 signed data with version + * `0x00` (data with intended validator). + * + * The digest is calculated by prefixing an arbitrary `data` with `"\x19\x00"` and the intended + * `validator` address. Then hashing the result. + * + * See {ECDSA-recover}. + */ + function toDataWithIntendedValidatorHash(address validator, bytes memory data) internal pure returns (bytes32) { + return keccak256(abi.encodePacked(hex"19_00", validator, data)); + } + + /** + * @dev Returns the keccak256 digest of an EIP-712 typed data (EIP-191 version `0x01`). + * + * The digest is calculated from a `domainSeparator` and a `structHash`, by prefixing them with + * `\x19\x01` and hashing the result. It corresponds to the hash signed by the + * https://eips.ethereum.org/EIPS/eip-712[`eth_signTypedData`] JSON-RPC method as part of EIP-712. + * + * See {ECDSA-recover}. + */ + function toTypedDataHash(bytes32 domainSeparator, bytes32 structHash) internal pure returns (bytes32 digest) { + /// @solidity memory-safe-assembly + assembly { + let ptr := mload(0x40) + mstore(ptr, hex"19_01") + mstore(add(ptr, 0x02), domainSeparator) + mstore(add(ptr, 0x22), structHash) + digest := keccak256(ptr, 0x42) + } + } +} diff --git a/contracts/utils/cryptography/SignatureChecker.sol b/contracts/utils/cryptography/SignatureChecker.sol new file mode 100644 index 000000000..584e33dc9 --- /dev/null +++ b/contracts/utils/cryptography/SignatureChecker.sol @@ -0,0 +1,48 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (utils/cryptography/SignatureChecker.sol) + +pragma solidity ^0.8.20; + +import {ECDSA} from "./ECDSA.sol"; +import {IERC1271} from "../../interfaces/IERC1271.sol"; + +/** + * @dev Signature verification helper that can be used instead of `ECDSA.recover` to seamlessly support both ECDSA + * signatures from externally owned accounts (EOAs) as well as ERC1271 signatures from smart contract wallets like + * Argent and Safe Wallet (previously Gnosis Safe). + */ +library SignatureChecker { + /** + * @dev Checks if a signature is valid for a given signer and data hash. If the signer is a smart contract, the + * signature is validated against that smart contract using ERC1271, otherwise it's validated using `ECDSA.recover`. + * + * NOTE: Unlike ECDSA signatures, contract signatures are revocable, and the outcome of this function can thus + * change through time. It could return true at block N and false at block N+1 (or the opposite). + */ + function isValidSignatureNow(address signer, bytes32 hash, bytes memory signature) internal view returns (bool) { + (address recovered, ECDSA.RecoverError error, ) = ECDSA.tryRecover(hash, signature); + return + (error == ECDSA.RecoverError.NoError && recovered == signer) || + isValidERC1271SignatureNow(signer, hash, signature); + } + + /** + * @dev Checks if a signature is valid for a given signer and data hash. The signature is validated + * against the signer smart contract using ERC1271. + * + * NOTE: Unlike ECDSA signatures, contract signatures are revocable, and the outcome of this function can thus + * change through time. It could return true at block N and false at block N+1 (or the opposite). + */ + function isValidERC1271SignatureNow( + address signer, + bytes32 hash, + bytes memory signature + ) internal view returns (bool) { + (bool success, bytes memory result) = signer.staticcall( + abi.encodeCall(IERC1271.isValidSignature, (hash, signature)) + ); + return (success && + result.length >= 32 && + abi.decode(result, (bytes32)) == bytes32(IERC1271.isValidSignature.selector)); + } +} diff --git a/contracts/utils/introspection/ERC165.sol b/contracts/utils/introspection/ERC165.sol new file mode 100644 index 000000000..8ce112f6f --- /dev/null +++ b/contracts/utils/introspection/ERC165.sol @@ -0,0 +1,27 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (utils/introspection/ERC165.sol) + +pragma solidity ^0.8.20; + +import {IERC165} from "./IERC165.sol"; + +/** + * @dev Implementation of the {IERC165} interface. + * + * Contracts that want to implement ERC165 should inherit from this contract and override {supportsInterface} to check + * for the additional interface id that will be supported. For example: + * + * ```solidity + * function supportsInterface(bytes4 interfaceId) public view virtual override returns (bool) { + * return interfaceId == type(MyInterface).interfaceId || super.supportsInterface(interfaceId); + * } + * ``` + */ +abstract contract ERC165 is IERC165 { + /** + * @dev See {IERC165-supportsInterface}. + */ + function supportsInterface(bytes4 interfaceId) public view virtual returns (bool) { + return interfaceId == type(IERC165).interfaceId; + } +} diff --git a/contracts/utils/introspection/ERC165Checker.sol b/contracts/utils/introspection/ERC165Checker.sol new file mode 100644 index 000000000..a04f9c012 --- /dev/null +++ b/contracts/utils/introspection/ERC165Checker.sol @@ -0,0 +1,124 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (utils/introspection/ERC165Checker.sol) + +pragma solidity ^0.8.20; + +import {IERC165} from "./IERC165.sol"; + +/** + * @dev Library used to query support of an interface declared via {IERC165}. + * + * Note that these functions return the actual result of the query: they do not + * `revert` if an interface is not supported. It is up to the caller to decide + * what to do in these cases. + */ +library ERC165Checker { + // As per the EIP-165 spec, no interface should ever match 0xffffffff + bytes4 private constant INTERFACE_ID_INVALID = 0xffffffff; + + /** + * @dev Returns true if `account` supports the {IERC165} interface. + */ + function supportsERC165(address account) internal view returns (bool) { + // Any contract that implements ERC165 must explicitly indicate support of + // InterfaceId_ERC165 and explicitly indicate non-support of InterfaceId_Invalid + return + supportsERC165InterfaceUnchecked(account, type(IERC165).interfaceId) && + !supportsERC165InterfaceUnchecked(account, INTERFACE_ID_INVALID); + } + + /** + * @dev Returns true if `account` supports the interface defined by + * `interfaceId`. Support for {IERC165} itself is queried automatically. + * + * See {IERC165-supportsInterface}. + */ + function supportsInterface(address account, bytes4 interfaceId) internal view returns (bool) { + // query support of both ERC165 as per the spec and support of _interfaceId + return supportsERC165(account) && supportsERC165InterfaceUnchecked(account, interfaceId); + } + + /** + * @dev Returns a boolean array where each value corresponds to the + * interfaces passed in and whether they're supported or not. This allows + * you to batch check interfaces for a contract where your expectation + * is that some interfaces may not be supported. + * + * See {IERC165-supportsInterface}. + */ + function getSupportedInterfaces( + address account, + bytes4[] memory interfaceIds + ) internal view returns (bool[] memory) { + // an array of booleans corresponding to interfaceIds and whether they're supported or not + bool[] memory interfaceIdsSupported = new bool[](interfaceIds.length); + + // query support of ERC165 itself + if (supportsERC165(account)) { + // query support of each interface in interfaceIds + for (uint256 i = 0; i < interfaceIds.length; i++) { + interfaceIdsSupported[i] = supportsERC165InterfaceUnchecked(account, interfaceIds[i]); + } + } + + return interfaceIdsSupported; + } + + /** + * @dev Returns true if `account` supports all the interfaces defined in + * `interfaceIds`. Support for {IERC165} itself is queried automatically. + * + * Batch-querying can lead to gas savings by skipping repeated checks for + * {IERC165} support. + * + * See {IERC165-supportsInterface}. + */ + function supportsAllInterfaces(address account, bytes4[] memory interfaceIds) internal view returns (bool) { + // query support of ERC165 itself + if (!supportsERC165(account)) { + return false; + } + + // query support of each interface in interfaceIds + for (uint256 i = 0; i < interfaceIds.length; i++) { + if (!supportsERC165InterfaceUnchecked(account, interfaceIds[i])) { + return false; + } + } + + // all interfaces supported + return true; + } + + /** + * @notice Query if a contract implements an interface, does not check ERC165 support + * @param account The address of the contract to query for support of an interface + * @param interfaceId The interface identifier, as specified in ERC-165 + * @return true if the contract at account indicates support of the interface with + * identifier interfaceId, false otherwise + * @dev Assumes that account contains a contract that supports ERC165, otherwise + * the behavior of this method is undefined. This precondition can be checked + * with {supportsERC165}. + * + * Some precompiled contracts will falsely indicate support for a given interface, so caution + * should be exercised when using this function. + * + * Interface identification is specified in ERC-165. + */ + function supportsERC165InterfaceUnchecked(address account, bytes4 interfaceId) internal view returns (bool) { + // prepare call + bytes memory encodedParams = abi.encodeCall(IERC165.supportsInterface, (interfaceId)); + + // perform static call + bool success; + uint256 returnSize; + uint256 returnValue; + assembly { + success := staticcall(30000, account, add(encodedParams, 0x20), mload(encodedParams), 0x00, 0x20) + returnSize := returndatasize() + returnValue := mload(0x00) + } + + return success && returnSize >= 0x20 && returnValue > 0; + } +} diff --git a/contracts/utils/introspection/IERC165.sol b/contracts/utils/introspection/IERC165.sol new file mode 100644 index 000000000..cfc9a1991 --- /dev/null +++ b/contracts/utils/introspection/IERC165.sol @@ -0,0 +1,25 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (utils/introspection/IERC165.sol) + +pragma solidity ^0.8.20; + +/** + * @dev Interface of the ERC165 standard, as defined in the + * https://eips.ethereum.org/EIPS/eip-165[EIP]. + * + * Implementers can declare support of contract interfaces, which can then be + * queried by others ({ERC165Checker}). + * + * For an implementation, see {ERC165}. + */ +interface IERC165 { + /** + * @dev Returns true if this contract implements the interface defined by + * `interfaceId`. See the corresponding + * https://eips.ethereum.org/EIPS/eip-165#how-interfaces-are-identified[EIP section] + * to learn more about how these ids are created. + * + * This function call must use less than 30 000 gas. + */ + function supportsInterface(bytes4 interfaceId) external view returns (bool); +} diff --git a/contracts/utils/math/Math.sol b/contracts/utils/math/Math.sol new file mode 100644 index 000000000..184dbd70d --- /dev/null +++ b/contracts/utils/math/Math.sol @@ -0,0 +1,415 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (utils/math/Math.sol) + +pragma solidity ^0.8.20; + +/** + * @dev Standard math utilities missing in the Solidity language. + */ +library Math { + /** + * @dev Muldiv operation overflow. + */ + error MathOverflowedMulDiv(); + + enum Rounding { + Floor, // Toward negative infinity + Ceil, // Toward positive infinity + Trunc, // Toward zero + Expand // Away from zero + } + + /** + * @dev Returns the addition of two unsigned integers, with an overflow flag. + */ + function tryAdd(uint256 a, uint256 b) internal pure returns (bool, uint256) { + unchecked { + uint256 c = a + b; + if (c < a) return (false, 0); + return (true, c); + } + } + + /** + * @dev Returns the subtraction of two unsigned integers, with an overflow flag. + */ + function trySub(uint256 a, uint256 b) internal pure returns (bool, uint256) { + unchecked { + if (b > a) return (false, 0); + return (true, a - b); + } + } + + /** + * @dev Returns the multiplication of two unsigned integers, with an overflow flag. + */ + function tryMul(uint256 a, uint256 b) internal pure returns (bool, uint256) { + unchecked { + // Gas optimization: this is cheaper than requiring 'a' not being zero, but the + // benefit is lost if 'b' is also tested. + // See: https://github.com/OpenZeppelin/openzeppelin-contracts/pull/522 + if (a == 0) return (true, 0); + uint256 c = a * b; + if (c / a != b) return (false, 0); + return (true, c); + } + } + + /** + * @dev Returns the division of two unsigned integers, with a division by zero flag. + */ + function tryDiv(uint256 a, uint256 b) internal pure returns (bool, uint256) { + unchecked { + if (b == 0) return (false, 0); + return (true, a / b); + } + } + + /** + * @dev Returns the remainder of dividing two unsigned integers, with a division by zero flag. + */ + function tryMod(uint256 a, uint256 b) internal pure returns (bool, uint256) { + unchecked { + if (b == 0) return (false, 0); + return (true, a % b); + } + } + + /** + * @dev Returns the largest of two numbers. + */ + function max(uint256 a, uint256 b) internal pure returns (uint256) { + return a > b ? a : b; + } + + /** + * @dev Returns the smallest of two numbers. + */ + function min(uint256 a, uint256 b) internal pure returns (uint256) { + return a < b ? a : b; + } + + /** + * @dev Returns the average of two numbers. The result is rounded towards + * zero. + */ + function average(uint256 a, uint256 b) internal pure returns (uint256) { + // (a + b) / 2 can overflow. + return (a & b) + (a ^ b) / 2; + } + + /** + * @dev Returns the ceiling of the division of two numbers. + * + * This differs from standard division with `/` in that it rounds towards infinity instead + * of rounding towards zero. + */ + function ceilDiv(uint256 a, uint256 b) internal pure returns (uint256) { + if (b == 0) { + // Guarantee the same behavior as in a regular Solidity division. + return a / b; + } + + // (a + b - 1) / b can overflow on addition, so we distribute. + return a == 0 ? 0 : (a - 1) / b + 1; + } + + /** + * @notice Calculates floor(x * y / denominator) with full precision. Throws if result overflows a uint256 or + * denominator == 0. + * @dev Original credit to Remco Bloemen under MIT license (https://xn--2-umb.com/21/muldiv) with further edits by + * Uniswap Labs also under MIT license. + */ + function mulDiv(uint256 x, uint256 y, uint256 denominator) internal pure returns (uint256 result) { + unchecked { + // 512-bit multiply [prod1 prod0] = x * y. Compute the product mod 2^256 and mod 2^256 - 1, then use + // use the Chinese Remainder Theorem to reconstruct the 512 bit result. The result is stored in two 256 + // variables such that product = prod1 * 2^256 + prod0. + uint256 prod0 = x * y; // Least significant 256 bits of the product + uint256 prod1; // Most significant 256 bits of the product + assembly { + let mm := mulmod(x, y, not(0)) + prod1 := sub(sub(mm, prod0), lt(mm, prod0)) + } + + // Handle non-overflow cases, 256 by 256 division. + if (prod1 == 0) { + // Solidity will revert if denominator == 0, unlike the div opcode on its own. + // The surrounding unchecked block does not change this fact. + // See https://docs.soliditylang.org/en/latest/control-structures.html#checked-or-unchecked-arithmetic. + return prod0 / denominator; + } + + // Make sure the result is less than 2^256. Also prevents denominator == 0. + if (denominator <= prod1) { + revert MathOverflowedMulDiv(); + } + + /////////////////////////////////////////////// + // 512 by 256 division. + /////////////////////////////////////////////// + + // Make division exact by subtracting the remainder from [prod1 prod0]. + uint256 remainder; + assembly { + // Compute remainder using mulmod. + remainder := mulmod(x, y, denominator) + + // Subtract 256 bit number from 512 bit number. + prod1 := sub(prod1, gt(remainder, prod0)) + prod0 := sub(prod0, remainder) + } + + // Factor powers of two out of denominator and compute largest power of two divisor of denominator. + // Always >= 1. See https://cs.stackexchange.com/q/138556/92363. + + uint256 twos = denominator & (0 - denominator); + assembly { + // Divide denominator by twos. + denominator := div(denominator, twos) + + // Divide [prod1 prod0] by twos. + prod0 := div(prod0, twos) + + // Flip twos such that it is 2^256 / twos. If twos is zero, then it becomes one. + twos := add(div(sub(0, twos), twos), 1) + } + + // Shift in bits from prod1 into prod0. + prod0 |= prod1 * twos; + + // Invert denominator mod 2^256. Now that denominator is an odd number, it has an inverse modulo 2^256 such + // that denominator * inv = 1 mod 2^256. Compute the inverse by starting with a seed that is correct for + // four bits. That is, denominator * inv = 1 mod 2^4. + uint256 inverse = (3 * denominator) ^ 2; + + // Use the Newton-Raphson iteration to improve the precision. Thanks to Hensel's lifting lemma, this also + // works in modular arithmetic, doubling the correct bits in each step. + inverse *= 2 - denominator * inverse; // inverse mod 2^8 + inverse *= 2 - denominator * inverse; // inverse mod 2^16 + inverse *= 2 - denominator * inverse; // inverse mod 2^32 + inverse *= 2 - denominator * inverse; // inverse mod 2^64 + inverse *= 2 - denominator * inverse; // inverse mod 2^128 + inverse *= 2 - denominator * inverse; // inverse mod 2^256 + + // Because the division is now exact we can divide by multiplying with the modular inverse of denominator. + // This will give us the correct result modulo 2^256. Since the preconditions guarantee that the outcome is + // less than 2^256, this is the final result. We don't need to compute the high bits of the result and prod1 + // is no longer required. + result = prod0 * inverse; + return result; + } + } + + /** + * @notice Calculates x * y / denominator with full precision, following the selected rounding direction. + */ + function mulDiv(uint256 x, uint256 y, uint256 denominator, Rounding rounding) internal pure returns (uint256) { + uint256 result = mulDiv(x, y, denominator); + if (unsignedRoundsUp(rounding) && mulmod(x, y, denominator) > 0) { + result += 1; + } + return result; + } + + /** + * @dev Returns the square root of a number. If the number is not a perfect square, the value is rounded + * towards zero. + * + * Inspired by Henry S. Warren, Jr.'s "Hacker's Delight" (Chapter 11). + */ + function sqrt(uint256 a) internal pure returns (uint256) { + if (a == 0) { + return 0; + } + + // For our first guess, we get the biggest power of 2 which is smaller than the square root of the target. + // + // We know that the "msb" (most significant bit) of our target number `a` is a power of 2 such that we have + // `msb(a) <= a < 2*msb(a)`. This value can be written `msb(a)=2**k` with `k=log2(a)`. + // + // This can be rewritten `2**log2(a) <= a < 2**(log2(a) + 1)` + // → `sqrt(2**k) <= sqrt(a) < sqrt(2**(k+1))` + // → `2**(k/2) <= sqrt(a) < 2**((k+1)/2) <= 2**(k/2 + 1)` + // + // Consequently, `2**(log2(a) / 2)` is a good first approximation of `sqrt(a)` with at least 1 correct bit. + uint256 result = 1 << (log2(a) >> 1); + + // At this point `result` is an estimation with one bit of precision. We know the true value is a uint128, + // since it is the square root of a uint256. Newton's method converges quadratically (precision doubles at + // every iteration). We thus need at most 7 iteration to turn our partial result with one bit of precision + // into the expected uint128 result. + unchecked { + result = (result + a / result) >> 1; + result = (result + a / result) >> 1; + result = (result + a / result) >> 1; + result = (result + a / result) >> 1; + result = (result + a / result) >> 1; + result = (result + a / result) >> 1; + result = (result + a / result) >> 1; + return min(result, a / result); + } + } + + /** + * @notice Calculates sqrt(a), following the selected rounding direction. + */ + function sqrt(uint256 a, Rounding rounding) internal pure returns (uint256) { + unchecked { + uint256 result = sqrt(a); + return result + (unsignedRoundsUp(rounding) && result * result < a ? 1 : 0); + } + } + + /** + * @dev Return the log in base 2 of a positive value rounded towards zero. + * Returns 0 if given 0. + */ + function log2(uint256 value) internal pure returns (uint256) { + uint256 result = 0; + unchecked { + if (value >> 128 > 0) { + value >>= 128; + result += 128; + } + if (value >> 64 > 0) { + value >>= 64; + result += 64; + } + if (value >> 32 > 0) { + value >>= 32; + result += 32; + } + if (value >> 16 > 0) { + value >>= 16; + result += 16; + } + if (value >> 8 > 0) { + value >>= 8; + result += 8; + } + if (value >> 4 > 0) { + value >>= 4; + result += 4; + } + if (value >> 2 > 0) { + value >>= 2; + result += 2; + } + if (value >> 1 > 0) { + result += 1; + } + } + return result; + } + + /** + * @dev Return the log in base 2, following the selected rounding direction, of a positive value. + * Returns 0 if given 0. + */ + function log2(uint256 value, Rounding rounding) internal pure returns (uint256) { + unchecked { + uint256 result = log2(value); + return result + (unsignedRoundsUp(rounding) && 1 << result < value ? 1 : 0); + } + } + + /** + * @dev Return the log in base 10 of a positive value rounded towards zero. + * Returns 0 if given 0. + */ + function log10(uint256 value) internal pure returns (uint256) { + uint256 result = 0; + unchecked { + if (value >= 10 ** 64) { + value /= 10 ** 64; + result += 64; + } + if (value >= 10 ** 32) { + value /= 10 ** 32; + result += 32; + } + if (value >= 10 ** 16) { + value /= 10 ** 16; + result += 16; + } + if (value >= 10 ** 8) { + value /= 10 ** 8; + result += 8; + } + if (value >= 10 ** 4) { + value /= 10 ** 4; + result += 4; + } + if (value >= 10 ** 2) { + value /= 10 ** 2; + result += 2; + } + if (value >= 10 ** 1) { + result += 1; + } + } + return result; + } + + /** + * @dev Return the log in base 10, following the selected rounding direction, of a positive value. + * Returns 0 if given 0. + */ + function log10(uint256 value, Rounding rounding) internal pure returns (uint256) { + unchecked { + uint256 result = log10(value); + return result + (unsignedRoundsUp(rounding) && 10 ** result < value ? 1 : 0); + } + } + + /** + * @dev Return the log in base 256 of a positive value rounded towards zero. + * Returns 0 if given 0. + * + * Adding one to the result gives the number of pairs of hex symbols needed to represent `value` as a hex string. + */ + function log256(uint256 value) internal pure returns (uint256) { + uint256 result = 0; + unchecked { + if (value >> 128 > 0) { + value >>= 128; + result += 16; + } + if (value >> 64 > 0) { + value >>= 64; + result += 8; + } + if (value >> 32 > 0) { + value >>= 32; + result += 4; + } + if (value >> 16 > 0) { + value >>= 16; + result += 2; + } + if (value >> 8 > 0) { + result += 1; + } + } + return result; + } + + /** + * @dev Return the log in base 256, following the selected rounding direction, of a positive value. + * Returns 0 if given 0. + */ + function log256(uint256 value, Rounding rounding) internal pure returns (uint256) { + unchecked { + uint256 result = log256(value); + return result + (unsignedRoundsUp(rounding) && 1 << (result << 3) < value ? 1 : 0); + } + } + + /** + * @dev Returns whether a provided rounding mode is considered rounding up for unsigned integers. + */ + function unsignedRoundsUp(Rounding rounding) internal pure returns (bool) { + return uint8(rounding) % 2 == 1; + } +} diff --git a/contracts/utils/math/SafeCast.sol b/contracts/utils/math/SafeCast.sol new file mode 100644 index 000000000..117dfa386 --- /dev/null +++ b/contracts/utils/math/SafeCast.sol @@ -0,0 +1,1153 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (utils/math/SafeCast.sol) +// This file was procedurally generated from scripts/generate/templates/SafeCast.js. + +pragma solidity ^0.8.20; + +/** + * @dev Wrappers over Solidity's uintXX/intXX casting operators with added overflow + * checks. + * + * Downcasting from uint256/int256 in Solidity does not revert on overflow. This can + * easily result in undesired exploitation or bugs, since developers usually + * assume that overflows raise errors. `SafeCast` restores this intuition by + * reverting the transaction when such an operation overflows. + * + * Using this library instead of the unchecked operations eliminates an entire + * class of bugs, so it's recommended to use it always. + */ +library SafeCast { + /** + * @dev Value doesn't fit in an uint of `bits` size. + */ + error SafeCastOverflowedUintDowncast(uint8 bits, uint256 value); + + /** + * @dev An int value doesn't fit in an uint of `bits` size. + */ + error SafeCastOverflowedIntToUint(int256 value); + + /** + * @dev Value doesn't fit in an int of `bits` size. + */ + error SafeCastOverflowedIntDowncast(uint8 bits, int256 value); + + /** + * @dev An uint value doesn't fit in an int of `bits` size. + */ + error SafeCastOverflowedUintToInt(uint256 value); + + /** + * @dev Returns the downcasted uint248 from uint256, reverting on + * overflow (when the input is greater than largest uint248). + * + * Counterpart to Solidity's `uint248` operator. + * + * Requirements: + * + * - input must fit into 248 bits + */ + function toUint248(uint256 value) internal pure returns (uint248) { + if (value > type(uint248).max) { + revert SafeCastOverflowedUintDowncast(248, value); + } + return uint248(value); + } + + /** + * @dev Returns the downcasted uint240 from uint256, reverting on + * overflow (when the input is greater than largest uint240). + * + * Counterpart to Solidity's `uint240` operator. + * + * Requirements: + * + * - input must fit into 240 bits + */ + function toUint240(uint256 value) internal pure returns (uint240) { + if (value > type(uint240).max) { + revert SafeCastOverflowedUintDowncast(240, value); + } + return uint240(value); + } + + /** + * @dev Returns the downcasted uint232 from uint256, reverting on + * overflow (when the input is greater than largest uint232). + * + * Counterpart to Solidity's `uint232` operator. + * + * Requirements: + * + * - input must fit into 232 bits + */ + function toUint232(uint256 value) internal pure returns (uint232) { + if (value > type(uint232).max) { + revert SafeCastOverflowedUintDowncast(232, value); + } + return uint232(value); + } + + /** + * @dev Returns the downcasted uint224 from uint256, reverting on + * overflow (when the input is greater than largest uint224). + * + * Counterpart to Solidity's `uint224` operator. + * + * Requirements: + * + * - input must fit into 224 bits + */ + function toUint224(uint256 value) internal pure returns (uint224) { + if (value > type(uint224).max) { + revert SafeCastOverflowedUintDowncast(224, value); + } + return uint224(value); + } + + /** + * @dev Returns the downcasted uint216 from uint256, reverting on + * overflow (when the input is greater than largest uint216). + * + * Counterpart to Solidity's `uint216` operator. + * + * Requirements: + * + * - input must fit into 216 bits + */ + function toUint216(uint256 value) internal pure returns (uint216) { + if (value > type(uint216).max) { + revert SafeCastOverflowedUintDowncast(216, value); + } + return uint216(value); + } + + /** + * @dev Returns the downcasted uint208 from uint256, reverting on + * overflow (when the input is greater than largest uint208). + * + * Counterpart to Solidity's `uint208` operator. + * + * Requirements: + * + * - input must fit into 208 bits + */ + function toUint208(uint256 value) internal pure returns (uint208) { + if (value > type(uint208).max) { + revert SafeCastOverflowedUintDowncast(208, value); + } + return uint208(value); + } + + /** + * @dev Returns the downcasted uint200 from uint256, reverting on + * overflow (when the input is greater than largest uint200). + * + * Counterpart to Solidity's `uint200` operator. + * + * Requirements: + * + * - input must fit into 200 bits + */ + function toUint200(uint256 value) internal pure returns (uint200) { + if (value > type(uint200).max) { + revert SafeCastOverflowedUintDowncast(200, value); + } + return uint200(value); + } + + /** + * @dev Returns the downcasted uint192 from uint256, reverting on + * overflow (when the input is greater than largest uint192). + * + * Counterpart to Solidity's `uint192` operator. + * + * Requirements: + * + * - input must fit into 192 bits + */ + function toUint192(uint256 value) internal pure returns (uint192) { + if (value > type(uint192).max) { + revert SafeCastOverflowedUintDowncast(192, value); + } + return uint192(value); + } + + /** + * @dev Returns the downcasted uint184 from uint256, reverting on + * overflow (when the input is greater than largest uint184). + * + * Counterpart to Solidity's `uint184` operator. + * + * Requirements: + * + * - input must fit into 184 bits + */ + function toUint184(uint256 value) internal pure returns (uint184) { + if (value > type(uint184).max) { + revert SafeCastOverflowedUintDowncast(184, value); + } + return uint184(value); + } + + /** + * @dev Returns the downcasted uint176 from uint256, reverting on + * overflow (when the input is greater than largest uint176). + * + * Counterpart to Solidity's `uint176` operator. + * + * Requirements: + * + * - input must fit into 176 bits + */ + function toUint176(uint256 value) internal pure returns (uint176) { + if (value > type(uint176).max) { + revert SafeCastOverflowedUintDowncast(176, value); + } + return uint176(value); + } + + /** + * @dev Returns the downcasted uint168 from uint256, reverting on + * overflow (when the input is greater than largest uint168). + * + * Counterpart to Solidity's `uint168` operator. + * + * Requirements: + * + * - input must fit into 168 bits + */ + function toUint168(uint256 value) internal pure returns (uint168) { + if (value > type(uint168).max) { + revert SafeCastOverflowedUintDowncast(168, value); + } + return uint168(value); + } + + /** + * @dev Returns the downcasted uint160 from uint256, reverting on + * overflow (when the input is greater than largest uint160). + * + * Counterpart to Solidity's `uint160` operator. + * + * Requirements: + * + * - input must fit into 160 bits + */ + function toUint160(uint256 value) internal pure returns (uint160) { + if (value > type(uint160).max) { + revert SafeCastOverflowedUintDowncast(160, value); + } + return uint160(value); + } + + /** + * @dev Returns the downcasted uint152 from uint256, reverting on + * overflow (when the input is greater than largest uint152). + * + * Counterpart to Solidity's `uint152` operator. + * + * Requirements: + * + * - input must fit into 152 bits + */ + function toUint152(uint256 value) internal pure returns (uint152) { + if (value > type(uint152).max) { + revert SafeCastOverflowedUintDowncast(152, value); + } + return uint152(value); + } + + /** + * @dev Returns the downcasted uint144 from uint256, reverting on + * overflow (when the input is greater than largest uint144). + * + * Counterpart to Solidity's `uint144` operator. + * + * Requirements: + * + * - input must fit into 144 bits + */ + function toUint144(uint256 value) internal pure returns (uint144) { + if (value > type(uint144).max) { + revert SafeCastOverflowedUintDowncast(144, value); + } + return uint144(value); + } + + /** + * @dev Returns the downcasted uint136 from uint256, reverting on + * overflow (when the input is greater than largest uint136). + * + * Counterpart to Solidity's `uint136` operator. + * + * Requirements: + * + * - input must fit into 136 bits + */ + function toUint136(uint256 value) internal pure returns (uint136) { + if (value > type(uint136).max) { + revert SafeCastOverflowedUintDowncast(136, value); + } + return uint136(value); + } + + /** + * @dev Returns the downcasted uint128 from uint256, reverting on + * overflow (when the input is greater than largest uint128). + * + * Counterpart to Solidity's `uint128` operator. + * + * Requirements: + * + * - input must fit into 128 bits + */ + function toUint128(uint256 value) internal pure returns (uint128) { + if (value > type(uint128).max) { + revert SafeCastOverflowedUintDowncast(128, value); + } + return uint128(value); + } + + /** + * @dev Returns the downcasted uint120 from uint256, reverting on + * overflow (when the input is greater than largest uint120). + * + * Counterpart to Solidity's `uint120` operator. + * + * Requirements: + * + * - input must fit into 120 bits + */ + function toUint120(uint256 value) internal pure returns (uint120) { + if (value > type(uint120).max) { + revert SafeCastOverflowedUintDowncast(120, value); + } + return uint120(value); + } + + /** + * @dev Returns the downcasted uint112 from uint256, reverting on + * overflow (when the input is greater than largest uint112). + * + * Counterpart to Solidity's `uint112` operator. + * + * Requirements: + * + * - input must fit into 112 bits + */ + function toUint112(uint256 value) internal pure returns (uint112) { + if (value > type(uint112).max) { + revert SafeCastOverflowedUintDowncast(112, value); + } + return uint112(value); + } + + /** + * @dev Returns the downcasted uint104 from uint256, reverting on + * overflow (when the input is greater than largest uint104). + * + * Counterpart to Solidity's `uint104` operator. + * + * Requirements: + * + * - input must fit into 104 bits + */ + function toUint104(uint256 value) internal pure returns (uint104) { + if (value > type(uint104).max) { + revert SafeCastOverflowedUintDowncast(104, value); + } + return uint104(value); + } + + /** + * @dev Returns the downcasted uint96 from uint256, reverting on + * overflow (when the input is greater than largest uint96). + * + * Counterpart to Solidity's `uint96` operator. + * + * Requirements: + * + * - input must fit into 96 bits + */ + function toUint96(uint256 value) internal pure returns (uint96) { + if (value > type(uint96).max) { + revert SafeCastOverflowedUintDowncast(96, value); + } + return uint96(value); + } + + /** + * @dev Returns the downcasted uint88 from uint256, reverting on + * overflow (when the input is greater than largest uint88). + * + * Counterpart to Solidity's `uint88` operator. + * + * Requirements: + * + * - input must fit into 88 bits + */ + function toUint88(uint256 value) internal pure returns (uint88) { + if (value > type(uint88).max) { + revert SafeCastOverflowedUintDowncast(88, value); + } + return uint88(value); + } + + /** + * @dev Returns the downcasted uint80 from uint256, reverting on + * overflow (when the input is greater than largest uint80). + * + * Counterpart to Solidity's `uint80` operator. + * + * Requirements: + * + * - input must fit into 80 bits + */ + function toUint80(uint256 value) internal pure returns (uint80) { + if (value > type(uint80).max) { + revert SafeCastOverflowedUintDowncast(80, value); + } + return uint80(value); + } + + /** + * @dev Returns the downcasted uint72 from uint256, reverting on + * overflow (when the input is greater than largest uint72). + * + * Counterpart to Solidity's `uint72` operator. + * + * Requirements: + * + * - input must fit into 72 bits + */ + function toUint72(uint256 value) internal pure returns (uint72) { + if (value > type(uint72).max) { + revert SafeCastOverflowedUintDowncast(72, value); + } + return uint72(value); + } + + /** + * @dev Returns the downcasted uint64 from uint256, reverting on + * overflow (when the input is greater than largest uint64). + * + * Counterpart to Solidity's `uint64` operator. + * + * Requirements: + * + * - input must fit into 64 bits + */ + function toUint64(uint256 value) internal pure returns (uint64) { + if (value > type(uint64).max) { + revert SafeCastOverflowedUintDowncast(64, value); + } + return uint64(value); + } + + /** + * @dev Returns the downcasted uint56 from uint256, reverting on + * overflow (when the input is greater than largest uint56). + * + * Counterpart to Solidity's `uint56` operator. + * + * Requirements: + * + * - input must fit into 56 bits + */ + function toUint56(uint256 value) internal pure returns (uint56) { + if (value > type(uint56).max) { + revert SafeCastOverflowedUintDowncast(56, value); + } + return uint56(value); + } + + /** + * @dev Returns the downcasted uint48 from uint256, reverting on + * overflow (when the input is greater than largest uint48). + * + * Counterpart to Solidity's `uint48` operator. + * + * Requirements: + * + * - input must fit into 48 bits + */ + function toUint48(uint256 value) internal pure returns (uint48) { + if (value > type(uint48).max) { + revert SafeCastOverflowedUintDowncast(48, value); + } + return uint48(value); + } + + /** + * @dev Returns the downcasted uint40 from uint256, reverting on + * overflow (when the input is greater than largest uint40). + * + * Counterpart to Solidity's `uint40` operator. + * + * Requirements: + * + * - input must fit into 40 bits + */ + function toUint40(uint256 value) internal pure returns (uint40) { + if (value > type(uint40).max) { + revert SafeCastOverflowedUintDowncast(40, value); + } + return uint40(value); + } + + /** + * @dev Returns the downcasted uint32 from uint256, reverting on + * overflow (when the input is greater than largest uint32). + * + * Counterpart to Solidity's `uint32` operator. + * + * Requirements: + * + * - input must fit into 32 bits + */ + function toUint32(uint256 value) internal pure returns (uint32) { + if (value > type(uint32).max) { + revert SafeCastOverflowedUintDowncast(32, value); + } + return uint32(value); + } + + /** + * @dev Returns the downcasted uint24 from uint256, reverting on + * overflow (when the input is greater than largest uint24). + * + * Counterpart to Solidity's `uint24` operator. + * + * Requirements: + * + * - input must fit into 24 bits + */ + function toUint24(uint256 value) internal pure returns (uint24) { + if (value > type(uint24).max) { + revert SafeCastOverflowedUintDowncast(24, value); + } + return uint24(value); + } + + /** + * @dev Returns the downcasted uint16 from uint256, reverting on + * overflow (when the input is greater than largest uint16). + * + * Counterpart to Solidity's `uint16` operator. + * + * Requirements: + * + * - input must fit into 16 bits + */ + function toUint16(uint256 value) internal pure returns (uint16) { + if (value > type(uint16).max) { + revert SafeCastOverflowedUintDowncast(16, value); + } + return uint16(value); + } + + /** + * @dev Returns the downcasted uint8 from uint256, reverting on + * overflow (when the input is greater than largest uint8). + * + * Counterpart to Solidity's `uint8` operator. + * + * Requirements: + * + * - input must fit into 8 bits + */ + function toUint8(uint256 value) internal pure returns (uint8) { + if (value > type(uint8).max) { + revert SafeCastOverflowedUintDowncast(8, value); + } + return uint8(value); + } + + /** + * @dev Converts a signed int256 into an unsigned uint256. + * + * Requirements: + * + * - input must be greater than or equal to 0. + */ + function toUint256(int256 value) internal pure returns (uint256) { + if (value < 0) { + revert SafeCastOverflowedIntToUint(value); + } + return uint256(value); + } + + /** + * @dev Returns the downcasted int248 from int256, reverting on + * overflow (when the input is less than smallest int248 or + * greater than largest int248). + * + * Counterpart to Solidity's `int248` operator. + * + * Requirements: + * + * - input must fit into 248 bits + */ + function toInt248(int256 value) internal pure returns (int248 downcasted) { + downcasted = int248(value); + if (downcasted != value) { + revert SafeCastOverflowedIntDowncast(248, value); + } + } + + /** + * @dev Returns the downcasted int240 from int256, reverting on + * overflow (when the input is less than smallest int240 or + * greater than largest int240). + * + * Counterpart to Solidity's `int240` operator. + * + * Requirements: + * + * - input must fit into 240 bits + */ + function toInt240(int256 value) internal pure returns (int240 downcasted) { + downcasted = int240(value); + if (downcasted != value) { + revert SafeCastOverflowedIntDowncast(240, value); + } + } + + /** + * @dev Returns the downcasted int232 from int256, reverting on + * overflow (when the input is less than smallest int232 or + * greater than largest int232). + * + * Counterpart to Solidity's `int232` operator. + * + * Requirements: + * + * - input must fit into 232 bits + */ + function toInt232(int256 value) internal pure returns (int232 downcasted) { + downcasted = int232(value); + if (downcasted != value) { + revert SafeCastOverflowedIntDowncast(232, value); + } + } + + /** + * @dev Returns the downcasted int224 from int256, reverting on + * overflow (when the input is less than smallest int224 or + * greater than largest int224). + * + * Counterpart to Solidity's `int224` operator. + * + * Requirements: + * + * - input must fit into 224 bits + */ + function toInt224(int256 value) internal pure returns (int224 downcasted) { + downcasted = int224(value); + if (downcasted != value) { + revert SafeCastOverflowedIntDowncast(224, value); + } + } + + /** + * @dev Returns the downcasted int216 from int256, reverting on + * overflow (when the input is less than smallest int216 or + * greater than largest int216). + * + * Counterpart to Solidity's `int216` operator. + * + * Requirements: + * + * - input must fit into 216 bits + */ + function toInt216(int256 value) internal pure returns (int216 downcasted) { + downcasted = int216(value); + if (downcasted != value) { + revert SafeCastOverflowedIntDowncast(216, value); + } + } + + /** + * @dev Returns the downcasted int208 from int256, reverting on + * overflow (when the input is less than smallest int208 or + * greater than largest int208). + * + * Counterpart to Solidity's `int208` operator. + * + * Requirements: + * + * - input must fit into 208 bits + */ + function toInt208(int256 value) internal pure returns (int208 downcasted) { + downcasted = int208(value); + if (downcasted != value) { + revert SafeCastOverflowedIntDowncast(208, value); + } + } + + /** + * @dev Returns the downcasted int200 from int256, reverting on + * overflow (when the input is less than smallest int200 or + * greater than largest int200). + * + * Counterpart to Solidity's `int200` operator. + * + * Requirements: + * + * - input must fit into 200 bits + */ + function toInt200(int256 value) internal pure returns (int200 downcasted) { + downcasted = int200(value); + if (downcasted != value) { + revert SafeCastOverflowedIntDowncast(200, value); + } + } + + /** + * @dev Returns the downcasted int192 from int256, reverting on + * overflow (when the input is less than smallest int192 or + * greater than largest int192). + * + * Counterpart to Solidity's `int192` operator. + * + * Requirements: + * + * - input must fit into 192 bits + */ + function toInt192(int256 value) internal pure returns (int192 downcasted) { + downcasted = int192(value); + if (downcasted != value) { + revert SafeCastOverflowedIntDowncast(192, value); + } + } + + /** + * @dev Returns the downcasted int184 from int256, reverting on + * overflow (when the input is less than smallest int184 or + * greater than largest int184). + * + * Counterpart to Solidity's `int184` operator. + * + * Requirements: + * + * - input must fit into 184 bits + */ + function toInt184(int256 value) internal pure returns (int184 downcasted) { + downcasted = int184(value); + if (downcasted != value) { + revert SafeCastOverflowedIntDowncast(184, value); + } + } + + /** + * @dev Returns the downcasted int176 from int256, reverting on + * overflow (when the input is less than smallest int176 or + * greater than largest int176). + * + * Counterpart to Solidity's `int176` operator. + * + * Requirements: + * + * - input must fit into 176 bits + */ + function toInt176(int256 value) internal pure returns (int176 downcasted) { + downcasted = int176(value); + if (downcasted != value) { + revert SafeCastOverflowedIntDowncast(176, value); + } + } + + /** + * @dev Returns the downcasted int168 from int256, reverting on + * overflow (when the input is less than smallest int168 or + * greater than largest int168). + * + * Counterpart to Solidity's `int168` operator. + * + * Requirements: + * + * - input must fit into 168 bits + */ + function toInt168(int256 value) internal pure returns (int168 downcasted) { + downcasted = int168(value); + if (downcasted != value) { + revert SafeCastOverflowedIntDowncast(168, value); + } + } + + /** + * @dev Returns the downcasted int160 from int256, reverting on + * overflow (when the input is less than smallest int160 or + * greater than largest int160). + * + * Counterpart to Solidity's `int160` operator. + * + * Requirements: + * + * - input must fit into 160 bits + */ + function toInt160(int256 value) internal pure returns (int160 downcasted) { + downcasted = int160(value); + if (downcasted != value) { + revert SafeCastOverflowedIntDowncast(160, value); + } + } + + /** + * @dev Returns the downcasted int152 from int256, reverting on + * overflow (when the input is less than smallest int152 or + * greater than largest int152). + * + * Counterpart to Solidity's `int152` operator. + * + * Requirements: + * + * - input must fit into 152 bits + */ + function toInt152(int256 value) internal pure returns (int152 downcasted) { + downcasted = int152(value); + if (downcasted != value) { + revert SafeCastOverflowedIntDowncast(152, value); + } + } + + /** + * @dev Returns the downcasted int144 from int256, reverting on + * overflow (when the input is less than smallest int144 or + * greater than largest int144). + * + * Counterpart to Solidity's `int144` operator. + * + * Requirements: + * + * - input must fit into 144 bits + */ + function toInt144(int256 value) internal pure returns (int144 downcasted) { + downcasted = int144(value); + if (downcasted != value) { + revert SafeCastOverflowedIntDowncast(144, value); + } + } + + /** + * @dev Returns the downcasted int136 from int256, reverting on + * overflow (when the input is less than smallest int136 or + * greater than largest int136). + * + * Counterpart to Solidity's `int136` operator. + * + * Requirements: + * + * - input must fit into 136 bits + */ + function toInt136(int256 value) internal pure returns (int136 downcasted) { + downcasted = int136(value); + if (downcasted != value) { + revert SafeCastOverflowedIntDowncast(136, value); + } + } + + /** + * @dev Returns the downcasted int128 from int256, reverting on + * overflow (when the input is less than smallest int128 or + * greater than largest int128). + * + * Counterpart to Solidity's `int128` operator. + * + * Requirements: + * + * - input must fit into 128 bits + */ + function toInt128(int256 value) internal pure returns (int128 downcasted) { + downcasted = int128(value); + if (downcasted != value) { + revert SafeCastOverflowedIntDowncast(128, value); + } + } + + /** + * @dev Returns the downcasted int120 from int256, reverting on + * overflow (when the input is less than smallest int120 or + * greater than largest int120). + * + * Counterpart to Solidity's `int120` operator. + * + * Requirements: + * + * - input must fit into 120 bits + */ + function toInt120(int256 value) internal pure returns (int120 downcasted) { + downcasted = int120(value); + if (downcasted != value) { + revert SafeCastOverflowedIntDowncast(120, value); + } + } + + /** + * @dev Returns the downcasted int112 from int256, reverting on + * overflow (when the input is less than smallest int112 or + * greater than largest int112). + * + * Counterpart to Solidity's `int112` operator. + * + * Requirements: + * + * - input must fit into 112 bits + */ + function toInt112(int256 value) internal pure returns (int112 downcasted) { + downcasted = int112(value); + if (downcasted != value) { + revert SafeCastOverflowedIntDowncast(112, value); + } + } + + /** + * @dev Returns the downcasted int104 from int256, reverting on + * overflow (when the input is less than smallest int104 or + * greater than largest int104). + * + * Counterpart to Solidity's `int104` operator. + * + * Requirements: + * + * - input must fit into 104 bits + */ + function toInt104(int256 value) internal pure returns (int104 downcasted) { + downcasted = int104(value); + if (downcasted != value) { + revert SafeCastOverflowedIntDowncast(104, value); + } + } + + /** + * @dev Returns the downcasted int96 from int256, reverting on + * overflow (when the input is less than smallest int96 or + * greater than largest int96). + * + * Counterpart to Solidity's `int96` operator. + * + * Requirements: + * + * - input must fit into 96 bits + */ + function toInt96(int256 value) internal pure returns (int96 downcasted) { + downcasted = int96(value); + if (downcasted != value) { + revert SafeCastOverflowedIntDowncast(96, value); + } + } + + /** + * @dev Returns the downcasted int88 from int256, reverting on + * overflow (when the input is less than smallest int88 or + * greater than largest int88). + * + * Counterpart to Solidity's `int88` operator. + * + * Requirements: + * + * - input must fit into 88 bits + */ + function toInt88(int256 value) internal pure returns (int88 downcasted) { + downcasted = int88(value); + if (downcasted != value) { + revert SafeCastOverflowedIntDowncast(88, value); + } + } + + /** + * @dev Returns the downcasted int80 from int256, reverting on + * overflow (when the input is less than smallest int80 or + * greater than largest int80). + * + * Counterpart to Solidity's `int80` operator. + * + * Requirements: + * + * - input must fit into 80 bits + */ + function toInt80(int256 value) internal pure returns (int80 downcasted) { + downcasted = int80(value); + if (downcasted != value) { + revert SafeCastOverflowedIntDowncast(80, value); + } + } + + /** + * @dev Returns the downcasted int72 from int256, reverting on + * overflow (when the input is less than smallest int72 or + * greater than largest int72). + * + * Counterpart to Solidity's `int72` operator. + * + * Requirements: + * + * - input must fit into 72 bits + */ + function toInt72(int256 value) internal pure returns (int72 downcasted) { + downcasted = int72(value); + if (downcasted != value) { + revert SafeCastOverflowedIntDowncast(72, value); + } + } + + /** + * @dev Returns the downcasted int64 from int256, reverting on + * overflow (when the input is less than smallest int64 or + * greater than largest int64). + * + * Counterpart to Solidity's `int64` operator. + * + * Requirements: + * + * - input must fit into 64 bits + */ + function toInt64(int256 value) internal pure returns (int64 downcasted) { + downcasted = int64(value); + if (downcasted != value) { + revert SafeCastOverflowedIntDowncast(64, value); + } + } + + /** + * @dev Returns the downcasted int56 from int256, reverting on + * overflow (when the input is less than smallest int56 or + * greater than largest int56). + * + * Counterpart to Solidity's `int56` operator. + * + * Requirements: + * + * - input must fit into 56 bits + */ + function toInt56(int256 value) internal pure returns (int56 downcasted) { + downcasted = int56(value); + if (downcasted != value) { + revert SafeCastOverflowedIntDowncast(56, value); + } + } + + /** + * @dev Returns the downcasted int48 from int256, reverting on + * overflow (when the input is less than smallest int48 or + * greater than largest int48). + * + * Counterpart to Solidity's `int48` operator. + * + * Requirements: + * + * - input must fit into 48 bits + */ + function toInt48(int256 value) internal pure returns (int48 downcasted) { + downcasted = int48(value); + if (downcasted != value) { + revert SafeCastOverflowedIntDowncast(48, value); + } + } + + /** + * @dev Returns the downcasted int40 from int256, reverting on + * overflow (when the input is less than smallest int40 or + * greater than largest int40). + * + * Counterpart to Solidity's `int40` operator. + * + * Requirements: + * + * - input must fit into 40 bits + */ + function toInt40(int256 value) internal pure returns (int40 downcasted) { + downcasted = int40(value); + if (downcasted != value) { + revert SafeCastOverflowedIntDowncast(40, value); + } + } + + /** + * @dev Returns the downcasted int32 from int256, reverting on + * overflow (when the input is less than smallest int32 or + * greater than largest int32). + * + * Counterpart to Solidity's `int32` operator. + * + * Requirements: + * + * - input must fit into 32 bits + */ + function toInt32(int256 value) internal pure returns (int32 downcasted) { + downcasted = int32(value); + if (downcasted != value) { + revert SafeCastOverflowedIntDowncast(32, value); + } + } + + /** + * @dev Returns the downcasted int24 from int256, reverting on + * overflow (when the input is less than smallest int24 or + * greater than largest int24). + * + * Counterpart to Solidity's `int24` operator. + * + * Requirements: + * + * - input must fit into 24 bits + */ + function toInt24(int256 value) internal pure returns (int24 downcasted) { + downcasted = int24(value); + if (downcasted != value) { + revert SafeCastOverflowedIntDowncast(24, value); + } + } + + /** + * @dev Returns the downcasted int16 from int256, reverting on + * overflow (when the input is less than smallest int16 or + * greater than largest int16). + * + * Counterpart to Solidity's `int16` operator. + * + * Requirements: + * + * - input must fit into 16 bits + */ + function toInt16(int256 value) internal pure returns (int16 downcasted) { + downcasted = int16(value); + if (downcasted != value) { + revert SafeCastOverflowedIntDowncast(16, value); + } + } + + /** + * @dev Returns the downcasted int8 from int256, reverting on + * overflow (when the input is less than smallest int8 or + * greater than largest int8). + * + * Counterpart to Solidity's `int8` operator. + * + * Requirements: + * + * - input must fit into 8 bits + */ + function toInt8(int256 value) internal pure returns (int8 downcasted) { + downcasted = int8(value); + if (downcasted != value) { + revert SafeCastOverflowedIntDowncast(8, value); + } + } + + /** + * @dev Converts an unsigned uint256 into a signed int256. + * + * Requirements: + * + * - input must be less than or equal to maxInt256. + */ + function toInt256(uint256 value) internal pure returns (int256) { + // Note: Unsafe cast below is okay because `type(int256).max` is guaranteed to be positive + if (value > uint256(type(int256).max)) { + revert SafeCastOverflowedUintToInt(value); + } + return int256(value); + } +} diff --git a/contracts/utils/math/SignedMath.sol b/contracts/utils/math/SignedMath.sol new file mode 100644 index 000000000..776b04527 --- /dev/null +++ b/contracts/utils/math/SignedMath.sol @@ -0,0 +1,43 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (utils/math/SignedMath.sol) + +pragma solidity ^0.8.20; + +/** + * @dev Standard signed math utilities missing in the Solidity language. + */ +library SignedMath { + /** + * @dev Returns the largest of two signed numbers. + */ + function max(int256 a, int256 b) internal pure returns (int256) { + return a > b ? a : b; + } + + /** + * @dev Returns the smallest of two signed numbers. + */ + function min(int256 a, int256 b) internal pure returns (int256) { + return a < b ? a : b; + } + + /** + * @dev Returns the average of two signed numbers without overflow. + * The result is rounded towards zero. + */ + function average(int256 a, int256 b) internal pure returns (int256) { + // Formula from the book "Hacker's Delight" + int256 x = (a & b) + ((a ^ b) >> 1); + return x + (int256(uint256(x) >> 255) & (a ^ b)); + } + + /** + * @dev Returns the absolute unsigned value of a signed value. + */ + function abs(int256 n) internal pure returns (uint256) { + unchecked { + // must be unchecked in order to support `n = type(int256).min` + return uint256(n >= 0 ? n : -n); + } + } +} diff --git a/contracts/utils/structs/BitMaps.sol b/contracts/utils/structs/BitMaps.sol new file mode 100644 index 000000000..086653efb --- /dev/null +++ b/contracts/utils/structs/BitMaps.sol @@ -0,0 +1,60 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (utils/structs/BitMaps.sol) +pragma solidity ^0.8.20; + +/** + * @dev Library for managing uint256 to bool mapping in a compact and efficient way, provided the keys are sequential. + * Largely inspired by Uniswap's https://github.com/Uniswap/merkle-distributor/blob/master/contracts/MerkleDistributor.sol[merkle-distributor]. + * + * BitMaps pack 256 booleans across each bit of a single 256-bit slot of `uint256` type. + * Hence booleans corresponding to 256 _sequential_ indices would only consume a single slot, + * unlike the regular `bool` which would consume an entire slot for a single value. + * + * This results in gas savings in two ways: + * + * - Setting a zero value to non-zero only once every 256 times + * - Accessing the same warm slot for every 256 _sequential_ indices + */ +library BitMaps { + struct BitMap { + mapping(uint256 bucket => uint256) _data; + } + + /** + * @dev Returns whether the bit at `index` is set. + */ + function get(BitMap storage bitmap, uint256 index) internal view returns (bool) { + uint256 bucket = index >> 8; + uint256 mask = 1 << (index & 0xff); + return bitmap._data[bucket] & mask != 0; + } + + /** + * @dev Sets the bit at `index` to the boolean `value`. + */ + function setTo(BitMap storage bitmap, uint256 index, bool value) internal { + if (value) { + set(bitmap, index); + } else { + unset(bitmap, index); + } + } + + /** + * @dev Sets the bit at `index`. + */ + function set(BitMap storage bitmap, uint256 index) internal { + uint256 bucket = index >> 8; + uint256 mask = 1 << (index & 0xff); + bitmap._data[bucket] |= mask; + } + + /** + * @dev Unsets the bit at `index`. + */ + function unset(BitMap storage bitmap, uint256 index) internal { + uint256 bucket = index >> 8; + uint256 mask = 1 << (index & 0xff); + bitmap._data[bucket] &= ~mask; + } +} diff --git a/contracts/utils/structs/Checkpoints.sol b/contracts/utils/structs/Checkpoints.sol new file mode 100644 index 000000000..49d73ce21 --- /dev/null +++ b/contracts/utils/structs/Checkpoints.sol @@ -0,0 +1,603 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (utils/structs/Checkpoints.sol) +// This file was procedurally generated from scripts/generate/templates/Checkpoints.js. + +pragma solidity ^0.8.20; + +import {Math} from "../math/Math.sol"; + +/** + * @dev This library defines the `Trace*` struct, for checkpointing values as they change at different points in + * time, and later looking up past values by block number. See {Votes} as an example. + * + * To create a history of checkpoints define a variable type `Checkpoints.Trace*` in your contract, and store a new + * checkpoint for the current transaction block using the {push} function. + */ +library Checkpoints { + /** + * @dev A value was attempted to be inserted on a past checkpoint. + */ + error CheckpointUnorderedInsertion(); + + struct Trace224 { + Checkpoint224[] _checkpoints; + } + + struct Checkpoint224 { + uint32 _key; + uint224 _value; + } + + /** + * @dev Pushes a (`key`, `value`) pair into a Trace224 so that it is stored as the checkpoint. + * + * Returns previous value and new value. + * + * IMPORTANT: Never accept `key` as a user input, since an arbitrary `type(uint32).max` key set will disable the + * library. + */ + function push(Trace224 storage self, uint32 key, uint224 value) internal returns (uint224, uint224) { + return _insert(self._checkpoints, key, value); + } + + /** + * @dev Returns the value in the first (oldest) checkpoint with key greater or equal than the search key, or zero if + * there is none. + */ + function lowerLookup(Trace224 storage self, uint32 key) internal view returns (uint224) { + uint256 len = self._checkpoints.length; + uint256 pos = _lowerBinaryLookup(self._checkpoints, key, 0, len); + return pos == len ? 0 : _unsafeAccess(self._checkpoints, pos)._value; + } + + /** + * @dev Returns the value in the last (most recent) checkpoint with key lower or equal than the search key, or zero + * if there is none. + */ + function upperLookup(Trace224 storage self, uint32 key) internal view returns (uint224) { + uint256 len = self._checkpoints.length; + uint256 pos = _upperBinaryLookup(self._checkpoints, key, 0, len); + return pos == 0 ? 0 : _unsafeAccess(self._checkpoints, pos - 1)._value; + } + + /** + * @dev Returns the value in the last (most recent) checkpoint with key lower or equal than the search key, or zero + * if there is none. + * + * NOTE: This is a variant of {upperLookup} that is optimised to find "recent" checkpoint (checkpoints with high + * keys). + */ + function upperLookupRecent(Trace224 storage self, uint32 key) internal view returns (uint224) { + uint256 len = self._checkpoints.length; + + uint256 low = 0; + uint256 high = len; + + if (len > 5) { + uint256 mid = len - Math.sqrt(len); + if (key < _unsafeAccess(self._checkpoints, mid)._key) { + high = mid; + } else { + low = mid + 1; + } + } + + uint256 pos = _upperBinaryLookup(self._checkpoints, key, low, high); + + return pos == 0 ? 0 : _unsafeAccess(self._checkpoints, pos - 1)._value; + } + + /** + * @dev Returns the value in the most recent checkpoint, or zero if there are no checkpoints. + */ + function latest(Trace224 storage self) internal view returns (uint224) { + uint256 pos = self._checkpoints.length; + return pos == 0 ? 0 : _unsafeAccess(self._checkpoints, pos - 1)._value; + } + + /** + * @dev Returns whether there is a checkpoint in the structure (i.e. it is not empty), and if so the key and value + * in the most recent checkpoint. + */ + function latestCheckpoint(Trace224 storage self) internal view returns (bool exists, uint32 _key, uint224 _value) { + uint256 pos = self._checkpoints.length; + if (pos == 0) { + return (false, 0, 0); + } else { + Checkpoint224 memory ckpt = _unsafeAccess(self._checkpoints, pos - 1); + return (true, ckpt._key, ckpt._value); + } + } + + /** + * @dev Returns the number of checkpoint. + */ + function length(Trace224 storage self) internal view returns (uint256) { + return self._checkpoints.length; + } + + /** + * @dev Returns checkpoint at given position. + */ + function at(Trace224 storage self, uint32 pos) internal view returns (Checkpoint224 memory) { + return self._checkpoints[pos]; + } + + /** + * @dev Pushes a (`key`, `value`) pair into an ordered list of checkpoints, either by inserting a new checkpoint, + * or by updating the last one. + */ + function _insert(Checkpoint224[] storage self, uint32 key, uint224 value) private returns (uint224, uint224) { + uint256 pos = self.length; + + if (pos > 0) { + // Copying to memory is important here. + Checkpoint224 memory last = _unsafeAccess(self, pos - 1); + + // Checkpoint keys must be non-decreasing. + if (last._key > key) { + revert CheckpointUnorderedInsertion(); + } + + // Update or push new checkpoint + if (last._key == key) { + _unsafeAccess(self, pos - 1)._value = value; + } else { + self.push(Checkpoint224({_key: key, _value: value})); + } + return (last._value, value); + } else { + self.push(Checkpoint224({_key: key, _value: value})); + return (0, value); + } + } + + /** + * @dev Return the index of the last (most recent) checkpoint with key lower or equal than the search key, or `high` + * if there is none. `low` and `high` define a section where to do the search, with inclusive `low` and exclusive + * `high`. + * + * WARNING: `high` should not be greater than the array's length. + */ + function _upperBinaryLookup( + Checkpoint224[] storage self, + uint32 key, + uint256 low, + uint256 high + ) private view returns (uint256) { + while (low < high) { + uint256 mid = Math.average(low, high); + if (_unsafeAccess(self, mid)._key > key) { + high = mid; + } else { + low = mid + 1; + } + } + return high; + } + + /** + * @dev Return the index of the first (oldest) checkpoint with key is greater or equal than the search key, or + * `high` if there is none. `low` and `high` define a section where to do the search, with inclusive `low` and + * exclusive `high`. + * + * WARNING: `high` should not be greater than the array's length. + */ + function _lowerBinaryLookup( + Checkpoint224[] storage self, + uint32 key, + uint256 low, + uint256 high + ) private view returns (uint256) { + while (low < high) { + uint256 mid = Math.average(low, high); + if (_unsafeAccess(self, mid)._key < key) { + low = mid + 1; + } else { + high = mid; + } + } + return high; + } + + /** + * @dev Access an element of the array without performing bounds check. The position is assumed to be within bounds. + */ + function _unsafeAccess( + Checkpoint224[] storage self, + uint256 pos + ) private pure returns (Checkpoint224 storage result) { + assembly { + mstore(0, self.slot) + result.slot := add(keccak256(0, 0x20), pos) + } + } + + struct Trace208 { + Checkpoint208[] _checkpoints; + } + + struct Checkpoint208 { + uint48 _key; + uint208 _value; + } + + /** + * @dev Pushes a (`key`, `value`) pair into a Trace208 so that it is stored as the checkpoint. + * + * Returns previous value and new value. + * + * IMPORTANT: Never accept `key` as a user input, since an arbitrary `type(uint48).max` key set will disable the + * library. + */ + function push(Trace208 storage self, uint48 key, uint208 value) internal returns (uint208, uint208) { + return _insert(self._checkpoints, key, value); + } + + /** + * @dev Returns the value in the first (oldest) checkpoint with key greater or equal than the search key, or zero if + * there is none. + */ + function lowerLookup(Trace208 storage self, uint48 key) internal view returns (uint208) { + uint256 len = self._checkpoints.length; + uint256 pos = _lowerBinaryLookup(self._checkpoints, key, 0, len); + return pos == len ? 0 : _unsafeAccess(self._checkpoints, pos)._value; + } + + /** + * @dev Returns the value in the last (most recent) checkpoint with key lower or equal than the search key, or zero + * if there is none. + */ + function upperLookup(Trace208 storage self, uint48 key) internal view returns (uint208) { + uint256 len = self._checkpoints.length; + uint256 pos = _upperBinaryLookup(self._checkpoints, key, 0, len); + return pos == 0 ? 0 : _unsafeAccess(self._checkpoints, pos - 1)._value; + } + + /** + * @dev Returns the value in the last (most recent) checkpoint with key lower or equal than the search key, or zero + * if there is none. + * + * NOTE: This is a variant of {upperLookup} that is optimised to find "recent" checkpoint (checkpoints with high + * keys). + */ + function upperLookupRecent(Trace208 storage self, uint48 key) internal view returns (uint208) { + uint256 len = self._checkpoints.length; + + uint256 low = 0; + uint256 high = len; + + if (len > 5) { + uint256 mid = len - Math.sqrt(len); + if (key < _unsafeAccess(self._checkpoints, mid)._key) { + high = mid; + } else { + low = mid + 1; + } + } + + uint256 pos = _upperBinaryLookup(self._checkpoints, key, low, high); + + return pos == 0 ? 0 : _unsafeAccess(self._checkpoints, pos - 1)._value; + } + + /** + * @dev Returns the value in the most recent checkpoint, or zero if there are no checkpoints. + */ + function latest(Trace208 storage self) internal view returns (uint208) { + uint256 pos = self._checkpoints.length; + return pos == 0 ? 0 : _unsafeAccess(self._checkpoints, pos - 1)._value; + } + + /** + * @dev Returns whether there is a checkpoint in the structure (i.e. it is not empty), and if so the key and value + * in the most recent checkpoint. + */ + function latestCheckpoint(Trace208 storage self) internal view returns (bool exists, uint48 _key, uint208 _value) { + uint256 pos = self._checkpoints.length; + if (pos == 0) { + return (false, 0, 0); + } else { + Checkpoint208 memory ckpt = _unsafeAccess(self._checkpoints, pos - 1); + return (true, ckpt._key, ckpt._value); + } + } + + /** + * @dev Returns the number of checkpoint. + */ + function length(Trace208 storage self) internal view returns (uint256) { + return self._checkpoints.length; + } + + /** + * @dev Returns checkpoint at given position. + */ + function at(Trace208 storage self, uint32 pos) internal view returns (Checkpoint208 memory) { + return self._checkpoints[pos]; + } + + /** + * @dev Pushes a (`key`, `value`) pair into an ordered list of checkpoints, either by inserting a new checkpoint, + * or by updating the last one. + */ + function _insert(Checkpoint208[] storage self, uint48 key, uint208 value) private returns (uint208, uint208) { + uint256 pos = self.length; + + if (pos > 0) { + // Copying to memory is important here. + Checkpoint208 memory last = _unsafeAccess(self, pos - 1); + + // Checkpoint keys must be non-decreasing. + if (last._key > key) { + revert CheckpointUnorderedInsertion(); + } + + // Update or push new checkpoint + if (last._key == key) { + _unsafeAccess(self, pos - 1)._value = value; + } else { + self.push(Checkpoint208({_key: key, _value: value})); + } + return (last._value, value); + } else { + self.push(Checkpoint208({_key: key, _value: value})); + return (0, value); + } + } + + /** + * @dev Return the index of the last (most recent) checkpoint with key lower or equal than the search key, or `high` + * if there is none. `low` and `high` define a section where to do the search, with inclusive `low` and exclusive + * `high`. + * + * WARNING: `high` should not be greater than the array's length. + */ + function _upperBinaryLookup( + Checkpoint208[] storage self, + uint48 key, + uint256 low, + uint256 high + ) private view returns (uint256) { + while (low < high) { + uint256 mid = Math.average(low, high); + if (_unsafeAccess(self, mid)._key > key) { + high = mid; + } else { + low = mid + 1; + } + } + return high; + } + + /** + * @dev Return the index of the first (oldest) checkpoint with key is greater or equal than the search key, or + * `high` if there is none. `low` and `high` define a section where to do the search, with inclusive `low` and + * exclusive `high`. + * + * WARNING: `high` should not be greater than the array's length. + */ + function _lowerBinaryLookup( + Checkpoint208[] storage self, + uint48 key, + uint256 low, + uint256 high + ) private view returns (uint256) { + while (low < high) { + uint256 mid = Math.average(low, high); + if (_unsafeAccess(self, mid)._key < key) { + low = mid + 1; + } else { + high = mid; + } + } + return high; + } + + /** + * @dev Access an element of the array without performing bounds check. The position is assumed to be within bounds. + */ + function _unsafeAccess( + Checkpoint208[] storage self, + uint256 pos + ) private pure returns (Checkpoint208 storage result) { + assembly { + mstore(0, self.slot) + result.slot := add(keccak256(0, 0x20), pos) + } + } + + struct Trace160 { + Checkpoint160[] _checkpoints; + } + + struct Checkpoint160 { + uint96 _key; + uint160 _value; + } + + /** + * @dev Pushes a (`key`, `value`) pair into a Trace160 so that it is stored as the checkpoint. + * + * Returns previous value and new value. + * + * IMPORTANT: Never accept `key` as a user input, since an arbitrary `type(uint96).max` key set will disable the + * library. + */ + function push(Trace160 storage self, uint96 key, uint160 value) internal returns (uint160, uint160) { + return _insert(self._checkpoints, key, value); + } + + /** + * @dev Returns the value in the first (oldest) checkpoint with key greater or equal than the search key, or zero if + * there is none. + */ + function lowerLookup(Trace160 storage self, uint96 key) internal view returns (uint160) { + uint256 len = self._checkpoints.length; + uint256 pos = _lowerBinaryLookup(self._checkpoints, key, 0, len); + return pos == len ? 0 : _unsafeAccess(self._checkpoints, pos)._value; + } + + /** + * @dev Returns the value in the last (most recent) checkpoint with key lower or equal than the search key, or zero + * if there is none. + */ + function upperLookup(Trace160 storage self, uint96 key) internal view returns (uint160) { + uint256 len = self._checkpoints.length; + uint256 pos = _upperBinaryLookup(self._checkpoints, key, 0, len); + return pos == 0 ? 0 : _unsafeAccess(self._checkpoints, pos - 1)._value; + } + + /** + * @dev Returns the value in the last (most recent) checkpoint with key lower or equal than the search key, or zero + * if there is none. + * + * NOTE: This is a variant of {upperLookup} that is optimised to find "recent" checkpoint (checkpoints with high + * keys). + */ + function upperLookupRecent(Trace160 storage self, uint96 key) internal view returns (uint160) { + uint256 len = self._checkpoints.length; + + uint256 low = 0; + uint256 high = len; + + if (len > 5) { + uint256 mid = len - Math.sqrt(len); + if (key < _unsafeAccess(self._checkpoints, mid)._key) { + high = mid; + } else { + low = mid + 1; + } + } + + uint256 pos = _upperBinaryLookup(self._checkpoints, key, low, high); + + return pos == 0 ? 0 : _unsafeAccess(self._checkpoints, pos - 1)._value; + } + + /** + * @dev Returns the value in the most recent checkpoint, or zero if there are no checkpoints. + */ + function latest(Trace160 storage self) internal view returns (uint160) { + uint256 pos = self._checkpoints.length; + return pos == 0 ? 0 : _unsafeAccess(self._checkpoints, pos - 1)._value; + } + + /** + * @dev Returns whether there is a checkpoint in the structure (i.e. it is not empty), and if so the key and value + * in the most recent checkpoint. + */ + function latestCheckpoint(Trace160 storage self) internal view returns (bool exists, uint96 _key, uint160 _value) { + uint256 pos = self._checkpoints.length; + if (pos == 0) { + return (false, 0, 0); + } else { + Checkpoint160 memory ckpt = _unsafeAccess(self._checkpoints, pos - 1); + return (true, ckpt._key, ckpt._value); + } + } + + /** + * @dev Returns the number of checkpoint. + */ + function length(Trace160 storage self) internal view returns (uint256) { + return self._checkpoints.length; + } + + /** + * @dev Returns checkpoint at given position. + */ + function at(Trace160 storage self, uint32 pos) internal view returns (Checkpoint160 memory) { + return self._checkpoints[pos]; + } + + /** + * @dev Pushes a (`key`, `value`) pair into an ordered list of checkpoints, either by inserting a new checkpoint, + * or by updating the last one. + */ + function _insert(Checkpoint160[] storage self, uint96 key, uint160 value) private returns (uint160, uint160) { + uint256 pos = self.length; + + if (pos > 0) { + // Copying to memory is important here. + Checkpoint160 memory last = _unsafeAccess(self, pos - 1); + + // Checkpoint keys must be non-decreasing. + if (last._key > key) { + revert CheckpointUnorderedInsertion(); + } + + // Update or push new checkpoint + if (last._key == key) { + _unsafeAccess(self, pos - 1)._value = value; + } else { + self.push(Checkpoint160({_key: key, _value: value})); + } + return (last._value, value); + } else { + self.push(Checkpoint160({_key: key, _value: value})); + return (0, value); + } + } + + /** + * @dev Return the index of the last (most recent) checkpoint with key lower or equal than the search key, or `high` + * if there is none. `low` and `high` define a section where to do the search, with inclusive `low` and exclusive + * `high`. + * + * WARNING: `high` should not be greater than the array's length. + */ + function _upperBinaryLookup( + Checkpoint160[] storage self, + uint96 key, + uint256 low, + uint256 high + ) private view returns (uint256) { + while (low < high) { + uint256 mid = Math.average(low, high); + if (_unsafeAccess(self, mid)._key > key) { + high = mid; + } else { + low = mid + 1; + } + } + return high; + } + + /** + * @dev Return the index of the first (oldest) checkpoint with key is greater or equal than the search key, or + * `high` if there is none. `low` and `high` define a section where to do the search, with inclusive `low` and + * exclusive `high`. + * + * WARNING: `high` should not be greater than the array's length. + */ + function _lowerBinaryLookup( + Checkpoint160[] storage self, + uint96 key, + uint256 low, + uint256 high + ) private view returns (uint256) { + while (low < high) { + uint256 mid = Math.average(low, high); + if (_unsafeAccess(self, mid)._key < key) { + low = mid + 1; + } else { + high = mid; + } + } + return high; + } + + /** + * @dev Access an element of the array without performing bounds check. The position is assumed to be within bounds. + */ + function _unsafeAccess( + Checkpoint160[] storage self, + uint256 pos + ) private pure returns (Checkpoint160 storage result) { + assembly { + mstore(0, self.slot) + result.slot := add(keccak256(0, 0x20), pos) + } + } +} diff --git a/contracts/utils/structs/DoubleEndedQueue.sol b/contracts/utils/structs/DoubleEndedQueue.sol new file mode 100644 index 000000000..1050675ac --- /dev/null +++ b/contracts/utils/structs/DoubleEndedQueue.sol @@ -0,0 +1,169 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (utils/structs/DoubleEndedQueue.sol) +pragma solidity ^0.8.20; + +/** + * @dev A sequence of items with the ability to efficiently push and pop items (i.e. insert and remove) on both ends of + * the sequence (called front and back). Among other access patterns, it can be used to implement efficient LIFO and + * FIFO queues. Storage use is optimized, and all operations are O(1) constant time. This includes {clear}, given that + * the existing queue contents are left in storage. + * + * The struct is called `Bytes32Deque`. Other types can be cast to and from `bytes32`. This data structure can only be + * used in storage, and not in memory. + * ```solidity + * DoubleEndedQueue.Bytes32Deque queue; + * ``` + */ +library DoubleEndedQueue { + /** + * @dev An operation (e.g. {front}) couldn't be completed due to the queue being empty. + */ + error QueueEmpty(); + + /** + * @dev A push operation couldn't be completed due to the queue being full. + */ + error QueueFull(); + + /** + * @dev An operation (e.g. {at}) couldn't be completed due to an index being out of bounds. + */ + error QueueOutOfBounds(); + + /** + * @dev Indices are 128 bits so begin and end are packed in a single storage slot for efficient access. + * + * Struct members have an underscore prefix indicating that they are "private" and should not be read or written to + * directly. Use the functions provided below instead. Modifying the struct manually may violate assumptions and + * lead to unexpected behavior. + * + * The first item is at data[begin] and the last item is at data[end - 1]. This range can wrap around. + */ + struct Bytes32Deque { + uint128 _begin; + uint128 _end; + mapping(uint128 index => bytes32) _data; + } + + /** + * @dev Inserts an item at the end of the queue. + * + * Reverts with {QueueFull} if the queue is full. + */ + function pushBack(Bytes32Deque storage deque, bytes32 value) internal { + unchecked { + uint128 backIndex = deque._end; + if (backIndex + 1 == deque._begin) revert QueueFull(); + deque._data[backIndex] = value; + deque._end = backIndex + 1; + } + } + + /** + * @dev Removes the item at the end of the queue and returns it. + * + * Reverts with {QueueEmpty} if the queue is empty. + */ + function popBack(Bytes32Deque storage deque) internal returns (bytes32 value) { + unchecked { + uint128 backIndex = deque._end; + if (backIndex == deque._begin) revert QueueEmpty(); + --backIndex; + value = deque._data[backIndex]; + delete deque._data[backIndex]; + deque._end = backIndex; + } + } + + /** + * @dev Inserts an item at the beginning of the queue. + * + * Reverts with {QueueFull} if the queue is full. + */ + function pushFront(Bytes32Deque storage deque, bytes32 value) internal { + unchecked { + uint128 frontIndex = deque._begin - 1; + if (frontIndex == deque._end) revert QueueFull(); + deque._data[frontIndex] = value; + deque._begin = frontIndex; + } + } + + /** + * @dev Removes the item at the beginning of the queue and returns it. + * + * Reverts with `QueueEmpty` if the queue is empty. + */ + function popFront(Bytes32Deque storage deque) internal returns (bytes32 value) { + unchecked { + uint128 frontIndex = deque._begin; + if (frontIndex == deque._end) revert QueueEmpty(); + value = deque._data[frontIndex]; + delete deque._data[frontIndex]; + deque._begin = frontIndex + 1; + } + } + + /** + * @dev Returns the item at the beginning of the queue. + * + * Reverts with `QueueEmpty` if the queue is empty. + */ + function front(Bytes32Deque storage deque) internal view returns (bytes32 value) { + if (empty(deque)) revert QueueEmpty(); + return deque._data[deque._begin]; + } + + /** + * @dev Returns the item at the end of the queue. + * + * Reverts with `QueueEmpty` if the queue is empty. + */ + function back(Bytes32Deque storage deque) internal view returns (bytes32 value) { + if (empty(deque)) revert QueueEmpty(); + unchecked { + return deque._data[deque._end - 1]; + } + } + + /** + * @dev Return the item at a position in the queue given by `index`, with the first item at 0 and last item at + * `length(deque) - 1`. + * + * Reverts with `QueueOutOfBounds` if the index is out of bounds. + */ + function at(Bytes32Deque storage deque, uint256 index) internal view returns (bytes32 value) { + if (index >= length(deque)) revert QueueOutOfBounds(); + // By construction, length is a uint128, so the check above ensures that index can be safely downcast to uint128 + unchecked { + return deque._data[deque._begin + uint128(index)]; + } + } + + /** + * @dev Resets the queue back to being empty. + * + * NOTE: The current items are left behind in storage. This does not affect the functioning of the queue, but misses + * out on potential gas refunds. + */ + function clear(Bytes32Deque storage deque) internal { + deque._begin = 0; + deque._end = 0; + } + + /** + * @dev Returns the number of items in the queue. + */ + function length(Bytes32Deque storage deque) internal view returns (uint256) { + unchecked { + return uint256(deque._end - deque._begin); + } + } + + /** + * @dev Returns true if the queue is empty. + */ + function empty(Bytes32Deque storage deque) internal view returns (bool) { + return deque._end == deque._begin; + } +} diff --git a/contracts/utils/structs/EnumerableMap.sol b/contracts/utils/structs/EnumerableMap.sol new file mode 100644 index 000000000..7736f5575 --- /dev/null +++ b/contracts/utils/structs/EnumerableMap.sol @@ -0,0 +1,533 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (utils/structs/EnumerableMap.sol) +// This file was procedurally generated from scripts/generate/templates/EnumerableMap.js. + +pragma solidity ^0.8.20; + +import {EnumerableSet} from "./EnumerableSet.sol"; + +/** + * @dev Library for managing an enumerable variant of Solidity's + * https://solidity.readthedocs.io/en/latest/types.html#mapping-types[`mapping`] + * type. + * + * Maps have the following properties: + * + * - Entries are added, removed, and checked for existence in constant time + * (O(1)). + * - Entries are enumerated in O(n). No guarantees are made on the ordering. + * + * ```solidity + * contract Example { + * // Add the library methods + * using EnumerableMap for EnumerableMap.UintToAddressMap; + * + * // Declare a set state variable + * EnumerableMap.UintToAddressMap private myMap; + * } + * ``` + * + * The following map types are supported: + * + * - `uint256 -> address` (`UintToAddressMap`) since v3.0.0 + * - `address -> uint256` (`AddressToUintMap`) since v4.6.0 + * - `bytes32 -> bytes32` (`Bytes32ToBytes32Map`) since v4.6.0 + * - `uint256 -> uint256` (`UintToUintMap`) since v4.7.0 + * - `bytes32 -> uint256` (`Bytes32ToUintMap`) since v4.7.0 + * + * [WARNING] + * ==== + * Trying to delete such a structure from storage will likely result in data corruption, rendering the structure + * unusable. + * See https://github.com/ethereum/solidity/pull/11843[ethereum/solidity#11843] for more info. + * + * In order to clean an EnumerableMap, you can either remove all elements one by one or create a fresh instance using an + * array of EnumerableMap. + * ==== + */ +library EnumerableMap { + using EnumerableSet for EnumerableSet.Bytes32Set; + + // To implement this library for multiple types with as little code repetition as possible, we write it in + // terms of a generic Map type with bytes32 keys and values. The Map implementation uses private functions, + // and user-facing implementations such as `UintToAddressMap` are just wrappers around the underlying Map. + // This means that we can only create new EnumerableMaps for types that fit in bytes32. + + /** + * @dev Query for a nonexistent map key. + */ + error EnumerableMapNonexistentKey(bytes32 key); + + struct Bytes32ToBytes32Map { + // Storage of keys + EnumerableSet.Bytes32Set _keys; + mapping(bytes32 key => bytes32) _values; + } + + /** + * @dev Adds a key-value pair to a map, or updates the value for an existing + * key. O(1). + * + * Returns true if the key was added to the map, that is if it was not + * already present. + */ + function set(Bytes32ToBytes32Map storage map, bytes32 key, bytes32 value) internal returns (bool) { + map._values[key] = value; + return map._keys.add(key); + } + + /** + * @dev Removes a key-value pair from a map. O(1). + * + * Returns true if the key was removed from the map, that is if it was present. + */ + function remove(Bytes32ToBytes32Map storage map, bytes32 key) internal returns (bool) { + delete map._values[key]; + return map._keys.remove(key); + } + + /** + * @dev Returns true if the key is in the map. O(1). + */ + function contains(Bytes32ToBytes32Map storage map, bytes32 key) internal view returns (bool) { + return map._keys.contains(key); + } + + /** + * @dev Returns the number of key-value pairs in the map. O(1). + */ + function length(Bytes32ToBytes32Map storage map) internal view returns (uint256) { + return map._keys.length(); + } + + /** + * @dev Returns the key-value pair stored at position `index` in the map. O(1). + * + * Note that there are no guarantees on the ordering of entries inside the + * array, and it may change when more entries are added or removed. + * + * Requirements: + * + * - `index` must be strictly less than {length}. + */ + function at(Bytes32ToBytes32Map storage map, uint256 index) internal view returns (bytes32, bytes32) { + bytes32 key = map._keys.at(index); + return (key, map._values[key]); + } + + /** + * @dev Tries to returns the value associated with `key`. O(1). + * Does not revert if `key` is not in the map. + */ + function tryGet(Bytes32ToBytes32Map storage map, bytes32 key) internal view returns (bool, bytes32) { + bytes32 value = map._values[key]; + if (value == bytes32(0)) { + return (contains(map, key), bytes32(0)); + } else { + return (true, value); + } + } + + /** + * @dev Returns the value associated with `key`. O(1). + * + * Requirements: + * + * - `key` must be in the map. + */ + function get(Bytes32ToBytes32Map storage map, bytes32 key) internal view returns (bytes32) { + bytes32 value = map._values[key]; + if (value == 0 && !contains(map, key)) { + revert EnumerableMapNonexistentKey(key); + } + return value; + } + + /** + * @dev Return the an array containing all the keys + * + * WARNING: This operation will copy the entire storage to memory, which can be quite expensive. This is designed + * to mostly be used by view accessors that are queried without any gas fees. Developers should keep in mind that + * this function has an unbounded cost, and using it as part of a state-changing function may render the function + * uncallable if the map grows to a point where copying to memory consumes too much gas to fit in a block. + */ + function keys(Bytes32ToBytes32Map storage map) internal view returns (bytes32[] memory) { + return map._keys.values(); + } + + // UintToUintMap + + struct UintToUintMap { + Bytes32ToBytes32Map _inner; + } + + /** + * @dev Adds a key-value pair to a map, or updates the value for an existing + * key. O(1). + * + * Returns true if the key was added to the map, that is if it was not + * already present. + */ + function set(UintToUintMap storage map, uint256 key, uint256 value) internal returns (bool) { + return set(map._inner, bytes32(key), bytes32(value)); + } + + /** + * @dev Removes a value from a map. O(1). + * + * Returns true if the key was removed from the map, that is if it was present. + */ + function remove(UintToUintMap storage map, uint256 key) internal returns (bool) { + return remove(map._inner, bytes32(key)); + } + + /** + * @dev Returns true if the key is in the map. O(1). + */ + function contains(UintToUintMap storage map, uint256 key) internal view returns (bool) { + return contains(map._inner, bytes32(key)); + } + + /** + * @dev Returns the number of elements in the map. O(1). + */ + function length(UintToUintMap storage map) internal view returns (uint256) { + return length(map._inner); + } + + /** + * @dev Returns the element stored at position `index` in the map. O(1). + * Note that there are no guarantees on the ordering of values inside the + * array, and it may change when more values are added or removed. + * + * Requirements: + * + * - `index` must be strictly less than {length}. + */ + function at(UintToUintMap storage map, uint256 index) internal view returns (uint256, uint256) { + (bytes32 key, bytes32 value) = at(map._inner, index); + return (uint256(key), uint256(value)); + } + + /** + * @dev Tries to returns the value associated with `key`. O(1). + * Does not revert if `key` is not in the map. + */ + function tryGet(UintToUintMap storage map, uint256 key) internal view returns (bool, uint256) { + (bool success, bytes32 value) = tryGet(map._inner, bytes32(key)); + return (success, uint256(value)); + } + + /** + * @dev Returns the value associated with `key`. O(1). + * + * Requirements: + * + * - `key` must be in the map. + */ + function get(UintToUintMap storage map, uint256 key) internal view returns (uint256) { + return uint256(get(map._inner, bytes32(key))); + } + + /** + * @dev Return the an array containing all the keys + * + * WARNING: This operation will copy the entire storage to memory, which can be quite expensive. This is designed + * to mostly be used by view accessors that are queried without any gas fees. Developers should keep in mind that + * this function has an unbounded cost, and using it as part of a state-changing function may render the function + * uncallable if the map grows to a point where copying to memory consumes too much gas to fit in a block. + */ + function keys(UintToUintMap storage map) internal view returns (uint256[] memory) { + bytes32[] memory store = keys(map._inner); + uint256[] memory result; + + /// @solidity memory-safe-assembly + assembly { + result := store + } + + return result; + } + + // UintToAddressMap + + struct UintToAddressMap { + Bytes32ToBytes32Map _inner; + } + + /** + * @dev Adds a key-value pair to a map, or updates the value for an existing + * key. O(1). + * + * Returns true if the key was added to the map, that is if it was not + * already present. + */ + function set(UintToAddressMap storage map, uint256 key, address value) internal returns (bool) { + return set(map._inner, bytes32(key), bytes32(uint256(uint160(value)))); + } + + /** + * @dev Removes a value from a map. O(1). + * + * Returns true if the key was removed from the map, that is if it was present. + */ + function remove(UintToAddressMap storage map, uint256 key) internal returns (bool) { + return remove(map._inner, bytes32(key)); + } + + /** + * @dev Returns true if the key is in the map. O(1). + */ + function contains(UintToAddressMap storage map, uint256 key) internal view returns (bool) { + return contains(map._inner, bytes32(key)); + } + + /** + * @dev Returns the number of elements in the map. O(1). + */ + function length(UintToAddressMap storage map) internal view returns (uint256) { + return length(map._inner); + } + + /** + * @dev Returns the element stored at position `index` in the map. O(1). + * Note that there are no guarantees on the ordering of values inside the + * array, and it may change when more values are added or removed. + * + * Requirements: + * + * - `index` must be strictly less than {length}. + */ + function at(UintToAddressMap storage map, uint256 index) internal view returns (uint256, address) { + (bytes32 key, bytes32 value) = at(map._inner, index); + return (uint256(key), address(uint160(uint256(value)))); + } + + /** + * @dev Tries to returns the value associated with `key`. O(1). + * Does not revert if `key` is not in the map. + */ + function tryGet(UintToAddressMap storage map, uint256 key) internal view returns (bool, address) { + (bool success, bytes32 value) = tryGet(map._inner, bytes32(key)); + return (success, address(uint160(uint256(value)))); + } + + /** + * @dev Returns the value associated with `key`. O(1). + * + * Requirements: + * + * - `key` must be in the map. + */ + function get(UintToAddressMap storage map, uint256 key) internal view returns (address) { + return address(uint160(uint256(get(map._inner, bytes32(key))))); + } + + /** + * @dev Return the an array containing all the keys + * + * WARNING: This operation will copy the entire storage to memory, which can be quite expensive. This is designed + * to mostly be used by view accessors that are queried without any gas fees. Developers should keep in mind that + * this function has an unbounded cost, and using it as part of a state-changing function may render the function + * uncallable if the map grows to a point where copying to memory consumes too much gas to fit in a block. + */ + function keys(UintToAddressMap storage map) internal view returns (uint256[] memory) { + bytes32[] memory store = keys(map._inner); + uint256[] memory result; + + /// @solidity memory-safe-assembly + assembly { + result := store + } + + return result; + } + + // AddressToUintMap + + struct AddressToUintMap { + Bytes32ToBytes32Map _inner; + } + + /** + * @dev Adds a key-value pair to a map, or updates the value for an existing + * key. O(1). + * + * Returns true if the key was added to the map, that is if it was not + * already present. + */ + function set(AddressToUintMap storage map, address key, uint256 value) internal returns (bool) { + return set(map._inner, bytes32(uint256(uint160(key))), bytes32(value)); + } + + /** + * @dev Removes a value from a map. O(1). + * + * Returns true if the key was removed from the map, that is if it was present. + */ + function remove(AddressToUintMap storage map, address key) internal returns (bool) { + return remove(map._inner, bytes32(uint256(uint160(key)))); + } + + /** + * @dev Returns true if the key is in the map. O(1). + */ + function contains(AddressToUintMap storage map, address key) internal view returns (bool) { + return contains(map._inner, bytes32(uint256(uint160(key)))); + } + + /** + * @dev Returns the number of elements in the map. O(1). + */ + function length(AddressToUintMap storage map) internal view returns (uint256) { + return length(map._inner); + } + + /** + * @dev Returns the element stored at position `index` in the map. O(1). + * Note that there are no guarantees on the ordering of values inside the + * array, and it may change when more values are added or removed. + * + * Requirements: + * + * - `index` must be strictly less than {length}. + */ + function at(AddressToUintMap storage map, uint256 index) internal view returns (address, uint256) { + (bytes32 key, bytes32 value) = at(map._inner, index); + return (address(uint160(uint256(key))), uint256(value)); + } + + /** + * @dev Tries to returns the value associated with `key`. O(1). + * Does not revert if `key` is not in the map. + */ + function tryGet(AddressToUintMap storage map, address key) internal view returns (bool, uint256) { + (bool success, bytes32 value) = tryGet(map._inner, bytes32(uint256(uint160(key)))); + return (success, uint256(value)); + } + + /** + * @dev Returns the value associated with `key`. O(1). + * + * Requirements: + * + * - `key` must be in the map. + */ + function get(AddressToUintMap storage map, address key) internal view returns (uint256) { + return uint256(get(map._inner, bytes32(uint256(uint160(key))))); + } + + /** + * @dev Return the an array containing all the keys + * + * WARNING: This operation will copy the entire storage to memory, which can be quite expensive. This is designed + * to mostly be used by view accessors that are queried without any gas fees. Developers should keep in mind that + * this function has an unbounded cost, and using it as part of a state-changing function may render the function + * uncallable if the map grows to a point where copying to memory consumes too much gas to fit in a block. + */ + function keys(AddressToUintMap storage map) internal view returns (address[] memory) { + bytes32[] memory store = keys(map._inner); + address[] memory result; + + /// @solidity memory-safe-assembly + assembly { + result := store + } + + return result; + } + + // Bytes32ToUintMap + + struct Bytes32ToUintMap { + Bytes32ToBytes32Map _inner; + } + + /** + * @dev Adds a key-value pair to a map, or updates the value for an existing + * key. O(1). + * + * Returns true if the key was added to the map, that is if it was not + * already present. + */ + function set(Bytes32ToUintMap storage map, bytes32 key, uint256 value) internal returns (bool) { + return set(map._inner, key, bytes32(value)); + } + + /** + * @dev Removes a value from a map. O(1). + * + * Returns true if the key was removed from the map, that is if it was present. + */ + function remove(Bytes32ToUintMap storage map, bytes32 key) internal returns (bool) { + return remove(map._inner, key); + } + + /** + * @dev Returns true if the key is in the map. O(1). + */ + function contains(Bytes32ToUintMap storage map, bytes32 key) internal view returns (bool) { + return contains(map._inner, key); + } + + /** + * @dev Returns the number of elements in the map. O(1). + */ + function length(Bytes32ToUintMap storage map) internal view returns (uint256) { + return length(map._inner); + } + + /** + * @dev Returns the element stored at position `index` in the map. O(1). + * Note that there are no guarantees on the ordering of values inside the + * array, and it may change when more values are added or removed. + * + * Requirements: + * + * - `index` must be strictly less than {length}. + */ + function at(Bytes32ToUintMap storage map, uint256 index) internal view returns (bytes32, uint256) { + (bytes32 key, bytes32 value) = at(map._inner, index); + return (key, uint256(value)); + } + + /** + * @dev Tries to returns the value associated with `key`. O(1). + * Does not revert if `key` is not in the map. + */ + function tryGet(Bytes32ToUintMap storage map, bytes32 key) internal view returns (bool, uint256) { + (bool success, bytes32 value) = tryGet(map._inner, key); + return (success, uint256(value)); + } + + /** + * @dev Returns the value associated with `key`. O(1). + * + * Requirements: + * + * - `key` must be in the map. + */ + function get(Bytes32ToUintMap storage map, bytes32 key) internal view returns (uint256) { + return uint256(get(map._inner, key)); + } + + /** + * @dev Return the an array containing all the keys + * + * WARNING: This operation will copy the entire storage to memory, which can be quite expensive. This is designed + * to mostly be used by view accessors that are queried without any gas fees. Developers should keep in mind that + * this function has an unbounded cost, and using it as part of a state-changing function may render the function + * uncallable if the map grows to a point where copying to memory consumes too much gas to fit in a block. + */ + function keys(Bytes32ToUintMap storage map) internal view returns (bytes32[] memory) { + bytes32[] memory store = keys(map._inner); + bytes32[] memory result; + + /// @solidity memory-safe-assembly + assembly { + result := store + } + + return result; + } +} diff --git a/contracts/utils/structs/EnumerableSet.sol b/contracts/utils/structs/EnumerableSet.sol new file mode 100644 index 000000000..7cdeb84d1 --- /dev/null +++ b/contracts/utils/structs/EnumerableSet.sol @@ -0,0 +1,378 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (utils/structs/EnumerableSet.sol) +// This file was procedurally generated from scripts/generate/templates/EnumerableSet.js. + +pragma solidity ^0.8.20; + +/** + * @dev Library for managing + * https://en.wikipedia.org/wiki/Set_(abstract_data_type)[sets] of primitive + * types. + * + * Sets have the following properties: + * + * - Elements are added, removed, and checked for existence in constant time + * (O(1)). + * - Elements are enumerated in O(n). No guarantees are made on the ordering. + * + * ```solidity + * contract Example { + * // Add the library methods + * using EnumerableSet for EnumerableSet.AddressSet; + * + * // Declare a set state variable + * EnumerableSet.AddressSet private mySet; + * } + * ``` + * + * As of v3.3.0, sets of type `bytes32` (`Bytes32Set`), `address` (`AddressSet`) + * and `uint256` (`UintSet`) are supported. + * + * [WARNING] + * ==== + * Trying to delete such a structure from storage will likely result in data corruption, rendering the structure + * unusable. + * See https://github.com/ethereum/solidity/pull/11843[ethereum/solidity#11843] for more info. + * + * In order to clean an EnumerableSet, you can either remove all elements one by one or create a fresh instance using an + * array of EnumerableSet. + * ==== + */ +library EnumerableSet { + // To implement this library for multiple types with as little code + // repetition as possible, we write it in terms of a generic Set type with + // bytes32 values. + // The Set implementation uses private functions, and user-facing + // implementations (such as AddressSet) are just wrappers around the + // underlying Set. + // This means that we can only create new EnumerableSets for types that fit + // in bytes32. + + struct Set { + // Storage of set values + bytes32[] _values; + // Position is the index of the value in the `values` array plus 1. + // Position 0 is used to mean a value is not in the set. + mapping(bytes32 value => uint256) _positions; + } + + /** + * @dev Add a value to a set. O(1). + * + * Returns true if the value was added to the set, that is if it was not + * already present. + */ + function _add(Set storage set, bytes32 value) private returns (bool) { + if (!_contains(set, value)) { + set._values.push(value); + // The value is stored at length-1, but we add 1 to all indexes + // and use 0 as a sentinel value + set._positions[value] = set._values.length; + return true; + } else { + return false; + } + } + + /** + * @dev Removes a value from a set. O(1). + * + * Returns true if the value was removed from the set, that is if it was + * present. + */ + function _remove(Set storage set, bytes32 value) private returns (bool) { + // We cache the value's position to prevent multiple reads from the same storage slot + uint256 position = set._positions[value]; + + if (position != 0) { + // Equivalent to contains(set, value) + // To delete an element from the _values array in O(1), we swap the element to delete with the last one in + // the array, and then remove the last element (sometimes called as 'swap and pop'). + // This modifies the order of the array, as noted in {at}. + + uint256 valueIndex = position - 1; + uint256 lastIndex = set._values.length - 1; + + if (valueIndex != lastIndex) { + bytes32 lastValue = set._values[lastIndex]; + + // Move the lastValue to the index where the value to delete is + set._values[valueIndex] = lastValue; + // Update the tracked position of the lastValue (that was just moved) + set._positions[lastValue] = position; + } + + // Delete the slot where the moved value was stored + set._values.pop(); + + // Delete the tracked position for the deleted slot + delete set._positions[value]; + + return true; + } else { + return false; + } + } + + /** + * @dev Returns true if the value is in the set. O(1). + */ + function _contains(Set storage set, bytes32 value) private view returns (bool) { + return set._positions[value] != 0; + } + + /** + * @dev Returns the number of values on the set. O(1). + */ + function _length(Set storage set) private view returns (uint256) { + return set._values.length; + } + + /** + * @dev Returns the value stored at position `index` in the set. O(1). + * + * Note that there are no guarantees on the ordering of values inside the + * array, and it may change when more values are added or removed. + * + * Requirements: + * + * - `index` must be strictly less than {length}. + */ + function _at(Set storage set, uint256 index) private view returns (bytes32) { + return set._values[index]; + } + + /** + * @dev Return the entire set in an array + * + * WARNING: This operation will copy the entire storage to memory, which can be quite expensive. This is designed + * to mostly be used by view accessors that are queried without any gas fees. Developers should keep in mind that + * this function has an unbounded cost, and using it as part of a state-changing function may render the function + * uncallable if the set grows to a point where copying to memory consumes too much gas to fit in a block. + */ + function _values(Set storage set) private view returns (bytes32[] memory) { + return set._values; + } + + // Bytes32Set + + struct Bytes32Set { + Set _inner; + } + + /** + * @dev Add a value to a set. O(1). + * + * Returns true if the value was added to the set, that is if it was not + * already present. + */ + function add(Bytes32Set storage set, bytes32 value) internal returns (bool) { + return _add(set._inner, value); + } + + /** + * @dev Removes a value from a set. O(1). + * + * Returns true if the value was removed from the set, that is if it was + * present. + */ + function remove(Bytes32Set storage set, bytes32 value) internal returns (bool) { + return _remove(set._inner, value); + } + + /** + * @dev Returns true if the value is in the set. O(1). + */ + function contains(Bytes32Set storage set, bytes32 value) internal view returns (bool) { + return _contains(set._inner, value); + } + + /** + * @dev Returns the number of values in the set. O(1). + */ + function length(Bytes32Set storage set) internal view returns (uint256) { + return _length(set._inner); + } + + /** + * @dev Returns the value stored at position `index` in the set. O(1). + * + * Note that there are no guarantees on the ordering of values inside the + * array, and it may change when more values are added or removed. + * + * Requirements: + * + * - `index` must be strictly less than {length}. + */ + function at(Bytes32Set storage set, uint256 index) internal view returns (bytes32) { + return _at(set._inner, index); + } + + /** + * @dev Return the entire set in an array + * + * WARNING: This operation will copy the entire storage to memory, which can be quite expensive. This is designed + * to mostly be used by view accessors that are queried without any gas fees. Developers should keep in mind that + * this function has an unbounded cost, and using it as part of a state-changing function may render the function + * uncallable if the set grows to a point where copying to memory consumes too much gas to fit in a block. + */ + function values(Bytes32Set storage set) internal view returns (bytes32[] memory) { + bytes32[] memory store = _values(set._inner); + bytes32[] memory result; + + /// @solidity memory-safe-assembly + assembly { + result := store + } + + return result; + } + + // AddressSet + + struct AddressSet { + Set _inner; + } + + /** + * @dev Add a value to a set. O(1). + * + * Returns true if the value was added to the set, that is if it was not + * already present. + */ + function add(AddressSet storage set, address value) internal returns (bool) { + return _add(set._inner, bytes32(uint256(uint160(value)))); + } + + /** + * @dev Removes a value from a set. O(1). + * + * Returns true if the value was removed from the set, that is if it was + * present. + */ + function remove(AddressSet storage set, address value) internal returns (bool) { + return _remove(set._inner, bytes32(uint256(uint160(value)))); + } + + /** + * @dev Returns true if the value is in the set. O(1). + */ + function contains(AddressSet storage set, address value) internal view returns (bool) { + return _contains(set._inner, bytes32(uint256(uint160(value)))); + } + + /** + * @dev Returns the number of values in the set. O(1). + */ + function length(AddressSet storage set) internal view returns (uint256) { + return _length(set._inner); + } + + /** + * @dev Returns the value stored at position `index` in the set. O(1). + * + * Note that there are no guarantees on the ordering of values inside the + * array, and it may change when more values are added or removed. + * + * Requirements: + * + * - `index` must be strictly less than {length}. + */ + function at(AddressSet storage set, uint256 index) internal view returns (address) { + return address(uint160(uint256(_at(set._inner, index)))); + } + + /** + * @dev Return the entire set in an array + * + * WARNING: This operation will copy the entire storage to memory, which can be quite expensive. This is designed + * to mostly be used by view accessors that are queried without any gas fees. Developers should keep in mind that + * this function has an unbounded cost, and using it as part of a state-changing function may render the function + * uncallable if the set grows to a point where copying to memory consumes too much gas to fit in a block. + */ + function values(AddressSet storage set) internal view returns (address[] memory) { + bytes32[] memory store = _values(set._inner); + address[] memory result; + + /// @solidity memory-safe-assembly + assembly { + result := store + } + + return result; + } + + // UintSet + + struct UintSet { + Set _inner; + } + + /** + * @dev Add a value to a set. O(1). + * + * Returns true if the value was added to the set, that is if it was not + * already present. + */ + function add(UintSet storage set, uint256 value) internal returns (bool) { + return _add(set._inner, bytes32(value)); + } + + /** + * @dev Removes a value from a set. O(1). + * + * Returns true if the value was removed from the set, that is if it was + * present. + */ + function remove(UintSet storage set, uint256 value) internal returns (bool) { + return _remove(set._inner, bytes32(value)); + } + + /** + * @dev Returns true if the value is in the set. O(1). + */ + function contains(UintSet storage set, uint256 value) internal view returns (bool) { + return _contains(set._inner, bytes32(value)); + } + + /** + * @dev Returns the number of values in the set. O(1). + */ + function length(UintSet storage set) internal view returns (uint256) { + return _length(set._inner); + } + + /** + * @dev Returns the value stored at position `index` in the set. O(1). + * + * Note that there are no guarantees on the ordering of values inside the + * array, and it may change when more values are added or removed. + * + * Requirements: + * + * - `index` must be strictly less than {length}. + */ + function at(UintSet storage set, uint256 index) internal view returns (uint256) { + return uint256(_at(set._inner, index)); + } + + /** + * @dev Return the entire set in an array + * + * WARNING: This operation will copy the entire storage to memory, which can be quite expensive. This is designed + * to mostly be used by view accessors that are queried without any gas fees. Developers should keep in mind that + * this function has an unbounded cost, and using it as part of a state-changing function may render the function + * uncallable if the set grows to a point where copying to memory consumes too much gas to fit in a block. + */ + function values(UintSet storage set) internal view returns (uint256[] memory) { + bytes32[] memory store = _values(set._inner); + uint256[] memory result; + + /// @solidity memory-safe-assembly + assembly { + result := store + } + + return result; + } +} diff --git a/contracts/utils/types/Time.sol b/contracts/utils/types/Time.sol new file mode 100644 index 000000000..df4d0af91 --- /dev/null +++ b/contracts/utils/types/Time.sol @@ -0,0 +1,126 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (utils/types/Time.sol) + +pragma solidity ^0.8.20; + +import {Math} from "../math/Math.sol"; +import {SafeCast} from "../math/SafeCast.sol"; + +/** + * @dev This library provides helpers for manipulating time-related objects. + * + * It uses the following types: + * - `uint48` for timepoints + * - `uint32` for durations + * + * While the library doesn't provide specific types for timepoints and duration, it does provide: + * - a `Delay` type to represent duration that can be programmed to change value automatically at a given point + * - additional helper functions + */ +library Time { + using Time for *; + + /** + * @dev Get the block timestamp as a Timepoint. + */ + function timestamp() internal view returns (uint48) { + return SafeCast.toUint48(block.timestamp); + } + + /** + * @dev Get the block number as a Timepoint. + */ + function blockNumber() internal view returns (uint48) { + return SafeCast.toUint48(block.number); + } + + // ==================================================== Delay ===================================================== + /** + * @dev A `Delay` is a uint32 duration that can be programmed to change value automatically at a given point in the + * future. The "effect" timepoint describes when the transitions happens from the "old" value to the "new" value. + * This allows updating the delay applied to some operation while keeping some guarantees. + * + * In particular, the {update} function guarantees that if the delay is reduced, the old delay still applies for + * some time. For example if the delay is currently 7 days to do an upgrade, the admin should not be able to set + * the delay to 0 and upgrade immediately. If the admin wants to reduce the delay, the old delay (7 days) should + * still apply for some time. + * + * + * The `Delay` type is 112 bits long, and packs the following: + * + * ``` + * | [uint48]: effect date (timepoint) + * | | [uint32]: value before (duration) + * ↓ ↓ ↓ [uint32]: value after (duration) + * 0xAAAAAAAAAAAABBBBBBBBCCCCCCCC + * ``` + * + * NOTE: The {get} and {withUpdate} functions operate using timestamps. Block number based delays are not currently + * supported. + */ + type Delay is uint112; + + /** + * @dev Wrap a duration into a Delay to add the one-step "update in the future" feature + */ + function toDelay(uint32 duration) internal pure returns (Delay) { + return Delay.wrap(duration); + } + + /** + * @dev Get the value at a given timepoint plus the pending value and effect timepoint if there is a scheduled + * change after this timepoint. If the effect timepoint is 0, then the pending value should not be considered. + */ + function _getFullAt(Delay self, uint48 timepoint) private pure returns (uint32, uint32, uint48) { + (uint32 valueBefore, uint32 valueAfter, uint48 effect) = self.unpack(); + return effect <= timepoint ? (valueAfter, 0, 0) : (valueBefore, valueAfter, effect); + } + + /** + * @dev Get the current value plus the pending value and effect timepoint if there is a scheduled change. If the + * effect timepoint is 0, then the pending value should not be considered. + */ + function getFull(Delay self) internal view returns (uint32, uint32, uint48) { + return _getFullAt(self, timestamp()); + } + + /** + * @dev Get the current value. + */ + function get(Delay self) internal view returns (uint32) { + (uint32 delay, , ) = self.getFull(); + return delay; + } + + /** + * @dev Update a Delay object so that it takes a new duration after a timepoint that is automatically computed to + * enforce the old delay at the moment of the update. Returns the updated Delay object and the timestamp when the + * new delay becomes effective. + */ + function withUpdate(Delay self, uint32 newValue, uint32 minSetback) internal view returns (Delay, uint48) { + uint32 value = self.get(); + uint32 setback = uint32(Math.max(minSetback, value > newValue ? value - newValue : 0)); + uint48 effect = timestamp() + setback; + return (pack(value, newValue, effect), effect); + } + + /** + * @dev Split a delay into its components: valueBefore, valueAfter and effect (transition timepoint). + */ + function unpack(Delay self) internal pure returns (uint32, uint32, uint48) { + uint112 raw = Delay.unwrap(self); + + uint32 valueAfter = uint32(raw); + uint32 valueBefore = uint32(raw >> 32); + uint48 effect = uint48(raw >> 64); + + return (valueBefore, valueAfter, effect); + } + + /** + * @dev pack the components into a Delay object. + */ + function pack(uint32 valueBefore, uint32 valueAfter, uint48 effect) internal pure returns (Delay) { + return Delay.wrap((uint112(effect) << 64) | (uint112(valueBefore) << 32) | uint112(valueAfter)); + } +} diff --git a/contracts/vendor/compound/ICompoundTimelock.sol b/contracts/vendor/compound/ICompoundTimelock.sol new file mode 100644 index 000000000..145e0a65f --- /dev/null +++ b/contracts/vendor/compound/ICompoundTimelock.sol @@ -0,0 +1,86 @@ +// SPDX-License-Identifier: MIT +// OpenZeppelin Contracts (last updated v5.0.0-rc.0) (vendor/compound/ICompoundTimelock.sol) + +pragma solidity ^0.8.20; + +/** + * https://github.com/compound-finance/compound-protocol/blob/master/contracts/Timelock.sol[Compound timelock] interface + */ +interface ICompoundTimelock { + event NewAdmin(address indexed newAdmin); + event NewPendingAdmin(address indexed newPendingAdmin); + event NewDelay(uint256 indexed newDelay); + event CancelTransaction( + bytes32 indexed txHash, + address indexed target, + uint256 value, + string signature, + bytes data, + uint256 eta + ); + event ExecuteTransaction( + bytes32 indexed txHash, + address indexed target, + uint256 value, + string signature, + bytes data, + uint256 eta + ); + event QueueTransaction( + bytes32 indexed txHash, + address indexed target, + uint256 value, + string signature, + bytes data, + uint256 eta + ); + + receive() external payable; + + // solhint-disable-next-line func-name-mixedcase + function GRACE_PERIOD() external view returns (uint256); + + // solhint-disable-next-line func-name-mixedcase + function MINIMUM_DELAY() external view returns (uint256); + + // solhint-disable-next-line func-name-mixedcase + function MAXIMUM_DELAY() external view returns (uint256); + + function admin() external view returns (address); + + function pendingAdmin() external view returns (address); + + function delay() external view returns (uint256); + + function queuedTransactions(bytes32) external view returns (bool); + + function setDelay(uint256) external; + + function acceptAdmin() external; + + function setPendingAdmin(address) external; + + function queueTransaction( + address target, + uint256 value, + string memory signature, + bytes memory data, + uint256 eta + ) external returns (bytes32); + + function cancelTransaction( + address target, + uint256 value, + string memory signature, + bytes memory data, + uint256 eta + ) external; + + function executeTransaction( + address target, + uint256 value, + string memory signature, + bytes memory data, + uint256 eta + ) external payable returns (bytes memory); +} diff --git a/contracts/vendor/compound/LICENSE b/contracts/vendor/compound/LICENSE new file mode 100644 index 000000000..7da232470 --- /dev/null +++ b/contracts/vendor/compound/LICENSE @@ -0,0 +1,11 @@ +Copyright 2020 Compound Labs, Inc. + +Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: + +1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. + +2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. + +3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. + +THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. \ No newline at end of file diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 000000000..ca39e51db --- /dev/null +++ b/docs/README.md @@ -0,0 +1,16 @@ +Documentation is hosted at https://docs.openzeppelin.com/contracts. + +All of the content for the site is in this repository. The guides are in the +[docs](/docs) directory, and the API Reference is extracted from comments in +the source code. If you want to help improve the content, this is the +repository you should be contributing to. + +[`solidity-docgen`](https://github.com/OpenZeppelin/solidity-docgen) is the +program that extracts the API Reference from source code. + +The [`docs.openzeppelin.com`](https://github.com/OpenZeppelin/docs.openzeppelin.com) +repository hosts the configuration for the entire site, which includes +documentation for all of the OpenZeppelin projects. + +To run the docs locally you should run `npm run docs:watch` on this +repository. diff --git a/docs/antora.yml b/docs/antora.yml new file mode 100644 index 000000000..46c7444e0 --- /dev/null +++ b/docs/antora.yml @@ -0,0 +1,7 @@ +name: contracts +title: Contracts +version: 5.x-rc +prerelease: true +nav: + - modules/ROOT/nav.adoc + - modules/api/nav.adoc diff --git a/docs/config.js b/docs/config.js new file mode 100644 index 000000000..f0af66390 --- /dev/null +++ b/docs/config.js @@ -0,0 +1,21 @@ +const path = require('path'); +const fs = require('fs'); + +/** @type import('solidity-docgen/dist/config').UserConfig */ +module.exports = { + outputDir: 'docs/modules/api/pages', + templates: 'docs/templates', + exclude: ['mocks'], + pageExtension: '.adoc', + pages: (_, file, config) => { + // For each contract file, find the closest README.adoc and return its location as the output page path. + const sourcesDir = path.resolve(config.root, config.sourcesDir); + let dir = path.resolve(config.root, file.absolutePath); + while (dir.startsWith(sourcesDir)) { + dir = path.dirname(dir); + if (fs.existsSync(path.join(dir, 'README.adoc'))) { + return path.relative(sourcesDir, dir) + config.pageExtension; + } + } + }, +}; diff --git a/docs/modules/ROOT/images/erc4626-attack-3a.png b/docs/modules/ROOT/images/erc4626-attack-3a.png new file mode 100644 index 0000000000000000000000000000000000000000..4cb52237d635f634085d87337322ac5e0741ff01 GIT binary patch literal 60433 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¨> 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 W72fFO~av*&4wv-#`&9xxJ7DPz*Q3{XF6KYttW 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 ZvU7})GO|xKx>5WWyCiin@%)Vk{~s{kR%ZYJ literal 0 HcmV?d00001 diff --git a/docs/modules/ROOT/images/erc4626-attack-6.png b/docs/modules/ROOT/images/erc4626-attack-6.png new file mode 100644 index 0000000000000000000000000000000000000000..1587fb5c1360e59243297ebca9f097ed116dcdc4 GIT binary patch literal 56290 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 O?BA=lCt1P7>wf@z+Op{Y literal 0 HcmV?d00001 diff --git a/docs/modules/ROOT/images/erc4626-attack.png b/docs/modules/ROOT/images/erc4626-attack.png new file mode 100644 index 0000000000000000000000000000000000000000..dc059b228bf86b49a55f9afac01baf1188b51904 GIT binary patch literal 58886 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

g*$r>t!O)t#tQ{bjOl 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 literal 0 HcmV?d00001 diff --git a/docs/modules/ROOT/images/erc4626-mint.png b/docs/modules/ROOT/images/erc4626-mint.png new file mode 100644 index 0000000000000000000000000000000000000000..f89ab90070952a0409570d00e2fb6e9ea0ed8c0f GIT binary patch literal 112787 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�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 literal 0 HcmV?d00001 diff --git a/docs/modules/ROOT/images/erc4626-rate-linear.png b/docs/modules/ROOT/images/erc4626-rate-linear.png new file mode 100644 index 0000000000000000000000000000000000000000..09e8045e15abf6b96c089d171635693a60aed60b GIT binary patch literal 50813 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
_8yl~6 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

XRhnQ}H08>D;q7lu(1A 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 literal 0 HcmV?d00001 diff --git a/docs/modules/ROOT/images/erc4626-rate-loglogext.png b/docs/modules/ROOT/images/erc4626-rate-loglogext.png new file mode 100644 index 0000000000000000000000000000000000000000..127bc7f2fddc37bcfd0863238db2c7874f4e210f GIT binary patch literal 109923 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�S;#YCJ>3E4Gp0$=R%K*`_zT?& z0-ZxnwwzRPywb16+oI$JM@1llN)rv;zB}g&$g2Pjqf_JvB8T=OE;s`)`&TPcu327t8xEeO1ZMeJ77e9@~F*J zv0WRU&=vMRhplNp4Iuw-v4PdJO|6j&ztrf&MR?BrwcXcSX439ESiF|ZlY?30P^^J& z5T$PyP39{_4r!a1-$_>pVKzpcu($RbtLLK*mi)2*-w$oJNBD zE_0d?%|4gqb(?S&ojmQv6X?tx?>70}%I8q%pP^SA_T^Rv| z_!?D#Lp>X>rNBPSi;eF!+Au`Vu&z;Vu}=Bry&4iw{F1Qnjr_t11%8wa_4WIW?Po(* zOmI_$u2P4{*$VsVhJ`X1f z-4|QplsNOJmkDID*G0%aVx}ygv7}95Ze9o#WgVyFm5{<8x+oMQH@t$syf!ME%xwd+`4>sAdTg8Z<6LE(>^PtHgfwtzC)hA;< z31)`FuC^t7CGz^2juNXmRoR`CM!kcdwP1dp2yx0lOwnT}bwB7mxe`VBKxF3QUINBC zN0AS8(o5mWYxoXSPh=HSKNh~W4E^@iYkdyqoke8ApNnU>sbd%IDYe8eTfY3ac)5#j z+wbqpJK}lLJG|2|v5$&N-{9(6*YP`O*+w(gg=br`IhZc~eUFRH=6LerN z5+ng5{fB&8ivqle4PI~L+WqY%8m8OW{_vBAzi(33Nq1%I$?%iZoGPyM%`@gH`YO+V z4&Zr{)AiEEaTlo5q$Tx;Gxl+jaONCC4VBpU5n&DNizN|@E_^r;w z`TYD~;4ggMZ-;2s=x09uwKH zQM9a_wJW{lX$4i}>JoQy)uImc1I?N`Ir}faxM#DS`=$Y{l3yFpCl+p4!g^eMJd|x!FDAhrs}sIShN%taH1<@ zCv$hBP=lv8BPO6_FkguOHZ_%j;_HrJ(O;@e2<>S)JKjSc>7OEylE!);VoYq_7|S%k zfQnELeKSPmwk9=amohH#WH+&d63)=aH`XmA|MUpVs!7OHg6aOIRg#;me*MreD%bZ> z6Er2o-?@_;I=a&Op|h?v21>k+redJlkusk<(rLjWzIrxQ-SR6&VD_sEGj;BwRKv6I zh2N@7!gL?%0v&31El~oxp2=SprQ-Cu-!u>QgfpDf0Nb6^s@CsappzUADZT@FnC$j$ z6Bla6G^K?Jt@~9bz6ZfOO%~b?;}V1ye{R0{mn|=>g)c&qF`6Fdn_wH)%@b3h2t82&!CGEYRuWiigqj&grmtNs{AF>MaL~O#NsA;>> z@0e7IC5E-h`*F5w(mbR^!n}7=+p11vFsr{ZWqg_&?5?~KkQ*C_Z}Bh4z##a{E_&4b zR!nAa>|cdRuX96MSKN3sr71w%pV8WhLyL z)YDFvx7!~Xb-~AMm0{lwP}bL2;b7o=z_9dba@`vhVUw2_uiD&eFQr;sSs9%GUdD^) zlGDvDKQs$UX<6ssl}_pP5KQ9;ow3I^c969ij9@vTCaQ>FA(MTv+U;;Js}1dO05!FA zd5;1(m{C(#i6J1ywYKAluhLuBo(TDNoUlCC_mJ-#lxaml8u@9lO3zlpMD}WQHug^q z2yxtZ_fY+0)oBd|DGYCpLdbsP{Dp;cPdlLrq)>8GuW-JJP|cld6^$aGTS$fu>qc+b zO#AV)<%PTlE+Xz8^Qr1e4iqCN4{l!fA%*Rw6b%tMQQN{`{?EFCfqT8VXXQy01VG{? zqtf+!(dH$5y_SymQyC%AB;&c)sF+*2354VXMXt%CFnsdqYK%=y%+9NfB@j3>v`7Lc z7I@`Snos%zfyGz0seAdiog}p?-`j2_e z<&(};tOZ*Y{!?y|u5L8&JP+u%k`R1+m|?p{Ut)_q=kWlm0VEf}+BzC2Wpz$D9w5oD zdA!_Ut#s$!Oy1EEH5uu2zfp-iWe&oF%Hpgx-m-B{6W~N4Ph~UhweC};XJR;yGd{)# zu30t4(hp3ZJ4WQk>A1k}z(;2wy@9x>LG;oOff*xAFoUfW(4VCk7h)Fp{93m3dTw@j zA|boLVJ|SuNB?MVlW_S~?}t^j%;~nqI_O8i#ui=(gkC%gpj|P;xs99C0)TAy`7CkW zkVV&pl_4ClAwnEqGa3@8fYbAo_>mD0_DRpE2X-HZ+F9;68)o&KYku}uCkcpmQEe{s zsr`W}%+Tp^^9v5bNH!+Mw`sW=qo}5P7}g(HjlSuQNgYp^L;_y+QYgY|UkldAFzZ$J zOgC@H_)L2x&SKG0rH_WT3*oI8;;{Mi`^c$;2`M=&ahP0QC~|{3_BP zCi0}#TJW4lCXQeqoW*4pYtj-ci=5gB>#@fy>Q)7VD(zce?zlW$={4UXYQ<)X%qts=S76uU`D!^4 zObV{f*Uut4nkpIh#YmDVI1i%6F|BSkW0#&J@Jk^sf0B!M!>`N~Jq+e6eU+TK)95)~ zdDZ@C+}ka9S#>9HvXpa@sn7JX@N%04nENSix@)NFon9>pCPHkTKJ=!xonTc(0z{lr z6&f$HXs~I(J{7G>F7nVwMGAiW*!d^$PoBQ({{hcN7R+QduNMCgTS4T=HNZhnN8_z% z=YotvWF}P5)SPk}XZ*M9XA?bZ3MNNCeWa2?-}opLTe5{y3=UdutdXreHz;>8*3{EO z|8FIOQL%SNUulk`3u>@-vQ$V$Aaj2z>S}bSIdtK;u9*;Z$C;X9lzCKd>}RB^wT=Z1 zZW!gB;Mej^a|eGb*mb)o01#dcl3xRuHBj*=~0=U!1Y1k{iL6p9f*%kiZo1tS^F zyVqPh+n+4s^BqYDhHuS{BQXi_jF9+-G*Nq?A9brtIO6on`*xP!CTBNPsy#{(OH!jv zMAlq0EXL~TH6fX6;?jNiHqltnC31lcI*rV$WS&u8%37Rz!z{&^<7~iE6u#07y1Th5 zPSqn}?`V)Jdv!I^+W^w5g6dARXwV1>&|EQ#Qg;9UBD3Pqy#{I{&>tA}-sz`&nqa_R z&M1&16=+3QdU48^+Aijcb+?NtFYpml!y}cpRvnnxsx;wzC;1t)TcZl)u1BN1vw<2r zRqIP+?*ry_@%s(Rg5={Vd|7KZNE3WVU-UO6PN$$V@Wh4EjXQSOANDt|_N zU}R1(Vahc3&S%RJNGQ0`TQ36>Q=`EThvAG}%;kw2)f3j8A>~4KjV6IhvDOGYFDkfMc-Gl-QHyyaDEt8kN98K;@EDTx5|O8EaxrmmWFVyimFo7ypR)H#bIk(VuRZp4A(xwFfwB%; zt`EuAql|d)_5ZbMsMHvtmP5&8uJj_+q|Jas&AS=*i@=fLcVE*T?$Z5sHV`4RdRZ7< znJ)2V#;?Tq`fuiW4<3n3@VxeQX`QaTO^uDcx5yvMrRni5{&RlTXg8UdO5-Cy|&NQJe7VZ{d48kF9Uo^zt1f-T(s5 zE%NMmdxp@V8lQ(NI*#uRpWi6ALE0gtguaxS>JqwSM!si|kAW)KGw8GY5NMKPyrVRa zcOILY6jJ&!L^-+ac30@+HtBD8BX@e1%U7^@fn7op1d#kS3 z_nQS$+xU>L4e8skVp_R-?)C|~72^T~j6zNl!cnAfUd&^k4~}azr+T@xB?cH1>-!&7 zAa%zmA9g-nO?F1hRBiX1;uZn!-%5-}M4a!@t=<}Y#Qu)QBN5*tq#KZXQUNVM$f1l) z>j2Y+4EeGznT(n=)@KShH$}J+(<98!kuXH+K@c{0PDMqh-JX0cr0Zfe%DjLnn4K9k zrGc=WcIz9=KWga|x~uo`uOcUjc4M;X^BYYY=5D9!p%}7IwhZ5dC4_T<3%aFPn}?wb zq8wSiE}+rSCGrn%C$G1EpC&A_l=3^hea_Zyi38(~!;b;WVD+7@H~+}XPy26}ff2@@ zN!RZ{MnQ?WQqb4YIvS|b?Sy#7tMT}1V*?RJxSCTM957Kv@yOX6Kw&|1I zaG6z7X3yaVC)T$A1g-#WrhGZ zSXF-Pha?x&@WI>Y)|1Lf5grcatU*+2t^PNg|)tBcaR9 zU!e8V<~6<%rxJ=cn1f5^m>~LTzxgp$eUgj-S3!akb9`uc}5z^JPdoP(6Nsl!SJ6yN zPX$Rpm$)=qHpU$w%Rzg5aY7qQuiDxFVcQK)RSo5uSLD4V1U*9I-5OZczzRTTm^Bf| za2l2r63R)J+uKs$e$x>FOtV+m_xA!cj6atXCV6UtxWsraH(hj5JxG+-LMP<~5C{U= zXW+pg^R@dI;0naD_Vyf*fNs}3MaU;e8yfULWe3I~JwN|Ag&yllbaZRUj~RF5H6L-} z{PoMJ$e^h`b7w2mJ1>hJIOu#>)RncakNS-vi%-UZk?>HHF^9u9zb80~HO;y@`Vg&tnR`hE2uuO&$8iQJ{`CcjA=>1Rql>_ zFnA-&A*6~CdXHs}ulo0g4)1B0wQN+&Eu7%mBop!O(Tl%)k*}mMDodW=vkFZn`|p_; z7(x>g4uib8vr#)91VE6>K-qNO%JWB9(*L9=RCC8z{?nk4DgO0IyPy4d>BaC?%8jnr zFCqljodpo;is_b#sNu@;U~fPq9^MM-%ku&8W_1KzW%pb-@!chnLfu`Qa3z#KqT-K5 zK0aXbqJ>R(WB&1bYYVq-mEdn;A^j|^WIVGvHCL49d?abb>&IeD(3>c?P3GIT z#X$;T|2OCCOIptz1@-y85Pz92j$Mm7-(Sn-dCX=A$DT< zH(ncG{e~B7qQolJy{gPT#P95OTL=*9o_%*Xs)G>U0F|tPDNodgkWX-u938GH{m=?^ z(?;E(Q%%$;PX(5rPOUJT#nB}_5k!eTj zv2c<-OCBa_+iVW*;S#uBTkXw!7>S+QIeT0*r-_PSzD?wSyDC3OA5}l#xBlAAPJqI@ zR=!Kdf50F(M=0*$e((8cnpk=GI4P|1?f20cNR!fET|!ofhwkJ z`~DRH0fB36mW?SOCBzLk`26c2VB+OX0+|!N*V%oT?gS_^@l7D|{YSgY>HI8P{Hb5b z@Y_5SA)z=P+0}SVo*cyBB2CymvQB1J-+Dd0x_(mGp`aFoQq%YrYkACZ0M4RL7z=E1|SU1ok^#c{TtXTpKWST53&&j>X#)v$yc` zq2~>0+kw^b|US; zZE`bW;i}_rYc|~@w5Ke7Xe&rflfpZByXmTPr6!82@2 zPbs-JfQXkkEuJNxmlrI+F);p*q36?F5&c_Y>2CQqnh&qtZ%n*1hhnZ5d%ga_hd=iX zRJ#_%&Dj#W^xh&Yr+~FA(;92rLCX;(eDPqpWc*~7I!D!%*>qXC%!X&rF7UZ5;1?B( zgo6b&`qj#2X;!6QxfjUG)E7S)U*MKS(ivi*l}{k|HN8uXGHQJg;5y(c&=`S`OefAJ3f=4bxiS zHL?QkEZx=8Vd>1APquTc2TXe%{U`Q^rOuoRbN1W5lycVfjsKDLj5<#0GlB=Bv!B!q z(bhS>9=d+h$6FMeq&h81C;DkQD4RGZIx<;ESAM``!51d#CB{wh1-71bEtb6Siu@nk z=y2ZSdzf(;wuf0zoQA|?P`0N*y0`t;SKd}edC%XM-`0l@3Q)fmGBD^p%ik$5ewli^ z_GYY}@i|LhO8z=R9wT=Q3lZt9W+=$jXP`SsRc)g_e*BH9>F}Ixj^>VHhRg-%+(obS+<25<`vFgFVeCSob-E)T6Oi!nQl2 z5^zQzY8e<0cB(lu4Oy;74ANur4HF2OO*`mPcvrtI3LR&+<{*)U3V)QA_E8QVj?oS` z;(#+`t`Stro0nzrV4jGP<+F@>&^`S_`S|m_7X)2Ak9vm@J{_Rrw4{Y!0E9W#GL!Uu z=`ydIUV{1Pw1aAf8Zn8Keh_MKL`K@{=(LbG?%1`0hknK}!pOEsU64WJh#T6&|19w~3fOM% zXlM9n-u*1JA!~@i1WtoW2U?!4T| zWEeN>{LkVWR_N}u1dAVB2}d0QlA$u^q=UStA`E#QhAdS-sHAu5<-q0$Ad-HE)+a-^ zTC`d5O?ost|A~`-Uo8~miDIbIth)Wg@<|05OZ0VDU{dwoG;R7hBw%stXKY|bh{lz% zyI66~8CvV=2)+YbND*Uwpo{L_Lmy#Q`vx(7U$_?9L~JMK3_Vrs+k0HCPu(YHjUny} z&n`p3IoZs(E9j{UBNqd}kLq0xxZP1EULPoYYLXt7-o)eyOHSqPfYov?XuEHxqiNW* zESADO%%C!K1d=P#|MN?Ojcm58@|0g1jOYep^TTDa_U948U0zFBw9?nz zR7q~VLm6Tz@($Nb$9tcrqg&B8NydUbdq3;)x$eu&)^vEN&c)CKNMwXmZtrUs1s5Bq zSp9iT9p$?Q_DVxqsC-Jh>Bfq4@1sgn3d^p)9RqFQfiIdF1xMA&Yz$s9A<>ZMQ~(jx z;;X})TXF}E>~Q>$tOmb54qB4OcSyT=^SHZK*KNAtiFvQmSOSj$af`x7W+efpFM8ur zVmPCT0M#>8MVem@UWS2rB)-0-@|3VU{*=-Jx2$Z|Nk+r^*%&KnVbeKX!X&h|?(5% zZGqBL`@bH9QuHmAUo;3m5qdeEZ=gfw*(%f0uN;Od6~e(f!wRs02ERb~JXO)NdoL{b z`ZGVV)YQgD_U9j-%5^kC*WtX#_|m1TrPvU984;r2SR)O_SAPr+y@6loXtKX*{@>k` z(}_?J({Z*&>+ZblOqk6xm2(&qa%ppAdFM&;e<+0FEw9RfR-_cUoH-~SIo`0mc+OoL zHUWNYZnY-D$)T7L?Bo|YnyUaGxXC_SwS5wzQ&2^nhbd*tiNG{&T_T;GfNo-Lv-j}X@RW=OjJ1U+V4e6cJh z^xWc?j-w~Q7b;J7A44e%ij)dpu8+O-EFZAf7nw`e?>ftOW)`PSnysT$F-Slv+{rVH z?fSM75CfqZn%f)mYCB+v6Ucb+QwUZp~pZYVvzZC>*LK#yeRhsUmn7!F5#DT3A6deYDWHIaHwQ11BF~%8SgyXCU#{ZYsEtgne(lS@EL_V zeZScind~l4H2;|^)cSCCX5(Mde>h$zzEKQ9WWQ$>{w>DO>w0{?+XTP7qSqR!tqDl1 zfzDgJv|nZU=b;0RX}9IEU#DVd24~!d;*rL~1znLC;f*;-0}cL6_o;f8yRHBDO7l{D zx+zfgzk-UM;iafm`>2aIJKIr%IX zyFM*{xO6Y*5jv~=gxJ9dzm#-HR@`CfdE-xQrH|-X%Hg+eC;vV}zfZpkLnDsMGn;se zzq~U-J=MQ{xOtgdZ^E*%iaq$X2U4DYM1%z4?Y^!R34f+w1gYYn@dFIJS{?-n8vkG z&Hb%4EKsHXcGQ=KpNjDdRZ78LKK93Z=K_eN98o=z6m!~d96Jr=>Ljp0h*1$OVt`fV z^?-zKpEQnd!USWqeh_zthVaf1bBnI*so!7h*0A20nv;Yni$Kj44v5bQyF)AoWAmT( zG6)=oRi$c7nM*Lykmh`OW2)6O=M=1J+f@d@}UP0GzG~_iyrJ?gkUvfxS_RbUtunpv!ZP>5sO0FKu6ZoRLl=7q5qzZPeP!9{aDTaue9wn*fAp#LeX)ZRwJSLS2ebl? zc{x>de>}_?2MOF4-^~Kw3#DD0mZ04l6{zS)@4A zFK))K4Vj2y_|ocd%4b+r>O~O5q0eiaQ#Mihu@wVhOE@%QQCTV3QGyWHpM$P=a59e+kNGar^kb?1_&!kb@o`InJSDIWX-VVYksr@%^ zRhQW23sL?0K`bRTmR~kbj!dHe>Z?2s=r-|9N+o_<$5b*YETISWwv6Ib^wS^9Y+Ce$ z&0IV&p>slYJJz)i)m!NEm+lWoVJn$SezmS*cSO8XEC{UD)^=6*5IK-5-zUlv@Xb@^ znl(Y!=%C=($LAq?BKs)fmw)H=e)FRM{0Yh{OBc(QZN`>h(#}VU^f&~#BVCT7EfFmd z9ioTFXE^NJq6K^}_Q+Heh{jI7dFQ>`wQ!L^WkoM|0FyD?D`vgdFr=cUHVH~E8w!9A zmB>ONQsPr(W%W z4k3*PZ!{sm-bx5hQ}YqAPX~@BD@(|(q_E?>ZoxUJ{uDiG?b0d_HT%|W?!@2u88QhF zd?#}MBBYf#W`!ScS|khf?8YB zOG;$hlSYcaw?(F9%gk0{Eer3Xlf*q3(;(F$0RVXFxcX~{>6f2v5xmbd{-p+(4hA5e zv0KYB$oq2uXJ_>t_9!p)C)kQl+}39@E0%tLE>1OGPJ3p#MI0NnLfd(n;X>U~i7(v^xa!~SNn1&B?cB3ASj z|LX~#%#jS)u_xSs!MnyRNoQ~CvnTX6yVLZpoQ?i&fMrpRPbq+4JRFQ^q;&uh;b9CP zKKQ%rFj-7=Vwk^=xS479@QzY;fMYK=={+_zg|Mx!PyrQaNg%7yfgVgqYx#Uy1!JSi zD&aSEY*O;60J!>hSv92ahEhxtCc8~d+g&Xpm zlp^d+$J*5CJi1xHbS;@JRs&IixqsmxP0xy8Ww`lbGE?L5hTRj;el|;K*$|1VxEGa; z#<4=AnKeE#dvdGPgsAkl#h979{C66bPkP+Bf4P-AHeL3RMg`!MU#6j!d9dFQoPv3(e?&7>dGd9p(KB#{NHAYi6y(4CkU#Cz?^xRdZn>8sf@V}16NZZ|~t!c>F zDgChHZ&FA7kt_Zz^{>CN(N$&CHkC(<&^vf=H}qei^^=0F)^CALyW>1xw7zQ{zQT;7P>A4%w0<%RrmHJHd8pD8-eIv4JS6lQ< z0w%2_q}mb*_?`?!Zy=941#4(|$p_pxgOpkjK>AejTon;pDBjF+%Yz3l(O6zmTCz(V zX)GJ#j6QlWB7b@zB{p9mmV``vmZ3)aX|WQ6bI)iE%w=yX+ItL?D=2WMNuE|Y6{I%2=Ay-M;Jn?Th#oM0f@7N)bqI)8;I6lvQsw0 zV3r^QYK*;`=(mv!#2??tj7Sr=-J6;(aT;Kv?%*?82}XB;BFsFlpDb*^$6ss8AABiI zwZ>Jo9KF?Vl_+}q#CoTJF7Mcb*$VJ!)a&Qkfo^u!&a9G-?e~Vk?NJiX=Gk#mlflOC zF3qjwqgI5!$q1?E+?QZdKzY$b`_TUEz{3jB;C&QMS7)0}Jn5jsP{R-~%=+is0UK|G zx7BFzCmx^%Bn!yLJUAFOjs24O=1|{%B*NtBJFx&|_5Jv_j@#4=arq_jZ=HaAUo`h9 zxa0n_NIX?0dY?;7e%f2fR}L*chtG%^fkTrNikJT3@c*&()lpeB?cOLzNQZ=!G>C+B zgQT>A2uKM?cQ>e{ba#j}(j5ZQ-5?Fp-3>SJ&E|RDbIv;7`NOrO?mc_rx~`e|1+v1I zgF_{D(tsZ+0UlodJ};tgg(KFMaR7(pTjrBbR=n*REX8^U2bQp@Vh&q}Jb(3qW@4h4tQwSd|vM;$Z zrT`D*UUqX_s%1oiumyrybeElrm1x28Yk-;!y1V&&jVk80bQwZQfUAG1@!b#++cRs|Ro|2gpK z>)_J^<=6bd82tbaE}$O)UFl!9ga4^@$34P_6-tt;j@oR3C8S`Q4gaL)w-QSUUJ@0sRVOks98 zXNc#^IB5WJjdR7RuZwu5%$5#X0njMJ@GYG(V5U5-YWadmVZ#G@O{Sk3dctjq$EfuD z?VPD!=+3|#CO{|n$4EWCtOQt=(w{2`cYMD>`!4Wqb*>1Zi+)J5xdL}AAChqbY!nKs z$ESaJ5UU`d>Z>=K3Otv*_C#Ms&hMoAsXs&T97~X)(pLRZ* zl#1wufM9vN%L}MbvOg-3ZuC~{2?gob1Wd;T5fYTZD@up+pj4$`&EmGKp0&AR zT_%;LY9eS!rk^yZo6?$yKuA@j8LpI-l!ZdWjaTCsTq^Q49)O~KyPjU`qnE^B_0$< zTrJIE*6rvtHG_BE0#Oh&7M{|___$DW`~SNKRl&=ev!AJC3TwKv;TMylv6~QEW=)DQ z)XBLQgMkhiss%YUqBJ^sf7-^60YO75!+Fz7Su?+u7Q91x*!OL9dU;Eh85Ms=!cE;j(mi(1xc6)-}mjeqw5vO!9fUWz#L9W-Q5{3UmVQR1RKic?m zeQQ-S%I>{>xG$V7&=Xqg*w*84OVv(N>i^Z_(W38f_^qp-^ifZce~ocnNQm2S5q~^aFg3Yw!mL##h;?K8gO9J8pKG&ueK-F#$8`wGJ}z6zh9x zyF!z;O-}0z$R`9&-%)gCuP#0(5TOFn7*)|V1N0T`bjHQr*}36*_WOmRK%YLM)< z(02$o;&1tK4AJ~#jmTk<2eggl2n&DPk+ zC2}y7q(o`HGuL)X7H(X7N$w;7G@ot1y*q|f{EeFCT32uCkG3}fiz`q4*qn*4!z;}4 zlX#By?2uiirgf3`uf$f80yVJzk?bWVAq7y)Do{X)gLDygIjLzR9o}|D z40B;`aCyq=+`3&IVD1%gTiB-K76?hMkZ-`-`UOyw zu|ww@Jhfn3sstdd6o~eE9H@pRSf3JUH%A zaWP zab6%XoC3TLx`6kAJu1Y?1D&u45YGVZn1bxqa7hRzkV4yG7TIwGpBSJv1igeIzXsBi zkW!G#Dv&=lhjXQ>ji0Qc^?%f)(;1H%g_X7a-#3_xZ^{9(HWuvbS{eyZf@7*QjmE#;ob>Xs;UjmquyeIpT*`RO7es$*1mvp9Qm5L#K@ZywLS64#vUQy zlvAD)^E47>t&h_)i~?>>w}j8){%=TK9YBZ%7=M}|rmb~Um zb6v|^&fk;_j&{iYtdi^L?%{VhZT52JiLJ_~V<^1eUo~ERA4!D>A~itcPs*1tc)tPX z6Tr3PnfcVmg-vyH%YL+bp!h?Z9a)}IysQb#H%i%neG?gk)vDO+3dHb%U~issj$Zjx zJge?Qpi3@rwUIFk>;ixWW82>X4I9v^%Fsh)SDT-Jx35-l&B4MnH+Y&bcextfc!Vg0 zw0(qGO7FzDTz_H!G5hajdA&EV8Js9ayv64H#pc8UT;PBZ&X>K=MQl;$V5!|A5U%MV zdLh~Ip)gM^N!COqeRtITNCc*%2ju5N-g}VQTd&S-B(SXoR+#dVl8C^l`ODtC3ovJ9 zx0vRbwdA&}PJ%iWbS~AfzStaWG0TX-&1h5oqXZanX6!J-oeUV6d;YgELhPTmgmfet_b>XW;V2+0kJLZP^H z6Gql`o5=ZVTWoz}cs)P`c&U$geZEfzgmHoMCJ+r#2Xb(bSqp%%0^?0q>%SsJzyaAW zr&^Yo#4L_{b{{)X#!hCZqzt^;69U^w#NuQiW=Sb``*jcOd389;L{ zvZU>v#D^sz(t*y2;&ed*o0F(zm3k`4KPN}8DhtpQ*=+XJ5v>{LS5HQ-+$?Kb2?vsbf> zVcBr{9uD&PfJCN2KvGQw<`|L|xVX3wW*(S%Lk1e!gX`8jki1{#DHUIS{*Qc9vjqj< z4``g|m!I!B$GZ97gtZj6g8b)h<-KaRt3tF2itC-#m{Q0gRpBN71!1PLN-X44?)3^I zS-L}XT5s%iO*ctQ+p5^Rspen~udUkZ^DL{Rq@_L6mmK-c1q6uB7b4?D);?H{DXG@g)3jl971c&iWRaY*us= zh@j4U$u2WH7v())8tM#hLMfaGiN^aNZK~f7t_7LCp`1A70w$m`diNB)D6`T*;17Dp z>A|eH0Us`BR2n!(LI`d#qTj$pk%5I}{diC~2RM!ZD^alEf$aK6kU?Rf@;4lMwy$vq zCUuw*uyp-(6vL?c)HaSKqs&Q)sJF3Cf2c%_R%=+|ma@=0CdcgZA~%I$PPC>mM+KBN zH>M2ym6U99HfU@#;PC2i0DT*g`fFXEry~%AdD0ohDFWKg|pAs@@?p4G$N2rk|K@NZS{Lphf4Ys6ryAL~VqSIGiklyliexB>w4-Cy-WkYU@kWFYLCao@OUtWsch-zTG{BSX72Ig=|C)u!BHQBS0TWJl_FLMeZfL< zxZk)IQDhgtug3eF?cBwbj zh5rpc6-DMM;2V(I-#6@8^|%-w^e+SU4z2&#`W35Y*xfNttNyM}QaoJNWtbJr_D{d( z9;{6tjk*D*mkAtu9i}M<`6M!gy!XLcd2gWnS4cc8fC5OrbNq|39_2vKnGBKT_gUMJ zedFxv{a$jU|4nVS3H=!p@;b%NCq48%bi^?L)pH!=OmF_;CAP@5aZRO}z8Nz8RGM3C zH8Bim%IRNlJ_D@ZRq%pFK*1I`K$ij|0Kfujg-pd3CyfI3~IqYWCbedVDP)a zh6w5RaeG8$WJ?2p!p~FMd;MRwi-jJj1WeniWa~{{3;hPlO0|o0@TA<0_FL(OlVpD1=jNNC{fxF|Ipk^pip--heU5rp8b=?djLo(V*s@y3b|Kw zLnJp?dqBvg>jL>pj2433LwuZSMEky8k49Zd;6 z5dcNaZy-f5h(KRopW*rQAHd8DESUh{*j2r02Dw*(H}_ix?hU|G;#*J<74Q&(tPX&u z4ZHh=HT25BDfJbwYi%u3V=@5l#*k$PU>pI5-EY9Cik3DzW#|I;H1lYy*=JX^;L!qk-#1Xhv2Rj_0VUxCd;` zA+k|Y)(-#Dq1rTz)?{R1$>~cL)7{l|mBgSLnd>hBOMC(V{Y;*!RBEt3N_p1C5&iuj zb-n*3cci6X7pHuyda2(>h3`Hg?N4WMbG|^}FM#($esbm&KtB^QvQOtjhap%D>EVh4 zg$=Hele^HsMRZ7%m)H5=8IZaM>G}{DJ4D9Db^s361{nIJ#y`LhD?z};w$7jNwMO!a3SJy+l>O%-aWyPva9gK7$Yg_?JMxyvuGsC-)3lkjj5l@K+O% z*bzleo*n>%Z1X*u9QzAVHxZ}Tuh9-YqO{(m*yIdi6i)UpD+4kfR0rwPt zqXaKu2HPf@tibL@$o}RHix#4BUt{I#4Q|{ldr&>945KJ-rM`K z7k-HSkdYr{jhf5vuTrL=5cbnQ%W2r}O35|0&};NpyoqL>@;>_MKsf(7IjG-o8ECl! z2Oc1BjJ2^>!EmZvA|oTS!u882hUxn1+1$v-BC^>NPg6-M5Be zuUCsoQZ7`TFk5Nx7T@A_tV8y{ZKEtb09+vt2OJ*nL zCKfb#{y<{5zRI7LM?!J*p86F&FPdT?lN@3CSo>aE!G1^xPZfjG{Kb>A(0gchqS?CLEgjmX7@&*GSyy|f&;KhsY_i$g1x6RKmSG8 zKLxO&qSpg@uhm9e?$OZyhZ=4-=NILj-&v$UOfLDEGN$=G#@@IHC4|-Sd(D8zg#mrD z$;bVB?D(`MZlcWOpXF?PB+5b1G#mNw)n@AB-hER;}qg>K*64$e*|WC zIWV#V73(lZ;oBRa+7Ca*F6~x+vh599Zs_kz9uMm+-lh>g;JfII)tpy%iq??IvQcj0 z$xFb5j655X406tG4URt2(wyc17r3E0HV#qbftoWVO}F5ajR70-Smy_oH9mhGrc-`{WD`FZJGmG)(6F_W^LL^Z-VW z&k-?xaa3tOX(9Xv6LPPzJ#lw8QjB>pC~RS{#(7iga)t#cJcDLlXA4(4*1_NZ5zA1n zyKzz#@|y8XoRK{JyPh$^7Y)%ZRDcG1$5v!(0V8iuOt(5PuUsh5h7iXykPb0|6l3+9 z0x~K=aKCyFDXNqxLZQf2sZLi@z}0)I5YA8-fln$?jhbjC>YeC-JYi#wM)QLH3Ey|< zv$-a=`jN7(OS9(WoMCWUuH$!{k(OVsFf6)tqa@j9b*;&I91^q2eBYnkAJmlE;#< z?0PTO`~U0m!U2Ic5BgYkNT5x_lgmSid-r*OfH_)w763u~s72wweHojdF*#z{K}wUR zVNY={b_(L6k`fN&Vg|Csmpz$!DuVRZNEXb4;wGS?dAqCYT7R`nDcy2_AJ(L3Uq|Z+u)I z%i=%ielz?brdwO#yQ|*!v^w)qcTT-;i+)x05V(4zXqIF=1&vUyKPH%E`6O( zCJb4Z6UmNR3%#2xdlnUmLv7aMQ)l_|{WXzy;Qw(o?fG@nCqvqE0nVxn!K$;Ku1o@& zyxqdGK8SodGapqz&G-beOd zy$sS8)23X&**OjBM({lopqo>ERPC*Oc!&Y7W)xp^Z{5l1zo>p%A7I-_D>J6)DixA# zrnWD+ud$Zs)DNWC=wsbQ35)kQzO^C#%oKUA-y?KO#bTCD?9>% zW5{O;*f}B81zB`tRUzNZ44xmRombnfo)XQTL{XqO{qA~XFF$eT()#kYjKLqI_8K#H z;kke8HelT#y6L1&HYdWo`!F+M)vx z$V4^<6;(w!^FN4Wpo95YEQYwdnmk>nj|Zo);TJQ{xnof%_E1Al{uD zfNdxDC zQLe|OTzAhVfMz8)gZCNY+3cZR@GJnj3&bQk$mzO|r$RK6J4}hdRT$9uN_VBf4-}*# ze|1FR-H5gKVe*vO(2WeO4wXhyh(pEJ=Hmr}8e| zQso=H{=+>mrStLAnnPZr6qVO6p_leFSu5-VvgCXdKE(N|l(W8LtdZ8TaegMM^6gq% zwY0O9CD($v-5J^Iir)fcj`@r4Su#~1$zL7Ma6!OdKOG+o;O?pj90q_I1-jWIV5cPq ziqxAc2UtTfi?3EmtcQosorn8pqHZ@c* z=&K=(Y#$aJw)G4)Dg1H*|Ly28UGCyhxd{h^{m&31443r{0uDwj!gH;3cYSM#Nr<*{ zm`!Ppt4xxL09!{egFz;Wj9(z!gQO8^cYUxo%T+Y!a%x*0f4p$_W7fi)UZC&EH~55T zz9FlB7Tq6{Y@6?Tg1%=YR}wms0qj+CjzKS>bf0oJ&tW=_ULzrtp8ay{op0r9_WgCP zDodsT&PBhiCx4m01~4GY>ecVbeS!iBe?4iw(e#t5hh4vrD5EqA{-H_WpOf~FSF03t zYn6Ps*IKlod+fC|V4-RyWT-uwwCx%1FmI^}aR$JA&=(3lY>r)?6;9_?Jqb3gCKb33 z6{ou#6l(VF!0;B+PCqQ-1SQle#&EtTxG3o^(S#&dO)6b5E_f2f{;_=4?54+hcJ_c* z-fE&zb8V-)8q;zKy_T_Q_0Q}9kG$2VK*dupAlVNGkOBc*_yaD?>ugUzAoQs3{I6aC{umZcCfX+-wDTtE=CGGMzL}OSTvvLup+TO zKBK1oSU!n3^YMVPyPm1Ho=LsFPGc);%jIsP>X)>ZR$)~>^<3I^PnNxk;BLii)C0r%Odyar$c5cHOL$D^ulikxKEmc^ep|{jk@~=A~(>n=1i%gA=paUTnQq z!dscQhXdHDu6KkBH4e|y>a>|D*!1b!gDUrrE$4Li5-P$UwSGFRAQB@YF?PvebVut= z{CFNsqR5aEy7B(U7Rgjc$nKm{wmk^_sVtmU*!dWx->71n!x=@Z`$_-8STt^i98!kDmXUM%?Xyx%t65weK3OLt7bJ_}wjG zi^ZEO&R}E5^G@mFEc@BYJ>Hf;zkWxltQ|EIeVi zJ3N-XpX)zSJ8jqH0G5g<3$Hl&XLj8#hf^@Ufx;J9)=;n#VrMJAG5f&Fc{lh+mY0l; zyrimYme!RY?X{64OXqNH8!rr0EvFCdsOo43rC2j0;8(^3eDTq-;$ghOa+gFy3te_1 zu2K&JyiX?9Kf?~Eo@>KAo{-nM@uk&R-Kun+o{-I1C>qYh6kpE>_Qfc{7W(~N94Dk3 ztE^w7HQ1Pjb#~tz>7yAOz=n5sjCnd5qVU-mmbZ-FQ@e&WPn!9SOfA5;LeiD{o@;)k zi?*7%IRZW2md5>5_;~nr>^1)E^bpyCjw{muviF?>>okQEO^=rOb~#bzJ zd%B)37Z+<~n+1evW}w+AYUO(!L_L3NGiIiytb-NhYrh>u9#&MGz+k@OcV{0rImI@2 z%%d%NFeB7Z`Bzstf|qDLF1^}>DjIKg%g)}~pX zv+OLxaI3#ekviuP*`y=n9TwM}qR>a!^LHxIslKJtL5y}%kfxJ8dSHG{p2H#4P~nix z?^DmNKtKHx8bS{`G9mnB8+5SBLvw<$Dy(V*+yi{xln9#chX}K=n2CU5Or|Q(S07VnPj;kRvzA`lvGgTcJAS zWe2?@0dsx6sX(()_Pku452i9fiq5cd;BkT3#x3Q+N#$I(~KUOjmABdx;#0|c;`Rx@tDA$ls+pb^lfw@^3 zWKY#odT@;pEV+iqlF{YlkVbPn@0~Xh9f%d&h|VmmzDHA2sn_cuU1241mN@*)bm6lk z-E*fWiS?{mi8Rx~L$2};Tw(@~=;808k-7$7Nb|gR?Y|@G`oY95k`yhQul4xshb5 z0P7%_38t+xD1`EIC(O?VnI>YAf>JJjKl#1!i!AtIJ>80P;^T;3E{>LqS`@L~a%d&^ zYIGG|a>CtqpJ)8?JyUqCiF@>{Wj+FK>6wBXR=QFkLF!b0n$Bcz!@162V!dJ3$*th- zwxt`}Op*I;CXlC=Ib^XS`MWA;AL$TdaZyOvfj`0e-s7&nI7W55 zNJ1(yn%cFUih=U@`S!Jo%b>}v&G-w;sNNzu&}r;aRVCGz9Ov>{eaU*YV(~5$-SoS{O)Q^@ySy;NA?(aQ!NQ$ zYhCzfoM~%zqm~f|5eRbuZ{|)AEkGc^Ml2?HuQwQ7c&QF9iIvwi zp+?lun{Ei$Iip@{3>?&&1SP0YSBG%oqLN#U;G2A}aHjEXTy#|IK8${h9bhS$2RD_P zRiot#eMfI`nNuW8%aLZW^_}X4^)(1cmn-HGSl!`pl%Jh1E>0D0k4A)qZZ0ni8tt<0 zV>3fzwJy2WlvAwLoKO-cJE-9ja?_8KS~YlvZ2hitm<+Q)psB-7&)-CcMM$EMO9%Rf z$J(Pw?YE>5i(O>2M3>TKuuzzlOsGV|zBif4MDtebGm- zR=$OSLT+eJg)eklclTo9gJ9AOjeC6Lfvy&Z=adS_XOds6;_sW}i|ptdra|LQ{c7`p zu?{976rUeDP+>Z?kQR={({`tkjvEpKZz-CFZ^gMYld+&c*-xe3ujWV%!HB18Ttd63syUq z3$?%*8m|bh40|sD_uNU`0nj?7FLodZ6Y=5*`Mi!m2!AEV(7x|g>8+|WKWNnC3}5Z> z$q#Dr+#6W&>9zCeXOPe&&{J|S8u}Oi*v$%ips+s%pHeH}UJwoDjF>}5t5gp7olVaJ ztALxkU*pDmz^-u=Gxv8bcwU2xv4Kw10fl%V^=CAtINvaT%fG-s7Ni~GKrij4xCxBp zWq$BdFdL$1{PZL}##04Mj0S2jbhTJQf9^IxcTsQpEv5b0Uq1DA z0HbWb*e4~gA&9A<)53v5p8Z2IJ|o=;WihAV)00bWm-s9qF^8p|D>z?fF!^MxknRxQ zP29g#^c}~$TjbS#BouPdOkV^nBqf=w8+9Cl`Qz%Qi_hrABrA<9bH4*QN9FEPP_F^- zT=BYYCbh3>uhBHoQGN@5*x`0JMgN!9OrO)AKEu_DMGvKN@oVM6;TWA_mHrmj==H&! z74eb;q#PDq)8>H8+mPm2GtloUquV~wXSt~)P%nI_H3132K?d={!VO;CV8$=)pOw0ZF`dtH`)kB1zTUpZ6t7FasIE4faxX}b zvP@}PLOH@SV1FyNemTm|J3QP*CpoCE7Yci_00xW%-GVCfq1@4&c-1V|pJe=&m|FM% zJ^KN88n1TlWu*tUQ-LiZX-RKB#6q)L_231sR9edcK5qPp`oZh|HlTWT#Q)0bHJnX& zRTbCc$B&K8&E?GW8MB<%2*?kv7?Cb#~k^&yA6>}E~snM1W; zf`w}1ABPlR>?$KGYg0e>US>2SSNGtqp)QOYbK)4YT49CC02jye_LG_JYR&vue`uma zFnyEI30LLr`ej?LOLRzLw0%F0hc;v9X|*;;;FBU!6)Cmtj4!{EjSi-nGZm0bq`CIL zA+;ChP7jD&)fRP2(#(q8m%h~* z&WR_}^l(qEms2*Itea$_*p;b$Fs%m+NdIy~P=Kpg{<=tFw)z!fT!2z(Z;`gw>a(BJIJVI6hFI8@kVjXBeZ4zjvPcp zmEwhHKC4W0;9h?hYUf(a(7;J1^eepSaevJCKbwYkGvAyq2>srlJ>gJ%KS9GiVwOh~ z&_L_jX>g9vRtXXvx3F6pv=qJ+Gq0=}+@B9fpnLDb99XQ#iq_MFIpPeIS1(Zw!F1Ol zo$V_lE<`j?oWZjOJ}y)MSN*=H;#~8drPM)pM&tK*!zgMw@|6af-l7NgSD$$El@V9 z9xLIktE_8znv3VU zMpTqnL(yq})HPS%*7?hGu3zeqr}mC8;0X1BoKFV}akuGUqg|El?-LJJcuvfP#r7~d zu7Fat#h*d!5sEn1S8!;eg+`tb?vw;VSMHw=@5XV%`JY+k}8<`jHux+|26J zriJZVtK2*83$ME}|LU;R_0q6DgYHk464P>OVMo2*Nj#fYE2!+TG8eB~vOpC5#92#Z zi}Zxu?{Qlz64;WgSgIPnt00=@Zfos)&JhQrw2-VMlTf)qu z+dwFF=2{*I-zoL;OA$NoP-VS{Jcco!rl55xJP`7=je2|&Oj@DkB<{TzZjB$MFZ>87$7$if=y5>9gti;03rxy!O z(YC$R(D=L#I|za&=EXH%3t|VSLsSJ$ZTCr=S__%{DRUV}b~N}xf4mtnkKTjP`)VqL zhf4k^YG}><6-aJe;cz2iM1D)%0NY%`D20}2sY*WJbjExpB&6} zjcUAycHf0G4>HN2QjN#-Kv+9Z@A{AyOrot|$&1S`)w$cotLX{7gmH|V?6@QRxzPu@ z-_oa-!7ZmdwX6j3_ZtTka{S!vo7^oOkztOCDNLDv+fLN_2DT-&e{@DHb+I%-VAIP6 z2Bqb#x73|x`!!wSg|Jhs?I;3hQeW2MvMhTXJ6ClZ=nd`Hm`YPM+AaQ%>P+eA7h5C2 z(HY#HXqU#9Y-o@E^gR6xh7*|6+2Swjd5Ya)d8DH&tVbBAqhh|i%WdYovCVCFTqX^L zF=lk~J6j_nZiR52%zk_ERv7HJ#+Xxu^u=qX*O+DXhn)6QGMC{q-DfK^AYP5CXb8AF zcMsI4v`FE+J8|FX^9QpuucHB+UE*4t!GqasjeN;cnzr$n+=_HH-Dq;B0ly z_rONGMQTLUHGB@eSU1-g2L2Y49qby8BX`w7Kr?zD|2D$;;sCFMxqf5?hmt*C7t?gV z`1>dP>4Iw-cjU!q%=L7v;mHCnky)~FY-WF6fF$a&SGzuP)aaLfvFdwpcq#!ZD6GIO zfunU9A)ev3CeL>*Qfz!bbUmx?m8OYpihCPMA(Wf?I9`w{u4d^heUe{4He@SslI9)o|! z^~>+eE0=E5G65H86zs=kSj$l4k0W+#LC>=NIK^^C6`%>P)&yTX&3}uO`jx_N*w7QB zf3?a@QZ#_^HJo$?Ad;}zuDphm3?^(2rw}tXHI?E0Ojy^<;#m{Ilw^8&#BI5jtwEP< zR|h`=CXbHrhmMD!qWpSzFpPI}ysF+y#00iTuQA_@!}w&tz@Uvw8hv6@!2-`SG+*WI${Ckj^uW@3BEK7s^_)EZUl#6Hm($^=4 z&#c)61kvj~ib?q$zi;yaZh*WAv!CUG9SV7@&kw%41KTI{3Y^DQPBF6gksr)z)z=`3 zEIw8q{{;fbBW;}k41LfJnm8>Q#t)s**mS?OaCEGh!MeSap>=FzS`-WL6nWT1^Y9Ct zfq?LIcz7AB}z@OGV3o0F8?_pD)~7-8y&8XS?!BzuZ%{2f&1;dj>&N|#6tV0R=6R~ zU5B&5YyumT8tjbA=9`s6CYsIi^ygTnTY(Ae@4PwA5@MjzQNwk27ReaN%m3+zfy2;* z6=I$rhVMJ3F4<37&P(k*g=N?5P91|&gvA`RI(K8kXNYk`BJnW%r%Lsa0NcZOf-A1K zy(flo3P2CB%>F_=oYmeqy9JN)gvNFKFu@L|rt7(%RbC~h)K2cUj~i$4fv9;()gUXD zuR}ZZ)+RwmmAthz#9`(2hc$DfwiV$cE{v{`7(ZT&cD(W0;5mKWkMnX?_iKA4+$U~@ zm4nL+uEDO$UkMZ)asp!1$<3SkRJ?iQpq2`ai`&exzCfAgFVD+kkz^nkA0KyA>>UoI zti*G)Oz&ooz$ImW6_uDJvt`)-%jI|{RkVrr0kt$bI{HT40MLeJnGpg2SYV9+_dAwJ z!})B=h=GY|_k-}!$*3Z`)84G*0^m53LsM9*cxHNf-eh_AZTFhUO;3*m%sDt!oU}zPKV2>hIivt&;G0Mc3M`^Zl?4-K{)R{g>ZDlCgi)?-Cb0#rn91 zV!Zj#=pKU6HPf0PRe^qin-jNz>H&3#W$h|HTI=g8=d?lpL8sHxA?_E6*7A)gHJZ$` zmes3PsolY{_W$llxw7zd;TunT$j(wNRu}eONSN`2&g?ph|MON+U`txeA3{G!HZ87E zvkzm&El~})aj{aN>+jL1 z-qYob_4U*=ZgEl?J*)W^z~vMC%b-RxwMaG~S&2L6^r^#s2F6XQwGGicQCiEYEq@Vs zuhY}Pp}qM*1_!$j#WeW|uTv1hsnLnp5UOY7wY268X12Gs2w&=nf4F1H!js9XXj;$G z85Lw6w)yu=l&|G&<8cQz1}DPht=4LEXdm$P^3mUl4Nat(PLm5Mf^A_s9nC1upls>xgqXYP)UPGHbpy=Z5k<0x2yyR}xKJ*vXqyg|!a)_wE> zk?l>7I%hdsk)kV;`%|V8>{TM^XCEXVFb7QZNITfQD^Bsi#1KTK!XJ8R&Z*7(r&}8O zWfm_#$Mf;~pC`CK$s3J+SE`YieYh0FVheCs4i*|U))c7tFa92Ok|X_QMFaj3oxt{D zwh~zog#0HU_JR=ak3qTwXy_~Jy|^*;qeR1(1H_yp=Ew(%)$+On*0rb+2_hVAR*H>^ zBAAB>rKp5kQHcpCL=Q|`G={9%+p7c6n0i4;llJq8>Y4(pEx7)J2NzC;0{NjNLeF~M zJnVy)$FEH6HlCIKlP8SLoFKKnf$0t7{4klBo7=U=aAIbQxPs%^lmX0N0&2=L>_tHblMT;{)M~W=v#+hgweUGUEV|tqw?-78VwGczEG)aZ-R( z$0FRn8ohM~cE06ymz{BpykmqbX_iSX{i7ZBT0!b6DiS6pd74eG?Wg&B=H!E9lQRB+ z2jGq3+4>SdXYPGC|KM?K5-K_0zI>$g!JRnew##7RhA+=DbhGjdx2D{2apZB=(X6P3 z(NHP$`-x{CE~pWN;0Ed0Y~$X1-p)4zH>ccEC({Xq)?13Kw%Cn%N`X3}GFC!q-8vhILk@j|1jVEfef(bD;Xm$0JHB{d|ezdo3@uCZ{14>Dl} zaJc}~tJ8enP0AZSD!#i5TNC0QG-uQ4vuTwVM0KbcyFNFv{C>lBRi4t_{jaJ-A zhq+8eH4bYUqGJkLwtId=y|2$%HLf#li>YO=`a9b|cv%|hb0CduPTRuDW{VF_B)i&? zQS#U|77y%vWGsJkuPz%W$})Rn{~(W&Eg=zMZk8#a`f*%15%y;EzDs*{7HgrL`fwO) zFnLzNpN#()_<4fbnGHsQV$ojc62GG%?k7+KZev?Q)zJC~TMCu6HfMQ=-vz z2@I{c{5JfBz8~dq#p2`l;=A1#bZl;oP>b->iTX27m#=KeQ)1%L`N^Bp6B||%gE`rH z-ggTFUb9*XQyY}L9_C8iUKLSkJ6=&AdD>JB3qPtkepxm%G?=a2sKjUp0lP$J4i;QC ze6~#M8qNHn)-%)@+v5!T4XfoJ;jce3KYB!S1Ld-;hKaHd!(Xk$I@I2sF;!Gm_8PoI zsbb99$ej}Tv)R5A>sGCM5fRvvm_9ei2x8{nYpFq9AW42-Z9fL?6ZWdEsZwAo zzmx36soV``ANm;(ocsh2h%3_GeoW5HV$l8*xyrwYZ(!45`&iqqawvVjrSM6_YNPLa z*bNlTvN9&v#?&kRVjP5eC$}3L&ylU4)SVg>=P4)YFY5OxRdkc@+7yg}4$il6=Paw@g`^K5PRy9=JFozKCC z;dZEHp3TX8wb-WGlpH6t?ooR?S2XI#FImB{+q0}>8x~8(WgOCp(Z)T{)5wzcjn_+- zrcZBR3-!hNX94aXG&G9&Zbym6G<-=cBOtew<>l*p0r zR6QYymCj6rLWMD{QiUqx0zG!Eq8DYwgd&>Y>S(ta0fIQT@!6!IZCSffoDMYEMRWBkm#I z9eh!$*xs*pi)v-a4fo68qmB<5vc#no%Wigdddl5(>2^GOS;@?Dk-K0#!BC|H-$nN= z_cy|~LV{O_v}mN`79q*nAfvj@m^B+S#>j6U)|JKoRTq(7ED4%OJ}<8WIcasxe{<;n z5%v~fL2X+bu85>47$6{xf`}j~9g>QafFdnj(w!o$v~)|CfOLa^5+dCt(%r4Z9Sc4C zoOA#GzxR2z``O#=UaU3OTw{(ozIS|cqCPh~cu`qIMdfpkmJ}`W)atv+&#x())7#S~ z7n)YTs&}xPj#n?MT__1`%n!ENyF_SrQ}PAsO9#zQp+?B`a`mREYKM8+mYCE!kXaSe zO11NcLm+U6@m@M#`SQhlT}^T9NYl9q74`rw>WjK4@vSEpC#j7VoOS20$Kor2+?4(Z zFEeXLnQ25ww->!S@7^~FQ|hh(Lqp1B`DI%vr}lmkpW2&c4?I@@-54hwoq(Sm*RS3t zo6+T7RnLQEX}V+qw>lc9US`~Hy!2(cV1wBef5ekrEwQdj`!{63{!e!GGnF)K%HU?J z1_Xr9(yPI2X^*!T@HBZ|AAN5wNI!SFuRX|oSDrv7*3i#-qsqlBh2A6oyYl0L`#upJ z1jwu>6}$O6rgYM3R`$V6Dcnmul1C7(-eo_lVMD|O}}YS8+L;VCjDUHV6qq~ z=`WrSH$oPbzIdU{_ZVaCc^S#p=Xw(Pa4a{G-H5Z}_yHsEye2)c2EAFsYqRXyUDZeF zUy0QY`;nZ2u|F|M(KJ$>bt2Iy;Ny3xs8Du_%SaXfB&G7p zXfGD!wx64^#YsE(K7@ANu?Ru7YzTAvJWD703!`SLu!81*%IKI!mY$nCRQ|F=g+IsQ z6yquUBpUovJmi#kO~mM&ZDLzKj>3T+x}M(mL2wazLFL!wgy1(g>7om(@mEgPzK+Kk zT;50|uL_K&#&+c0`v#SGvU^}HE{x(@cq$bp=WO)dxe1pj+WODL|F{z)&?BNd?Z`4- z;lF?HL#nw!&>tYlmcda<(FU+FbK}NV>+we_v2}xf?C}clwY*;|*|>sPd+|qB=0~(h zzTB#e{Y5jIC&u|D#j;(6m!x00y(JgBS;mq^%vA$1Sm~H(q}O(lefxNEiCxL_2ag;d zhUJJ56I@71(2mkM?iJS7(30VI5{q39T=<>ClL+%*Sg}yioOK7Vivu6!-{|5hfD1+M z#t4kS&7wm!0krAIA9AU)V$SC26UBU}*^!xWDkX@zSi=N9`x4K((*L>&}GMTQ@aoD0`s0hG`gosIH z6!&#D=Sxb!3O0Fz$O7K5DjB~>XP8`O%4_#fvmRz6{9*0LVZPgxo&jgy(3*&*Zrm^_ z?}+fz+TBRCIK$>L{9vFFT!LBGwN z$1wJ}yX!$AEA|}*^|#_}k1F-Xk%baAUzrx(mtE)=gf|^bFR1dl!g{@1hGcQm7V#KK z+B}prQ|)m<1MLMp#){4ZDfb(*0+!*m9yVSB&u>d^1p}FR3D~9$8;?-VPs|a^AgIyI%%JpddfoWs=$iSy% z*T^cn)`+k|2*88<4EI3Y1f)0qO6^I5bVrHJ#zAww{>Y~zPwn@^wzJD`Y%zkGqy+?q zPti@=zh;Pa>aPS}iCmRQ6O+z|kUUO0NMQOQ+Yps2L8z%>US5^+i)DKyvMTPT>s^^< zi~se2cf`Os53RVQM5Czc>)F_<*{IIDE*zY5E|QHNRI@3|N%-OPX^;3E`~CXGb|y$J zQ_L1OT~Y@DHGbY4MQWGpB(>(=|L6OOzw^<*YNvdl15@KPU#;)A@X>mIZ`6Z(8f!l_ zEyuhzCM_xsx4zG2zC4HllJ_l=hc{T5Ol}u!ggpH+mW+QedcG!G30Vj@a@hR{Gqfff z*}d=W3;9k|J$B5Up9XD8eC}0CCI94jp5q9Al;b70m>ZKjqXzNXeTm-}4r0p#hfnYC=Rx ziT84rkuw~rOf^T4|0TDzjE(im^mWp1ze(X<#=Jv3zJ)OiQXWQcT&XqN@L)Of88pr! zG?Nk9ZZU>J2!5D8As1amM@p_(o9?mT)PEAg$gN*EJ+M0M#R2eRGIC{gjn-KGSBkk`h@RLq| zAFTw%LQgsLr7rTHD^Aw_$9K4>XH6A_d=nl+0+})9H~OtSUC>utokzr2KkS`Tp1#)O zj%V7lWOI=@xTRaMq3a>5o13%IZLMuBY`LN`qw-)C9cmP@QXXMW+An1mJbPD1dJ<$m zT9ZF(Ld5qdUki8XV?G7zTeaVBy5$Vsf0VD5ltRpHm%{R75htMe1`lV}KB0e2dKijN zf|u2L<4zsrd#>E({Rs6U*SH;Jqh_^bbtsjTP1?AfoR9=ZbYKS6+C~ioVg`-#2W)z6 zDLS(TXbN=34Fz_tPO@s>c)z>}QLK4;IiSyb;`ZpXFCy#bRbg!mo8$MJ8})b>DB`7$ ziu_;vHoo^R_taYpjj#bG>HLjid8SQ=O|hGKjgd+;&9?KAFF$1`$|5Ni#pNDyu*kmd zKfaosM%|#Dlg?y!3 zO8fVw63>pO<3}`yM8Z*O#W=531lJtY02E$0NztKRJ|bAMOKPvgH5uBCK*Ei(S>Vl&H3N_%BfNV^xG&Z1 zfH!!?iK7pV#XZSgw8*Z#I|DKMZHl+1UCe@~H#ftT=v&%bkb2=D3HKA5-sS7|J}h8T zZ5nyh{^ff(08+9vdIbDm`ooe^_D<8AA(g|^o5`s7^pP2FYI5GLhYZM~&97%%X+N5Z zgVyQI89kjXWG2>V)mM}&12p>ZjU6XIq^-i}p?Cwvi+vODTyG`!c|kV{bMKH?_!!7H zO>G=F&T7e2)o(n!Rw3VMynent%w|O>ws1(LP@uVuSswaRf zsJ*Sh=g~(xYj3^)Gr5JE^(#}lUPL#%E z$^);EdVz$`v5c@VJLojs-Vwum)RZCuw^2lH<-$`Lcdk$9+bJbfGUz?_v-jmw#WbinP)(X=ME{vjEeSypTx|#v&thE|RCmtA zr%R8|?SaCY?QKt}zu|?1c?)=oStrQ7!K+xQC{zyS9Y+7QRE|ow3 zqSyAFGc~A|kGJEfQrBU;yd=w@wjlYcy;+(i>&-og9kOEA_fCmrMjuA)QjEwd(NcRZ zAYa5xm=B5?XDuD!WcQ`ti@pmAV^)0H7mMCIehM0{eRG7D_DhzhF2^D9ycq$Am(r!p z##wrA_cE3#C8V>71hwbs0=*#O8qhJSM*O1du6;9NtXYE|X(m84a@{#^i>&!czRe}K zKvKLBnP4uRL%lDhX&WaVX@g-`yj<$M(~mFEjy;iXUGbbw9hAFCTchWK(2S1a38+)& zq+RhewVA#PR6F{1WY*V>@drFTw8RRD{?+jyfvY6mS%x5y%n4P=G#^o`AJhbDPwux` zUDB<#a~;gJ742l}e5_iFN*H31xxqF==|K}ldA-ls|g`^fs_bG34=0KjBzDlzj@6T9|!)%{-8c4NMwBi*^Sc{t$rJncJ%Fu7GxFR z+n_mIldR=+5^Z27{}=elZkwQGwk`I~C5138{Hel=IP5Th)=_p0FU{5ZDLFt6@jYo>?vi{a#_!X}jpc{ml=C@_pQZ#r;I`-6`Sd6_~D^X}3 z0)idEQ-NT=Mux7izODmP9BY~TbbfEqpW$1G&z%Vswq#);J;u9D z+xIbPTj!p$PN3fN$*UvEqoE1CFIP)Gxkd#ST+BBnR#&8pFHTQ`7rQ^NE)P)J&2E+q z8z2mUTX&-8yLyqF!KZu96(!eRZ}2v44{{p{sarp!*P$8Vs^FJrOULmaT^I@Y@2*9Q z2Vx^pn}^h3D&zM=>QH1GkO|Z)xCjekyujP~BRwEYCs6Zw_f<9r#_X(MSKr{;oB77v z{AJ*7;V*~nzW#8b>+1&PRXN8CCHptJ4g_*17kI2U9G&tMSgO6{I58 z9^~V!LEUIdNU9-?5p&R5%R#p}yOkDQfHqH60Np5&oYkVvwtpCsl9EB$7b8?bunYP#Tw+J z$4H$Mi~J_Lb=*s{Z5j!dW|kZSEJmr5%US?o+}*6y`)Sn~zM)A4w1!vLh&aR5dzR>mW!>;&wQ;ijK`#*yt1QcLZ;Q`1?(2^RoI8fI8{!iEA7t zhc|>hN!(IF)Xp({c2QxtsK!;rKa8x_Z=@iSse9xE{At7&3Lj+1yoVICim`?x!7Sfapr4JA8%#69u#p)oPP>YnA zCqxG_zzU+}${NvlE`TbAUQlF0`q9Od_ME`4FT7%NKtx(KOnmO#tNXg~@q8_(b~HdE zeRd?;8ryo_x>7I2CK(VVyl4MP&pwQM(|m%-zIB`o5pY`#B?u(xS4_u;(=X$3YQ6GZ z{7s)EW;c|HaOCtyxerFHc)GgI-m?&rDT+9u3h)3&!WtQ}2$+jlgO3fRi-0Cz7(HR` zKc8cg`z0O*)5gUB#QSqBnDK_IFX1~hHzda22bH&Ja}OO+ zR;ddw9ya)=!9B`OJZ(FPup>-h4ahOi!%6MDo9^RjD%EiZh=nPdIgA$ zhmR)w+EhFS*)bBGBA^SXdMGA{LB|~3k|5>qtSv;o`!Y~Wc$w5phx}Vxw6I&E{6cXX z<;$BeIm6cxo^tQ3Rw>EU>TZ-hNtsGmCW=^QJ+@<9S#STBwo~~#8_Kv@Dkh^2uCJF| z#OAMWA1;#oS1&JAWN#kP|fJjDD_X6UGIN!pd07YrD5Lu4Sz8; z$ZzO%KKfOIVUkaWdVc)_6)mPE-!Rd%R;1Q#9%sD0n0K~<{nxrI$Rz6Cna-##?|h`%D@gBC%=^0|d2rK}mMF&< z15T}evw6?8m}s}h;XK%0$=V0qx3fljZrbLtI!7-FU+dcz#&=`dM6pj9?MzwHx>$_N z9gLY9@w5X99N=txcpybMdQ^xQ&7;^zy6CI z$tVW~#NaIBfPer)la=0FWC~-LGT4^oOcDUS{}+&S_pFno;m*r&`P&m^qn44K{jR4+ z4wS+0o}J9nW8ON>Pa(`)qRy{GxP<*A-k<1lBN(ATIPtD%`;t35iNW}{jgOCU6pQZM zyH|W&5M3o7I%rmIzglUYzk9opogwQl8)@b!MTBR6lPZHkAM38RKP)uzK{|oU_iNIr z9%j0p=O#|t$uV%yet&Y*I?(XV;y8U!?&v5h@Fr%>K_0SGjf1)1yvqL4{%wG&h+Uo*g$wgbr8 z{&TkVp}e-d)WOOODwND$%+?Q5!l9$fOtL32hZb6_t^zjMF1T{G2BCj~`c3WL*kxxj z4uR@c_@4;&@e|?^Q#aR z9C-ohM3LWj?D@7Q-vbIfdStJE&pvYXf(O??(?n!h~x5C|-;o1EY42XbL+ znF3o&=go4a}~3t9P~(~LE^3a6cC1PR{Qzn_NVJV$bMF&Y=$EjWk$rx4c4+-qx0!g(-7<|QsK%H z2cJY5eAo*%3SvK5L`m-N+KO3&$lC9uE%e!4VGaylOz;`xJ6jp$o*KNqn7j+i3&=PA z*d;*v-?5#ec7l$Et3sIaKVP48bnprC1lz03 zMgV9nY8`OmI?#8q=p4Hf;Twsro=`3TSx;yLT_ku^ba15tZ7Gxi{xXjvNl4zghb$v# zaZU9k>dpB%ObTE+#bK|^KU%hJn)$9%h_nj$1RdIsha#g4FD(|~qSj)VWwT$`w zePK-zsiOu$GTQ`aV`H1=PRqBSKKtKOI7f~DLbuE%FE1pS?qS)4ll@@PXZ>I$+sfYe5+0;*$3nkM5}>@4Nc=u-=|&eY)_|e< zdNS90^s8%B5?0pYyp0eZpT`b^kcC{iNWOlJIWTll-FJ}h2V6@Xwx}rGdhlV&kp>i0 zsU<;IpI!kn1AN0CpIf92d~kroO9@Noqm6`Ry6><)&j}qwJ>`7YDP5xkR3W6978O>} zQFebSMKGJ1p_70D_*}ZQhJuZxGQkrGwxF|nC5CUrFwg$rP9ZY9-Sh|_*fr*|KYkq_ z-vX>mQdjwm0i=C|G+C~OZfFi;osvP2fmri-;NBDC@q?7SVTHSpDRpg3R|3L$vY;1Fft~@6~h9cm0Avh=lzgGkhJ#JFwb~Szx4y1qk)BsXH#F zzQ>!FH2o9C4udBa!}>3VjZ zH~YEm`IL*kix=sByZeG%WqYz?%6#DN#vG8Bl%9`xDlQJ(Mts_1*o_^>PLJ1LC;E^% z`eKkf5zQ^aYF>>ZIi*Owf}2L{kT3mj#=V{Vi(qUN!FefU~qG@Gl4va#Omb_PpRgt{NP1=^4Ejh&NL z*P`TP&t3kDaa~xJ{hjc}|J9C?29@K+i;>^o;Yzyx@e_lLec$Myw%yT@m?WK}@_LcI zOl2T)&l{j6uSQMVm7#j@7al2TpS3KooRugw8I9<1;@=z6cHXa=s4;S?72o_yXBtR0 z6uae&;TI~#qq58D-@g^L*qL6L{SEod@02B&tMmQX(=3jAwxU-CRR+$lz6CZj1Q$4+ zv@X0UCCSdoSxpE_sZe{$B2Gfvcx|#}7|U9OB~6cpWtSk``qc;dwi#bL=5CMXbE&3u z!7*uK|9|LQ*RJF2w{Y-&zKVH)kW~){zHkzbaclXq^}~gfphDB}%Dh3~dHhLvB2Ev6 zc$)$x*F7r2vIwO)|)HLv_*!&Xjy zW($=5@Mq=Yrs91JXNmDJvD&W@CY+^R;Xbd+%*^YKO*);)(c^&#@!-;L{1T7lhxj&I z@T|Isx0CfCE@?(zyJ3wt_QPfsLSy)O7@A0 zaw46!oL99~%ei*;6L(@X7d-v#-ey}7Cb5hWQCAtwrdD!g5AIwp{=9rA<(hzBixs{* z>KV|p#;zz%+Q)yXRw(K>z5Fd8z2X_KP5x1z4&bMSaV9zq#Vp`-6qXj+=i}K!`yLStnu#aQnP%1np z*5_M7sMYdepD+GMP_(te%p=9F|3oY#304j$b+9AxGzdyDGe@Py!d6k?$k8_T(Z|{_SHKQ1v<-WcNt*a5O;9k%CG&k z^z34<=&w~1p2jx)oO0I|`?ctDx4lwZ*yR{V&~=FITh(r3hHlNV(&*FV=H?>EMOe=w zTj`ssw~~WYym?nFW5)fvQBDTCeFfL$+(*jZt#Y)do7=9qQ zxZG6T!(YJGg@xla8#ytvB4ZT`q(Q$q$#XRonqGN3(v0$@xe5kp*!Fu~xr?C&1#>a^ z_)SQ;;g=c{*0y1@|Zzqn6uXRrd?wQ{?W+`W# zEhMbCK%X@|bM<3iVAVj)+-8fYNDXDb6@^r9-mu9JIhS>vW>CG6eR_~rkT$Q%Hrck1 zw2p2!+gM(k*=sw^F=+dP#fBTa5>CTM!{yW_wPCX`BO<15<9~*dIXX&Z^bWntBW~Hd z*OYq+Rr#0N_^;wYe~OA%qVm{Vib)k)3qded^2%z`M*>6Tx7lU_Md**QV`z((w`xzG zm(`xs4vd$cAd$1@kdu3EB7q+8FEDrV)LvSybMWV`w&aN*3k z617uDs$o%j#-aRA>@3rW?<@U$c7^7G4*!Eq^kTBWx}9aOx}Ti?BFs@!lIhD})$*y$s9R%cAfra_!Uq>r38I6FXkJCe zokoNg7*&_gEs;IG)cGn*M@~X)Y}&PD{wX?L8Ll%3#7N=C|5>^+mxX- zEUpA-4ndp87Vu+YtFQ_sDm%TvRnqxEKj0SAX7A5Es8Lgj5TDUmU;*Lba^=_WU3OlL zs`xGU0%yw+sxd~zvSzhI$4`tOU>atmAG>s1z=fx$F1$7M~d()DbGi~Qt4 z{=EUoPZ}^W+myD{){~Mb?C`&ZQ(yGBwjwVvDWE25x@tygM)Libs=T_8X-Ma_-Dtbf z%nmYb1A!7V1<2ypll=byitTrj&mNAf-XnS7rRybcUZq;-##rx~1~vdtaJWWYl+n}E zvn}+KUW2Cu)@G%3c0MxxnAW{}^|_als=oG)2iQ4|=PBhco(#ELjRltxx06<_WdDV~ zih7K*XE9+s1Wzs$SKua9)Tl)oKgy3@FOy68d%?6{tbHH_9#RoS_|f_J{r z--sWlUw}G>k6_OEiWFlNY@$qCiSRHizaf;6oSI-+&g`w%xucEAlk$fP2M&q>i>5~} z)de%crp%YC*p`~3BFK5REf(iXx6aV44x@ZJ#P8;&>Z(q~jp+f2%3P&0I?s5(*pa6= zU)<32=-w@jwl(f;#FU4>-x+i7hyhwQ8>IvP384v}h_|bL3z~a5kLQKAJi`F9?DZQ$ln8TAFd$3X}c{2X$i?H&s-yHgVkBm86KVn z35!e{`gwPs=%@A)7N%n3V6SCzwSOhaK1O?vqZy>NcHU=ENPC5mw*YVj8mx?X2%p6)pgojf3y+gX_@p zfheu4DZyM?Y{gWOQE6LKjC}=^x?3?EUj9nB;JPD(={HlA4u)dV*8x`>ub)1i(|(mX z(fR%gD@=S4LR(0A8CO_2y9&egj&HGILlNS3bYo%N@ zri%x)5e9WT%2SC+H)X z-|=d%B*+QifxFN(RZ_zEK@Vp0lizSiZZ@B58NCMb(~(+g!T_oc`RhP~6KnTrfy>H{ zH&(DIf8kbKe7=r&1-!Ap@v*Fv?57N^t%Y{C$XZO{hh)|tK8qC=%H;hkIWM%A^Sz_SQ4gk(O#0*6j1vipTIaOs8 zK43#K_Q_t=c>g%Rn%~?Y{=>u|&kxxA{M`>p*n0wK!r!{|TnXB3HVf$&OZoy~l>gE# zImiyjuKw!am-M3FhrOHe_inQLv1_-@2t2>$&BEEWb$OSxU;|V#ci2kurU_k0j+MRp zs8pZMR51yDr`CYAI3GiC0MS0TidVc`Wa_)NfLQXxOSYTA@qJV!r4J4=*Q#Fd8$Bos zVkr4DSwUDbSm5ngNme0>VTbC}E-K8T)jQmv$$v)HJCzdmQ$F)q=qLYp$ds~V7vge+ zMrg}7;x7Ze#X`Ppi04=C1NcPVbpwa1&wmwqxXTRTihv9}W>&ydoP$R4=OVE!nz5d^ z7Zt`Y51q1wBv(*O3S(0CNOZXQ77q{Dhm{duF4Wq2^*ji=V4Gyoo2hvWdpkkCe4oU< z=xchOK{7%gk?%4Ms1G<^27AyeLZPXz0#_Cz;mzdsBB3h}ztqWdT2H*iTOdirSt9iN z58fIM0)DY}z5a!Y@xXAWC=H!E9>?vmaAB6BjpyDvflspe`AlR0X_C%XVwq<2#1+L% zu_9wMQ&%=VbKz^ZmMp$Ymc;!grT4_RW6}u{`%j)MoG{<93R9&_lxA7&kQwR0G21+^AYHqQ>@!gP|z~*S;C& zZbyUHsDC@1uU20go!rsT+__pzXLt4i^4|iANR;j?+-0?^Bd&2%M1g99Pu7sG;!Q)W zcx}^7%XiRR-ph?8R)!+>r=Q%kA9Ho|w)2Y*(q=Tv$i;FELcmNSiZ+Th0^(DF>;c4Bs!ZTDftcew0}%DMZ{Q-baRJBgmL{G~P@>G`IqvwnV@ zH2Isjq67|ry>5Z%QS*iM43qwu{_U*1n`A5BAwe!jlQ z+xV30iGj&Q&XYH4wu6%K_NYduIMdG?JaJK48Yj^g8Yklrnm!etyP#@t=AmZ|HEcqw z$kDCA+M}g>`A$1ACGJxe2eWZspP&{8fMneQC7T6ATGwL!%-5t4v?zfn=IDL$Ob~YU zwI->xIcFG!{q9c#RVZ6D4GUNE!83zv1J>=$uT%@y1!SFa%e2w8^V78d4D#-uv2|yqZ{W}70T2$QVU313&m~l80 zk4$*_Ux8I4QY~7pc`yZeM8)Zt1Ioj+hnSQkLa;b6O3ezcQ-tNiz5o7F{0 zo$yT>e7a~p7CLc5SjeM55m6=JUyET1iWPr^7;jz4j`{JK+z=6;giF9Q3(PVRZx#?% zyMwDh$%JfaX(-41h`ku;Zg?GgruKDT!lLkqlY1vXI?*~hf7x=-^Kgt;D+X5b>dY%i zmGu9%I#VmThPY*5Ctf(EX(2?d@PjYf*DI*5VRP3Yl;8b#XwUfJ>{8ZgUxh@nFR?dLi!GX97UhL&}~B4KjoEBDQ(Y>FS- zB?qXOB5H)tEebH;0@RYU+G-7tJk}nS<5D7MizMqy8fSC3xet;}-pGQlDZ-+7bECeA|4E7g>_PvCcO}hSF?h9z!&}ioh)( znGaMpIy+CDhmGSI%alh27BW3Y)*^PvhSAU^1XI9&!=i8)i)fm1o&bxS2A*?A*Ll9I zex|Cs>BpH;Ds<~H@JY#GQ)${fL(gAFIngk_OacY-DfRd6t}4$B`R9f2oY&7xSSpPg z!%I*Dki14NNgK~T7BgjI4v{52<*=V^UyU0PXLlPn{>giH+;4vzR0-(!TbmKaaL3w<xzlK>86DLhvuEXu3hP- zE^4f5C0_{QLZu>{m`zOL!J<@>?>$$Z#;)?hoeO2|c2qhOovS z^mDOHazHiRVy9WjfB1Ywz3DQpIRw}Ra(4cvHT7-#8LH$T!GKey8%EUD@6PmWY`z5} z=l4(Jww!2r{@vNmSY5l(PDyIxN0mJIJWC=P|l4JXZha>4e8fJS3Y zsF~J}uD69RzX6`|F+(0#mLHyo=qnONwI;QDZ%+yjI7dBAq6RLoHY?aAJBOrz7iW^EQ0kit!6;3#@8*MQn=$5%5q|NWmbKjQr#Hb@K2(D(EsJ$Zw4n7h zMutd|&a3d@$tE@84WZW>2G;;!0x;tNUz`)UNt1q;Sc|(AH2vLy$Ux!EV!yUvixfJ| z(#KkMg+Vi}U~`5(Z5j^YH6u+iju=c4j>&7URKK$a6M0(uM~tW8FkpY-?ucnb1`wL;=3h z*lgXR4rvmM4AAnnAKI&NO%8Vd#H|=G<2nbH)vwwi$Kyoo3BjOo>;1DCSVYop2Ecx9 zdQuxJCgN-fwITET>GU%eWtap0YZ4A00smk2J__Oc2z_t4?N~t!T=SlGcKk;5&Bq^E zx$MB7Qc7A3*$!4`c0XdOBr1Cj2?iy&953;nt6%*Yi#5FcXZ4s6bh$n9u`}rs{aIHT zW!@El8KRPKTs5{C!!I=-?(~U-Rxie@w(} zblTe`>-FHbYjKk9*;9UDzXg~`Pk4Qic-_)a-|6ytjj4@?S z>mJ-7*r{FzQy}n9zN#?KkLh|Yx`=Yw5efIuL2yh=yr10eif7USx%4gA3gbRHx2O-! z*`WYDcq37`lN=jx;jB zhL@kJ?%57?CCkD1WUc~7;!KgenWpLH3*=EK`5r+xB+wJ!R{a&Aj4hJ}|D_>RQXWbx zMjf#7VM_A9W3(RHRZMQuG2bnrcP6*vxjb?$TA;OV{8=VmS}6Y4{V4#vlb(L_8Ivxh zoj|1IzRVz>Amjsp^-&6D7Iw_#1>Q;^a@rr;ScgY$?OIq(KKUeR&Kz|zV}sYvhA@?bu& zg~{F>W|!;04i56ETa#1K;C$NJ)1Nje+~IsnTSSvDPxjfX8Zh9pa`b#mdh;LDTj zJDhjV&b@fK7u&um?7Qh%H6uHK6o0 zGkKe^mZkWf!^;GsG#|~0`z_tentM08-yy|u2+x-(P-d>a5p*joWVw6yZsqtX98(2S zKX>i%s#y^nf($^(3pfUPcX!t?zS*i|lnX(XAqXt>p(vYWcvj?N~imDa@`u}{tT~h%Pv9W3m8!2fscz8 zr~7rME@X}ilw{5u56>moPhqJ$%;LKqwrKz<5(Ec&X0~{zp-R(*V-)h5t9#r6|(D*vi|E zx$@#ILtehXU{jb66g9ChieSZ$~FdbrBpoT+^^LSSsyJ3UO!R;JC+-*Bk z2}$Pc%!Dgmm*R{_q+Lew5Jz%Gd`-FLSe<1lcr6q^L)LYLeBbE*sD|=Jl13;i#bYA_ z1HnNXZ(MTM;l0U5AFH3AQO@y_;hvtXpLP`LwlU#&)SdpWld;G6C{FGY2I9C)jj6G* z_R3Jfy+kKeuyQqwuakQ>Fz_6FT<@Lk(nSB;IV(ME%DGJ`P;{a(<1i||E>3tphy`q# zicdwU!Yk8KpnyZG0=iGxq49>!;FR9=+i2TdPFnfe2%M0(ODs6gs5*&`GqLL*!xlPO z`4SML@6v_JnrSvE}rOms!8eGtC{&@^oqjWhb&EougE5m$nL_W4*8hPLzZc9!sq z#^z(^eB=DKTFLmTt;YWWg)k5rP8;alG>!Dxg5`tanz{7&nGsZI7FZ@x|1um?dS+kz zRL8-zfk}&&KmLsFNF7vVTo}WeJiZVuWxKc1cII#-mtUa(LG!%+rc7l}b#iMUVy@tF z=#rbUZzVAv*Jpg326D#Zd?oT}PxWhAq37PG!XZmPZL6|!a;jcAsi~1ti}^oVu1gD} z8dq#mvlqx&kNwBrL~oQkc~#*-t+%&d;ne6xMdAG_v0f}h1i88@lWrR68bFw_*jEOv z%8B}vACkf*GeP&WYlj{^g=P$cB-G50H!QY^ z>EkdHA})7Q2C)V>HJDwONx8oiXg9ZXMrPP)(CJ*r#4>x>*nWM23St&gz*=)ut-Tw@ zkAolMF?P`5DW_9#gS_NIwD5~qgMI%vne|)q3#{eBmoCt_5b&w2jnR4%9`v|m9lfO1 z7i65=|IKAN^Js8+WJDR9%cS72?CGWeZ7=~FdwqKRJy9SLg2{#l`H`C-MVF1@M}=Iq zs)!Qf!M{|!g9DrgNU*ont16v!;&N>CKfQ;}AP!~ayMy`ajy2h*Ol#loBF)wbXvJP5 zq=vf5=iO%nx)@vfS=R3D^&0PGf z<~yFMt9Rt&*E;q$Scj_GdLuP^#y@uwdS`-s3*R{#7d_eJV?)_{i#$5Ef z3!0rWA5z``K@k$kF@OM%o(r@ySMOm2Kl$WH@LxVc5r&9wikeTGVnB~iicnDqnCagU zCFnokln$0_7_o;o27BdVkGK?>6fYG_$x2*mr_?{V$L;@uGE&C8%RadMzukf2_}4Ul zdzlP7n0WfH+7}mi9?8?)xwCWwLMvl#%|MUPn|%u9116mb-!18oC-~o&2=-Fe^FEUr z`V{61b!56egZD5~NVu%MQhTonG0^x|K>lyn<-r^O;Sr=Z**Kf_(H_5kuj^T}n!U?p ztVi!3ZtC?jzOi{sBBvJffX4aCH+Z>cc0aq7gV5o3w|D~!Hb8T+SF5h)#BNIGt7z=T zz-dFju!_xZhUI?^=crsZWjd28)0TfLvmjGXwDI-`~ppVaHV6+axN zu#*pya&TE)9@~9Xc9PgVEOa%#&t@*Au0OZak)iK$zks(n4{)f|G2sfijLv7+(v!jc z5*M0^IRpW%j4#_Jm$vz z-USMI=~IGdLeh05g{j$F5A&##1I}#TMbFQW9J4F4J$kuyOc*T;l_NZ%p?_5C?|xk# z-OumF4outVGS?Tmy>HM|YgXqv`8McbgQ8}u&Pq9r%2NE+UTx5BSH_Or(h;$osTfpN zzSA<~N5F;7#gW27)1oC6dVIIfyLQ>9{26Unu4o&XsWNrOAgm)lTs4-n^8Z*X^zVbA z2xHBFhNBcBnnSlrTqz#>83lqav=jz~2PU7v)eDU4&zr;-x^?K(&2b603_bBSz8bye zz(@AS94Ad(9({O4$S>|qoJyDTHOiB+8;d1t`#G}o3eP?)lA4cCOnoEzF1J&U$Trh!plCZ5wqt%z} zaNisEP%J76+ThB9>tSm;MB`B?g3CrtUI8M7! z3LIjf2R*G==Qde8?ZpMjJ)Zz&p@L0&V)FFqoQ>n;?Okb!-Sn=Of z)8~hdnTdQM2H8VuCMwxIcK=UuVU zahD+dYeI&cFV-MoO}YH#6`-BJ8LUH-p~KLZzn9D~HQNFe%(*3=JfG}lal4F|BE`(# zqMQ~~JSgAr5ZV!3)G0zmTzQ!xtaBy6u`b`plaoFindP6M2_ltnD3S}6L9y)U0i#la zv&0iq>c-h{jZ`Vs82W$w!)c#Vts4m?sE+ShbY)Ay6rx& z)rHngt6JD;|r56NsQ1L0{;Inl&;>C`pkh^IGjQn%!Ak#y{#y@R(@X}Gx zx70qli?OmNndlffzC9&70vi+pei=BFVa6VtXg)#4VluexM@kiQ z>#M4*UBOBZ@fQLjEty}IW26Bq$*xk{W$XC($EYQe)Cc863Xkt%MVo9wh-DdJ==8!X zU%vUq@GDgSDST?)4^a>0xu!&_ZHr{6NJ}~oI3C7~q2<_tk=;x&&(jw~c9Z1;(BqTh zTOmrnQHC~inT)2{YX@m#LQQnaTl~GVcbV+Wsf!r>!ULh=%UcmCy8cl8lTRIV?CQp= zTKTprOt0ZLNB?Na1>Gh8Hm5Xl;2fs zN=}igIBC=VWj>*I7xf{`B9NM(8)<{N2bo1VMJRg$ml7n43w^qsf$;z&#i_;2n<`hi zaTnyAZhU^;JRI=Z7J;7Pq0FY`7_Uw~m6Jj(G0|2{9+6n29)z~6)p@uv_a$L_vi)yZ zV#cDNGWjp(6JQE|j`>GCeKN%9KFIDT*-3IHi^IW!1Y|Lkh_tWplLQWRdEinyM~fvsONKcSW4pGa##TZpZiG{m&yI^{Kn>yKWBVfg zwBsM^u;!&tE8MD`OSuwWMZy;xz4zBIicJiyqiM}{w%w;E|AV_@&^p7vl>dLD9RD^d zIU>QU`|-%+K&?gFF42jswtHqfcLZ5~_hC>Pu6~a`1G)mFC5+obnw(V@$ z1ehE-Ebm(jEp*$4(T*a?z!x{Fe+m8*38+0+xy5a^V`ubnG;O&mEyV$Xb^W*^VvkylZNn6dqN|EyeS=%hDDr&_h9x%MSSjayoc zfd6^2E{@c%V+`Z`tUY;XQek=0^{v)DB19WN8sq%kx$^oE;~G9BeFJDB>;I|l%HyG2 z`~DQC6=^xAC=^AKea#w`eF-T`$SFIc(oh(bt>f6ThAdgL@7bx8CB~2~29s=M?8{ij z^8W78dCqyB=RBY1egAy_=#$93&2{~L*L{6AuqASV>@Gmr4IICn2iusdUs&pq6XoeI zoZ>sWpUo9?zjNhkbLEzZ`Je7Nx+w?G!JVr-?b4St8t9xdH%@259qB!}zNS}92PqP; zLfbcC!xb-wSK1SG~eJgy?NNnb)B-VAcs)ur2w%>LKceg+pG02?*j zU5}{P?u#?i8jd}(rYKPPkO|FO-Q&+7qRRcQp7mY*4!3C`w`tf`YFfQ^+G(uLDh$9r z=UI_XSsH^n;9@;0r0x&yc@~10Zltv_k;SUd3~^Zd=WAmB{%?YhzigORbZOC_vcnOtqcenZg|bLzdU0j@}O<=7$O6#rFU0(eVDd9T!& zf0tMJjZFXE@9c+ew`*U4P)0h}K#H+hJ*8qn=~!YslinHdaOJ9R0!sWDiO-i7K=q3y z-JmHyX?f)Fy=9#*JvOi6T6)2|e{!YKydp}6lD_%78&3i2`L`&$+_-os<-3Q4Ci}Btk zuRX`5v1?02pm5@Z;5G*-&TJ{@LD zy5o#P5TW%!rAR6!LR332UdnDw~5yJ-uk6*yPW8D$YEs( zDcy(DrJbwwQO?6`4Q7riLoRBtQY__4u^L}xs7aV#T`GG7*ck!D{^5u0_`Nx^q*h_6 zHOHCg+t2liY3ZY2>s}=FNZcBT_MU@m)F78$^ksl11Y9Xv!tOhj|BCa|hOM~uz2I|5 zC0~E5g=GUDeH_9CSt0L~HqVJTBM^af zm)qH2WcP8t#I1sl0|NBK(=zUOvl?`G(suB&%9uV7-rlA*MF(Go&0Pc(?|Q&kGCqD) zfC)CR5nZhJF-E}CTb)l>nl5kxqv|%20tTvGuc!CI)tCRG%ybcW7gEcNquQv&FeH-K zckWA1#BEB)NYzo_bQrCXsIJOmvh~76Rt4KYz>b5-k?PAktETrN>&Ni+9rh%7A8KC2 zb8QWZc2})uk~J6`@U33wg+cQrB*Df@AKM@Z<`)+F-487Qs1V?QYc{8SX%DzXwxT0p z%k6l&ZXm^MhX3V5$-c?m+qZCcgo|(zBj~2SZ3&?c&1-JQ!C{H$X`hD!!w9y`^!9Vi zfh3rCBi2&14V$PB!tEAvR0i97&(m@PyG{YajazbQ`M1o&z!?q!v?V-EG7-x`4Lx&? z#|ht;?aKF?yp30wvn%dhMtD1W1aCEImC2{oBu8%W&Im}`vI7@Z5o$_^&OTga)GJA~ zND9aXhoPt}FhSzdFO)4fe-d-188PhgLVB1WsQF-t_E^LHBRxB=UH8Se&roetRGA)3 z5Za~38-a>&By~5C<(YSl0Ak}SY3kFrd^)`4jKl=PK4Ua>iyz{80fJTLjv((wb#FT_ z4E^c6z<1)dlifccSIn|rM{#jCXzd5NGBuMF9B1zYsH|EU9~B)c4Bv@N4Z( z|8AL`?(i1vxOke2z4Gk+U~@ag3xJhRRqy7c!Id7x8T%cK*}ryodn@#`Uyi3Q5=;e3 zl>5?J%_iW8bTQ?w7|ZbVt_vL8FuoPFwVw^>e(M2WL*;FqkBFF9T229pYLM`5HoNH` z1_}Qicpez#f&4T7Ox-&b4&bJ!`3H;)xU+%q13BQRGmqpbSocQSZllidYLQ9&iQ++1 z_tC6Ayzs5?v zj`Qb7Ql)U>Qvxj4CarFC?yDJ!iYWe z_Tn`<7A+HD{gZgF3`>LV$3%`bK5dNec|5z&&19;2q?)DAl%~Ic>qX^#1hdJgV0pDs z3rx*+3%7|(geRszw+kFw5{ur}ov`cu*f?pe&Qn%E$~&Iq3e|(xDa#nI0mJ<+pqYVV zplgX?)vJW*roIJL{|;st27rT2{)!)vtpHL^$=bkuLrIxgTb+q)7StWB*MgS((+ zEWF3N0Zf?OYOlny!V;kWRBR&*u})B+vw>>}5q^B>gv~(xtI6-`y!wz61Hi2vM`kOM z?gBdPT`@=J9bj70V#p8!L9A;$-kye4pw2ycaJE6gT#o?}I_^%H;)&0FpTTAVZjN6$qKy;>j8tWz-7IuDMfL&RO!VXI;*Wprj?I?z{s?&%ge<@`{V# zxSzFW4+2E0Isk1zy|GdQAW@(qzPf~e`^pFcd^RhOz$Ne@=|d`1FM-#LdgI#_6$u|y za5SghLpo8O#hq1=Uq1GJ>AEva8-<(la8}H@`~;310#lgq?@g--io&efcMcuB)skZsHWRwV=L6*m4dAPv=IXLz3S3%YxIfq*cmeVR zn4ZgBb8r(1l`Pqd8M$(-=m;=}Mr+kzq$KSID}(5N7XG_83EqRD5zrvof;?q^u@88+ zk&A<>2tj~LJjur7NkMZv=fJ5g<9%?1y>L<`&9!Bn4)TuMj^hH{GcK!V8oVJaiSGbg z>C19AWTCgscAKH8KU#fS6m)f+JkqqpBJFV~8`+Npe!F)=$kz~A2= zy(~wWEXp=24RY|H5GMP}!vGPzo@b(g#bSE|M@L6nqJ_sZx8g21a@sFQGrh7<04Ij0 z@5BAutnJ>$GI4g491G4uqNC#dUnuRbl2?*A98pB4f$TZ7rX4xq`g2gNZ_Mne2{%W? z>kZr#^5`=wZ{-*i`9fyRVj0BMY{?#wS!6sQyK)kxB|S%*S2e${c72o|0ZdSzt6iP@ z#t!fE+2f;NoM&WYwBzj4p!AcH@nd6S#T!Pd+?pAi(5avmcivX#^QW{#OCg?@O&;0@Se=Zo;KPX)7-apOoyPgUjwDLC- z$T4P&lJolv>%=+}V5#rHIHFq}xqpcHM~LyC<2r9PMq|Jz}%vuDpLPkEibTSqTG z3n;5;(Vu9f({~c2P1XmoG&hBDHR18%ap`&)+fr{LQ0UyI-oqVI5w1TL`+p@2_wbOo zbkBgP#b4CrH{|Rq5);3~xE%(mHg~ndU)pR=)%0l+-EEKCs|Bq<9vqlC{dLP_WiI3M)n7l^HRmAxW^xhCgH2D_5y9; zIv=N1KFfn~h1=Yf=?YSAuKnM`c7Q;es%?jPwDtA5Xl(8iys9#g4T(HpD-hRtUQ|b% zlwy(btipgxlvFK`*&F$PR8Z%NCg2-NYd5CQ{LP1C!jR*r1$N>jGYo7}(A_FH9S%&9 zrcJl2*92W7AmRqE?RxbHe~6Y*?kja{^Lblqc`u}#gXZV&Z!XAfAw&xDoI11)CYUQ!H zkPt14mDEkw937Y2Dj(?hel(>tTk6sLX{dhYV0jT989CqYh)39Pw$|2Wo9nBPYbI>j zdcvJtl+X)8jWfsSgxuF3)~w+b$Qvw))wxHsmKEN>vVrP zczHlKw%UDwHKnSmisWHnU{JOANez_M$lkVG$-QC4J_2ENDbE984mf}wfSWl`2twNi zT}Zruw?7wmU^Oa5r>3O5pU$`tvlxl7#K)(CT>v~C&~-OJh>`^4zFxR+!AT2O@W7bs z$i8QBaT+HXZ?(R-fCQh+6D>nG=h(I&1}#XyX;Oc4inxiJ{w^`-z4!3vBFh8i<>gLV zsix&i-A1e99-EfG@SCXX>Kjab?zw;e^B+a2lD6_doWAJUyVMsJQF*qx`!P%gXejaYD={4H#02`;ccofp@NO`sK zGuRndtc0s;%7W!vw$0hypv51wl^)(y+u10}xQF&E4^MJZQW9YUFH1R(5TOXfO))9w z=@jT-U0FADO-+fI79Ubl-a0W_*m7;+_Gdm8%n3V~mMS*}Vq#)e`p0D(v^>^2YM#H& z0ph~DcM9itcrtQwMq%FZVlWu2D3-AJ8tt(@%oZ(X&)kuwL29-poMWjbw@S_ALjgB& zUp22;uAb4>)9bp?QL5oU0!Nicl&R9y_F(t-;BxXg-;CzCnBBML;I{EkOGSym(9JO_ zoqu@%`-(qpK#u#K#*PUvf2gt}Jo#yVCu9Uwnvg1T6$6=5SzRXu)n+!jjT|z-!h87p z^R(eqod#Z`*RLR`Ez5RGyk?GmsYMvS*yI+MC|)i8+=Zl?(VbINq|0kkr7yG8sf!iW zYfx@jF3)pc%98tg;5ST->kK5d&S3}@m@LB*8@--QkJTs-?X7wKtxsGFm?wjaeY#pQsj>^v_{9$* z6y6IopBml`2}n6j-U8DUW5P|oqdYfq?+{+wi?wEZsH6o!s?#leybMs5m}`l6)2+1| zu$r*%3Ag8}j*7W60R))GyIF6o&X4vx6R}PjU4o$X1!Bk4)D#LFRSF+1Sfptspqt&| z*rO|Cz&YjxKSv~9Sat<}CoG__go7ZSQ zQy)N=4ef$}K5I0(UVu)_VXy^OFjFywQ`zfu5zTomO*Tog-T(WZ`ar9vAT%SnVR(qR zwLwG*m9N<>#Oy75tuaV7kq2+hXMj6rzp` zVv}o)s##3U{V?u9DfN)DB4Ok!+-2!Fn>w?hFhRjR{&WC4g{1cR9!Gy$D3??zl)F?5 zlw*25XxxX}P5$u353ivv@vX%oqu5sT3&>Qw$q zAFKvutzceHGnChd!-3)zubF(`9(Sk`e8ulrpgLjoFP-v7hjVE(FLY&T+T<6!JvdUc2DrO2JRYedNCg3e5`4I59Tl$7V6o_zWz#kd})S7ZhZWj7t&C`pfRExXD7v`Os6lxsGD7UqCI_oyx7P7nBcoBKV+TA|Xn=(@Jkk^f zQ~HqSQIm&{w^o9;z5oGI24?RVOc?NBa;lzzAh?zqEM)~uwD7OAlOKX{dHDvJkdd2f z(Vlb#a#Q8LAR%P1M4&whT?EF2XP(CfNqS?kf>PXo70C9r_nxHXdi&VS$JNSHszzXSERFt!ZTspk8 z*PM#F1!R=67T^!AcBadINKpxE#N#bt?Q`+`Woej!$io40>jJD~;+9A~&ViKoT(a^? zO1r~2HNGOX0Q$vg=D?j-jg13yN$Rm;f&Kmcxm)&q#Tlge-06NNf_(s+Ts(4-5L`J2 zErOA57nltkRoHXS9^f4Ki~2eVj{{kV%?-NFAb)lgEV1>NddQTNl&p8iZ5(D{VR4&> zyfVWuL0IfCuu3-uyDxGS78b7b_0-gdo>6;xnSEtzi#*kq+RE=aJR4P+a`tBR@rS?n zO<&gbrZ*dAR)2EkyzgVZEPeIO9Uo~4pWppb-+#=Ckyf6*kn@J!uLlbl!uZhHdpB>X zNX&bUKNgRxYks6fx!daM8q1{>pVDPBy12MFeL+g9xxT($uIE#4Z**8#m>n9OW|C)V zZhnS?gJW4!1-0UF@2CBqQawFAkJc8ggMxxS*@=anmUCZMF6wO|lbzDi(`Rr*0-ybOtlV_T7J!_Rb zWn^Jt!AdSbN$-<;Npm+nD~qSZkavbyt5t1+@9NTvjEb76hjZ)Z^$1H!#;B%-!q3vv z)495AL=$AOAK_oZVq%eGGTCi&{Q|r&d?%6Aa;`VWiaQ9w7%g=mT0D3lBImK$^7gH~ zub-c=sA$CI=4Suk;MkWhC*c;Y9USmOLuPz@d_uCa@wvIVlhe~3p|*V@_&ePryz??)f4&YSb`^A}ZC#=;fal*Alh zlO2J<#l*_my1D7@g)Pb)`#-ms1~ymh+`9M}5BG&q NxuSVFSK-!^{{fq-$;AKw literal 0 HcmV?d00001 diff --git a/docs/modules/ROOT/images/tally-exec.png b/docs/modules/ROOT/images/tally-exec.png new file mode 100644 index 0000000000000000000000000000000000000000..e24a145d09abc70ab36c6f036bce726e8410534a GIT binary patch literal 231859 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

>t>*+2Sz_Kd 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∈YQ8Q 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 VZVAzj{5LR4@tvC7A6e6o{|B=b*sA~l literal 0 HcmV?d00001 diff --git a/docs/modules/ROOT/images/tally-vote.png b/docs/modules/ROOT/images/tally-vote.png new file mode 100644 index 0000000000000000000000000000000000000000..7d270fce091298627d9c181c315415c7710de784 GIT binary patch literal 40507 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 dynamically, it is not always possible to determine which accounts hold a particular role. This is important as it allows proving certain properties about a system, such as that an administrative account is a multisig or a DAO, or that a certain role has been removed from all users, effectively disabling any associated functionality. + +Under the hood, `AccessControl` uses `EnumerableSet`, a more powerful variant of Solidity's `mapping` type, which allows for key enumeration. `getRoleMemberCount` can be used to retrieve the number of accounts that have a particular role, and `getRoleMember` can then be called to get the address of each of these accounts. + +```javascript +const minterCount = await myToken.getRoleMemberCount(MINTER_ROLE); + +const members = []; +for (let i = 0; i < minterCount; ++i) { + members.push(await myToken.getRoleMember(MINTER_ROLE, i)); +} +``` + +== Delayed operation + +Access control is essential to prevent unauthorized access to critical functions. These functions may be used to mint tokens, freeze transfers or perform an upgrade that completely changes the smart contract logic. While xref:api:access.adoc#Ownable[`Ownable`] and xref:api:access.adoc#AccessControl[`AccessControl`] can prevent unauthorized access, they do not address the issue of a misbehaving administrator attacking their own system to the prejudice of their users. + +This is the issue the xref:api:governance.adoc#TimelockController[`TimelockController`] is addressing. + +The xref:api:governance.adoc#TimelockController[`TimelockController`] is a proxy that is governed by proposers and executors. When set as the owner/admin/controller of a smart contract, it ensures that whichever maintenance operation is ordered by the proposers is subject to a delay. This delay protects the users of the smart contract by giving them time to review the maintenance operation and exit the system if they consider it is in their best interest to do so. + +=== Using `TimelockController` + +By default, the address that deployed the xref:api:governance.adoc#TimelockController[`TimelockController`] gets administration privileges over the timelock. This role grants the right to assign proposers, executors, and other administrators. + +The first step in configuring the xref:api:governance.adoc#TimelockController[`TimelockController`] is to assign at least one proposer and one executor. These can be assigned during construction or later by anyone with the administrator role. These roles are not exclusive, meaning an account can have both roles. + +Roles are managed using the xref:api:access.adoc#AccessControl[`AccessControl`] interface and the `bytes32` values for each role are accessible through the `ADMIN_ROLE`, `PROPOSER_ROLE` and `EXECUTOR_ROLE` constants. + +There is an additional feature built on top of `AccessControl`: giving the executor role to `address(0)` opens access to anyone to execute a proposal once the timelock has expired. This feature, while useful, should be used with caution. + +At this point, with both a proposer and an executor assigned, the timelock can perform operations. + +An optional next step is for the deployer to renounce its administrative privileges and leave the timelock self-administered. If the deployer decides to do so, all further maintenance, including assigning new proposers/schedulers or changing the timelock duration will have to follow the timelock workflow. This links the governance of the timelock to the governance of contracts attached to the timelock, and enforce a delay on timelock maintenance operations. + +WARNING: If the deployer renounces administrative rights in favour of timelock itself, assigning new proposers or executors will require a timelocked operation. This means that if the accounts in charge of any of these two roles become unavailable, then the entire contract (and any contract it controls) becomes locked indefinitely. + +With both the proposer and executor roles assigned and the timelock in charge of its own administration, you can now transfer the ownership/control of any contract to the timelock. + +TIP: A recommended configuration is to grant both roles to a secure governance contract such as a DAO or a multisig, and to additionally grant the executor role to a few EOAs held by people in charge of helping with the maintenance operations. These wallets cannot take over control of the timelock but they can help smoothen the workflow. + +=== Minimum delay + +Operations executed by the xref:api:governance.adoc#TimelockController[`TimelockController`] are not subject to a fixed delay but rather a minimum delay. Some major updates might call for a longer delay. For example, if a delay of just a few days might be sufficient for users to audit a minting operation, it makes sense to use a delay of a few weeks, or even a few months, when scheduling a smart contract upgrade. + +The minimum delay (accessible through the xref:api:governance.adoc#TimelockController-getMinDelay--[`getMinDelay`] method) can be updated by calling the xref:api:governance.adoc#TimelockController-updateDelay-uint256-[`updateDelay`] function. Bear in mind that access to this function is only accessible by the timelock itself, meaning this maintenance operation has to go through the timelock itself. diff --git a/docs/modules/ROOT/pages/crowdsales.adoc b/docs/modules/ROOT/pages/crowdsales.adoc new file mode 100644 index 000000000..37579211d --- /dev/null +++ b/docs/modules/ROOT/pages/crowdsales.adoc @@ -0,0 +1,11 @@ += Crowdsales + +All crowdsale-related contracts were removed from the OpenZeppelin Contracts library on the https://forum.openzeppelin.com/t/openzeppelin-contracts-v3-0-beta-release/2256[v3.0.0 release] due to both a decline in their usage and the complexity associated with migrating them to Solidity v0.6. + +They are however still available on the v2.5 release of OpenZeppelin Contracts, which you can install by running: + +```console +$ npm install @openzeppelin/contracts@v2.5 +``` + +Refer to the https://docs.openzeppelin.com/contracts/2.x/crowdsales[v2.x documentation] when working with them. diff --git a/docs/modules/ROOT/pages/drafts.adoc b/docs/modules/ROOT/pages/drafts.adoc new file mode 100644 index 000000000..b2c1ae628 --- /dev/null +++ b/docs/modules/ROOT/pages/drafts.adoc @@ -0,0 +1,19 @@ += Drafts + +All draft contracts were either moved into a different directory or removed from the OpenZeppelin Contracts library on the https://forum.openzeppelin.com/t/openzeppelin-contracts-v3-0-beta-release/2256[v3.0.0 release]. + +* `ERC20Migrator`: removed. +* xref:api:token/ERC20.adoc#ERC20Snapshot[`ERC20Snapshot`]: moved to `token/ERC20`. +* `ERC20Detailed` and `ERC1046`: removed. +* `TokenVesting`: removed. Pending a replacement that is being discussed in https://github.com/OpenZeppelin/openzeppelin-contracts/issues/1214[`#1214`]. +* xref:api:utils.adoc#Counters[`Counters`]: moved to xref:api:utils.adoc[`utils`]. +* xref:api:utils.adoc#Strings[`Strings`]: moved to xref:api:utils.adoc[`utils`]. +* xref:api:utils.adoc#SignedSafeMath[`SignedSafeMath`]: moved to xref:api:utils.adoc[`utils`]. + +Removed contracts are still available on the v2.5 release of OpenZeppelin Contracts, which you can install by running: + +```console +$ npm install @openzeppelin/contracts@v2.5 +``` + +Refer to the xref:2.x@contracts:api:drafts.adoc[v2.x documentation] when working with them. diff --git a/docs/modules/ROOT/pages/erc1155.adoc b/docs/modules/ROOT/pages/erc1155.adoc new file mode 100644 index 000000000..5a4c91670 --- /dev/null +++ b/docs/modules/ROOT/pages/erc1155.adoc @@ -0,0 +1,145 @@ += ERC1155 + +ERC1155 is a novel token standard that aims to take the best from previous standards to create a xref:tokens.adoc#different-kinds-of-tokens[*fungibility-agnostic*] and *gas-efficient* xref:tokens.adoc#but_first_coffee_a_primer_on_token_contracts[token contract]. + +TIP: ERC1155 draws ideas from all of xref:erc20.adoc[ERC20], xref:erc721.adoc[ERC721], and https://eips.ethereum.org/EIPS/eip-777[ERC777]. If you're unfamiliar with those standards, head to their guides before moving on. + +[[multi-token-standard]] +== Multi Token Standard + +The distinctive feature of ERC1155 is that it uses a single smart contract to represent multiple tokens at once. This is why its xref:api:token/ERC1155.adoc#IERC1155-balanceOf-address-uint256-[`balanceOf`] function differs from ERC20's and ERC777's: it has an additional `id` argument for the identifier of the token that you want to query the balance of. + +This is similar to how ERC721 does things, but in that standard a token `id` has no concept of balance: each token is non-fungible and exists or doesn't. The ERC721 xref:api:token/ERC721.adoc#IERC721-balanceOf-address-[`balanceOf`] function refers to _how many different tokens_ an account has, not how many of each. On the other hand, in ERC1155 accounts have a distinct balance for each token `id`, and non-fungible tokens are implemented by simply minting a single one of them. + +This approach leads to massive gas savings for projects that require multiple tokens. Instead of deploying a new contract for each token type, a single ERC1155 token contract can hold the entire system state, reducing deployment costs and complexity. + +[[batch-operations]] +== Batch Operations + +Because all state is held in a single contract, it is possible to operate over multiple tokens in a single transaction very efficiently. The standard provides two functions, xref:api:token/ERC1155.adoc#IERC1155-balanceOfBatch-address---uint256---[`balanceOfBatch`] and xref:api:token/ERC1155.adoc#IERC1155-safeBatchTransferFrom-address-address-uint256---uint256---bytes-[`safeBatchTransferFrom`], that make querying multiple balances and transferring multiple tokens simpler and less gas-intensive. + +In the spirit of the standard, we've also included batch operations in the non-standard functions, such as xref:api:token/ERC1155.adoc#ERC1155-_mintBatch-address-uint256---uint256---bytes-[`_mintBatch`]. + +== Constructing an ERC1155 Token Contract + +We'll use ERC1155 to track multiple items in our game, which will each have their own unique attributes. We mint all items to the deployer of the contract, which we can later transfer to players. Players are free to keep their tokens or trade them with other people as they see fit, as they would any other asset on the blockchain! + +For simplicity, we will mint all items in the constructor, but you could add minting functionality to the contract to mint on demand to players. + +TIP: For an overview of minting mechanisms, check out xref:erc20-supply.adoc[Creating ERC20 Supply]. + +Here's what a contract for tokenized items might look like: + +[source,solidity] +---- +// contracts/GameItems.sol +// SPDX-License-Identifier: MIT +pragma solidity ^0.8.20; + +import {ERC1155} from "@openzeppelin/contracts/token/ERC1155/ERC1155.sol"; + +contract GameItems is ERC1155 { + uint256 public constant GOLD = 0; + uint256 public constant SILVER = 1; + uint256 public constant THORS_HAMMER = 2; + uint256 public constant SWORD = 3; + uint256 public constant SHIELD = 4; + + constructor() ERC1155("https://game.example/api/item/{id}.json") { + _mint(msg.sender, GOLD, 10**18, ""); + _mint(msg.sender, SILVER, 10**27, ""); + _mint(msg.sender, THORS_HAMMER, 1, ""); + _mint(msg.sender, SWORD, 10**9, ""); + _mint(msg.sender, SHIELD, 10**9, ""); + } +} +---- + +Note that for our Game Items, Gold is a fungible token whilst Thor's Hammer is a non-fungible token as we minted only one. + +The xref:api:token/ERC1155.adoc#ERC1155[`ERC1155`] contract includes the optional extension xref:api:token/ERC1155.adoc#IERC1155MetadataURI[`IERC1155MetadataURI`]. That's where the xref:api:token/ERC1155.adoc#IERC1155MetadataURI-uri-uint256-[`uri`] function comes from: we use it to retrieve the metadata uri. + +Also note that, unlike ERC20, ERC1155 lacks a `decimals` field, since each token is distinct and cannot be partitioned. + +Once deployed, we will be able to query the deployer’s balance: +[source,javascript] +---- +> gameItems.balanceOf(deployerAddress,3) +1000000000 +---- + +We can transfer items to player accounts: +[source,javascript] +---- +> gameItems.safeTransferFrom(deployerAddress, playerAddress, 2, 1, "0x0") +> gameItems.balanceOf(playerAddress, 2) +1 +> gameItems.balanceOf(deployerAddress, 2) +0 +---- + +We can also batch transfer items to player accounts and get the balance of batches: +[source,javascript] +---- +> gameItems.safeBatchTransferFrom(deployerAddress, playerAddress, [0,1,3,4], [50,100,1,1], "0x0") +> gameItems.balanceOfBatch([playerAddress,playerAddress,playerAddress,playerAddress,playerAddress], [0,1,2,3,4]) +[50,100,1,1,1] +---- + +The metadata uri can be obtained: + +[source,javascript] +---- +> gameItems.uri(2) +"https://game.example/api/item/{id}.json" +---- + +The `uri` can include the string `++{id}++` which clients must replace with the actual token ID, in lowercase hexadecimal (with no 0x prefix) and leading zero padded to 64 hex characters. + +For token ID `2` and uri `++https://game.example/api/item/{id}.json++` clients would replace `++{id}++` with `0000000000000000000000000000000000000000000000000000000000000002` to retrieve JSON at `https://game.example/api/item/0000000000000000000000000000000000000000000000000000000000000002.json`. + +The JSON document for token ID 2 might look something like: + +[source,json] +---- +{ + "name": "Thor's hammer", + "description": "Mjölnir, the legendary hammer of the Norse god of thunder.", + "image": "https://game.example/item-id-8u5h2m.png", + "strength": 20 +} +---- + +For more information about the metadata JSON Schema, check out the https://github.com/ethereum/EIPs/blob/master/EIPS/eip-1155.md#erc-1155-metadata-uri-json-schema[ERC-1155 Metadata URI JSON Schema]. + +NOTE: You'll notice that the item's information is included in the metadata, but that information isn't on-chain! So a game developer could change the underlying metadata, changing the rules of the game! + +TIP: If you'd like to put all item information on-chain, you can extend ERC721 to do so (though it will be rather costly) by providing a xref:utilities.adoc#base64[`Base64`] Data URI with the JSON schema encoded. You could also leverage IPFS to store the URI information, but these techniques are out of the scope of this overview guide + +[[sending-to-contracts]] +== Sending Tokens to Contracts + +A key difference when using xref:api:token/ERC1155.adoc#IERC1155-safeTransferFrom-address-address-uint256-uint256-bytes-[`safeTransferFrom`] is that token transfers to other contracts may revert with the following message: + +[source,text] +---- +ERC1155: transfer to non ERC1155Receiver implementer +---- + +This is a good thing! It means that the recipient contract has not registered itself as aware of the ERC1155 protocol, so transfers to it are disabled to *prevent tokens from being locked forever*. As an example, https://etherscan.io/token/0xa74476443119A942dE498590Fe1f2454d7D4aC0d?a=0xa74476443119A942dE498590Fe1f2454d7D4aC0d[the Golem contract currently holds over 350k `GNT` tokens], worth multiple tens of thousands of dollars, and lacks methods to get them out of there. This has happened to virtually every ERC20-backed project, usually due to user error. + +In order for our contract to receive ERC1155 tokens we can inherit from the convenience contract xref:api:token/ERC1155.adoc#ERC1155Holder[`ERC1155Holder`] which handles the registering for us. Though we need to remember to implement functionality to allow tokens to be transferred out of our contract: + +[source,solidity] +---- +// contracts/MyContract.sol +// SPDX-License-Identifier: MIT +pragma solidity ^0.8.20; + +import {ERC1155Holder} from "@openzeppelin/contracts/token/ERC1155/utils/ERC1155Holder.sol"; + +contract MyContract is ERC1155Holder { +} +---- + +We can also implement more complex scenarios using the xref:api:token/ERC1155.adoc#IERC1155Receiver-onERC1155Received-address-address-uint256-uint256-bytes-[`onERC1155Received`] and xref:api:token/ERC1155.adoc#IERC1155Receiver-onERC1155BatchReceived-address-address-uint256---uint256---bytes-[`onERC1155BatchReceived`] functions. diff --git a/docs/modules/ROOT/pages/erc20-supply.adoc b/docs/modules/ROOT/pages/erc20-supply.adoc new file mode 100644 index 000000000..44cbd73dd --- /dev/null +++ b/docs/modules/ROOT/pages/erc20-supply.adoc @@ -0,0 +1,85 @@ += Creating ERC20 Supply + +In this guide, you will learn how to create an ERC20 token with a custom supply mechanism. We will showcase two idiomatic ways to use OpenZeppelin Contracts for this purpose that you will be able to apply to your smart contract development practice. + +The standard interface implemented by tokens built on Ethereum is called ERC20, and Contracts includes a widely used implementation of it: the aptly named xref:api:token/ERC20.adoc[`ERC20`] contract. This contract, like the standard itself, is quite simple and bare-bones. In fact, if you try to deploy an instance of `ERC20` as-is it will be quite literally useless... it will have no supply! What use is a token with no supply? + +The way that supply is created is not defined in the ERC20 document. Every token is free to experiment with its own mechanisms, ranging from the most decentralized to the most centralized, from the most naive to the most researched, and more. + +[[fixed-supply]] +== Fixed Supply + +Let's say we want a token with a fixed supply of 1000, initially allocated to the account that deploys the contract. If you've used Contracts v1, you may have written code like the following: + +[source,solidity] +---- +contract ERC20FixedSupply is ERC20 { + constructor() { + totalSupply += 1000; + balances[msg.sender] += 1000; + } +} +---- + +Starting with Contracts v2, this pattern is not only discouraged, but disallowed. The variables `totalSupply` and `balances` are now private implementation details of `ERC20`, and you can't directly write to them. Instead, there is an internal xref:api:token/ERC20.adoc#ERC20-_mint-address-uint256-[`_mint`] function that will do exactly this: + +[source,solidity] +---- +contract ERC20FixedSupply is ERC20 { + constructor() ERC20("Fixed", "FIX") { + _mint(msg.sender, 1000); + } +} +---- + +Encapsulating state like this makes it safer to extend contracts. For instance, in the first example we had to manually keep the `totalSupply` in sync with the modified balances, which is easy to forget. In fact, we omitted something else that is also easily forgotten: the `Transfer` event that is required by the standard, and which is relied on by some clients. The second example does not have this bug, because the internal `_mint` function takes care of it. + +[[rewarding-miners]] +== Rewarding Miners + +The internal xref:api:token/ERC20.adoc#ERC20-_mint-address-uint256-[`_mint`] function is the key building block that allows us to write ERC20 extensions that implement a supply mechanism. + +The mechanism we will implement is a token reward for the miners that produce Ethereum blocks. In Solidity, we can access the address of the current block's miner in the global variable `block.coinbase`. We will mint a token reward to this address whenever someone calls the function `mintMinerReward()` on our token. The mechanism may sound silly, but you never know what kind of dynamic this might result in, and it's worth analyzing and experimenting with! + +[source,solidity] +---- +contract ERC20WithMinerReward is ERC20 { + constructor() ERC20("Reward", "RWD") {} + + function mintMinerReward() public { + _mint(block.coinbase, 1000); + } +} +---- + +As we can see, `_mint` makes it super easy to do this correctly. + +[[automating-the-reward]] +== Automating the Reward + +So far our supply mechanism was triggered manually, but `ERC20` also allows us to extend the core functionality of the token through the xref:api:token/ERC20.adoc#ERC20-_beforeTokenTransfer-address-address-uint256-[`_beforeTokenTransfer`] hook (see xref:extending-contracts.adoc#using-hooks[Using Hooks]). + +Adding to the supply mechanism from the previous section, we can use this hook to mint a miner reward for every token transfer that is included in the blockchain. + +[source,solidity] +---- +contract ERC20WithAutoMinerReward is ERC20 { + constructor() ERC20("Reward", "RWD") {} + + function _mintMinerReward() internal { + _mint(block.coinbase, 1000); + } + + function _beforeTokenTransfer(address from, address to, uint256 value) internal virtual override { + if (!(from == address(0) && to == block.coinbase)) { + _mintMinerReward(); + } + super._beforeTokenTransfer(from, to, value); + } +} +---- + +[[wrapping-up]] +== Wrapping Up + +We've seen how to implement a ERC20 supply mechanism: internally through `_mint`. Hopefully this has helped you understand how to use OpenZeppelin Contracts and some of the design principles behind it, and you can apply them to your own smart contracts. diff --git a/docs/modules/ROOT/pages/erc20.adoc b/docs/modules/ROOT/pages/erc20.adoc new file mode 100644 index 000000000..2b85070a6 --- /dev/null +++ b/docs/modules/ROOT/pages/erc20.adoc @@ -0,0 +1,77 @@ += ERC20 + +An ERC20 token contract keeps track of xref:tokens.adoc#different-kinds-of-tokens[_fungible_ tokens]: any one token is exactly equal to any other token; no tokens have special rights or behavior associated with them. This makes ERC20 tokens useful for things like a *medium of exchange currency*, *voting rights*, *staking*, and more. + +OpenZeppelin Contracts provides many ERC20-related contracts. On the xref:api:token/ERC20.adoc[`API reference`] you'll find detailed information on their properties and usage. + +[[constructing-an-erc20-token-contract]] +== Constructing an ERC20 Token Contract + +Using Contracts, we can easily create our own ERC20 token contract, which will be used to track _Gold_ (GLD), an internal currency in a hypothetical game. + +Here's what our GLD token might look like. + +[source,solidity] +---- +// contracts/GLDToken.sol +// SPDX-License-Identifier: MIT +pragma solidity ^0.8.20; + +import {ERC20} from "@openzeppelin/contracts/token/ERC20/ERC20.sol"; + +contract GLDToken is ERC20 { + constructor(uint256 initialSupply) ERC20("Gold", "GLD") { + _mint(msg.sender, initialSupply); + } +} +---- + +Our contracts are often used via https://solidity.readthedocs.io/en/latest/contracts.html#inheritance[inheritance], and here we're reusing xref:api:token/ERC20.adoc#erc20[`ERC20`] for both the basic standard implementation and the xref:api:token/ERC20.adoc#ERC20-name--[`name`], xref:api:token/ERC20.adoc#ERC20-symbol--[`symbol`], and xref:api:token/ERC20.adoc#ERC20-decimals--[`decimals`] optional extensions. Additionally, we're creating an `initialSupply` of tokens, which will be assigned to the address that deploys the contract. + +TIP: For a more complete discussion of ERC20 supply mechanisms, see xref:erc20-supply.adoc[Creating ERC20 Supply]. + +That's it! Once deployed, we will be able to query the deployer's balance: + +[source,javascript] +---- +> GLDToken.balanceOf(deployerAddress) +1000000000000000000000 +---- + +We can also xref:api:token/ERC20.adoc#IERC20-transfer-address-uint256-[transfer] these tokens to other accounts: + +[source,javascript] +---- +> GLDToken.transfer(otherAddress, 300000000000000000000) +> GLDToken.balanceOf(otherAddress) +300000000000000000000 +> GLDToken.balanceOf(deployerAddress) +700000000000000000000 +---- + +[[a-note-on-decimals]] +== A Note on `decimals` + +Often, you'll want to be able to divide your tokens into arbitrary amounts: say, if you own `5 GLD`, you may want to send `1.5 GLD` to a friend, and keep `3.5 GLD` to yourself. Unfortunately, Solidity and the EVM do not support this behavior: only integer (whole) numbers can be used, which poses an issue. You may send `1` or `2` tokens, but not `1.5`. + +To work around this, xref:api:token/ERC20.adoc#ERC20[`ERC20`] provides a xref:api:token/ERC20.adoc#ERC20-decimals--[`decimals`] field, which is used to specify how many decimal places a token has. To be able to transfer `1.5 GLD`, `decimals` must be at least `1`, since that number has a single decimal place. + +How can this be achieved? It's actually very simple: a token contract can use larger integer values, so that a balance of `50` will represent `5 GLD`, a transfer of `15` will correspond to `1.5 GLD` being sent, and so on. + +It is important to understand that `decimals` is _only used for display purposes_. All arithmetic inside the contract is still performed on integers, and it is the different user interfaces (wallets, exchanges, etc.) that must adjust the displayed values according to `decimals`. The total token supply and balance of each account are not specified in `GLD`: you need to divide by `10 ** decimals` to get the actual `GLD` amount. + +You'll probably want to use a `decimals` value of `18`, just like Ether and most ERC20 token contracts in use, unless you have a very special reason not to. When minting tokens or transferring them around, you will be actually sending the number `num GLD * (10 ** decimals)`. + +NOTE: By default, `ERC20` uses a value of `18` for `decimals`. To use a different value, you will need to override the `decimals()` function in your contract. + +```solidity +function decimals() public view virtual override returns (uint8) { + return 16; +} +``` + +So if you want to send `5` tokens using a token contract with 18 decimals, the method to call will actually be: + +```solidity +transfer(recipient, 5 * (10 ** 18)); +``` diff --git a/docs/modules/ROOT/pages/erc4626.adoc b/docs/modules/ROOT/pages/erc4626.adoc new file mode 100644 index 000000000..43ec3ebb9 --- /dev/null +++ b/docs/modules/ROOT/pages/erc4626.adoc @@ -0,0 +1,214 @@ += ERC4626 +:stem: latexmath + +https://eips.ethereum.org/EIPS/eip-4626[ERC4626] is an extension of xref:erc20.adoc[ERC20] that proposes a standard interface for token vaults. This standard interface can be used by widely different contracts (including lending markets, aggregators, and intrinsically interest bearing tokens), which brings a number of subtleties. Navigating these potential issues is essential to implementing a compliant and composable token vault. + +We provide a base implementation of ERC4626 that includes a simple vault. This contract is designed in a way that allows developers to easily re-configure the vault's behavior, with minimal overrides, while staying compliant. In this guide, we will discuss some security considerations that affect ERC4626. We will also discuss common customizations of the vault. + +[[inflation-attack]] +== Security concern: Inflation attack + +=== Visualizing the vault + +In exchange for the assets deposited into an ERC4626 vault, a user receives shares. These shares can later be burned to redeem the corresponding underlying assets. The number of shares a user gets depends on the amount of assets they put in and on the exchange rate of the vault. This exchange rate is defined by the current liquidity held by the vault. + +- If a vault has 100 tokens to back 200 shares, then each share is worth 0.5 assets. +- If a vault has 200 tokens to back 100 shares, then each share is worth 2.0 assets. + +In other words, the exchange rate can be defined as the slope of the line that passes through the origin and the current number of assets and shares in the vault. Deposits and withdrawals move the vault in this line. + +image::erc4626-rate-linear.png[Exchange rates in linear scale] + +When plotted in log-log scale, the rate is defined similarly, but appears differently (because the point (0,0) is infinitely far away). Rates are represented by "diagonal" lines with different offsets. + +image::erc4626-rate-loglog.png[Exchange rates in logarithmic scale] + +In such a reprentation, widely different rates can be clearly visible in the same graph. This wouldn't be the case in linear scale. + +image::erc4626-rate-loglogext.png[More exchange rates in logarithmic scale] + +=== The attack + +When depositing tokens, the number of shares a user gets is rounded towards zero. This rounding takes away value from the user in favor or the vault (i.e. in favor of all the current share holders). This rounding is often negligible because of the amount at stake. If you deposit 1e9 shares worth of tokens, the rounding will have you lose at most 0.0000001% of your deposit. However if you deposit 10 shares worth of tokens, you could lose 10% of your deposit. Even worse, if you deposit <1 share worth of tokens, then you get 0 shares, and you basically made a donation. + +For a given amount of assets, the more shares you receive the safer you are. If you want to limit your losses to at most 1%, you need to receive at least 100 shares. + +image::erc4626-deposit.png[Depositing assets] + +In the figure we can see that for a given deposit of 500 assets, the number of shares we get and the corresponding rounding losses depend on the exchange rate. If the exchange rate is that of the orange curve, we are getting less than a share, so we lose 100% of our deposit. However, if the exchange rate is that of the green curve, we get 5000 shares, which limits our rounding losses to at most 0.02%. + +image::erc4626-mint.png[Minting shares] + +Symmetrically, if we focus on limiting our losses to a maximum of 0.5%, we need to get at least 200 shares. With the green exchange rate that requires just 20 tokens, but with the orange rate that requires 200000 tokens. + +We can clearly see that that the blue and green curves correspond to vaults that are safer than the yellow and orange curves. + +The idea of an inflation attack is that an attacker can donate assets to the vault to move the rate curve to the right, and make the vault unsafe. + +image::erc4626-attack.png[Inflation attack without protection] + +Figure 6 shows how an attacker can manipulate the rate of an empty vault. First the attacker must deposit a small amount of tokens (1 token) and follow up with a donation of 1e5 tokens directly to the vault to move the exchange rate "right". This puts the vault in a state where any deposit smaller than 1e5 would be completely lost to the vault. Given that the attacker is the only share holder (from their donation), the attacker would steal all the tokens deposited. + +An attacker would typically wait for a user to do the first deposit into the vault, and would frontrun that operation with the attack described above. The risk is low, and the size of the "donation" required to manipulate the vault is equivalent to the size of the deposit that is being attacked. + +In math that gives: + +- stem:[a_0] the attacker deposit +- stem:[a_1] the attacker donation +- stem:[u] the user deposit + +[%header,cols=4*] +|=== +| +| Assets +| Shares +| Rate + +| initial +| stem:[0] +| stem:[0] +| - + +| after attacker's deposit +| stem:[a_0] +| stem:[a_0] +| stem:[1] + +| after attacker's donation +| stem:[a_0+a_1] +| stem:[a_0] +| stem:[\frac{a_0}{a_0+a_1}] +|=== + +This means a deposit of stem:[u] will give stem:[\frac{u \times a_0}{a_0 + a_1}] shares. + +For the attacker to dilute that deposit to 0 shares, causing the user to lose all its deposit, it must ensure that + +[stem] +++++ +\frac{u \times a_0}{a_0+a_1} < 1 \iff u < 1 + \frac{a_1}{a_0} +++++ + +Using stem:[a_0 = 1] and stem:[a_1 = u] is enough. So the attacker only needs stem:[u+1] assets to perform a successful attack. + +It is easy to generalize the above results to scenarios where the attacker is going after a smaller fraction of the user's deposit. In order to target stem:[\frac{u}{n}], the user needs to suffer rounding of a similar fraction, which means the user must receive at most stem:[n] shares. This results in: + +[stem] +++++ +\frac{u \times a_0}{a_0+a_1} < n \iff \frac{u}{n} < 1 + \frac{a_1}{a_0} +++++ + +In this scenario, the attack is stem:[n] times less powerful (in how much it is stealing) and costs stem:[n] times less to execute. In both cases, the amount of funds the attacker needs to commit is equivalent to its potential earnings. + +=== Defending with a virtual offset + +The defense we propose is based on the approach used in link:https://github.com/boringcrypto/YieldBox[YieldBox]. It consists of two parts: + +- Use an offset between the "precision" of the representation of shares and assets. Said otherwise, we use more decimal places to represent the shares than the underlying token does to represent the assets. +- Include virtual shares and virtual assets in the exchange rate computation. These virtual assets enforce the conversion rate when the vault is empty. + +These two parts work together in enforcing the security of the vault. First, the increased precision corresponds to a high rate, which we saw is safer as it reduces the rounding error when computing the amount of shares. Second, the virtual assets and shares (in addition to simplifying a lot of the computations) capture part of the donation, making it unprofitable for a developer to perform an attack. + +Following the previous math definitions, we have: + +- stem:[\delta] the vault offset +- stem:[a_0] the attacker deposit +- stem:[a_1] the attacker donation +- stem:[u] the user deposit + +[%header,cols=4*] +|=== +| +| Assets +| Shares +| Rate + +| initial +| stem:[1] +| stem:[10^\delta] +| stem:[10^\delta] + +| after attacker's deposit +| stem:[1+a_0] +| stem:[10^\delta \times (1+a_0)] +| stem:[10^\delta] + +| after attacker's donation +| stem:[1+a_0+a_1] +| stem:[10^\delta \times (1+a_0)] +| stem:[10^\delta \times \frac{1+a_0}{1+a_0+a_1}] +|=== + +One important thing to note is that the attacker only owns a fraction stem:[\frac{a_0}{1 + a_0}] of the shares, so when doing the donation, he will only be able to recover that fraction stem:[\frac{a_1 \times a_0}{1 + a_0}] of the donation. The remaining stem:[\frac{a_1}{1+a_0}] are captured by the vault. + +[stem] +++++ +\mathit{loss} = \frac{a_1}{1+a_0} +++++ + +When the user deposits stem:[u], he receives + +[stem] +++++ +10^\delta \times u \times \frac{1+a_0}{1+a_0+a_1} +++++ + +For the attacker to dilute that deposit to 0 shares, causing the user to lose all its deposit, it must ensure that + +[stem] +++++ +10^\delta \times u \times \frac{1+a_0}{1+a_0+a_1} < 1 +++++ + +[stem] +++++ +\iff 10^\delta \times u < \frac{1+a_0+a_1}{1+a_0} +++++ + +[stem] +++++ +\iff 10^\delta \times u < 1 + \frac{a_1}{1+a_0} +++++ + +[stem] +++++ +\iff 10^\delta \times u \le \mathit{loss} +++++ + +- If the offset is 0, the attacker loss is at least equal to the user's deposit. +- If the offset is greater than 0, the attacker will have to suffer losses that are orders of magnitude bigger than the amount of value that can hypothetically be stolen from the user. + +This shows that even with an offset of 0, the virtual shares and assets make this attack non profitable for the attacker. Bigger offsets increase the security even further by making any attack on the user extremely wasteful. + +The following figure shows how the offset impacts the initial rate and limits the ability of an attacker with limited funds to inflate it effectively. + +image::erc4626-attack-3a.png[Inflation attack without offset=3] +stem:[\delta = 3], stem:[a_0 = 1], stem:[a_1 = 10^5] + +image::erc4626-attack-3b.png[Inflation attack without offset=3 and an attacker deposit that limits its losses] +stem:[\delta = 3], stem:[a_0 = 100], stem:[a_1 = 10^5] + +image::erc4626-attack-6.png[Inflation attack without offset=6] +stem:[\delta = 6], stem:[a_0 = 1], stem:[a_1 = 10^5] + + +[[fees]] +== Custom behavior: Adding fees to the vault + +In an ERC4626 vaults, fees can be captured during the deposit/mint and/or during the withdraw/redeem steps. In both cases it is essential to remain compliant with the ERC4626 requirements with regard to the preview functions. + +For example, if calling `deposit(100, receiver)`, the caller should deposit exactly 100 underlying tokens, including fees, and the receiver should receive a number of shares that matches the value returned by `previewDeposit(100)`. Similarly, `previewMint` should account for the fees that the user will have to pay on top of share's cost. + +As for the `Deposit` event, while this is less clear in the EIP spec itself, there seems to be consensus that it should include the number of assets paid for by the user, including the fees. + +On the other hand, when withdrawing assets, the number given by the user should correspond to what he receives. Any fees should be added to the quote (in shares) performed by `previewWithdraw`. + +The `Withdraw` event should include the number of shares the user burns (including fees) and the number of assets the user actually receives (after fees are deducted). + +The consequence of this design is that both the `Deposit` and `Withdraw` events will describe two exchange rates. The spread between the "Buy-in" and the "Exit" prices correspond to the fees taken by the vault. + +The following example describes how fees proportional to the deposited/withdrawn amount can be implemented: + +```solidity +include::api:example$ERC4626Fees.sol[] +``` diff --git a/docs/modules/ROOT/pages/erc721.adoc b/docs/modules/ROOT/pages/erc721.adoc new file mode 100644 index 000000000..7481c6b62 --- /dev/null +++ b/docs/modules/ROOT/pages/erc721.adoc @@ -0,0 +1,79 @@ += ERC721 + +We've discussed how you can make a _fungible_ token using xref:erc20.adoc[ERC20], but what if not all tokens are alike? This comes up in situations like *real estate*, *voting rights*, or *collectibles*, where some items are valued more than others, due to their usefulness, rarity, etc. ERC721 is a standard for representing ownership of xref:tokens.adoc#different-kinds-of-tokens[_non-fungible_ tokens], that is, where each token is unique. + +ERC721 is a more complex standard than ERC20, with multiple optional extensions, and is split across a number of contracts. The OpenZeppelin Contracts provide flexibility regarding how these are combined, along with custom useful extensions. Check out the xref:api:token/ERC721.adoc[API Reference] to learn more about these. + +== Constructing an ERC721 Token Contract + +We'll use ERC721 to track items in our game, which will each have their own unique attributes. Whenever one is to be awarded to a player, it will be minted and sent to them. Players are free to keep their token or trade it with other people as they see fit, as they would any other asset on the blockchain! Please note any account can call `awardItem` to mint items. To restrict what accounts can mint items we can add xref:access-control.adoc[Access Control]. + +Here's what a contract for tokenized items might look like: + +[source,solidity] +---- +// contracts/GameItem.sol +// SPDX-License-Identifier: MIT +pragma solidity ^0.8.20; + +import {ERC721URIStorage} from "@openzeppelin/contracts/token/ERC721/extensions/ERC721URIStorage.sol"; + +contract GameItem is ERC721URIStorage { + uint256 private _nextTokenId; + + constructor() ERC721("GameItem", "ITM") {} + + function awardItem(address player, string memory tokenURI) + public + returns (uint256) + { + uint256 tokenId = _nextTokenId++; + _mint(player, tokenId); + _setTokenURI(tokenId, tokenURI); + + return tokenId; + } +} +---- + +The xref:api:token/ERC721.adoc#ERC721URIStorage[`ERC721URIStorage`] contract is an implementation of ERC721 that includes the metadata standard extensions (xref:api:token/ERC721.adoc#IERC721Metadata[`IERC721Metadata`]) as well as a mechanism for per-token metadata. That's where the xref:api:token/ERC721.adoc#ERC721-_setTokenURI-uint256-string-[`_setTokenURI`] method comes from: we use it to store an item's metadata. + +Also note that, unlike ERC20, ERC721 lacks a `decimals` field, since each token is distinct and cannot be partitioned. + +New items can be created: + +[source,javascript] +---- +> gameItem.awardItem(playerAddress, "https://game.example/item-id-8u5h2m.json") +Transaction successful. Transaction hash: 0x... +Events emitted: + - Transfer(0x0000000000000000000000000000000000000000, playerAddress, 7) +---- + +And the owner and metadata of each item queried: + +[source,javascript] +---- +> gameItem.ownerOf(7) +playerAddress +> gameItem.tokenURI(7) +"https://game.example/item-id-8u5h2m.json" +---- + +This `tokenURI` should resolve to a JSON document that might look something like: + +[source,json] +---- +{ + "name": "Thor's hammer", + "description": "Mjölnir, the legendary hammer of the Norse god of thunder.", + "image": "https://game.example/item-id-8u5h2m.png", + "strength": 20 +} +---- + +For more information about the `tokenURI` metadata JSON Schema, check out the https://eips.ethereum.org/EIPS/eip-721[ERC721 specification]. + +NOTE: You'll notice that the item's information is included in the metadata, but that information isn't on-chain! So a game developer could change the underlying metadata, changing the rules of the game! + +TIP: If you'd like to put all item information on-chain, you can extend ERC721 to do so (though it will be rather costly) by providing a xref:utilities.adoc#base64[`Base64`] Data URI with the JSON schema encoded. You could also leverage IPFS to store the tokenURI information, but these techniques are out of the scope of this overview guide. diff --git a/docs/modules/ROOT/pages/extending-contracts.adoc b/docs/modules/ROOT/pages/extending-contracts.adoc new file mode 100644 index 000000000..1c13d6b4b --- /dev/null +++ b/docs/modules/ROOT/pages/extending-contracts.adoc @@ -0,0 +1,131 @@ += Extending Contracts + +Most of the OpenZeppelin Contracts are expected to be used via https://solidity.readthedocs.io/en/latest/contracts.html#inheritance[inheritance]: you will _inherit_ from them when writing your own contracts. + +This is the commonly found `is` syntax, like in `contract MyToken is ERC20`. + +[NOTE] +==== +Unlike ``contract``s, Solidity ``library``s are not inherited from and instead rely on the https://solidity.readthedocs.io/en/latest/contracts.html#using-for[`using for`] syntax. + +OpenZeppelin Contracts has some ``library``s: most are in the xref:api:utils.adoc[Utils] directory. +==== + +== Overriding + +Inheritance is often used to add the parent contract's functionality to your own contract, but that's not all it can do. You can also _change_ how some parts of the parent behave using _overrides_. + +For example, imagine you want to change xref:api:access.adoc#AccessControl[`AccessControl`] so that xref:api:access.adoc#AccessControl-revokeRole-bytes32-address-[`revokeRole`] can no longer be called. This can be achieved using overrides: + +```solidity +// contracts/ModifiedAccessControl.sol +// SPDX-License-Identifier: MIT +pragma solidity ^0.8.20; + +import {AccessControl} from "@openzeppelin/contracts/access/AccessControl.sol"; + +contract ModifiedAccessControl is AccessControl { + // Override the revokeRole function + function revokeRole(bytes32, address) public override { + revert("ModifiedAccessControl: cannot revoke roles"); + } +} +``` + +The old `revokeRole` is then replaced by our override, and any calls to it will immediately revert. We cannot _remove_ the function from the contract, but reverting on all calls is good enough. + +=== Calling `super` + +Sometimes you want to _extend_ a parent's behavior, instead of outright changing it to something else. This is where `super` comes in. + +The `super` keyword will let you call functions defined in a parent contract, even if they are overridden. This mechanism can be used to add additional checks to a function, emit events, or otherwise add functionality as you see fit. + +TIP: For more information on how overrides work, head over to the https://solidity.readthedocs.io/en/latest/contracts.html#index-17[official Solidity documentation]. + +Here is a modified version of xref:api:access.adoc#AccessControl[`AccessControl`] where xref:api:access.adoc#AccessControl-revokeRole-bytes32-address-[`revokeRole`] cannot be used to revoke the `DEFAULT_ADMIN_ROLE`: + + +```solidity +// contracts/ModifiedAccessControl.sol +// SPDX-License-Identifier: MIT +pragma solidity ^0.8.20; + +import {AccessControl} from "@openzeppelin/contracts/access/AccessControl.sol"; + +contract ModifiedAccessControl is AccessControl { + function revokeRole(bytes32 role, address account) public override { + require( + role != DEFAULT_ADMIN_ROLE, + "ModifiedAccessControl: cannot revoke default admin role" + ); + + super.revokeRole(role, account); + } +} +``` + +The `super.revokeRole` statement at the end will invoke ``AccessControl``'s original version of `revokeRole`, the same code that would've run if there were no overrides in place. + +NOTE: The same rule is implemented and extended in xref:api:access.adoc#AccessControlDefaultAdminRules[`AccessControlDefaultAdminRules`], an extension that also adds enforced security measures for the `DEFAULT_ADMIN_ROLE`. + +[[using-hooks]] +== Using Hooks + +Sometimes, in order to extend a parent contract you will need to override multiple related functions, which leads to code duplication and increased likelihood of bugs. + +For example, consider implementing safe xref:api:token/ERC20.adoc#ERC20[`ERC20`] transfers in the style of xref:api:token/ERC721.adoc#IERC721Receiver[`IERC721Receiver`]. You may think overriding xref:api:token/ERC20.adoc#ERC20-transfer-address-uint256-[`transfer`] and xref:api:token/ERC20.adoc#ERC20-transferFrom-address-address-uint256-[`transferFrom`] would be enough, but what about xref:api:token/ERC20.adoc#ERC20-_transfer-address-address-uint256-[`_transfer`] and xref:api:token/ERC20.adoc#ERC20-_mint-address-uint256-[`_mint`]? To prevent you from having to deal with these details, we introduced **hooks**. + +Hooks are simply functions that are called before or after some action takes place. They provide a centralized point to _hook into_ and extend the original behavior. + +Here's how you would implement the `IERC721Receiver` pattern in `ERC20`, using the xref:api:token/ERC20.adoc#ERC20-_beforeTokenTransfer-address-address-uint256-[`_beforeTokenTransfer`] hook: + +```solidity +pragma solidity ^0.8.20; + +import {ERC20} from "@openzeppelin/contracts/token/ERC20/ERC20.sol"; + +contract ERC20WithSafeTransfer is ERC20 { + function _beforeTokenTransfer(address from, address to, uint256 amount) + internal virtual override + { + super._beforeTokenTransfer(from, to, amount); + + require(_validRecipient(to), "ERC20WithSafeTransfer: invalid recipient"); + } + + function _validRecipient(address to) private view returns (bool) { + ... + } + + ... +} +``` + +Using hooks this way leads to cleaner and safer code, without having to rely on a deep understanding of the parent's internals. + +=== Rules of Hooks + +There's a few guidelines you should follow when writing code that uses hooks in order to prevent issues. They are very simple, but do make sure you follow them: + +1. Whenever you override a parent's hook, re-apply the `virtual` attribute to the hook. That will allow child contracts to add more functionality to the hook. +2. **Always** call the parent's hook in your override using `super`. This will make sure all hooks in the inheritance tree are called: contracts like xref:api:token/ERC20.adoc#ERC20Pausable[`ERC20Pausable`] rely on this behavior. + +```solidity +contract MyToken is ERC20 { + function _beforeTokenTransfer(address from, address to, uint256 amount) + internal virtual override // Add virtual here! + { + super._beforeTokenTransfer(from, to, amount); // Call parent hook + ... + } +} +``` +That's it! Enjoy simpler code using hooks! + +== Security + +The maintainers of OpenZeppelin Contracts are mainly concerned with the correctness and security of the code as published in the library, and the combinations of base contracts with the official extensions from the library. + +Custom overrides, and those of hooks in particular, may break some important assumptions and introduce vulnerabilities in otherwise secure code. While we try to ensure the contracts remain secure in the face of a wide range of potential customizations, this is done in a best-effort manner. While we try to document all important assumptions, this should not be relied upon. Custom overrides should be carefully reviewed and checked against the source code of the contract they are customizing so as to fully understand their impact and guarantee their security. + +The way functions interact internally should not be assumed to stay stable across releases of the library. For example, a function that is used in one context in a particular release may not be used in the same context in the next release. Contracts that override functions should revalidate their assumptions when updating the version of OpenZeppelin Contracts they are built on. diff --git a/docs/modules/ROOT/pages/faq.adoc b/docs/modules/ROOT/pages/faq.adoc new file mode 100644 index 000000000..81c34bbf5 --- /dev/null +++ b/docs/modules/ROOT/pages/faq.adoc @@ -0,0 +1,13 @@ += Frequently Asked Questions + +== Can I restrict a function to EOAs only? + +When calling external addresses from your contract it is unsafe to assume that an address is an externally-owned account (EOA) and not a contract. Attempting to prevent calls from contracts is highly discouraged. It breaks composability, breaks support for smart wallets like Gnosis Safe, and does not provide security since it can be circumvented by calling from a contract constructor. + +Although checking that the address has code, `address.code.length > 0`, may seem to differentiate contracts from EOAs, it can only say that an address is currently a contract, and its negation (that an address is not currently a contract) does not imply that the address is an EOA. Some counterexamples are: + + - address of a contract in construction + - address where a contract will be created + - address where a contract lived, but was destroyed + +Furthermore, an address will be considered a contract within the same transaction where it is scheduled for destruction by `SELFDESTRUCT`, which only has an effect at the end of the entire transaction. diff --git a/docs/modules/ROOT/pages/governance.adoc b/docs/modules/ROOT/pages/governance.adoc new file mode 100644 index 000000000..b8db64230 --- /dev/null +++ b/docs/modules/ROOT/pages/governance.adoc @@ -0,0 +1,240 @@ += How to set up on-chain governance + +In this guide we will learn how OpenZeppelin’s Governor contract works, how to set it up, and how to use it to create proposals, vote for them, and execute them, using tools provided by Ethers.js and Tally. + +NOTE: Find detailed contract documentation at xref:api:governance.adoc[Governance API]. + +== Introduction + +Decentralized protocols are in constant evolution from the moment they are publicly released. Often, the initial team retains control of this evolution in the first stages, but eventually delegates it to a community of stakeholders. The process by which this community makes decisions is called on-chain governance, and it has become a central component of decentralized protocols, fueling varied decisions such as parameter tweaking, smart contract upgrades, integrations with other protocols, treasury management, grants, etc. + +This governance protocol is generally implemented in a special-purpose contract called “Governor”. The GovernorAlpha and GovernorBravo contracts designed by Compound have been very successful and popular so far, with the downside that projects with different requirements have had to fork the code to customize it for their needs, which can pose a high risk of introducing security issues. For OpenZeppelin Contracts, we set out to build a modular system of Governor contracts so that forking is not needed, and different requirements can be accommodated by writing small modules using Solidity inheritance. You will find the most common requirements out of the box in OpenZeppelin Contracts, but writing additional ones is simple, and we will be adding new features as requested by the community in future releases. Additionally, the design of OpenZeppelin Governor requires minimal use of storage and results in more gas efficient operation. + +== Compatibility + +OpenZeppelin’s Governor system was designed with a concern for compatibility with existing systems that were based on Compound’s GovernorAlpha and GovernorBravo. Because of this, you will find that many modules are presented in two variants, one of which is built for compatibility with those systems. + +=== ERC20Votes & ERC20VotesComp + +The ERC20 extension to keep track of votes and vote delegation is one such case. The shorter one is the more generic version because it can support token supplies greater than 2^96, while the “Comp” variant is limited in that regard, but exactly fits the interface of the COMP token that is used by GovernorAlpha and Bravo. Both contract variants share the same events, so they are fully compatible when looking at events only. + +=== Governor & GovernorStorage + +An OpenZeppelin Governor contract is not interface-compatible with Compound's GovernorAlpha or Bravo. Even though events are fully compatible, proposal lifecycle functions (creation, execution, etc.) have different signatures that are meant to optimize storage use. Other functions from GovernorAlpha are Bravo are likewise not available. It’s possible to opt in some Bravo-like behavior by inheriting from the GovernorStorage module. This module provides proposal enumerability and alternate versions of the `queue`, `execute` and `cancel` function that only take the proposal id. This module reduces the calldata needed by some operations in exchange for an increased the storage footprint. This might be a good trade-off for some L2 chains. It also provides primitives for indexer-free frontends. + +Note that even with the use of this module, one important difference with Compound's GovernorBravo is the way that `proposalId`s are calculated. Governor uses the hash of the proposal parameters with the purpose of keeping its data off-chain by event indexing, while the original Bravo implementation uses sequential `proposalId`s. + +=== GovernorTimelockControl & GovernorTimelockCompound + +When using a timelock with your Governor contract, you can use either OpenZeppelin’s TimelockController or Compound’s Timelock. Based on the choice of timelock, you should choose the corresponding Governor module: GovernorTimelockControl or GovernorTimelockCompound respectively. This allows you to migrate an existing GovernorAlpha instance to an OpenZeppelin-based Governor without changing the timelock in use. + +=== Tally + +https://www.tally.xyz[Tally] is a full-fledged application for user owned on-chain governance. It comprises a voting dashboard, proposal creation wizard, real time research and analysis, and educational content. + +For all of these options, the Governor will be compatible with Tally: users will be able to create proposals, visualize voting power and advocates, navigate proposals, and cast votes. For proposal creation in particular, projects can also use Defender Admin as an alternative interface. + +In the rest of this guide, we will focus on a fresh deploy of the vanilla OpenZeppelin Governor features without concern for compatibility with GovernorAlpha or Bravo. + +== Setup + +=== Token + +The voting power of each account in our governance setup will be determined by an ERC20 token. The token has to implement the ERC20Votes extension. This extension will keep track of historical balances so that voting power is retrieved from past snapshots rather than current balance, which is an important protection that prevents double voting. + +```solidity +include::api:example$governance/MyToken.sol[] +``` + +If your project already has a live token that does not include ERC20Votes and is not upgradeable, you can wrap it in a governance token by using ERC20Wrapper. This will allow token holders to participate in governance by wrapping their tokens 1-to-1. + +```solidity +include::api:example$governance/MyTokenWrapped.sol[] +``` + +NOTE: The only other source of voting power available in OpenZeppelin Contracts currently is xref:api:token/ERC721.adoc#ERC721Votes[`ERC721Votes`]. ERC721 tokens that don't provide this functionality can be wrapped into a voting tokens using a combination of xref:api:token/ERC721.adoc#ERC721Votes[`ERC721Votes`] and xref:api:token/ERC721Wrapper.adoc#ERC721Wrapper[`ERC721Wrapper`]. + +NOTE: The internal clock used by the token to store voting balances will dictate the operating mode of the Governor contract attached to it. By default, block numbers are used. Since v4.9, developers can override the xref:api:interfaces.adoc#IERC6372[IERC6372] clock to use timestamps instead of block numbers. + +=== Governor + +Initially, we will build a Governor without a timelock. The core logic is given by the Governor contract, but we still need to choose: 1) how voting power is determined, 2) how many votes are needed for quorum, 3) what options people have when casting a vote and how those votes are counted, and 4) what type of token should be used to vote. Each of these aspects is customizable by writing your own module, or more easily choosing one from OpenZeppelin Contracts. + +For 1) we will use the GovernorVotes module, which hooks to an IVotes instance to determine the voting power of an account based on the token balance they hold when a proposal becomes active. This module requires as a constructor parameter the address of the token. This module also discovers the clock mode (ERC6372) used by the token and applies it to the Governor. + +For 2) we will use GovernorVotesQuorumFraction which works together with ERC20Votes to define quorum as a percentage of the total supply at the block a proposal’s voting power is retrieved. This requires a constructor parameter to set the percentage. Most Governors nowadays use 4%, so we will initialize the module with parameter 4 (this indicates the percentage, resulting in 4%). + +For 3) we will use GovernorCountingSimple, a module that offers 3 options to voters: For, Against, and Abstain, and where only For and Abstain votes are counted towards quorum. + +Besides these modules, Governor itself has some parameters we must set. + +votingDelay: How long after a proposal is created should voting power be fixed. A large voting delay gives users time to unstake tokens if necessary. + +votingPeriod: How long does a proposal remain open to votes. + +These parameters are specified in the unit defined in the token's clock. Assuming the token uses block numbers, and assuming block time of around 12 seconds, we will have set votingDelay = 1 day = 7200 blocks, and votingPeriod = 1 week = 50400 blocks. + +We can optionally set a proposal threshold as well. This restricts proposal creation to accounts who have enough voting power. + +```solidity +include::api:example$governance/MyGovernor.sol[] +``` + +=== Timelock + +It is good practice to add a timelock to governance decisions. This allows users to exit the system if they disagree with a decision before it is executed. We will use OpenZeppelin’s TimelockController in combination with the GovernorTimelockControl module. + +IMPORTANT: When using a timelock, it is the timelock that will execute proposals and thus the timelock that should hold any funds, ownership, and access control roles. Before version 4.5 there was no way to recover funds in the Governor contract when using a timelock! Before version 4.3, when using the Compound Timelock, ETH in the timelock was not easily accessible. + +TimelockController uses an AccessControl setup that we need to understand in order to set up roles. + +- The Proposer role is in charge of queueing operations: this is the role the Governor instance should be granted, and it should likely be the only proposer in the system. +- The Executor role is in charge of executing already available operations: we can assign this role to the special zero address to allow anyone to execute (if operations can be particularly time sensitive, the Governor should be made Executor instead). +- Lastly, there is the Admin role, which can grant and revoke the two previous roles: this is a very sensitive role that will be granted automatically to the timelock itself, and optionally to a second account, which can be used for ease of setup but should promptly renounce the role. + +== Proposal Lifecycle + +Let’s walk through how to create and execute a proposal on our newly deployed Governor. + +A proposal is a sequence of actions that the Governor contract will perform if it passes. Each action consists of a target address, calldata encoding a function call, and an amount of ETH to include. Additionally, a proposal includes a human-readable description. + +=== Create a Proposal + +Let’s say we want to create a proposal to give a team a grant, in the form of ERC20 tokens from the governance treasury. This proposal will consist of a single action where the target is the ERC20 token, calldata is the encoded function call `transfer(, )`, and with 0 ETH attached. + +Generally a proposal will be created with the help of an interface such as Tally or Defender. Here we will show how to create the proposal using Ethers.js. + +First we get all the parameters necessary for the proposal action. + +```javascript +const tokenAddress = ...; +const token = await ethers.getContractAt(‘ERC20’, tokenAddress); + +const teamAddress = ...; +const grantAmount = ...; +const transferCalldata = token.interface.encodeFunctionData(‘transfer’, [teamAddress, grantAmount]); +``` + +Now we are ready to call the propose function of the Governor. Note that we don’t pass in one array of actions, but instead three arrays corresponding to the list of targets, the list of values, and the list of calldatas. In this case it’s a single action, so it’s simple: + +```javascript +await governor.propose( + [tokenAddress], + [0], + [transferCalldata], + “Proposal #1: Give grant to team”, +); +``` + +This will create a new proposal, with a proposal id that is obtained by hashing together the proposal data, and which will also be found in an event in the logs of the transaction. + +=== Cast a Vote + +Once a proposal is active, delegates can cast their vote. Note that it is delegates who carry voting power: if a token holder wants to participate, they can set a trusted representative as their delegate, or they can become a delegate themselves by self-delegating their voting power. + +Votes are cast by interacting with the Governor contract through the `castVote` family of functions. Voters would generally invoke this from a governance UI such as Tally. + +image::tally-vote.png[Voting in Tally] + +=== Execute the Proposal + +Once the voting period is over, if quorum was reached (enough voting power participated) and the majority voted in favor, the proposal is considered successful and can proceed to be executed. Once a proposal passes, it can be queued and executed from the same place you voted. + +image::tally-exec.png[Administration Panel in Tally] + +We will see now how to do this manually using Ethers.js. + +If a timelock was set up, the first step to execution is queueing. You will notice that both the queue and execute functions require passing in the entire proposal parameters, as opposed to just the proposal id. This is necessary because this data is not stored on chain, as a measure to save gas. Note that these parameters can always be found in the events emitted by the contract. The only parameter that is not sent in its entirety is the description, since this is only needed in its hashed form to compute the proposal id. + +To queue, we call the queue function: + +```javascript +const descriptionHash = ethers.utils.id(“Proposal #1: Give grant to team”); + +await governor.queue( + [tokenAddress], + [0], + [transferCalldata], + descriptionHash, +); +``` + +This will cause the Governor to interact with the timelock contract and queue the actions for execution after the required delay. + +After enough time has passed (according to the timelock parameters), the proposal can be executed. If there was no timelock to begin with, this step can be ran immediately after the proposal succeeds. + +```javascript +await governor.execute( + [tokenAddress], + [0], + [transferCalldata], + descriptionHash, +); +``` + +Executing the proposal will transfer the ERC20 tokens to the chosen recipient. To wrap up: we set up a system where a treasury is controlled by the collective decision of the token holders of a project, and all actions are executed via proposals enforced by on-chain votes. + +== Timestamp based governance + +=== Motivation + +It is sometimes difficult to deal with durations expressed in number of blocks because of inconsistent or unpredictable time between blocks. This is particularly true of some L2 networks where blocks are produced based on blockchain usage. Using number of blocks can also lead to the governance rules being affected by network upgrades that modify the expected time between blocks. + +The difficulty of replacing block numbers with timestamps is that the Governor and the token must both use the same format when querying past votes. If a token is designed around block numbers, it is not possible for a Governor to reliably do timestamp based lookups. + +Therefore, designing a timestamp based voting system starts with the token. + +=== Token + +Since v4.9, all voting contracts (including xref:api:token/ERC20.adoc#ERC20Votes[`ERC20Votes`] and xref:api:token/ERC721.adoc#ERC721Votes[`ERC721Votes`]) rely on xref:api:interfaces.adoc#IERC6372[IERC6372] for clock management. In order to change from operating with block numbers to operating with timestamps, all that is required is to override the `clock()` and `CLOCK_MODE()` functions. + +```solidity +include::api:example$governance/MyTokenTimestampBased.sol[] +``` + +=== Governor + +The Governor will automatically detect the clock mode used by the token and adapt to it. There is no need to override anything in the Governor contract. However, the clock mode does affect how some values are interpreted. It is therefore necessary to set the `votingDelay()` and `votingPeriod()` accordingly. + +```solidity +// SPDX-License-Identifier: MIT +pragma solidity ^0.8.20; + +import {Governor} from "@openzeppelin/contracts/governance/Governor.sol"; +import {GovernorCountingSimple} from "@openzeppelin/contracts/governance/compatibility/GovernorCountingSimple.sol"; +import {GovernorVotes} from "@openzeppelin/contracts/governance/extensions/GovernorVotes.sol"; +import {GovernorVotesQuorumFraction} from "@openzeppelin/contracts/governance/extensions/GovernorVotesQuorumFraction.sol"; +import {GovernorTimelockControl} from "@openzeppelin/contracts/governance/extensions/GovernorTimelockControl.sol"; +import {TimelockController} from "@openzeppelin/contracts/governance/TimelockController.sol"; +import {IVotes} from "@openzeppelin/contracts/governance/utils/IVotes.sol"; + +contract MyGovernor is Governor, GovernorCountingSimple, GovernorVotes, GovernorVotesQuorumFraction, GovernorTimelockControl { + constructor(IVotes _token, TimelockController _timelock) + Governor("MyGovernor") + GovernorVotes(_token) + GovernorVotesQuorumFraction(4) + GovernorTimelockControl(_timelock) + {} + + function votingDelay() public pure virtual override returns (uint256) { + return 1 days; + } + + function votingPeriod() public pure virtual override returns (uint256) { + return 1 weeks; + } + + function proposalThreshold() public pure virtual override returns (uint256) { + return 0; + } + + // ... +} + +``` + +=== Disclaimer + +Timestamp based voting is a recent feature that was formalized in EIP-6372 and EIP-5805, and introduced in v4.9. At the time this feature is released, governance tooling such as https://www.tally.xyz[Tally] does not support it yet. While support for timestamps should come soon, users can expect invalid reporting of deadlines & durations. This invalid reporting by offchain tools does not affect the onchain security and functionality of the governance contract. + +Governors with timestamp support (v4.9 and above) are compatible with old tokens (before v4.9) and will operate in "block number" mode (which is the mode all old tokens operate on). On the other hand, old Governor instances (before v4.9) are not compatible with new tokens operating using timestamps. If you update your token code to use timestamps, make sure to also update your Governor code. diff --git a/docs/modules/ROOT/pages/index.adoc b/docs/modules/ROOT/pages/index.adoc new file mode 100644 index 000000000..905ce231d --- /dev/null +++ b/docs/modules/ROOT/pages/index.adoc @@ -0,0 +1,79 @@ += Contracts + +*A library for secure smart contract development.* Build on a solid foundation of community-vetted code. + + * Implementations of standards like xref:erc20.adoc[ERC20] and xref:erc721.adoc[ERC721]. + * Flexible xref:access-control.adoc[role-based permissioning] scheme. + * Reusable xref:utilities.adoc[Solidity components] to build custom contracts and complex decentralized systems. + +== Overview + +[[install]] +=== Installation + +==== Hardhat, Truffle (npm) + +```console +$ npm install @openzeppelin/contracts +``` + +OpenZeppelin Contracts features a xref:releases-stability.adoc#api-stability[stable API], which means that your contracts won't break unexpectedly when upgrading to a newer minor version. + +==== Foundry (git) + +WARNING: When installing via git, it is a common error to use the `master` branch. This is a development branch that should be avoided in favor of tagged releases. The release process involves security measures that the `master` branch does not guarantee. + +WARNING: Foundry installs the latest version initially, but subsequent `forge update` commands will use the `master` branch. + +```console +$ forge install OpenZeppelin/openzeppelin-contracts +``` + +Add `@openzeppelin/contracts/=lib/openzeppelin-contracts/contracts/` in `remappings.txt.` + +[[usage]] +=== Usage + +Once installed, you can use the contracts in the library by importing them: + +[source,solidity] +---- +// contracts/MyNFT.sol +// SPDX-License-Identifier: MIT +pragma solidity ^0.8.20; + +import {ERC721} from "@openzeppelin/contracts/token/ERC721/ERC721.sol"; + +contract MyNFT is ERC721 { + constructor() ERC721("MyNFT", "MNFT") { + } +} +---- + +TIP: If you're new to smart contract development, head to xref:learn::developing-smart-contracts.adoc[Developing Smart Contracts] to learn about creating a new project and compiling your contracts. + +To keep your system secure, you should **always** use the installed code as-is, and neither copy-paste it from online sources, nor modify it yourself. The library is designed so that only the contracts and functions you use are deployed, so you don't need to worry about it needlessly increasing gas costs. + +[[security]] +== Security + +Please report any security issues you find via our https://www.immunefi.com/bounty/openzeppelin[bug bounty program on Immunefi] or directly to security@openzeppelin.org. + +The https://contracts.openzeppelin.com/security[Security Center] contains more details about the secure development process. + +[[next-steps]] +== Learn More + +The guides in the sidebar will teach about different concepts, and how to use the related contracts that OpenZeppelin Contracts provides: + +* xref:access-control.adoc[Access Control]: decide who can perform each of the actions on your system. +* xref:tokens.adoc[Tokens]: create tradable assets or collectibles, like the well known xref:erc20.adoc[ERC20] and xref:erc721.adoc[ERC721] standards. +* xref:utilities.adoc[Utilities]: generic useful tools, including non-overflowing math, signature verification, and trustless paying systems. + +The xref:api:token/ERC20.adoc[full API] is also thoroughly documented, and serves as a great reference when developing your smart contract application. You can also ask for help or follow Contracts' development in the https://forum.openzeppelin.com[community forum]. + +Finally, you may want to take a look at the https://blog.openzeppelin.com/guides/[guides on our blog], which cover several common use cases and good practices. The following articles provide great background reading, though please note, some of the referenced tools have changed as the tooling in the ecosystem continues to rapidly evolve. + +* https://blog.openzeppelin.com/the-hitchhikers-guide-to-smart-contracts-in-ethereum-848f08001f05[The Hitchhiker’s Guide to Smart Contracts in Ethereum] will help you get an overview of the various tools available for smart contract development, and help you set up your environment. +* https://blog.openzeppelin.com/a-gentle-introduction-to-ethereum-programming-part-1-783cc7796094[A Gentle Introduction to Ethereum Programming, Part 1] provides very useful information on an introductory level, including many basic concepts from the Ethereum platform. +* For a more in-depth dive, you may read the guide https://blog.openzeppelin.com/designing-the-architecture-for-your-ethereum-application-9cec086f8317[Designing the architecture for your Ethereum application], which discusses how to better structure your application and its relationship to the real world. diff --git a/docs/modules/ROOT/pages/releases-stability.adoc b/docs/modules/ROOT/pages/releases-stability.adoc new file mode 100644 index 000000000..9a3310377 --- /dev/null +++ b/docs/modules/ROOT/pages/releases-stability.adoc @@ -0,0 +1,85 @@ += New Releases and API Stability + +Developing smart contracts is hard, and a conservative approach towards dependencies is sometimes favored. However, it is also very important to stay on top of new releases: these may include bug fixes, or deprecate old patterns in favor of newer and better practices. + +Here we describe when you should expect new releases to come out, and how this affects you as a user of OpenZeppelin Contracts. + +[[release-schedule]] +== Release Schedule + +OpenZeppelin Contracts follows a <>. + +We aim for a new minor release every 1 or 2 months. + +[[minor-releases]] +=== Release Candidates + +Before every release, we publish a feature-frozen release candidate. The purpose of the release candidate is to have a period where the community can review the new code before the actual release. If important problems are discovered, several more release candidates may be required. After a week of no more changes to the release candidate, the new version is published. + +[[major-releases]] +=== Major Releases + +After several months or a year, a new major release may come out. These are not scheduled, but will be based on the need to release breaking changes such as a redesign of a core feature of the library (e.g. https://github.com/OpenZeppelin/openzeppelin-contracts/pulls/2112[access control] in 3.0). Since we value stability, we aim for these to happen infrequently (expect no less than six months between majors). However, we may be forced to release one when there are big changes to the Solidity language. + +[[api-stability]] +== API Stability + +On the https://github.com/OpenZeppelin/openzeppelin-contracts/releases/tag/v2.0.0[OpenZeppelin Contracts 2.0 release], we committed ourselves to keeping a stable API. We aim to more precisely define what we understand by _stable_ and _API_ here, so users of the library can understand these guarantees and be confident their project won't break unexpectedly. + +In a nutshell, the API being stable means _if your project is working today, it will continue to do so after a minor upgrade_. New contracts and features will be added in minor releases, but only in a backwards compatible way. + +[[versioning-scheme]] +=== Versioning Scheme + +We follow https://semver.org/[SemVer], which means API breakage may occur between major releases (which <>). + +[[solidity-functions]] +=== Solidity Functions + +While the internal implementation of functions may change, their semantics and signature will remain the same. The domain of their arguments will not be less restrictive (e.g. if transferring a value of 0 is disallowed, it will remain disallowed), nor will general state restrictions be lifted (e.g. `whenPaused` modifiers). + +If new functions are added to a contract, it will be in a backwards-compatible way: their usage won't be mandatory, and they won't extend functionality in ways that may foreseeably break an application (e.g. https://github.com/OpenZeppelin/openzeppelin-contracts/issues/1512[an `internal` method may be added to make it easier to retrieve information that was already available]). + +[[internal]] +==== `internal` + +This extends not only to `external` and `public` functions, but also `internal` ones: many contracts are meant to be used by inheriting them (e.g. `Pausable`, `PullPayment`, `AccessControl`), and are therefore used by calling these functions. Similarly, since all OpenZeppelin Contracts state variables are `private`, they can only be accessed this way (e.g. to create new `ERC20` tokens, instead of manually modifying `totalSupply` and `balances`, `_mint` should be called). + +`private` functions have no guarantees on their behavior, usage, or existence. + +Finally, sometimes language limitations will force us to e.g. make `internal` a function that should be `private` in order to implement features the way we want to. These cases will be well documented, and the normal stability guarantees won't apply. + +[[libraries]] +=== Libraries + +Some of our Solidity libraries use ``struct``s to handle internal data that should not be accessed directly (e.g. `Counter`). There's an https://github.com/ethereum/solidity/issues/4637[open issue] in the Solidity repository requesting a language feature to prevent said access, but it looks like it won't be implemented any time soon. Because of this, we will use leading underscores and mark said `struct` s to make it clear to the user that its contents and layout are _not_ part of the API. + +[[events]] +=== Events + +No events will be removed, and their arguments won't be changed in any way. New events may be added in later versions, and existing events may be emitted under new, reasonable circumstances (e.g. https://github.com/OpenZeppelin/openzeppelin-contracts/issues/707[from 2.1 on, `ERC20` also emits `Approval` on `transferFrom` calls]). + +[[drafts]] +=== Drafts + +Some contracts implement EIPs that are still in Draft status, recognizable by a file name beginning with `draft-`, such as `utils/cryptography/draft-EIP712.sol`. Due to their nature as drafts, the details of these contracts may change and we cannot guarantee their stability. Minor releases of OpenZeppelin Contracts may contain breaking changes for the contracts labelled as Drafts, which will be duly announced in the https://github.com/OpenZeppelin/openzeppelin-contracts/blob/master/CHANGELOG.md[changelog]. The EIPs included are used by projects in production and this may make them less likely to change significantly. + +[[gas-costs]] +=== Gas Costs + +While attempts will generally be made to lower the gas costs of working with OpenZeppelin Contracts, there are no guarantees regarding this. In particular, users should not assume gas costs will not increase when upgrading library versions. + +[[bugfixes]] +=== Bug Fixes + +The API stability guarantees may need to be broken in order to fix a bug, and we will do so. This decision won't be made lightly however, and all options will be explored to make the change as non-disruptive as possible. When sufficient, contracts or functions which may result in unsafe behavior will be deprecated instead of removed (e.g. https://github.com/OpenZeppelin/openzeppelin-contracts/pull/1543[#1543] and https://github.com/OpenZeppelin/openzeppelin-contracts/pull/1550[#1550]). + +[[solidity-compiler-version]] +=== Solidity Compiler Version + +Starting on version 0.5.0, the Solidity team switched to a faster release cycle, with minor releases every few weeks (v0.5.0 was released on November 2018, and v0.5.5 on March 2019), and major, breaking-change releases every couple of months (with v0.6.0 released on December 2019 and v0.7.0 on July 2020). Including the compiler version in OpenZeppelin Contract's stability guarantees would therefore force the library to either stick to old compilers, or release frequent major updates simply to keep up with newer Solidity releases. + +Because of this, *the minimum required Solidity compiler version is not part of the stability guarantees*, and users may be required to upgrade their compiler when using newer versions of Contracts. Bug fixes will still be backported to past major releases so that all versions currently in use receive these updates. + +You can read more about the rationale behind this, the other options we considered and why we went down this path https://github.com/OpenZeppelin/openzeppelin-contracts/issues/1498#issuecomment-449191611[here]. + diff --git a/docs/modules/ROOT/pages/tokens.adoc b/docs/modules/ROOT/pages/tokens.adoc new file mode 100644 index 000000000..10626f548 --- /dev/null +++ b/docs/modules/ROOT/pages/tokens.adoc @@ -0,0 +1,31 @@ += Tokens + +Ah, the "token": blockchain's most powerful and most misunderstood tool. + +A token is a _representation of something in the blockchain_. This something can be money, time, services, shares in a company, a virtual pet, anything. By representing things as tokens, we can allow smart contracts to interact with them, exchange them, create or destroy them. + +[[but_first_coffee_a_primer_on_token_contracts]] +== But First, [strikethrough]#Coffee# a Primer on Token Contracts + +Much of the confusion surrounding tokens comes from two concepts getting mixed up: _token contracts_ and the actual _tokens_. + +A _token contract_ is simply an Ethereum smart contract. "Sending tokens" actually means "calling a method on a smart contract that someone wrote and deployed". At the end of the day, a token contract is not much more than a mapping of addresses to balances, plus some methods to add and subtract from those balances. + +It is these balances that represent the _tokens_ themselves. Someone "has tokens" when their balance in the token contract is non-zero. That's it! These balances could be considered money, experience points in a game, deeds of ownership, or voting rights, and each of these tokens would be stored in different token contracts. + +[[different-kinds-of-tokens]] +== Different Kinds of Tokens + +Note that there's a big difference between having two voting rights and two deeds of ownership: each vote is equal to all others, but houses usually are not! This is called https://en.wikipedia.org/wiki/Fungibility[fungibility]. _Fungible goods_ are equivalent and interchangeable, like Ether, fiat currencies, and voting rights. _Non-fungible_ goods are unique and distinct, like deeds of ownership, or collectibles. + +In a nutshell, when dealing with non-fungibles (like your house) you care about _which ones_ you have, while in fungible assets (like your bank account statement) what matters is _how much_ you have. + +== Standards + +Even though the concept of a token is simple, they have a variety of complexities in the implementation. Because everything in Ethereum is just a smart contract, and there are no rules about what smart contracts have to do, the community has developed a variety of *standards* (called EIPs or ERCs) for documenting how a contract can interoperate with other contracts. + +You've probably heard of the ERC20 or ERC721 token standards, and that's why you're here. Head to our specialized guides to learn more about these: + + * xref:erc20.adoc[ERC20]: the most widespread token standard for fungible assets, albeit somewhat limited by its simplicity. + * xref:erc721.adoc[ERC721]: the de-facto solution for non-fungible tokens, often used for collectibles and games. + * xref:erc1155.adoc[ERC1155]: a novel standard for multi-tokens, allowing for a single contract to represent multiple fungible and non-fungible tokens, along with batched operations for increased gas efficiency. diff --git a/docs/modules/ROOT/pages/upgradeable.adoc b/docs/modules/ROOT/pages/upgradeable.adoc new file mode 100644 index 000000000..7324c9bad --- /dev/null +++ b/docs/modules/ROOT/pages/upgradeable.adoc @@ -0,0 +1,73 @@ += Using with Upgrades + +If your contract is going to be deployed with upgradeability, such as using the xref:upgrades-plugins::index.adoc[OpenZeppelin Upgrades Plugins], you will need to use the Upgradeable variant of OpenZeppelin Contracts. + +This variant is available as a separate package called `@openzeppelin/contracts-upgradeable`, which is hosted in the repository https://github.com/OpenZeppelin/openzeppelin-contracts-upgradeable[OpenZeppelin/openzeppelin-contracts-upgradeable]. + +It follows all of the rules for xref:upgrades-plugins::writing-upgradeable.adoc[Writing Upgradeable Contracts]: constructors are replaced by initializer functions, state variables are initialized in initializer functions, and we additionally check for storage incompatibilities across minor versions. + +TIP: OpenZeppelin provides a full suite of tools for deploying and securing upgradeable smart contracts. xref:openzeppelin::upgrades.adoc[Check out the full list of resources]. + +== Overview + +=== Installation + +```console +$ npm install @openzeppelin/contracts-upgradeable +``` + +=== Usage + +The package replicates the structure of the main OpenZeppelin Contracts package, but every file and contract has the suffix `Upgradeable`. + +```diff +-import {ERC721} from "@openzeppelin/contracts/token/ERC721/ERC721.sol"; ++import {ERC721Upgradeable} from "@openzeppelin/contracts-upgradeable/token/ERC721/ERC721Upgradeable.sol"; + +-contract MyCollectible is ERC721 { ++contract MyCollectible is ERC721Upgradeable { +``` + +Constructors are replaced by internal initializer functions following the naming convention `+__{ContractName}_init+`. Since these are internal, you must always define your own public initializer function and call the parent initializer of the contract you extend. + +```diff +- constructor() ERC721("MyCollectible", "MCO") public { ++ function initialize() initializer public { ++ __ERC721_init("MyCollectible", "MCO"); + } +``` + +CAUTION: Use with multiple inheritance requires special attention. See the section below titled <>. + +Once this contract is set up and compiled, you can deploy it using the xref:upgrades-plugins::index.adoc[Upgrades Plugins]. The following snippet shows an example deployment script using Hardhat. + +```js +// scripts/deploy-my-collectible.js +const { ethers, upgrades } = require("hardhat"); + +async function main() { + const MyCollectible = await ethers.getContractFactory("MyCollectible"); + + const mc = await upgrades.deployProxy(MyCollectible); + + await mc.deployed(); + console.log("MyCollectible deployed to:", mc.address); +} + +main(); +``` + +== Further Notes + +[[multiple-inheritance]] +=== Multiple Inheritance + +Initializer functions are not linearized by the compiler like constructors. Because of this, each `+__{ContractName}_init+` function embeds the linearized calls to all parent initializers. As a consequence, calling two of these `init` functions can potentially initialize the same contract twice. + +The function `+__{ContractName}_init_unchained+` found in every contract is the initializer function minus the calls to parent initializers, and can be used to avoid the double initialization problem, but doing this manually is not recommended. We hope to be able to implement safety checks for this in future versions of the Upgrades Plugins. + +=== Storage Gaps + +You may notice that every contract includes a state variable named `+__gap+`. This is empty reserved space in storage that is put in place in Upgradeable contracts. It allows us to freely add new state variables in the future without compromising the storage compatibility with existing deployments. + +It isn't safe to simply add a state variable because it "shifts down" all of the state variables below in the inheritance chain. This makes the storage layouts incompatible, as explained in xref:upgrades-plugins::writing-upgradeable.adoc#modifying-your-contracts[Writing Upgradeable Contracts]. The size of the `+__gap+` array is calculated so that the amount of storage used by a contract always adds up to the same number (in this case 50 storage slots). diff --git a/docs/modules/ROOT/pages/utilities.adoc b/docs/modules/ROOT/pages/utilities.adoc new file mode 100644 index 000000000..487b47a80 --- /dev/null +++ b/docs/modules/ROOT/pages/utilities.adoc @@ -0,0 +1,185 @@ += Utilities + +The OpenZeppelin Contracts provide a ton of useful utilities that you can use in your project. Here are some of the more popular ones. + +[[cryptography]] +== Cryptography + +=== Checking Signatures On-Chain + +xref:api:utils.adoc#ECDSA[`ECDSA`] provides functions for recovering and managing Ethereum account ECDSA signatures. These are often generated via https://web3js.readthedocs.io/en/v1.7.3/web3-eth.html#sign[`web3.eth.sign`], and are a 65 byte array (of type `bytes` in Solidity) arranged the following way: `[[v (1)], [r (32)], [s (32)]]`. + +The data signer can be recovered with xref:api:utils.adoc#ECDSA-recover-bytes32-bytes-[`ECDSA.recover`], and its address compared to verify the signature. Most wallets will hash the data to sign and add the prefix '\x19Ethereum Signed Message:\n', so when attempting to recover the signer of an Ethereum signed message hash, you'll want to use xref:api:utils.adoc#MessageHashUtils-toEthSignedMessageHash-bytes32-[`toEthSignedMessageHash`]. + +[source,solidity] +---- +using ECDSA for bytes32; +using MessageHashUtils for bytes32; + +function _verify(bytes32 data, bytes memory signature, address account) internal pure returns (bool) { + return data + .toEthSignedMessageHash() + .recover(signature) == account; +} +---- + +WARNING: Getting signature verification right is not trivial: make sure you fully read and understand xref:api:utils.adoc#MessageHashUtils[`MessageHashUtils`]'s and xref:api:utils.adoc#ECDSA[`ECDSA`]'s documentation. + +=== Verifying Merkle Proofs + +xref:api:utils.adoc#MerkleProof[`MerkleProof`] provides: + +* xref:api:utils.adoc#MerkleProof-verify-bytes32---bytes32-bytes32-[`verify`] - can prove that some value is part of a https://en.wikipedia.org/wiki/Merkle_tree[Merkle tree]. + +* xref:api:utils.adoc#MerkleProof-multiProofVerify-bytes32-bytes32---bytes32---bool---[`multiProofVerify`] - can prove multiple values are part of a Merkle tree. + +[[introspection]] +== Introspection + +In Solidity, it's frequently helpful to know whether or not a contract supports an interface you'd like to use. ERC165 is a standard that helps do runtime interface detection. Contracts provide helpers both for implementing ERC165 in your contracts and querying other contracts: + +* xref:api:utils.adoc#IERC165[`IERC165`] — this is the ERC165 interface that defines xref:api:utils.adoc#IERC165-supportsInterface-bytes4-[`supportsInterface`]. When implementing ERC165, you'll conform to this interface. +* xref:api:utils.adoc#ERC165[`ERC165`] — inherit this contract if you'd like to support interface detection using a lookup table in contract storage. You can register interfaces using xref:api:utils.adoc#ERC165-_registerInterface-bytes4-[`_registerInterface(bytes4)`]: check out example usage as part of the ERC721 implementation. +* xref:api:utils.adoc#ERC165Checker[`ERC165Checker`] — ERC165Checker simplifies the process of checking whether or not a contract supports an interface you care about. +* include with `using ERC165Checker for address;` +* xref:api:utils.adoc#ERC165Checker-_supportsInterface-address-bytes4-[`myAddress._supportsInterface(bytes4)`] +* xref:api:utils.adoc#ERC165Checker-_supportsAllInterfaces-address-bytes4---[`myAddress._supportsAllInterfaces(bytes4[\])`] + +[source,solidity] +---- +contract MyContract { + using ERC165Checker for address; + + bytes4 private InterfaceId_ERC721 = 0x80ac58cd; + + /** + * @dev transfer an ERC721 token from this contract to someone else + */ + function transferERC721( + address token, + address to, + uint256 tokenId + ) + public + { + require(token.supportsInterface(InterfaceId_ERC721), "IS_NOT_721_TOKEN"); + IERC721(token).transferFrom(address(this), to, tokenId); + } +} +---- + +[[math]] +== Math + +The most popular math related library OpenZeppelin Contracts provides is xref:api:utils.adoc#SafeMath[`SafeMath`], which provides mathematical functions that protect your contract from overflows and underflows. + +Include the contract with `using SafeMath for uint256;` and then call the functions: + +* `myNumber.add(otherNumber)` +* `myNumber.sub(otherNumber)` +* `myNumber.div(otherNumber)` +* `myNumber.mul(otherNumber)` +* `myNumber.mod(otherNumber)` + +Easy! + +[[payment]] +== Payment + +Want to split some payments between multiple people? Maybe you have an app that sends 30% of art purchases to the original creator and 70% of the profits to the current owner; you can build that with xref:api:finance.adoc#PaymentSplitter[`PaymentSplitter`]! + +In Solidity, there are some security concerns with blindly sending money to accounts, since it allows them to execute arbitrary code. You can read up on these security concerns in the https://consensys.github.io/smart-contract-best-practices/[Ethereum Smart Contract Best Practices] website. + +[[collections]] +== Collections + +If you need support for more powerful collections than Solidity's native arrays and mappings, take a look at xref:api:utils.adoc#EnumerableSet[`EnumerableSet`] and xref:api:utils.adoc#EnumerableMap[`EnumerableMap`]. They are similar to mappings in that they store and remove elements in constant time and don't allow for repeated entries, but they also support _enumeration_, which means you can easily query all stored entries both on and off-chain. + +[[misc]] +== Misc + +=== Base64 + +xref:api:utils.adoc#Base64[`Base64`] util allows you to transform `bytes32` data into its Base64 `string` representation. + +This is especially useful for building URL-safe tokenURIs for both xref:api:token/ERC721.adoc#IERC721Metadata-tokenURI-uint256-[`ERC721`] or xref:api:token/ERC1155.adoc#IERC1155MetadataURI-uri-uint256-[`ERC1155`]. This library provides a clever way to serve URL-safe https://developer.mozilla.org/docs/Web/HTTP/Basics_of_HTTP/Data_URIs/[Data URI] compliant strings to serve on-chain data structures. + +Here is an example to send JSON Metadata through a Base64 Data URI using an ERC721: + +[source, solidity] +---- +// contracts/My721Token.sol +// SPDX-License-Identifier: MIT + +import {ERC721} from "@openzeppelin/contracts/token/ERC721/ERC721.sol"; +import {Strings} from "@openzeppelin/contracts/utils/Strings.sol"; +import {Base64} from "@openzeppelin/contracts/utils/Base64.sol"; + +contract My721Token is ERC721 { + using Strings for uint256; + + constructor() ERC721("My721Token", "MTK") {} + + ... + + function tokenURI(uint256 tokenId) + public + pure + override + returns (string memory) + { + bytes memory dataURI = abi.encodePacked( + '{', + '"name": "My721Token #', tokenId.toString(), '"', + // Replace with extra ERC721 Metadata properties + '}' + ); + + return string( + abi.encodePacked( + "data:application/json;base64,", + Base64.encode(dataURI) + ) + ); + } +} +---- + +=== Multicall + +The `Multicall` abstract contract comes with a `multicall` function that bundles together multiple calls in a single external call. With it, external accounts may perform atomic operations comprising several function calls. This is not only useful for EOAs to make multiple calls in a single transaction, it's also a way to revert a previous call if a later one fails. + +Consider this dummy contract: + +[source,solidity] +---- +// contracts/Box.sol +// SPDX-License-Identifier: MIT +pragma solidity ^0.8.20; + +import "@openzeppelin/contracts/utils/Multicall.sol"; + +contract Box is Multicall { + function foo() public { + ... + } + + function bar() public { + ... + } +} +---- + +This is how to call the `multicall` function using Truffle, allowing `foo` and `bar` to be called in a single transaction: +[source,javascript] +---- +// scripts/foobar.js + +const Box = artifacts.require('Box'); +const instance = await Box.new(); + +await instance.multicall([ + instance.contract.methods.foo().encodeABI(), + instance.contract.methods.bar().encodeABI() +]); +---- diff --git a/docs/modules/ROOT/pages/wizard.adoc b/docs/modules/ROOT/pages/wizard.adoc new file mode 100644 index 000000000..262505378 --- /dev/null +++ b/docs/modules/ROOT/pages/wizard.adoc @@ -0,0 +1,15 @@ += Contracts Wizard +:page-notoc: + +Not sure where to start? Use the interactive generator below to bootstrap your +contract and learn about the components offered in OpenZeppelin Contracts. + +TIP: Place the resulting contract in your `contracts` directory in order to compile it with a tool like Hardhat or Truffle. Consider reading our guide on xref:learn::developing-smart-contracts.adoc[Developing Smart Contracts] for more guidance! + +++++ + + + +++++ + + diff --git a/docs/modules/api/examples/ERC4626Fees.sol b/docs/modules/api/examples/ERC4626Fees.sol new file mode 100644 index 000000000..b508efe4f --- /dev/null +++ b/docs/modules/api/examples/ERC4626Fees.sol @@ -0,0 +1,103 @@ +// SPDX-License-Identifier: MIT + +pragma solidity ^0.8.20; + +import {IERC20} from "@openzeppelin/contracts/token/ERC20/IERC20.sol"; +import {ERC4626} from "@openzeppelin/contracts/token/ERC20/extensions/ERC4626.sol"; +import {SafeERC20} from "@openzeppelin/contracts/token/ERC20/utils/SafeERC20.sol"; +import {Math} from "@openzeppelin/contracts/utils/math/Math.sol"; + +/// @dev ERC4626 vault with entry/exit fees expressed in https://en.wikipedia.org/wiki/Basis_point[basis point (bp)]. +abstract contract ERC4626Fees is ERC4626 { + using Math for uint256; + + uint256 private constant _BASIS_POINT_SCALE = 1e4; + + // === Overrides === + + /// @dev Preview taking an entry fee on deposit. See {IERC4626-previewDeposit}. + function previewDeposit(uint256 assets) public view virtual override returns (uint256) { + uint256 fee = _feeOnTotal(assets, _entryFeeBasisPoints()); + return super.previewDeposit(assets - fee); + } + + /// @dev Preview adding an entry fee on mint. See {IERC4626-previewMint}. + function previewMint(uint256 shares) public view virtual override returns (uint256) { + uint256 assets = super.previewMint(shares); + return assets + _feeOnRaw(assets, _entryFeeBasisPoints()); + } + + /// @dev Preview adding an exit fee on withdraw. See {IERC4626-previewWithdraw}. + function previewWithdraw(uint256 assets) public view virtual override returns (uint256) { + uint256 fee = _feeOnRaw(assets, _exitFeeBasisPoints()); + return super.previewWithdraw(assets + fee); + } + + /// @dev Preview taking an exit fee on redeem. See {IERC4626-previewRedeem}. + function previewRedeem(uint256 shares) public view virtual override returns (uint256) { + uint256 assets = super.previewRedeem(shares); + return assets - _feeOnTotal(assets, _exitFeeBasisPoints()); + } + + /// @dev Send entry fee to {_entryFeeRecipient}. See {IERC4626-_deposit}. + function _deposit(address caller, address receiver, uint256 assets, uint256 shares) internal virtual override { + uint256 fee = _feeOnTotal(assets, _entryFeeBasisPoints()); + address recipient = _entryFeeRecipient(); + + super._deposit(caller, receiver, assets, shares); + + if (fee > 0 && recipient != address(this)) { + SafeERC20.safeTransfer(IERC20(asset()), recipient, fee); + } + } + + /// @dev Send exit fee to {_exitFeeRecipient}. See {IERC4626-_deposit}. + function _withdraw( + address caller, + address receiver, + address owner, + uint256 assets, + uint256 shares + ) internal virtual override { + uint256 fee = _feeOnRaw(assets, _exitFeeBasisPoints()); + address recipient = _exitFeeRecipient(); + + super._withdraw(caller, receiver, owner, assets, shares); + + if (fee > 0 && recipient != address(this)) { + SafeERC20.safeTransfer(IERC20(asset()), recipient, fee); + } + } + + // === Fee configuration === + + function _entryFeeBasisPoints() internal view virtual returns (uint256) { + return 0; // replace with e.g. 100 for 1% + } + + function _exitFeeBasisPoints() internal view virtual returns (uint256) { + return 0; // replace with e.g. 100 for 1% + } + + function _entryFeeRecipient() internal view virtual returns (address) { + return address(0); // replace with e.g. a treasury address + } + + function _exitFeeRecipient() internal view virtual returns (address) { + return address(0); // replace with e.g. a treasury address + } + + // === Fee operations === + + /// @dev Calculates the fees that should be added to an amount `assets` that does not already include fees. + /// Used in {IERC4626-mint} and {IERC4626-withdraw} operations. + function _feeOnRaw(uint256 assets, uint256 feeBasisPoints) private pure returns (uint256) { + return assets.mulDiv(feeBasisPoints, _BASIS_POINT_SCALE, Math.Rounding.Ceil); + } + + /// @dev Calculates the fee part of an amount `assets` that already includes fees. + /// Used in {IERC4626-deposit} and {IERC4626-redeem} operations. + function _feeOnTotal(uint256 assets, uint256 feeBasisPoints) private pure returns (uint256) { + return assets.mulDiv(feeBasisPoints, feeBasisPoints + _BASIS_POINT_SCALE, Math.Rounding.Ceil); + } +} diff --git a/docs/modules/api/examples/governance/MyGovernor.sol b/docs/modules/api/examples/governance/MyGovernor.sol new file mode 100644 index 000000000..b4e69d764 --- /dev/null +++ b/docs/modules/api/examples/governance/MyGovernor.sol @@ -0,0 +1,81 @@ +// SPDX-License-Identifier: MIT +pragma solidity ^0.8.20; + +import {IGovernor, Governor} from "@openzeppelin/contracts/governance/Governor.sol"; +import {GovernorCountingSimple} from "@openzeppelin/contracts/governance/extensions/GovernorCountingSimple.sol"; +import {GovernorVotes} from "@openzeppelin/contracts/governance/extensions/GovernorVotes.sol"; +import {GovernorVotesQuorumFraction} from "@openzeppelin/contracts/governance/extensions/GovernorVotesQuorumFraction.sol"; +import {GovernorTimelockControl} from "@openzeppelin/contracts/governance/extensions/GovernorTimelockControl.sol"; +import {TimelockController} from "@openzeppelin/contracts/governance/TimelockController.sol"; +import {IVotes} from "@openzeppelin/contracts/governance/utils/IVotes.sol"; +import {IERC165} from "@openzeppelin/contracts/interfaces/IERC165.sol"; + +contract MyGovernor is + Governor, + GovernorCountingSimple, + GovernorVotes, + GovernorVotesQuorumFraction, + GovernorTimelockControl +{ + constructor( + IVotes _token, + TimelockController _timelock + ) Governor("MyGovernor") GovernorVotes(_token) GovernorVotesQuorumFraction(4) GovernorTimelockControl(_timelock) {} + + function votingDelay() public pure override returns (uint256) { + return 7200; // 1 day + } + + function votingPeriod() public pure override returns (uint256) { + return 50400; // 1 week + } + + function proposalThreshold() public pure override returns (uint256) { + return 0; + } + + // The functions below are overrides required by Solidity. + + function state(uint256 proposalId) public view override(Governor, GovernorTimelockControl) returns (ProposalState) { + return super.state(proposalId); + } + + function proposalNeedsQueuing( + uint256 proposalId + ) public view virtual override(Governor, GovernorTimelockControl) returns (bool) { + return super.proposalNeedsQueuing(proposalId); + } + + function _queueOperations( + uint256 proposalId, + address[] memory targets, + uint256[] memory values, + bytes[] memory calldatas, + bytes32 descriptionHash + ) internal override(Governor, GovernorTimelockControl) returns (uint48) { + return super._queueOperations(proposalId, targets, values, calldatas, descriptionHash); + } + + function _executeOperations( + uint256 proposalId, + address[] memory targets, + uint256[] memory values, + bytes[] memory calldatas, + bytes32 descriptionHash + ) internal override(Governor, GovernorTimelockControl) { + super._executeOperations(proposalId, targets, values, calldatas, descriptionHash); + } + + function _cancel( + address[] memory targets, + uint256[] memory values, + bytes[] memory calldatas, + bytes32 descriptionHash + ) internal override(Governor, GovernorTimelockControl) returns (uint256) { + return super._cancel(targets, values, calldatas, descriptionHash); + } + + function _executor() internal view override(Governor, GovernorTimelockControl) returns (address) { + return super._executor(); + } +} diff --git a/docs/modules/api/examples/governance/MyToken.sol b/docs/modules/api/examples/governance/MyToken.sol new file mode 100644 index 000000000..e358ec207 --- /dev/null +++ b/docs/modules/api/examples/governance/MyToken.sol @@ -0,0 +1,21 @@ +// SPDX-License-Identifier: MIT +pragma solidity ^0.8.20; + +import {ERC20} from "@openzeppelin/contracts/token/ERC20/ERC20.sol"; +import {ERC20Permit} from "@openzeppelin/contracts/token/ERC20/extensions/ERC20Permit.sol"; +import {ERC20Votes} from "@openzeppelin/contracts/token/ERC20/extensions/ERC20Votes.sol"; +import {Nonces} from "@openzeppelin/contracts/utils/Nonces.sol"; + +contract MyToken is ERC20, ERC20Permit, ERC20Votes { + constructor() ERC20("MyToken", "MTK") ERC20Permit("MyToken") {} + + // The functions below are overrides required by Solidity. + + function _update(address from, address to, uint256 amount) internal override(ERC20, ERC20Votes) { + super._update(from, to, amount); + } + + function nonces(address owner) public view virtual override(ERC20Permit, Nonces) returns (uint256) { + return super.nonces(owner); + } +} diff --git a/docs/modules/api/examples/governance/MyTokenTimestampBased.sol b/docs/modules/api/examples/governance/MyTokenTimestampBased.sol new file mode 100644 index 000000000..87d271062 --- /dev/null +++ b/docs/modules/api/examples/governance/MyTokenTimestampBased.sol @@ -0,0 +1,32 @@ +// SPDX-License-Identifier: MIT +pragma solidity ^0.8.20; + +import {ERC20} from "@openzeppelin/contracts/token/ERC20/ERC20.sol"; +import {ERC20Permit} from "@openzeppelin/contracts/token/ERC20/extensions/ERC20Permit.sol"; +import {ERC20Votes} from "@openzeppelin/contracts/token/ERC20/extensions/ERC20Votes.sol"; +import {Nonces} from "@openzeppelin/contracts/utils/Nonces.sol"; + +contract MyTokenTimestampBased is ERC20, ERC20Permit, ERC20Votes { + constructor() ERC20("MyTokenTimestampBased", "MTK") ERC20Permit("MyTokenTimestampBased") {} + + // Overrides IERC6372 functions to make the token & governor timestamp-based + + function clock() public view override returns (uint48) { + return uint48(block.timestamp); + } + + // solhint-disable-next-line func-name-mixedcase + function CLOCK_MODE() public pure override returns (string memory) { + return "mode=timestamp"; + } + + // The functions below are overrides required by Solidity. + + function _update(address from, address to, uint256 amount) internal override(ERC20, ERC20Votes) { + super._update(from, to, amount); + } + + function nonces(address owner) public view virtual override(ERC20Permit, Nonces) returns (uint256) { + return super.nonces(owner); + } +} diff --git a/docs/modules/api/examples/governance/MyTokenWrapped.sol b/docs/modules/api/examples/governance/MyTokenWrapped.sol new file mode 100644 index 000000000..bdcc1f02b --- /dev/null +++ b/docs/modules/api/examples/governance/MyTokenWrapped.sol @@ -0,0 +1,28 @@ +// SPDX-License-Identifier: MIT +pragma solidity ^0.8.20; + +import {IERC20, ERC20} from "@openzeppelin/contracts/token/ERC20/ERC20.sol"; +import {ERC20Permit} from "@openzeppelin/contracts/token/ERC20/extensions/ERC20Permit.sol"; +import {ERC20Votes} from "@openzeppelin/contracts/token/ERC20/extensions/ERC20Votes.sol"; +import {ERC20Wrapper} from "@openzeppelin/contracts/token/ERC20/extensions/ERC20Wrapper.sol"; +import {Nonces} from "@openzeppelin/contracts/utils/Nonces.sol"; + +contract MyTokenWrapped is ERC20, ERC20Permit, ERC20Votes, ERC20Wrapper { + constructor( + IERC20 wrappedToken + ) ERC20("MyTokenWrapped", "MTK") ERC20Permit("MyTokenWrapped") ERC20Wrapper(wrappedToken) {} + + // The functions below are overrides required by Solidity. + + function decimals() public view override(ERC20, ERC20Wrapper) returns (uint8) { + return super.decimals(); + } + + function _update(address from, address to, uint256 amount) internal override(ERC20, ERC20Votes) { + super._update(from, to, amount); + } + + function nonces(address owner) public view virtual override(ERC20Permit, Nonces) returns (uint256) { + return super.nonces(owner); + } +} diff --git a/docs/modules/api/nav.adoc b/docs/modules/api/nav.adoc new file mode 100644 index 000000000..ac2ab659c --- /dev/null +++ b/docs/modules/api/nav.adoc @@ -0,0 +1,12 @@ +.API +* xref:access.adoc[Access] +* xref:token/common.adoc[Common (Tokens)] +* xref:token/ERC20.adoc[ERC 20] +* xref:token/ERC721.adoc[ERC 721] +* xref:token/ERC1155.adoc[ERC 1155] +* xref:finance.adoc[Finance] +* xref:governance.adoc[Governance] +* xref:interfaces.adoc[Interfaces] +* xref:metatx.adoc[Meta Transactions] +* xref:proxy.adoc[Proxy] +* xref:utils.adoc[Utils] diff --git a/docs/modules/api/pages/access.adoc b/docs/modules/api/pages/access.adoc new file mode 100644 index 000000000..f96488ea7 --- /dev/null +++ b/docs/modules/api/pages/access.adoc @@ -0,0 +1,2582 @@ +:github-icon: pass:[] +:AccessControl: pass:normal[xref:access.adoc#AccessControl[`AccessControl`]] +:Ownable: pass:normal[xref:access.adoc#Ownable[`Ownable`]] +:xref-Ownable-onlyOwner--: xref:access.adoc#Ownable-onlyOwner-- +:xref-Ownable-constructor-address-: xref:access.adoc#Ownable-constructor-address- +:xref-Ownable-owner--: xref:access.adoc#Ownable-owner-- +:xref-Ownable-_checkOwner--: xref:access.adoc#Ownable-_checkOwner-- +:xref-Ownable-renounceOwnership--: xref:access.adoc#Ownable-renounceOwnership-- +:xref-Ownable-transferOwnership-address-: xref:access.adoc#Ownable-transferOwnership-address- +:xref-Ownable-_transferOwnership-address-: xref:access.adoc#Ownable-_transferOwnership-address- +:xref-Ownable-OwnershipTransferred-address-address-: xref:access.adoc#Ownable-OwnershipTransferred-address-address- +:xref-Ownable-OwnableUnauthorizedAccount-address-: xref:access.adoc#Ownable-OwnableUnauthorizedAccount-address- +:xref-Ownable-OwnableInvalidOwner-address-: xref:access.adoc#Ownable-OwnableInvalidOwner-address- +:xref-Ownable2Step-pendingOwner--: xref:access.adoc#Ownable2Step-pendingOwner-- +:xref-Ownable2Step-transferOwnership-address-: xref:access.adoc#Ownable2Step-transferOwnership-address- +:xref-Ownable2Step-_transferOwnership-address-: xref:access.adoc#Ownable2Step-_transferOwnership-address- +:xref-Ownable2Step-acceptOwnership--: xref:access.adoc#Ownable2Step-acceptOwnership-- +:xref-Ownable-owner--: xref:access.adoc#Ownable-owner-- +:xref-Ownable-_checkOwner--: xref:access.adoc#Ownable-_checkOwner-- +:xref-Ownable-renounceOwnership--: xref:access.adoc#Ownable-renounceOwnership-- +:xref-Ownable2Step-OwnershipTransferStarted-address-address-: xref:access.adoc#Ownable2Step-OwnershipTransferStarted-address-address- +:xref-Ownable-OwnershipTransferred-address-address-: xref:access.adoc#Ownable-OwnershipTransferred-address-address- +:xref-Ownable-OwnableUnauthorizedAccount-address-: xref:access.adoc#Ownable-OwnableUnauthorizedAccount-address- +:xref-Ownable-OwnableInvalidOwner-address-: xref:access.adoc#Ownable-OwnableInvalidOwner-address- +:xref-IAccessControl-hasRole-bytes32-address-: xref:access.adoc#IAccessControl-hasRole-bytes32-address- +:xref-IAccessControl-getRoleAdmin-bytes32-: xref:access.adoc#IAccessControl-getRoleAdmin-bytes32- +:xref-IAccessControl-grantRole-bytes32-address-: xref:access.adoc#IAccessControl-grantRole-bytes32-address- +:xref-IAccessControl-revokeRole-bytes32-address-: xref:access.adoc#IAccessControl-revokeRole-bytes32-address- +:xref-IAccessControl-renounceRole-bytes32-address-: xref:access.adoc#IAccessControl-renounceRole-bytes32-address- +:xref-IAccessControl-RoleAdminChanged-bytes32-bytes32-bytes32-: xref:access.adoc#IAccessControl-RoleAdminChanged-bytes32-bytes32-bytes32- +:xref-IAccessControl-RoleGranted-bytes32-address-address-: xref:access.adoc#IAccessControl-RoleGranted-bytes32-address-address- +:xref-IAccessControl-RoleRevoked-bytes32-address-address-: xref:access.adoc#IAccessControl-RoleRevoked-bytes32-address-address- +:xref-IAccessControl-AccessControlUnauthorizedAccount-address-bytes32-: xref:access.adoc#IAccessControl-AccessControlUnauthorizedAccount-address-bytes32- +:xref-IAccessControl-AccessControlBadConfirmation--: xref:access.adoc#IAccessControl-AccessControlBadConfirmation-- +:AccessControl-_setRoleAdmin: pass:normal[xref:access.adoc#AccessControl-_setRoleAdmin-bytes32-bytes32-[`AccessControl._setRoleAdmin`]] +:AccessControlEnumerable: pass:normal[xref:access.adoc#AccessControlEnumerable[`AccessControlEnumerable`]] +:AccessControlDefaultAdminRules: pass:normal[xref:access.adoc#AccessControlDefaultAdminRules[`AccessControlDefaultAdminRules`]] +:xref-AccessControl-onlyRole-bytes32-: xref:access.adoc#AccessControl-onlyRole-bytes32- +:xref-AccessControl-supportsInterface-bytes4-: xref:access.adoc#AccessControl-supportsInterface-bytes4- +:xref-AccessControl-hasRole-bytes32-address-: xref:access.adoc#AccessControl-hasRole-bytes32-address- +:xref-AccessControl-_checkRole-bytes32-: xref:access.adoc#AccessControl-_checkRole-bytes32- +:xref-AccessControl-_checkRole-bytes32-address-: xref:access.adoc#AccessControl-_checkRole-bytes32-address- +:xref-AccessControl-getRoleAdmin-bytes32-: xref:access.adoc#AccessControl-getRoleAdmin-bytes32- +:xref-AccessControl-grantRole-bytes32-address-: xref:access.adoc#AccessControl-grantRole-bytes32-address- +:xref-AccessControl-revokeRole-bytes32-address-: xref:access.adoc#AccessControl-revokeRole-bytes32-address- +:xref-AccessControl-renounceRole-bytes32-address-: xref:access.adoc#AccessControl-renounceRole-bytes32-address- +:xref-AccessControl-_setRoleAdmin-bytes32-bytes32-: xref:access.adoc#AccessControl-_setRoleAdmin-bytes32-bytes32- +:xref-AccessControl-_grantRole-bytes32-address-: xref:access.adoc#AccessControl-_grantRole-bytes32-address- +:xref-AccessControl-_revokeRole-bytes32-address-: xref:access.adoc#AccessControl-_revokeRole-bytes32-address- +:xref-IAccessControl-RoleAdminChanged-bytes32-bytes32-bytes32-: xref:access.adoc#IAccessControl-RoleAdminChanged-bytes32-bytes32-bytes32- +:xref-IAccessControl-RoleGranted-bytes32-address-address-: xref:access.adoc#IAccessControl-RoleGranted-bytes32-address-address- +:xref-IAccessControl-RoleRevoked-bytes32-address-address-: xref:access.adoc#IAccessControl-RoleRevoked-bytes32-address-address- +:xref-IAccessControl-AccessControlUnauthorizedAccount-address-bytes32-: xref:access.adoc#IAccessControl-AccessControlUnauthorizedAccount-address-bytes32- +:xref-IAccessControl-AccessControlBadConfirmation--: xref:access.adoc#IAccessControl-AccessControlBadConfirmation-- +:IERC165-supportsInterface: pass:normal[xref:utils.adoc#IERC165-supportsInterface-bytes4-[`IERC165.supportsInterface`]] +:xref-IAccessControlEnumerable-getRoleMember-bytes32-uint256-: xref:access.adoc#IAccessControlEnumerable-getRoleMember-bytes32-uint256- +:xref-IAccessControlEnumerable-getRoleMemberCount-bytes32-: xref:access.adoc#IAccessControlEnumerable-getRoleMemberCount-bytes32- +:xref-IAccessControl-hasRole-bytes32-address-: xref:access.adoc#IAccessControl-hasRole-bytes32-address- +:xref-IAccessControl-getRoleAdmin-bytes32-: xref:access.adoc#IAccessControl-getRoleAdmin-bytes32- +:xref-IAccessControl-grantRole-bytes32-address-: xref:access.adoc#IAccessControl-grantRole-bytes32-address- +:xref-IAccessControl-revokeRole-bytes32-address-: xref:access.adoc#IAccessControl-revokeRole-bytes32-address- +:xref-IAccessControl-renounceRole-bytes32-address-: xref:access.adoc#IAccessControl-renounceRole-bytes32-address- +:xref-IAccessControl-RoleAdminChanged-bytes32-bytes32-bytes32-: xref:access.adoc#IAccessControl-RoleAdminChanged-bytes32-bytes32-bytes32- +:xref-IAccessControl-RoleGranted-bytes32-address-address-: xref:access.adoc#IAccessControl-RoleGranted-bytes32-address-address- +:xref-IAccessControl-RoleRevoked-bytes32-address-address-: xref:access.adoc#IAccessControl-RoleRevoked-bytes32-address-address- +:xref-IAccessControl-AccessControlUnauthorizedAccount-address-bytes32-: xref:access.adoc#IAccessControl-AccessControlUnauthorizedAccount-address-bytes32- +:xref-IAccessControl-AccessControlBadConfirmation--: xref:access.adoc#IAccessControl-AccessControlBadConfirmation-- +:AccessControl: pass:normal[xref:access.adoc#AccessControl[`AccessControl`]] +:xref-AccessControlEnumerable-supportsInterface-bytes4-: xref:access.adoc#AccessControlEnumerable-supportsInterface-bytes4- +:xref-AccessControlEnumerable-getRoleMember-bytes32-uint256-: xref:access.adoc#AccessControlEnumerable-getRoleMember-bytes32-uint256- +:xref-AccessControlEnumerable-getRoleMemberCount-bytes32-: xref:access.adoc#AccessControlEnumerable-getRoleMemberCount-bytes32- +:xref-AccessControlEnumerable-_grantRole-bytes32-address-: xref:access.adoc#AccessControlEnumerable-_grantRole-bytes32-address- +:xref-AccessControlEnumerable-_revokeRole-bytes32-address-: xref:access.adoc#AccessControlEnumerable-_revokeRole-bytes32-address- +:xref-AccessControl-hasRole-bytes32-address-: xref:access.adoc#AccessControl-hasRole-bytes32-address- +:xref-AccessControl-_checkRole-bytes32-: xref:access.adoc#AccessControl-_checkRole-bytes32- +:xref-AccessControl-_checkRole-bytes32-address-: xref:access.adoc#AccessControl-_checkRole-bytes32-address- +:xref-AccessControl-getRoleAdmin-bytes32-: xref:access.adoc#AccessControl-getRoleAdmin-bytes32- +:xref-AccessControl-grantRole-bytes32-address-: xref:access.adoc#AccessControl-grantRole-bytes32-address- +:xref-AccessControl-revokeRole-bytes32-address-: xref:access.adoc#AccessControl-revokeRole-bytes32-address- +:xref-AccessControl-renounceRole-bytes32-address-: xref:access.adoc#AccessControl-renounceRole-bytes32-address- +:xref-AccessControl-_setRoleAdmin-bytes32-bytes32-: xref:access.adoc#AccessControl-_setRoleAdmin-bytes32-bytes32- +:xref-IAccessControl-RoleAdminChanged-bytes32-bytes32-bytes32-: xref:access.adoc#IAccessControl-RoleAdminChanged-bytes32-bytes32-bytes32- +:xref-IAccessControl-RoleGranted-bytes32-address-address-: xref:access.adoc#IAccessControl-RoleGranted-bytes32-address-address- +:xref-IAccessControl-RoleRevoked-bytes32-address-address-: xref:access.adoc#IAccessControl-RoleRevoked-bytes32-address-address- +:xref-IAccessControl-AccessControlUnauthorizedAccount-address-bytes32-: xref:access.adoc#IAccessControl-AccessControlUnauthorizedAccount-address-bytes32- +:xref-IAccessControl-AccessControlBadConfirmation--: xref:access.adoc#IAccessControl-AccessControlBadConfirmation-- +:IERC165-supportsInterface: pass:normal[xref:utils.adoc#IERC165-supportsInterface-bytes4-[`IERC165.supportsInterface`]] +:AccessControl-_grantRole: pass:normal[xref:access.adoc#AccessControl-_grantRole-bytes32-address-[`AccessControl._grantRole`]] +:AccessControl-_revokeRole: pass:normal[xref:access.adoc#AccessControl-_revokeRole-bytes32-address-[`AccessControl._revokeRole`]] +:xref-IAccessControlDefaultAdminRules-defaultAdmin--: xref:access.adoc#IAccessControlDefaultAdminRules-defaultAdmin-- +:xref-IAccessControlDefaultAdminRules-pendingDefaultAdmin--: xref:access.adoc#IAccessControlDefaultAdminRules-pendingDefaultAdmin-- +:xref-IAccessControlDefaultAdminRules-defaultAdminDelay--: xref:access.adoc#IAccessControlDefaultAdminRules-defaultAdminDelay-- +:xref-IAccessControlDefaultAdminRules-pendingDefaultAdminDelay--: xref:access.adoc#IAccessControlDefaultAdminRules-pendingDefaultAdminDelay-- +:xref-IAccessControlDefaultAdminRules-beginDefaultAdminTransfer-address-: xref:access.adoc#IAccessControlDefaultAdminRules-beginDefaultAdminTransfer-address- +:xref-IAccessControlDefaultAdminRules-cancelDefaultAdminTransfer--: xref:access.adoc#IAccessControlDefaultAdminRules-cancelDefaultAdminTransfer-- +:xref-IAccessControlDefaultAdminRules-acceptDefaultAdminTransfer--: xref:access.adoc#IAccessControlDefaultAdminRules-acceptDefaultAdminTransfer-- +:xref-IAccessControlDefaultAdminRules-changeDefaultAdminDelay-uint48-: xref:access.adoc#IAccessControlDefaultAdminRules-changeDefaultAdminDelay-uint48- +:xref-IAccessControlDefaultAdminRules-rollbackDefaultAdminDelay--: xref:access.adoc#IAccessControlDefaultAdminRules-rollbackDefaultAdminDelay-- +:xref-IAccessControlDefaultAdminRules-defaultAdminDelayIncreaseWait--: xref:access.adoc#IAccessControlDefaultAdminRules-defaultAdminDelayIncreaseWait-- +:xref-IAccessControl-hasRole-bytes32-address-: xref:access.adoc#IAccessControl-hasRole-bytes32-address- +:xref-IAccessControl-getRoleAdmin-bytes32-: xref:access.adoc#IAccessControl-getRoleAdmin-bytes32- +:xref-IAccessControl-grantRole-bytes32-address-: xref:access.adoc#IAccessControl-grantRole-bytes32-address- +:xref-IAccessControl-revokeRole-bytes32-address-: xref:access.adoc#IAccessControl-revokeRole-bytes32-address- +:xref-IAccessControl-renounceRole-bytes32-address-: xref:access.adoc#IAccessControl-renounceRole-bytes32-address- +:xref-IAccessControlDefaultAdminRules-DefaultAdminTransferScheduled-address-uint48-: xref:access.adoc#IAccessControlDefaultAdminRules-DefaultAdminTransferScheduled-address-uint48- +:xref-IAccessControlDefaultAdminRules-DefaultAdminTransferCanceled--: xref:access.adoc#IAccessControlDefaultAdminRules-DefaultAdminTransferCanceled-- +:xref-IAccessControlDefaultAdminRules-DefaultAdminDelayChangeScheduled-uint48-uint48-: xref:access.adoc#IAccessControlDefaultAdminRules-DefaultAdminDelayChangeScheduled-uint48-uint48- +:xref-IAccessControlDefaultAdminRules-DefaultAdminDelayChangeCanceled--: xref:access.adoc#IAccessControlDefaultAdminRules-DefaultAdminDelayChangeCanceled-- +:xref-IAccessControl-RoleAdminChanged-bytes32-bytes32-bytes32-: xref:access.adoc#IAccessControl-RoleAdminChanged-bytes32-bytes32-bytes32- +:xref-IAccessControl-RoleGranted-bytes32-address-address-: xref:access.adoc#IAccessControl-RoleGranted-bytes32-address-address- +:xref-IAccessControl-RoleRevoked-bytes32-address-address-: xref:access.adoc#IAccessControl-RoleRevoked-bytes32-address-address- +:xref-IAccessControlDefaultAdminRules-AccessControlInvalidDefaultAdmin-address-: xref:access.adoc#IAccessControlDefaultAdminRules-AccessControlInvalidDefaultAdmin-address- +:xref-IAccessControlDefaultAdminRules-AccessControlEnforcedDefaultAdminRules--: xref:access.adoc#IAccessControlDefaultAdminRules-AccessControlEnforcedDefaultAdminRules-- +:xref-IAccessControlDefaultAdminRules-AccessControlEnforcedDefaultAdminDelay-uint48-: xref:access.adoc#IAccessControlDefaultAdminRules-AccessControlEnforcedDefaultAdminDelay-uint48- +:xref-IAccessControl-AccessControlUnauthorizedAccount-address-bytes32-: xref:access.adoc#IAccessControl-AccessControlUnauthorizedAccount-address-bytes32- +:xref-IAccessControl-AccessControlBadConfirmation--: xref:access.adoc#IAccessControl-AccessControlBadConfirmation-- +:AccessControl: pass:normal[xref:access.adoc#AccessControl[`AccessControl`]] +:AccessControl: pass:normal[xref:access.adoc#AccessControl[`AccessControl`]] +:xref-AccessControlDefaultAdminRules-constructor-uint48-address-: xref:access.adoc#AccessControlDefaultAdminRules-constructor-uint48-address- +:xref-AccessControlDefaultAdminRules-supportsInterface-bytes4-: xref:access.adoc#AccessControlDefaultAdminRules-supportsInterface-bytes4- +:xref-AccessControlDefaultAdminRules-owner--: xref:access.adoc#AccessControlDefaultAdminRules-owner-- +:xref-AccessControlDefaultAdminRules-grantRole-bytes32-address-: xref:access.adoc#AccessControlDefaultAdminRules-grantRole-bytes32-address- +:xref-AccessControlDefaultAdminRules-revokeRole-bytes32-address-: xref:access.adoc#AccessControlDefaultAdminRules-revokeRole-bytes32-address- +:xref-AccessControlDefaultAdminRules-renounceRole-bytes32-address-: xref:access.adoc#AccessControlDefaultAdminRules-renounceRole-bytes32-address- +:xref-AccessControlDefaultAdminRules-_grantRole-bytes32-address-: xref:access.adoc#AccessControlDefaultAdminRules-_grantRole-bytes32-address- +:xref-AccessControlDefaultAdminRules-_revokeRole-bytes32-address-: xref:access.adoc#AccessControlDefaultAdminRules-_revokeRole-bytes32-address- +:xref-AccessControlDefaultAdminRules-_setRoleAdmin-bytes32-bytes32-: xref:access.adoc#AccessControlDefaultAdminRules-_setRoleAdmin-bytes32-bytes32- +:xref-AccessControlDefaultAdminRules-defaultAdmin--: xref:access.adoc#AccessControlDefaultAdminRules-defaultAdmin-- +:xref-AccessControlDefaultAdminRules-pendingDefaultAdmin--: xref:access.adoc#AccessControlDefaultAdminRules-pendingDefaultAdmin-- +:xref-AccessControlDefaultAdminRules-defaultAdminDelay--: xref:access.adoc#AccessControlDefaultAdminRules-defaultAdminDelay-- +:xref-AccessControlDefaultAdminRules-pendingDefaultAdminDelay--: xref:access.adoc#AccessControlDefaultAdminRules-pendingDefaultAdminDelay-- +:xref-AccessControlDefaultAdminRules-defaultAdminDelayIncreaseWait--: xref:access.adoc#AccessControlDefaultAdminRules-defaultAdminDelayIncreaseWait-- +:xref-AccessControlDefaultAdminRules-beginDefaultAdminTransfer-address-: xref:access.adoc#AccessControlDefaultAdminRules-beginDefaultAdminTransfer-address- +:xref-AccessControlDefaultAdminRules-_beginDefaultAdminTransfer-address-: xref:access.adoc#AccessControlDefaultAdminRules-_beginDefaultAdminTransfer-address- +:xref-AccessControlDefaultAdminRules-cancelDefaultAdminTransfer--: xref:access.adoc#AccessControlDefaultAdminRules-cancelDefaultAdminTransfer-- +:xref-AccessControlDefaultAdminRules-_cancelDefaultAdminTransfer--: xref:access.adoc#AccessControlDefaultAdminRules-_cancelDefaultAdminTransfer-- +:xref-AccessControlDefaultAdminRules-acceptDefaultAdminTransfer--: xref:access.adoc#AccessControlDefaultAdminRules-acceptDefaultAdminTransfer-- +:xref-AccessControlDefaultAdminRules-_acceptDefaultAdminTransfer--: xref:access.adoc#AccessControlDefaultAdminRules-_acceptDefaultAdminTransfer-- +:xref-AccessControlDefaultAdminRules-changeDefaultAdminDelay-uint48-: xref:access.adoc#AccessControlDefaultAdminRules-changeDefaultAdminDelay-uint48- +:xref-AccessControlDefaultAdminRules-_changeDefaultAdminDelay-uint48-: xref:access.adoc#AccessControlDefaultAdminRules-_changeDefaultAdminDelay-uint48- +:xref-AccessControlDefaultAdminRules-rollbackDefaultAdminDelay--: xref:access.adoc#AccessControlDefaultAdminRules-rollbackDefaultAdminDelay-- +:xref-AccessControlDefaultAdminRules-_rollbackDefaultAdminDelay--: xref:access.adoc#AccessControlDefaultAdminRules-_rollbackDefaultAdminDelay-- +:xref-AccessControlDefaultAdminRules-_delayChangeWait-uint48-: xref:access.adoc#AccessControlDefaultAdminRules-_delayChangeWait-uint48- +:xref-AccessControl-hasRole-bytes32-address-: xref:access.adoc#AccessControl-hasRole-bytes32-address- +:xref-AccessControl-_checkRole-bytes32-: xref:access.adoc#AccessControl-_checkRole-bytes32- +:xref-AccessControl-_checkRole-bytes32-address-: xref:access.adoc#AccessControl-_checkRole-bytes32-address- +:xref-AccessControl-getRoleAdmin-bytes32-: xref:access.adoc#AccessControl-getRoleAdmin-bytes32- +:xref-IAccessControlDefaultAdminRules-DefaultAdminTransferScheduled-address-uint48-: xref:access.adoc#IAccessControlDefaultAdminRules-DefaultAdminTransferScheduled-address-uint48- +:xref-IAccessControlDefaultAdminRules-DefaultAdminTransferCanceled--: xref:access.adoc#IAccessControlDefaultAdminRules-DefaultAdminTransferCanceled-- +:xref-IAccessControlDefaultAdminRules-DefaultAdminDelayChangeScheduled-uint48-uint48-: xref:access.adoc#IAccessControlDefaultAdminRules-DefaultAdminDelayChangeScheduled-uint48-uint48- +:xref-IAccessControlDefaultAdminRules-DefaultAdminDelayChangeCanceled--: xref:access.adoc#IAccessControlDefaultAdminRules-DefaultAdminDelayChangeCanceled-- +:xref-IAccessControl-RoleAdminChanged-bytes32-bytes32-bytes32-: xref:access.adoc#IAccessControl-RoleAdminChanged-bytes32-bytes32-bytes32- +:xref-IAccessControl-RoleGranted-bytes32-address-address-: xref:access.adoc#IAccessControl-RoleGranted-bytes32-address-address- +:xref-IAccessControl-RoleRevoked-bytes32-address-address-: xref:access.adoc#IAccessControl-RoleRevoked-bytes32-address-address- +:xref-IAccessControlDefaultAdminRules-AccessControlInvalidDefaultAdmin-address-: xref:access.adoc#IAccessControlDefaultAdminRules-AccessControlInvalidDefaultAdmin-address- +:xref-IAccessControlDefaultAdminRules-AccessControlEnforcedDefaultAdminRules--: xref:access.adoc#IAccessControlDefaultAdminRules-AccessControlEnforcedDefaultAdminRules-- +:xref-IAccessControlDefaultAdminRules-AccessControlEnforcedDefaultAdminDelay-uint48-: xref:access.adoc#IAccessControlDefaultAdminRules-AccessControlEnforcedDefaultAdminDelay-uint48- +:xref-IAccessControl-AccessControlUnauthorizedAccount-address-bytes32-: xref:access.adoc#IAccessControl-AccessControlUnauthorizedAccount-address-bytes32- +:xref-IAccessControl-AccessControlBadConfirmation--: xref:access.adoc#IAccessControl-AccessControlBadConfirmation-- +:IERC165-supportsInterface: pass:normal[xref:utils.adoc#IERC165-supportsInterface-bytes4-[`IERC165.supportsInterface`]] +:IERC5313-owner: pass:normal[xref:interfaces.adoc#IERC5313-owner--[`IERC5313.owner`]] +:AccessControl-grantRole: pass:normal[xref:access.adoc#AccessControl-grantRole-bytes32-address-[`AccessControl.grantRole`]] +:AccessControl-revokeRole: pass:normal[xref:access.adoc#AccessControl-revokeRole-bytes32-address-[`AccessControl.revokeRole`]] +:AccessControl-renounceRole: pass:normal[xref:access.adoc#AccessControl-renounceRole-bytes32-address-[`AccessControl.renounceRole`]] +:AccessControl-_grantRole: pass:normal[xref:access.adoc#AccessControl-_grantRole-bytes32-address-[`AccessControl._grantRole`]] +:AccessControl-_revokeRole: pass:normal[xref:access.adoc#AccessControl-_revokeRole-bytes32-address-[`AccessControl._revokeRole`]] +:AccessControl-_setRoleAdmin: pass:normal[xref:access.adoc#AccessControl-_setRoleAdmin-bytes32-bytes32-[`AccessControl._setRoleAdmin`]] +:xref-IAuthority-canCall-address-address-bytes4-: xref:access.adoc#IAuthority-canCall-address-address-bytes4- +:AccessManaged: pass:normal[xref:access.adoc#AccessManaged[`AccessManaged`]] +:IAuthority: pass:normal[xref:access.adoc#IAuthority[`IAuthority`]] +:Ownable: pass:normal[xref:access.adoc#Ownable[`Ownable`]] +:AccessManager: pass:normal[xref:access.adoc#AccessManager[`AccessManager`]] +:Ownable: pass:normal[xref:access.adoc#Ownable[`Ownable`]] +:AccessManager: pass:normal[xref:access.adoc#AccessManager[`AccessManager`]] +:AccessManager: pass:normal[xref:access.adoc#AccessManager[`AccessManager`]] +:AccessManager: pass:normal[xref:access.adoc#AccessManager[`AccessManager`]] +:Ownable: pass:normal[xref:access.adoc#Ownable[`Ownable`]] +:AccessControl: pass:normal[xref:access.adoc#AccessControl[`AccessControl`]] +:AccessManager: pass:normal[xref:access.adoc#AccessManager[`AccessManager`]] +:Ownable-renounceOwnership: pass:normal[xref:access.adoc#Ownable-renounceOwnership--[`Ownable.renounceOwnership`]] +:AccessControl-renounceRole: pass:normal[xref:access.adoc#AccessControl-renounceRole-bytes32-address-[`AccessControl.renounceRole`]] +:xref-AccessManager-onlyAuthorized--: xref:access.adoc#AccessManager-onlyAuthorized-- +:xref-AccessManager-constructor-address-: xref:access.adoc#AccessManager-constructor-address- +:xref-AccessManager-canCall-address-address-bytes4-: xref:access.adoc#AccessManager-canCall-address-address-bytes4- +:xref-AccessManager-expiration--: xref:access.adoc#AccessManager-expiration-- +:xref-AccessManager-minSetback--: xref:access.adoc#AccessManager-minSetback-- +:xref-AccessManager-isTargetClosed-address-: xref:access.adoc#AccessManager-isTargetClosed-address- +:xref-AccessManager-getTargetFunctionRole-address-bytes4-: xref:access.adoc#AccessManager-getTargetFunctionRole-address-bytes4- +:xref-AccessManager-getTargetAdminDelay-address-: xref:access.adoc#AccessManager-getTargetAdminDelay-address- +:xref-AccessManager-getRoleAdmin-uint64-: xref:access.adoc#AccessManager-getRoleAdmin-uint64- +:xref-AccessManager-getRoleGuardian-uint64-: xref:access.adoc#AccessManager-getRoleGuardian-uint64- +:xref-AccessManager-getRoleGrantDelay-uint64-: xref:access.adoc#AccessManager-getRoleGrantDelay-uint64- +:xref-AccessManager-getAccess-uint64-address-: xref:access.adoc#AccessManager-getAccess-uint64-address- +:xref-AccessManager-hasRole-uint64-address-: xref:access.adoc#AccessManager-hasRole-uint64-address- +:xref-AccessManager-labelRole-uint64-string-: xref:access.adoc#AccessManager-labelRole-uint64-string- +:xref-AccessManager-grantRole-uint64-address-uint32-: xref:access.adoc#AccessManager-grantRole-uint64-address-uint32- +:xref-AccessManager-revokeRole-uint64-address-: xref:access.adoc#AccessManager-revokeRole-uint64-address- +:xref-AccessManager-renounceRole-uint64-address-: xref:access.adoc#AccessManager-renounceRole-uint64-address- +:xref-AccessManager-setRoleAdmin-uint64-uint64-: xref:access.adoc#AccessManager-setRoleAdmin-uint64-uint64- +:xref-AccessManager-setRoleGuardian-uint64-uint64-: xref:access.adoc#AccessManager-setRoleGuardian-uint64-uint64- +:xref-AccessManager-setGrantDelay-uint64-uint32-: xref:access.adoc#AccessManager-setGrantDelay-uint64-uint32- +:xref-AccessManager-_grantRole-uint64-address-uint32-uint32-: xref:access.adoc#AccessManager-_grantRole-uint64-address-uint32-uint32- +:xref-AccessManager-_revokeRole-uint64-address-: xref:access.adoc#AccessManager-_revokeRole-uint64-address- +:xref-AccessManager-_setRoleAdmin-uint64-uint64-: xref:access.adoc#AccessManager-_setRoleAdmin-uint64-uint64- +:xref-AccessManager-_setRoleGuardian-uint64-uint64-: xref:access.adoc#AccessManager-_setRoleGuardian-uint64-uint64- +:xref-AccessManager-_setGrantDelay-uint64-uint32-: xref:access.adoc#AccessManager-_setGrantDelay-uint64-uint32- +:xref-AccessManager-setTargetFunctionRole-address-bytes4---uint64-: xref:access.adoc#AccessManager-setTargetFunctionRole-address-bytes4---uint64- +:xref-AccessManager-_setTargetFunctionRole-address-bytes4-uint64-: xref:access.adoc#AccessManager-_setTargetFunctionRole-address-bytes4-uint64- +:xref-AccessManager-setTargetAdminDelay-address-uint32-: xref:access.adoc#AccessManager-setTargetAdminDelay-address-uint32- +:xref-AccessManager-_setTargetAdminDelay-address-uint32-: xref:access.adoc#AccessManager-_setTargetAdminDelay-address-uint32- +:xref-AccessManager-setTargetClosed-address-bool-: xref:access.adoc#AccessManager-setTargetClosed-address-bool- +:xref-AccessManager-_setTargetClosed-address-bool-: xref:access.adoc#AccessManager-_setTargetClosed-address-bool- +:xref-AccessManager-getSchedule-bytes32-: xref:access.adoc#AccessManager-getSchedule-bytes32- +:xref-AccessManager-getNonce-bytes32-: xref:access.adoc#AccessManager-getNonce-bytes32- +:xref-AccessManager-schedule-address-bytes-uint48-: xref:access.adoc#AccessManager-schedule-address-bytes-uint48- +:xref-AccessManager-execute-address-bytes-: xref:access.adoc#AccessManager-execute-address-bytes- +:xref-AccessManager-consumeScheduledOp-address-bytes-: xref:access.adoc#AccessManager-consumeScheduledOp-address-bytes- +:xref-AccessManager-_consumeScheduledOp-bytes32-: xref:access.adoc#AccessManager-_consumeScheduledOp-bytes32- +:xref-AccessManager-cancel-address-address-bytes-: xref:access.adoc#AccessManager-cancel-address-address-bytes- +:xref-AccessManager-hashOperation-address-address-bytes-: xref:access.adoc#AccessManager-hashOperation-address-address-bytes- +:xref-AccessManager-updateAuthority-address-address-: xref:access.adoc#AccessManager-updateAuthority-address-address- +:xref-Multicall-multicall-bytes---: xref:utils.adoc#Multicall-multicall-bytes--- +:xref-IAccessManager-OperationScheduled-bytes32-uint32-uint48-address-address-bytes-: xref:access.adoc#IAccessManager-OperationScheduled-bytes32-uint32-uint48-address-address-bytes- +:xref-IAccessManager-OperationExecuted-bytes32-uint32-: xref:access.adoc#IAccessManager-OperationExecuted-bytes32-uint32- +:xref-IAccessManager-OperationCanceled-bytes32-uint32-: xref:access.adoc#IAccessManager-OperationCanceled-bytes32-uint32- +:xref-IAccessManager-RoleLabel-uint64-string-: xref:access.adoc#IAccessManager-RoleLabel-uint64-string- +:xref-IAccessManager-RoleGranted-uint64-address-uint32-uint48-bool-: xref:access.adoc#IAccessManager-RoleGranted-uint64-address-uint32-uint48-bool- +:xref-IAccessManager-RoleRevoked-uint64-address-: xref:access.adoc#IAccessManager-RoleRevoked-uint64-address- +:xref-IAccessManager-RoleAdminChanged-uint64-uint64-: xref:access.adoc#IAccessManager-RoleAdminChanged-uint64-uint64- +:xref-IAccessManager-RoleGuardianChanged-uint64-uint64-: xref:access.adoc#IAccessManager-RoleGuardianChanged-uint64-uint64- +:xref-IAccessManager-RoleGrantDelayChanged-uint64-uint32-uint48-: xref:access.adoc#IAccessManager-RoleGrantDelayChanged-uint64-uint32-uint48- +:xref-IAccessManager-TargetClosed-address-bool-: xref:access.adoc#IAccessManager-TargetClosed-address-bool- +:xref-IAccessManager-TargetFunctionRoleUpdated-address-bytes4-uint64-: xref:access.adoc#IAccessManager-TargetFunctionRoleUpdated-address-bytes4-uint64- +:xref-IAccessManager-TargetAdminDelayUpdated-address-uint32-uint48-: xref:access.adoc#IAccessManager-TargetAdminDelayUpdated-address-uint32-uint48- +:xref-IAccessManager-AccessManagerAlreadyScheduled-bytes32-: xref:access.adoc#IAccessManager-AccessManagerAlreadyScheduled-bytes32- +:xref-IAccessManager-AccessManagerNotScheduled-bytes32-: xref:access.adoc#IAccessManager-AccessManagerNotScheduled-bytes32- +:xref-IAccessManager-AccessManagerNotReady-bytes32-: xref:access.adoc#IAccessManager-AccessManagerNotReady-bytes32- +:xref-IAccessManager-AccessManagerExpired-bytes32-: xref:access.adoc#IAccessManager-AccessManagerExpired-bytes32- +:xref-IAccessManager-AccessManagerLockedAccount-address-: xref:access.adoc#IAccessManager-AccessManagerLockedAccount-address- +:xref-IAccessManager-AccessManagerLockedRole-uint64-: xref:access.adoc#IAccessManager-AccessManagerLockedRole-uint64- +:xref-IAccessManager-AccessManagerBadConfirmation--: xref:access.adoc#IAccessManager-AccessManagerBadConfirmation-- +:xref-IAccessManager-AccessManagerUnauthorizedAccount-address-uint64-: xref:access.adoc#IAccessManager-AccessManagerUnauthorizedAccount-address-uint64- +:xref-IAccessManager-AccessManagerUnauthorizedCall-address-address-bytes4-: xref:access.adoc#IAccessManager-AccessManagerUnauthorizedCall-address-address-bytes4- +:xref-IAccessManager-AccessManagerUnauthorizedConsume-address-: xref:access.adoc#IAccessManager-AccessManagerUnauthorizedConsume-address- +:xref-IAccessManager-AccessManagerUnauthorizedCancel-address-address-address-bytes4-: xref:access.adoc#IAccessManager-AccessManagerUnauthorizedCancel-address-address-address-bytes4- +:xref-IAccessManager-AccessManagerInvalidInitialAdmin-address-: xref:access.adoc#IAccessManager-AccessManagerInvalidInitialAdmin-address- +:AccessManager: pass:normal[xref:access.adoc#AccessManager[`AccessManager`]] +:IAuthority: pass:normal[xref:access.adoc#IAuthority[`IAuthority`]] +:xref-AccessManaged-restricted--: xref:access.adoc#AccessManaged-restricted-- +:xref-AccessManaged-constructor-address-: xref:access.adoc#AccessManaged-constructor-address- +:xref-AccessManaged-authority--: xref:access.adoc#AccessManaged-authority-- +:xref-AccessManaged-setAuthority-address-: xref:access.adoc#AccessManaged-setAuthority-address- +:xref-AccessManaged-isConsumingScheduledOp--: xref:access.adoc#AccessManaged-isConsumingScheduledOp-- +:xref-AccessManaged-_setAuthority-address-: xref:access.adoc#AccessManaged-_setAuthority-address- +:xref-AccessManaged-_checkCanCall-address-bytes-: xref:access.adoc#AccessManaged-_checkCanCall-address-bytes- +:xref-IAccessManaged-AuthorityUpdated-address-: xref:access.adoc#IAccessManaged-AuthorityUpdated-address- +:xref-IAccessManaged-AccessManagedUnauthorized-address-: xref:access.adoc#IAccessManaged-AccessManagedUnauthorized-address- +:xref-IAccessManaged-AccessManagedRequiredDelay-address-uint32-: xref:access.adoc#IAccessManaged-AccessManagedRequiredDelay-address-uint32- +:xref-IAccessManaged-AccessManagedInvalidAuthority-address-: xref:access.adoc#IAccessManaged-AccessManagedInvalidAuthority-address- += Access Control + +[.readme-notice] +NOTE: This document is better viewed at https://docs.openzeppelin.com/contracts/api/access + +This directory provides ways to restrict who can access the functions of a contract or when they can do it. + +- {AccessControl} provides a general role based access control mechanism. Multiple hierarchical roles can be created and assigned each to multiple accounts. +- {Ownable} is a simpler mechanism with a single owner "role" that can be assigned to a single account. This simpler mechanism can be useful for quick tests but projects with production concerns are likely to outgrow it. + +== Core + +:OwnableUnauthorizedAccount: pass:normal[xref:#Ownable-OwnableUnauthorizedAccount-address-[`++OwnableUnauthorizedAccount++`]] +:OwnableInvalidOwner: pass:normal[xref:#Ownable-OwnableInvalidOwner-address-[`++OwnableInvalidOwner++`]] +:OwnershipTransferred: pass:normal[xref:#Ownable-OwnershipTransferred-address-address-[`++OwnershipTransferred++`]] +:constructor: pass:normal[xref:#Ownable-constructor-address-[`++constructor++`]] +:onlyOwner: pass:normal[xref:#Ownable-onlyOwner--[`++onlyOwner++`]] +:owner: pass:normal[xref:#Ownable-owner--[`++owner++`]] +:_checkOwner: pass:normal[xref:#Ownable-_checkOwner--[`++_checkOwner++`]] +:renounceOwnership: pass:normal[xref:#Ownable-renounceOwnership--[`++renounceOwnership++`]] +:transferOwnership: pass:normal[xref:#Ownable-transferOwnership-address-[`++transferOwnership++`]] +:_transferOwnership: pass:normal[xref:#Ownable-_transferOwnership-address-[`++_transferOwnership++`]] + +[.contract] +[[Ownable]] +=== `++Ownable++` link:https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v5.0.0-rc.0/contracts/access/Ownable.sol[{github-icon},role=heading-link] + +[.hljs-theme-light.nopadding] +```solidity +import "@openzeppelin/contracts/access/Ownable.sol"; +``` + +Contract module which provides a basic access control mechanism, where +there is an account (an owner) that can be granted exclusive access to +specific functions. + +The initial owner is set to the address provided by the deployer. This can +later be changed with {transferOwnership}. + +This module is used through inheritance. It will make available the modifier +`onlyOwner`, which can be applied to your functions to restrict their use to +the owner. + +[.contract-index] +.Modifiers +-- +* {xref-Ownable-onlyOwner--}[`++onlyOwner()++`] +-- + +[.contract-index] +.Functions +-- +* {xref-Ownable-constructor-address-}[`++constructor(initialOwner)++`] +* {xref-Ownable-owner--}[`++owner()++`] +* {xref-Ownable-_checkOwner--}[`++_checkOwner()++`] +* {xref-Ownable-renounceOwnership--}[`++renounceOwnership()++`] +* {xref-Ownable-transferOwnership-address-}[`++transferOwnership(newOwner)++`] +* {xref-Ownable-_transferOwnership-address-}[`++_transferOwnership(newOwner)++`] + +-- + +[.contract-index] +.Events +-- +* {xref-Ownable-OwnershipTransferred-address-address-}[`++OwnershipTransferred(previousOwner, newOwner)++`] + +-- + +[.contract-index] +.Errors +-- +* {xref-Ownable-OwnableUnauthorizedAccount-address-}[`++OwnableUnauthorizedAccount(account)++`] +* {xref-Ownable-OwnableInvalidOwner-address-}[`++OwnableInvalidOwner(owner)++`] + +-- + +[.contract-item] +[[Ownable-onlyOwner--]] +==== `[.contract-item-name]#++onlyOwner++#++()++` [.item-kind]#modifier# + +Throws if called by any account other than the owner. + +[.contract-item] +[[Ownable-constructor-address-]] +==== `[.contract-item-name]#++constructor++#++(address initialOwner)++` [.item-kind]#internal# + +Initializes the contract setting the address provided by the deployer as the initial owner. + +[.contract-item] +[[Ownable-owner--]] +==== `[.contract-item-name]#++owner++#++() → address++` [.item-kind]#public# + +Returns the address of the current owner. + +[.contract-item] +[[Ownable-_checkOwner--]] +==== `[.contract-item-name]#++_checkOwner++#++()++` [.item-kind]#internal# + +Throws if the sender is not the owner. + +[.contract-item] +[[Ownable-renounceOwnership--]] +==== `[.contract-item-name]#++renounceOwnership++#++()++` [.item-kind]#public# + +Leaves the contract without owner. It will not be possible to call +`onlyOwner` functions. Can only be called by the current owner. + +NOTE: Renouncing ownership will leave the contract without an owner, +thereby disabling any functionality that is only available to the owner. + +[.contract-item] +[[Ownable-transferOwnership-address-]] +==== `[.contract-item-name]#++transferOwnership++#++(address newOwner)++` [.item-kind]#public# + +Transfers ownership of the contract to a new account (`newOwner`). +Can only be called by the current owner. + +[.contract-item] +[[Ownable-_transferOwnership-address-]] +==== `[.contract-item-name]#++_transferOwnership++#++(address newOwner)++` [.item-kind]#internal# + +Transfers ownership of the contract to a new account (`newOwner`). +Internal function without access restriction. + +[.contract-item] +[[Ownable-OwnershipTransferred-address-address-]] +==== `[.contract-item-name]#++OwnershipTransferred++#++(address indexed previousOwner, address indexed newOwner)++` [.item-kind]#event# + +[.contract-item] +[[Ownable-OwnableUnauthorizedAccount-address-]] +==== `[.contract-item-name]#++OwnableUnauthorizedAccount++#++(address account)++` [.item-kind]#error# + +The caller account is not authorized to perform an operation. + +[.contract-item] +[[Ownable-OwnableInvalidOwner-address-]] +==== `[.contract-item-name]#++OwnableInvalidOwner++#++(address owner)++` [.item-kind]#error# + +The owner is not a valid owner account. (eg. `address(0)`) + +:OwnershipTransferStarted: pass:normal[xref:#Ownable2Step-OwnershipTransferStarted-address-address-[`++OwnershipTransferStarted++`]] +:pendingOwner: pass:normal[xref:#Ownable2Step-pendingOwner--[`++pendingOwner++`]] +:transferOwnership: pass:normal[xref:#Ownable2Step-transferOwnership-address-[`++transferOwnership++`]] +:_transferOwnership: pass:normal[xref:#Ownable2Step-_transferOwnership-address-[`++_transferOwnership++`]] +:acceptOwnership: pass:normal[xref:#Ownable2Step-acceptOwnership--[`++acceptOwnership++`]] + +[.contract] +[[Ownable2Step]] +=== `++Ownable2Step++` link:https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v5.0.0-rc.0/contracts/access/Ownable2Step.sol[{github-icon},role=heading-link] + +[.hljs-theme-light.nopadding] +```solidity +import "@openzeppelin/contracts/access/Ownable2Step.sol"; +``` + +Contract module which provides access control mechanism, where +there is an account (an owner) that can be granted exclusive access to +specific functions. + +The initial owner is specified at deployment time in the constructor for `Ownable`. This +can later be changed with {transferOwnership} and {acceptOwnership}. + +This module is used through inheritance. It will make available all functions +from parent (Ownable). + +[.contract-index] +.Functions +-- +* {xref-Ownable2Step-pendingOwner--}[`++pendingOwner()++`] +* {xref-Ownable2Step-transferOwnership-address-}[`++transferOwnership(newOwner)++`] +* {xref-Ownable2Step-_transferOwnership-address-}[`++_transferOwnership(newOwner)++`] +* {xref-Ownable2Step-acceptOwnership--}[`++acceptOwnership()++`] + +[.contract-subindex-inherited] +.Ownable +* {xref-Ownable-owner--}[`++owner()++`] +* {xref-Ownable-_checkOwner--}[`++_checkOwner()++`] +* {xref-Ownable-renounceOwnership--}[`++renounceOwnership()++`] + +-- + +[.contract-index] +.Events +-- +* {xref-Ownable2Step-OwnershipTransferStarted-address-address-}[`++OwnershipTransferStarted(previousOwner, newOwner)++`] + +[.contract-subindex-inherited] +.Ownable +* {xref-Ownable-OwnershipTransferred-address-address-}[`++OwnershipTransferred(previousOwner, newOwner)++`] + +-- + +[.contract-index] +.Errors +-- + +[.contract-subindex-inherited] +.Ownable +* {xref-Ownable-OwnableUnauthorizedAccount-address-}[`++OwnableUnauthorizedAccount(account)++`] +* {xref-Ownable-OwnableInvalidOwner-address-}[`++OwnableInvalidOwner(owner)++`] + +-- + +[.contract-item] +[[Ownable2Step-pendingOwner--]] +==== `[.contract-item-name]#++pendingOwner++#++() → address++` [.item-kind]#public# + +Returns the address of the pending owner. + +[.contract-item] +[[Ownable2Step-transferOwnership-address-]] +==== `[.contract-item-name]#++transferOwnership++#++(address newOwner)++` [.item-kind]#public# + +Starts the ownership transfer of the contract to a new account. Replaces the pending transfer if there is one. +Can only be called by the current owner. + +[.contract-item] +[[Ownable2Step-_transferOwnership-address-]] +==== `[.contract-item-name]#++_transferOwnership++#++(address newOwner)++` [.item-kind]#internal# + +Transfers ownership of the contract to a new account (`newOwner`) and deletes any pending owner. +Internal function without access restriction. + +[.contract-item] +[[Ownable2Step-acceptOwnership--]] +==== `[.contract-item-name]#++acceptOwnership++#++()++` [.item-kind]#public# + +The new owner accepts the ownership transfer. + +[.contract-item] +[[Ownable2Step-OwnershipTransferStarted-address-address-]] +==== `[.contract-item-name]#++OwnershipTransferStarted++#++(address indexed previousOwner, address indexed newOwner)++` [.item-kind]#event# + +:AccessControlUnauthorizedAccount: pass:normal[xref:#IAccessControl-AccessControlUnauthorizedAccount-address-bytes32-[`++AccessControlUnauthorizedAccount++`]] +:AccessControlBadConfirmation: pass:normal[xref:#IAccessControl-AccessControlBadConfirmation--[`++AccessControlBadConfirmation++`]] +:RoleAdminChanged: pass:normal[xref:#IAccessControl-RoleAdminChanged-bytes32-bytes32-bytes32-[`++RoleAdminChanged++`]] +:RoleGranted: pass:normal[xref:#IAccessControl-RoleGranted-bytes32-address-address-[`++RoleGranted++`]] +:RoleRevoked: pass:normal[xref:#IAccessControl-RoleRevoked-bytes32-address-address-[`++RoleRevoked++`]] +:hasRole: pass:normal[xref:#IAccessControl-hasRole-bytes32-address-[`++hasRole++`]] +:getRoleAdmin: pass:normal[xref:#IAccessControl-getRoleAdmin-bytes32-[`++getRoleAdmin++`]] +:grantRole: pass:normal[xref:#IAccessControl-grantRole-bytes32-address-[`++grantRole++`]] +:revokeRole: pass:normal[xref:#IAccessControl-revokeRole-bytes32-address-[`++revokeRole++`]] +:renounceRole: pass:normal[xref:#IAccessControl-renounceRole-bytes32-address-[`++renounceRole++`]] + +[.contract] +[[IAccessControl]] +=== `++IAccessControl++` link:https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v5.0.0-rc.0/contracts/access/IAccessControl.sol[{github-icon},role=heading-link] + +[.hljs-theme-light.nopadding] +```solidity +import "@openzeppelin/contracts/access/IAccessControl.sol"; +``` + +External interface of AccessControl declared to support ERC165 detection. + +[.contract-index] +.Functions +-- +* {xref-IAccessControl-hasRole-bytes32-address-}[`++hasRole(role, account)++`] +* {xref-IAccessControl-getRoleAdmin-bytes32-}[`++getRoleAdmin(role)++`] +* {xref-IAccessControl-grantRole-bytes32-address-}[`++grantRole(role, account)++`] +* {xref-IAccessControl-revokeRole-bytes32-address-}[`++revokeRole(role, account)++`] +* {xref-IAccessControl-renounceRole-bytes32-address-}[`++renounceRole(role, callerConfirmation)++`] + +-- + +[.contract-index] +.Events +-- +* {xref-IAccessControl-RoleAdminChanged-bytes32-bytes32-bytes32-}[`++RoleAdminChanged(role, previousAdminRole, newAdminRole)++`] +* {xref-IAccessControl-RoleGranted-bytes32-address-address-}[`++RoleGranted(role, account, sender)++`] +* {xref-IAccessControl-RoleRevoked-bytes32-address-address-}[`++RoleRevoked(role, account, sender)++`] + +-- + +[.contract-index] +.Errors +-- +* {xref-IAccessControl-AccessControlUnauthorizedAccount-address-bytes32-}[`++AccessControlUnauthorizedAccount(account, neededRole)++`] +* {xref-IAccessControl-AccessControlBadConfirmation--}[`++AccessControlBadConfirmation()++`] + +-- + +[.contract-item] +[[IAccessControl-hasRole-bytes32-address-]] +==== `[.contract-item-name]#++hasRole++#++(bytes32 role, address account) → bool++` [.item-kind]#external# + +Returns `true` if `account` has been granted `role`. + +[.contract-item] +[[IAccessControl-getRoleAdmin-bytes32-]] +==== `[.contract-item-name]#++getRoleAdmin++#++(bytes32 role) → bytes32++` [.item-kind]#external# + +Returns the admin role that controls `role`. See {grantRole} and +{revokeRole}. + +To change a role's admin, use {AccessControl-_setRoleAdmin}. + +[.contract-item] +[[IAccessControl-grantRole-bytes32-address-]] +==== `[.contract-item-name]#++grantRole++#++(bytes32 role, address account)++` [.item-kind]#external# + +Grants `role` to `account`. + +If `account` had not been already granted `role`, emits a {RoleGranted} +event. + +Requirements: + +- the caller must have ``role``'s admin role. + +[.contract-item] +[[IAccessControl-revokeRole-bytes32-address-]] +==== `[.contract-item-name]#++revokeRole++#++(bytes32 role, address account)++` [.item-kind]#external# + +Revokes `role` from `account`. + +If `account` had been granted `role`, emits a {RoleRevoked} event. + +Requirements: + +- the caller must have ``role``'s admin role. + +[.contract-item] +[[IAccessControl-renounceRole-bytes32-address-]] +==== `[.contract-item-name]#++renounceRole++#++(bytes32 role, address callerConfirmation)++` [.item-kind]#external# + +Revokes `role` from the calling account. + +Roles are often managed via {grantRole} and {revokeRole}: this function's +purpose is to provide a mechanism for accounts to lose their privileges +if they are compromised (such as when a trusted device is misplaced). + +If the calling account had been granted `role`, emits a {RoleRevoked} +event. + +Requirements: + +- the caller must be `callerConfirmation`. + +[.contract-item] +[[IAccessControl-RoleAdminChanged-bytes32-bytes32-bytes32-]] +==== `[.contract-item-name]#++RoleAdminChanged++#++(bytes32 indexed role, bytes32 indexed previousAdminRole, bytes32 indexed newAdminRole)++` [.item-kind]#event# + +Emitted when `newAdminRole` is set as ``role``'s admin role, replacing `previousAdminRole` + +`DEFAULT_ADMIN_ROLE` is the starting admin for all roles, despite +{RoleAdminChanged} not being emitted signaling this. + +[.contract-item] +[[IAccessControl-RoleGranted-bytes32-address-address-]] +==== `[.contract-item-name]#++RoleGranted++#++(bytes32 indexed role, address indexed account, address indexed sender)++` [.item-kind]#event# + +Emitted when `account` is granted `role`. + +`sender` is the account that originated the contract call, an admin role +bearer except when using {AccessControl-_setupRole}. + +[.contract-item] +[[IAccessControl-RoleRevoked-bytes32-address-address-]] +==== `[.contract-item-name]#++RoleRevoked++#++(bytes32 indexed role, address indexed account, address indexed sender)++` [.item-kind]#event# + +Emitted when `account` is revoked `role`. + +`sender` is the account that originated the contract call: + - if using `revokeRole`, it is the admin role bearer + - if using `renounceRole`, it is the role bearer (i.e. `account`) + +[.contract-item] +[[IAccessControl-AccessControlUnauthorizedAccount-address-bytes32-]] +==== `[.contract-item-name]#++AccessControlUnauthorizedAccount++#++(address account, bytes32 neededRole)++` [.item-kind]#error# + +The `account` is missing a role. + +[.contract-item] +[[IAccessControl-AccessControlBadConfirmation--]] +==== `[.contract-item-name]#++AccessControlBadConfirmation++#++()++` [.item-kind]#error# + +The caller of a function is not the expected one. + +NOTE: Don't confuse with {AccessControlUnauthorizedAccount}. + +:RoleData: pass:normal[xref:#AccessControl-RoleData[`++RoleData++`]] +:DEFAULT_ADMIN_ROLE: pass:normal[xref:#AccessControl-DEFAULT_ADMIN_ROLE-bytes32[`++DEFAULT_ADMIN_ROLE++`]] +:onlyRole: pass:normal[xref:#AccessControl-onlyRole-bytes32-[`++onlyRole++`]] +:supportsInterface: pass:normal[xref:#AccessControl-supportsInterface-bytes4-[`++supportsInterface++`]] +:hasRole: pass:normal[xref:#AccessControl-hasRole-bytes32-address-[`++hasRole++`]] +:_checkRole: pass:normal[xref:#AccessControl-_checkRole-bytes32-[`++_checkRole++`]] +:_checkRole: pass:normal[xref:#AccessControl-_checkRole-bytes32-address-[`++_checkRole++`]] +:getRoleAdmin: pass:normal[xref:#AccessControl-getRoleAdmin-bytes32-[`++getRoleAdmin++`]] +:grantRole: pass:normal[xref:#AccessControl-grantRole-bytes32-address-[`++grantRole++`]] +:revokeRole: pass:normal[xref:#AccessControl-revokeRole-bytes32-address-[`++revokeRole++`]] +:renounceRole: pass:normal[xref:#AccessControl-renounceRole-bytes32-address-[`++renounceRole++`]] +:_setRoleAdmin: pass:normal[xref:#AccessControl-_setRoleAdmin-bytes32-bytes32-[`++_setRoleAdmin++`]] +:_grantRole: pass:normal[xref:#AccessControl-_grantRole-bytes32-address-[`++_grantRole++`]] +:_revokeRole: pass:normal[xref:#AccessControl-_revokeRole-bytes32-address-[`++_revokeRole++`]] + +[.contract] +[[AccessControl]] +=== `++AccessControl++` link:https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v5.0.0-rc.0/contracts/access/AccessControl.sol[{github-icon},role=heading-link] + +[.hljs-theme-light.nopadding] +```solidity +import "@openzeppelin/contracts/access/AccessControl.sol"; +``` + +Contract module that allows children to implement role-based access +control mechanisms. This is a lightweight version that doesn't allow enumerating role +members except through off-chain means by accessing the contract event logs. Some +applications may benefit from on-chain enumerability, for those cases see +{AccessControlEnumerable}. + +Roles are referred to by their `bytes32` identifier. These should be exposed +in the external API and be unique. The best way to achieve this is by +using `public constant` hash digests: + +```solidity +bytes32 public constant MY_ROLE = keccak256("MY_ROLE"); +``` + +Roles can be used to represent a set of permissions. To restrict access to a +function call, use {hasRole}: + +```solidity +function foo() public { + require(hasRole(MY_ROLE, msg.sender)); + ... +} +``` + +Roles can be granted and revoked dynamically via the {grantRole} and +{revokeRole} functions. Each role has an associated admin role, and only +accounts that have a role's admin role can call {grantRole} and {revokeRole}. + +By default, the admin role for all roles is `DEFAULT_ADMIN_ROLE`, which means +that only accounts with this role will be able to grant or revoke other +roles. More complex role relationships can be created by using +{_setRoleAdmin}. + +WARNING: The `DEFAULT_ADMIN_ROLE` is also its own admin: it has permission to +grant and revoke this role. Extra precautions should be taken to secure +accounts that have been granted it. We recommend using {AccessControlDefaultAdminRules} +to enforce additional security measures for this role. + +[.contract-index] +.Modifiers +-- +* {xref-AccessControl-onlyRole-bytes32-}[`++onlyRole(role)++`] +-- + +[.contract-index] +.Functions +-- +* {xref-AccessControl-supportsInterface-bytes4-}[`++supportsInterface(interfaceId)++`] +* {xref-AccessControl-hasRole-bytes32-address-}[`++hasRole(role, account)++`] +* {xref-AccessControl-_checkRole-bytes32-}[`++_checkRole(role)++`] +* {xref-AccessControl-_checkRole-bytes32-address-}[`++_checkRole(role, account)++`] +* {xref-AccessControl-getRoleAdmin-bytes32-}[`++getRoleAdmin(role)++`] +* {xref-AccessControl-grantRole-bytes32-address-}[`++grantRole(role, account)++`] +* {xref-AccessControl-revokeRole-bytes32-address-}[`++revokeRole(role, account)++`] +* {xref-AccessControl-renounceRole-bytes32-address-}[`++renounceRole(role, callerConfirmation)++`] +* {xref-AccessControl-_setRoleAdmin-bytes32-bytes32-}[`++_setRoleAdmin(role, adminRole)++`] +* {xref-AccessControl-_grantRole-bytes32-address-}[`++_grantRole(role, account)++`] +* {xref-AccessControl-_revokeRole-bytes32-address-}[`++_revokeRole(role, account)++`] + +[.contract-subindex-inherited] +.ERC165 + +[.contract-subindex-inherited] +.IERC165 + +[.contract-subindex-inherited] +.IAccessControl + +-- + +[.contract-index] +.Events +-- + +[.contract-subindex-inherited] +.ERC165 + +[.contract-subindex-inherited] +.IERC165 + +[.contract-subindex-inherited] +.IAccessControl +* {xref-IAccessControl-RoleAdminChanged-bytes32-bytes32-bytes32-}[`++RoleAdminChanged(role, previousAdminRole, newAdminRole)++`] +* {xref-IAccessControl-RoleGranted-bytes32-address-address-}[`++RoleGranted(role, account, sender)++`] +* {xref-IAccessControl-RoleRevoked-bytes32-address-address-}[`++RoleRevoked(role, account, sender)++`] + +-- + +[.contract-index] +.Errors +-- + +[.contract-subindex-inherited] +.ERC165 + +[.contract-subindex-inherited] +.IERC165 + +[.contract-subindex-inherited] +.IAccessControl +* {xref-IAccessControl-AccessControlUnauthorizedAccount-address-bytes32-}[`++AccessControlUnauthorizedAccount(account, neededRole)++`] +* {xref-IAccessControl-AccessControlBadConfirmation--}[`++AccessControlBadConfirmation()++`] + +-- + +[.contract-item] +[[AccessControl-onlyRole-bytes32-]] +==== `[.contract-item-name]#++onlyRole++#++(bytes32 role)++` [.item-kind]#modifier# + +Modifier that checks that an account has a specific role. Reverts +with an {AccessControlUnauthorizedAccount} error including the required role. + +[.contract-item] +[[AccessControl-supportsInterface-bytes4-]] +==== `[.contract-item-name]#++supportsInterface++#++(bytes4 interfaceId) → bool++` [.item-kind]#public# + +See {IERC165-supportsInterface}. + +[.contract-item] +[[AccessControl-hasRole-bytes32-address-]] +==== `[.contract-item-name]#++hasRole++#++(bytes32 role, address account) → bool++` [.item-kind]#public# + +Returns `true` if `account` has been granted `role`. + +[.contract-item] +[[AccessControl-_checkRole-bytes32-]] +==== `[.contract-item-name]#++_checkRole++#++(bytes32 role)++` [.item-kind]#internal# + +Reverts with an {AccessControlUnauthorizedAccount} error if `_msgSender()` +is missing `role`. Overriding this function changes the behavior of the {onlyRole} modifier. + +[.contract-item] +[[AccessControl-_checkRole-bytes32-address-]] +==== `[.contract-item-name]#++_checkRole++#++(bytes32 role, address account)++` [.item-kind]#internal# + +Reverts with an {AccessControlUnauthorizedAccount} error if `account` +is missing `role`. + +[.contract-item] +[[AccessControl-getRoleAdmin-bytes32-]] +==== `[.contract-item-name]#++getRoleAdmin++#++(bytes32 role) → bytes32++` [.item-kind]#public# + +Returns the admin role that controls `role`. See {grantRole} and +{revokeRole}. + +To change a role's admin, use {_setRoleAdmin}. + +[.contract-item] +[[AccessControl-grantRole-bytes32-address-]] +==== `[.contract-item-name]#++grantRole++#++(bytes32 role, address account)++` [.item-kind]#public# + +Grants `role` to `account`. + +If `account` had not been already granted `role`, emits a {RoleGranted} +event. + +Requirements: + +- the caller must have ``role``'s admin role. + +May emit a {RoleGranted} event. + +[.contract-item] +[[AccessControl-revokeRole-bytes32-address-]] +==== `[.contract-item-name]#++revokeRole++#++(bytes32 role, address account)++` [.item-kind]#public# + +Revokes `role` from `account`. + +If `account` had been granted `role`, emits a {RoleRevoked} event. + +Requirements: + +- the caller must have ``role``'s admin role. + +May emit a {RoleRevoked} event. + +[.contract-item] +[[AccessControl-renounceRole-bytes32-address-]] +==== `[.contract-item-name]#++renounceRole++#++(bytes32 role, address callerConfirmation)++` [.item-kind]#public# + +Revokes `role` from the calling account. + +Roles are often managed via {grantRole} and {revokeRole}: this function's +purpose is to provide a mechanism for accounts to lose their privileges +if they are compromised (such as when a trusted device is misplaced). + +If the calling account had been revoked `role`, emits a {RoleRevoked} +event. + +Requirements: + +- the caller must be `callerConfirmation`. + +May emit a {RoleRevoked} event. + +[.contract-item] +[[AccessControl-_setRoleAdmin-bytes32-bytes32-]] +==== `[.contract-item-name]#++_setRoleAdmin++#++(bytes32 role, bytes32 adminRole)++` [.item-kind]#internal# + +Sets `adminRole` as ``role``'s admin role. + +Emits a {RoleAdminChanged} event. + +[.contract-item] +[[AccessControl-_grantRole-bytes32-address-]] +==== `[.contract-item-name]#++_grantRole++#++(bytes32 role, address account) → bool++` [.item-kind]#internal# + +Attempts to grant `role` to `account` and returns a boolean indicating if `role` was granted. + +Internal function without access restriction. + +May emit a {RoleGranted} event. + +[.contract-item] +[[AccessControl-_revokeRole-bytes32-address-]] +==== `[.contract-item-name]#++_revokeRole++#++(bytes32 role, address account) → bool++` [.item-kind]#internal# + +Attempts to revoke `role` to `account` and returns a boolean indicating if `role` was revoked. + +Internal function without access restriction. + +May emit a {RoleRevoked} event. + +== Extensions + +:getRoleMember: pass:normal[xref:#IAccessControlEnumerable-getRoleMember-bytes32-uint256-[`++getRoleMember++`]] +:getRoleMemberCount: pass:normal[xref:#IAccessControlEnumerable-getRoleMemberCount-bytes32-[`++getRoleMemberCount++`]] + +[.contract] +[[IAccessControlEnumerable]] +=== `++IAccessControlEnumerable++` link:https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v5.0.0-rc.0/contracts/access/extensions/IAccessControlEnumerable.sol[{github-icon},role=heading-link] + +[.hljs-theme-light.nopadding] +```solidity +import "@openzeppelin/contracts/access/extensions/IAccessControlEnumerable.sol"; +``` + +External interface of AccessControlEnumerable declared to support ERC165 detection. + +[.contract-index] +.Functions +-- +* {xref-IAccessControlEnumerable-getRoleMember-bytes32-uint256-}[`++getRoleMember(role, index)++`] +* {xref-IAccessControlEnumerable-getRoleMemberCount-bytes32-}[`++getRoleMemberCount(role)++`] + +[.contract-subindex-inherited] +.IAccessControl +* {xref-IAccessControl-hasRole-bytes32-address-}[`++hasRole(role, account)++`] +* {xref-IAccessControl-getRoleAdmin-bytes32-}[`++getRoleAdmin(role)++`] +* {xref-IAccessControl-grantRole-bytes32-address-}[`++grantRole(role, account)++`] +* {xref-IAccessControl-revokeRole-bytes32-address-}[`++revokeRole(role, account)++`] +* {xref-IAccessControl-renounceRole-bytes32-address-}[`++renounceRole(role, callerConfirmation)++`] + +-- + +[.contract-index] +.Events +-- + +[.contract-subindex-inherited] +.IAccessControl +* {xref-IAccessControl-RoleAdminChanged-bytes32-bytes32-bytes32-}[`++RoleAdminChanged(role, previousAdminRole, newAdminRole)++`] +* {xref-IAccessControl-RoleGranted-bytes32-address-address-}[`++RoleGranted(role, account, sender)++`] +* {xref-IAccessControl-RoleRevoked-bytes32-address-address-}[`++RoleRevoked(role, account, sender)++`] + +-- + +[.contract-index] +.Errors +-- + +[.contract-subindex-inherited] +.IAccessControl +* {xref-IAccessControl-AccessControlUnauthorizedAccount-address-bytes32-}[`++AccessControlUnauthorizedAccount(account, neededRole)++`] +* {xref-IAccessControl-AccessControlBadConfirmation--}[`++AccessControlBadConfirmation()++`] + +-- + +[.contract-item] +[[IAccessControlEnumerable-getRoleMember-bytes32-uint256-]] +==== `[.contract-item-name]#++getRoleMember++#++(bytes32 role, uint256 index) → address++` [.item-kind]#external# + +Returns one of the accounts that have `role`. `index` must be a +value between 0 and {getRoleMemberCount}, non-inclusive. + +Role bearers are not sorted in any particular way, and their ordering may +change at any point. + +WARNING: When using {getRoleMember} and {getRoleMemberCount}, make sure +you perform all queries on the same block. See the following +https://forum.openzeppelin.com/t/iterating-over-elements-on-enumerableset-in-openzeppelin-contracts/2296[forum post] +for more information. + +[.contract-item] +[[IAccessControlEnumerable-getRoleMemberCount-bytes32-]] +==== `[.contract-item-name]#++getRoleMemberCount++#++(bytes32 role) → uint256++` [.item-kind]#external# + +Returns the number of accounts that have `role`. Can be used +together with {getRoleMember} to enumerate all bearers of a role. + +:supportsInterface: pass:normal[xref:#AccessControlEnumerable-supportsInterface-bytes4-[`++supportsInterface++`]] +:getRoleMember: pass:normal[xref:#AccessControlEnumerable-getRoleMember-bytes32-uint256-[`++getRoleMember++`]] +:getRoleMemberCount: pass:normal[xref:#AccessControlEnumerable-getRoleMemberCount-bytes32-[`++getRoleMemberCount++`]] +:_grantRole: pass:normal[xref:#AccessControlEnumerable-_grantRole-bytes32-address-[`++_grantRole++`]] +:_revokeRole: pass:normal[xref:#AccessControlEnumerable-_revokeRole-bytes32-address-[`++_revokeRole++`]] + +[.contract] +[[AccessControlEnumerable]] +=== `++AccessControlEnumerable++` link:https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v5.0.0-rc.0/contracts/access/extensions/AccessControlEnumerable.sol[{github-icon},role=heading-link] + +[.hljs-theme-light.nopadding] +```solidity +import "@openzeppelin/contracts/access/extensions/AccessControlEnumerable.sol"; +``` + +Extension of {AccessControl} that allows enumerating the members of each role. + +[.contract-index] +.Functions +-- +* {xref-AccessControlEnumerable-supportsInterface-bytes4-}[`++supportsInterface(interfaceId)++`] +* {xref-AccessControlEnumerable-getRoleMember-bytes32-uint256-}[`++getRoleMember(role, index)++`] +* {xref-AccessControlEnumerable-getRoleMemberCount-bytes32-}[`++getRoleMemberCount(role)++`] +* {xref-AccessControlEnumerable-_grantRole-bytes32-address-}[`++_grantRole(role, account)++`] +* {xref-AccessControlEnumerable-_revokeRole-bytes32-address-}[`++_revokeRole(role, account)++`] + +[.contract-subindex-inherited] +.AccessControl +* {xref-AccessControl-hasRole-bytes32-address-}[`++hasRole(role, account)++`] +* {xref-AccessControl-_checkRole-bytes32-}[`++_checkRole(role)++`] +* {xref-AccessControl-_checkRole-bytes32-address-}[`++_checkRole(role, account)++`] +* {xref-AccessControl-getRoleAdmin-bytes32-}[`++getRoleAdmin(role)++`] +* {xref-AccessControl-grantRole-bytes32-address-}[`++grantRole(role, account)++`] +* {xref-AccessControl-revokeRole-bytes32-address-}[`++revokeRole(role, account)++`] +* {xref-AccessControl-renounceRole-bytes32-address-}[`++renounceRole(role, callerConfirmation)++`] +* {xref-AccessControl-_setRoleAdmin-bytes32-bytes32-}[`++_setRoleAdmin(role, adminRole)++`] + +[.contract-subindex-inherited] +.ERC165 + +[.contract-subindex-inherited] +.IERC165 + +[.contract-subindex-inherited] +.IAccessControlEnumerable + +[.contract-subindex-inherited] +.IAccessControl + +-- + +[.contract-index] +.Events +-- + +[.contract-subindex-inherited] +.AccessControl + +[.contract-subindex-inherited] +.ERC165 + +[.contract-subindex-inherited] +.IERC165 + +[.contract-subindex-inherited] +.IAccessControlEnumerable + +[.contract-subindex-inherited] +.IAccessControl +* {xref-IAccessControl-RoleAdminChanged-bytes32-bytes32-bytes32-}[`++RoleAdminChanged(role, previousAdminRole, newAdminRole)++`] +* {xref-IAccessControl-RoleGranted-bytes32-address-address-}[`++RoleGranted(role, account, sender)++`] +* {xref-IAccessControl-RoleRevoked-bytes32-address-address-}[`++RoleRevoked(role, account, sender)++`] + +-- + +[.contract-index] +.Errors +-- + +[.contract-subindex-inherited] +.AccessControl + +[.contract-subindex-inherited] +.ERC165 + +[.contract-subindex-inherited] +.IERC165 + +[.contract-subindex-inherited] +.IAccessControlEnumerable + +[.contract-subindex-inherited] +.IAccessControl +* {xref-IAccessControl-AccessControlUnauthorizedAccount-address-bytes32-}[`++AccessControlUnauthorizedAccount(account, neededRole)++`] +* {xref-IAccessControl-AccessControlBadConfirmation--}[`++AccessControlBadConfirmation()++`] + +-- + +[.contract-item] +[[AccessControlEnumerable-supportsInterface-bytes4-]] +==== `[.contract-item-name]#++supportsInterface++#++(bytes4 interfaceId) → bool++` [.item-kind]#public# + +See {IERC165-supportsInterface}. + +[.contract-item] +[[AccessControlEnumerable-getRoleMember-bytes32-uint256-]] +==== `[.contract-item-name]#++getRoleMember++#++(bytes32 role, uint256 index) → address++` [.item-kind]#public# + +Returns one of the accounts that have `role`. `index` must be a +value between 0 and {getRoleMemberCount}, non-inclusive. + +Role bearers are not sorted in any particular way, and their ordering may +change at any point. + +WARNING: When using {getRoleMember} and {getRoleMemberCount}, make sure +you perform all queries on the same block. See the following +https://forum.openzeppelin.com/t/iterating-over-elements-on-enumerableset-in-openzeppelin-contracts/2296[forum post] +for more information. + +[.contract-item] +[[AccessControlEnumerable-getRoleMemberCount-bytes32-]] +==== `[.contract-item-name]#++getRoleMemberCount++#++(bytes32 role) → uint256++` [.item-kind]#public# + +Returns the number of accounts that have `role`. Can be used +together with {getRoleMember} to enumerate all bearers of a role. + +[.contract-item] +[[AccessControlEnumerable-_grantRole-bytes32-address-]] +==== `[.contract-item-name]#++_grantRole++#++(bytes32 role, address account) → bool++` [.item-kind]#internal# + +Overload {AccessControl-_grantRole} to track enumerable memberships + +[.contract-item] +[[AccessControlEnumerable-_revokeRole-bytes32-address-]] +==== `[.contract-item-name]#++_revokeRole++#++(bytes32 role, address account) → bool++` [.item-kind]#internal# + +Overload {AccessControl-_revokeRole} to track enumerable memberships + +:AccessControlInvalidDefaultAdmin: pass:normal[xref:#IAccessControlDefaultAdminRules-AccessControlInvalidDefaultAdmin-address-[`++AccessControlInvalidDefaultAdmin++`]] +:AccessControlEnforcedDefaultAdminRules: pass:normal[xref:#IAccessControlDefaultAdminRules-AccessControlEnforcedDefaultAdminRules--[`++AccessControlEnforcedDefaultAdminRules++`]] +:AccessControlEnforcedDefaultAdminDelay: pass:normal[xref:#IAccessControlDefaultAdminRules-AccessControlEnforcedDefaultAdminDelay-uint48-[`++AccessControlEnforcedDefaultAdminDelay++`]] +:DefaultAdminTransferScheduled: pass:normal[xref:#IAccessControlDefaultAdminRules-DefaultAdminTransferScheduled-address-uint48-[`++DefaultAdminTransferScheduled++`]] +:DefaultAdminTransferCanceled: pass:normal[xref:#IAccessControlDefaultAdminRules-DefaultAdminTransferCanceled--[`++DefaultAdminTransferCanceled++`]] +:DefaultAdminDelayChangeScheduled: pass:normal[xref:#IAccessControlDefaultAdminRules-DefaultAdminDelayChangeScheduled-uint48-uint48-[`++DefaultAdminDelayChangeScheduled++`]] +:DefaultAdminDelayChangeCanceled: pass:normal[xref:#IAccessControlDefaultAdminRules-DefaultAdminDelayChangeCanceled--[`++DefaultAdminDelayChangeCanceled++`]] +:defaultAdmin: pass:normal[xref:#IAccessControlDefaultAdminRules-defaultAdmin--[`++defaultAdmin++`]] +:pendingDefaultAdmin: pass:normal[xref:#IAccessControlDefaultAdminRules-pendingDefaultAdmin--[`++pendingDefaultAdmin++`]] +:defaultAdminDelay: pass:normal[xref:#IAccessControlDefaultAdminRules-defaultAdminDelay--[`++defaultAdminDelay++`]] +:pendingDefaultAdminDelay: pass:normal[xref:#IAccessControlDefaultAdminRules-pendingDefaultAdminDelay--[`++pendingDefaultAdminDelay++`]] +:beginDefaultAdminTransfer: pass:normal[xref:#IAccessControlDefaultAdminRules-beginDefaultAdminTransfer-address-[`++beginDefaultAdminTransfer++`]] +:cancelDefaultAdminTransfer: pass:normal[xref:#IAccessControlDefaultAdminRules-cancelDefaultAdminTransfer--[`++cancelDefaultAdminTransfer++`]] +:acceptDefaultAdminTransfer: pass:normal[xref:#IAccessControlDefaultAdminRules-acceptDefaultAdminTransfer--[`++acceptDefaultAdminTransfer++`]] +:changeDefaultAdminDelay: pass:normal[xref:#IAccessControlDefaultAdminRules-changeDefaultAdminDelay-uint48-[`++changeDefaultAdminDelay++`]] +:rollbackDefaultAdminDelay: pass:normal[xref:#IAccessControlDefaultAdminRules-rollbackDefaultAdminDelay--[`++rollbackDefaultAdminDelay++`]] +:defaultAdminDelayIncreaseWait: pass:normal[xref:#IAccessControlDefaultAdminRules-defaultAdminDelayIncreaseWait--[`++defaultAdminDelayIncreaseWait++`]] + +[.contract] +[[IAccessControlDefaultAdminRules]] +=== `++IAccessControlDefaultAdminRules++` link:https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v5.0.0-rc.0/contracts/access/extensions/IAccessControlDefaultAdminRules.sol[{github-icon},role=heading-link] + +[.hljs-theme-light.nopadding] +```solidity +import "@openzeppelin/contracts/access/extensions/IAccessControlDefaultAdminRules.sol"; +``` + +External interface of AccessControlDefaultAdminRules declared to support ERC165 detection. + +[.contract-index] +.Functions +-- +* {xref-IAccessControlDefaultAdminRules-defaultAdmin--}[`++defaultAdmin()++`] +* {xref-IAccessControlDefaultAdminRules-pendingDefaultAdmin--}[`++pendingDefaultAdmin()++`] +* {xref-IAccessControlDefaultAdminRules-defaultAdminDelay--}[`++defaultAdminDelay()++`] +* {xref-IAccessControlDefaultAdminRules-pendingDefaultAdminDelay--}[`++pendingDefaultAdminDelay()++`] +* {xref-IAccessControlDefaultAdminRules-beginDefaultAdminTransfer-address-}[`++beginDefaultAdminTransfer(newAdmin)++`] +* {xref-IAccessControlDefaultAdminRules-cancelDefaultAdminTransfer--}[`++cancelDefaultAdminTransfer()++`] +* {xref-IAccessControlDefaultAdminRules-acceptDefaultAdminTransfer--}[`++acceptDefaultAdminTransfer()++`] +* {xref-IAccessControlDefaultAdminRules-changeDefaultAdminDelay-uint48-}[`++changeDefaultAdminDelay(newDelay)++`] +* {xref-IAccessControlDefaultAdminRules-rollbackDefaultAdminDelay--}[`++rollbackDefaultAdminDelay()++`] +* {xref-IAccessControlDefaultAdminRules-defaultAdminDelayIncreaseWait--}[`++defaultAdminDelayIncreaseWait()++`] + +[.contract-subindex-inherited] +.IAccessControl +* {xref-IAccessControl-hasRole-bytes32-address-}[`++hasRole(role, account)++`] +* {xref-IAccessControl-getRoleAdmin-bytes32-}[`++getRoleAdmin(role)++`] +* {xref-IAccessControl-grantRole-bytes32-address-}[`++grantRole(role, account)++`] +* {xref-IAccessControl-revokeRole-bytes32-address-}[`++revokeRole(role, account)++`] +* {xref-IAccessControl-renounceRole-bytes32-address-}[`++renounceRole(role, callerConfirmation)++`] + +-- + +[.contract-index] +.Events +-- +* {xref-IAccessControlDefaultAdminRules-DefaultAdminTransferScheduled-address-uint48-}[`++DefaultAdminTransferScheduled(newAdmin, acceptSchedule)++`] +* {xref-IAccessControlDefaultAdminRules-DefaultAdminTransferCanceled--}[`++DefaultAdminTransferCanceled()++`] +* {xref-IAccessControlDefaultAdminRules-DefaultAdminDelayChangeScheduled-uint48-uint48-}[`++DefaultAdminDelayChangeScheduled(newDelay, effectSchedule)++`] +* {xref-IAccessControlDefaultAdminRules-DefaultAdminDelayChangeCanceled--}[`++DefaultAdminDelayChangeCanceled()++`] + +[.contract-subindex-inherited] +.IAccessControl +* {xref-IAccessControl-RoleAdminChanged-bytes32-bytes32-bytes32-}[`++RoleAdminChanged(role, previousAdminRole, newAdminRole)++`] +* {xref-IAccessControl-RoleGranted-bytes32-address-address-}[`++RoleGranted(role, account, sender)++`] +* {xref-IAccessControl-RoleRevoked-bytes32-address-address-}[`++RoleRevoked(role, account, sender)++`] + +-- + +[.contract-index] +.Errors +-- +* {xref-IAccessControlDefaultAdminRules-AccessControlInvalidDefaultAdmin-address-}[`++AccessControlInvalidDefaultAdmin(defaultAdmin)++`] +* {xref-IAccessControlDefaultAdminRules-AccessControlEnforcedDefaultAdminRules--}[`++AccessControlEnforcedDefaultAdminRules()++`] +* {xref-IAccessControlDefaultAdminRules-AccessControlEnforcedDefaultAdminDelay-uint48-}[`++AccessControlEnforcedDefaultAdminDelay(schedule)++`] + +[.contract-subindex-inherited] +.IAccessControl +* {xref-IAccessControl-AccessControlUnauthorizedAccount-address-bytes32-}[`++AccessControlUnauthorizedAccount(account, neededRole)++`] +* {xref-IAccessControl-AccessControlBadConfirmation--}[`++AccessControlBadConfirmation()++`] + +-- + +[.contract-item] +[[IAccessControlDefaultAdminRules-defaultAdmin--]] +==== `[.contract-item-name]#++defaultAdmin++#++() → address++` [.item-kind]#external# + +Returns the address of the current `DEFAULT_ADMIN_ROLE` holder. + +[.contract-item] +[[IAccessControlDefaultAdminRules-pendingDefaultAdmin--]] +==== `[.contract-item-name]#++pendingDefaultAdmin++#++() → address newAdmin, uint48 acceptSchedule++` [.item-kind]#external# + +Returns a tuple of a `newAdmin` and an accept schedule. + +After the `schedule` passes, the `newAdmin` will be able to accept the {defaultAdmin} role +by calling {acceptDefaultAdminTransfer}, completing the role transfer. + +A zero value only in `acceptSchedule` indicates no pending admin transfer. + +NOTE: A zero address `newAdmin` means that {defaultAdmin} is being renounced. + +[.contract-item] +[[IAccessControlDefaultAdminRules-defaultAdminDelay--]] +==== `[.contract-item-name]#++defaultAdminDelay++#++() → uint48++` [.item-kind]#external# + +Returns the delay required to schedule the acceptance of a {defaultAdmin} transfer started. + +This delay will be added to the current timestamp when calling {beginDefaultAdminTransfer} to set +the acceptance schedule. + +NOTE: If a delay change has been scheduled, it will take effect as soon as the schedule passes, making this +function returns the new delay. See {changeDefaultAdminDelay}. + +[.contract-item] +[[IAccessControlDefaultAdminRules-pendingDefaultAdminDelay--]] +==== `[.contract-item-name]#++pendingDefaultAdminDelay++#++() → uint48 newDelay, uint48 effectSchedule++` [.item-kind]#external# + +Returns a tuple of `newDelay` and an effect schedule. + +After the `schedule` passes, the `newDelay` will get into effect immediately for every +new {defaultAdmin} transfer started with {beginDefaultAdminTransfer}. + +A zero value only in `effectSchedule` indicates no pending delay change. + +NOTE: A zero value only for `newDelay` means that the next {defaultAdminDelay} +will be zero after the effect schedule. + +[.contract-item] +[[IAccessControlDefaultAdminRules-beginDefaultAdminTransfer-address-]] +==== `[.contract-item-name]#++beginDefaultAdminTransfer++#++(address newAdmin)++` [.item-kind]#external# + +Starts a {defaultAdmin} transfer by setting a {pendingDefaultAdmin} scheduled for acceptance +after the current timestamp plus a {defaultAdminDelay}. + +Requirements: + +- Only can be called by the current {defaultAdmin}. + +Emits a DefaultAdminRoleChangeStarted event. + +[.contract-item] +[[IAccessControlDefaultAdminRules-cancelDefaultAdminTransfer--]] +==== `[.contract-item-name]#++cancelDefaultAdminTransfer++#++()++` [.item-kind]#external# + +Cancels a {defaultAdmin} transfer previously started with {beginDefaultAdminTransfer}. + +A {pendingDefaultAdmin} not yet accepted can also be cancelled with this function. + +Requirements: + +- Only can be called by the current {defaultAdmin}. + +May emit a DefaultAdminTransferCanceled event. + +[.contract-item] +[[IAccessControlDefaultAdminRules-acceptDefaultAdminTransfer--]] +==== `[.contract-item-name]#++acceptDefaultAdminTransfer++#++()++` [.item-kind]#external# + +Completes a {defaultAdmin} transfer previously started with {beginDefaultAdminTransfer}. + +After calling the function: + +- `DEFAULT_ADMIN_ROLE` should be granted to the caller. +- `DEFAULT_ADMIN_ROLE` should be revoked from the previous holder. +- {pendingDefaultAdmin} should be reset to zero values. + +Requirements: + +- Only can be called by the {pendingDefaultAdmin}'s `newAdmin`. +- The {pendingDefaultAdmin}'s `acceptSchedule` should've passed. + +[.contract-item] +[[IAccessControlDefaultAdminRules-changeDefaultAdminDelay-uint48-]] +==== `[.contract-item-name]#++changeDefaultAdminDelay++#++(uint48 newDelay)++` [.item-kind]#external# + +Initiates a {defaultAdminDelay} update by setting a {pendingDefaultAdminDelay} scheduled for getting +into effect after the current timestamp plus a {defaultAdminDelay}. + +This function guarantees that any call to {beginDefaultAdminTransfer} done between the timestamp this +method is called and the {pendingDefaultAdminDelay} effect schedule will use the current {defaultAdminDelay} +set before calling. + +The {pendingDefaultAdminDelay}'s effect schedule is defined in a way that waiting until the schedule and then +calling {beginDefaultAdminTransfer} with the new delay will take at least the same as another {defaultAdmin} +complete transfer (including acceptance). + +The schedule is designed for two scenarios: + +- When the delay is changed for a larger one the schedule is `block.timestamp + newDelay` capped by +{defaultAdminDelayIncreaseWait}. +- When the delay is changed for a shorter one, the schedule is `block.timestamp + (current delay - new delay)`. + +A {pendingDefaultAdminDelay} that never got into effect will be canceled in favor of a new scheduled change. + +Requirements: + +- Only can be called by the current {defaultAdmin}. + +Emits a DefaultAdminDelayChangeScheduled event and may emit a DefaultAdminDelayChangeCanceled event. + +[.contract-item] +[[IAccessControlDefaultAdminRules-rollbackDefaultAdminDelay--]] +==== `[.contract-item-name]#++rollbackDefaultAdminDelay++#++()++` [.item-kind]#external# + +Cancels a scheduled {defaultAdminDelay} change. + +Requirements: + +- Only can be called by the current {defaultAdmin}. + +May emit a DefaultAdminDelayChangeCanceled event. + +[.contract-item] +[[IAccessControlDefaultAdminRules-defaultAdminDelayIncreaseWait--]] +==== `[.contract-item-name]#++defaultAdminDelayIncreaseWait++#++() → uint48++` [.item-kind]#external# + +Maximum time in seconds for an increase to {defaultAdminDelay} (that is scheduled using {changeDefaultAdminDelay}) +to take effect. Default to 5 days. + +When the {defaultAdminDelay} is scheduled to be increased, it goes into effect after the new delay has passed with +the purpose of giving enough time for reverting any accidental change (i.e. using milliseconds instead of seconds) +that may lock the contract. However, to avoid excessive schedules, the wait is capped by this function and it can +be overrode for a custom {defaultAdminDelay} increase scheduling. + +IMPORTANT: Make sure to add a reasonable amount of time while overriding this value, otherwise, +there's a risk of setting a high new delay that goes into effect almost immediately without the +possibility of human intervention in the case of an input error (eg. set milliseconds instead of seconds). + +[.contract-item] +[[IAccessControlDefaultAdminRules-DefaultAdminTransferScheduled-address-uint48-]] +==== `[.contract-item-name]#++DefaultAdminTransferScheduled++#++(address indexed newAdmin, uint48 acceptSchedule)++` [.item-kind]#event# + +Emitted when a {defaultAdmin} transfer is started, setting `newAdmin` as the next +address to become the {defaultAdmin} by calling {acceptDefaultAdminTransfer} only after `acceptSchedule` +passes. + +[.contract-item] +[[IAccessControlDefaultAdminRules-DefaultAdminTransferCanceled--]] +==== `[.contract-item-name]#++DefaultAdminTransferCanceled++#++()++` [.item-kind]#event# + +Emitted when a {pendingDefaultAdmin} is reset if it was never accepted, regardless of its schedule. + +[.contract-item] +[[IAccessControlDefaultAdminRules-DefaultAdminDelayChangeScheduled-uint48-uint48-]] +==== `[.contract-item-name]#++DefaultAdminDelayChangeScheduled++#++(uint48 newDelay, uint48 effectSchedule)++` [.item-kind]#event# + +Emitted when a {defaultAdminDelay} change is started, setting `newDelay` as the next +delay to be applied between default admin transfer after `effectSchedule` has passed. + +[.contract-item] +[[IAccessControlDefaultAdminRules-DefaultAdminDelayChangeCanceled--]] +==== `[.contract-item-name]#++DefaultAdminDelayChangeCanceled++#++()++` [.item-kind]#event# + +Emitted when a {pendingDefaultAdminDelay} is reset if its schedule didn't pass. + +[.contract-item] +[[IAccessControlDefaultAdminRules-AccessControlInvalidDefaultAdmin-address-]] +==== `[.contract-item-name]#++AccessControlInvalidDefaultAdmin++#++(address defaultAdmin)++` [.item-kind]#error# + +The new default admin is not a valid default admin. + +[.contract-item] +[[IAccessControlDefaultAdminRules-AccessControlEnforcedDefaultAdminRules--]] +==== `[.contract-item-name]#++AccessControlEnforcedDefaultAdminRules++#++()++` [.item-kind]#error# + +At least one of the following rules was violated: + +- The `DEFAULT_ADMIN_ROLE` must only be managed by itself. +- The `DEFAULT_ADMIN_ROLE` must only be held by one account at the time. +- Any `DEFAULT_ADMIN_ROLE` transfer must be in two delayed steps. + +[.contract-item] +[[IAccessControlDefaultAdminRules-AccessControlEnforcedDefaultAdminDelay-uint48-]] +==== `[.contract-item-name]#++AccessControlEnforcedDefaultAdminDelay++#++(uint48 schedule)++` [.item-kind]#error# + +The delay for transferring the default admin delay is enforced and +the operation must wait until `schedule`. + +NOTE: `schedule` can be 0 indicating there's no transfer scheduled. + +:constructor: pass:normal[xref:#AccessControlDefaultAdminRules-constructor-uint48-address-[`++constructor++`]] +:supportsInterface: pass:normal[xref:#AccessControlDefaultAdminRules-supportsInterface-bytes4-[`++supportsInterface++`]] +:owner: pass:normal[xref:#AccessControlDefaultAdminRules-owner--[`++owner++`]] +:grantRole: pass:normal[xref:#AccessControlDefaultAdminRules-grantRole-bytes32-address-[`++grantRole++`]] +:revokeRole: pass:normal[xref:#AccessControlDefaultAdminRules-revokeRole-bytes32-address-[`++revokeRole++`]] +:renounceRole: pass:normal[xref:#AccessControlDefaultAdminRules-renounceRole-bytes32-address-[`++renounceRole++`]] +:_grantRole: pass:normal[xref:#AccessControlDefaultAdminRules-_grantRole-bytes32-address-[`++_grantRole++`]] +:_revokeRole: pass:normal[xref:#AccessControlDefaultAdminRules-_revokeRole-bytes32-address-[`++_revokeRole++`]] +:_setRoleAdmin: pass:normal[xref:#AccessControlDefaultAdminRules-_setRoleAdmin-bytes32-bytes32-[`++_setRoleAdmin++`]] +:defaultAdmin: pass:normal[xref:#AccessControlDefaultAdminRules-defaultAdmin--[`++defaultAdmin++`]] +:pendingDefaultAdmin: pass:normal[xref:#AccessControlDefaultAdminRules-pendingDefaultAdmin--[`++pendingDefaultAdmin++`]] +:defaultAdminDelay: pass:normal[xref:#AccessControlDefaultAdminRules-defaultAdminDelay--[`++defaultAdminDelay++`]] +:pendingDefaultAdminDelay: pass:normal[xref:#AccessControlDefaultAdminRules-pendingDefaultAdminDelay--[`++pendingDefaultAdminDelay++`]] +:defaultAdminDelayIncreaseWait: pass:normal[xref:#AccessControlDefaultAdminRules-defaultAdminDelayIncreaseWait--[`++defaultAdminDelayIncreaseWait++`]] +:beginDefaultAdminTransfer: pass:normal[xref:#AccessControlDefaultAdminRules-beginDefaultAdminTransfer-address-[`++beginDefaultAdminTransfer++`]] +:_beginDefaultAdminTransfer: pass:normal[xref:#AccessControlDefaultAdminRules-_beginDefaultAdminTransfer-address-[`++_beginDefaultAdminTransfer++`]] +:cancelDefaultAdminTransfer: pass:normal[xref:#AccessControlDefaultAdminRules-cancelDefaultAdminTransfer--[`++cancelDefaultAdminTransfer++`]] +:_cancelDefaultAdminTransfer: pass:normal[xref:#AccessControlDefaultAdminRules-_cancelDefaultAdminTransfer--[`++_cancelDefaultAdminTransfer++`]] +:acceptDefaultAdminTransfer: pass:normal[xref:#AccessControlDefaultAdminRules-acceptDefaultAdminTransfer--[`++acceptDefaultAdminTransfer++`]] +:_acceptDefaultAdminTransfer: pass:normal[xref:#AccessControlDefaultAdminRules-_acceptDefaultAdminTransfer--[`++_acceptDefaultAdminTransfer++`]] +:changeDefaultAdminDelay: pass:normal[xref:#AccessControlDefaultAdminRules-changeDefaultAdminDelay-uint48-[`++changeDefaultAdminDelay++`]] +:_changeDefaultAdminDelay: pass:normal[xref:#AccessControlDefaultAdminRules-_changeDefaultAdminDelay-uint48-[`++_changeDefaultAdminDelay++`]] +:rollbackDefaultAdminDelay: pass:normal[xref:#AccessControlDefaultAdminRules-rollbackDefaultAdminDelay--[`++rollbackDefaultAdminDelay++`]] +:_rollbackDefaultAdminDelay: pass:normal[xref:#AccessControlDefaultAdminRules-_rollbackDefaultAdminDelay--[`++_rollbackDefaultAdminDelay++`]] +:_delayChangeWait: pass:normal[xref:#AccessControlDefaultAdminRules-_delayChangeWait-uint48-[`++_delayChangeWait++`]] + +[.contract] +[[AccessControlDefaultAdminRules]] +=== `++AccessControlDefaultAdminRules++` link:https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v5.0.0-rc.0/contracts/access/extensions/AccessControlDefaultAdminRules.sol[{github-icon},role=heading-link] + +[.hljs-theme-light.nopadding] +```solidity +import "@openzeppelin/contracts/access/extensions/AccessControlDefaultAdminRules.sol"; +``` + +Extension of {AccessControl} that allows specifying special rules to manage +the `DEFAULT_ADMIN_ROLE` holder, which is a sensitive role with special permissions +over other roles that may potentially have privileged rights in the system. + +If a specific role doesn't have an admin role assigned, the holder of the +`DEFAULT_ADMIN_ROLE` will have the ability to grant it and revoke it. + +This contract implements the following risk mitigations on top of {AccessControl}: + +* Only one account holds the `DEFAULT_ADMIN_ROLE` since deployment until it's potentially renounced. +* Enforces a 2-step process to transfer the `DEFAULT_ADMIN_ROLE` to another account. +* Enforces a configurable delay between the two steps, with the ability to cancel before the transfer is accepted. +* The delay can be changed by scheduling, see {changeDefaultAdminDelay}. +* It is not possible to use another role to manage the `DEFAULT_ADMIN_ROLE`. + +Example usage: + +```solidity +contract MyToken is AccessControlDefaultAdminRules { + constructor() AccessControlDefaultAdminRules( + 3 days, + msg.sender // Explicit initial `DEFAULT_ADMIN_ROLE` holder + ) {} +} +``` + +[.contract-index] +.Functions +-- +* {xref-AccessControlDefaultAdminRules-constructor-uint48-address-}[`++constructor(initialDelay, initialDefaultAdmin)++`] +* {xref-AccessControlDefaultAdminRules-supportsInterface-bytes4-}[`++supportsInterface(interfaceId)++`] +* {xref-AccessControlDefaultAdminRules-owner--}[`++owner()++`] +* {xref-AccessControlDefaultAdminRules-grantRole-bytes32-address-}[`++grantRole(role, account)++`] +* {xref-AccessControlDefaultAdminRules-revokeRole-bytes32-address-}[`++revokeRole(role, account)++`] +* {xref-AccessControlDefaultAdminRules-renounceRole-bytes32-address-}[`++renounceRole(role, account)++`] +* {xref-AccessControlDefaultAdminRules-_grantRole-bytes32-address-}[`++_grantRole(role, account)++`] +* {xref-AccessControlDefaultAdminRules-_revokeRole-bytes32-address-}[`++_revokeRole(role, account)++`] +* {xref-AccessControlDefaultAdminRules-_setRoleAdmin-bytes32-bytes32-}[`++_setRoleAdmin(role, adminRole)++`] +* {xref-AccessControlDefaultAdminRules-defaultAdmin--}[`++defaultAdmin()++`] +* {xref-AccessControlDefaultAdminRules-pendingDefaultAdmin--}[`++pendingDefaultAdmin()++`] +* {xref-AccessControlDefaultAdminRules-defaultAdminDelay--}[`++defaultAdminDelay()++`] +* {xref-AccessControlDefaultAdminRules-pendingDefaultAdminDelay--}[`++pendingDefaultAdminDelay()++`] +* {xref-AccessControlDefaultAdminRules-defaultAdminDelayIncreaseWait--}[`++defaultAdminDelayIncreaseWait()++`] +* {xref-AccessControlDefaultAdminRules-beginDefaultAdminTransfer-address-}[`++beginDefaultAdminTransfer(newAdmin)++`] +* {xref-AccessControlDefaultAdminRules-_beginDefaultAdminTransfer-address-}[`++_beginDefaultAdminTransfer(newAdmin)++`] +* {xref-AccessControlDefaultAdminRules-cancelDefaultAdminTransfer--}[`++cancelDefaultAdminTransfer()++`] +* {xref-AccessControlDefaultAdminRules-_cancelDefaultAdminTransfer--}[`++_cancelDefaultAdminTransfer()++`] +* {xref-AccessControlDefaultAdminRules-acceptDefaultAdminTransfer--}[`++acceptDefaultAdminTransfer()++`] +* {xref-AccessControlDefaultAdminRules-_acceptDefaultAdminTransfer--}[`++_acceptDefaultAdminTransfer()++`] +* {xref-AccessControlDefaultAdminRules-changeDefaultAdminDelay-uint48-}[`++changeDefaultAdminDelay(newDelay)++`] +* {xref-AccessControlDefaultAdminRules-_changeDefaultAdminDelay-uint48-}[`++_changeDefaultAdminDelay(newDelay)++`] +* {xref-AccessControlDefaultAdminRules-rollbackDefaultAdminDelay--}[`++rollbackDefaultAdminDelay()++`] +* {xref-AccessControlDefaultAdminRules-_rollbackDefaultAdminDelay--}[`++_rollbackDefaultAdminDelay()++`] +* {xref-AccessControlDefaultAdminRules-_delayChangeWait-uint48-}[`++_delayChangeWait(newDelay)++`] + +[.contract-subindex-inherited] +.AccessControl +* {xref-AccessControl-hasRole-bytes32-address-}[`++hasRole(role, account)++`] +* {xref-AccessControl-_checkRole-bytes32-}[`++_checkRole(role)++`] +* {xref-AccessControl-_checkRole-bytes32-address-}[`++_checkRole(role, account)++`] +* {xref-AccessControl-getRoleAdmin-bytes32-}[`++getRoleAdmin(role)++`] + +[.contract-subindex-inherited] +.ERC165 + +[.contract-subindex-inherited] +.IERC165 + +[.contract-subindex-inherited] +.IERC5313 + +[.contract-subindex-inherited] +.IAccessControlDefaultAdminRules + +[.contract-subindex-inherited] +.IAccessControl + +-- + +[.contract-index] +.Events +-- + +[.contract-subindex-inherited] +.AccessControl + +[.contract-subindex-inherited] +.ERC165 + +[.contract-subindex-inherited] +.IERC165 + +[.contract-subindex-inherited] +.IERC5313 + +[.contract-subindex-inherited] +.IAccessControlDefaultAdminRules +* {xref-IAccessControlDefaultAdminRules-DefaultAdminTransferScheduled-address-uint48-}[`++DefaultAdminTransferScheduled(newAdmin, acceptSchedule)++`] +* {xref-IAccessControlDefaultAdminRules-DefaultAdminTransferCanceled--}[`++DefaultAdminTransferCanceled()++`] +* {xref-IAccessControlDefaultAdminRules-DefaultAdminDelayChangeScheduled-uint48-uint48-}[`++DefaultAdminDelayChangeScheduled(newDelay, effectSchedule)++`] +* {xref-IAccessControlDefaultAdminRules-DefaultAdminDelayChangeCanceled--}[`++DefaultAdminDelayChangeCanceled()++`] + +[.contract-subindex-inherited] +.IAccessControl +* {xref-IAccessControl-RoleAdminChanged-bytes32-bytes32-bytes32-}[`++RoleAdminChanged(role, previousAdminRole, newAdminRole)++`] +* {xref-IAccessControl-RoleGranted-bytes32-address-address-}[`++RoleGranted(role, account, sender)++`] +* {xref-IAccessControl-RoleRevoked-bytes32-address-address-}[`++RoleRevoked(role, account, sender)++`] + +-- + +[.contract-index] +.Errors +-- + +[.contract-subindex-inherited] +.AccessControl + +[.contract-subindex-inherited] +.ERC165 + +[.contract-subindex-inherited] +.IERC165 + +[.contract-subindex-inherited] +.IERC5313 + +[.contract-subindex-inherited] +.IAccessControlDefaultAdminRules +* {xref-IAccessControlDefaultAdminRules-AccessControlInvalidDefaultAdmin-address-}[`++AccessControlInvalidDefaultAdmin(defaultAdmin)++`] +* {xref-IAccessControlDefaultAdminRules-AccessControlEnforcedDefaultAdminRules--}[`++AccessControlEnforcedDefaultAdminRules()++`] +* {xref-IAccessControlDefaultAdminRules-AccessControlEnforcedDefaultAdminDelay-uint48-}[`++AccessControlEnforcedDefaultAdminDelay(schedule)++`] + +[.contract-subindex-inherited] +.IAccessControl +* {xref-IAccessControl-AccessControlUnauthorizedAccount-address-bytes32-}[`++AccessControlUnauthorizedAccount(account, neededRole)++`] +* {xref-IAccessControl-AccessControlBadConfirmation--}[`++AccessControlBadConfirmation()++`] + +-- + +[.contract-item] +[[AccessControlDefaultAdminRules-constructor-uint48-address-]] +==== `[.contract-item-name]#++constructor++#++(uint48 initialDelay, address initialDefaultAdmin)++` [.item-kind]#internal# + +Sets the initial values for {defaultAdminDelay} and {defaultAdmin} address. + +[.contract-item] +[[AccessControlDefaultAdminRules-supportsInterface-bytes4-]] +==== `[.contract-item-name]#++supportsInterface++#++(bytes4 interfaceId) → bool++` [.item-kind]#public# + +See {IERC165-supportsInterface}. + +[.contract-item] +[[AccessControlDefaultAdminRules-owner--]] +==== `[.contract-item-name]#++owner++#++() → address++` [.item-kind]#public# + +See {IERC5313-owner}. + +[.contract-item] +[[AccessControlDefaultAdminRules-grantRole-bytes32-address-]] +==== `[.contract-item-name]#++grantRole++#++(bytes32 role, address account)++` [.item-kind]#public# + +See {AccessControl-grantRole}. Reverts for `DEFAULT_ADMIN_ROLE`. + +[.contract-item] +[[AccessControlDefaultAdminRules-revokeRole-bytes32-address-]] +==== `[.contract-item-name]#++revokeRole++#++(bytes32 role, address account)++` [.item-kind]#public# + +See {AccessControl-revokeRole}. Reverts for `DEFAULT_ADMIN_ROLE`. + +[.contract-item] +[[AccessControlDefaultAdminRules-renounceRole-bytes32-address-]] +==== `[.contract-item-name]#++renounceRole++#++(bytes32 role, address account)++` [.item-kind]#public# + +See {AccessControl-renounceRole}. + +For the `DEFAULT_ADMIN_ROLE`, it only allows renouncing in two steps by first calling +{beginDefaultAdminTransfer} to the `address(0)`, so it's required that the {pendingDefaultAdmin} schedule +has also passed when calling this function. + +After its execution, it will not be possible to call `onlyRole(DEFAULT_ADMIN_ROLE)` functions. + +NOTE: Renouncing `DEFAULT_ADMIN_ROLE` will leave the contract without a {defaultAdmin}, +thereby disabling any functionality that is only available for it, and the possibility of reassigning a +non-administrated role. + +[.contract-item] +[[AccessControlDefaultAdminRules-_grantRole-bytes32-address-]] +==== `[.contract-item-name]#++_grantRole++#++(bytes32 role, address account) → bool++` [.item-kind]#internal# + +See {AccessControl-_grantRole}. + +For `DEFAULT_ADMIN_ROLE`, it only allows granting if there isn't already a {defaultAdmin} or if the +role has been previously renounced. + +NOTE: Exposing this function through another mechanism may make the `DEFAULT_ADMIN_ROLE` +assignable again. Make sure to guarantee this is the expected behavior in your implementation. + +[.contract-item] +[[AccessControlDefaultAdminRules-_revokeRole-bytes32-address-]] +==== `[.contract-item-name]#++_revokeRole++#++(bytes32 role, address account) → bool++` [.item-kind]#internal# + +See {AccessControl-_revokeRole}. + +[.contract-item] +[[AccessControlDefaultAdminRules-_setRoleAdmin-bytes32-bytes32-]] +==== `[.contract-item-name]#++_setRoleAdmin++#++(bytes32 role, bytes32 adminRole)++` [.item-kind]#internal# + +See {AccessControl-_setRoleAdmin}. Reverts for `DEFAULT_ADMIN_ROLE`. + +[.contract-item] +[[AccessControlDefaultAdminRules-defaultAdmin--]] +==== `[.contract-item-name]#++defaultAdmin++#++() → address++` [.item-kind]#public# + +Returns the address of the current `DEFAULT_ADMIN_ROLE` holder. + +[.contract-item] +[[AccessControlDefaultAdminRules-pendingDefaultAdmin--]] +==== `[.contract-item-name]#++pendingDefaultAdmin++#++() → address newAdmin, uint48 schedule++` [.item-kind]#public# + +Returns a tuple of a `newAdmin` and an accept schedule. + +After the `schedule` passes, the `newAdmin` will be able to accept the {defaultAdmin} role +by calling {acceptDefaultAdminTransfer}, completing the role transfer. + +A zero value only in `acceptSchedule` indicates no pending admin transfer. + +NOTE: A zero address `newAdmin` means that {defaultAdmin} is being renounced. + +[.contract-item] +[[AccessControlDefaultAdminRules-defaultAdminDelay--]] +==== `[.contract-item-name]#++defaultAdminDelay++#++() → uint48++` [.item-kind]#public# + +Returns the delay required to schedule the acceptance of a {defaultAdmin} transfer started. + +This delay will be added to the current timestamp when calling {beginDefaultAdminTransfer} to set +the acceptance schedule. + +NOTE: If a delay change has been scheduled, it will take effect as soon as the schedule passes, making this +function returns the new delay. See {changeDefaultAdminDelay}. + +[.contract-item] +[[AccessControlDefaultAdminRules-pendingDefaultAdminDelay--]] +==== `[.contract-item-name]#++pendingDefaultAdminDelay++#++() → uint48 newDelay, uint48 schedule++` [.item-kind]#public# + +Returns a tuple of `newDelay` and an effect schedule. + +After the `schedule` passes, the `newDelay` will get into effect immediately for every +new {defaultAdmin} transfer started with {beginDefaultAdminTransfer}. + +A zero value only in `effectSchedule` indicates no pending delay change. + +NOTE: A zero value only for `newDelay` means that the next {defaultAdminDelay} +will be zero after the effect schedule. + +[.contract-item] +[[AccessControlDefaultAdminRules-defaultAdminDelayIncreaseWait--]] +==== `[.contract-item-name]#++defaultAdminDelayIncreaseWait++#++() → uint48++` [.item-kind]#public# + +Maximum time in seconds for an increase to {defaultAdminDelay} (that is scheduled using {changeDefaultAdminDelay}) +to take effect. Default to 5 days. + +When the {defaultAdminDelay} is scheduled to be increased, it goes into effect after the new delay has passed with +the purpose of giving enough time for reverting any accidental change (i.e. using milliseconds instead of seconds) +that may lock the contract. However, to avoid excessive schedules, the wait is capped by this function and it can +be overrode for a custom {defaultAdminDelay} increase scheduling. + +IMPORTANT: Make sure to add a reasonable amount of time while overriding this value, otherwise, +there's a risk of setting a high new delay that goes into effect almost immediately without the +possibility of human intervention in the case of an input error (eg. set milliseconds instead of seconds). + +[.contract-item] +[[AccessControlDefaultAdminRules-beginDefaultAdminTransfer-address-]] +==== `[.contract-item-name]#++beginDefaultAdminTransfer++#++(address newAdmin)++` [.item-kind]#public# + +Starts a {defaultAdmin} transfer by setting a {pendingDefaultAdmin} scheduled for acceptance +after the current timestamp plus a {defaultAdminDelay}. + +Requirements: + +- Only can be called by the current {defaultAdmin}. + +Emits a DefaultAdminRoleChangeStarted event. + +[.contract-item] +[[AccessControlDefaultAdminRules-_beginDefaultAdminTransfer-address-]] +==== `[.contract-item-name]#++_beginDefaultAdminTransfer++#++(address newAdmin)++` [.item-kind]#internal# + +See {beginDefaultAdminTransfer}. + +Internal function without access restriction. + +[.contract-item] +[[AccessControlDefaultAdminRules-cancelDefaultAdminTransfer--]] +==== `[.contract-item-name]#++cancelDefaultAdminTransfer++#++()++` [.item-kind]#public# + +Cancels a {defaultAdmin} transfer previously started with {beginDefaultAdminTransfer}. + +A {pendingDefaultAdmin} not yet accepted can also be cancelled with this function. + +Requirements: + +- Only can be called by the current {defaultAdmin}. + +May emit a DefaultAdminTransferCanceled event. + +[.contract-item] +[[AccessControlDefaultAdminRules-_cancelDefaultAdminTransfer--]] +==== `[.contract-item-name]#++_cancelDefaultAdminTransfer++#++()++` [.item-kind]#internal# + +See {cancelDefaultAdminTransfer}. + +Internal function without access restriction. + +[.contract-item] +[[AccessControlDefaultAdminRules-acceptDefaultAdminTransfer--]] +==== `[.contract-item-name]#++acceptDefaultAdminTransfer++#++()++` [.item-kind]#public# + +Completes a {defaultAdmin} transfer previously started with {beginDefaultAdminTransfer}. + +After calling the function: + +- `DEFAULT_ADMIN_ROLE` should be granted to the caller. +- `DEFAULT_ADMIN_ROLE` should be revoked from the previous holder. +- {pendingDefaultAdmin} should be reset to zero values. + +Requirements: + +- Only can be called by the {pendingDefaultAdmin}'s `newAdmin`. +- The {pendingDefaultAdmin}'s `acceptSchedule` should've passed. + +[.contract-item] +[[AccessControlDefaultAdminRules-_acceptDefaultAdminTransfer--]] +==== `[.contract-item-name]#++_acceptDefaultAdminTransfer++#++()++` [.item-kind]#internal# + +See {acceptDefaultAdminTransfer}. + +Internal function without access restriction. + +[.contract-item] +[[AccessControlDefaultAdminRules-changeDefaultAdminDelay-uint48-]] +==== `[.contract-item-name]#++changeDefaultAdminDelay++#++(uint48 newDelay)++` [.item-kind]#public# + +Initiates a {defaultAdminDelay} update by setting a {pendingDefaultAdminDelay} scheduled for getting +into effect after the current timestamp plus a {defaultAdminDelay}. + +This function guarantees that any call to {beginDefaultAdminTransfer} done between the timestamp this +method is called and the {pendingDefaultAdminDelay} effect schedule will use the current {defaultAdminDelay} +set before calling. + +The {pendingDefaultAdminDelay}'s effect schedule is defined in a way that waiting until the schedule and then +calling {beginDefaultAdminTransfer} with the new delay will take at least the same as another {defaultAdmin} +complete transfer (including acceptance). + +The schedule is designed for two scenarios: + +- When the delay is changed for a larger one the schedule is `block.timestamp + newDelay` capped by +{defaultAdminDelayIncreaseWait}. +- When the delay is changed for a shorter one, the schedule is `block.timestamp + (current delay - new delay)`. + +A {pendingDefaultAdminDelay} that never got into effect will be canceled in favor of a new scheduled change. + +Requirements: + +- Only can be called by the current {defaultAdmin}. + +Emits a DefaultAdminDelayChangeScheduled event and may emit a DefaultAdminDelayChangeCanceled event. + +[.contract-item] +[[AccessControlDefaultAdminRules-_changeDefaultAdminDelay-uint48-]] +==== `[.contract-item-name]#++_changeDefaultAdminDelay++#++(uint48 newDelay)++` [.item-kind]#internal# + +See {changeDefaultAdminDelay}. + +Internal function without access restriction. + +[.contract-item] +[[AccessControlDefaultAdminRules-rollbackDefaultAdminDelay--]] +==== `[.contract-item-name]#++rollbackDefaultAdminDelay++#++()++` [.item-kind]#public# + +Cancels a scheduled {defaultAdminDelay} change. + +Requirements: + +- Only can be called by the current {defaultAdmin}. + +May emit a DefaultAdminDelayChangeCanceled event. + +[.contract-item] +[[AccessControlDefaultAdminRules-_rollbackDefaultAdminDelay--]] +==== `[.contract-item-name]#++_rollbackDefaultAdminDelay++#++()++` [.item-kind]#internal# + +See {rollbackDefaultAdminDelay}. + +Internal function without access restriction. + +[.contract-item] +[[AccessControlDefaultAdminRules-_delayChangeWait-uint48-]] +==== `[.contract-item-name]#++_delayChangeWait++#++(uint48 newDelay) → uint48++` [.item-kind]#internal# + +Returns the amount of seconds to wait after the `newDelay` will +become the new {defaultAdminDelay}. + +The value returned guarantees that if the delay is reduced, it will go into effect +after a wait that honors the previously set delay. + +See {defaultAdminDelayIncreaseWait}. + +== AccessManager + +:canCall: pass:normal[xref:#IAuthority-canCall-address-address-bytes4-[`++canCall++`]] + +[.contract] +[[IAuthority]] +=== `++IAuthority++` link:https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v5.0.0-rc.0/contracts/access/manager/IAuthority.sol[{github-icon},role=heading-link] + +[.hljs-theme-light.nopadding] +```solidity +import "@openzeppelin/contracts/access/manager/IAuthority.sol"; +``` + +Standard interface for permissioning originally defined in Dappsys. + +[.contract-index] +.Functions +-- +* {xref-IAuthority-canCall-address-address-bytes4-}[`++canCall(caller, target, selector)++`] + +-- + +[.contract-item] +[[IAuthority-canCall-address-address-bytes4-]] +==== `[.contract-item-name]#++canCall++#++(address caller, address target, bytes4 selector) → bool allowed++` [.item-kind]#external# + +Returns true if the caller can invoke on a target the function identified by a function selector. + +:TargetConfig: pass:normal[xref:#AccessManager-TargetConfig[`++TargetConfig++`]] +:Access: pass:normal[xref:#AccessManager-Access[`++Access++`]] +:Role: pass:normal[xref:#AccessManager-Role[`++Role++`]] +:Schedule: pass:normal[xref:#AccessManager-Schedule[`++Schedule++`]] +:ADMIN_ROLE: pass:normal[xref:#AccessManager-ADMIN_ROLE-uint64[`++ADMIN_ROLE++`]] +:PUBLIC_ROLE: pass:normal[xref:#AccessManager-PUBLIC_ROLE-uint64[`++PUBLIC_ROLE++`]] +:onlyAuthorized: pass:normal[xref:#AccessManager-onlyAuthorized--[`++onlyAuthorized++`]] +:constructor: pass:normal[xref:#AccessManager-constructor-address-[`++constructor++`]] +:canCall: pass:normal[xref:#AccessManager-canCall-address-address-bytes4-[`++canCall++`]] +:expiration: pass:normal[xref:#AccessManager-expiration--[`++expiration++`]] +:minSetback: pass:normal[xref:#AccessManager-minSetback--[`++minSetback++`]] +:isTargetClosed: pass:normal[xref:#AccessManager-isTargetClosed-address-[`++isTargetClosed++`]] +:getTargetFunctionRole: pass:normal[xref:#AccessManager-getTargetFunctionRole-address-bytes4-[`++getTargetFunctionRole++`]] +:getTargetAdminDelay: pass:normal[xref:#AccessManager-getTargetAdminDelay-address-[`++getTargetAdminDelay++`]] +:getRoleAdmin: pass:normal[xref:#AccessManager-getRoleAdmin-uint64-[`++getRoleAdmin++`]] +:getRoleGuardian: pass:normal[xref:#AccessManager-getRoleGuardian-uint64-[`++getRoleGuardian++`]] +:getRoleGrantDelay: pass:normal[xref:#AccessManager-getRoleGrantDelay-uint64-[`++getRoleGrantDelay++`]] +:getAccess: pass:normal[xref:#AccessManager-getAccess-uint64-address-[`++getAccess++`]] +:hasRole: pass:normal[xref:#AccessManager-hasRole-uint64-address-[`++hasRole++`]] +:labelRole: pass:normal[xref:#AccessManager-labelRole-uint64-string-[`++labelRole++`]] +:grantRole: pass:normal[xref:#AccessManager-grantRole-uint64-address-uint32-[`++grantRole++`]] +:revokeRole: pass:normal[xref:#AccessManager-revokeRole-uint64-address-[`++revokeRole++`]] +:renounceRole: pass:normal[xref:#AccessManager-renounceRole-uint64-address-[`++renounceRole++`]] +:setRoleAdmin: pass:normal[xref:#AccessManager-setRoleAdmin-uint64-uint64-[`++setRoleAdmin++`]] +:setRoleGuardian: pass:normal[xref:#AccessManager-setRoleGuardian-uint64-uint64-[`++setRoleGuardian++`]] +:setGrantDelay: pass:normal[xref:#AccessManager-setGrantDelay-uint64-uint32-[`++setGrantDelay++`]] +:_grantRole: pass:normal[xref:#AccessManager-_grantRole-uint64-address-uint32-uint32-[`++_grantRole++`]] +:_revokeRole: pass:normal[xref:#AccessManager-_revokeRole-uint64-address-[`++_revokeRole++`]] +:_setRoleAdmin: pass:normal[xref:#AccessManager-_setRoleAdmin-uint64-uint64-[`++_setRoleAdmin++`]] +:_setRoleGuardian: pass:normal[xref:#AccessManager-_setRoleGuardian-uint64-uint64-[`++_setRoleGuardian++`]] +:_setGrantDelay: pass:normal[xref:#AccessManager-_setGrantDelay-uint64-uint32-[`++_setGrantDelay++`]] +:setTargetFunctionRole: pass:normal[xref:#AccessManager-setTargetFunctionRole-address-bytes4---uint64-[`++setTargetFunctionRole++`]] +:_setTargetFunctionRole: pass:normal[xref:#AccessManager-_setTargetFunctionRole-address-bytes4-uint64-[`++_setTargetFunctionRole++`]] +:setTargetAdminDelay: pass:normal[xref:#AccessManager-setTargetAdminDelay-address-uint32-[`++setTargetAdminDelay++`]] +:_setTargetAdminDelay: pass:normal[xref:#AccessManager-_setTargetAdminDelay-address-uint32-[`++_setTargetAdminDelay++`]] +:setTargetClosed: pass:normal[xref:#AccessManager-setTargetClosed-address-bool-[`++setTargetClosed++`]] +:_setTargetClosed: pass:normal[xref:#AccessManager-_setTargetClosed-address-bool-[`++_setTargetClosed++`]] +:getSchedule: pass:normal[xref:#AccessManager-getSchedule-bytes32-[`++getSchedule++`]] +:getNonce: pass:normal[xref:#AccessManager-getNonce-bytes32-[`++getNonce++`]] +:schedule: pass:normal[xref:#AccessManager-schedule-address-bytes-uint48-[`++schedule++`]] +:execute: pass:normal[xref:#AccessManager-execute-address-bytes-[`++execute++`]] +:consumeScheduledOp: pass:normal[xref:#AccessManager-consumeScheduledOp-address-bytes-[`++consumeScheduledOp++`]] +:_consumeScheduledOp: pass:normal[xref:#AccessManager-_consumeScheduledOp-bytes32-[`++_consumeScheduledOp++`]] +:cancel: pass:normal[xref:#AccessManager-cancel-address-address-bytes-[`++cancel++`]] +:hashOperation: pass:normal[xref:#AccessManager-hashOperation-address-address-bytes-[`++hashOperation++`]] +:updateAuthority: pass:normal[xref:#AccessManager-updateAuthority-address-address-[`++updateAuthority++`]] + +[.contract] +[[AccessManager]] +=== `++AccessManager++` link:https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v5.0.0-rc.0/contracts/access/manager/AccessManager.sol[{github-icon},role=heading-link] + +[.hljs-theme-light.nopadding] +```solidity +import "@openzeppelin/contracts/access/manager/AccessManager.sol"; +``` + +AccessManager is a central contract to store the permissions of a system. + +The smart contracts under the control of an AccessManager instance will have a set of "restricted" functions, and the +exact details of how access is restricted for each of those functions is configurable by the admins of the instance. +These restrictions are expressed in terms of "roles". + +An AccessManager instance will define a set of roles. Accounts can be added into any number of these roles. Each of +them defines a role, and may confer access to some of the restricted functions in the system, as configured by admins +through the use of {setFunctionAllowedRoles}. + +Note that a function in a target contract may become permissioned in this way only when: 1) said contract is +{AccessManaged} and is connected to this contract as its manager, and 2) said function is decorated with the +`restricted` modifier. + +There is a special role defined by default named "public" which all accounts automatically have. + +In addition to the access rules defined by each target's functions being assigned to roles, then entire target can +be "closed". This "closed" mode is set/unset by the admin using {setTargetClosed} and can be used to lock a contract +while permissions are being (re-)configured. + +Since all the permissions of the managed system can be modified by the admins of this instance, it is expected that +they will be highly secured (e.g., a multisig or a well-configured DAO). + +NOTE: This contract implements a form of the {IAuthority} interface, but {canCall} has additional return data so it +doesn't inherit `IAuthority`. It is however compatible with the `IAuthority` interface since the first 32 bytes of +the return data are a boolean as expected by that interface. + +NOTE: Systems that implement other access control mechanisms (for example using {Ownable}) can be paired with an +{AccessManager} by transferring permissions (ownership in the case of {Ownable}) directly to the {AccessManager}. +Users will be able to interact with these contracts through the {execute} function, following the access rules +registered in the {AccessManager}. Keep in mind that in that context, the msg.sender seen by restricted functions +will be {AccessManager} itself. + +WARNING: When granting permissions over an {Ownable} or {AccessControl} contract to an {AccessManager}, be very +mindful of the danger associated with functions such as {{Ownable-renounceOwnership}} or +{{AccessControl-renounceRole}}. + +[.contract-index] +.Modifiers +-- +* {xref-AccessManager-onlyAuthorized--}[`++onlyAuthorized()++`] +-- + +[.contract-index] +.Functions +-- +* {xref-AccessManager-constructor-address-}[`++constructor(initialAdmin)++`] +* {xref-AccessManager-canCall-address-address-bytes4-}[`++canCall(caller, target, selector)++`] +* {xref-AccessManager-expiration--}[`++expiration()++`] +* {xref-AccessManager-minSetback--}[`++minSetback()++`] +* {xref-AccessManager-isTargetClosed-address-}[`++isTargetClosed(target)++`] +* {xref-AccessManager-getTargetFunctionRole-address-bytes4-}[`++getTargetFunctionRole(target, selector)++`] +* {xref-AccessManager-getTargetAdminDelay-address-}[`++getTargetAdminDelay(target)++`] +* {xref-AccessManager-getRoleAdmin-uint64-}[`++getRoleAdmin(roleId)++`] +* {xref-AccessManager-getRoleGuardian-uint64-}[`++getRoleGuardian(roleId)++`] +* {xref-AccessManager-getRoleGrantDelay-uint64-}[`++getRoleGrantDelay(roleId)++`] +* {xref-AccessManager-getAccess-uint64-address-}[`++getAccess(roleId, account)++`] +* {xref-AccessManager-hasRole-uint64-address-}[`++hasRole(roleId, account)++`] +* {xref-AccessManager-labelRole-uint64-string-}[`++labelRole(roleId, label)++`] +* {xref-AccessManager-grantRole-uint64-address-uint32-}[`++grantRole(roleId, account, executionDelay)++`] +* {xref-AccessManager-revokeRole-uint64-address-}[`++revokeRole(roleId, account)++`] +* {xref-AccessManager-renounceRole-uint64-address-}[`++renounceRole(roleId, callerConfirmation)++`] +* {xref-AccessManager-setRoleAdmin-uint64-uint64-}[`++setRoleAdmin(roleId, admin)++`] +* {xref-AccessManager-setRoleGuardian-uint64-uint64-}[`++setRoleGuardian(roleId, guardian)++`] +* {xref-AccessManager-setGrantDelay-uint64-uint32-}[`++setGrantDelay(roleId, newDelay)++`] +* {xref-AccessManager-_grantRole-uint64-address-uint32-uint32-}[`++_grantRole(roleId, account, grantDelay, executionDelay)++`] +* {xref-AccessManager-_revokeRole-uint64-address-}[`++_revokeRole(roleId, account)++`] +* {xref-AccessManager-_setRoleAdmin-uint64-uint64-}[`++_setRoleAdmin(roleId, admin)++`] +* {xref-AccessManager-_setRoleGuardian-uint64-uint64-}[`++_setRoleGuardian(roleId, guardian)++`] +* {xref-AccessManager-_setGrantDelay-uint64-uint32-}[`++_setGrantDelay(roleId, newDelay)++`] +* {xref-AccessManager-setTargetFunctionRole-address-bytes4---uint64-}[`++setTargetFunctionRole(target, selectors, roleId)++`] +* {xref-AccessManager-_setTargetFunctionRole-address-bytes4-uint64-}[`++_setTargetFunctionRole(target, selector, roleId)++`] +* {xref-AccessManager-setTargetAdminDelay-address-uint32-}[`++setTargetAdminDelay(target, newDelay)++`] +* {xref-AccessManager-_setTargetAdminDelay-address-uint32-}[`++_setTargetAdminDelay(target, newDelay)++`] +* {xref-AccessManager-setTargetClosed-address-bool-}[`++setTargetClosed(target, closed)++`] +* {xref-AccessManager-_setTargetClosed-address-bool-}[`++_setTargetClosed(target, closed)++`] +* {xref-AccessManager-getSchedule-bytes32-}[`++getSchedule(id)++`] +* {xref-AccessManager-getNonce-bytes32-}[`++getNonce(id)++`] +* {xref-AccessManager-schedule-address-bytes-uint48-}[`++schedule(target, data, when)++`] +* {xref-AccessManager-execute-address-bytes-}[`++execute(target, data)++`] +* {xref-AccessManager-consumeScheduledOp-address-bytes-}[`++consumeScheduledOp(caller, data)++`] +* {xref-AccessManager-_consumeScheduledOp-bytes32-}[`++_consumeScheduledOp(operationId)++`] +* {xref-AccessManager-cancel-address-address-bytes-}[`++cancel(caller, target, data)++`] +* {xref-AccessManager-hashOperation-address-address-bytes-}[`++hashOperation(caller, target, data)++`] +* {xref-AccessManager-updateAuthority-address-address-}[`++updateAuthority(target, newAuthority)++`] + +[.contract-subindex-inherited] +.IAccessManager + +[.contract-subindex-inherited] +.Multicall +* {xref-Multicall-multicall-bytes---}[`++multicall(data)++`] + +-- + +[.contract-index] +.Events +-- + +[.contract-subindex-inherited] +.IAccessManager +* {xref-IAccessManager-OperationScheduled-bytes32-uint32-uint48-address-address-bytes-}[`++OperationScheduled(operationId, nonce, schedule, caller, target, data)++`] +* {xref-IAccessManager-OperationExecuted-bytes32-uint32-}[`++OperationExecuted(operationId, nonce)++`] +* {xref-IAccessManager-OperationCanceled-bytes32-uint32-}[`++OperationCanceled(operationId, nonce)++`] +* {xref-IAccessManager-RoleLabel-uint64-string-}[`++RoleLabel(roleId, label)++`] +* {xref-IAccessManager-RoleGranted-uint64-address-uint32-uint48-bool-}[`++RoleGranted(roleId, account, delay, since, newMember)++`] +* {xref-IAccessManager-RoleRevoked-uint64-address-}[`++RoleRevoked(roleId, account)++`] +* {xref-IAccessManager-RoleAdminChanged-uint64-uint64-}[`++RoleAdminChanged(roleId, admin)++`] +* {xref-IAccessManager-RoleGuardianChanged-uint64-uint64-}[`++RoleGuardianChanged(roleId, guardian)++`] +* {xref-IAccessManager-RoleGrantDelayChanged-uint64-uint32-uint48-}[`++RoleGrantDelayChanged(roleId, delay, since)++`] +* {xref-IAccessManager-TargetClosed-address-bool-}[`++TargetClosed(target, closed)++`] +* {xref-IAccessManager-TargetFunctionRoleUpdated-address-bytes4-uint64-}[`++TargetFunctionRoleUpdated(target, selector, roleId)++`] +* {xref-IAccessManager-TargetAdminDelayUpdated-address-uint32-uint48-}[`++TargetAdminDelayUpdated(target, delay, since)++`] + +[.contract-subindex-inherited] +.Multicall + +-- + +[.contract-index] +.Errors +-- + +[.contract-subindex-inherited] +.IAccessManager +* {xref-IAccessManager-AccessManagerAlreadyScheduled-bytes32-}[`++AccessManagerAlreadyScheduled(operationId)++`] +* {xref-IAccessManager-AccessManagerNotScheduled-bytes32-}[`++AccessManagerNotScheduled(operationId)++`] +* {xref-IAccessManager-AccessManagerNotReady-bytes32-}[`++AccessManagerNotReady(operationId)++`] +* {xref-IAccessManager-AccessManagerExpired-bytes32-}[`++AccessManagerExpired(operationId)++`] +* {xref-IAccessManager-AccessManagerLockedAccount-address-}[`++AccessManagerLockedAccount(account)++`] +* {xref-IAccessManager-AccessManagerLockedRole-uint64-}[`++AccessManagerLockedRole(roleId)++`] +* {xref-IAccessManager-AccessManagerBadConfirmation--}[`++AccessManagerBadConfirmation()++`] +* {xref-IAccessManager-AccessManagerUnauthorizedAccount-address-uint64-}[`++AccessManagerUnauthorizedAccount(msgsender, roleId)++`] +* {xref-IAccessManager-AccessManagerUnauthorizedCall-address-address-bytes4-}[`++AccessManagerUnauthorizedCall(caller, target, selector)++`] +* {xref-IAccessManager-AccessManagerUnauthorizedConsume-address-}[`++AccessManagerUnauthorizedConsume(target)++`] +* {xref-IAccessManager-AccessManagerUnauthorizedCancel-address-address-address-bytes4-}[`++AccessManagerUnauthorizedCancel(msgsender, caller, target, selector)++`] +* {xref-IAccessManager-AccessManagerInvalidInitialAdmin-address-}[`++AccessManagerInvalidInitialAdmin(initialAdmin)++`] + +[.contract-subindex-inherited] +.Multicall + +-- + +[.contract-item] +[[AccessManager-onlyAuthorized--]] +==== `[.contract-item-name]#++onlyAuthorized++#++()++` [.item-kind]#modifier# + +Check that the caller is authorized to perform the operation, following the restrictions encoded in +{_getAdminRestrictions}. + +[.contract-item] +[[AccessManager-constructor-address-]] +==== `[.contract-item-name]#++constructor++#++(address initialAdmin)++` [.item-kind]#public# + +[.contract-item] +[[AccessManager-canCall-address-address-bytes4-]] +==== `[.contract-item-name]#++canCall++#++(address caller, address target, bytes4 selector) → bool, uint32++` [.item-kind]#public# + +Check if an address (`caller`) is authorised to call a given function on a given contract directly (with +no restriction). Additionally, it returns the delay needed to perform the call indirectly through the {schedule} +& {execute} workflow. + +This function is usually called by the targeted contract to control immediate execution of restricted functions. +Therefore we only return true is the call can be performed without any delay. If the call is subject to a delay, +then the function should return false, and the caller should schedule the operation for future execution. + +We may be able to hash the operation, and check if the call was scheduled, but we would not be able to cleanup +the schedule, leaving the possibility of multiple executions. Maybe this function should not be view? + +NOTE: The IAuthority interface does not include the `uint32` delay. This is an extension of that interface that +is backward compatible. Some contracts may thus ignore the second return argument. In that case they will fail +to identify the indirect workflow, and will consider calls that require a delay to be forbidden. + +[.contract-item] +[[AccessManager-expiration--]] +==== `[.contract-item-name]#++expiration++#++() → uint32++` [.item-kind]#public# + +Expiration delay for scheduled proposals. Defaults to 1 week. + +[.contract-item] +[[AccessManager-minSetback--]] +==== `[.contract-item-name]#++minSetback++#++() → uint32++` [.item-kind]#public# + +Minimum setback for all delay updates, with the exception of execution delays, which +can be increased without setback (and in the event of an accidental increase can be reset +via {revokeRole}). Defaults to 5 days. + +[.contract-item] +[[AccessManager-isTargetClosed-address-]] +==== `[.contract-item-name]#++isTargetClosed++#++(address target) → bool++` [.item-kind]#public# + +Get the mode under which a contract is operating. + +[.contract-item] +[[AccessManager-getTargetFunctionRole-address-bytes4-]] +==== `[.contract-item-name]#++getTargetFunctionRole++#++(address target, bytes4 selector) → uint64++` [.item-kind]#public# + +Get the role required to call a function. + +[.contract-item] +[[AccessManager-getTargetAdminDelay-address-]] +==== `[.contract-item-name]#++getTargetAdminDelay++#++(address target) → uint32++` [.item-kind]#public# + +Get the admin delay for a target contract. Changes to contract configuration are subject to this delay. + +[.contract-item] +[[AccessManager-getRoleAdmin-uint64-]] +==== `[.contract-item-name]#++getRoleAdmin++#++(uint64 roleId) → uint64++` [.item-kind]#public# + +Get the id of the role that acts as an admin for given role. + +The admin permission is required to grant the role, revoke the role and update the execution delay to execute +an operation that is restricted to this role. + +[.contract-item] +[[AccessManager-getRoleGuardian-uint64-]] +==== `[.contract-item-name]#++getRoleGuardian++#++(uint64 roleId) → uint64++` [.item-kind]#public# + +Get the role that acts as a guardian for a given role. + +The guardian permission allows canceling operations that have been scheduled under the role. + +[.contract-item] +[[AccessManager-getRoleGrantDelay-uint64-]] +==== `[.contract-item-name]#++getRoleGrantDelay++#++(uint64 roleId) → uint32++` [.item-kind]#public# + +Get the role current grant delay, that value may change at any point, without an event emitted, following +a call to {setGrantDelay}. Changes to this value, including effect timepoint are notified by the +{RoleGrantDelayChanged} event. + +[.contract-item] +[[AccessManager-getAccess-uint64-address-]] +==== `[.contract-item-name]#++getAccess++#++(uint64 roleId, address account) → uint48, uint32, uint32, uint48++` [.item-kind]#public# + +Get the access details for a given account for a given role. These details include the timepoint at which +membership becomes active, and the delay applied to all operation by this user that requires this permission +level. + +Returns: +[0] Timestamp at which the account membership becomes valid. 0 means role is not granted. +[1] Current execution delay for the account. +[2] Pending execution delay for the account. +[3] Timestamp at which the pending execution delay will become active. 0 means no delay update is scheduled. + +[.contract-item] +[[AccessManager-hasRole-uint64-address-]] +==== `[.contract-item-name]#++hasRole++#++(uint64 roleId, address account) → bool, uint32++` [.item-kind]#public# + +Check if a given account currently had the permission level corresponding to a given role. Note that this +permission might be associated with a delay. {getAccess} can provide more details. + +[.contract-item] +[[AccessManager-labelRole-uint64-string-]] +==== `[.contract-item-name]#++labelRole++#++(uint64 roleId, string label)++` [.item-kind]#public# + +Give a label to a role, for improved role discoverabily by UIs. + +Emits a {RoleLabel} event. + +[.contract-item] +[[AccessManager-grantRole-uint64-address-uint32-]] +==== `[.contract-item-name]#++grantRole++#++(uint64 roleId, address account, uint32 executionDelay)++` [.item-kind]#public# + +Add `account` to `roleId`, or change its execution delay. + +This gives the account the authorization to call any function that is restricted to this role. An optional +execution delay (in seconds) can be set. If that delay is non 0, the user is required to schedule any operation +that is restricted to members this role. The user will only be able to execute the operation after the delay has +passed, before it has expired. During this period, admin and guardians can cancel the operation (see {cancel}). + +If the account has already been granted this role, the execution delay will be updated. This update is not +immediate and follows the delay rules. For example, If a user currently has a delay of 3 hours, and this is +called to reduce that delay to 1 hour, the new delay will take some time to take effect, enforcing that any +operation executed in the 3 hours that follows this update was indeed scheduled before this update. + +Requirements: + +- the caller must be an admin for the role (see {getRoleAdmin}) + +Emits a {RoleGranted} event + +[.contract-item] +[[AccessManager-revokeRole-uint64-address-]] +==== `[.contract-item-name]#++revokeRole++#++(uint64 roleId, address account)++` [.item-kind]#public# + +Remove an account from a role, with immediate effect. If the account does not have the role, this call has +no effect. + +Requirements: + +- the caller must be an admin for the role (see {getRoleAdmin}) + +Emits a {RoleRevoked} event if the account had the role. + +[.contract-item] +[[AccessManager-renounceRole-uint64-address-]] +==== `[.contract-item-name]#++renounceRole++#++(uint64 roleId, address callerConfirmation)++` [.item-kind]#public# + +Renounce role permissions for the calling account, with immediate effect. If the sender is not in +the role, this call has no effect. + +Requirements: + +- the caller must be `callerConfirmation`. + +Emits a {RoleRevoked} event if the account had the role. + +[.contract-item] +[[AccessManager-setRoleAdmin-uint64-uint64-]] +==== `[.contract-item-name]#++setRoleAdmin++#++(uint64 roleId, uint64 admin)++` [.item-kind]#public# + +Change admin role for a given role. + +Requirements: + +- the caller must be a global admin + +Emits a {RoleAdminChanged} event + +[.contract-item] +[[AccessManager-setRoleGuardian-uint64-uint64-]] +==== `[.contract-item-name]#++setRoleGuardian++#++(uint64 roleId, uint64 guardian)++` [.item-kind]#public# + +Change guardian role for a given role. + +Requirements: + +- the caller must be a global admin + +Emits a {RoleGuardianChanged} event + +[.contract-item] +[[AccessManager-setGrantDelay-uint64-uint32-]] +==== `[.contract-item-name]#++setGrantDelay++#++(uint64 roleId, uint32 newDelay)++` [.item-kind]#public# + +Update the delay for granting a `roleId`. + +Requirements: + +- the caller must be a global admin + +Emits a {RoleGrantDelayChanged} event. + +[.contract-item] +[[AccessManager-_grantRole-uint64-address-uint32-uint32-]] +==== `[.contract-item-name]#++_grantRole++#++(uint64 roleId, address account, uint32 grantDelay, uint32 executionDelay) → bool++` [.item-kind]#internal# + +Internal version of {grantRole} without access control. Returns true if the role was newly granted. + +Emits a {RoleGranted} event. + +[.contract-item] +[[AccessManager-_revokeRole-uint64-address-]] +==== `[.contract-item-name]#++_revokeRole++#++(uint64 roleId, address account) → bool++` [.item-kind]#internal# + +Internal version of {revokeRole} without access control. This logic is also used by {renounceRole}. +Returns true if the role was previously granted. + +Emits a {RoleRevoked} event if the account had the role. + +[.contract-item] +[[AccessManager-_setRoleAdmin-uint64-uint64-]] +==== `[.contract-item-name]#++_setRoleAdmin++#++(uint64 roleId, uint64 admin)++` [.item-kind]#internal# + +Internal version of {setRoleAdmin} without access control. + +Emits a {RoleAdminChanged} event + +[.contract-item] +[[AccessManager-_setRoleGuardian-uint64-uint64-]] +==== `[.contract-item-name]#++_setRoleGuardian++#++(uint64 roleId, uint64 guardian)++` [.item-kind]#internal# + +Internal version of {setRoleGuardian} without access control. + +Emits a {RoleGuardianChanged} event + +[.contract-item] +[[AccessManager-_setGrantDelay-uint64-uint32-]] +==== `[.contract-item-name]#++_setGrantDelay++#++(uint64 roleId, uint32 newDelay)++` [.item-kind]#internal# + +Internal version of {setGrantDelay} without access control. + +Emits a {RoleGrantDelayChanged} event + +[.contract-item] +[[AccessManager-setTargetFunctionRole-address-bytes4---uint64-]] +==== `[.contract-item-name]#++setTargetFunctionRole++#++(address target, bytes4[] selectors, uint64 roleId)++` [.item-kind]#public# + +Set the role required to call functions identified by the `selectors` in the `target` contract. + +Requirements: + +- the caller must be a global admin + +Emits a {TargetFunctionRoleUpdated} event per selector. + +[.contract-item] +[[AccessManager-_setTargetFunctionRole-address-bytes4-uint64-]] +==== `[.contract-item-name]#++_setTargetFunctionRole++#++(address target, bytes4 selector, uint64 roleId)++` [.item-kind]#internal# + +Internal version of {setFunctionAllowedRole} without access control. + +Emits a {TargetFunctionRoleUpdated} event + +[.contract-item] +[[AccessManager-setTargetAdminDelay-address-uint32-]] +==== `[.contract-item-name]#++setTargetAdminDelay++#++(address target, uint32 newDelay)++` [.item-kind]#public# + +Set the delay for changing the configuration of a given target contract. + +Requirements: + +- the caller must be a global admin + +Emits a {TargetAdminDelayUpdated} event per selector + +[.contract-item] +[[AccessManager-_setTargetAdminDelay-address-uint32-]] +==== `[.contract-item-name]#++_setTargetAdminDelay++#++(address target, uint32 newDelay)++` [.item-kind]#internal# + +Internal version of {setTargetAdminDelay} without access control. + +Emits a {TargetAdminDelayUpdated} event + +[.contract-item] +[[AccessManager-setTargetClosed-address-bool-]] +==== `[.contract-item-name]#++setTargetClosed++#++(address target, bool closed)++` [.item-kind]#public# + +Set the closed flag for a contract. + +Requirements: + +- the caller must be a global admin + +Emits a {TargetClosed} event. + +[.contract-item] +[[AccessManager-_setTargetClosed-address-bool-]] +==== `[.contract-item-name]#++_setTargetClosed++#++(address target, bool closed)++` [.item-kind]#internal# + +Set the closed flag for a contract. This is an internal setter with no access restrictions. + +Emits a {TargetClosed} event. + +[.contract-item] +[[AccessManager-getSchedule-bytes32-]] +==== `[.contract-item-name]#++getSchedule++#++(bytes32 id) → uint48++` [.item-kind]#public# + +Return the timepoint at which a scheduled operation will be ready for execution. This returns 0 if the +operation is not yet scheduled, has expired, was executed, or was canceled. + +[.contract-item] +[[AccessManager-getNonce-bytes32-]] +==== `[.contract-item-name]#++getNonce++#++(bytes32 id) → uint32++` [.item-kind]#public# + +Return the nonce for the latest scheduled operation with a given id. Returns 0 if the operation has never +been scheduled. + +[.contract-item] +[[AccessManager-schedule-address-bytes-uint48-]] +==== `[.contract-item-name]#++schedule++#++(address target, bytes data, uint48 when) → bytes32 operationId, uint32 nonce++` [.item-kind]#public# + +Schedule a delayed operation for future execution, and return the operation identifier. It is possible to +choose the timestamp at which the operation becomes executable as long as it satisfies the execution delays +required for the caller. The special value zero will automatically set the earliest possible time. + +Returns the `operationId` that was scheduled. Since this value is a hash of the parameters, it can reoccur when +the same parameters are used; if this is relevant, the returned `nonce` can be used to uniquely identify this +scheduled operation from other occurrences of the same `operationId` in invocations of {execute} and {cancel}. + +Emits a {OperationScheduled} event. + +NOTE: It is not possible to concurrently schedule more than one operation with the same `target` and `data`. If +this is necessary, a random byte can be appended to `data` to act as a salt that will be ignored by the target +contract if it is using standard Solidity ABI encoding. + +[.contract-item] +[[AccessManager-execute-address-bytes-]] +==== `[.contract-item-name]#++execute++#++(address target, bytes data) → uint32++` [.item-kind]#public# + +Execute a function that is delay restricted, provided it was properly scheduled beforehand, or the +execution delay is 0. + +Returns the nonce that identifies the previously scheduled operation that is executed, or 0 if the +operation wasn't previously scheduled (if the caller doesn't have an execution delay). + +Emits an {OperationExecuted} event only if the call was scheduled and delayed. + +[.contract-item] +[[AccessManager-consumeScheduledOp-address-bytes-]] +==== `[.contract-item-name]#++consumeScheduledOp++#++(address caller, bytes data)++` [.item-kind]#public# + +Consume a scheduled operation targeting the caller. If such an operation exists, mark it as consumed +(emit an {OperationExecuted} event and clean the state). Otherwise, throw an error. + +This is useful for contract that want to enforce that calls targeting them were scheduled on the manager, +with all the verifications that it implies. + +Emit a {OperationExecuted} event + +[.contract-item] +[[AccessManager-_consumeScheduledOp-bytes32-]] +==== `[.contract-item-name]#++_consumeScheduledOp++#++(bytes32 operationId) → uint32++` [.item-kind]#internal# + +Internal variant of {consumeScheduledOp} that operates on bytes32 operationId. + +Returns the nonce of the scheduled operation that is consumed. + +[.contract-item] +[[AccessManager-cancel-address-address-bytes-]] +==== `[.contract-item-name]#++cancel++#++(address caller, address target, bytes data) → uint32++` [.item-kind]#public# + +Cancel a scheduled (delayed) operation. Returns the nonce that identifies the previously scheduled +operation that is cancelled. + +Requirements: + +- the caller must be the proposer, a guardian of the targeted function, or a global admin + +Emits a {OperationCanceled} event. + +[.contract-item] +[[AccessManager-hashOperation-address-address-bytes-]] +==== `[.contract-item-name]#++hashOperation++#++(address caller, address target, bytes data) → bytes32++` [.item-kind]#public# + +Hashing function for delayed operations + +[.contract-item] +[[AccessManager-updateAuthority-address-address-]] +==== `[.contract-item-name]#++updateAuthority++#++(address target, address newAuthority)++` [.item-kind]#public# + +Change the AccessManager instance used by a contract that correctly uses this instance. + +Requirements: + +- the caller must be a global admin + +:constructor: pass:normal[xref:#AccessManaged-constructor-address-[`++constructor++`]] +:restricted: pass:normal[xref:#AccessManaged-restricted--[`++restricted++`]] +:authority: pass:normal[xref:#AccessManaged-authority--[`++authority++`]] +:setAuthority: pass:normal[xref:#AccessManaged-setAuthority-address-[`++setAuthority++`]] +:isConsumingScheduledOp: pass:normal[xref:#AccessManaged-isConsumingScheduledOp--[`++isConsumingScheduledOp++`]] +:_setAuthority: pass:normal[xref:#AccessManaged-_setAuthority-address-[`++_setAuthority++`]] +:_checkCanCall: pass:normal[xref:#AccessManaged-_checkCanCall-address-bytes-[`++_checkCanCall++`]] + +[.contract] +[[AccessManaged]] +=== `++AccessManaged++` link:https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v5.0.0-rc.0/contracts/access/manager/AccessManaged.sol[{github-icon},role=heading-link] + +[.hljs-theme-light.nopadding] +```solidity +import "@openzeppelin/contracts/access/manager/AccessManaged.sol"; +``` + +This contract module makes available a {restricted} modifier. Functions decorated with this modifier will be +permissioned according to an "authority": a contract like {AccessManager} that follows the {IAuthority} interface, +implementing a policy that allows certain callers to access certain functions. + +IMPORTANT: The `restricted` modifier should never be used on `internal` functions, judiciously used in `public` +functions, and ideally only used in `external` functions. See {restricted}. + +[.contract-index] +.Modifiers +-- +* {xref-AccessManaged-restricted--}[`++restricted()++`] +-- + +[.contract-index] +.Functions +-- +* {xref-AccessManaged-constructor-address-}[`++constructor(initialAuthority)++`] +* {xref-AccessManaged-authority--}[`++authority()++`] +* {xref-AccessManaged-setAuthority-address-}[`++setAuthority(newAuthority)++`] +* {xref-AccessManaged-isConsumingScheduledOp--}[`++isConsumingScheduledOp()++`] +* {xref-AccessManaged-_setAuthority-address-}[`++_setAuthority(newAuthority)++`] +* {xref-AccessManaged-_checkCanCall-address-bytes-}[`++_checkCanCall(caller, data)++`] + +[.contract-subindex-inherited] +.IAccessManaged + +-- + +[.contract-index] +.Events +-- + +[.contract-subindex-inherited] +.IAccessManaged +* {xref-IAccessManaged-AuthorityUpdated-address-}[`++AuthorityUpdated(authority)++`] + +-- + +[.contract-index] +.Errors +-- + +[.contract-subindex-inherited] +.IAccessManaged +* {xref-IAccessManaged-AccessManagedUnauthorized-address-}[`++AccessManagedUnauthorized(caller)++`] +* {xref-IAccessManaged-AccessManagedRequiredDelay-address-uint32-}[`++AccessManagedRequiredDelay(caller, delay)++`] +* {xref-IAccessManaged-AccessManagedInvalidAuthority-address-}[`++AccessManagedInvalidAuthority(authority)++`] + +-- + +[.contract-item] +[[AccessManaged-restricted--]] +==== `[.contract-item-name]#++restricted++#++()++` [.item-kind]#modifier# + +Restricts access to a function as defined by the connected Authority for this contract and the +caller and selector of the function that entered the contract. + +[IMPORTANT] +==== +In general, this modifier should only be used on `external` functions. It is okay to use it on `public` +functions that are used as external entry points and are not called internally. Unless you know what you're +doing, it should never be used on `internal` functions. Failure to follow these rules can have critical security +implications! This is because the permissions are determined by the function that entered the contract, i.e. the +function at the bottom of the call stack, and not the function where the modifier is visible in the source code. +==== + +[NOTE] +==== +Selector collisions are mitigated by scoping permissions per contract, but some edge cases must be considered: + +* If the https://docs.soliditylang.org/en/v0.8.20/contracts.html#receive-ether-function[`receive()`] function +is restricted, any other function with a `0x00000000` selector will share permissions with `receive()`. +* Similarly, if there's no `receive()` function but a `fallback()` instead, the fallback might be called with +empty `calldata`, sharing the `0x00000000` selector permissions as well. +* For any other selector, if the restricted function is set on an upgradeable contract, an upgrade may remove +the restricted function and replace it with a new method whose selector replaces the last one, keeping the +previous permissions. +==== + +[.contract-item] +[[AccessManaged-constructor-address-]] +==== `[.contract-item-name]#++constructor++#++(address initialAuthority)++` [.item-kind]#internal# + +Initializes the contract connected to an initial authority. + +[.contract-item] +[[AccessManaged-authority--]] +==== `[.contract-item-name]#++authority++#++() → address++` [.item-kind]#public# + +Returns the current authority. + +[.contract-item] +[[AccessManaged-setAuthority-address-]] +==== `[.contract-item-name]#++setAuthority++#++(address newAuthority)++` [.item-kind]#public# + +Transfers control to a new authority. The caller must be the current authority. + +[.contract-item] +[[AccessManaged-isConsumingScheduledOp--]] +==== `[.contract-item-name]#++isConsumingScheduledOp++#++() → bytes4++` [.item-kind]#public# + +Returns true only in the context of a delayed restricted call, at the moment that the scheduled operation is +being consumed. Prevents denial of service for delayed restricted calls in the case that the contract performs +attacker controlled calls. + +[.contract-item] +[[AccessManaged-_setAuthority-address-]] +==== `[.contract-item-name]#++_setAuthority++#++(address newAuthority)++` [.item-kind]#internal# + +Transfers control to a new authority. Internal function with no access restriction. Allows bypassing the +permissions set by the current authority. + +[.contract-item] +[[AccessManaged-_checkCanCall-address-bytes-]] +==== `[.contract-item-name]#++_checkCanCall++#++(address caller, bytes data)++` [.item-kind]#internal# + +Reverts if the caller is not allowed to call the function identified by a selector. + diff --git a/docs/modules/api/pages/finance.adoc b/docs/modules/api/pages/finance.adoc new file mode 100644 index 000000000..c2f5f12dd --- /dev/null +++ b/docs/modules/api/pages/finance.adoc @@ -0,0 +1,234 @@ +:github-icon: pass:[] +:VestingWallet: pass:normal[xref:finance.adoc#VestingWallet[`VestingWallet`]] +:Ownable: pass:normal[xref:access.adoc#Ownable[`Ownable`]] +:xref-VestingWallet-constructor-address-uint64-uint64-: xref:finance.adoc#VestingWallet-constructor-address-uint64-uint64- +:xref-VestingWallet-receive--: xref:finance.adoc#VestingWallet-receive-- +:xref-VestingWallet-start--: xref:finance.adoc#VestingWallet-start-- +:xref-VestingWallet-duration--: xref:finance.adoc#VestingWallet-duration-- +:xref-VestingWallet-end--: xref:finance.adoc#VestingWallet-end-- +:xref-VestingWallet-released--: xref:finance.adoc#VestingWallet-released-- +:xref-VestingWallet-released-address-: xref:finance.adoc#VestingWallet-released-address- +:xref-VestingWallet-releasable--: xref:finance.adoc#VestingWallet-releasable-- +:xref-VestingWallet-releasable-address-: xref:finance.adoc#VestingWallet-releasable-address- +:xref-VestingWallet-release--: xref:finance.adoc#VestingWallet-release-- +:xref-VestingWallet-release-address-: xref:finance.adoc#VestingWallet-release-address- +:xref-VestingWallet-vestedAmount-uint64-: xref:finance.adoc#VestingWallet-vestedAmount-uint64- +:xref-VestingWallet-vestedAmount-address-uint64-: xref:finance.adoc#VestingWallet-vestedAmount-address-uint64- +:xref-VestingWallet-_vestingSchedule-uint256-uint64-: xref:finance.adoc#VestingWallet-_vestingSchedule-uint256-uint64- +:xref-Ownable-owner--: xref:access.adoc#Ownable-owner-- +:xref-Ownable-_checkOwner--: xref:access.adoc#Ownable-_checkOwner-- +:xref-Ownable-renounceOwnership--: xref:access.adoc#Ownable-renounceOwnership-- +:xref-Ownable-transferOwnership-address-: xref:access.adoc#Ownable-transferOwnership-address- +:xref-Ownable-_transferOwnership-address-: xref:access.adoc#Ownable-_transferOwnership-address- +:xref-VestingWallet-EtherReleased-uint256-: xref:finance.adoc#VestingWallet-EtherReleased-uint256- +:xref-VestingWallet-ERC20Released-address-uint256-: xref:finance.adoc#VestingWallet-ERC20Released-address-uint256- +:xref-Ownable-OwnershipTransferred-address-address-: xref:access.adoc#Ownable-OwnershipTransferred-address-address- +:xref-Ownable-OwnableUnauthorizedAccount-address-: xref:access.adoc#Ownable-OwnableUnauthorizedAccount-address- +:xref-Ownable-OwnableInvalidOwner-address-: xref:access.adoc#Ownable-OwnableInvalidOwner-address- += Finance + +[.readme-notice] +NOTE: This document is better viewed at https://docs.openzeppelin.com/contracts/api/finance + +This directory includes primitives for financial systems: + +- {VestingWallet} handles the vesting of Ether and ERC20 tokens for a given beneficiary. Custody of multiple tokens can + be given to this contract, which will release the token to the beneficiary following a given, customizable, vesting + schedule. + +== Contracts + +:EtherReleased: pass:normal[xref:#VestingWallet-EtherReleased-uint256-[`++EtherReleased++`]] +:ERC20Released: pass:normal[xref:#VestingWallet-ERC20Released-address-uint256-[`++ERC20Released++`]] +:constructor: pass:normal[xref:#VestingWallet-constructor-address-uint64-uint64-[`++constructor++`]] +:receive: pass:normal[xref:#VestingWallet-receive--[`++receive++`]] +:start: pass:normal[xref:#VestingWallet-start--[`++start++`]] +:duration: pass:normal[xref:#VestingWallet-duration--[`++duration++`]] +:end: pass:normal[xref:#VestingWallet-end--[`++end++`]] +:released: pass:normal[xref:#VestingWallet-released--[`++released++`]] +:released: pass:normal[xref:#VestingWallet-released-address-[`++released++`]] +:releasable: pass:normal[xref:#VestingWallet-releasable--[`++releasable++`]] +:releasable: pass:normal[xref:#VestingWallet-releasable-address-[`++releasable++`]] +:release: pass:normal[xref:#VestingWallet-release--[`++release++`]] +:release: pass:normal[xref:#VestingWallet-release-address-[`++release++`]] +:vestedAmount: pass:normal[xref:#VestingWallet-vestedAmount-uint64-[`++vestedAmount++`]] +:vestedAmount: pass:normal[xref:#VestingWallet-vestedAmount-address-uint64-[`++vestedAmount++`]] +:_vestingSchedule: pass:normal[xref:#VestingWallet-_vestingSchedule-uint256-uint64-[`++_vestingSchedule++`]] + +[.contract] +[[VestingWallet]] +=== `++VestingWallet++` link:https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v5.0.0-rc.0/contracts/finance/VestingWallet.sol[{github-icon},role=heading-link] + +[.hljs-theme-light.nopadding] +```solidity +import "@openzeppelin/contracts/finance/VestingWallet.sol"; +``` + +A vesting wallet is an ownable contract that can receive native currency and ERC20 tokens, and release these +assets to the wallet owner, also referred to as "beneficiary", according to a vesting schedule. + +Any assets transferred to this contract will follow the vesting schedule as if they were locked from the beginning. +Consequently, if the vesting has already started, any amount of tokens sent to this contract will (at least partly) +be immediately releasable. + +By setting the duration to 0, one can configure this contract to behave like an asset timelock that hold tokens for +a beneficiary until a specified time. + +NOTE: Since the wallet is {Ownable}, and ownership can be transferred, it is possible to sell unvested tokens. +Preventing this in a smart contract is difficult, considering that: 1) a beneficiary address could be a +counterfactually deployed contract, 2) there is likely to be a migration path for EOAs to become contracts in the +near future. + +NOTE: When using this contract with any token whose balance is adjusted automatically (i.e. a rebase token), make +sure to account the supply/balance adjustment in the vesting schedule to ensure the vested amount is as intended. + +[.contract-index] +.Functions +-- +* {xref-VestingWallet-constructor-address-uint64-uint64-}[`++constructor(beneficiary, startTimestamp, durationSeconds)++`] +* {xref-VestingWallet-receive--}[`++receive()++`] +* {xref-VestingWallet-start--}[`++start()++`] +* {xref-VestingWallet-duration--}[`++duration()++`] +* {xref-VestingWallet-end--}[`++end()++`] +* {xref-VestingWallet-released--}[`++released()++`] +* {xref-VestingWallet-released-address-}[`++released(token)++`] +* {xref-VestingWallet-releasable--}[`++releasable()++`] +* {xref-VestingWallet-releasable-address-}[`++releasable(token)++`] +* {xref-VestingWallet-release--}[`++release()++`] +* {xref-VestingWallet-release-address-}[`++release(token)++`] +* {xref-VestingWallet-vestedAmount-uint64-}[`++vestedAmount(timestamp)++`] +* {xref-VestingWallet-vestedAmount-address-uint64-}[`++vestedAmount(token, timestamp)++`] +* {xref-VestingWallet-_vestingSchedule-uint256-uint64-}[`++_vestingSchedule(totalAllocation, timestamp)++`] + +[.contract-subindex-inherited] +.Ownable +* {xref-Ownable-owner--}[`++owner()++`] +* {xref-Ownable-_checkOwner--}[`++_checkOwner()++`] +* {xref-Ownable-renounceOwnership--}[`++renounceOwnership()++`] +* {xref-Ownable-transferOwnership-address-}[`++transferOwnership(newOwner)++`] +* {xref-Ownable-_transferOwnership-address-}[`++_transferOwnership(newOwner)++`] + +-- + +[.contract-index] +.Events +-- +* {xref-VestingWallet-EtherReleased-uint256-}[`++EtherReleased(amount)++`] +* {xref-VestingWallet-ERC20Released-address-uint256-}[`++ERC20Released(token, amount)++`] + +[.contract-subindex-inherited] +.Ownable +* {xref-Ownable-OwnershipTransferred-address-address-}[`++OwnershipTransferred(previousOwner, newOwner)++`] + +-- + +[.contract-index] +.Errors +-- + +[.contract-subindex-inherited] +.Ownable +* {xref-Ownable-OwnableUnauthorizedAccount-address-}[`++OwnableUnauthorizedAccount(account)++`] +* {xref-Ownable-OwnableInvalidOwner-address-}[`++OwnableInvalidOwner(owner)++`] + +-- + +[.contract-item] +[[VestingWallet-constructor-address-uint64-uint64-]] +==== `[.contract-item-name]#++constructor++#++(address beneficiary, uint64 startTimestamp, uint64 durationSeconds)++` [.item-kind]#public# + +Sets the sender as the initial owner, the beneficiary as the pending owner, the start timestamp and the +vesting duration of the vesting wallet. + +[.contract-item] +[[VestingWallet-receive--]] +==== `[.contract-item-name]#++receive++#++()++` [.item-kind]#external# + +The contract should be able to receive Eth. + +[.contract-item] +[[VestingWallet-start--]] +==== `[.contract-item-name]#++start++#++() → uint256++` [.item-kind]#public# + +Getter for the start timestamp. + +[.contract-item] +[[VestingWallet-duration--]] +==== `[.contract-item-name]#++duration++#++() → uint256++` [.item-kind]#public# + +Getter for the vesting duration. + +[.contract-item] +[[VestingWallet-end--]] +==== `[.contract-item-name]#++end++#++() → uint256++` [.item-kind]#public# + +Getter for the end timestamp. + +[.contract-item] +[[VestingWallet-released--]] +==== `[.contract-item-name]#++released++#++() → uint256++` [.item-kind]#public# + +Amount of eth already released + +[.contract-item] +[[VestingWallet-released-address-]] +==== `[.contract-item-name]#++released++#++(address token) → uint256++` [.item-kind]#public# + +Amount of token already released + +[.contract-item] +[[VestingWallet-releasable--]] +==== `[.contract-item-name]#++releasable++#++() → uint256++` [.item-kind]#public# + +Getter for the amount of releasable eth. + +[.contract-item] +[[VestingWallet-releasable-address-]] +==== `[.contract-item-name]#++releasable++#++(address token) → uint256++` [.item-kind]#public# + +Getter for the amount of releasable `token` tokens. `token` should be the address of an +IERC20 contract. + +[.contract-item] +[[VestingWallet-release--]] +==== `[.contract-item-name]#++release++#++()++` [.item-kind]#public# + +Release the native token (ether) that have already vested. + +Emits a {EtherReleased} event. + +[.contract-item] +[[VestingWallet-release-address-]] +==== `[.contract-item-name]#++release++#++(address token)++` [.item-kind]#public# + +Release the tokens that have already vested. + +Emits a {ERC20Released} event. + +[.contract-item] +[[VestingWallet-vestedAmount-uint64-]] +==== `[.contract-item-name]#++vestedAmount++#++(uint64 timestamp) → uint256++` [.item-kind]#public# + +Calculates the amount of ether that has already vested. Default implementation is a linear vesting curve. + +[.contract-item] +[[VestingWallet-vestedAmount-address-uint64-]] +==== `[.contract-item-name]#++vestedAmount++#++(address token, uint64 timestamp) → uint256++` [.item-kind]#public# + +Calculates the amount of tokens that has already vested. Default implementation is a linear vesting curve. + +[.contract-item] +[[VestingWallet-_vestingSchedule-uint256-uint64-]] +==== `[.contract-item-name]#++_vestingSchedule++#++(uint256 totalAllocation, uint64 timestamp) → uint256++` [.item-kind]#internal# + +Virtual implementation of the vesting formula. This returns the amount vested, as a function of time, for +an asset given its total historical allocation. + +[.contract-item] +[[VestingWallet-EtherReleased-uint256-]] +==== `[.contract-item-name]#++EtherReleased++#++(uint256 amount)++` [.item-kind]#event# + +[.contract-item] +[[VestingWallet-ERC20Released-address-uint256-]] +==== `[.contract-item-name]#++ERC20Released++#++(address indexed token, uint256 amount)++` [.item-kind]#event# + diff --git a/docs/modules/api/pages/governance.adoc b/docs/modules/api/pages/governance.adoc new file mode 100644 index 000000000..fd3abcac0 --- /dev/null +++ b/docs/modules/api/pages/governance.adoc @@ -0,0 +1,5226 @@ +:github-icon: pass:[] +:Governor: pass:normal[xref:governance.adoc#Governor[`Governor`]] +:GovernorVotes: pass:normal[xref:governance.adoc#GovernorVotes[`GovernorVotes`]] +:ERC20Votes: pass:normal[xref:token/ERC20.adoc#ERC20Votes[`ERC20Votes`]] +:ERC721Votes: pass:normal[xref:token/ERC721.adoc#ERC721Votes[`ERC721Votes`]] +:GovernorVotesQuorumFraction: pass:normal[xref:governance.adoc#GovernorVotesQuorumFraction[`GovernorVotesQuorumFraction`]] +:GovernorCountingSimple: pass:normal[xref:governance.adoc#GovernorCountingSimple[`GovernorCountingSimple`]] +:GovernorTimelockControl: pass:normal[xref:governance.adoc#GovernorTimelockControl[`GovernorTimelockControl`]] +:TimelockController: pass:normal[xref:governance.adoc#TimelockController[`TimelockController`]] +:GovernorTimelockCompound: pass:normal[xref:governance.adoc#GovernorTimelockCompound[`GovernorTimelockCompound`]] +:GovernorStorage: pass:normal[xref:governance.adoc#GovernorStorage[`GovernorStorage`]] +:GovernorSettings: pass:normal[xref:governance.adoc#GovernorSettings[`GovernorSettings`]] +:GovernorPreventLateQuorum: pass:normal[xref:governance.adoc#GovernorPreventLateQuorum[`GovernorPreventLateQuorum`]] +:Governor-_cancel: pass:normal[xref:governance.adoc#Governor-_cancel-address---uint256---bytes---bytes32-[`Governor._cancel`]] +:Governor: pass:normal[xref:governance.adoc#Governor[`Governor`]] +:xref-IGovernor-name--: xref:governance.adoc#IGovernor-name-- +:xref-IGovernor-version--: xref:governance.adoc#IGovernor-version-- +:xref-IGovernor-COUNTING_MODE--: xref:governance.adoc#IGovernor-COUNTING_MODE-- +:xref-IGovernor-hashProposal-address---uint256---bytes---bytes32-: xref:governance.adoc#IGovernor-hashProposal-address---uint256---bytes---bytes32- +:xref-IGovernor-state-uint256-: xref:governance.adoc#IGovernor-state-uint256- +:xref-IGovernor-proposalThreshold--: xref:governance.adoc#IGovernor-proposalThreshold-- +:xref-IGovernor-proposalSnapshot-uint256-: xref:governance.adoc#IGovernor-proposalSnapshot-uint256- +:xref-IGovernor-proposalDeadline-uint256-: xref:governance.adoc#IGovernor-proposalDeadline-uint256- +:xref-IGovernor-proposalProposer-uint256-: xref:governance.adoc#IGovernor-proposalProposer-uint256- +:xref-IGovernor-proposalEta-uint256-: xref:governance.adoc#IGovernor-proposalEta-uint256- +:xref-IGovernor-proposalNeedsQueuing-uint256-: xref:governance.adoc#IGovernor-proposalNeedsQueuing-uint256- +:xref-IGovernor-votingDelay--: xref:governance.adoc#IGovernor-votingDelay-- +:xref-IGovernor-votingPeriod--: xref:governance.adoc#IGovernor-votingPeriod-- +:xref-IGovernor-quorum-uint256-: xref:governance.adoc#IGovernor-quorum-uint256- +:xref-IGovernor-getVotes-address-uint256-: xref:governance.adoc#IGovernor-getVotes-address-uint256- +:xref-IGovernor-getVotesWithParams-address-uint256-bytes-: xref:governance.adoc#IGovernor-getVotesWithParams-address-uint256-bytes- +:xref-IGovernor-hasVoted-uint256-address-: xref:governance.adoc#IGovernor-hasVoted-uint256-address- +:xref-IGovernor-propose-address---uint256---bytes---string-: xref:governance.adoc#IGovernor-propose-address---uint256---bytes---string- +:xref-IGovernor-queue-address---uint256---bytes---bytes32-: xref:governance.adoc#IGovernor-queue-address---uint256---bytes---bytes32- +:xref-IGovernor-execute-address---uint256---bytes---bytes32-: xref:governance.adoc#IGovernor-execute-address---uint256---bytes---bytes32- +:xref-IGovernor-cancel-address---uint256---bytes---bytes32-: xref:governance.adoc#IGovernor-cancel-address---uint256---bytes---bytes32- +:xref-IGovernor-castVote-uint256-uint8-: xref:governance.adoc#IGovernor-castVote-uint256-uint8- +:xref-IGovernor-castVoteWithReason-uint256-uint8-string-: xref:governance.adoc#IGovernor-castVoteWithReason-uint256-uint8-string- +:xref-IGovernor-castVoteWithReasonAndParams-uint256-uint8-string-bytes-: xref:governance.adoc#IGovernor-castVoteWithReasonAndParams-uint256-uint8-string-bytes- +:xref-IGovernor-castVoteBySig-uint256-uint8-address-bytes-: xref:governance.adoc#IGovernor-castVoteBySig-uint256-uint8-address-bytes- +:xref-IGovernor-castVoteWithReasonAndParamsBySig-uint256-uint8-address-string-bytes-bytes-: xref:governance.adoc#IGovernor-castVoteWithReasonAndParamsBySig-uint256-uint8-address-string-bytes-bytes- +:xref-IERC6372-clock--: xref:interfaces.adoc#IERC6372-clock-- +:xref-IERC6372-CLOCK_MODE--: xref:interfaces.adoc#IERC6372-CLOCK_MODE-- +:xref-IERC165-supportsInterface-bytes4-: xref:utils.adoc#IERC165-supportsInterface-bytes4- +:xref-IGovernor-ProposalCreated-uint256-address-address---uint256---string---bytes---uint256-uint256-string-: xref:governance.adoc#IGovernor-ProposalCreated-uint256-address-address---uint256---string---bytes---uint256-uint256-string- +:xref-IGovernor-ProposalQueued-uint256-uint256-: xref:governance.adoc#IGovernor-ProposalQueued-uint256-uint256- +:xref-IGovernor-ProposalExecuted-uint256-: xref:governance.adoc#IGovernor-ProposalExecuted-uint256- +:xref-IGovernor-ProposalCanceled-uint256-: xref:governance.adoc#IGovernor-ProposalCanceled-uint256- +:xref-IGovernor-VoteCast-address-uint256-uint8-uint256-string-: xref:governance.adoc#IGovernor-VoteCast-address-uint256-uint8-uint256-string- +:xref-IGovernor-VoteCastWithParams-address-uint256-uint8-uint256-string-bytes-: xref:governance.adoc#IGovernor-VoteCastWithParams-address-uint256-uint8-uint256-string-bytes- +:xref-IGovernor-GovernorInvalidProposalLength-uint256-uint256-uint256-: xref:governance.adoc#IGovernor-GovernorInvalidProposalLength-uint256-uint256-uint256- +:xref-IGovernor-GovernorAlreadyCastVote-address-: xref:governance.adoc#IGovernor-GovernorAlreadyCastVote-address- +:xref-IGovernor-GovernorDisabledDeposit--: xref:governance.adoc#IGovernor-GovernorDisabledDeposit-- +:xref-IGovernor-GovernorOnlyProposer-address-: xref:governance.adoc#IGovernor-GovernorOnlyProposer-address- +:xref-IGovernor-GovernorOnlyExecutor-address-: xref:governance.adoc#IGovernor-GovernorOnlyExecutor-address- +:xref-IGovernor-GovernorNonexistentProposal-uint256-: xref:governance.adoc#IGovernor-GovernorNonexistentProposal-uint256- +:xref-IGovernor-GovernorUnexpectedProposalState-uint256-enum-IGovernor-ProposalState-bytes32-: xref:governance.adoc#IGovernor-GovernorUnexpectedProposalState-uint256-enum-IGovernor-ProposalState-bytes32- +:xref-IGovernor-GovernorInvalidVotingPeriod-uint256-: xref:governance.adoc#IGovernor-GovernorInvalidVotingPeriod-uint256- +:xref-IGovernor-GovernorInsufficientProposerVotes-address-uint256-uint256-: xref:governance.adoc#IGovernor-GovernorInsufficientProposerVotes-address-uint256-uint256- +:xref-IGovernor-GovernorRestrictedProposer-address-: xref:governance.adoc#IGovernor-GovernorRestrictedProposer-address- +:xref-IGovernor-GovernorInvalidVoteType--: xref:governance.adoc#IGovernor-GovernorInvalidVoteType-- +:xref-IGovernor-GovernorQueueNotImplemented--: xref:governance.adoc#IGovernor-GovernorQueueNotImplemented-- +:xref-IGovernor-GovernorNotQueuedProposal-uint256-: xref:governance.adoc#IGovernor-GovernorNotQueuedProposal-uint256- +:xref-IGovernor-GovernorAlreadyQueuedProposal-uint256-: xref:governance.adoc#IGovernor-GovernorAlreadyQueuedProposal-uint256- +:xref-IGovernor-GovernorInvalidSignature-address-: xref:governance.adoc#IGovernor-GovernorInvalidSignature-address- +:IERC6372-clock: pass:normal[xref:interfaces.adoc#IERC6372-clock--[`IERC6372.clock`]] +:ERC20Votes: pass:normal[xref:token/ERC20.adoc#ERC20Votes[`ERC20Votes`]] +:ERC20Votes: pass:normal[xref:token/ERC20.adoc#ERC20Votes[`ERC20Votes`]] +:IGovernor-votingDelay: pass:normal[xref:governance.adoc#IGovernor-votingDelay--[`IGovernor.votingDelay`]] +:IGovernor-votingPeriod: pass:normal[xref:governance.adoc#IGovernor-votingPeriod--[`IGovernor.votingPeriod`]] +:Governor-_encodeStateBitmap: pass:normal[xref:governance.adoc#Governor-_encodeStateBitmap-enum-IGovernor-ProposalState-[`Governor._encodeStateBitmap`]] +:IERC1271-isValidSignature: pass:normal[xref:interfaces.adoc#IERC1271-isValidSignature-bytes32-bytes-[`IERC1271.isValidSignature`]] +:xref-Governor-onlyGovernance--: xref:governance.adoc#Governor-onlyGovernance-- +:xref-Governor-constructor-string-: xref:governance.adoc#Governor-constructor-string- +:xref-Governor-receive--: xref:governance.adoc#Governor-receive-- +:xref-Governor-supportsInterface-bytes4-: xref:governance.adoc#Governor-supportsInterface-bytes4- +:xref-Governor-name--: xref:governance.adoc#Governor-name-- +:xref-Governor-version--: xref:governance.adoc#Governor-version-- +:xref-Governor-hashProposal-address---uint256---bytes---bytes32-: xref:governance.adoc#Governor-hashProposal-address---uint256---bytes---bytes32- +:xref-Governor-state-uint256-: xref:governance.adoc#Governor-state-uint256- +:xref-Governor-proposalThreshold--: xref:governance.adoc#Governor-proposalThreshold-- +:xref-Governor-proposalSnapshot-uint256-: xref:governance.adoc#Governor-proposalSnapshot-uint256- +:xref-Governor-proposalDeadline-uint256-: xref:governance.adoc#Governor-proposalDeadline-uint256- +:xref-Governor-proposalProposer-uint256-: xref:governance.adoc#Governor-proposalProposer-uint256- +:xref-Governor-proposalEta-uint256-: xref:governance.adoc#Governor-proposalEta-uint256- +:xref-Governor-proposalNeedsQueuing-uint256-: xref:governance.adoc#Governor-proposalNeedsQueuing-uint256- +:xref-Governor-_checkGovernance--: xref:governance.adoc#Governor-_checkGovernance-- +:xref-Governor-_quorumReached-uint256-: xref:governance.adoc#Governor-_quorumReached-uint256- +:xref-Governor-_voteSucceeded-uint256-: xref:governance.adoc#Governor-_voteSucceeded-uint256- +:xref-Governor-_getVotes-address-uint256-bytes-: xref:governance.adoc#Governor-_getVotes-address-uint256-bytes- +:xref-Governor-_countVote-uint256-address-uint8-uint256-bytes-: xref:governance.adoc#Governor-_countVote-uint256-address-uint8-uint256-bytes- +:xref-Governor-_defaultParams--: xref:governance.adoc#Governor-_defaultParams-- +:xref-Governor-propose-address---uint256---bytes---string-: xref:governance.adoc#Governor-propose-address---uint256---bytes---string- +:xref-Governor-_propose-address---uint256---bytes---string-address-: xref:governance.adoc#Governor-_propose-address---uint256---bytes---string-address- +:xref-Governor-queue-address---uint256---bytes---bytes32-: xref:governance.adoc#Governor-queue-address---uint256---bytes---bytes32- +:xref-Governor-_queueOperations-uint256-address---uint256---bytes---bytes32-: xref:governance.adoc#Governor-_queueOperations-uint256-address---uint256---bytes---bytes32- +:xref-Governor-execute-address---uint256---bytes---bytes32-: xref:governance.adoc#Governor-execute-address---uint256---bytes---bytes32- +:xref-Governor-_executeOperations-uint256-address---uint256---bytes---bytes32-: xref:governance.adoc#Governor-_executeOperations-uint256-address---uint256---bytes---bytes32- +:xref-Governor-cancel-address---uint256---bytes---bytes32-: xref:governance.adoc#Governor-cancel-address---uint256---bytes---bytes32- +:xref-Governor-_cancel-address---uint256---bytes---bytes32-: xref:governance.adoc#Governor-_cancel-address---uint256---bytes---bytes32- +:xref-Governor-getVotes-address-uint256-: xref:governance.adoc#Governor-getVotes-address-uint256- +:xref-Governor-getVotesWithParams-address-uint256-bytes-: xref:governance.adoc#Governor-getVotesWithParams-address-uint256-bytes- +:xref-Governor-castVote-uint256-uint8-: xref:governance.adoc#Governor-castVote-uint256-uint8- +:xref-Governor-castVoteWithReason-uint256-uint8-string-: xref:governance.adoc#Governor-castVoteWithReason-uint256-uint8-string- +:xref-Governor-castVoteWithReasonAndParams-uint256-uint8-string-bytes-: xref:governance.adoc#Governor-castVoteWithReasonAndParams-uint256-uint8-string-bytes- +:xref-Governor-castVoteBySig-uint256-uint8-address-bytes-: xref:governance.adoc#Governor-castVoteBySig-uint256-uint8-address-bytes- +:xref-Governor-castVoteWithReasonAndParamsBySig-uint256-uint8-address-string-bytes-bytes-: xref:governance.adoc#Governor-castVoteWithReasonAndParamsBySig-uint256-uint8-address-string-bytes-bytes- +:xref-Governor-_castVote-uint256-address-uint8-string-: xref:governance.adoc#Governor-_castVote-uint256-address-uint8-string- +:xref-Governor-_castVote-uint256-address-uint8-string-bytes-: xref:governance.adoc#Governor-_castVote-uint256-address-uint8-string-bytes- +:xref-Governor-relay-address-uint256-bytes-: xref:governance.adoc#Governor-relay-address-uint256-bytes- +:xref-Governor-_executor--: xref:governance.adoc#Governor-_executor-- +:xref-Governor-onERC721Received-address-address-uint256-bytes-: xref:governance.adoc#Governor-onERC721Received-address-address-uint256-bytes- +:xref-Governor-onERC1155Received-address-address-uint256-uint256-bytes-: xref:governance.adoc#Governor-onERC1155Received-address-address-uint256-uint256-bytes- +:xref-Governor-onERC1155BatchReceived-address-address-uint256---uint256---bytes-: xref:governance.adoc#Governor-onERC1155BatchReceived-address-address-uint256---uint256---bytes- +:xref-Governor-_encodeStateBitmap-enum-IGovernor-ProposalState-: xref:governance.adoc#Governor-_encodeStateBitmap-enum-IGovernor-ProposalState- +:xref-Governor-_isValidDescriptionForProposer-address-string-: xref:governance.adoc#Governor-_isValidDescriptionForProposer-address-string- +:xref-Governor-clock--: xref:governance.adoc#Governor-clock-- +:xref-Governor-CLOCK_MODE--: xref:governance.adoc#Governor-CLOCK_MODE-- +:xref-Governor-votingDelay--: xref:governance.adoc#Governor-votingDelay-- +:xref-Governor-votingPeriod--: xref:governance.adoc#Governor-votingPeriod-- +:xref-Governor-quorum-uint256-: xref:governance.adoc#Governor-quorum-uint256- +:xref-IGovernor-COUNTING_MODE--: xref:governance.adoc#IGovernor-COUNTING_MODE-- +:xref-IGovernor-hasVoted-uint256-address-: xref:governance.adoc#IGovernor-hasVoted-uint256-address- +:xref-Nonces-nonces-address-: xref:utils.adoc#Nonces-nonces-address- +:xref-Nonces-_useNonce-address-: xref:utils.adoc#Nonces-_useNonce-address- +:xref-Nonces-_useCheckedNonce-address-uint256-: xref:utils.adoc#Nonces-_useCheckedNonce-address-uint256- +:xref-EIP712-_domainSeparatorV4--: xref:utils.adoc#EIP712-_domainSeparatorV4-- +:xref-EIP712-_hashTypedDataV4-bytes32-: xref:utils.adoc#EIP712-_hashTypedDataV4-bytes32- +:xref-EIP712-eip712Domain--: xref:utils.adoc#EIP712-eip712Domain-- +:xref-EIP712-_EIP712Name--: xref:utils.adoc#EIP712-_EIP712Name-- +:xref-EIP712-_EIP712Version--: xref:utils.adoc#EIP712-_EIP712Version-- +:xref-IGovernor-ProposalCreated-uint256-address-address---uint256---string---bytes---uint256-uint256-string-: xref:governance.adoc#IGovernor-ProposalCreated-uint256-address-address---uint256---string---bytes---uint256-uint256-string- +:xref-IGovernor-ProposalQueued-uint256-uint256-: xref:governance.adoc#IGovernor-ProposalQueued-uint256-uint256- +:xref-IGovernor-ProposalExecuted-uint256-: xref:governance.adoc#IGovernor-ProposalExecuted-uint256- +:xref-IGovernor-ProposalCanceled-uint256-: xref:governance.adoc#IGovernor-ProposalCanceled-uint256- +:xref-IGovernor-VoteCast-address-uint256-uint8-uint256-string-: xref:governance.adoc#IGovernor-VoteCast-address-uint256-uint8-uint256-string- +:xref-IGovernor-VoteCastWithParams-address-uint256-uint8-uint256-string-bytes-: xref:governance.adoc#IGovernor-VoteCastWithParams-address-uint256-uint8-uint256-string-bytes- +:xref-IERC5267-EIP712DomainChanged--: xref:interfaces.adoc#IERC5267-EIP712DomainChanged-- +:xref-IGovernor-GovernorInvalidProposalLength-uint256-uint256-uint256-: xref:governance.adoc#IGovernor-GovernorInvalidProposalLength-uint256-uint256-uint256- +:xref-IGovernor-GovernorAlreadyCastVote-address-: xref:governance.adoc#IGovernor-GovernorAlreadyCastVote-address- +:xref-IGovernor-GovernorDisabledDeposit--: xref:governance.adoc#IGovernor-GovernorDisabledDeposit-- +:xref-IGovernor-GovernorOnlyProposer-address-: xref:governance.adoc#IGovernor-GovernorOnlyProposer-address- +:xref-IGovernor-GovernorOnlyExecutor-address-: xref:governance.adoc#IGovernor-GovernorOnlyExecutor-address- +:xref-IGovernor-GovernorNonexistentProposal-uint256-: xref:governance.adoc#IGovernor-GovernorNonexistentProposal-uint256- +:xref-IGovernor-GovernorUnexpectedProposalState-uint256-enum-IGovernor-ProposalState-bytes32-: xref:governance.adoc#IGovernor-GovernorUnexpectedProposalState-uint256-enum-IGovernor-ProposalState-bytes32- +:xref-IGovernor-GovernorInvalidVotingPeriod-uint256-: xref:governance.adoc#IGovernor-GovernorInvalidVotingPeriod-uint256- +:xref-IGovernor-GovernorInsufficientProposerVotes-address-uint256-uint256-: xref:governance.adoc#IGovernor-GovernorInsufficientProposerVotes-address-uint256-uint256- +:xref-IGovernor-GovernorRestrictedProposer-address-: xref:governance.adoc#IGovernor-GovernorRestrictedProposer-address- +:xref-IGovernor-GovernorInvalidVoteType--: xref:governance.adoc#IGovernor-GovernorInvalidVoteType-- +:xref-IGovernor-GovernorQueueNotImplemented--: xref:governance.adoc#IGovernor-GovernorQueueNotImplemented-- +:xref-IGovernor-GovernorNotQueuedProposal-uint256-: xref:governance.adoc#IGovernor-GovernorNotQueuedProposal-uint256- +:xref-IGovernor-GovernorAlreadyQueuedProposal-uint256-: xref:governance.adoc#IGovernor-GovernorAlreadyQueuedProposal-uint256- +:xref-IGovernor-GovernorInvalidSignature-address-: xref:governance.adoc#IGovernor-GovernorInvalidSignature-address- +:xref-Nonces-InvalidAccountNonce-address-uint256-: xref:utils.adoc#Nonces-InvalidAccountNonce-address-uint256- +:GovernorSettings: pass:normal[xref:governance.adoc#GovernorSettings[`GovernorSettings`]] +:IERC165-supportsInterface: pass:normal[xref:utils.adoc#IERC165-supportsInterface-bytes4-[`IERC165.supportsInterface`]] +:IGovernor-name: pass:normal[xref:governance.adoc#IGovernor-name--[`IGovernor.name`]] +:IGovernor-version: pass:normal[xref:governance.adoc#IGovernor-version--[`IGovernor.version`]] +:IGovernor-hashProposal: pass:normal[xref:governance.adoc#IGovernor-hashProposal-address---uint256---bytes---bytes32-[`IGovernor.hashProposal`]] +:IGovernor-state: pass:normal[xref:governance.adoc#IGovernor-state-uint256-[`IGovernor.state`]] +:IGovernor-proposalThreshold: pass:normal[xref:governance.adoc#IGovernor-proposalThreshold--[`IGovernor.proposalThreshold`]] +:IGovernor-proposalSnapshot: pass:normal[xref:governance.adoc#IGovernor-proposalSnapshot-uint256-[`IGovernor.proposalSnapshot`]] +:IGovernor-proposalDeadline: pass:normal[xref:governance.adoc#IGovernor-proposalDeadline-uint256-[`IGovernor.proposalDeadline`]] +:IGovernor-proposalProposer: pass:normal[xref:governance.adoc#IGovernor-proposalProposer-uint256-[`IGovernor.proposalProposer`]] +:IGovernor-proposalEta: pass:normal[xref:governance.adoc#IGovernor-proposalEta-uint256-[`IGovernor.proposalEta`]] +:IGovernor-proposalNeedsQueuing: pass:normal[xref:governance.adoc#IGovernor-proposalNeedsQueuing-uint256-[`IGovernor.proposalNeedsQueuing`]] +:IGovernor-propose: pass:normal[xref:governance.adoc#IGovernor-propose-address---uint256---bytes---string-[`IGovernor.propose`]] +:IGovernor-ProposalCreated: pass:normal[xref:governance.adoc#IGovernor-ProposalCreated-uint256-address-address---uint256---string---bytes---uint256-uint256-string-[`IGovernor.ProposalCreated`]] +:IGovernor-queue: pass:normal[xref:governance.adoc#IGovernor-queue-address---uint256---bytes---bytes32-[`IGovernor.queue`]] +:IGovernor-execute: pass:normal[xref:governance.adoc#IGovernor-execute-address---uint256---bytes---bytes32-[`IGovernor.execute`]] +:IGovernor-cancel: pass:normal[xref:governance.adoc#IGovernor-cancel-address---uint256---bytes---bytes32-[`IGovernor.cancel`]] +:IGovernor-ProposalCanceled: pass:normal[xref:governance.adoc#IGovernor-ProposalCanceled-uint256-[`IGovernor.ProposalCanceled`]] +:IGovernor-getVotes: pass:normal[xref:governance.adoc#IGovernor-getVotes-address-uint256-[`IGovernor.getVotes`]] +:IGovernor-getVotesWithParams: pass:normal[xref:governance.adoc#IGovernor-getVotesWithParams-address-uint256-bytes-[`IGovernor.getVotesWithParams`]] +:IGovernor-castVote: pass:normal[xref:governance.adoc#IGovernor-castVote-uint256-uint8-[`IGovernor.castVote`]] +:IGovernor-castVoteWithReason: pass:normal[xref:governance.adoc#IGovernor-castVoteWithReason-uint256-uint8-string-[`IGovernor.castVoteWithReason`]] +:IGovernor-castVoteWithReasonAndParams: pass:normal[xref:governance.adoc#IGovernor-castVoteWithReasonAndParams-uint256-uint8-string-bytes-[`IGovernor.castVoteWithReasonAndParams`]] +:IGovernor-castVoteBySig: pass:normal[xref:governance.adoc#IGovernor-castVoteBySig-uint256-uint8-address-bytes-[`IGovernor.castVoteBySig`]] +:IGovernor-castVoteWithReasonAndParamsBySig: pass:normal[xref:governance.adoc#IGovernor-castVoteWithReasonAndParamsBySig-uint256-uint8-address-string-bytes-bytes-[`IGovernor.castVoteWithReasonAndParamsBySig`]] +:IGovernor-getVotes: pass:normal[xref:governance.adoc#IGovernor-getVotes-address-uint256-[`IGovernor.getVotes`]] +:IGovernor-VoteCast: pass:normal[xref:governance.adoc#IGovernor-VoteCast-address-uint256-uint8-uint256-string-[`IGovernor.VoteCast`]] +:IGovernor-getVotes: pass:normal[xref:governance.adoc#IGovernor-getVotes-address-uint256-[`IGovernor.getVotes`]] +:IGovernor-VoteCast: pass:normal[xref:governance.adoc#IGovernor-VoteCast-address-uint256-uint8-uint256-string-[`IGovernor.VoteCast`]] +:IERC721Receiver-onERC721Received: pass:normal[xref:token/ERC721.adoc#IERC721Receiver-onERC721Received-address-address-uint256-bytes-[`IERC721Receiver.onERC721Received`]] +:IERC1155Receiver-onERC1155Received: pass:normal[xref:token/ERC1155.adoc#IERC1155Receiver-onERC1155Received-address-address-uint256-uint256-bytes-[`IERC1155Receiver.onERC1155Received`]] +:IERC1155Receiver-onERC1155BatchReceived: pass:normal[xref:token/ERC1155.adoc#IERC1155Receiver-onERC1155BatchReceived-address-address-uint256---uint256---bytes-[`IERC1155Receiver.onERC1155BatchReceived`]] +:IERC6372-clock: pass:normal[xref:interfaces.adoc#IERC6372-clock--[`IERC6372.clock`]] +:ERC20Votes: pass:normal[xref:token/ERC20.adoc#ERC20Votes[`ERC20Votes`]] +:Governor: pass:normal[xref:governance.adoc#Governor[`Governor`]] +:xref-GovernorCountingSimple-COUNTING_MODE--: xref:governance.adoc#GovernorCountingSimple-COUNTING_MODE-- +:xref-GovernorCountingSimple-hasVoted-uint256-address-: xref:governance.adoc#GovernorCountingSimple-hasVoted-uint256-address- +:xref-GovernorCountingSimple-proposalVotes-uint256-: xref:governance.adoc#GovernorCountingSimple-proposalVotes-uint256- +:xref-GovernorCountingSimple-_quorumReached-uint256-: xref:governance.adoc#GovernorCountingSimple-_quorumReached-uint256- +:xref-GovernorCountingSimple-_voteSucceeded-uint256-: xref:governance.adoc#GovernorCountingSimple-_voteSucceeded-uint256- +:xref-GovernorCountingSimple-_countVote-uint256-address-uint8-uint256-bytes-: xref:governance.adoc#GovernorCountingSimple-_countVote-uint256-address-uint8-uint256-bytes- +:xref-Governor-receive--: xref:governance.adoc#Governor-receive-- +:xref-Governor-supportsInterface-bytes4-: xref:governance.adoc#Governor-supportsInterface-bytes4- +:xref-Governor-name--: xref:governance.adoc#Governor-name-- +:xref-Governor-version--: xref:governance.adoc#Governor-version-- +:xref-Governor-hashProposal-address---uint256---bytes---bytes32-: xref:governance.adoc#Governor-hashProposal-address---uint256---bytes---bytes32- +:xref-Governor-state-uint256-: xref:governance.adoc#Governor-state-uint256- +:xref-Governor-proposalThreshold--: xref:governance.adoc#Governor-proposalThreshold-- +:xref-Governor-proposalSnapshot-uint256-: xref:governance.adoc#Governor-proposalSnapshot-uint256- +:xref-Governor-proposalDeadline-uint256-: xref:governance.adoc#Governor-proposalDeadline-uint256- +:xref-Governor-proposalProposer-uint256-: xref:governance.adoc#Governor-proposalProposer-uint256- +:xref-Governor-proposalEta-uint256-: xref:governance.adoc#Governor-proposalEta-uint256- +:xref-Governor-proposalNeedsQueuing-uint256-: xref:governance.adoc#Governor-proposalNeedsQueuing-uint256- +:xref-Governor-_checkGovernance--: xref:governance.adoc#Governor-_checkGovernance-- +:xref-Governor-_getVotes-address-uint256-bytes-: xref:governance.adoc#Governor-_getVotes-address-uint256-bytes- +:xref-Governor-_defaultParams--: xref:governance.adoc#Governor-_defaultParams-- +:xref-Governor-propose-address---uint256---bytes---string-: xref:governance.adoc#Governor-propose-address---uint256---bytes---string- +:xref-Governor-_propose-address---uint256---bytes---string-address-: xref:governance.adoc#Governor-_propose-address---uint256---bytes---string-address- +:xref-Governor-queue-address---uint256---bytes---bytes32-: xref:governance.adoc#Governor-queue-address---uint256---bytes---bytes32- +:xref-Governor-_queueOperations-uint256-address---uint256---bytes---bytes32-: xref:governance.adoc#Governor-_queueOperations-uint256-address---uint256---bytes---bytes32- +:xref-Governor-execute-address---uint256---bytes---bytes32-: xref:governance.adoc#Governor-execute-address---uint256---bytes---bytes32- +:xref-Governor-_executeOperations-uint256-address---uint256---bytes---bytes32-: xref:governance.adoc#Governor-_executeOperations-uint256-address---uint256---bytes---bytes32- +:xref-Governor-cancel-address---uint256---bytes---bytes32-: xref:governance.adoc#Governor-cancel-address---uint256---bytes---bytes32- +:xref-Governor-_cancel-address---uint256---bytes---bytes32-: xref:governance.adoc#Governor-_cancel-address---uint256---bytes---bytes32- +:xref-Governor-getVotes-address-uint256-: xref:governance.adoc#Governor-getVotes-address-uint256- +:xref-Governor-getVotesWithParams-address-uint256-bytes-: xref:governance.adoc#Governor-getVotesWithParams-address-uint256-bytes- +:xref-Governor-castVote-uint256-uint8-: xref:governance.adoc#Governor-castVote-uint256-uint8- +:xref-Governor-castVoteWithReason-uint256-uint8-string-: xref:governance.adoc#Governor-castVoteWithReason-uint256-uint8-string- +:xref-Governor-castVoteWithReasonAndParams-uint256-uint8-string-bytes-: xref:governance.adoc#Governor-castVoteWithReasonAndParams-uint256-uint8-string-bytes- +:xref-Governor-castVoteBySig-uint256-uint8-address-bytes-: xref:governance.adoc#Governor-castVoteBySig-uint256-uint8-address-bytes- +:xref-Governor-castVoteWithReasonAndParamsBySig-uint256-uint8-address-string-bytes-bytes-: xref:governance.adoc#Governor-castVoteWithReasonAndParamsBySig-uint256-uint8-address-string-bytes-bytes- +:xref-Governor-_castVote-uint256-address-uint8-string-: xref:governance.adoc#Governor-_castVote-uint256-address-uint8-string- +:xref-Governor-_castVote-uint256-address-uint8-string-bytes-: xref:governance.adoc#Governor-_castVote-uint256-address-uint8-string-bytes- +:xref-Governor-relay-address-uint256-bytes-: xref:governance.adoc#Governor-relay-address-uint256-bytes- +:xref-Governor-_executor--: xref:governance.adoc#Governor-_executor-- +:xref-Governor-onERC721Received-address-address-uint256-bytes-: xref:governance.adoc#Governor-onERC721Received-address-address-uint256-bytes- +:xref-Governor-onERC1155Received-address-address-uint256-uint256-bytes-: xref:governance.adoc#Governor-onERC1155Received-address-address-uint256-uint256-bytes- +:xref-Governor-onERC1155BatchReceived-address-address-uint256---uint256---bytes-: xref:governance.adoc#Governor-onERC1155BatchReceived-address-address-uint256---uint256---bytes- +:xref-Governor-_encodeStateBitmap-enum-IGovernor-ProposalState-: xref:governance.adoc#Governor-_encodeStateBitmap-enum-IGovernor-ProposalState- +:xref-Governor-_isValidDescriptionForProposer-address-string-: xref:governance.adoc#Governor-_isValidDescriptionForProposer-address-string- +:xref-Governor-clock--: xref:governance.adoc#Governor-clock-- +:xref-Governor-CLOCK_MODE--: xref:governance.adoc#Governor-CLOCK_MODE-- +:xref-Governor-votingDelay--: xref:governance.adoc#Governor-votingDelay-- +:xref-Governor-votingPeriod--: xref:governance.adoc#Governor-votingPeriod-- +:xref-Governor-quorum-uint256-: xref:governance.adoc#Governor-quorum-uint256- +:xref-Nonces-nonces-address-: xref:utils.adoc#Nonces-nonces-address- +:xref-Nonces-_useNonce-address-: xref:utils.adoc#Nonces-_useNonce-address- +:xref-Nonces-_useCheckedNonce-address-uint256-: xref:utils.adoc#Nonces-_useCheckedNonce-address-uint256- +:xref-EIP712-_domainSeparatorV4--: xref:utils.adoc#EIP712-_domainSeparatorV4-- +:xref-EIP712-_hashTypedDataV4-bytes32-: xref:utils.adoc#EIP712-_hashTypedDataV4-bytes32- +:xref-EIP712-eip712Domain--: xref:utils.adoc#EIP712-eip712Domain-- +:xref-EIP712-_EIP712Name--: xref:utils.adoc#EIP712-_EIP712Name-- +:xref-EIP712-_EIP712Version--: xref:utils.adoc#EIP712-_EIP712Version-- +:xref-IGovernor-ProposalCreated-uint256-address-address---uint256---string---bytes---uint256-uint256-string-: xref:governance.adoc#IGovernor-ProposalCreated-uint256-address-address---uint256---string---bytes---uint256-uint256-string- +:xref-IGovernor-ProposalQueued-uint256-uint256-: xref:governance.adoc#IGovernor-ProposalQueued-uint256-uint256- +:xref-IGovernor-ProposalExecuted-uint256-: xref:governance.adoc#IGovernor-ProposalExecuted-uint256- +:xref-IGovernor-ProposalCanceled-uint256-: xref:governance.adoc#IGovernor-ProposalCanceled-uint256- +:xref-IGovernor-VoteCast-address-uint256-uint8-uint256-string-: xref:governance.adoc#IGovernor-VoteCast-address-uint256-uint8-uint256-string- +:xref-IGovernor-VoteCastWithParams-address-uint256-uint8-uint256-string-bytes-: xref:governance.adoc#IGovernor-VoteCastWithParams-address-uint256-uint8-uint256-string-bytes- +:xref-IERC5267-EIP712DomainChanged--: xref:interfaces.adoc#IERC5267-EIP712DomainChanged-- +:xref-IGovernor-GovernorInvalidProposalLength-uint256-uint256-uint256-: xref:governance.adoc#IGovernor-GovernorInvalidProposalLength-uint256-uint256-uint256- +:xref-IGovernor-GovernorAlreadyCastVote-address-: xref:governance.adoc#IGovernor-GovernorAlreadyCastVote-address- +:xref-IGovernor-GovernorDisabledDeposit--: xref:governance.adoc#IGovernor-GovernorDisabledDeposit-- +:xref-IGovernor-GovernorOnlyProposer-address-: xref:governance.adoc#IGovernor-GovernorOnlyProposer-address- +:xref-IGovernor-GovernorOnlyExecutor-address-: xref:governance.adoc#IGovernor-GovernorOnlyExecutor-address- +:xref-IGovernor-GovernorNonexistentProposal-uint256-: xref:governance.adoc#IGovernor-GovernorNonexistentProposal-uint256- +:xref-IGovernor-GovernorUnexpectedProposalState-uint256-enum-IGovernor-ProposalState-bytes32-: xref:governance.adoc#IGovernor-GovernorUnexpectedProposalState-uint256-enum-IGovernor-ProposalState-bytes32- +:xref-IGovernor-GovernorInvalidVotingPeriod-uint256-: xref:governance.adoc#IGovernor-GovernorInvalidVotingPeriod-uint256- +:xref-IGovernor-GovernorInsufficientProposerVotes-address-uint256-uint256-: xref:governance.adoc#IGovernor-GovernorInsufficientProposerVotes-address-uint256-uint256- +:xref-IGovernor-GovernorRestrictedProposer-address-: xref:governance.adoc#IGovernor-GovernorRestrictedProposer-address- +:xref-IGovernor-GovernorInvalidVoteType--: xref:governance.adoc#IGovernor-GovernorInvalidVoteType-- +:xref-IGovernor-GovernorQueueNotImplemented--: xref:governance.adoc#IGovernor-GovernorQueueNotImplemented-- +:xref-IGovernor-GovernorNotQueuedProposal-uint256-: xref:governance.adoc#IGovernor-GovernorNotQueuedProposal-uint256- +:xref-IGovernor-GovernorAlreadyQueuedProposal-uint256-: xref:governance.adoc#IGovernor-GovernorAlreadyQueuedProposal-uint256- +:xref-IGovernor-GovernorInvalidSignature-address-: xref:governance.adoc#IGovernor-GovernorInvalidSignature-address- +:xref-Nonces-InvalidAccountNonce-address-uint256-: xref:utils.adoc#Nonces-InvalidAccountNonce-address-uint256- +:IGovernor-COUNTING_MODE: pass:normal[xref:governance.adoc#IGovernor-COUNTING_MODE--[`IGovernor.COUNTING_MODE`]] +:IGovernor-hasVoted: pass:normal[xref:governance.adoc#IGovernor-hasVoted-uint256-address-[`IGovernor.hasVoted`]] +:Governor-_quorumReached: pass:normal[xref:governance.adoc#Governor-_quorumReached-uint256-[`Governor._quorumReached`]] +:Governor-_voteSucceeded: pass:normal[xref:governance.adoc#Governor-_voteSucceeded-uint256-[`Governor._voteSucceeded`]] +:Governor-_countVote: pass:normal[xref:governance.adoc#Governor-_countVote-uint256-address-uint8-uint256-bytes-[`Governor._countVote`]] +:Governor: pass:normal[xref:governance.adoc#Governor[`Governor`]] +:ERC20Votes: pass:normal[xref:token/ERC20.adoc#ERC20Votes[`ERC20Votes`]] +:ERC721Votes: pass:normal[xref:token/ERC721.adoc#ERC721Votes[`ERC721Votes`]] +:xref-GovernorVotes-constructor-contract-IVotes-: xref:governance.adoc#GovernorVotes-constructor-contract-IVotes- +:xref-GovernorVotes-token--: xref:governance.adoc#GovernorVotes-token-- +:xref-GovernorVotes-clock--: xref:governance.adoc#GovernorVotes-clock-- +:xref-GovernorVotes-CLOCK_MODE--: xref:governance.adoc#GovernorVotes-CLOCK_MODE-- +:xref-GovernorVotes-_getVotes-address-uint256-bytes-: xref:governance.adoc#GovernorVotes-_getVotes-address-uint256-bytes- +:xref-Governor-receive--: xref:governance.adoc#Governor-receive-- +:xref-Governor-supportsInterface-bytes4-: xref:governance.adoc#Governor-supportsInterface-bytes4- +:xref-Governor-name--: xref:governance.adoc#Governor-name-- +:xref-Governor-version--: xref:governance.adoc#Governor-version-- +:xref-Governor-hashProposal-address---uint256---bytes---bytes32-: xref:governance.adoc#Governor-hashProposal-address---uint256---bytes---bytes32- +:xref-Governor-state-uint256-: xref:governance.adoc#Governor-state-uint256- +:xref-Governor-proposalThreshold--: xref:governance.adoc#Governor-proposalThreshold-- +:xref-Governor-proposalSnapshot-uint256-: xref:governance.adoc#Governor-proposalSnapshot-uint256- +:xref-Governor-proposalDeadline-uint256-: xref:governance.adoc#Governor-proposalDeadline-uint256- +:xref-Governor-proposalProposer-uint256-: xref:governance.adoc#Governor-proposalProposer-uint256- +:xref-Governor-proposalEta-uint256-: xref:governance.adoc#Governor-proposalEta-uint256- +:xref-Governor-proposalNeedsQueuing-uint256-: xref:governance.adoc#Governor-proposalNeedsQueuing-uint256- +:xref-Governor-_checkGovernance--: xref:governance.adoc#Governor-_checkGovernance-- +:xref-Governor-_quorumReached-uint256-: xref:governance.adoc#Governor-_quorumReached-uint256- +:xref-Governor-_voteSucceeded-uint256-: xref:governance.adoc#Governor-_voteSucceeded-uint256- +:xref-Governor-_countVote-uint256-address-uint8-uint256-bytes-: xref:governance.adoc#Governor-_countVote-uint256-address-uint8-uint256-bytes- +:xref-Governor-_defaultParams--: xref:governance.adoc#Governor-_defaultParams-- +:xref-Governor-propose-address---uint256---bytes---string-: xref:governance.adoc#Governor-propose-address---uint256---bytes---string- +:xref-Governor-_propose-address---uint256---bytes---string-address-: xref:governance.adoc#Governor-_propose-address---uint256---bytes---string-address- +:xref-Governor-queue-address---uint256---bytes---bytes32-: xref:governance.adoc#Governor-queue-address---uint256---bytes---bytes32- +:xref-Governor-_queueOperations-uint256-address---uint256---bytes---bytes32-: xref:governance.adoc#Governor-_queueOperations-uint256-address---uint256---bytes---bytes32- +:xref-Governor-execute-address---uint256---bytes---bytes32-: xref:governance.adoc#Governor-execute-address---uint256---bytes---bytes32- +:xref-Governor-_executeOperations-uint256-address---uint256---bytes---bytes32-: xref:governance.adoc#Governor-_executeOperations-uint256-address---uint256---bytes---bytes32- +:xref-Governor-cancel-address---uint256---bytes---bytes32-: xref:governance.adoc#Governor-cancel-address---uint256---bytes---bytes32- +:xref-Governor-_cancel-address---uint256---bytes---bytes32-: xref:governance.adoc#Governor-_cancel-address---uint256---bytes---bytes32- +:xref-Governor-getVotes-address-uint256-: xref:governance.adoc#Governor-getVotes-address-uint256- +:xref-Governor-getVotesWithParams-address-uint256-bytes-: xref:governance.adoc#Governor-getVotesWithParams-address-uint256-bytes- +:xref-Governor-castVote-uint256-uint8-: xref:governance.adoc#Governor-castVote-uint256-uint8- +:xref-Governor-castVoteWithReason-uint256-uint8-string-: xref:governance.adoc#Governor-castVoteWithReason-uint256-uint8-string- +:xref-Governor-castVoteWithReasonAndParams-uint256-uint8-string-bytes-: xref:governance.adoc#Governor-castVoteWithReasonAndParams-uint256-uint8-string-bytes- +:xref-Governor-castVoteBySig-uint256-uint8-address-bytes-: xref:governance.adoc#Governor-castVoteBySig-uint256-uint8-address-bytes- +:xref-Governor-castVoteWithReasonAndParamsBySig-uint256-uint8-address-string-bytes-bytes-: xref:governance.adoc#Governor-castVoteWithReasonAndParamsBySig-uint256-uint8-address-string-bytes-bytes- +:xref-Governor-_castVote-uint256-address-uint8-string-: xref:governance.adoc#Governor-_castVote-uint256-address-uint8-string- +:xref-Governor-_castVote-uint256-address-uint8-string-bytes-: xref:governance.adoc#Governor-_castVote-uint256-address-uint8-string-bytes- +:xref-Governor-relay-address-uint256-bytes-: xref:governance.adoc#Governor-relay-address-uint256-bytes- +:xref-Governor-_executor--: xref:governance.adoc#Governor-_executor-- +:xref-Governor-onERC721Received-address-address-uint256-bytes-: xref:governance.adoc#Governor-onERC721Received-address-address-uint256-bytes- +:xref-Governor-onERC1155Received-address-address-uint256-uint256-bytes-: xref:governance.adoc#Governor-onERC1155Received-address-address-uint256-uint256-bytes- +:xref-Governor-onERC1155BatchReceived-address-address-uint256---uint256---bytes-: xref:governance.adoc#Governor-onERC1155BatchReceived-address-address-uint256---uint256---bytes- +:xref-Governor-_encodeStateBitmap-enum-IGovernor-ProposalState-: xref:governance.adoc#Governor-_encodeStateBitmap-enum-IGovernor-ProposalState- +:xref-Governor-_isValidDescriptionForProposer-address-string-: xref:governance.adoc#Governor-_isValidDescriptionForProposer-address-string- +:xref-Governor-votingDelay--: xref:governance.adoc#Governor-votingDelay-- +:xref-Governor-votingPeriod--: xref:governance.adoc#Governor-votingPeriod-- +:xref-Governor-quorum-uint256-: xref:governance.adoc#Governor-quorum-uint256- +:xref-IGovernor-COUNTING_MODE--: xref:governance.adoc#IGovernor-COUNTING_MODE-- +:xref-IGovernor-hasVoted-uint256-address-: xref:governance.adoc#IGovernor-hasVoted-uint256-address- +:xref-Nonces-nonces-address-: xref:utils.adoc#Nonces-nonces-address- +:xref-Nonces-_useNonce-address-: xref:utils.adoc#Nonces-_useNonce-address- +:xref-Nonces-_useCheckedNonce-address-uint256-: xref:utils.adoc#Nonces-_useCheckedNonce-address-uint256- +:xref-EIP712-_domainSeparatorV4--: xref:utils.adoc#EIP712-_domainSeparatorV4-- +:xref-EIP712-_hashTypedDataV4-bytes32-: xref:utils.adoc#EIP712-_hashTypedDataV4-bytes32- +:xref-EIP712-eip712Domain--: xref:utils.adoc#EIP712-eip712Domain-- +:xref-EIP712-_EIP712Name--: xref:utils.adoc#EIP712-_EIP712Name-- +:xref-EIP712-_EIP712Version--: xref:utils.adoc#EIP712-_EIP712Version-- +:xref-IGovernor-ProposalCreated-uint256-address-address---uint256---string---bytes---uint256-uint256-string-: xref:governance.adoc#IGovernor-ProposalCreated-uint256-address-address---uint256---string---bytes---uint256-uint256-string- +:xref-IGovernor-ProposalQueued-uint256-uint256-: xref:governance.adoc#IGovernor-ProposalQueued-uint256-uint256- +:xref-IGovernor-ProposalExecuted-uint256-: xref:governance.adoc#IGovernor-ProposalExecuted-uint256- +:xref-IGovernor-ProposalCanceled-uint256-: xref:governance.adoc#IGovernor-ProposalCanceled-uint256- +:xref-IGovernor-VoteCast-address-uint256-uint8-uint256-string-: xref:governance.adoc#IGovernor-VoteCast-address-uint256-uint8-uint256-string- +:xref-IGovernor-VoteCastWithParams-address-uint256-uint8-uint256-string-bytes-: xref:governance.adoc#IGovernor-VoteCastWithParams-address-uint256-uint8-uint256-string-bytes- +:xref-IERC5267-EIP712DomainChanged--: xref:interfaces.adoc#IERC5267-EIP712DomainChanged-- +:xref-IGovernor-GovernorInvalidProposalLength-uint256-uint256-uint256-: xref:governance.adoc#IGovernor-GovernorInvalidProposalLength-uint256-uint256-uint256- +:xref-IGovernor-GovernorAlreadyCastVote-address-: xref:governance.adoc#IGovernor-GovernorAlreadyCastVote-address- +:xref-IGovernor-GovernorDisabledDeposit--: xref:governance.adoc#IGovernor-GovernorDisabledDeposit-- +:xref-IGovernor-GovernorOnlyProposer-address-: xref:governance.adoc#IGovernor-GovernorOnlyProposer-address- +:xref-IGovernor-GovernorOnlyExecutor-address-: xref:governance.adoc#IGovernor-GovernorOnlyExecutor-address- +:xref-IGovernor-GovernorNonexistentProposal-uint256-: xref:governance.adoc#IGovernor-GovernorNonexistentProposal-uint256- +:xref-IGovernor-GovernorUnexpectedProposalState-uint256-enum-IGovernor-ProposalState-bytes32-: xref:governance.adoc#IGovernor-GovernorUnexpectedProposalState-uint256-enum-IGovernor-ProposalState-bytes32- +:xref-IGovernor-GovernorInvalidVotingPeriod-uint256-: xref:governance.adoc#IGovernor-GovernorInvalidVotingPeriod-uint256- +:xref-IGovernor-GovernorInsufficientProposerVotes-address-uint256-uint256-: xref:governance.adoc#IGovernor-GovernorInsufficientProposerVotes-address-uint256-uint256- +:xref-IGovernor-GovernorRestrictedProposer-address-: xref:governance.adoc#IGovernor-GovernorRestrictedProposer-address- +:xref-IGovernor-GovernorInvalidVoteType--: xref:governance.adoc#IGovernor-GovernorInvalidVoteType-- +:xref-IGovernor-GovernorQueueNotImplemented--: xref:governance.adoc#IGovernor-GovernorQueueNotImplemented-- +:xref-IGovernor-GovernorNotQueuedProposal-uint256-: xref:governance.adoc#IGovernor-GovernorNotQueuedProposal-uint256- +:xref-IGovernor-GovernorAlreadyQueuedProposal-uint256-: xref:governance.adoc#IGovernor-GovernorAlreadyQueuedProposal-uint256- +:xref-IGovernor-GovernorInvalidSignature-address-: xref:governance.adoc#IGovernor-GovernorInvalidSignature-address- +:xref-Nonces-InvalidAccountNonce-address-uint256-: xref:utils.adoc#Nonces-InvalidAccountNonce-address-uint256- +:Governor: pass:normal[xref:governance.adoc#Governor[`Governor`]] +:ERC20Votes: pass:normal[xref:token/ERC20.adoc#ERC20Votes[`ERC20Votes`]] +:xref-GovernorVotesQuorumFraction-constructor-uint256-: xref:governance.adoc#GovernorVotesQuorumFraction-constructor-uint256- +:xref-GovernorVotesQuorumFraction-quorumNumerator--: xref:governance.adoc#GovernorVotesQuorumFraction-quorumNumerator-- +:xref-GovernorVotesQuorumFraction-quorumNumerator-uint256-: xref:governance.adoc#GovernorVotesQuorumFraction-quorumNumerator-uint256- +:xref-GovernorVotesQuorumFraction-quorumDenominator--: xref:governance.adoc#GovernorVotesQuorumFraction-quorumDenominator-- +:xref-GovernorVotesQuorumFraction-quorum-uint256-: xref:governance.adoc#GovernorVotesQuorumFraction-quorum-uint256- +:xref-GovernorVotesQuorumFraction-updateQuorumNumerator-uint256-: xref:governance.adoc#GovernorVotesQuorumFraction-updateQuorumNumerator-uint256- +:xref-GovernorVotesQuorumFraction-_updateQuorumNumerator-uint256-: xref:governance.adoc#GovernorVotesQuorumFraction-_updateQuorumNumerator-uint256- +:xref-GovernorVotes-token--: xref:governance.adoc#GovernorVotes-token-- +:xref-GovernorVotes-clock--: xref:governance.adoc#GovernorVotes-clock-- +:xref-GovernorVotes-CLOCK_MODE--: xref:governance.adoc#GovernorVotes-CLOCK_MODE-- +:xref-GovernorVotes-_getVotes-address-uint256-bytes-: xref:governance.adoc#GovernorVotes-_getVotes-address-uint256-bytes- +:xref-Governor-receive--: xref:governance.adoc#Governor-receive-- +:xref-Governor-supportsInterface-bytes4-: xref:governance.adoc#Governor-supportsInterface-bytes4- +:xref-Governor-name--: xref:governance.adoc#Governor-name-- +:xref-Governor-version--: xref:governance.adoc#Governor-version-- +:xref-Governor-hashProposal-address---uint256---bytes---bytes32-: xref:governance.adoc#Governor-hashProposal-address---uint256---bytes---bytes32- +:xref-Governor-state-uint256-: xref:governance.adoc#Governor-state-uint256- +:xref-Governor-proposalThreshold--: xref:governance.adoc#Governor-proposalThreshold-- +:xref-Governor-proposalSnapshot-uint256-: xref:governance.adoc#Governor-proposalSnapshot-uint256- +:xref-Governor-proposalDeadline-uint256-: xref:governance.adoc#Governor-proposalDeadline-uint256- +:xref-Governor-proposalProposer-uint256-: xref:governance.adoc#Governor-proposalProposer-uint256- +:xref-Governor-proposalEta-uint256-: xref:governance.adoc#Governor-proposalEta-uint256- +:xref-Governor-proposalNeedsQueuing-uint256-: xref:governance.adoc#Governor-proposalNeedsQueuing-uint256- +:xref-Governor-_checkGovernance--: xref:governance.adoc#Governor-_checkGovernance-- +:xref-Governor-_quorumReached-uint256-: xref:governance.adoc#Governor-_quorumReached-uint256- +:xref-Governor-_voteSucceeded-uint256-: xref:governance.adoc#Governor-_voteSucceeded-uint256- +:xref-Governor-_countVote-uint256-address-uint8-uint256-bytes-: xref:governance.adoc#Governor-_countVote-uint256-address-uint8-uint256-bytes- +:xref-Governor-_defaultParams--: xref:governance.adoc#Governor-_defaultParams-- +:xref-Governor-propose-address---uint256---bytes---string-: xref:governance.adoc#Governor-propose-address---uint256---bytes---string- +:xref-Governor-_propose-address---uint256---bytes---string-address-: xref:governance.adoc#Governor-_propose-address---uint256---bytes---string-address- +:xref-Governor-queue-address---uint256---bytes---bytes32-: xref:governance.adoc#Governor-queue-address---uint256---bytes---bytes32- +:xref-Governor-_queueOperations-uint256-address---uint256---bytes---bytes32-: xref:governance.adoc#Governor-_queueOperations-uint256-address---uint256---bytes---bytes32- +:xref-Governor-execute-address---uint256---bytes---bytes32-: xref:governance.adoc#Governor-execute-address---uint256---bytes---bytes32- +:xref-Governor-_executeOperations-uint256-address---uint256---bytes---bytes32-: xref:governance.adoc#Governor-_executeOperations-uint256-address---uint256---bytes---bytes32- +:xref-Governor-cancel-address---uint256---bytes---bytes32-: xref:governance.adoc#Governor-cancel-address---uint256---bytes---bytes32- +:xref-Governor-_cancel-address---uint256---bytes---bytes32-: xref:governance.adoc#Governor-_cancel-address---uint256---bytes---bytes32- +:xref-Governor-getVotes-address-uint256-: xref:governance.adoc#Governor-getVotes-address-uint256- +:xref-Governor-getVotesWithParams-address-uint256-bytes-: xref:governance.adoc#Governor-getVotesWithParams-address-uint256-bytes- +:xref-Governor-castVote-uint256-uint8-: xref:governance.adoc#Governor-castVote-uint256-uint8- +:xref-Governor-castVoteWithReason-uint256-uint8-string-: xref:governance.adoc#Governor-castVoteWithReason-uint256-uint8-string- +:xref-Governor-castVoteWithReasonAndParams-uint256-uint8-string-bytes-: xref:governance.adoc#Governor-castVoteWithReasonAndParams-uint256-uint8-string-bytes- +:xref-Governor-castVoteBySig-uint256-uint8-address-bytes-: xref:governance.adoc#Governor-castVoteBySig-uint256-uint8-address-bytes- +:xref-Governor-castVoteWithReasonAndParamsBySig-uint256-uint8-address-string-bytes-bytes-: xref:governance.adoc#Governor-castVoteWithReasonAndParamsBySig-uint256-uint8-address-string-bytes-bytes- +:xref-Governor-_castVote-uint256-address-uint8-string-: xref:governance.adoc#Governor-_castVote-uint256-address-uint8-string- +:xref-Governor-_castVote-uint256-address-uint8-string-bytes-: xref:governance.adoc#Governor-_castVote-uint256-address-uint8-string-bytes- +:xref-Governor-relay-address-uint256-bytes-: xref:governance.adoc#Governor-relay-address-uint256-bytes- +:xref-Governor-_executor--: xref:governance.adoc#Governor-_executor-- +:xref-Governor-onERC721Received-address-address-uint256-bytes-: xref:governance.adoc#Governor-onERC721Received-address-address-uint256-bytes- +:xref-Governor-onERC1155Received-address-address-uint256-uint256-bytes-: xref:governance.adoc#Governor-onERC1155Received-address-address-uint256-uint256-bytes- +:xref-Governor-onERC1155BatchReceived-address-address-uint256---uint256---bytes-: xref:governance.adoc#Governor-onERC1155BatchReceived-address-address-uint256---uint256---bytes- +:xref-Governor-_encodeStateBitmap-enum-IGovernor-ProposalState-: xref:governance.adoc#Governor-_encodeStateBitmap-enum-IGovernor-ProposalState- +:xref-Governor-_isValidDescriptionForProposer-address-string-: xref:governance.adoc#Governor-_isValidDescriptionForProposer-address-string- +:xref-Governor-votingDelay--: xref:governance.adoc#Governor-votingDelay-- +:xref-Governor-votingPeriod--: xref:governance.adoc#Governor-votingPeriod-- +:xref-IGovernor-COUNTING_MODE--: xref:governance.adoc#IGovernor-COUNTING_MODE-- +:xref-IGovernor-hasVoted-uint256-address-: xref:governance.adoc#IGovernor-hasVoted-uint256-address- +:xref-Nonces-nonces-address-: xref:utils.adoc#Nonces-nonces-address- +:xref-Nonces-_useNonce-address-: xref:utils.adoc#Nonces-_useNonce-address- +:xref-Nonces-_useCheckedNonce-address-uint256-: xref:utils.adoc#Nonces-_useCheckedNonce-address-uint256- +:xref-EIP712-_domainSeparatorV4--: xref:utils.adoc#EIP712-_domainSeparatorV4-- +:xref-EIP712-_hashTypedDataV4-bytes32-: xref:utils.adoc#EIP712-_hashTypedDataV4-bytes32- +:xref-EIP712-eip712Domain--: xref:utils.adoc#EIP712-eip712Domain-- +:xref-EIP712-_EIP712Name--: xref:utils.adoc#EIP712-_EIP712Name-- +:xref-EIP712-_EIP712Version--: xref:utils.adoc#EIP712-_EIP712Version-- +:xref-GovernorVotesQuorumFraction-QuorumNumeratorUpdated-uint256-uint256-: xref:governance.adoc#GovernorVotesQuorumFraction-QuorumNumeratorUpdated-uint256-uint256- +:xref-IGovernor-ProposalCreated-uint256-address-address---uint256---string---bytes---uint256-uint256-string-: xref:governance.adoc#IGovernor-ProposalCreated-uint256-address-address---uint256---string---bytes---uint256-uint256-string- +:xref-IGovernor-ProposalQueued-uint256-uint256-: xref:governance.adoc#IGovernor-ProposalQueued-uint256-uint256- +:xref-IGovernor-ProposalExecuted-uint256-: xref:governance.adoc#IGovernor-ProposalExecuted-uint256- +:xref-IGovernor-ProposalCanceled-uint256-: xref:governance.adoc#IGovernor-ProposalCanceled-uint256- +:xref-IGovernor-VoteCast-address-uint256-uint8-uint256-string-: xref:governance.adoc#IGovernor-VoteCast-address-uint256-uint8-uint256-string- +:xref-IGovernor-VoteCastWithParams-address-uint256-uint8-uint256-string-bytes-: xref:governance.adoc#IGovernor-VoteCastWithParams-address-uint256-uint8-uint256-string-bytes- +:xref-IERC5267-EIP712DomainChanged--: xref:interfaces.adoc#IERC5267-EIP712DomainChanged-- +:xref-GovernorVotesQuorumFraction-GovernorInvalidQuorumFraction-uint256-uint256-: xref:governance.adoc#GovernorVotesQuorumFraction-GovernorInvalidQuorumFraction-uint256-uint256- +:xref-IGovernor-GovernorInvalidProposalLength-uint256-uint256-uint256-: xref:governance.adoc#IGovernor-GovernorInvalidProposalLength-uint256-uint256-uint256- +:xref-IGovernor-GovernorAlreadyCastVote-address-: xref:governance.adoc#IGovernor-GovernorAlreadyCastVote-address- +:xref-IGovernor-GovernorDisabledDeposit--: xref:governance.adoc#IGovernor-GovernorDisabledDeposit-- +:xref-IGovernor-GovernorOnlyProposer-address-: xref:governance.adoc#IGovernor-GovernorOnlyProposer-address- +:xref-IGovernor-GovernorOnlyExecutor-address-: xref:governance.adoc#IGovernor-GovernorOnlyExecutor-address- +:xref-IGovernor-GovernorNonexistentProposal-uint256-: xref:governance.adoc#IGovernor-GovernorNonexistentProposal-uint256- +:xref-IGovernor-GovernorUnexpectedProposalState-uint256-enum-IGovernor-ProposalState-bytes32-: xref:governance.adoc#IGovernor-GovernorUnexpectedProposalState-uint256-enum-IGovernor-ProposalState-bytes32- +:xref-IGovernor-GovernorInvalidVotingPeriod-uint256-: xref:governance.adoc#IGovernor-GovernorInvalidVotingPeriod-uint256- +:xref-IGovernor-GovernorInsufficientProposerVotes-address-uint256-uint256-: xref:governance.adoc#IGovernor-GovernorInsufficientProposerVotes-address-uint256-uint256- +:xref-IGovernor-GovernorRestrictedProposer-address-: xref:governance.adoc#IGovernor-GovernorRestrictedProposer-address- +:xref-IGovernor-GovernorInvalidVoteType--: xref:governance.adoc#IGovernor-GovernorInvalidVoteType-- +:xref-IGovernor-GovernorQueueNotImplemented--: xref:governance.adoc#IGovernor-GovernorQueueNotImplemented-- +:xref-IGovernor-GovernorNotQueuedProposal-uint256-: xref:governance.adoc#IGovernor-GovernorNotQueuedProposal-uint256- +:xref-IGovernor-GovernorAlreadyQueuedProposal-uint256-: xref:governance.adoc#IGovernor-GovernorAlreadyQueuedProposal-uint256- +:xref-IGovernor-GovernorInvalidSignature-address-: xref:governance.adoc#IGovernor-GovernorInvalidSignature-address- +:xref-Nonces-InvalidAccountNonce-address-uint256-: xref:utils.adoc#Nonces-InvalidAccountNonce-address-uint256- +:Governor: pass:normal[xref:governance.adoc#Governor[`Governor`]] +:TimelockController: pass:normal[xref:governance.adoc#TimelockController[`TimelockController`]] +:TimelockController: pass:normal[xref:governance.adoc#TimelockController[`TimelockController`]] +:Governor: pass:normal[xref:governance.adoc#Governor[`Governor`]] +:Governor: pass:normal[xref:governance.adoc#Governor[`Governor`]] +:TimelockController: pass:normal[xref:governance.adoc#TimelockController[`TimelockController`]] +:Governor: pass:normal[xref:governance.adoc#Governor[`Governor`]] +:TimelockController: pass:normal[xref:governance.adoc#TimelockController[`TimelockController`]] +:Governor: pass:normal[xref:governance.adoc#Governor[`Governor`]] +:Governor-relay: pass:normal[xref:governance.adoc#Governor-relay-address-uint256-bytes-[`Governor.relay`]] +:AccessManager-schedule: pass:normal[xref:access.adoc#AccessManager-schedule-address-bytes-uint48-[`AccessManager.schedule`]] +:xref-GovernorTimelockControl-constructor-contract-TimelockController-: xref:governance.adoc#GovernorTimelockControl-constructor-contract-TimelockController- +:xref-GovernorTimelockControl-state-uint256-: xref:governance.adoc#GovernorTimelockControl-state-uint256- +:xref-GovernorTimelockControl-timelock--: xref:governance.adoc#GovernorTimelockControl-timelock-- +:xref-GovernorTimelockControl-proposalNeedsQueuing-uint256-: xref:governance.adoc#GovernorTimelockControl-proposalNeedsQueuing-uint256- +:xref-GovernorTimelockControl-_queueOperations-uint256-address---uint256---bytes---bytes32-: xref:governance.adoc#GovernorTimelockControl-_queueOperations-uint256-address---uint256---bytes---bytes32- +:xref-GovernorTimelockControl-_executeOperations-uint256-address---uint256---bytes---bytes32-: xref:governance.adoc#GovernorTimelockControl-_executeOperations-uint256-address---uint256---bytes---bytes32- +:xref-GovernorTimelockControl-_cancel-address---uint256---bytes---bytes32-: xref:governance.adoc#GovernorTimelockControl-_cancel-address---uint256---bytes---bytes32- +:xref-GovernorTimelockControl-_executor--: xref:governance.adoc#GovernorTimelockControl-_executor-- +:xref-GovernorTimelockControl-updateTimelock-contract-TimelockController-: xref:governance.adoc#GovernorTimelockControl-updateTimelock-contract-TimelockController- +:xref-Governor-receive--: xref:governance.adoc#Governor-receive-- +:xref-Governor-supportsInterface-bytes4-: xref:governance.adoc#Governor-supportsInterface-bytes4- +:xref-Governor-name--: xref:governance.adoc#Governor-name-- +:xref-Governor-version--: xref:governance.adoc#Governor-version-- +:xref-Governor-hashProposal-address---uint256---bytes---bytes32-: xref:governance.adoc#Governor-hashProposal-address---uint256---bytes---bytes32- +:xref-Governor-proposalThreshold--: xref:governance.adoc#Governor-proposalThreshold-- +:xref-Governor-proposalSnapshot-uint256-: xref:governance.adoc#Governor-proposalSnapshot-uint256- +:xref-Governor-proposalDeadline-uint256-: xref:governance.adoc#Governor-proposalDeadline-uint256- +:xref-Governor-proposalProposer-uint256-: xref:governance.adoc#Governor-proposalProposer-uint256- +:xref-Governor-proposalEta-uint256-: xref:governance.adoc#Governor-proposalEta-uint256- +:xref-Governor-_checkGovernance--: xref:governance.adoc#Governor-_checkGovernance-- +:xref-Governor-_quorumReached-uint256-: xref:governance.adoc#Governor-_quorumReached-uint256- +:xref-Governor-_voteSucceeded-uint256-: xref:governance.adoc#Governor-_voteSucceeded-uint256- +:xref-Governor-_getVotes-address-uint256-bytes-: xref:governance.adoc#Governor-_getVotes-address-uint256-bytes- +:xref-Governor-_countVote-uint256-address-uint8-uint256-bytes-: xref:governance.adoc#Governor-_countVote-uint256-address-uint8-uint256-bytes- +:xref-Governor-_defaultParams--: xref:governance.adoc#Governor-_defaultParams-- +:xref-Governor-propose-address---uint256---bytes---string-: xref:governance.adoc#Governor-propose-address---uint256---bytes---string- +:xref-Governor-_propose-address---uint256---bytes---string-address-: xref:governance.adoc#Governor-_propose-address---uint256---bytes---string-address- +:xref-Governor-queue-address---uint256---bytes---bytes32-: xref:governance.adoc#Governor-queue-address---uint256---bytes---bytes32- +:xref-Governor-execute-address---uint256---bytes---bytes32-: xref:governance.adoc#Governor-execute-address---uint256---bytes---bytes32- +:xref-Governor-cancel-address---uint256---bytes---bytes32-: xref:governance.adoc#Governor-cancel-address---uint256---bytes---bytes32- +:xref-Governor-getVotes-address-uint256-: xref:governance.adoc#Governor-getVotes-address-uint256- +:xref-Governor-getVotesWithParams-address-uint256-bytes-: xref:governance.adoc#Governor-getVotesWithParams-address-uint256-bytes- +:xref-Governor-castVote-uint256-uint8-: xref:governance.adoc#Governor-castVote-uint256-uint8- +:xref-Governor-castVoteWithReason-uint256-uint8-string-: xref:governance.adoc#Governor-castVoteWithReason-uint256-uint8-string- +:xref-Governor-castVoteWithReasonAndParams-uint256-uint8-string-bytes-: xref:governance.adoc#Governor-castVoteWithReasonAndParams-uint256-uint8-string-bytes- +:xref-Governor-castVoteBySig-uint256-uint8-address-bytes-: xref:governance.adoc#Governor-castVoteBySig-uint256-uint8-address-bytes- +:xref-Governor-castVoteWithReasonAndParamsBySig-uint256-uint8-address-string-bytes-bytes-: xref:governance.adoc#Governor-castVoteWithReasonAndParamsBySig-uint256-uint8-address-string-bytes-bytes- +:xref-Governor-_castVote-uint256-address-uint8-string-: xref:governance.adoc#Governor-_castVote-uint256-address-uint8-string- +:xref-Governor-_castVote-uint256-address-uint8-string-bytes-: xref:governance.adoc#Governor-_castVote-uint256-address-uint8-string-bytes- +:xref-Governor-relay-address-uint256-bytes-: xref:governance.adoc#Governor-relay-address-uint256-bytes- +:xref-Governor-onERC721Received-address-address-uint256-bytes-: xref:governance.adoc#Governor-onERC721Received-address-address-uint256-bytes- +:xref-Governor-onERC1155Received-address-address-uint256-uint256-bytes-: xref:governance.adoc#Governor-onERC1155Received-address-address-uint256-uint256-bytes- +:xref-Governor-onERC1155BatchReceived-address-address-uint256---uint256---bytes-: xref:governance.adoc#Governor-onERC1155BatchReceived-address-address-uint256---uint256---bytes- +:xref-Governor-_encodeStateBitmap-enum-IGovernor-ProposalState-: xref:governance.adoc#Governor-_encodeStateBitmap-enum-IGovernor-ProposalState- +:xref-Governor-_isValidDescriptionForProposer-address-string-: xref:governance.adoc#Governor-_isValidDescriptionForProposer-address-string- +:xref-Governor-clock--: xref:governance.adoc#Governor-clock-- +:xref-Governor-CLOCK_MODE--: xref:governance.adoc#Governor-CLOCK_MODE-- +:xref-Governor-votingDelay--: xref:governance.adoc#Governor-votingDelay-- +:xref-Governor-votingPeriod--: xref:governance.adoc#Governor-votingPeriod-- +:xref-Governor-quorum-uint256-: xref:governance.adoc#Governor-quorum-uint256- +:xref-IGovernor-COUNTING_MODE--: xref:governance.adoc#IGovernor-COUNTING_MODE-- +:xref-IGovernor-hasVoted-uint256-address-: xref:governance.adoc#IGovernor-hasVoted-uint256-address- +:xref-Nonces-nonces-address-: xref:utils.adoc#Nonces-nonces-address- +:xref-Nonces-_useNonce-address-: xref:utils.adoc#Nonces-_useNonce-address- +:xref-Nonces-_useCheckedNonce-address-uint256-: xref:utils.adoc#Nonces-_useCheckedNonce-address-uint256- +:xref-EIP712-_domainSeparatorV4--: xref:utils.adoc#EIP712-_domainSeparatorV4-- +:xref-EIP712-_hashTypedDataV4-bytes32-: xref:utils.adoc#EIP712-_hashTypedDataV4-bytes32- +:xref-EIP712-eip712Domain--: xref:utils.adoc#EIP712-eip712Domain-- +:xref-EIP712-_EIP712Name--: xref:utils.adoc#EIP712-_EIP712Name-- +:xref-EIP712-_EIP712Version--: xref:utils.adoc#EIP712-_EIP712Version-- +:xref-GovernorTimelockControl-TimelockChange-address-address-: xref:governance.adoc#GovernorTimelockControl-TimelockChange-address-address- +:xref-IGovernor-ProposalCreated-uint256-address-address---uint256---string---bytes---uint256-uint256-string-: xref:governance.adoc#IGovernor-ProposalCreated-uint256-address-address---uint256---string---bytes---uint256-uint256-string- +:xref-IGovernor-ProposalQueued-uint256-uint256-: xref:governance.adoc#IGovernor-ProposalQueued-uint256-uint256- +:xref-IGovernor-ProposalExecuted-uint256-: xref:governance.adoc#IGovernor-ProposalExecuted-uint256- +:xref-IGovernor-ProposalCanceled-uint256-: xref:governance.adoc#IGovernor-ProposalCanceled-uint256- +:xref-IGovernor-VoteCast-address-uint256-uint8-uint256-string-: xref:governance.adoc#IGovernor-VoteCast-address-uint256-uint8-uint256-string- +:xref-IGovernor-VoteCastWithParams-address-uint256-uint8-uint256-string-bytes-: xref:governance.adoc#IGovernor-VoteCastWithParams-address-uint256-uint8-uint256-string-bytes- +:xref-IERC5267-EIP712DomainChanged--: xref:interfaces.adoc#IERC5267-EIP712DomainChanged-- +:xref-IGovernor-GovernorInvalidProposalLength-uint256-uint256-uint256-: xref:governance.adoc#IGovernor-GovernorInvalidProposalLength-uint256-uint256-uint256- +:xref-IGovernor-GovernorAlreadyCastVote-address-: xref:governance.adoc#IGovernor-GovernorAlreadyCastVote-address- +:xref-IGovernor-GovernorDisabledDeposit--: xref:governance.adoc#IGovernor-GovernorDisabledDeposit-- +:xref-IGovernor-GovernorOnlyProposer-address-: xref:governance.adoc#IGovernor-GovernorOnlyProposer-address- +:xref-IGovernor-GovernorOnlyExecutor-address-: xref:governance.adoc#IGovernor-GovernorOnlyExecutor-address- +:xref-IGovernor-GovernorNonexistentProposal-uint256-: xref:governance.adoc#IGovernor-GovernorNonexistentProposal-uint256- +:xref-IGovernor-GovernorUnexpectedProposalState-uint256-enum-IGovernor-ProposalState-bytes32-: xref:governance.adoc#IGovernor-GovernorUnexpectedProposalState-uint256-enum-IGovernor-ProposalState-bytes32- +:xref-IGovernor-GovernorInvalidVotingPeriod-uint256-: xref:governance.adoc#IGovernor-GovernorInvalidVotingPeriod-uint256- +:xref-IGovernor-GovernorInsufficientProposerVotes-address-uint256-uint256-: xref:governance.adoc#IGovernor-GovernorInsufficientProposerVotes-address-uint256-uint256- +:xref-IGovernor-GovernorRestrictedProposer-address-: xref:governance.adoc#IGovernor-GovernorRestrictedProposer-address- +:xref-IGovernor-GovernorInvalidVoteType--: xref:governance.adoc#IGovernor-GovernorInvalidVoteType-- +:xref-IGovernor-GovernorQueueNotImplemented--: xref:governance.adoc#IGovernor-GovernorQueueNotImplemented-- +:xref-IGovernor-GovernorNotQueuedProposal-uint256-: xref:governance.adoc#IGovernor-GovernorNotQueuedProposal-uint256- +:xref-IGovernor-GovernorAlreadyQueuedProposal-uint256-: xref:governance.adoc#IGovernor-GovernorAlreadyQueuedProposal-uint256- +:xref-IGovernor-GovernorInvalidSignature-address-: xref:governance.adoc#IGovernor-GovernorInvalidSignature-address- +:xref-Nonces-InvalidAccountNonce-address-uint256-: xref:utils.adoc#Nonces-InvalidAccountNonce-address-uint256- +:Governor-state: pass:normal[xref:governance.adoc#Governor-state-uint256-[`Governor.state`]] +:IGovernor-proposalNeedsQueuing: pass:normal[xref:governance.adoc#IGovernor-proposalNeedsQueuing-uint256-[`IGovernor.proposalNeedsQueuing`]] +:Governor-_executeOperations: pass:normal[xref:governance.adoc#Governor-_executeOperations-uint256-address---uint256---bytes---bytes32-[`Governor._executeOperations`]] +:Governor-_cancel: pass:normal[xref:governance.adoc#Governor-_cancel-address---uint256---bytes---bytes32-[`Governor._cancel`]] +:Governor: pass:normal[xref:governance.adoc#Governor[`Governor`]] +:Governor: pass:normal[xref:governance.adoc#Governor[`Governor`]] +:GovernorTimelockCompound-__acceptAdmin: pass:normal[xref:governance.adoc#GovernorTimelockCompound-__acceptAdmin--[`GovernorTimelockCompound.__acceptAdmin`]] +:TimelockController: pass:normal[xref:governance.adoc#TimelockController[`TimelockController`]] +:Governor: pass:normal[xref:governance.adoc#Governor[`Governor`]] +:TimelockController: pass:normal[xref:governance.adoc#TimelockController[`TimelockController`]] +:Governor: pass:normal[xref:governance.adoc#Governor[`Governor`]] +:xref-GovernorTimelockCompound-constructor-contract-ICompoundTimelock-: xref:governance.adoc#GovernorTimelockCompound-constructor-contract-ICompoundTimelock- +:xref-GovernorTimelockCompound-state-uint256-: xref:governance.adoc#GovernorTimelockCompound-state-uint256- +:xref-GovernorTimelockCompound-timelock--: xref:governance.adoc#GovernorTimelockCompound-timelock-- +:xref-GovernorTimelockCompound-proposalNeedsQueuing-uint256-: xref:governance.adoc#GovernorTimelockCompound-proposalNeedsQueuing-uint256- +:xref-GovernorTimelockCompound-_queueOperations-uint256-address---uint256---bytes---bytes32-: xref:governance.adoc#GovernorTimelockCompound-_queueOperations-uint256-address---uint256---bytes---bytes32- +:xref-GovernorTimelockCompound-_executeOperations-uint256-address---uint256---bytes---bytes32-: xref:governance.adoc#GovernorTimelockCompound-_executeOperations-uint256-address---uint256---bytes---bytes32- +:xref-GovernorTimelockCompound-_cancel-address---uint256---bytes---bytes32-: xref:governance.adoc#GovernorTimelockCompound-_cancel-address---uint256---bytes---bytes32- +:xref-GovernorTimelockCompound-_executor--: xref:governance.adoc#GovernorTimelockCompound-_executor-- +:xref-GovernorTimelockCompound-__acceptAdmin--: xref:governance.adoc#GovernorTimelockCompound-__acceptAdmin-- +:xref-GovernorTimelockCompound-updateTimelock-contract-ICompoundTimelock-: xref:governance.adoc#GovernorTimelockCompound-updateTimelock-contract-ICompoundTimelock- +:xref-Governor-receive--: xref:governance.adoc#Governor-receive-- +:xref-Governor-supportsInterface-bytes4-: xref:governance.adoc#Governor-supportsInterface-bytes4- +:xref-Governor-name--: xref:governance.adoc#Governor-name-- +:xref-Governor-version--: xref:governance.adoc#Governor-version-- +:xref-Governor-hashProposal-address---uint256---bytes---bytes32-: xref:governance.adoc#Governor-hashProposal-address---uint256---bytes---bytes32- +:xref-Governor-proposalThreshold--: xref:governance.adoc#Governor-proposalThreshold-- +:xref-Governor-proposalSnapshot-uint256-: xref:governance.adoc#Governor-proposalSnapshot-uint256- +:xref-Governor-proposalDeadline-uint256-: xref:governance.adoc#Governor-proposalDeadline-uint256- +:xref-Governor-proposalProposer-uint256-: xref:governance.adoc#Governor-proposalProposer-uint256- +:xref-Governor-proposalEta-uint256-: xref:governance.adoc#Governor-proposalEta-uint256- +:xref-Governor-_checkGovernance--: xref:governance.adoc#Governor-_checkGovernance-- +:xref-Governor-_quorumReached-uint256-: xref:governance.adoc#Governor-_quorumReached-uint256- +:xref-Governor-_voteSucceeded-uint256-: xref:governance.adoc#Governor-_voteSucceeded-uint256- +:xref-Governor-_getVotes-address-uint256-bytes-: xref:governance.adoc#Governor-_getVotes-address-uint256-bytes- +:xref-Governor-_countVote-uint256-address-uint8-uint256-bytes-: xref:governance.adoc#Governor-_countVote-uint256-address-uint8-uint256-bytes- +:xref-Governor-_defaultParams--: xref:governance.adoc#Governor-_defaultParams-- +:xref-Governor-propose-address---uint256---bytes---string-: xref:governance.adoc#Governor-propose-address---uint256---bytes---string- +:xref-Governor-_propose-address---uint256---bytes---string-address-: xref:governance.adoc#Governor-_propose-address---uint256---bytes---string-address- +:xref-Governor-queue-address---uint256---bytes---bytes32-: xref:governance.adoc#Governor-queue-address---uint256---bytes---bytes32- +:xref-Governor-execute-address---uint256---bytes---bytes32-: xref:governance.adoc#Governor-execute-address---uint256---bytes---bytes32- +:xref-Governor-cancel-address---uint256---bytes---bytes32-: xref:governance.adoc#Governor-cancel-address---uint256---bytes---bytes32- +:xref-Governor-getVotes-address-uint256-: xref:governance.adoc#Governor-getVotes-address-uint256- +:xref-Governor-getVotesWithParams-address-uint256-bytes-: xref:governance.adoc#Governor-getVotesWithParams-address-uint256-bytes- +:xref-Governor-castVote-uint256-uint8-: xref:governance.adoc#Governor-castVote-uint256-uint8- +:xref-Governor-castVoteWithReason-uint256-uint8-string-: xref:governance.adoc#Governor-castVoteWithReason-uint256-uint8-string- +:xref-Governor-castVoteWithReasonAndParams-uint256-uint8-string-bytes-: xref:governance.adoc#Governor-castVoteWithReasonAndParams-uint256-uint8-string-bytes- +:xref-Governor-castVoteBySig-uint256-uint8-address-bytes-: xref:governance.adoc#Governor-castVoteBySig-uint256-uint8-address-bytes- +:xref-Governor-castVoteWithReasonAndParamsBySig-uint256-uint8-address-string-bytes-bytes-: xref:governance.adoc#Governor-castVoteWithReasonAndParamsBySig-uint256-uint8-address-string-bytes-bytes- +:xref-Governor-_castVote-uint256-address-uint8-string-: xref:governance.adoc#Governor-_castVote-uint256-address-uint8-string- +:xref-Governor-_castVote-uint256-address-uint8-string-bytes-: xref:governance.adoc#Governor-_castVote-uint256-address-uint8-string-bytes- +:xref-Governor-relay-address-uint256-bytes-: xref:governance.adoc#Governor-relay-address-uint256-bytes- +:xref-Governor-onERC721Received-address-address-uint256-bytes-: xref:governance.adoc#Governor-onERC721Received-address-address-uint256-bytes- +:xref-Governor-onERC1155Received-address-address-uint256-uint256-bytes-: xref:governance.adoc#Governor-onERC1155Received-address-address-uint256-uint256-bytes- +:xref-Governor-onERC1155BatchReceived-address-address-uint256---uint256---bytes-: xref:governance.adoc#Governor-onERC1155BatchReceived-address-address-uint256---uint256---bytes- +:xref-Governor-_encodeStateBitmap-enum-IGovernor-ProposalState-: xref:governance.adoc#Governor-_encodeStateBitmap-enum-IGovernor-ProposalState- +:xref-Governor-_isValidDescriptionForProposer-address-string-: xref:governance.adoc#Governor-_isValidDescriptionForProposer-address-string- +:xref-Governor-clock--: xref:governance.adoc#Governor-clock-- +:xref-Governor-CLOCK_MODE--: xref:governance.adoc#Governor-CLOCK_MODE-- +:xref-Governor-votingDelay--: xref:governance.adoc#Governor-votingDelay-- +:xref-Governor-votingPeriod--: xref:governance.adoc#Governor-votingPeriod-- +:xref-Governor-quorum-uint256-: xref:governance.adoc#Governor-quorum-uint256- +:xref-IGovernor-COUNTING_MODE--: xref:governance.adoc#IGovernor-COUNTING_MODE-- +:xref-IGovernor-hasVoted-uint256-address-: xref:governance.adoc#IGovernor-hasVoted-uint256-address- +:xref-Nonces-nonces-address-: xref:utils.adoc#Nonces-nonces-address- +:xref-Nonces-_useNonce-address-: xref:utils.adoc#Nonces-_useNonce-address- +:xref-Nonces-_useCheckedNonce-address-uint256-: xref:utils.adoc#Nonces-_useCheckedNonce-address-uint256- +:xref-EIP712-_domainSeparatorV4--: xref:utils.adoc#EIP712-_domainSeparatorV4-- +:xref-EIP712-_hashTypedDataV4-bytes32-: xref:utils.adoc#EIP712-_hashTypedDataV4-bytes32- +:xref-EIP712-eip712Domain--: xref:utils.adoc#EIP712-eip712Domain-- +:xref-EIP712-_EIP712Name--: xref:utils.adoc#EIP712-_EIP712Name-- +:xref-EIP712-_EIP712Version--: xref:utils.adoc#EIP712-_EIP712Version-- +:xref-GovernorTimelockCompound-TimelockChange-address-address-: xref:governance.adoc#GovernorTimelockCompound-TimelockChange-address-address- +:xref-IGovernor-ProposalCreated-uint256-address-address---uint256---string---bytes---uint256-uint256-string-: xref:governance.adoc#IGovernor-ProposalCreated-uint256-address-address---uint256---string---bytes---uint256-uint256-string- +:xref-IGovernor-ProposalQueued-uint256-uint256-: xref:governance.adoc#IGovernor-ProposalQueued-uint256-uint256- +:xref-IGovernor-ProposalExecuted-uint256-: xref:governance.adoc#IGovernor-ProposalExecuted-uint256- +:xref-IGovernor-ProposalCanceled-uint256-: xref:governance.adoc#IGovernor-ProposalCanceled-uint256- +:xref-IGovernor-VoteCast-address-uint256-uint8-uint256-string-: xref:governance.adoc#IGovernor-VoteCast-address-uint256-uint8-uint256-string- +:xref-IGovernor-VoteCastWithParams-address-uint256-uint8-uint256-string-bytes-: xref:governance.adoc#IGovernor-VoteCastWithParams-address-uint256-uint8-uint256-string-bytes- +:xref-IERC5267-EIP712DomainChanged--: xref:interfaces.adoc#IERC5267-EIP712DomainChanged-- +:xref-IGovernor-GovernorInvalidProposalLength-uint256-uint256-uint256-: xref:governance.adoc#IGovernor-GovernorInvalidProposalLength-uint256-uint256-uint256- +:xref-IGovernor-GovernorAlreadyCastVote-address-: xref:governance.adoc#IGovernor-GovernorAlreadyCastVote-address- +:xref-IGovernor-GovernorDisabledDeposit--: xref:governance.adoc#IGovernor-GovernorDisabledDeposit-- +:xref-IGovernor-GovernorOnlyProposer-address-: xref:governance.adoc#IGovernor-GovernorOnlyProposer-address- +:xref-IGovernor-GovernorOnlyExecutor-address-: xref:governance.adoc#IGovernor-GovernorOnlyExecutor-address- +:xref-IGovernor-GovernorNonexistentProposal-uint256-: xref:governance.adoc#IGovernor-GovernorNonexistentProposal-uint256- +:xref-IGovernor-GovernorUnexpectedProposalState-uint256-enum-IGovernor-ProposalState-bytes32-: xref:governance.adoc#IGovernor-GovernorUnexpectedProposalState-uint256-enum-IGovernor-ProposalState-bytes32- +:xref-IGovernor-GovernorInvalidVotingPeriod-uint256-: xref:governance.adoc#IGovernor-GovernorInvalidVotingPeriod-uint256- +:xref-IGovernor-GovernorInsufficientProposerVotes-address-uint256-uint256-: xref:governance.adoc#IGovernor-GovernorInsufficientProposerVotes-address-uint256-uint256- +:xref-IGovernor-GovernorRestrictedProposer-address-: xref:governance.adoc#IGovernor-GovernorRestrictedProposer-address- +:xref-IGovernor-GovernorInvalidVoteType--: xref:governance.adoc#IGovernor-GovernorInvalidVoteType-- +:xref-IGovernor-GovernorQueueNotImplemented--: xref:governance.adoc#IGovernor-GovernorQueueNotImplemented-- +:xref-IGovernor-GovernorNotQueuedProposal-uint256-: xref:governance.adoc#IGovernor-GovernorNotQueuedProposal-uint256- +:xref-IGovernor-GovernorAlreadyQueuedProposal-uint256-: xref:governance.adoc#IGovernor-GovernorAlreadyQueuedProposal-uint256- +:xref-IGovernor-GovernorInvalidSignature-address-: xref:governance.adoc#IGovernor-GovernorInvalidSignature-address- +:xref-Nonces-InvalidAccountNonce-address-uint256-: xref:utils.adoc#Nonces-InvalidAccountNonce-address-uint256- +:Governor-state: pass:normal[xref:governance.adoc#Governor-state-uint256-[`Governor.state`]] +:IGovernor-proposalNeedsQueuing: pass:normal[xref:governance.adoc#IGovernor-proposalNeedsQueuing-uint256-[`IGovernor.proposalNeedsQueuing`]] +:Governor-_executeOperations: pass:normal[xref:governance.adoc#Governor-_executeOperations-uint256-address---uint256---bytes---bytes32-[`Governor._executeOperations`]] +:Governor-_cancel: pass:normal[xref:governance.adoc#Governor-_cancel-address---uint256---bytes---bytes32-[`Governor._cancel`]] +:Governor: pass:normal[xref:governance.adoc#Governor[`Governor`]] +:xref-GovernorSettings-constructor-uint48-uint32-uint256-: xref:governance.adoc#GovernorSettings-constructor-uint48-uint32-uint256- +:xref-GovernorSettings-votingDelay--: xref:governance.adoc#GovernorSettings-votingDelay-- +:xref-GovernorSettings-votingPeriod--: xref:governance.adoc#GovernorSettings-votingPeriod-- +:xref-GovernorSettings-proposalThreshold--: xref:governance.adoc#GovernorSettings-proposalThreshold-- +:xref-GovernorSettings-setVotingDelay-uint48-: xref:governance.adoc#GovernorSettings-setVotingDelay-uint48- +:xref-GovernorSettings-setVotingPeriod-uint32-: xref:governance.adoc#GovernorSettings-setVotingPeriod-uint32- +:xref-GovernorSettings-setProposalThreshold-uint256-: xref:governance.adoc#GovernorSettings-setProposalThreshold-uint256- +:xref-GovernorSettings-_setVotingDelay-uint48-: xref:governance.adoc#GovernorSettings-_setVotingDelay-uint48- +:xref-GovernorSettings-_setVotingPeriod-uint32-: xref:governance.adoc#GovernorSettings-_setVotingPeriod-uint32- +:xref-GovernorSettings-_setProposalThreshold-uint256-: xref:governance.adoc#GovernorSettings-_setProposalThreshold-uint256- +:xref-Governor-receive--: xref:governance.adoc#Governor-receive-- +:xref-Governor-supportsInterface-bytes4-: xref:governance.adoc#Governor-supportsInterface-bytes4- +:xref-Governor-name--: xref:governance.adoc#Governor-name-- +:xref-Governor-version--: xref:governance.adoc#Governor-version-- +:xref-Governor-hashProposal-address---uint256---bytes---bytes32-: xref:governance.adoc#Governor-hashProposal-address---uint256---bytes---bytes32- +:xref-Governor-state-uint256-: xref:governance.adoc#Governor-state-uint256- +:xref-Governor-proposalSnapshot-uint256-: xref:governance.adoc#Governor-proposalSnapshot-uint256- +:xref-Governor-proposalDeadline-uint256-: xref:governance.adoc#Governor-proposalDeadline-uint256- +:xref-Governor-proposalProposer-uint256-: xref:governance.adoc#Governor-proposalProposer-uint256- +:xref-Governor-proposalEta-uint256-: xref:governance.adoc#Governor-proposalEta-uint256- +:xref-Governor-proposalNeedsQueuing-uint256-: xref:governance.adoc#Governor-proposalNeedsQueuing-uint256- +:xref-Governor-_checkGovernance--: xref:governance.adoc#Governor-_checkGovernance-- +:xref-Governor-_quorumReached-uint256-: xref:governance.adoc#Governor-_quorumReached-uint256- +:xref-Governor-_voteSucceeded-uint256-: xref:governance.adoc#Governor-_voteSucceeded-uint256- +:xref-Governor-_getVotes-address-uint256-bytes-: xref:governance.adoc#Governor-_getVotes-address-uint256-bytes- +:xref-Governor-_countVote-uint256-address-uint8-uint256-bytes-: xref:governance.adoc#Governor-_countVote-uint256-address-uint8-uint256-bytes- +:xref-Governor-_defaultParams--: xref:governance.adoc#Governor-_defaultParams-- +:xref-Governor-propose-address---uint256---bytes---string-: xref:governance.adoc#Governor-propose-address---uint256---bytes---string- +:xref-Governor-_propose-address---uint256---bytes---string-address-: xref:governance.adoc#Governor-_propose-address---uint256---bytes---string-address- +:xref-Governor-queue-address---uint256---bytes---bytes32-: xref:governance.adoc#Governor-queue-address---uint256---bytes---bytes32- +:xref-Governor-_queueOperations-uint256-address---uint256---bytes---bytes32-: xref:governance.adoc#Governor-_queueOperations-uint256-address---uint256---bytes---bytes32- +:xref-Governor-execute-address---uint256---bytes---bytes32-: xref:governance.adoc#Governor-execute-address---uint256---bytes---bytes32- +:xref-Governor-_executeOperations-uint256-address---uint256---bytes---bytes32-: xref:governance.adoc#Governor-_executeOperations-uint256-address---uint256---bytes---bytes32- +:xref-Governor-cancel-address---uint256---bytes---bytes32-: xref:governance.adoc#Governor-cancel-address---uint256---bytes---bytes32- +:xref-Governor-_cancel-address---uint256---bytes---bytes32-: xref:governance.adoc#Governor-_cancel-address---uint256---bytes---bytes32- +:xref-Governor-getVotes-address-uint256-: xref:governance.adoc#Governor-getVotes-address-uint256- +:xref-Governor-getVotesWithParams-address-uint256-bytes-: xref:governance.adoc#Governor-getVotesWithParams-address-uint256-bytes- +:xref-Governor-castVote-uint256-uint8-: xref:governance.adoc#Governor-castVote-uint256-uint8- +:xref-Governor-castVoteWithReason-uint256-uint8-string-: xref:governance.adoc#Governor-castVoteWithReason-uint256-uint8-string- +:xref-Governor-castVoteWithReasonAndParams-uint256-uint8-string-bytes-: xref:governance.adoc#Governor-castVoteWithReasonAndParams-uint256-uint8-string-bytes- +:xref-Governor-castVoteBySig-uint256-uint8-address-bytes-: xref:governance.adoc#Governor-castVoteBySig-uint256-uint8-address-bytes- +:xref-Governor-castVoteWithReasonAndParamsBySig-uint256-uint8-address-string-bytes-bytes-: xref:governance.adoc#Governor-castVoteWithReasonAndParamsBySig-uint256-uint8-address-string-bytes-bytes- +:xref-Governor-_castVote-uint256-address-uint8-string-: xref:governance.adoc#Governor-_castVote-uint256-address-uint8-string- +:xref-Governor-_castVote-uint256-address-uint8-string-bytes-: xref:governance.adoc#Governor-_castVote-uint256-address-uint8-string-bytes- +:xref-Governor-relay-address-uint256-bytes-: xref:governance.adoc#Governor-relay-address-uint256-bytes- +:xref-Governor-_executor--: xref:governance.adoc#Governor-_executor-- +:xref-Governor-onERC721Received-address-address-uint256-bytes-: xref:governance.adoc#Governor-onERC721Received-address-address-uint256-bytes- +:xref-Governor-onERC1155Received-address-address-uint256-uint256-bytes-: xref:governance.adoc#Governor-onERC1155Received-address-address-uint256-uint256-bytes- +:xref-Governor-onERC1155BatchReceived-address-address-uint256---uint256---bytes-: xref:governance.adoc#Governor-onERC1155BatchReceived-address-address-uint256---uint256---bytes- +:xref-Governor-_encodeStateBitmap-enum-IGovernor-ProposalState-: xref:governance.adoc#Governor-_encodeStateBitmap-enum-IGovernor-ProposalState- +:xref-Governor-_isValidDescriptionForProposer-address-string-: xref:governance.adoc#Governor-_isValidDescriptionForProposer-address-string- +:xref-Governor-clock--: xref:governance.adoc#Governor-clock-- +:xref-Governor-CLOCK_MODE--: xref:governance.adoc#Governor-CLOCK_MODE-- +:xref-Governor-quorum-uint256-: xref:governance.adoc#Governor-quorum-uint256- +:xref-IGovernor-COUNTING_MODE--: xref:governance.adoc#IGovernor-COUNTING_MODE-- +:xref-IGovernor-hasVoted-uint256-address-: xref:governance.adoc#IGovernor-hasVoted-uint256-address- +:xref-Nonces-nonces-address-: xref:utils.adoc#Nonces-nonces-address- +:xref-Nonces-_useNonce-address-: xref:utils.adoc#Nonces-_useNonce-address- +:xref-Nonces-_useCheckedNonce-address-uint256-: xref:utils.adoc#Nonces-_useCheckedNonce-address-uint256- +:xref-EIP712-_domainSeparatorV4--: xref:utils.adoc#EIP712-_domainSeparatorV4-- +:xref-EIP712-_hashTypedDataV4-bytes32-: xref:utils.adoc#EIP712-_hashTypedDataV4-bytes32- +:xref-EIP712-eip712Domain--: xref:utils.adoc#EIP712-eip712Domain-- +:xref-EIP712-_EIP712Name--: xref:utils.adoc#EIP712-_EIP712Name-- +:xref-EIP712-_EIP712Version--: xref:utils.adoc#EIP712-_EIP712Version-- +:xref-GovernorSettings-VotingDelaySet-uint256-uint256-: xref:governance.adoc#GovernorSettings-VotingDelaySet-uint256-uint256- +:xref-GovernorSettings-VotingPeriodSet-uint256-uint256-: xref:governance.adoc#GovernorSettings-VotingPeriodSet-uint256-uint256- +:xref-GovernorSettings-ProposalThresholdSet-uint256-uint256-: xref:governance.adoc#GovernorSettings-ProposalThresholdSet-uint256-uint256- +:xref-IGovernor-ProposalCreated-uint256-address-address---uint256---string---bytes---uint256-uint256-string-: xref:governance.adoc#IGovernor-ProposalCreated-uint256-address-address---uint256---string---bytes---uint256-uint256-string- +:xref-IGovernor-ProposalQueued-uint256-uint256-: xref:governance.adoc#IGovernor-ProposalQueued-uint256-uint256- +:xref-IGovernor-ProposalExecuted-uint256-: xref:governance.adoc#IGovernor-ProposalExecuted-uint256- +:xref-IGovernor-ProposalCanceled-uint256-: xref:governance.adoc#IGovernor-ProposalCanceled-uint256- +:xref-IGovernor-VoteCast-address-uint256-uint8-uint256-string-: xref:governance.adoc#IGovernor-VoteCast-address-uint256-uint8-uint256-string- +:xref-IGovernor-VoteCastWithParams-address-uint256-uint8-uint256-string-bytes-: xref:governance.adoc#IGovernor-VoteCastWithParams-address-uint256-uint8-uint256-string-bytes- +:xref-IERC5267-EIP712DomainChanged--: xref:interfaces.adoc#IERC5267-EIP712DomainChanged-- +:xref-IGovernor-GovernorInvalidProposalLength-uint256-uint256-uint256-: xref:governance.adoc#IGovernor-GovernorInvalidProposalLength-uint256-uint256-uint256- +:xref-IGovernor-GovernorAlreadyCastVote-address-: xref:governance.adoc#IGovernor-GovernorAlreadyCastVote-address- +:xref-IGovernor-GovernorDisabledDeposit--: xref:governance.adoc#IGovernor-GovernorDisabledDeposit-- +:xref-IGovernor-GovernorOnlyProposer-address-: xref:governance.adoc#IGovernor-GovernorOnlyProposer-address- +:xref-IGovernor-GovernorOnlyExecutor-address-: xref:governance.adoc#IGovernor-GovernorOnlyExecutor-address- +:xref-IGovernor-GovernorNonexistentProposal-uint256-: xref:governance.adoc#IGovernor-GovernorNonexistentProposal-uint256- +:xref-IGovernor-GovernorUnexpectedProposalState-uint256-enum-IGovernor-ProposalState-bytes32-: xref:governance.adoc#IGovernor-GovernorUnexpectedProposalState-uint256-enum-IGovernor-ProposalState-bytes32- +:xref-IGovernor-GovernorInvalidVotingPeriod-uint256-: xref:governance.adoc#IGovernor-GovernorInvalidVotingPeriod-uint256- +:xref-IGovernor-GovernorInsufficientProposerVotes-address-uint256-uint256-: xref:governance.adoc#IGovernor-GovernorInsufficientProposerVotes-address-uint256-uint256- +:xref-IGovernor-GovernorRestrictedProposer-address-: xref:governance.adoc#IGovernor-GovernorRestrictedProposer-address- +:xref-IGovernor-GovernorInvalidVoteType--: xref:governance.adoc#IGovernor-GovernorInvalidVoteType-- +:xref-IGovernor-GovernorQueueNotImplemented--: xref:governance.adoc#IGovernor-GovernorQueueNotImplemented-- +:xref-IGovernor-GovernorNotQueuedProposal-uint256-: xref:governance.adoc#IGovernor-GovernorNotQueuedProposal-uint256- +:xref-IGovernor-GovernorAlreadyQueuedProposal-uint256-: xref:governance.adoc#IGovernor-GovernorAlreadyQueuedProposal-uint256- +:xref-IGovernor-GovernorInvalidSignature-address-: xref:governance.adoc#IGovernor-GovernorInvalidSignature-address- +:xref-Nonces-InvalidAccountNonce-address-uint256-: xref:utils.adoc#Nonces-InvalidAccountNonce-address-uint256- +:IGovernor-votingDelay: pass:normal[xref:governance.adoc#IGovernor-votingDelay--[`IGovernor.votingDelay`]] +:IGovernor-votingPeriod: pass:normal[xref:governance.adoc#IGovernor-votingPeriod--[`IGovernor.votingPeriod`]] +:Governor-proposalThreshold: pass:normal[xref:governance.adoc#Governor-proposalThreshold--[`Governor.proposalThreshold`]] +:xref-GovernorPreventLateQuorum-constructor-uint48-: xref:governance.adoc#GovernorPreventLateQuorum-constructor-uint48- +:xref-GovernorPreventLateQuorum-proposalDeadline-uint256-: xref:governance.adoc#GovernorPreventLateQuorum-proposalDeadline-uint256- +:xref-GovernorPreventLateQuorum-_castVote-uint256-address-uint8-string-bytes-: xref:governance.adoc#GovernorPreventLateQuorum-_castVote-uint256-address-uint8-string-bytes- +:xref-GovernorPreventLateQuorum-lateQuorumVoteExtension--: xref:governance.adoc#GovernorPreventLateQuorum-lateQuorumVoteExtension-- +:xref-GovernorPreventLateQuorum-setLateQuorumVoteExtension-uint48-: xref:governance.adoc#GovernorPreventLateQuorum-setLateQuorumVoteExtension-uint48- +:xref-GovernorPreventLateQuorum-_setLateQuorumVoteExtension-uint48-: xref:governance.adoc#GovernorPreventLateQuorum-_setLateQuorumVoteExtension-uint48- +:xref-Governor-receive--: xref:governance.adoc#Governor-receive-- +:xref-Governor-supportsInterface-bytes4-: xref:governance.adoc#Governor-supportsInterface-bytes4- +:xref-Governor-name--: xref:governance.adoc#Governor-name-- +:xref-Governor-version--: xref:governance.adoc#Governor-version-- +:xref-Governor-hashProposal-address---uint256---bytes---bytes32-: xref:governance.adoc#Governor-hashProposal-address---uint256---bytes---bytes32- +:xref-Governor-state-uint256-: xref:governance.adoc#Governor-state-uint256- +:xref-Governor-proposalThreshold--: xref:governance.adoc#Governor-proposalThreshold-- +:xref-Governor-proposalSnapshot-uint256-: xref:governance.adoc#Governor-proposalSnapshot-uint256- +:xref-Governor-proposalProposer-uint256-: xref:governance.adoc#Governor-proposalProposer-uint256- +:xref-Governor-proposalEta-uint256-: xref:governance.adoc#Governor-proposalEta-uint256- +:xref-Governor-proposalNeedsQueuing-uint256-: xref:governance.adoc#Governor-proposalNeedsQueuing-uint256- +:xref-Governor-_checkGovernance--: xref:governance.adoc#Governor-_checkGovernance-- +:xref-Governor-_quorumReached-uint256-: xref:governance.adoc#Governor-_quorumReached-uint256- +:xref-Governor-_voteSucceeded-uint256-: xref:governance.adoc#Governor-_voteSucceeded-uint256- +:xref-Governor-_getVotes-address-uint256-bytes-: xref:governance.adoc#Governor-_getVotes-address-uint256-bytes- +:xref-Governor-_countVote-uint256-address-uint8-uint256-bytes-: xref:governance.adoc#Governor-_countVote-uint256-address-uint8-uint256-bytes- +:xref-Governor-_defaultParams--: xref:governance.adoc#Governor-_defaultParams-- +:xref-Governor-propose-address---uint256---bytes---string-: xref:governance.adoc#Governor-propose-address---uint256---bytes---string- +:xref-Governor-_propose-address---uint256---bytes---string-address-: xref:governance.adoc#Governor-_propose-address---uint256---bytes---string-address- +:xref-Governor-queue-address---uint256---bytes---bytes32-: xref:governance.adoc#Governor-queue-address---uint256---bytes---bytes32- +:xref-Governor-_queueOperations-uint256-address---uint256---bytes---bytes32-: xref:governance.adoc#Governor-_queueOperations-uint256-address---uint256---bytes---bytes32- +:xref-Governor-execute-address---uint256---bytes---bytes32-: xref:governance.adoc#Governor-execute-address---uint256---bytes---bytes32- +:xref-Governor-_executeOperations-uint256-address---uint256---bytes---bytes32-: xref:governance.adoc#Governor-_executeOperations-uint256-address---uint256---bytes---bytes32- +:xref-Governor-cancel-address---uint256---bytes---bytes32-: xref:governance.adoc#Governor-cancel-address---uint256---bytes---bytes32- +:xref-Governor-_cancel-address---uint256---bytes---bytes32-: xref:governance.adoc#Governor-_cancel-address---uint256---bytes---bytes32- +:xref-Governor-getVotes-address-uint256-: xref:governance.adoc#Governor-getVotes-address-uint256- +:xref-Governor-getVotesWithParams-address-uint256-bytes-: xref:governance.adoc#Governor-getVotesWithParams-address-uint256-bytes- +:xref-Governor-castVote-uint256-uint8-: xref:governance.adoc#Governor-castVote-uint256-uint8- +:xref-Governor-castVoteWithReason-uint256-uint8-string-: xref:governance.adoc#Governor-castVoteWithReason-uint256-uint8-string- +:xref-Governor-castVoteWithReasonAndParams-uint256-uint8-string-bytes-: xref:governance.adoc#Governor-castVoteWithReasonAndParams-uint256-uint8-string-bytes- +:xref-Governor-castVoteBySig-uint256-uint8-address-bytes-: xref:governance.adoc#Governor-castVoteBySig-uint256-uint8-address-bytes- +:xref-Governor-castVoteWithReasonAndParamsBySig-uint256-uint8-address-string-bytes-bytes-: xref:governance.adoc#Governor-castVoteWithReasonAndParamsBySig-uint256-uint8-address-string-bytes-bytes- +:xref-Governor-_castVote-uint256-address-uint8-string-: xref:governance.adoc#Governor-_castVote-uint256-address-uint8-string- +:xref-Governor-relay-address-uint256-bytes-: xref:governance.adoc#Governor-relay-address-uint256-bytes- +:xref-Governor-_executor--: xref:governance.adoc#Governor-_executor-- +:xref-Governor-onERC721Received-address-address-uint256-bytes-: xref:governance.adoc#Governor-onERC721Received-address-address-uint256-bytes- +:xref-Governor-onERC1155Received-address-address-uint256-uint256-bytes-: xref:governance.adoc#Governor-onERC1155Received-address-address-uint256-uint256-bytes- +:xref-Governor-onERC1155BatchReceived-address-address-uint256---uint256---bytes-: xref:governance.adoc#Governor-onERC1155BatchReceived-address-address-uint256---uint256---bytes- +:xref-Governor-_encodeStateBitmap-enum-IGovernor-ProposalState-: xref:governance.adoc#Governor-_encodeStateBitmap-enum-IGovernor-ProposalState- +:xref-Governor-_isValidDescriptionForProposer-address-string-: xref:governance.adoc#Governor-_isValidDescriptionForProposer-address-string- +:xref-Governor-clock--: xref:governance.adoc#Governor-clock-- +:xref-Governor-CLOCK_MODE--: xref:governance.adoc#Governor-CLOCK_MODE-- +:xref-Governor-votingDelay--: xref:governance.adoc#Governor-votingDelay-- +:xref-Governor-votingPeriod--: xref:governance.adoc#Governor-votingPeriod-- +:xref-Governor-quorum-uint256-: xref:governance.adoc#Governor-quorum-uint256- +:xref-IGovernor-COUNTING_MODE--: xref:governance.adoc#IGovernor-COUNTING_MODE-- +:xref-IGovernor-hasVoted-uint256-address-: xref:governance.adoc#IGovernor-hasVoted-uint256-address- +:xref-Nonces-nonces-address-: xref:utils.adoc#Nonces-nonces-address- +:xref-Nonces-_useNonce-address-: xref:utils.adoc#Nonces-_useNonce-address- +:xref-Nonces-_useCheckedNonce-address-uint256-: xref:utils.adoc#Nonces-_useCheckedNonce-address-uint256- +:xref-EIP712-_domainSeparatorV4--: xref:utils.adoc#EIP712-_domainSeparatorV4-- +:xref-EIP712-_hashTypedDataV4-bytes32-: xref:utils.adoc#EIP712-_hashTypedDataV4-bytes32- +:xref-EIP712-eip712Domain--: xref:utils.adoc#EIP712-eip712Domain-- +:xref-EIP712-_EIP712Name--: xref:utils.adoc#EIP712-_EIP712Name-- +:xref-EIP712-_EIP712Version--: xref:utils.adoc#EIP712-_EIP712Version-- +:xref-GovernorPreventLateQuorum-ProposalExtended-uint256-uint64-: xref:governance.adoc#GovernorPreventLateQuorum-ProposalExtended-uint256-uint64- +:xref-GovernorPreventLateQuorum-LateQuorumVoteExtensionSet-uint64-uint64-: xref:governance.adoc#GovernorPreventLateQuorum-LateQuorumVoteExtensionSet-uint64-uint64- +:xref-IGovernor-ProposalCreated-uint256-address-address---uint256---string---bytes---uint256-uint256-string-: xref:governance.adoc#IGovernor-ProposalCreated-uint256-address-address---uint256---string---bytes---uint256-uint256-string- +:xref-IGovernor-ProposalQueued-uint256-uint256-: xref:governance.adoc#IGovernor-ProposalQueued-uint256-uint256- +:xref-IGovernor-ProposalExecuted-uint256-: xref:governance.adoc#IGovernor-ProposalExecuted-uint256- +:xref-IGovernor-ProposalCanceled-uint256-: xref:governance.adoc#IGovernor-ProposalCanceled-uint256- +:xref-IGovernor-VoteCast-address-uint256-uint8-uint256-string-: xref:governance.adoc#IGovernor-VoteCast-address-uint256-uint8-uint256-string- +:xref-IGovernor-VoteCastWithParams-address-uint256-uint8-uint256-string-bytes-: xref:governance.adoc#IGovernor-VoteCastWithParams-address-uint256-uint8-uint256-string-bytes- +:xref-IERC5267-EIP712DomainChanged--: xref:interfaces.adoc#IERC5267-EIP712DomainChanged-- +:xref-IGovernor-GovernorInvalidProposalLength-uint256-uint256-uint256-: xref:governance.adoc#IGovernor-GovernorInvalidProposalLength-uint256-uint256-uint256- +:xref-IGovernor-GovernorAlreadyCastVote-address-: xref:governance.adoc#IGovernor-GovernorAlreadyCastVote-address- +:xref-IGovernor-GovernorDisabledDeposit--: xref:governance.adoc#IGovernor-GovernorDisabledDeposit-- +:xref-IGovernor-GovernorOnlyProposer-address-: xref:governance.adoc#IGovernor-GovernorOnlyProposer-address- +:xref-IGovernor-GovernorOnlyExecutor-address-: xref:governance.adoc#IGovernor-GovernorOnlyExecutor-address- +:xref-IGovernor-GovernorNonexistentProposal-uint256-: xref:governance.adoc#IGovernor-GovernorNonexistentProposal-uint256- +:xref-IGovernor-GovernorUnexpectedProposalState-uint256-enum-IGovernor-ProposalState-bytes32-: xref:governance.adoc#IGovernor-GovernorUnexpectedProposalState-uint256-enum-IGovernor-ProposalState-bytes32- +:xref-IGovernor-GovernorInvalidVotingPeriod-uint256-: xref:governance.adoc#IGovernor-GovernorInvalidVotingPeriod-uint256- +:xref-IGovernor-GovernorInsufficientProposerVotes-address-uint256-uint256-: xref:governance.adoc#IGovernor-GovernorInsufficientProposerVotes-address-uint256-uint256- +:xref-IGovernor-GovernorRestrictedProposer-address-: xref:governance.adoc#IGovernor-GovernorRestrictedProposer-address- +:xref-IGovernor-GovernorInvalidVoteType--: xref:governance.adoc#IGovernor-GovernorInvalidVoteType-- +:xref-IGovernor-GovernorQueueNotImplemented--: xref:governance.adoc#IGovernor-GovernorQueueNotImplemented-- +:xref-IGovernor-GovernorNotQueuedProposal-uint256-: xref:governance.adoc#IGovernor-GovernorNotQueuedProposal-uint256- +:xref-IGovernor-GovernorAlreadyQueuedProposal-uint256-: xref:governance.adoc#IGovernor-GovernorAlreadyQueuedProposal-uint256- +:xref-IGovernor-GovernorInvalidSignature-address-: xref:governance.adoc#IGovernor-GovernorInvalidSignature-address- +:xref-Nonces-InvalidAccountNonce-address-uint256-: xref:utils.adoc#Nonces-InvalidAccountNonce-address-uint256- +:Governor-proposalDeadline: pass:normal[xref:governance.adoc#Governor-proposalDeadline-uint256-[`Governor.proposalDeadline`]] +:Governor-_castVote: pass:normal[xref:governance.adoc#Governor-_castVote-uint256-address-uint8-string-bytes-[`Governor._castVote`]] +:Governor: pass:normal[xref:governance.adoc#Governor[`Governor`]] +:Governor-queue: pass:normal[xref:governance.adoc#Governor-queue-address---uint256---bytes---bytes32-[`Governor.queue`]] +:Governor-execute: pass:normal[xref:governance.adoc#Governor-execute-address---uint256---bytes---bytes32-[`Governor.execute`]] +:xref-GovernorStorage-_propose-address---uint256---bytes---string-address-: xref:governance.adoc#GovernorStorage-_propose-address---uint256---bytes---string-address- +:xref-GovernorStorage-queue-uint256-: xref:governance.adoc#GovernorStorage-queue-uint256- +:xref-GovernorStorage-execute-uint256-: xref:governance.adoc#GovernorStorage-execute-uint256- +:xref-GovernorStorage-cancel-uint256-: xref:governance.adoc#GovernorStorage-cancel-uint256- +:xref-GovernorStorage-proposalCount--: xref:governance.adoc#GovernorStorage-proposalCount-- +:xref-GovernorStorage-proposalDetails-uint256-: xref:governance.adoc#GovernorStorage-proposalDetails-uint256- +:xref-GovernorStorage-proposalDetailsAt-uint256-: xref:governance.adoc#GovernorStorage-proposalDetailsAt-uint256- +:xref-Governor-receive--: xref:governance.adoc#Governor-receive-- +:xref-Governor-supportsInterface-bytes4-: xref:governance.adoc#Governor-supportsInterface-bytes4- +:xref-Governor-name--: xref:governance.adoc#Governor-name-- +:xref-Governor-version--: xref:governance.adoc#Governor-version-- +:xref-Governor-hashProposal-address---uint256---bytes---bytes32-: xref:governance.adoc#Governor-hashProposal-address---uint256---bytes---bytes32- +:xref-Governor-state-uint256-: xref:governance.adoc#Governor-state-uint256- +:xref-Governor-proposalThreshold--: xref:governance.adoc#Governor-proposalThreshold-- +:xref-Governor-proposalSnapshot-uint256-: xref:governance.adoc#Governor-proposalSnapshot-uint256- +:xref-Governor-proposalDeadline-uint256-: xref:governance.adoc#Governor-proposalDeadline-uint256- +:xref-Governor-proposalProposer-uint256-: xref:governance.adoc#Governor-proposalProposer-uint256- +:xref-Governor-proposalEta-uint256-: xref:governance.adoc#Governor-proposalEta-uint256- +:xref-Governor-proposalNeedsQueuing-uint256-: xref:governance.adoc#Governor-proposalNeedsQueuing-uint256- +:xref-Governor-_checkGovernance--: xref:governance.adoc#Governor-_checkGovernance-- +:xref-Governor-_quorumReached-uint256-: xref:governance.adoc#Governor-_quorumReached-uint256- +:xref-Governor-_voteSucceeded-uint256-: xref:governance.adoc#Governor-_voteSucceeded-uint256- +:xref-Governor-_getVotes-address-uint256-bytes-: xref:governance.adoc#Governor-_getVotes-address-uint256-bytes- +:xref-Governor-_countVote-uint256-address-uint8-uint256-bytes-: xref:governance.adoc#Governor-_countVote-uint256-address-uint8-uint256-bytes- +:xref-Governor-_defaultParams--: xref:governance.adoc#Governor-_defaultParams-- +:xref-Governor-propose-address---uint256---bytes---string-: xref:governance.adoc#Governor-propose-address---uint256---bytes---string- +:xref-Governor-queue-address---uint256---bytes---bytes32-: xref:governance.adoc#Governor-queue-address---uint256---bytes---bytes32- +:xref-Governor-_queueOperations-uint256-address---uint256---bytes---bytes32-: xref:governance.adoc#Governor-_queueOperations-uint256-address---uint256---bytes---bytes32- +:xref-Governor-execute-address---uint256---bytes---bytes32-: xref:governance.adoc#Governor-execute-address---uint256---bytes---bytes32- +:xref-Governor-_executeOperations-uint256-address---uint256---bytes---bytes32-: xref:governance.adoc#Governor-_executeOperations-uint256-address---uint256---bytes---bytes32- +:xref-Governor-cancel-address---uint256---bytes---bytes32-: xref:governance.adoc#Governor-cancel-address---uint256---bytes---bytes32- +:xref-Governor-_cancel-address---uint256---bytes---bytes32-: xref:governance.adoc#Governor-_cancel-address---uint256---bytes---bytes32- +:xref-Governor-getVotes-address-uint256-: xref:governance.adoc#Governor-getVotes-address-uint256- +:xref-Governor-getVotesWithParams-address-uint256-bytes-: xref:governance.adoc#Governor-getVotesWithParams-address-uint256-bytes- +:xref-Governor-castVote-uint256-uint8-: xref:governance.adoc#Governor-castVote-uint256-uint8- +:xref-Governor-castVoteWithReason-uint256-uint8-string-: xref:governance.adoc#Governor-castVoteWithReason-uint256-uint8-string- +:xref-Governor-castVoteWithReasonAndParams-uint256-uint8-string-bytes-: xref:governance.adoc#Governor-castVoteWithReasonAndParams-uint256-uint8-string-bytes- +:xref-Governor-castVoteBySig-uint256-uint8-address-bytes-: xref:governance.adoc#Governor-castVoteBySig-uint256-uint8-address-bytes- +:xref-Governor-castVoteWithReasonAndParamsBySig-uint256-uint8-address-string-bytes-bytes-: xref:governance.adoc#Governor-castVoteWithReasonAndParamsBySig-uint256-uint8-address-string-bytes-bytes- +:xref-Governor-_castVote-uint256-address-uint8-string-: xref:governance.adoc#Governor-_castVote-uint256-address-uint8-string- +:xref-Governor-_castVote-uint256-address-uint8-string-bytes-: xref:governance.adoc#Governor-_castVote-uint256-address-uint8-string-bytes- +:xref-Governor-relay-address-uint256-bytes-: xref:governance.adoc#Governor-relay-address-uint256-bytes- +:xref-Governor-_executor--: xref:governance.adoc#Governor-_executor-- +:xref-Governor-onERC721Received-address-address-uint256-bytes-: xref:governance.adoc#Governor-onERC721Received-address-address-uint256-bytes- +:xref-Governor-onERC1155Received-address-address-uint256-uint256-bytes-: xref:governance.adoc#Governor-onERC1155Received-address-address-uint256-uint256-bytes- +:xref-Governor-onERC1155BatchReceived-address-address-uint256---uint256---bytes-: xref:governance.adoc#Governor-onERC1155BatchReceived-address-address-uint256---uint256---bytes- +:xref-Governor-_encodeStateBitmap-enum-IGovernor-ProposalState-: xref:governance.adoc#Governor-_encodeStateBitmap-enum-IGovernor-ProposalState- +:xref-Governor-_isValidDescriptionForProposer-address-string-: xref:governance.adoc#Governor-_isValidDescriptionForProposer-address-string- +:xref-Governor-clock--: xref:governance.adoc#Governor-clock-- +:xref-Governor-CLOCK_MODE--: xref:governance.adoc#Governor-CLOCK_MODE-- +:xref-Governor-votingDelay--: xref:governance.adoc#Governor-votingDelay-- +:xref-Governor-votingPeriod--: xref:governance.adoc#Governor-votingPeriod-- +:xref-Governor-quorum-uint256-: xref:governance.adoc#Governor-quorum-uint256- +:xref-IGovernor-COUNTING_MODE--: xref:governance.adoc#IGovernor-COUNTING_MODE-- +:xref-IGovernor-hasVoted-uint256-address-: xref:governance.adoc#IGovernor-hasVoted-uint256-address- +:xref-Nonces-nonces-address-: xref:utils.adoc#Nonces-nonces-address- +:xref-Nonces-_useNonce-address-: xref:utils.adoc#Nonces-_useNonce-address- +:xref-Nonces-_useCheckedNonce-address-uint256-: xref:utils.adoc#Nonces-_useCheckedNonce-address-uint256- +:xref-EIP712-_domainSeparatorV4--: xref:utils.adoc#EIP712-_domainSeparatorV4-- +:xref-EIP712-_hashTypedDataV4-bytes32-: xref:utils.adoc#EIP712-_hashTypedDataV4-bytes32- +:xref-EIP712-eip712Domain--: xref:utils.adoc#EIP712-eip712Domain-- +:xref-EIP712-_EIP712Name--: xref:utils.adoc#EIP712-_EIP712Name-- +:xref-EIP712-_EIP712Version--: xref:utils.adoc#EIP712-_EIP712Version-- +:xref-IGovernor-ProposalCreated-uint256-address-address---uint256---string---bytes---uint256-uint256-string-: xref:governance.adoc#IGovernor-ProposalCreated-uint256-address-address---uint256---string---bytes---uint256-uint256-string- +:xref-IGovernor-ProposalQueued-uint256-uint256-: xref:governance.adoc#IGovernor-ProposalQueued-uint256-uint256- +:xref-IGovernor-ProposalExecuted-uint256-: xref:governance.adoc#IGovernor-ProposalExecuted-uint256- +:xref-IGovernor-ProposalCanceled-uint256-: xref:governance.adoc#IGovernor-ProposalCanceled-uint256- +:xref-IGovernor-VoteCast-address-uint256-uint8-uint256-string-: xref:governance.adoc#IGovernor-VoteCast-address-uint256-uint8-uint256-string- +:xref-IGovernor-VoteCastWithParams-address-uint256-uint8-uint256-string-bytes-: xref:governance.adoc#IGovernor-VoteCastWithParams-address-uint256-uint8-uint256-string-bytes- +:xref-IERC5267-EIP712DomainChanged--: xref:interfaces.adoc#IERC5267-EIP712DomainChanged-- +:xref-IGovernor-GovernorInvalidProposalLength-uint256-uint256-uint256-: xref:governance.adoc#IGovernor-GovernorInvalidProposalLength-uint256-uint256-uint256- +:xref-IGovernor-GovernorAlreadyCastVote-address-: xref:governance.adoc#IGovernor-GovernorAlreadyCastVote-address- +:xref-IGovernor-GovernorDisabledDeposit--: xref:governance.adoc#IGovernor-GovernorDisabledDeposit-- +:xref-IGovernor-GovernorOnlyProposer-address-: xref:governance.adoc#IGovernor-GovernorOnlyProposer-address- +:xref-IGovernor-GovernorOnlyExecutor-address-: xref:governance.adoc#IGovernor-GovernorOnlyExecutor-address- +:xref-IGovernor-GovernorNonexistentProposal-uint256-: xref:governance.adoc#IGovernor-GovernorNonexistentProposal-uint256- +:xref-IGovernor-GovernorUnexpectedProposalState-uint256-enum-IGovernor-ProposalState-bytes32-: xref:governance.adoc#IGovernor-GovernorUnexpectedProposalState-uint256-enum-IGovernor-ProposalState-bytes32- +:xref-IGovernor-GovernorInvalidVotingPeriod-uint256-: xref:governance.adoc#IGovernor-GovernorInvalidVotingPeriod-uint256- +:xref-IGovernor-GovernorInsufficientProposerVotes-address-uint256-uint256-: xref:governance.adoc#IGovernor-GovernorInsufficientProposerVotes-address-uint256-uint256- +:xref-IGovernor-GovernorRestrictedProposer-address-: xref:governance.adoc#IGovernor-GovernorRestrictedProposer-address- +:xref-IGovernor-GovernorInvalidVoteType--: xref:governance.adoc#IGovernor-GovernorInvalidVoteType-- +:xref-IGovernor-GovernorQueueNotImplemented--: xref:governance.adoc#IGovernor-GovernorQueueNotImplemented-- +:xref-IGovernor-GovernorNotQueuedProposal-uint256-: xref:governance.adoc#IGovernor-GovernorNotQueuedProposal-uint256- +:xref-IGovernor-GovernorAlreadyQueuedProposal-uint256-: xref:governance.adoc#IGovernor-GovernorAlreadyQueuedProposal-uint256- +:xref-IGovernor-GovernorInvalidSignature-address-: xref:governance.adoc#IGovernor-GovernorInvalidSignature-address- +:xref-Nonces-InvalidAccountNonce-address-uint256-: xref:utils.adoc#Nonces-InvalidAccountNonce-address-uint256- +:IGovernor-execute: pass:normal[xref:governance.adoc#IGovernor-execute-address---uint256---bytes---bytes32-[`IGovernor.execute`]] +:IGovernor-cancel: pass:normal[xref:governance.adoc#IGovernor-cancel-address---uint256---bytes---bytes32-[`IGovernor.cancel`]] +:ERC721Votes: pass:normal[xref:token/ERC721.adoc#ERC721Votes[`ERC721Votes`]] +:ERC721-balanceOf: pass:normal[xref:token/ERC721.adoc#ERC721-balanceOf-address-[`ERC721.balanceOf`]] +:xref-Votes-clock--: xref:governance.adoc#Votes-clock-- +:xref-Votes-CLOCK_MODE--: xref:governance.adoc#Votes-CLOCK_MODE-- +:xref-Votes-getVotes-address-: xref:governance.adoc#Votes-getVotes-address- +:xref-Votes-getPastVotes-address-uint256-: xref:governance.adoc#Votes-getPastVotes-address-uint256- +:xref-Votes-getPastTotalSupply-uint256-: xref:governance.adoc#Votes-getPastTotalSupply-uint256- +:xref-Votes-_getTotalSupply--: xref:governance.adoc#Votes-_getTotalSupply-- +:xref-Votes-delegates-address-: xref:governance.adoc#Votes-delegates-address- +:xref-Votes-delegate-address-: xref:governance.adoc#Votes-delegate-address- +:xref-Votes-delegateBySig-address-uint256-uint256-uint8-bytes32-bytes32-: xref:governance.adoc#Votes-delegateBySig-address-uint256-uint256-uint8-bytes32-bytes32- +:xref-Votes-_delegate-address-address-: xref:governance.adoc#Votes-_delegate-address-address- +:xref-Votes-_transferVotingUnits-address-address-uint256-: xref:governance.adoc#Votes-_transferVotingUnits-address-address-uint256- +:xref-Votes-_numCheckpoints-address-: xref:governance.adoc#Votes-_numCheckpoints-address- +:xref-Votes-_checkpoints-address-uint32-: xref:governance.adoc#Votes-_checkpoints-address-uint32- +:xref-Votes-_getVotingUnits-address-: xref:governance.adoc#Votes-_getVotingUnits-address- +:xref-Nonces-nonces-address-: xref:utils.adoc#Nonces-nonces-address- +:xref-Nonces-_useNonce-address-: xref:utils.adoc#Nonces-_useNonce-address- +:xref-Nonces-_useCheckedNonce-address-uint256-: xref:utils.adoc#Nonces-_useCheckedNonce-address-uint256- +:xref-EIP712-_domainSeparatorV4--: xref:utils.adoc#EIP712-_domainSeparatorV4-- +:xref-EIP712-_hashTypedDataV4-bytes32-: xref:utils.adoc#EIP712-_hashTypedDataV4-bytes32- +:xref-EIP712-eip712Domain--: xref:utils.adoc#EIP712-eip712Domain-- +:xref-EIP712-_EIP712Name--: xref:utils.adoc#EIP712-_EIP712Name-- +:xref-EIP712-_EIP712Version--: xref:utils.adoc#EIP712-_EIP712Version-- +:xref-IVotes-DelegateChanged-address-address-address-: xref:governance.adoc#IVotes-DelegateChanged-address-address-address- +:xref-IVotes-DelegateVotesChanged-address-uint256-uint256-: xref:governance.adoc#IVotes-DelegateVotesChanged-address-uint256-uint256- +:xref-IERC5267-EIP712DomainChanged--: xref:interfaces.adoc#IERC5267-EIP712DomainChanged-- +:xref-Votes-ERC6372InconsistentClock--: xref:governance.adoc#Votes-ERC6372InconsistentClock-- +:xref-Votes-ERC5805FutureLookup-uint256-uint48-: xref:governance.adoc#Votes-ERC5805FutureLookup-uint256-uint48- +:xref-IVotes-VotesExpiredSignature-uint256-: xref:governance.adoc#IVotes-VotesExpiredSignature-uint256- +:xref-Nonces-InvalidAccountNonce-address-uint256-: xref:utils.adoc#Nonces-InvalidAccountNonce-address-uint256- +:IVotes-DelegateChanged: pass:normal[xref:governance.adoc#IVotes-DelegateChanged-address-address-address-[`IVotes.DelegateChanged`]] +:IVotes-DelegateVotesChanged: pass:normal[xref:governance.adoc#IVotes-DelegateVotesChanged-address-uint256-uint256-[`IVotes.DelegateVotesChanged`]] +:TimelockController: pass:normal[xref:governance.adoc#TimelockController[`TimelockController`]] +:Governor: pass:normal[xref:governance.adoc#Governor[`Governor`]] +:TimelockController: pass:normal[xref:governance.adoc#TimelockController[`TimelockController`]] +:xref-TimelockController-onlyRoleOrOpenRole-bytes32-: xref:governance.adoc#TimelockController-onlyRoleOrOpenRole-bytes32- +:xref-TimelockController-constructor-uint256-address---address---address-: xref:governance.adoc#TimelockController-constructor-uint256-address---address---address- +:xref-TimelockController-receive--: xref:governance.adoc#TimelockController-receive-- +:xref-TimelockController-supportsInterface-bytes4-: xref:governance.adoc#TimelockController-supportsInterface-bytes4- +:xref-TimelockController-isOperation-bytes32-: xref:governance.adoc#TimelockController-isOperation-bytes32- +:xref-TimelockController-isOperationPending-bytes32-: xref:governance.adoc#TimelockController-isOperationPending-bytes32- +:xref-TimelockController-isOperationReady-bytes32-: xref:governance.adoc#TimelockController-isOperationReady-bytes32- +:xref-TimelockController-isOperationDone-bytes32-: xref:governance.adoc#TimelockController-isOperationDone-bytes32- +:xref-TimelockController-getTimestamp-bytes32-: xref:governance.adoc#TimelockController-getTimestamp-bytes32- +:xref-TimelockController-getOperationState-bytes32-: xref:governance.adoc#TimelockController-getOperationState-bytes32- +:xref-TimelockController-getMinDelay--: xref:governance.adoc#TimelockController-getMinDelay-- +:xref-TimelockController-hashOperation-address-uint256-bytes-bytes32-bytes32-: xref:governance.adoc#TimelockController-hashOperation-address-uint256-bytes-bytes32-bytes32- +:xref-TimelockController-hashOperationBatch-address---uint256---bytes---bytes32-bytes32-: xref:governance.adoc#TimelockController-hashOperationBatch-address---uint256---bytes---bytes32-bytes32- +:xref-TimelockController-schedule-address-uint256-bytes-bytes32-bytes32-uint256-: xref:governance.adoc#TimelockController-schedule-address-uint256-bytes-bytes32-bytes32-uint256- +:xref-TimelockController-scheduleBatch-address---uint256---bytes---bytes32-bytes32-uint256-: xref:governance.adoc#TimelockController-scheduleBatch-address---uint256---bytes---bytes32-bytes32-uint256- +:xref-TimelockController-cancel-bytes32-: xref:governance.adoc#TimelockController-cancel-bytes32- +:xref-TimelockController-execute-address-uint256-bytes-bytes32-bytes32-: xref:governance.adoc#TimelockController-execute-address-uint256-bytes-bytes32-bytes32- +:xref-TimelockController-executeBatch-address---uint256---bytes---bytes32-bytes32-: xref:governance.adoc#TimelockController-executeBatch-address---uint256---bytes---bytes32-bytes32- +:xref-TimelockController-_execute-address-uint256-bytes-: xref:governance.adoc#TimelockController-_execute-address-uint256-bytes- +:xref-TimelockController-updateDelay-uint256-: xref:governance.adoc#TimelockController-updateDelay-uint256- +:xref-TimelockController-_encodeStateBitmap-enum-TimelockController-OperationState-: xref:governance.adoc#TimelockController-_encodeStateBitmap-enum-TimelockController-OperationState- +:xref-ERC1155Holder-onERC1155Received-address-address-uint256-uint256-bytes-: xref:token/ERC1155.adoc#ERC1155Holder-onERC1155Received-address-address-uint256-uint256-bytes- +:xref-ERC1155Holder-onERC1155BatchReceived-address-address-uint256---uint256---bytes-: xref:token/ERC1155.adoc#ERC1155Holder-onERC1155BatchReceived-address-address-uint256---uint256---bytes- +:xref-ERC721Holder-onERC721Received-address-address-uint256-bytes-: xref:token/ERC721.adoc#ERC721Holder-onERC721Received-address-address-uint256-bytes- +:xref-AccessControl-hasRole-bytes32-address-: xref:access.adoc#AccessControl-hasRole-bytes32-address- +:xref-AccessControl-_checkRole-bytes32-: xref:access.adoc#AccessControl-_checkRole-bytes32- +:xref-AccessControl-_checkRole-bytes32-address-: xref:access.adoc#AccessControl-_checkRole-bytes32-address- +:xref-AccessControl-getRoleAdmin-bytes32-: xref:access.adoc#AccessControl-getRoleAdmin-bytes32- +:xref-AccessControl-grantRole-bytes32-address-: xref:access.adoc#AccessControl-grantRole-bytes32-address- +:xref-AccessControl-revokeRole-bytes32-address-: xref:access.adoc#AccessControl-revokeRole-bytes32-address- +:xref-AccessControl-renounceRole-bytes32-address-: xref:access.adoc#AccessControl-renounceRole-bytes32-address- +:xref-AccessControl-_setRoleAdmin-bytes32-bytes32-: xref:access.adoc#AccessControl-_setRoleAdmin-bytes32-bytes32- +:xref-AccessControl-_grantRole-bytes32-address-: xref:access.adoc#AccessControl-_grantRole-bytes32-address- +:xref-AccessControl-_revokeRole-bytes32-address-: xref:access.adoc#AccessControl-_revokeRole-bytes32-address- +:xref-TimelockController-CallScheduled-bytes32-uint256-address-uint256-bytes-bytes32-uint256-: xref:governance.adoc#TimelockController-CallScheduled-bytes32-uint256-address-uint256-bytes-bytes32-uint256- +:xref-TimelockController-CallExecuted-bytes32-uint256-address-uint256-bytes-: xref:governance.adoc#TimelockController-CallExecuted-bytes32-uint256-address-uint256-bytes- +:xref-TimelockController-CallSalt-bytes32-bytes32-: xref:governance.adoc#TimelockController-CallSalt-bytes32-bytes32- +:xref-TimelockController-Cancelled-bytes32-: xref:governance.adoc#TimelockController-Cancelled-bytes32- +:xref-TimelockController-MinDelayChange-uint256-uint256-: xref:governance.adoc#TimelockController-MinDelayChange-uint256-uint256- +:xref-IAccessControl-RoleAdminChanged-bytes32-bytes32-bytes32-: xref:access.adoc#IAccessControl-RoleAdminChanged-bytes32-bytes32-bytes32- +:xref-IAccessControl-RoleGranted-bytes32-address-address-: xref:access.adoc#IAccessControl-RoleGranted-bytes32-address-address- +:xref-IAccessControl-RoleRevoked-bytes32-address-address-: xref:access.adoc#IAccessControl-RoleRevoked-bytes32-address-address- +:xref-TimelockController-TimelockInvalidOperationLength-uint256-uint256-uint256-: xref:governance.adoc#TimelockController-TimelockInvalidOperationLength-uint256-uint256-uint256- +:xref-TimelockController-TimelockInsufficientDelay-uint256-uint256-: xref:governance.adoc#TimelockController-TimelockInsufficientDelay-uint256-uint256- +:xref-TimelockController-TimelockUnexpectedOperationState-bytes32-bytes32-: xref:governance.adoc#TimelockController-TimelockUnexpectedOperationState-bytes32-bytes32- +:xref-TimelockController-TimelockUnexecutedPredecessor-bytes32-: xref:governance.adoc#TimelockController-TimelockUnexecutedPredecessor-bytes32- +:xref-TimelockController-TimelockUnauthorizedCaller-address-: xref:governance.adoc#TimelockController-TimelockUnauthorizedCaller-address- +:xref-IAccessControl-AccessControlUnauthorizedAccount-address-bytes32-: xref:access.adoc#IAccessControl-AccessControlUnauthorizedAccount-address-bytes32- +:xref-IAccessControl-AccessControlBadConfirmation--: xref:access.adoc#IAccessControl-AccessControlBadConfirmation-- +:IERC165-supportsInterface: pass:normal[xref:utils.adoc#IERC165-supportsInterface-bytes4-[`IERC165.supportsInterface`]] +:AccessControl: pass:normal[xref:access.adoc#AccessControl[`AccessControl`]] += Governance + +[.readme-notice] +NOTE: This document is better viewed at https://docs.openzeppelin.com/contracts/api/governance + +This directory includes primitives for on-chain governance. + +== Governor + +This modular system of Governor contracts allows the deployment on-chain voting protocols similar to https://compound.finance/docs/governance[Compound's Governor Alpha & Bravo] and beyond, through the ability to easily customize multiple aspects of the protocol. + +[TIP] +==== +For a guided experience, set up your Governor contract using https://wizard.openzeppelin.com/#governor[Contracts Wizard]. + +For a written walkthrough, check out our guide on xref:ROOT:governance.adoc[How to set up on-chain governance]. +==== + +* {Governor}: The core contract that contains all the logic and primitives. It is abstract and requires choosing one of each of the modules below, or custom ones. + +Votes modules determine the source of voting power, and sometimes quorum number. + +* {GovernorVotes}: Extracts voting weight from an {ERC20Votes}, or since v4.5 an {ERC721Votes} token. + +* {GovernorVotesQuorumFraction}: Combines with `GovernorVotes` to set the quorum as a fraction of the total token supply. + +Counting modules determine valid voting options. + +* {GovernorCountingSimple}: Simple voting mechanism with 3 voting options: Against, For and Abstain. + +Timelock extensions add a delay for governance decisions to be executed. The workflow is extended to require a `queue` step before execution. With these modules, proposals are executed by the external timelock contract, thus it is the timelock that has to hold the assets that are being governed. + +* {GovernorTimelockControl}: Connects with an instance of {TimelockController}. Allows multiple proposers and executors, in addition to the Governor itself. + +* {GovernorTimelockCompound}: Connects with an instance of Compound's https://github.com/compound-finance/compound-protocol/blob/master/contracts/Timelock.sol[`Timelock`] contract. + +Other extensions can customize the behavior or interface in multiple ways. + +* {GovernorStorage}: Stores the proposal details onchain and provides enumerability of the proposals. This can be useful for some L2 chains where storage is cheap compared to calldata. + +* {GovernorSettings}: Manages some of the settings (voting delay, voting period duration, and proposal threshold) in a way that can be updated through a governance proposal, without requiring an upgrade. + +* {GovernorPreventLateQuorum}: Ensures there is a minimum voting period after quorum is reached as a security protection against large voters. + +In addition to modules and extensions, the core contract requires a few virtual functions to be implemented to your particular specifications: + +* <>: Delay (in EIP-6372 clock) since the proposal is submitted until voting power is fixed and voting starts. This can be used to enforce a delay after a proposal is published for users to buy tokens, or delegate their votes. +* <>: Delay (in EIP-6372 clock) since the proposal starts until voting ends. +* <>: Quorum required for a proposal to be successful. This function includes a `timepoint` argument (see EIP-6372) so the quorum can adapt through time, for example, to follow a token's `totalSupply`. + +NOTE: Functions of the `Governor` contract do not include access control. If you want to restrict access, you should add these checks by overloading the particular functions. Among these, {Governor-_cancel} is internal by default, and you will have to expose it (with the right access control mechanism) yourself if this function is needed. + +=== Core + +:ProposalState: pass:normal[xref:#IGovernor-ProposalState[`++ProposalState++`]] +:GovernorInvalidProposalLength: pass:normal[xref:#IGovernor-GovernorInvalidProposalLength-uint256-uint256-uint256-[`++GovernorInvalidProposalLength++`]] +:GovernorAlreadyCastVote: pass:normal[xref:#IGovernor-GovernorAlreadyCastVote-address-[`++GovernorAlreadyCastVote++`]] +:GovernorDisabledDeposit: pass:normal[xref:#IGovernor-GovernorDisabledDeposit--[`++GovernorDisabledDeposit++`]] +:GovernorOnlyProposer: pass:normal[xref:#IGovernor-GovernorOnlyProposer-address-[`++GovernorOnlyProposer++`]] +:GovernorOnlyExecutor: pass:normal[xref:#IGovernor-GovernorOnlyExecutor-address-[`++GovernorOnlyExecutor++`]] +:GovernorNonexistentProposal: pass:normal[xref:#IGovernor-GovernorNonexistentProposal-uint256-[`++GovernorNonexistentProposal++`]] +:GovernorUnexpectedProposalState: pass:normal[xref:#IGovernor-GovernorUnexpectedProposalState-uint256-enum-IGovernor-ProposalState-bytes32-[`++GovernorUnexpectedProposalState++`]] +:GovernorInvalidVotingPeriod: pass:normal[xref:#IGovernor-GovernorInvalidVotingPeriod-uint256-[`++GovernorInvalidVotingPeriod++`]] +:GovernorInsufficientProposerVotes: pass:normal[xref:#IGovernor-GovernorInsufficientProposerVotes-address-uint256-uint256-[`++GovernorInsufficientProposerVotes++`]] +:GovernorRestrictedProposer: pass:normal[xref:#IGovernor-GovernorRestrictedProposer-address-[`++GovernorRestrictedProposer++`]] +:GovernorInvalidVoteType: pass:normal[xref:#IGovernor-GovernorInvalidVoteType--[`++GovernorInvalidVoteType++`]] +:GovernorQueueNotImplemented: pass:normal[xref:#IGovernor-GovernorQueueNotImplemented--[`++GovernorQueueNotImplemented++`]] +:GovernorNotQueuedProposal: pass:normal[xref:#IGovernor-GovernorNotQueuedProposal-uint256-[`++GovernorNotQueuedProposal++`]] +:GovernorAlreadyQueuedProposal: pass:normal[xref:#IGovernor-GovernorAlreadyQueuedProposal-uint256-[`++GovernorAlreadyQueuedProposal++`]] +:GovernorInvalidSignature: pass:normal[xref:#IGovernor-GovernorInvalidSignature-address-[`++GovernorInvalidSignature++`]] +:ProposalCreated: pass:normal[xref:#IGovernor-ProposalCreated-uint256-address-address---uint256---string---bytes---uint256-uint256-string-[`++ProposalCreated++`]] +:ProposalQueued: pass:normal[xref:#IGovernor-ProposalQueued-uint256-uint256-[`++ProposalQueued++`]] +:ProposalExecuted: pass:normal[xref:#IGovernor-ProposalExecuted-uint256-[`++ProposalExecuted++`]] +:ProposalCanceled: pass:normal[xref:#IGovernor-ProposalCanceled-uint256-[`++ProposalCanceled++`]] +:VoteCast: pass:normal[xref:#IGovernor-VoteCast-address-uint256-uint8-uint256-string-[`++VoteCast++`]] +:VoteCastWithParams: pass:normal[xref:#IGovernor-VoteCastWithParams-address-uint256-uint8-uint256-string-bytes-[`++VoteCastWithParams++`]] +:name: pass:normal[xref:#IGovernor-name--[`++name++`]] +:version: pass:normal[xref:#IGovernor-version--[`++version++`]] +:COUNTING_MODE: pass:normal[xref:#IGovernor-COUNTING_MODE--[`++COUNTING_MODE++`]] +:hashProposal: pass:normal[xref:#IGovernor-hashProposal-address---uint256---bytes---bytes32-[`++hashProposal++`]] +:state: pass:normal[xref:#IGovernor-state-uint256-[`++state++`]] +:proposalThreshold: pass:normal[xref:#IGovernor-proposalThreshold--[`++proposalThreshold++`]] +:proposalSnapshot: pass:normal[xref:#IGovernor-proposalSnapshot-uint256-[`++proposalSnapshot++`]] +:proposalDeadline: pass:normal[xref:#IGovernor-proposalDeadline-uint256-[`++proposalDeadline++`]] +:proposalProposer: pass:normal[xref:#IGovernor-proposalProposer-uint256-[`++proposalProposer++`]] +:proposalEta: pass:normal[xref:#IGovernor-proposalEta-uint256-[`++proposalEta++`]] +:proposalNeedsQueuing: pass:normal[xref:#IGovernor-proposalNeedsQueuing-uint256-[`++proposalNeedsQueuing++`]] +:votingDelay: pass:normal[xref:#IGovernor-votingDelay--[`++votingDelay++`]] +:votingPeriod: pass:normal[xref:#IGovernor-votingPeriod--[`++votingPeriod++`]] +:quorum: pass:normal[xref:#IGovernor-quorum-uint256-[`++quorum++`]] +:getVotes: pass:normal[xref:#IGovernor-getVotes-address-uint256-[`++getVotes++`]] +:getVotesWithParams: pass:normal[xref:#IGovernor-getVotesWithParams-address-uint256-bytes-[`++getVotesWithParams++`]] +:hasVoted: pass:normal[xref:#IGovernor-hasVoted-uint256-address-[`++hasVoted++`]] +:propose: pass:normal[xref:#IGovernor-propose-address---uint256---bytes---string-[`++propose++`]] +:queue: pass:normal[xref:#IGovernor-queue-address---uint256---bytes---bytes32-[`++queue++`]] +:execute: pass:normal[xref:#IGovernor-execute-address---uint256---bytes---bytes32-[`++execute++`]] +:cancel: pass:normal[xref:#IGovernor-cancel-address---uint256---bytes---bytes32-[`++cancel++`]] +:castVote: pass:normal[xref:#IGovernor-castVote-uint256-uint8-[`++castVote++`]] +:castVoteWithReason: pass:normal[xref:#IGovernor-castVoteWithReason-uint256-uint8-string-[`++castVoteWithReason++`]] +:castVoteWithReasonAndParams: pass:normal[xref:#IGovernor-castVoteWithReasonAndParams-uint256-uint8-string-bytes-[`++castVoteWithReasonAndParams++`]] +:castVoteBySig: pass:normal[xref:#IGovernor-castVoteBySig-uint256-uint8-address-bytes-[`++castVoteBySig++`]] +:castVoteWithReasonAndParamsBySig: pass:normal[xref:#IGovernor-castVoteWithReasonAndParamsBySig-uint256-uint8-address-string-bytes-bytes-[`++castVoteWithReasonAndParamsBySig++`]] + +[.contract] +[[IGovernor]] +=== `++IGovernor++` link:https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v5.0.0-rc.0/contracts/governance/IGovernor.sol[{github-icon},role=heading-link] + +[.hljs-theme-light.nopadding] +```solidity +import "@openzeppelin/contracts/governance/IGovernor.sol"; +``` + +Interface of the {Governor} core. + +[.contract-index] +.Functions +-- +* {xref-IGovernor-name--}[`++name()++`] +* {xref-IGovernor-version--}[`++version()++`] +* {xref-IGovernor-COUNTING_MODE--}[`++COUNTING_MODE()++`] +* {xref-IGovernor-hashProposal-address---uint256---bytes---bytes32-}[`++hashProposal(targets, values, calldatas, descriptionHash)++`] +* {xref-IGovernor-state-uint256-}[`++state(proposalId)++`] +* {xref-IGovernor-proposalThreshold--}[`++proposalThreshold()++`] +* {xref-IGovernor-proposalSnapshot-uint256-}[`++proposalSnapshot(proposalId)++`] +* {xref-IGovernor-proposalDeadline-uint256-}[`++proposalDeadline(proposalId)++`] +* {xref-IGovernor-proposalProposer-uint256-}[`++proposalProposer(proposalId)++`] +* {xref-IGovernor-proposalEta-uint256-}[`++proposalEta(proposalId)++`] +* {xref-IGovernor-proposalNeedsQueuing-uint256-}[`++proposalNeedsQueuing(proposalId)++`] +* {xref-IGovernor-votingDelay--}[`++votingDelay()++`] +* {xref-IGovernor-votingPeriod--}[`++votingPeriod()++`] +* {xref-IGovernor-quorum-uint256-}[`++quorum(timepoint)++`] +* {xref-IGovernor-getVotes-address-uint256-}[`++getVotes(account, timepoint)++`] +* {xref-IGovernor-getVotesWithParams-address-uint256-bytes-}[`++getVotesWithParams(account, timepoint, params)++`] +* {xref-IGovernor-hasVoted-uint256-address-}[`++hasVoted(proposalId, account)++`] +* {xref-IGovernor-propose-address---uint256---bytes---string-}[`++propose(targets, values, calldatas, description)++`] +* {xref-IGovernor-queue-address---uint256---bytes---bytes32-}[`++queue(targets, values, calldatas, descriptionHash)++`] +* {xref-IGovernor-execute-address---uint256---bytes---bytes32-}[`++execute(targets, values, calldatas, descriptionHash)++`] +* {xref-IGovernor-cancel-address---uint256---bytes---bytes32-}[`++cancel(targets, values, calldatas, descriptionHash)++`] +* {xref-IGovernor-castVote-uint256-uint8-}[`++castVote(proposalId, support)++`] +* {xref-IGovernor-castVoteWithReason-uint256-uint8-string-}[`++castVoteWithReason(proposalId, support, reason)++`] +* {xref-IGovernor-castVoteWithReasonAndParams-uint256-uint8-string-bytes-}[`++castVoteWithReasonAndParams(proposalId, support, reason, params)++`] +* {xref-IGovernor-castVoteBySig-uint256-uint8-address-bytes-}[`++castVoteBySig(proposalId, support, voter, signature)++`] +* {xref-IGovernor-castVoteWithReasonAndParamsBySig-uint256-uint8-address-string-bytes-bytes-}[`++castVoteWithReasonAndParamsBySig(proposalId, support, voter, reason, params, signature)++`] + +[.contract-subindex-inherited] +.IERC6372 +* {xref-IERC6372-clock--}[`++clock()++`] +* {xref-IERC6372-CLOCK_MODE--}[`++CLOCK_MODE()++`] + +[.contract-subindex-inherited] +.IERC165 +* {xref-IERC165-supportsInterface-bytes4-}[`++supportsInterface(interfaceId)++`] + +-- + +[.contract-index] +.Events +-- +* {xref-IGovernor-ProposalCreated-uint256-address-address---uint256---string---bytes---uint256-uint256-string-}[`++ProposalCreated(proposalId, proposer, targets, values, signatures, calldatas, voteStart, voteEnd, description)++`] +* {xref-IGovernor-ProposalQueued-uint256-uint256-}[`++ProposalQueued(proposalId, etaSeconds)++`] +* {xref-IGovernor-ProposalExecuted-uint256-}[`++ProposalExecuted(proposalId)++`] +* {xref-IGovernor-ProposalCanceled-uint256-}[`++ProposalCanceled(proposalId)++`] +* {xref-IGovernor-VoteCast-address-uint256-uint8-uint256-string-}[`++VoteCast(voter, proposalId, support, weight, reason)++`] +* {xref-IGovernor-VoteCastWithParams-address-uint256-uint8-uint256-string-bytes-}[`++VoteCastWithParams(voter, proposalId, support, weight, reason, params)++`] + +[.contract-subindex-inherited] +.IERC6372 + +[.contract-subindex-inherited] +.IERC165 + +-- + +[.contract-index] +.Errors +-- +* {xref-IGovernor-GovernorInvalidProposalLength-uint256-uint256-uint256-}[`++GovernorInvalidProposalLength(targets, calldatas, values)++`] +* {xref-IGovernor-GovernorAlreadyCastVote-address-}[`++GovernorAlreadyCastVote(voter)++`] +* {xref-IGovernor-GovernorDisabledDeposit--}[`++GovernorDisabledDeposit()++`] +* {xref-IGovernor-GovernorOnlyProposer-address-}[`++GovernorOnlyProposer(account)++`] +* {xref-IGovernor-GovernorOnlyExecutor-address-}[`++GovernorOnlyExecutor(account)++`] +* {xref-IGovernor-GovernorNonexistentProposal-uint256-}[`++GovernorNonexistentProposal(proposalId)++`] +* {xref-IGovernor-GovernorUnexpectedProposalState-uint256-enum-IGovernor-ProposalState-bytes32-}[`++GovernorUnexpectedProposalState(proposalId, current, expectedStates)++`] +* {xref-IGovernor-GovernorInvalidVotingPeriod-uint256-}[`++GovernorInvalidVotingPeriod(votingPeriod)++`] +* {xref-IGovernor-GovernorInsufficientProposerVotes-address-uint256-uint256-}[`++GovernorInsufficientProposerVotes(proposer, votes, threshold)++`] +* {xref-IGovernor-GovernorRestrictedProposer-address-}[`++GovernorRestrictedProposer(proposer)++`] +* {xref-IGovernor-GovernorInvalidVoteType--}[`++GovernorInvalidVoteType()++`] +* {xref-IGovernor-GovernorQueueNotImplemented--}[`++GovernorQueueNotImplemented()++`] +* {xref-IGovernor-GovernorNotQueuedProposal-uint256-}[`++GovernorNotQueuedProposal(proposalId)++`] +* {xref-IGovernor-GovernorAlreadyQueuedProposal-uint256-}[`++GovernorAlreadyQueuedProposal(proposalId)++`] +* {xref-IGovernor-GovernorInvalidSignature-address-}[`++GovernorInvalidSignature(voter)++`] + +[.contract-subindex-inherited] +.IERC6372 + +[.contract-subindex-inherited] +.IERC165 + +-- + +[.contract-item] +[[IGovernor-name--]] +==== `[.contract-item-name]#++name++#++() → string++` [.item-kind]#external# + +Name of the governor instance (used in building the ERC712 domain separator). + +[.contract-item] +[[IGovernor-version--]] +==== `[.contract-item-name]#++version++#++() → string++` [.item-kind]#external# + +Version of the governor instance (used in building the ERC712 domain separator). Default: "1" + +[.contract-item] +[[IGovernor-COUNTING_MODE--]] +==== `[.contract-item-name]#++COUNTING_MODE++#++() → string++` [.item-kind]#external# + +A description of the possible `support` values for {castVote} and the way these votes are counted, meant to +be consumed by UIs to show correct vote options and interpret the results. The string is a URL-encoded sequence of +key-value pairs that each describe one aspect, for example `support=bravo&quorum=for,abstain`. + +There are 2 standard keys: `support` and `quorum`. + +- `support=bravo` refers to the vote options 0 = Against, 1 = For, 2 = Abstain, as in `GovernorBravo`. +- `quorum=bravo` means that only For votes are counted towards quorum. +- `quorum=for,abstain` means that both For and Abstain votes are counted towards quorum. + +If a counting module makes use of encoded `params`, it should include this under a `params` key with a unique +name that describes the behavior. For example: + +- `params=fractional` might refer to a scheme where votes are divided fractionally between for/against/abstain. +- `params=erc721` might refer to a scheme where specific NFTs are delegated to vote. + +NOTE: The string can be decoded by the standard +https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams[`URLSearchParams`] +JavaScript class. + +[.contract-item] +[[IGovernor-hashProposal-address---uint256---bytes---bytes32-]] +==== `[.contract-item-name]#++hashProposal++#++(address[] targets, uint256[] values, bytes[] calldatas, bytes32 descriptionHash) → uint256++` [.item-kind]#external# + +Hashing function used to (re)build the proposal id from the proposal details.. + +[.contract-item] +[[IGovernor-state-uint256-]] +==== `[.contract-item-name]#++state++#++(uint256 proposalId) → enum IGovernor.ProposalState++` [.item-kind]#external# + +Current state of a proposal, following Compound's convention + +[.contract-item] +[[IGovernor-proposalThreshold--]] +==== `[.contract-item-name]#++proposalThreshold++#++() → uint256++` [.item-kind]#external# + +The number of votes required in order for a voter to become a proposer. + +[.contract-item] +[[IGovernor-proposalSnapshot-uint256-]] +==== `[.contract-item-name]#++proposalSnapshot++#++(uint256 proposalId) → uint256++` [.item-kind]#external# + +Timepoint used to retrieve user's votes and quorum. If using block number (as per Compound's Comp), the +snapshot is performed at the end of this block. Hence, voting for this proposal starts at the beginning of the +following block. + +[.contract-item] +[[IGovernor-proposalDeadline-uint256-]] +==== `[.contract-item-name]#++proposalDeadline++#++(uint256 proposalId) → uint256++` [.item-kind]#external# + +Timepoint at which votes close. If using block number, votes close at the end of this block, so it is +possible to cast a vote during this block. + +[.contract-item] +[[IGovernor-proposalProposer-uint256-]] +==== `[.contract-item-name]#++proposalProposer++#++(uint256 proposalId) → address++` [.item-kind]#external# + +The account that created a proposal. + +[.contract-item] +[[IGovernor-proposalEta-uint256-]] +==== `[.contract-item-name]#++proposalEta++#++(uint256 proposalId) → uint256++` [.item-kind]#external# + +The time when a queued proposal becomes executable ("ETA"). Unlike {proposalSnapshot} and +{proposalDeadline}, this doesn't use the governor clock, and instead relies on the executor's clock which may be +different. In most cases this will be a timestamp. + +[.contract-item] +[[IGovernor-proposalNeedsQueuing-uint256-]] +==== `[.contract-item-name]#++proposalNeedsQueuing++#++(uint256 proposalId) → bool++` [.item-kind]#external# + +Whether a proposal needs to be queued before execution. + +[.contract-item] +[[IGovernor-votingDelay--]] +==== `[.contract-item-name]#++votingDelay++#++() → uint256++` [.item-kind]#external# + +Delay, between the proposal is created and the vote starts. The unit this duration is expressed in depends +on the clock (see EIP-6372) this contract uses. + +This can be increased to leave time for users to buy voting power, or delegate it, before the voting of a +proposal starts. + +NOTE: While this interface returns a uint256, timepoints are stored as uint48 following the ERC-6372 clock type. +Consequently this value must fit in a uint48 (when added to the current clock). See {IERC6372-clock}. + +[.contract-item] +[[IGovernor-votingPeriod--]] +==== `[.contract-item-name]#++votingPeriod++#++() → uint256++` [.item-kind]#external# + +Delay between the vote start and vote end. The unit this duration is expressed in depends on the clock +(see EIP-6372) this contract uses. + +NOTE: The {votingDelay} can delay the start of the vote. This must be considered when setting the voting +duration compared to the voting delay. + +NOTE: This value is stored when the proposal is submitted so that possible changes to the value do not affect +proposals that have already been submitted. The type used to save it is a uint32. Consequently, while this +interface returns a uint256, the value it returns should fit in a uint32. + +[.contract-item] +[[IGovernor-quorum-uint256-]] +==== `[.contract-item-name]#++quorum++#++(uint256 timepoint) → uint256++` [.item-kind]#external# + +Minimum number of cast voted required for a proposal to be successful. + +NOTE: The `timepoint` parameter corresponds to the snapshot used for counting vote. This allows to scale the +quorum depending on values such as the totalSupply of a token at this timepoint (see {ERC20Votes}). + +[.contract-item] +[[IGovernor-getVotes-address-uint256-]] +==== `[.contract-item-name]#++getVotes++#++(address account, uint256 timepoint) → uint256++` [.item-kind]#external# + +Voting power of an `account` at a specific `timepoint`. + +Note: this can be implemented in a number of ways, for example by reading the delegated balance from one (or +multiple), {ERC20Votes} tokens. + +[.contract-item] +[[IGovernor-getVotesWithParams-address-uint256-bytes-]] +==== `[.contract-item-name]#++getVotesWithParams++#++(address account, uint256 timepoint, bytes params) → uint256++` [.item-kind]#external# + +Voting power of an `account` at a specific `timepoint` given additional encoded parameters. + +[.contract-item] +[[IGovernor-hasVoted-uint256-address-]] +==== `[.contract-item-name]#++hasVoted++#++(uint256 proposalId, address account) → bool++` [.item-kind]#external# + +Returns whether `account` has cast a vote on `proposalId`. + +[.contract-item] +[[IGovernor-propose-address---uint256---bytes---string-]] +==== `[.contract-item-name]#++propose++#++(address[] targets, uint256[] values, bytes[] calldatas, string description) → uint256 proposalId++` [.item-kind]#external# + +Create a new proposal. Vote start after a delay specified by {IGovernor-votingDelay} and lasts for a +duration specified by {IGovernor-votingPeriod}. + +Emits a {ProposalCreated} event. + +[.contract-item] +[[IGovernor-queue-address---uint256---bytes---bytes32-]] +==== `[.contract-item-name]#++queue++#++(address[] targets, uint256[] values, bytes[] calldatas, bytes32 descriptionHash) → uint256 proposalId++` [.item-kind]#external# + +Queue a proposal. Some governors require this step to be performed before execution can happen. If queuing +is not necessary, this function may revert. +Queuing a proposal requires the quorum to be reached, the vote to be successful, and the deadline to be reached. + +Emits a {ProposalQueued} event. + +[.contract-item] +[[IGovernor-execute-address---uint256---bytes---bytes32-]] +==== `[.contract-item-name]#++execute++#++(address[] targets, uint256[] values, bytes[] calldatas, bytes32 descriptionHash) → uint256 proposalId++` [.item-kind]#external# + +Execute a successful proposal. This requires the quorum to be reached, the vote to be successful, and the +deadline to be reached. Depending on the governor it might also be required that the proposal was queued and +that some delay passed. + +Emits a {ProposalExecuted} event. + +NOTE: Some modules can modify the requirements for execution, for example by adding an additional timelock. + +[.contract-item] +[[IGovernor-cancel-address---uint256---bytes---bytes32-]] +==== `[.contract-item-name]#++cancel++#++(address[] targets, uint256[] values, bytes[] calldatas, bytes32 descriptionHash) → uint256 proposalId++` [.item-kind]#external# + +Cancel a proposal. A proposal is cancellable by the proposer, but only while it is Pending state, i.e. +before the vote starts. + +Emits a {ProposalCanceled} event. + +[.contract-item] +[[IGovernor-castVote-uint256-uint8-]] +==== `[.contract-item-name]#++castVote++#++(uint256 proposalId, uint8 support) → uint256 balance++` [.item-kind]#external# + +Cast a vote + +Emits a {VoteCast} event. + +[.contract-item] +[[IGovernor-castVoteWithReason-uint256-uint8-string-]] +==== `[.contract-item-name]#++castVoteWithReason++#++(uint256 proposalId, uint8 support, string reason) → uint256 balance++` [.item-kind]#external# + +Cast a vote with a reason + +Emits a {VoteCast} event. + +[.contract-item] +[[IGovernor-castVoteWithReasonAndParams-uint256-uint8-string-bytes-]] +==== `[.contract-item-name]#++castVoteWithReasonAndParams++#++(uint256 proposalId, uint8 support, string reason, bytes params) → uint256 balance++` [.item-kind]#external# + +Cast a vote with a reason and additional encoded parameters + +Emits a {VoteCast} or {VoteCastWithParams} event depending on the length of params. + +[.contract-item] +[[IGovernor-castVoteBySig-uint256-uint8-address-bytes-]] +==== `[.contract-item-name]#++castVoteBySig++#++(uint256 proposalId, uint8 support, address voter, bytes signature) → uint256 balance++` [.item-kind]#external# + +Cast a vote using the voter's signature, including ERC-1271 signature support. + +Emits a {VoteCast} event. + +[.contract-item] +[[IGovernor-castVoteWithReasonAndParamsBySig-uint256-uint8-address-string-bytes-bytes-]] +==== `[.contract-item-name]#++castVoteWithReasonAndParamsBySig++#++(uint256 proposalId, uint8 support, address voter, string reason, bytes params, bytes signature) → uint256 balance++` [.item-kind]#external# + +Cast a vote with a reason and additional encoded parameters using the voter's signature, +including ERC-1271 signature support. + +Emits a {VoteCast} or {VoteCastWithParams} event depending on the length of params. + +[.contract-item] +[[IGovernor-ProposalCreated-uint256-address-address---uint256---string---bytes---uint256-uint256-string-]] +==== `[.contract-item-name]#++ProposalCreated++#++(uint256 proposalId, address proposer, address[] targets, uint256[] values, string[] signatures, bytes[] calldatas, uint256 voteStart, uint256 voteEnd, string description)++` [.item-kind]#event# + +Emitted when a proposal is created. + +[.contract-item] +[[IGovernor-ProposalQueued-uint256-uint256-]] +==== `[.contract-item-name]#++ProposalQueued++#++(uint256 proposalId, uint256 etaSeconds)++` [.item-kind]#event# + +Emitted when a proposal is queued. + +[.contract-item] +[[IGovernor-ProposalExecuted-uint256-]] +==== `[.contract-item-name]#++ProposalExecuted++#++(uint256 proposalId)++` [.item-kind]#event# + +Emitted when a proposal is executed. + +[.contract-item] +[[IGovernor-ProposalCanceled-uint256-]] +==== `[.contract-item-name]#++ProposalCanceled++#++(uint256 proposalId)++` [.item-kind]#event# + +Emitted when a proposal is canceled. + +[.contract-item] +[[IGovernor-VoteCast-address-uint256-uint8-uint256-string-]] +==== `[.contract-item-name]#++VoteCast++#++(address indexed voter, uint256 proposalId, uint8 support, uint256 weight, string reason)++` [.item-kind]#event# + +Emitted when a vote is cast without params. + +Note: `support` values should be seen as buckets. Their interpretation depends on the voting module used. + +[.contract-item] +[[IGovernor-VoteCastWithParams-address-uint256-uint8-uint256-string-bytes-]] +==== `[.contract-item-name]#++VoteCastWithParams++#++(address indexed voter, uint256 proposalId, uint8 support, uint256 weight, string reason, bytes params)++` [.item-kind]#event# + +Emitted when a vote is cast with params. + +Note: `support` values should be seen as buckets. Their interpretation depends on the voting module used. +`params` are additional encoded parameters. Their interpepretation also depends on the voting module used. + +[.contract-item] +[[IGovernor-GovernorInvalidProposalLength-uint256-uint256-uint256-]] +==== `[.contract-item-name]#++GovernorInvalidProposalLength++#++(uint256 targets, uint256 calldatas, uint256 values)++` [.item-kind]#error# + +Empty proposal or a mismatch between the parameters length for a proposal call. + +[.contract-item] +[[IGovernor-GovernorAlreadyCastVote-address-]] +==== `[.contract-item-name]#++GovernorAlreadyCastVote++#++(address voter)++` [.item-kind]#error# + +The vote was already cast. + +[.contract-item] +[[IGovernor-GovernorDisabledDeposit--]] +==== `[.contract-item-name]#++GovernorDisabledDeposit++#++()++` [.item-kind]#error# + +Token deposits are disabled in this contract. + +[.contract-item] +[[IGovernor-GovernorOnlyProposer-address-]] +==== `[.contract-item-name]#++GovernorOnlyProposer++#++(address account)++` [.item-kind]#error# + +The `account` is not a proposer. + +[.contract-item] +[[IGovernor-GovernorOnlyExecutor-address-]] +==== `[.contract-item-name]#++GovernorOnlyExecutor++#++(address account)++` [.item-kind]#error# + +The `account` is not the governance executor. + +[.contract-item] +[[IGovernor-GovernorNonexistentProposal-uint256-]] +==== `[.contract-item-name]#++GovernorNonexistentProposal++#++(uint256 proposalId)++` [.item-kind]#error# + +The `proposalId` doesn't exist. + +[.contract-item] +[[IGovernor-GovernorUnexpectedProposalState-uint256-enum-IGovernor-ProposalState-bytes32-]] +==== `[.contract-item-name]#++GovernorUnexpectedProposalState++#++(uint256 proposalId, enum IGovernor.ProposalState current, bytes32 expectedStates)++` [.item-kind]#error# + +The current state of a proposal is not the required for performing an operation. +The `expectedStates` is a bitmap with the bits enabled for each ProposalState enum position +counting from right to left. + +NOTE: If `expectedState` is `bytes32(0)`, the proposal is expected to not be in any state (i.e. not exist). +This is the case when a proposal that is expected to be unset is already initiated (the proposal is duplicated). + +See {Governor-_encodeStateBitmap}. + +[.contract-item] +[[IGovernor-GovernorInvalidVotingPeriod-uint256-]] +==== `[.contract-item-name]#++GovernorInvalidVotingPeriod++#++(uint256 votingPeriod)++` [.item-kind]#error# + +The voting period set is not a valid period. + +[.contract-item] +[[IGovernor-GovernorInsufficientProposerVotes-address-uint256-uint256-]] +==== `[.contract-item-name]#++GovernorInsufficientProposerVotes++#++(address proposer, uint256 votes, uint256 threshold)++` [.item-kind]#error# + +The `proposer` does not have the required votes to create a proposal. + +[.contract-item] +[[IGovernor-GovernorRestrictedProposer-address-]] +==== `[.contract-item-name]#++GovernorRestrictedProposer++#++(address proposer)++` [.item-kind]#error# + +The `proposer` is not allowed to create a proposal. + +[.contract-item] +[[IGovernor-GovernorInvalidVoteType--]] +==== `[.contract-item-name]#++GovernorInvalidVoteType++#++()++` [.item-kind]#error# + +The vote type used is not valid for the corresponding counting module. + +[.contract-item] +[[IGovernor-GovernorQueueNotImplemented--]] +==== `[.contract-item-name]#++GovernorQueueNotImplemented++#++()++` [.item-kind]#error# + +Queue operation is not implemented for this governor. Execute should be called directly. + +[.contract-item] +[[IGovernor-GovernorNotQueuedProposal-uint256-]] +==== `[.contract-item-name]#++GovernorNotQueuedProposal++#++(uint256 proposalId)++` [.item-kind]#error# + +The proposal hasn't been queued yet. + +[.contract-item] +[[IGovernor-GovernorAlreadyQueuedProposal-uint256-]] +==== `[.contract-item-name]#++GovernorAlreadyQueuedProposal++#++(uint256 proposalId)++` [.item-kind]#error# + +The proposal has already been queued. + +[.contract-item] +[[IGovernor-GovernorInvalidSignature-address-]] +==== `[.contract-item-name]#++GovernorInvalidSignature++#++(address voter)++` [.item-kind]#error# + +The provided signature is not valid for the expected `voter`. +If the `voter` is a contract, the signature is not valid using {IERC1271-isValidSignature}. + +:BALLOT_TYPEHASH: pass:normal[xref:#Governor-BALLOT_TYPEHASH-bytes32[`++BALLOT_TYPEHASH++`]] +:EXTENDED_BALLOT_TYPEHASH: pass:normal[xref:#Governor-EXTENDED_BALLOT_TYPEHASH-bytes32[`++EXTENDED_BALLOT_TYPEHASH++`]] +:ProposalCore: pass:normal[xref:#Governor-ProposalCore[`++ProposalCore++`]] +:onlyGovernance: pass:normal[xref:#Governor-onlyGovernance--[`++onlyGovernance++`]] +:constructor: pass:normal[xref:#Governor-constructor-string-[`++constructor++`]] +:receive: pass:normal[xref:#Governor-receive--[`++receive++`]] +:supportsInterface: pass:normal[xref:#Governor-supportsInterface-bytes4-[`++supportsInterface++`]] +:name: pass:normal[xref:#Governor-name--[`++name++`]] +:version: pass:normal[xref:#Governor-version--[`++version++`]] +:hashProposal: pass:normal[xref:#Governor-hashProposal-address---uint256---bytes---bytes32-[`++hashProposal++`]] +:state: pass:normal[xref:#Governor-state-uint256-[`++state++`]] +:proposalThreshold: pass:normal[xref:#Governor-proposalThreshold--[`++proposalThreshold++`]] +:proposalSnapshot: pass:normal[xref:#Governor-proposalSnapshot-uint256-[`++proposalSnapshot++`]] +:proposalDeadline: pass:normal[xref:#Governor-proposalDeadline-uint256-[`++proposalDeadline++`]] +:proposalProposer: pass:normal[xref:#Governor-proposalProposer-uint256-[`++proposalProposer++`]] +:proposalEta: pass:normal[xref:#Governor-proposalEta-uint256-[`++proposalEta++`]] +:proposalNeedsQueuing: pass:normal[xref:#Governor-proposalNeedsQueuing-uint256-[`++proposalNeedsQueuing++`]] +:_checkGovernance: pass:normal[xref:#Governor-_checkGovernance--[`++_checkGovernance++`]] +:_quorumReached: pass:normal[xref:#Governor-_quorumReached-uint256-[`++_quorumReached++`]] +:_voteSucceeded: pass:normal[xref:#Governor-_voteSucceeded-uint256-[`++_voteSucceeded++`]] +:_getVotes: pass:normal[xref:#Governor-_getVotes-address-uint256-bytes-[`++_getVotes++`]] +:_countVote: pass:normal[xref:#Governor-_countVote-uint256-address-uint8-uint256-bytes-[`++_countVote++`]] +:_defaultParams: pass:normal[xref:#Governor-_defaultParams--[`++_defaultParams++`]] +:propose: pass:normal[xref:#Governor-propose-address---uint256---bytes---string-[`++propose++`]] +:_propose: pass:normal[xref:#Governor-_propose-address---uint256---bytes---string-address-[`++_propose++`]] +:queue: pass:normal[xref:#Governor-queue-address---uint256---bytes---bytes32-[`++queue++`]] +:_queueOperations: pass:normal[xref:#Governor-_queueOperations-uint256-address---uint256---bytes---bytes32-[`++_queueOperations++`]] +:execute: pass:normal[xref:#Governor-execute-address---uint256---bytes---bytes32-[`++execute++`]] +:_executeOperations: pass:normal[xref:#Governor-_executeOperations-uint256-address---uint256---bytes---bytes32-[`++_executeOperations++`]] +:cancel: pass:normal[xref:#Governor-cancel-address---uint256---bytes---bytes32-[`++cancel++`]] +:_cancel: pass:normal[xref:#Governor-_cancel-address---uint256---bytes---bytes32-[`++_cancel++`]] +:getVotes: pass:normal[xref:#Governor-getVotes-address-uint256-[`++getVotes++`]] +:getVotesWithParams: pass:normal[xref:#Governor-getVotesWithParams-address-uint256-bytes-[`++getVotesWithParams++`]] +:castVote: pass:normal[xref:#Governor-castVote-uint256-uint8-[`++castVote++`]] +:castVoteWithReason: pass:normal[xref:#Governor-castVoteWithReason-uint256-uint8-string-[`++castVoteWithReason++`]] +:castVoteWithReasonAndParams: pass:normal[xref:#Governor-castVoteWithReasonAndParams-uint256-uint8-string-bytes-[`++castVoteWithReasonAndParams++`]] +:castVoteBySig: pass:normal[xref:#Governor-castVoteBySig-uint256-uint8-address-bytes-[`++castVoteBySig++`]] +:castVoteWithReasonAndParamsBySig: pass:normal[xref:#Governor-castVoteWithReasonAndParamsBySig-uint256-uint8-address-string-bytes-bytes-[`++castVoteWithReasonAndParamsBySig++`]] +:_castVote: pass:normal[xref:#Governor-_castVote-uint256-address-uint8-string-[`++_castVote++`]] +:_castVote: pass:normal[xref:#Governor-_castVote-uint256-address-uint8-string-bytes-[`++_castVote++`]] +:relay: pass:normal[xref:#Governor-relay-address-uint256-bytes-[`++relay++`]] +:_executor: pass:normal[xref:#Governor-_executor--[`++_executor++`]] +:onERC721Received: pass:normal[xref:#Governor-onERC721Received-address-address-uint256-bytes-[`++onERC721Received++`]] +:onERC1155Received: pass:normal[xref:#Governor-onERC1155Received-address-address-uint256-uint256-bytes-[`++onERC1155Received++`]] +:onERC1155BatchReceived: pass:normal[xref:#Governor-onERC1155BatchReceived-address-address-uint256---uint256---bytes-[`++onERC1155BatchReceived++`]] +:_encodeStateBitmap: pass:normal[xref:#Governor-_encodeStateBitmap-enum-IGovernor-ProposalState-[`++_encodeStateBitmap++`]] +:_isValidDescriptionForProposer: pass:normal[xref:#Governor-_isValidDescriptionForProposer-address-string-[`++_isValidDescriptionForProposer++`]] +:clock: pass:normal[xref:#Governor-clock--[`++clock++`]] +:CLOCK_MODE: pass:normal[xref:#Governor-CLOCK_MODE--[`++CLOCK_MODE++`]] +:votingDelay: pass:normal[xref:#Governor-votingDelay--[`++votingDelay++`]] +:votingPeriod: pass:normal[xref:#Governor-votingPeriod--[`++votingPeriod++`]] +:quorum: pass:normal[xref:#Governor-quorum-uint256-[`++quorum++`]] + +[.contract] +[[Governor]] +=== `++Governor++` link:https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v5.0.0-rc.0/contracts/governance/Governor.sol[{github-icon},role=heading-link] + +[.hljs-theme-light.nopadding] +```solidity +import "@openzeppelin/contracts/governance/Governor.sol"; +``` + +Core of the governance system, designed to be extended through various modules. + +This contract is abstract and requires several functions to be implemented in various modules: + +- A counting module must implement {quorum}, {_quorumReached}, {_voteSucceeded} and {_countVote} +- A voting module must implement {_getVotes} +- Additionally, {votingPeriod} must also be implemented + +[.contract-index] +.Modifiers +-- +* {xref-Governor-onlyGovernance--}[`++onlyGovernance()++`] +-- + +[.contract-index] +.Functions +-- +* {xref-Governor-constructor-string-}[`++constructor(name_)++`] +* {xref-Governor-receive--}[`++receive()++`] +* {xref-Governor-supportsInterface-bytes4-}[`++supportsInterface(interfaceId)++`] +* {xref-Governor-name--}[`++name()++`] +* {xref-Governor-version--}[`++version()++`] +* {xref-Governor-hashProposal-address---uint256---bytes---bytes32-}[`++hashProposal(targets, values, calldatas, descriptionHash)++`] +* {xref-Governor-state-uint256-}[`++state(proposalId)++`] +* {xref-Governor-proposalThreshold--}[`++proposalThreshold()++`] +* {xref-Governor-proposalSnapshot-uint256-}[`++proposalSnapshot(proposalId)++`] +* {xref-Governor-proposalDeadline-uint256-}[`++proposalDeadline(proposalId)++`] +* {xref-Governor-proposalProposer-uint256-}[`++proposalProposer(proposalId)++`] +* {xref-Governor-proposalEta-uint256-}[`++proposalEta(proposalId)++`] +* {xref-Governor-proposalNeedsQueuing-uint256-}[`++proposalNeedsQueuing()++`] +* {xref-Governor-_checkGovernance--}[`++_checkGovernance()++`] +* {xref-Governor-_quorumReached-uint256-}[`++_quorumReached(proposalId)++`] +* {xref-Governor-_voteSucceeded-uint256-}[`++_voteSucceeded(proposalId)++`] +* {xref-Governor-_getVotes-address-uint256-bytes-}[`++_getVotes(account, timepoint, params)++`] +* {xref-Governor-_countVote-uint256-address-uint8-uint256-bytes-}[`++_countVote(proposalId, account, support, weight, params)++`] +* {xref-Governor-_defaultParams--}[`++_defaultParams()++`] +* {xref-Governor-propose-address---uint256---bytes---string-}[`++propose(targets, values, calldatas, description)++`] +* {xref-Governor-_propose-address---uint256---bytes---string-address-}[`++_propose(targets, values, calldatas, description, proposer)++`] +* {xref-Governor-queue-address---uint256---bytes---bytes32-}[`++queue(targets, values, calldatas, descriptionHash)++`] +* {xref-Governor-_queueOperations-uint256-address---uint256---bytes---bytes32-}[`++_queueOperations(, , , , )++`] +* {xref-Governor-execute-address---uint256---bytes---bytes32-}[`++execute(targets, values, calldatas, descriptionHash)++`] +* {xref-Governor-_executeOperations-uint256-address---uint256---bytes---bytes32-}[`++_executeOperations(, targets, values, calldatas, )++`] +* {xref-Governor-cancel-address---uint256---bytes---bytes32-}[`++cancel(targets, values, calldatas, descriptionHash)++`] +* {xref-Governor-_cancel-address---uint256---bytes---bytes32-}[`++_cancel(targets, values, calldatas, descriptionHash)++`] +* {xref-Governor-getVotes-address-uint256-}[`++getVotes(account, timepoint)++`] +* {xref-Governor-getVotesWithParams-address-uint256-bytes-}[`++getVotesWithParams(account, timepoint, params)++`] +* {xref-Governor-castVote-uint256-uint8-}[`++castVote(proposalId, support)++`] +* {xref-Governor-castVoteWithReason-uint256-uint8-string-}[`++castVoteWithReason(proposalId, support, reason)++`] +* {xref-Governor-castVoteWithReasonAndParams-uint256-uint8-string-bytes-}[`++castVoteWithReasonAndParams(proposalId, support, reason, params)++`] +* {xref-Governor-castVoteBySig-uint256-uint8-address-bytes-}[`++castVoteBySig(proposalId, support, voter, signature)++`] +* {xref-Governor-castVoteWithReasonAndParamsBySig-uint256-uint8-address-string-bytes-bytes-}[`++castVoteWithReasonAndParamsBySig(proposalId, support, voter, reason, params, signature)++`] +* {xref-Governor-_castVote-uint256-address-uint8-string-}[`++_castVote(proposalId, account, support, reason)++`] +* {xref-Governor-_castVote-uint256-address-uint8-string-bytes-}[`++_castVote(proposalId, account, support, reason, params)++`] +* {xref-Governor-relay-address-uint256-bytes-}[`++relay(target, value, data)++`] +* {xref-Governor-_executor--}[`++_executor()++`] +* {xref-Governor-onERC721Received-address-address-uint256-bytes-}[`++onERC721Received(, , , )++`] +* {xref-Governor-onERC1155Received-address-address-uint256-uint256-bytes-}[`++onERC1155Received(, , , , )++`] +* {xref-Governor-onERC1155BatchReceived-address-address-uint256---uint256---bytes-}[`++onERC1155BatchReceived(, , , , )++`] +* {xref-Governor-_encodeStateBitmap-enum-IGovernor-ProposalState-}[`++_encodeStateBitmap(proposalState)++`] +* {xref-Governor-_isValidDescriptionForProposer-address-string-}[`++_isValidDescriptionForProposer(proposer, description)++`] +* {xref-Governor-clock--}[`++clock()++`] +* {xref-Governor-CLOCK_MODE--}[`++CLOCK_MODE()++`] +* {xref-Governor-votingDelay--}[`++votingDelay()++`] +* {xref-Governor-votingPeriod--}[`++votingPeriod()++`] +* {xref-Governor-quorum-uint256-}[`++quorum(timepoint)++`] + +[.contract-subindex-inherited] +.IERC1155Receiver + +[.contract-subindex-inherited] +.IERC721Receiver + +[.contract-subindex-inherited] +.IGovernor +* {xref-IGovernor-COUNTING_MODE--}[`++COUNTING_MODE()++`] +* {xref-IGovernor-hasVoted-uint256-address-}[`++hasVoted(proposalId, account)++`] + +[.contract-subindex-inherited] +.IERC6372 + +[.contract-subindex-inherited] +.Nonces +* {xref-Nonces-nonces-address-}[`++nonces(owner)++`] +* {xref-Nonces-_useNonce-address-}[`++_useNonce(owner)++`] +* {xref-Nonces-_useCheckedNonce-address-uint256-}[`++_useCheckedNonce(owner, nonce)++`] + +[.contract-subindex-inherited] +.EIP712 +* {xref-EIP712-_domainSeparatorV4--}[`++_domainSeparatorV4()++`] +* {xref-EIP712-_hashTypedDataV4-bytes32-}[`++_hashTypedDataV4(structHash)++`] +* {xref-EIP712-eip712Domain--}[`++eip712Domain()++`] +* {xref-EIP712-_EIP712Name--}[`++_EIP712Name()++`] +* {xref-EIP712-_EIP712Version--}[`++_EIP712Version()++`] + +[.contract-subindex-inherited] +.IERC5267 + +[.contract-subindex-inherited] +.ERC165 + +[.contract-subindex-inherited] +.IERC165 + +-- + +[.contract-index] +.Events +-- + +[.contract-subindex-inherited] +.IERC1155Receiver + +[.contract-subindex-inherited] +.IERC721Receiver + +[.contract-subindex-inherited] +.IGovernor +* {xref-IGovernor-ProposalCreated-uint256-address-address---uint256---string---bytes---uint256-uint256-string-}[`++ProposalCreated(proposalId, proposer, targets, values, signatures, calldatas, voteStart, voteEnd, description)++`] +* {xref-IGovernor-ProposalQueued-uint256-uint256-}[`++ProposalQueued(proposalId, etaSeconds)++`] +* {xref-IGovernor-ProposalExecuted-uint256-}[`++ProposalExecuted(proposalId)++`] +* {xref-IGovernor-ProposalCanceled-uint256-}[`++ProposalCanceled(proposalId)++`] +* {xref-IGovernor-VoteCast-address-uint256-uint8-uint256-string-}[`++VoteCast(voter, proposalId, support, weight, reason)++`] +* {xref-IGovernor-VoteCastWithParams-address-uint256-uint8-uint256-string-bytes-}[`++VoteCastWithParams(voter, proposalId, support, weight, reason, params)++`] + +[.contract-subindex-inherited] +.IERC6372 + +[.contract-subindex-inherited] +.Nonces + +[.contract-subindex-inherited] +.EIP712 + +[.contract-subindex-inherited] +.IERC5267 +* {xref-IERC5267-EIP712DomainChanged--}[`++EIP712DomainChanged()++`] + +[.contract-subindex-inherited] +.ERC165 + +[.contract-subindex-inherited] +.IERC165 + +-- + +[.contract-index] +.Errors +-- + +[.contract-subindex-inherited] +.IERC1155Receiver + +[.contract-subindex-inherited] +.IERC721Receiver + +[.contract-subindex-inherited] +.IGovernor +* {xref-IGovernor-GovernorInvalidProposalLength-uint256-uint256-uint256-}[`++GovernorInvalidProposalLength(targets, calldatas, values)++`] +* {xref-IGovernor-GovernorAlreadyCastVote-address-}[`++GovernorAlreadyCastVote(voter)++`] +* {xref-IGovernor-GovernorDisabledDeposit--}[`++GovernorDisabledDeposit()++`] +* {xref-IGovernor-GovernorOnlyProposer-address-}[`++GovernorOnlyProposer(account)++`] +* {xref-IGovernor-GovernorOnlyExecutor-address-}[`++GovernorOnlyExecutor(account)++`] +* {xref-IGovernor-GovernorNonexistentProposal-uint256-}[`++GovernorNonexistentProposal(proposalId)++`] +* {xref-IGovernor-GovernorUnexpectedProposalState-uint256-enum-IGovernor-ProposalState-bytes32-}[`++GovernorUnexpectedProposalState(proposalId, current, expectedStates)++`] +* {xref-IGovernor-GovernorInvalidVotingPeriod-uint256-}[`++GovernorInvalidVotingPeriod(votingPeriod)++`] +* {xref-IGovernor-GovernorInsufficientProposerVotes-address-uint256-uint256-}[`++GovernorInsufficientProposerVotes(proposer, votes, threshold)++`] +* {xref-IGovernor-GovernorRestrictedProposer-address-}[`++GovernorRestrictedProposer(proposer)++`] +* {xref-IGovernor-GovernorInvalidVoteType--}[`++GovernorInvalidVoteType()++`] +* {xref-IGovernor-GovernorQueueNotImplemented--}[`++GovernorQueueNotImplemented()++`] +* {xref-IGovernor-GovernorNotQueuedProposal-uint256-}[`++GovernorNotQueuedProposal(proposalId)++`] +* {xref-IGovernor-GovernorAlreadyQueuedProposal-uint256-}[`++GovernorAlreadyQueuedProposal(proposalId)++`] +* {xref-IGovernor-GovernorInvalidSignature-address-}[`++GovernorInvalidSignature(voter)++`] + +[.contract-subindex-inherited] +.IERC6372 + +[.contract-subindex-inherited] +.Nonces +* {xref-Nonces-InvalidAccountNonce-address-uint256-}[`++InvalidAccountNonce(account, currentNonce)++`] + +[.contract-subindex-inherited] +.EIP712 + +[.contract-subindex-inherited] +.IERC5267 + +[.contract-subindex-inherited] +.ERC165 + +[.contract-subindex-inherited] +.IERC165 + +-- + +[.contract-item] +[[Governor-onlyGovernance--]] +==== `[.contract-item-name]#++onlyGovernance++#++()++` [.item-kind]#modifier# + +Restricts a function so it can only be executed through governance proposals. For example, governance +parameter setters in {GovernorSettings} are protected using this modifier. + +The governance executing address may be different from the Governor's own address, for example it could be a +timelock. This can be customized by modules by overriding {_executor}. The executor is only able to invoke these +functions during the execution of the governor's {execute} function, and not under any other circumstances. Thus, +for example, additional timelock proposers are not able to change governance parameters without going through the +governance protocol (since v4.6). + +[.contract-item] +[[Governor-constructor-string-]] +==== `[.contract-item-name]#++constructor++#++(string name_)++` [.item-kind]#internal# + +Sets the value for {name} and {version} + +[.contract-item] +[[Governor-receive--]] +==== `[.contract-item-name]#++receive++#++()++` [.item-kind]#external# + +Function to receive ETH that will be handled by the governor (disabled if executor is a third party contract) + +[.contract-item] +[[Governor-supportsInterface-bytes4-]] +==== `[.contract-item-name]#++supportsInterface++#++(bytes4 interfaceId) → bool++` [.item-kind]#public# + +See {IERC165-supportsInterface}. + +[.contract-item] +[[Governor-name--]] +==== `[.contract-item-name]#++name++#++() → string++` [.item-kind]#public# + +See {IGovernor-name}. + +[.contract-item] +[[Governor-version--]] +==== `[.contract-item-name]#++version++#++() → string++` [.item-kind]#public# + +See {IGovernor-version}. + +[.contract-item] +[[Governor-hashProposal-address---uint256---bytes---bytes32-]] +==== `[.contract-item-name]#++hashProposal++#++(address[] targets, uint256[] values, bytes[] calldatas, bytes32 descriptionHash) → uint256++` [.item-kind]#public# + +See {IGovernor-hashProposal}. + +The proposal id is produced by hashing the ABI encoded `targets` array, the `values` array, the `calldatas` array +and the descriptionHash (bytes32 which itself is the keccak256 hash of the description string). This proposal id +can be produced from the proposal data which is part of the {ProposalCreated} event. It can even be computed in +advance, before the proposal is submitted. + +Note that the chainId and the governor address are not part of the proposal id computation. Consequently, the +same proposal (with same operation and same description) will have the same id if submitted on multiple governors +across multiple networks. This also means that in order to execute the same operation twice (on the same +governor) the proposer will have to change the description in order to avoid proposal id conflicts. + +[.contract-item] +[[Governor-state-uint256-]] +==== `[.contract-item-name]#++state++#++(uint256 proposalId) → enum IGovernor.ProposalState++` [.item-kind]#public# + +See {IGovernor-state}. + +[.contract-item] +[[Governor-proposalThreshold--]] +==== `[.contract-item-name]#++proposalThreshold++#++() → uint256++` [.item-kind]#public# + +See {IGovernor-proposalThreshold}. + +[.contract-item] +[[Governor-proposalSnapshot-uint256-]] +==== `[.contract-item-name]#++proposalSnapshot++#++(uint256 proposalId) → uint256++` [.item-kind]#public# + +See {IGovernor-proposalSnapshot}. + +[.contract-item] +[[Governor-proposalDeadline-uint256-]] +==== `[.contract-item-name]#++proposalDeadline++#++(uint256 proposalId) → uint256++` [.item-kind]#public# + +See {IGovernor-proposalDeadline}. + +[.contract-item] +[[Governor-proposalProposer-uint256-]] +==== `[.contract-item-name]#++proposalProposer++#++(uint256 proposalId) → address++` [.item-kind]#public# + +See {IGovernor-proposalProposer}. + +[.contract-item] +[[Governor-proposalEta-uint256-]] +==== `[.contract-item-name]#++proposalEta++#++(uint256 proposalId) → uint256++` [.item-kind]#public# + +See {IGovernor-proposalEta}. + +[.contract-item] +[[Governor-proposalNeedsQueuing-uint256-]] +==== `[.contract-item-name]#++proposalNeedsQueuing++#++(uint256) → bool++` [.item-kind]#public# + +See {IGovernor-proposalNeedsQueuing}. + +[.contract-item] +[[Governor-_checkGovernance--]] +==== `[.contract-item-name]#++_checkGovernance++#++()++` [.item-kind]#internal# + +Reverts if the `msg.sender` is not the executor. In case the executor is not this contract +itself, the function reverts if `msg.data` is not whitelisted as a result of an {execute} +operation. See {onlyGovernance}. + +[.contract-item] +[[Governor-_quorumReached-uint256-]] +==== `[.contract-item-name]#++_quorumReached++#++(uint256 proposalId) → bool++` [.item-kind]#internal# + +Amount of votes already cast passes the threshold limit. + +[.contract-item] +[[Governor-_voteSucceeded-uint256-]] +==== `[.contract-item-name]#++_voteSucceeded++#++(uint256 proposalId) → bool++` [.item-kind]#internal# + +Is the proposal successful or not. + +[.contract-item] +[[Governor-_getVotes-address-uint256-bytes-]] +==== `[.contract-item-name]#++_getVotes++#++(address account, uint256 timepoint, bytes params) → uint256++` [.item-kind]#internal# + +Get the voting weight of `account` at a specific `timepoint`, for a vote as described by `params`. + +[.contract-item] +[[Governor-_countVote-uint256-address-uint8-uint256-bytes-]] +==== `[.contract-item-name]#++_countVote++#++(uint256 proposalId, address account, uint8 support, uint256 weight, bytes params)++` [.item-kind]#internal# + +Register a vote for `proposalId` by `account` with a given `support`, voting `weight` and voting `params`. + +Note: Support is generic and can represent various things depending on the voting system used. + +[.contract-item] +[[Governor-_defaultParams--]] +==== `[.contract-item-name]#++_defaultParams++#++() → bytes++` [.item-kind]#internal# + +Default additional encoded parameters used by castVote methods that don't include them + +Note: Should be overridden by specific implementations to use an appropriate value, the +meaning of the additional params, in the context of that implementation + +[.contract-item] +[[Governor-propose-address---uint256---bytes---string-]] +==== `[.contract-item-name]#++propose++#++(address[] targets, uint256[] values, bytes[] calldatas, string description) → uint256++` [.item-kind]#public# + +See {IGovernor-propose}. This function has opt-in frontrunning protection, described in {_isValidDescriptionForProposer}. + +[.contract-item] +[[Governor-_propose-address---uint256---bytes---string-address-]] +==== `[.contract-item-name]#++_propose++#++(address[] targets, uint256[] values, bytes[] calldatas, string description, address proposer) → uint256 proposalId++` [.item-kind]#internal# + +Internal propose mechanism. Can be overridden to add more logic on proposal creation. + +Emits a {IGovernor-ProposalCreated} event. + +[.contract-item] +[[Governor-queue-address---uint256---bytes---bytes32-]] +==== `[.contract-item-name]#++queue++#++(address[] targets, uint256[] values, bytes[] calldatas, bytes32 descriptionHash) → uint256++` [.item-kind]#public# + +See {IGovernor-queue}. + +[.contract-item] +[[Governor-_queueOperations-uint256-address---uint256---bytes---bytes32-]] +==== `[.contract-item-name]#++_queueOperations++#++(uint256, address[], uint256[], bytes[], bytes32) → uint48++` [.item-kind]#internal# + +Internal queuing mechanism. Can be overridden (without a super call) to modify the way queuing is +performed (for example adding a vault/timelock). + +This is empty by default, and must be overridden to implement queuing. + +This function returns a timestamp that describes the expected ETA for execution. If the returned value is 0 +(which is the default value), the core will consider queueing did not succeed, and the public {queue} function +will revert. + +NOTE: Calling this function directly will NOT check the current state of the proposal, or emit the +`ProposalQueued` event. Queuing a proposal should be done using {queue}. + +[.contract-item] +[[Governor-execute-address---uint256---bytes---bytes32-]] +==== `[.contract-item-name]#++execute++#++(address[] targets, uint256[] values, bytes[] calldatas, bytes32 descriptionHash) → uint256++` [.item-kind]#public# + +See {IGovernor-execute}. + +[.contract-item] +[[Governor-_executeOperations-uint256-address---uint256---bytes---bytes32-]] +==== `[.contract-item-name]#++_executeOperations++#++(uint256, address[] targets, uint256[] values, bytes[] calldatas, bytes32)++` [.item-kind]#internal# + +Internal execution mechanism. Can be overridden (without a super call) to modify the way execution is +performed (for example adding a vault/timelock). + +NOTE: Calling this function directly will NOT check the current state of the proposal, set the executed flag to +true or emit the `ProposalExecuted` event. Executing a proposal should be done using {execute} or {_execute}. + +[.contract-item] +[[Governor-cancel-address---uint256---bytes---bytes32-]] +==== `[.contract-item-name]#++cancel++#++(address[] targets, uint256[] values, bytes[] calldatas, bytes32 descriptionHash) → uint256++` [.item-kind]#public# + +See {IGovernor-cancel}. + +[.contract-item] +[[Governor-_cancel-address---uint256---bytes---bytes32-]] +==== `[.contract-item-name]#++_cancel++#++(address[] targets, uint256[] values, bytes[] calldatas, bytes32 descriptionHash) → uint256++` [.item-kind]#internal# + +Internal cancel mechanism with minimal restrictions. A proposal can be cancelled in any state other than +Canceled, Expired, or Executed. Once cancelled a proposal can't be re-submitted. + +Emits a {IGovernor-ProposalCanceled} event. + +[.contract-item] +[[Governor-getVotes-address-uint256-]] +==== `[.contract-item-name]#++getVotes++#++(address account, uint256 timepoint) → uint256++` [.item-kind]#public# + +See {IGovernor-getVotes}. + +[.contract-item] +[[Governor-getVotesWithParams-address-uint256-bytes-]] +==== `[.contract-item-name]#++getVotesWithParams++#++(address account, uint256 timepoint, bytes params) → uint256++` [.item-kind]#public# + +See {IGovernor-getVotesWithParams}. + +[.contract-item] +[[Governor-castVote-uint256-uint8-]] +==== `[.contract-item-name]#++castVote++#++(uint256 proposalId, uint8 support) → uint256++` [.item-kind]#public# + +See {IGovernor-castVote}. + +[.contract-item] +[[Governor-castVoteWithReason-uint256-uint8-string-]] +==== `[.contract-item-name]#++castVoteWithReason++#++(uint256 proposalId, uint8 support, string reason) → uint256++` [.item-kind]#public# + +See {IGovernor-castVoteWithReason}. + +[.contract-item] +[[Governor-castVoteWithReasonAndParams-uint256-uint8-string-bytes-]] +==== `[.contract-item-name]#++castVoteWithReasonAndParams++#++(uint256 proposalId, uint8 support, string reason, bytes params) → uint256++` [.item-kind]#public# + +See {IGovernor-castVoteWithReasonAndParams}. + +[.contract-item] +[[Governor-castVoteBySig-uint256-uint8-address-bytes-]] +==== `[.contract-item-name]#++castVoteBySig++#++(uint256 proposalId, uint8 support, address voter, bytes signature) → uint256++` [.item-kind]#public# + +See {IGovernor-castVoteBySig}. + +[.contract-item] +[[Governor-castVoteWithReasonAndParamsBySig-uint256-uint8-address-string-bytes-bytes-]] +==== `[.contract-item-name]#++castVoteWithReasonAndParamsBySig++#++(uint256 proposalId, uint8 support, address voter, string reason, bytes params, bytes signature) → uint256++` [.item-kind]#public# + +See {IGovernor-castVoteWithReasonAndParamsBySig}. + +[.contract-item] +[[Governor-_castVote-uint256-address-uint8-string-]] +==== `[.contract-item-name]#++_castVote++#++(uint256 proposalId, address account, uint8 support, string reason) → uint256++` [.item-kind]#internal# + +Internal vote casting mechanism: Check that the vote is pending, that it has not been cast yet, retrieve +voting weight using {IGovernor-getVotes} and call the {_countVote} internal function. Uses the _defaultParams(). + +Emits a {IGovernor-VoteCast} event. + +[.contract-item] +[[Governor-_castVote-uint256-address-uint8-string-bytes-]] +==== `[.contract-item-name]#++_castVote++#++(uint256 proposalId, address account, uint8 support, string reason, bytes params) → uint256++` [.item-kind]#internal# + +Internal vote casting mechanism: Check that the vote is pending, that it has not been cast yet, retrieve +voting weight using {IGovernor-getVotes} and call the {_countVote} internal function. + +Emits a {IGovernor-VoteCast} event. + +[.contract-item] +[[Governor-relay-address-uint256-bytes-]] +==== `[.contract-item-name]#++relay++#++(address target, uint256 value, bytes data)++` [.item-kind]#external# + +Relays a transaction or function call to an arbitrary target. In cases where the governance executor +is some contract other than the governor itself, like when using a timelock, this function can be invoked +in a governance proposal to recover tokens or Ether that was sent to the governor contract by mistake. +Note that if the executor is simply the governor itself, use of `relay` is redundant. + +[.contract-item] +[[Governor-_executor--]] +==== `[.contract-item-name]#++_executor++#++() → address++` [.item-kind]#internal# + +Address through which the governor executes action. Will be overloaded by module that execute actions +through another contract such as a timelock. + +[.contract-item] +[[Governor-onERC721Received-address-address-uint256-bytes-]] +==== `[.contract-item-name]#++onERC721Received++#++(address, address, uint256, bytes) → bytes4++` [.item-kind]#public# + +See {IERC721Receiver-onERC721Received}. +Receiving tokens is disabled if the governance executor is other than the governor itself (eg. when using with a timelock). + +[.contract-item] +[[Governor-onERC1155Received-address-address-uint256-uint256-bytes-]] +==== `[.contract-item-name]#++onERC1155Received++#++(address, address, uint256, uint256, bytes) → bytes4++` [.item-kind]#public# + +See {IERC1155Receiver-onERC1155Received}. +Receiving tokens is disabled if the governance executor is other than the governor itself (eg. when using with a timelock). + +[.contract-item] +[[Governor-onERC1155BatchReceived-address-address-uint256---uint256---bytes-]] +==== `[.contract-item-name]#++onERC1155BatchReceived++#++(address, address, uint256[], uint256[], bytes) → bytes4++` [.item-kind]#public# + +See {IERC1155Receiver-onERC1155BatchReceived}. +Receiving tokens is disabled if the governance executor is other than the governor itself (eg. when using with a timelock). + +[.contract-item] +[[Governor-_encodeStateBitmap-enum-IGovernor-ProposalState-]] +==== `[.contract-item-name]#++_encodeStateBitmap++#++(enum IGovernor.ProposalState proposalState) → bytes32++` [.item-kind]#internal# + +Encodes a `ProposalState` into a `bytes32` representation where each bit enabled corresponds to +the underlying position in the `ProposalState` enum. For example: + +0x000...10000 + ^^^^^^------ ... + ^----- Succeeded + ^---- Defeated + ^--- Canceled + ^-- Active + ^- Pending + +[.contract-item] +[[Governor-_isValidDescriptionForProposer-address-string-]] +==== `[.contract-item-name]#++_isValidDescriptionForProposer++#++(address proposer, string description) → bool++` [.item-kind]#internal# + +[.contract-item] +[[Governor-clock--]] +==== `[.contract-item-name]#++clock++#++() → uint48++` [.item-kind]#public# + +Clock used for flagging checkpoints. Can be overridden to implement timestamp based checkpoints (and voting). + +[.contract-item] +[[Governor-CLOCK_MODE--]] +==== `[.contract-item-name]#++CLOCK_MODE++#++() → string++` [.item-kind]#public# + +Description of the clock + +[.contract-item] +[[Governor-votingDelay--]] +==== `[.contract-item-name]#++votingDelay++#++() → uint256++` [.item-kind]#public# + +Delay, between the proposal is created and the vote starts. The unit this duration is expressed in depends +on the clock (see EIP-6372) this contract uses. + +This can be increased to leave time for users to buy voting power, or delegate it, before the voting of a +proposal starts. + +NOTE: While this interface returns a uint256, timepoints are stored as uint48 following the ERC-6372 clock type. +Consequently this value must fit in a uint48 (when added to the current clock). See {IERC6372-clock}. + +[.contract-item] +[[Governor-votingPeriod--]] +==== `[.contract-item-name]#++votingPeriod++#++() → uint256++` [.item-kind]#public# + +Delay between the vote start and vote end. The unit this duration is expressed in depends on the clock +(see EIP-6372) this contract uses. + +NOTE: The {votingDelay} can delay the start of the vote. This must be considered when setting the voting +duration compared to the voting delay. + +NOTE: This value is stored when the proposal is submitted so that possible changes to the value do not affect +proposals that have already been submitted. The type used to save it is a uint32. Consequently, while this +interface returns a uint256, the value it returns should fit in a uint32. + +[.contract-item] +[[Governor-quorum-uint256-]] +==== `[.contract-item-name]#++quorum++#++(uint256 timepoint) → uint256++` [.item-kind]#public# + +Minimum number of cast voted required for a proposal to be successful. + +NOTE: The `timepoint` parameter corresponds to the snapshot used for counting vote. This allows to scale the +quorum depending on values such as the totalSupply of a token at this timepoint (see {ERC20Votes}). + +=== Modules + +:VoteType: pass:normal[xref:#GovernorCountingSimple-VoteType[`++VoteType++`]] +:ProposalVote: pass:normal[xref:#GovernorCountingSimple-ProposalVote[`++ProposalVote++`]] +:COUNTING_MODE: pass:normal[xref:#GovernorCountingSimple-COUNTING_MODE--[`++COUNTING_MODE++`]] +:hasVoted: pass:normal[xref:#GovernorCountingSimple-hasVoted-uint256-address-[`++hasVoted++`]] +:proposalVotes: pass:normal[xref:#GovernorCountingSimple-proposalVotes-uint256-[`++proposalVotes++`]] +:_quorumReached: pass:normal[xref:#GovernorCountingSimple-_quorumReached-uint256-[`++_quorumReached++`]] +:_voteSucceeded: pass:normal[xref:#GovernorCountingSimple-_voteSucceeded-uint256-[`++_voteSucceeded++`]] +:_countVote: pass:normal[xref:#GovernorCountingSimple-_countVote-uint256-address-uint8-uint256-bytes-[`++_countVote++`]] + +[.contract] +[[GovernorCountingSimple]] +=== `++GovernorCountingSimple++` link:https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v5.0.0-rc.0/contracts/governance/extensions/GovernorCountingSimple.sol[{github-icon},role=heading-link] + +[.hljs-theme-light.nopadding] +```solidity +import "@openzeppelin/contracts/governance/extensions/GovernorCountingSimple.sol"; +``` + +Extension of {Governor} for simple, 3 options, vote counting. + +[.contract-index] +.Functions +-- +* {xref-GovernorCountingSimple-COUNTING_MODE--}[`++COUNTING_MODE()++`] +* {xref-GovernorCountingSimple-hasVoted-uint256-address-}[`++hasVoted(proposalId, account)++`] +* {xref-GovernorCountingSimple-proposalVotes-uint256-}[`++proposalVotes(proposalId)++`] +* {xref-GovernorCountingSimple-_quorumReached-uint256-}[`++_quorumReached(proposalId)++`] +* {xref-GovernorCountingSimple-_voteSucceeded-uint256-}[`++_voteSucceeded(proposalId)++`] +* {xref-GovernorCountingSimple-_countVote-uint256-address-uint8-uint256-bytes-}[`++_countVote(proposalId, account, support, weight, )++`] + +[.contract-subindex-inherited] +.Governor +* {xref-Governor-receive--}[`++receive()++`] +* {xref-Governor-supportsInterface-bytes4-}[`++supportsInterface(interfaceId)++`] +* {xref-Governor-name--}[`++name()++`] +* {xref-Governor-version--}[`++version()++`] +* {xref-Governor-hashProposal-address---uint256---bytes---bytes32-}[`++hashProposal(targets, values, calldatas, descriptionHash)++`] +* {xref-Governor-state-uint256-}[`++state(proposalId)++`] +* {xref-Governor-proposalThreshold--}[`++proposalThreshold()++`] +* {xref-Governor-proposalSnapshot-uint256-}[`++proposalSnapshot(proposalId)++`] +* {xref-Governor-proposalDeadline-uint256-}[`++proposalDeadline(proposalId)++`] +* {xref-Governor-proposalProposer-uint256-}[`++proposalProposer(proposalId)++`] +* {xref-Governor-proposalEta-uint256-}[`++proposalEta(proposalId)++`] +* {xref-Governor-proposalNeedsQueuing-uint256-}[`++proposalNeedsQueuing()++`] +* {xref-Governor-_checkGovernance--}[`++_checkGovernance()++`] +* {xref-Governor-_getVotes-address-uint256-bytes-}[`++_getVotes(account, timepoint, params)++`] +* {xref-Governor-_defaultParams--}[`++_defaultParams()++`] +* {xref-Governor-propose-address---uint256---bytes---string-}[`++propose(targets, values, calldatas, description)++`] +* {xref-Governor-_propose-address---uint256---bytes---string-address-}[`++_propose(targets, values, calldatas, description, proposer)++`] +* {xref-Governor-queue-address---uint256---bytes---bytes32-}[`++queue(targets, values, calldatas, descriptionHash)++`] +* {xref-Governor-_queueOperations-uint256-address---uint256---bytes---bytes32-}[`++_queueOperations(, , , , )++`] +* {xref-Governor-execute-address---uint256---bytes---bytes32-}[`++execute(targets, values, calldatas, descriptionHash)++`] +* {xref-Governor-_executeOperations-uint256-address---uint256---bytes---bytes32-}[`++_executeOperations(, targets, values, calldatas, )++`] +* {xref-Governor-cancel-address---uint256---bytes---bytes32-}[`++cancel(targets, values, calldatas, descriptionHash)++`] +* {xref-Governor-_cancel-address---uint256---bytes---bytes32-}[`++_cancel(targets, values, calldatas, descriptionHash)++`] +* {xref-Governor-getVotes-address-uint256-}[`++getVotes(account, timepoint)++`] +* {xref-Governor-getVotesWithParams-address-uint256-bytes-}[`++getVotesWithParams(account, timepoint, params)++`] +* {xref-Governor-castVote-uint256-uint8-}[`++castVote(proposalId, support)++`] +* {xref-Governor-castVoteWithReason-uint256-uint8-string-}[`++castVoteWithReason(proposalId, support, reason)++`] +* {xref-Governor-castVoteWithReasonAndParams-uint256-uint8-string-bytes-}[`++castVoteWithReasonAndParams(proposalId, support, reason, params)++`] +* {xref-Governor-castVoteBySig-uint256-uint8-address-bytes-}[`++castVoteBySig(proposalId, support, voter, signature)++`] +* {xref-Governor-castVoteWithReasonAndParamsBySig-uint256-uint8-address-string-bytes-bytes-}[`++castVoteWithReasonAndParamsBySig(proposalId, support, voter, reason, params, signature)++`] +* {xref-Governor-_castVote-uint256-address-uint8-string-}[`++_castVote(proposalId, account, support, reason)++`] +* {xref-Governor-_castVote-uint256-address-uint8-string-bytes-}[`++_castVote(proposalId, account, support, reason, params)++`] +* {xref-Governor-relay-address-uint256-bytes-}[`++relay(target, value, data)++`] +* {xref-Governor-_executor--}[`++_executor()++`] +* {xref-Governor-onERC721Received-address-address-uint256-bytes-}[`++onERC721Received(, , , )++`] +* {xref-Governor-onERC1155Received-address-address-uint256-uint256-bytes-}[`++onERC1155Received(, , , , )++`] +* {xref-Governor-onERC1155BatchReceived-address-address-uint256---uint256---bytes-}[`++onERC1155BatchReceived(, , , , )++`] +* {xref-Governor-_encodeStateBitmap-enum-IGovernor-ProposalState-}[`++_encodeStateBitmap(proposalState)++`] +* {xref-Governor-_isValidDescriptionForProposer-address-string-}[`++_isValidDescriptionForProposer(proposer, description)++`] +* {xref-Governor-clock--}[`++clock()++`] +* {xref-Governor-CLOCK_MODE--}[`++CLOCK_MODE()++`] +* {xref-Governor-votingDelay--}[`++votingDelay()++`] +* {xref-Governor-votingPeriod--}[`++votingPeriod()++`] +* {xref-Governor-quorum-uint256-}[`++quorum(timepoint)++`] + +[.contract-subindex-inherited] +.IERC1155Receiver + +[.contract-subindex-inherited] +.IERC721Receiver + +[.contract-subindex-inherited] +.IGovernor + +[.contract-subindex-inherited] +.IERC6372 + +[.contract-subindex-inherited] +.Nonces +* {xref-Nonces-nonces-address-}[`++nonces(owner)++`] +* {xref-Nonces-_useNonce-address-}[`++_useNonce(owner)++`] +* {xref-Nonces-_useCheckedNonce-address-uint256-}[`++_useCheckedNonce(owner, nonce)++`] + +[.contract-subindex-inherited] +.EIP712 +* {xref-EIP712-_domainSeparatorV4--}[`++_domainSeparatorV4()++`] +* {xref-EIP712-_hashTypedDataV4-bytes32-}[`++_hashTypedDataV4(structHash)++`] +* {xref-EIP712-eip712Domain--}[`++eip712Domain()++`] +* {xref-EIP712-_EIP712Name--}[`++_EIP712Name()++`] +* {xref-EIP712-_EIP712Version--}[`++_EIP712Version()++`] + +[.contract-subindex-inherited] +.IERC5267 + +[.contract-subindex-inherited] +.ERC165 + +[.contract-subindex-inherited] +.IERC165 + +-- + +[.contract-index] +.Events +-- + +[.contract-subindex-inherited] +.Governor + +[.contract-subindex-inherited] +.IERC1155Receiver + +[.contract-subindex-inherited] +.IERC721Receiver + +[.contract-subindex-inherited] +.IGovernor +* {xref-IGovernor-ProposalCreated-uint256-address-address---uint256---string---bytes---uint256-uint256-string-}[`++ProposalCreated(proposalId, proposer, targets, values, signatures, calldatas, voteStart, voteEnd, description)++`] +* {xref-IGovernor-ProposalQueued-uint256-uint256-}[`++ProposalQueued(proposalId, etaSeconds)++`] +* {xref-IGovernor-ProposalExecuted-uint256-}[`++ProposalExecuted(proposalId)++`] +* {xref-IGovernor-ProposalCanceled-uint256-}[`++ProposalCanceled(proposalId)++`] +* {xref-IGovernor-VoteCast-address-uint256-uint8-uint256-string-}[`++VoteCast(voter, proposalId, support, weight, reason)++`] +* {xref-IGovernor-VoteCastWithParams-address-uint256-uint8-uint256-string-bytes-}[`++VoteCastWithParams(voter, proposalId, support, weight, reason, params)++`] + +[.contract-subindex-inherited] +.IERC6372 + +[.contract-subindex-inherited] +.Nonces + +[.contract-subindex-inherited] +.EIP712 + +[.contract-subindex-inherited] +.IERC5267 +* {xref-IERC5267-EIP712DomainChanged--}[`++EIP712DomainChanged()++`] + +[.contract-subindex-inherited] +.ERC165 + +[.contract-subindex-inherited] +.IERC165 + +-- + +[.contract-index] +.Errors +-- + +[.contract-subindex-inherited] +.Governor + +[.contract-subindex-inherited] +.IERC1155Receiver + +[.contract-subindex-inherited] +.IERC721Receiver + +[.contract-subindex-inherited] +.IGovernor +* {xref-IGovernor-GovernorInvalidProposalLength-uint256-uint256-uint256-}[`++GovernorInvalidProposalLength(targets, calldatas, values)++`] +* {xref-IGovernor-GovernorAlreadyCastVote-address-}[`++GovernorAlreadyCastVote(voter)++`] +* {xref-IGovernor-GovernorDisabledDeposit--}[`++GovernorDisabledDeposit()++`] +* {xref-IGovernor-GovernorOnlyProposer-address-}[`++GovernorOnlyProposer(account)++`] +* {xref-IGovernor-GovernorOnlyExecutor-address-}[`++GovernorOnlyExecutor(account)++`] +* {xref-IGovernor-GovernorNonexistentProposal-uint256-}[`++GovernorNonexistentProposal(proposalId)++`] +* {xref-IGovernor-GovernorUnexpectedProposalState-uint256-enum-IGovernor-ProposalState-bytes32-}[`++GovernorUnexpectedProposalState(proposalId, current, expectedStates)++`] +* {xref-IGovernor-GovernorInvalidVotingPeriod-uint256-}[`++GovernorInvalidVotingPeriod(votingPeriod)++`] +* {xref-IGovernor-GovernorInsufficientProposerVotes-address-uint256-uint256-}[`++GovernorInsufficientProposerVotes(proposer, votes, threshold)++`] +* {xref-IGovernor-GovernorRestrictedProposer-address-}[`++GovernorRestrictedProposer(proposer)++`] +* {xref-IGovernor-GovernorInvalidVoteType--}[`++GovernorInvalidVoteType()++`] +* {xref-IGovernor-GovernorQueueNotImplemented--}[`++GovernorQueueNotImplemented()++`] +* {xref-IGovernor-GovernorNotQueuedProposal-uint256-}[`++GovernorNotQueuedProposal(proposalId)++`] +* {xref-IGovernor-GovernorAlreadyQueuedProposal-uint256-}[`++GovernorAlreadyQueuedProposal(proposalId)++`] +* {xref-IGovernor-GovernorInvalidSignature-address-}[`++GovernorInvalidSignature(voter)++`] + +[.contract-subindex-inherited] +.IERC6372 + +[.contract-subindex-inherited] +.Nonces +* {xref-Nonces-InvalidAccountNonce-address-uint256-}[`++InvalidAccountNonce(account, currentNonce)++`] + +[.contract-subindex-inherited] +.EIP712 + +[.contract-subindex-inherited] +.IERC5267 + +[.contract-subindex-inherited] +.ERC165 + +[.contract-subindex-inherited] +.IERC165 + +-- + +[.contract-item] +[[GovernorCountingSimple-COUNTING_MODE--]] +==== `[.contract-item-name]#++COUNTING_MODE++#++() → string++` [.item-kind]#public# + +See {IGovernor-COUNTING_MODE}. + +[.contract-item] +[[GovernorCountingSimple-hasVoted-uint256-address-]] +==== `[.contract-item-name]#++hasVoted++#++(uint256 proposalId, address account) → bool++` [.item-kind]#public# + +See {IGovernor-hasVoted}. + +[.contract-item] +[[GovernorCountingSimple-proposalVotes-uint256-]] +==== `[.contract-item-name]#++proposalVotes++#++(uint256 proposalId) → uint256 againstVotes, uint256 forVotes, uint256 abstainVotes++` [.item-kind]#public# + +Accessor to the internal vote counts. + +[.contract-item] +[[GovernorCountingSimple-_quorumReached-uint256-]] +==== `[.contract-item-name]#++_quorumReached++#++(uint256 proposalId) → bool++` [.item-kind]#internal# + +See {Governor-_quorumReached}. + +[.contract-item] +[[GovernorCountingSimple-_voteSucceeded-uint256-]] +==== `[.contract-item-name]#++_voteSucceeded++#++(uint256 proposalId) → bool++` [.item-kind]#internal# + +See {Governor-_voteSucceeded}. In this module, the forVotes must be strictly over the againstVotes. + +[.contract-item] +[[GovernorCountingSimple-_countVote-uint256-address-uint8-uint256-bytes-]] +==== `[.contract-item-name]#++_countVote++#++(uint256 proposalId, address account, uint8 support, uint256 weight, bytes)++` [.item-kind]#internal# + +See {Governor-_countVote}. In this module, the support follows the `VoteType` enum (from Governor Bravo). + +:constructor: pass:normal[xref:#GovernorVotes-constructor-contract-IVotes-[`++constructor++`]] +:token: pass:normal[xref:#GovernorVotes-token--[`++token++`]] +:clock: pass:normal[xref:#GovernorVotes-clock--[`++clock++`]] +:CLOCK_MODE: pass:normal[xref:#GovernorVotes-CLOCK_MODE--[`++CLOCK_MODE++`]] +:_getVotes: pass:normal[xref:#GovernorVotes-_getVotes-address-uint256-bytes-[`++_getVotes++`]] + +[.contract] +[[GovernorVotes]] +=== `++GovernorVotes++` link:https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v5.0.0-rc.0/contracts/governance/extensions/GovernorVotes.sol[{github-icon},role=heading-link] + +[.hljs-theme-light.nopadding] +```solidity +import "@openzeppelin/contracts/governance/extensions/GovernorVotes.sol"; +``` + +Extension of {Governor} for voting weight extraction from an {ERC20Votes} token, or since v4.5 an {ERC721Votes} +token. + +[.contract-index] +.Functions +-- +* {xref-GovernorVotes-constructor-contract-IVotes-}[`++constructor(tokenAddress)++`] +* {xref-GovernorVotes-token--}[`++token()++`] +* {xref-GovernorVotes-clock--}[`++clock()++`] +* {xref-GovernorVotes-CLOCK_MODE--}[`++CLOCK_MODE()++`] +* {xref-GovernorVotes-_getVotes-address-uint256-bytes-}[`++_getVotes(account, timepoint, )++`] + +[.contract-subindex-inherited] +.Governor +* {xref-Governor-receive--}[`++receive()++`] +* {xref-Governor-supportsInterface-bytes4-}[`++supportsInterface(interfaceId)++`] +* {xref-Governor-name--}[`++name()++`] +* {xref-Governor-version--}[`++version()++`] +* {xref-Governor-hashProposal-address---uint256---bytes---bytes32-}[`++hashProposal(targets, values, calldatas, descriptionHash)++`] +* {xref-Governor-state-uint256-}[`++state(proposalId)++`] +* {xref-Governor-proposalThreshold--}[`++proposalThreshold()++`] +* {xref-Governor-proposalSnapshot-uint256-}[`++proposalSnapshot(proposalId)++`] +* {xref-Governor-proposalDeadline-uint256-}[`++proposalDeadline(proposalId)++`] +* {xref-Governor-proposalProposer-uint256-}[`++proposalProposer(proposalId)++`] +* {xref-Governor-proposalEta-uint256-}[`++proposalEta(proposalId)++`] +* {xref-Governor-proposalNeedsQueuing-uint256-}[`++proposalNeedsQueuing()++`] +* {xref-Governor-_checkGovernance--}[`++_checkGovernance()++`] +* {xref-Governor-_quorumReached-uint256-}[`++_quorumReached(proposalId)++`] +* {xref-Governor-_voteSucceeded-uint256-}[`++_voteSucceeded(proposalId)++`] +* {xref-Governor-_countVote-uint256-address-uint8-uint256-bytes-}[`++_countVote(proposalId, account, support, weight, params)++`] +* {xref-Governor-_defaultParams--}[`++_defaultParams()++`] +* {xref-Governor-propose-address---uint256---bytes---string-}[`++propose(targets, values, calldatas, description)++`] +* {xref-Governor-_propose-address---uint256---bytes---string-address-}[`++_propose(targets, values, calldatas, description, proposer)++`] +* {xref-Governor-queue-address---uint256---bytes---bytes32-}[`++queue(targets, values, calldatas, descriptionHash)++`] +* {xref-Governor-_queueOperations-uint256-address---uint256---bytes---bytes32-}[`++_queueOperations(, , , , )++`] +* {xref-Governor-execute-address---uint256---bytes---bytes32-}[`++execute(targets, values, calldatas, descriptionHash)++`] +* {xref-Governor-_executeOperations-uint256-address---uint256---bytes---bytes32-}[`++_executeOperations(, targets, values, calldatas, )++`] +* {xref-Governor-cancel-address---uint256---bytes---bytes32-}[`++cancel(targets, values, calldatas, descriptionHash)++`] +* {xref-Governor-_cancel-address---uint256---bytes---bytes32-}[`++_cancel(targets, values, calldatas, descriptionHash)++`] +* {xref-Governor-getVotes-address-uint256-}[`++getVotes(account, timepoint)++`] +* {xref-Governor-getVotesWithParams-address-uint256-bytes-}[`++getVotesWithParams(account, timepoint, params)++`] +* {xref-Governor-castVote-uint256-uint8-}[`++castVote(proposalId, support)++`] +* {xref-Governor-castVoteWithReason-uint256-uint8-string-}[`++castVoteWithReason(proposalId, support, reason)++`] +* {xref-Governor-castVoteWithReasonAndParams-uint256-uint8-string-bytes-}[`++castVoteWithReasonAndParams(proposalId, support, reason, params)++`] +* {xref-Governor-castVoteBySig-uint256-uint8-address-bytes-}[`++castVoteBySig(proposalId, support, voter, signature)++`] +* {xref-Governor-castVoteWithReasonAndParamsBySig-uint256-uint8-address-string-bytes-bytes-}[`++castVoteWithReasonAndParamsBySig(proposalId, support, voter, reason, params, signature)++`] +* {xref-Governor-_castVote-uint256-address-uint8-string-}[`++_castVote(proposalId, account, support, reason)++`] +* {xref-Governor-_castVote-uint256-address-uint8-string-bytes-}[`++_castVote(proposalId, account, support, reason, params)++`] +* {xref-Governor-relay-address-uint256-bytes-}[`++relay(target, value, data)++`] +* {xref-Governor-_executor--}[`++_executor()++`] +* {xref-Governor-onERC721Received-address-address-uint256-bytes-}[`++onERC721Received(, , , )++`] +* {xref-Governor-onERC1155Received-address-address-uint256-uint256-bytes-}[`++onERC1155Received(, , , , )++`] +* {xref-Governor-onERC1155BatchReceived-address-address-uint256---uint256---bytes-}[`++onERC1155BatchReceived(, , , , )++`] +* {xref-Governor-_encodeStateBitmap-enum-IGovernor-ProposalState-}[`++_encodeStateBitmap(proposalState)++`] +* {xref-Governor-_isValidDescriptionForProposer-address-string-}[`++_isValidDescriptionForProposer(proposer, description)++`] +* {xref-Governor-votingDelay--}[`++votingDelay()++`] +* {xref-Governor-votingPeriod--}[`++votingPeriod()++`] +* {xref-Governor-quorum-uint256-}[`++quorum(timepoint)++`] + +[.contract-subindex-inherited] +.IERC1155Receiver + +[.contract-subindex-inherited] +.IERC721Receiver + +[.contract-subindex-inherited] +.IGovernor +* {xref-IGovernor-COUNTING_MODE--}[`++COUNTING_MODE()++`] +* {xref-IGovernor-hasVoted-uint256-address-}[`++hasVoted(proposalId, account)++`] + +[.contract-subindex-inherited] +.IERC6372 + +[.contract-subindex-inherited] +.Nonces +* {xref-Nonces-nonces-address-}[`++nonces(owner)++`] +* {xref-Nonces-_useNonce-address-}[`++_useNonce(owner)++`] +* {xref-Nonces-_useCheckedNonce-address-uint256-}[`++_useCheckedNonce(owner, nonce)++`] + +[.contract-subindex-inherited] +.EIP712 +* {xref-EIP712-_domainSeparatorV4--}[`++_domainSeparatorV4()++`] +* {xref-EIP712-_hashTypedDataV4-bytes32-}[`++_hashTypedDataV4(structHash)++`] +* {xref-EIP712-eip712Domain--}[`++eip712Domain()++`] +* {xref-EIP712-_EIP712Name--}[`++_EIP712Name()++`] +* {xref-EIP712-_EIP712Version--}[`++_EIP712Version()++`] + +[.contract-subindex-inherited] +.IERC5267 + +[.contract-subindex-inherited] +.ERC165 + +[.contract-subindex-inherited] +.IERC165 + +-- + +[.contract-index] +.Events +-- + +[.contract-subindex-inherited] +.Governor + +[.contract-subindex-inherited] +.IERC1155Receiver + +[.contract-subindex-inherited] +.IERC721Receiver + +[.contract-subindex-inherited] +.IGovernor +* {xref-IGovernor-ProposalCreated-uint256-address-address---uint256---string---bytes---uint256-uint256-string-}[`++ProposalCreated(proposalId, proposer, targets, values, signatures, calldatas, voteStart, voteEnd, description)++`] +* {xref-IGovernor-ProposalQueued-uint256-uint256-}[`++ProposalQueued(proposalId, etaSeconds)++`] +* {xref-IGovernor-ProposalExecuted-uint256-}[`++ProposalExecuted(proposalId)++`] +* {xref-IGovernor-ProposalCanceled-uint256-}[`++ProposalCanceled(proposalId)++`] +* {xref-IGovernor-VoteCast-address-uint256-uint8-uint256-string-}[`++VoteCast(voter, proposalId, support, weight, reason)++`] +* {xref-IGovernor-VoteCastWithParams-address-uint256-uint8-uint256-string-bytes-}[`++VoteCastWithParams(voter, proposalId, support, weight, reason, params)++`] + +[.contract-subindex-inherited] +.IERC6372 + +[.contract-subindex-inherited] +.Nonces + +[.contract-subindex-inherited] +.EIP712 + +[.contract-subindex-inherited] +.IERC5267 +* {xref-IERC5267-EIP712DomainChanged--}[`++EIP712DomainChanged()++`] + +[.contract-subindex-inherited] +.ERC165 + +[.contract-subindex-inherited] +.IERC165 + +-- + +[.contract-index] +.Errors +-- + +[.contract-subindex-inherited] +.Governor + +[.contract-subindex-inherited] +.IERC1155Receiver + +[.contract-subindex-inherited] +.IERC721Receiver + +[.contract-subindex-inherited] +.IGovernor +* {xref-IGovernor-GovernorInvalidProposalLength-uint256-uint256-uint256-}[`++GovernorInvalidProposalLength(targets, calldatas, values)++`] +* {xref-IGovernor-GovernorAlreadyCastVote-address-}[`++GovernorAlreadyCastVote(voter)++`] +* {xref-IGovernor-GovernorDisabledDeposit--}[`++GovernorDisabledDeposit()++`] +* {xref-IGovernor-GovernorOnlyProposer-address-}[`++GovernorOnlyProposer(account)++`] +* {xref-IGovernor-GovernorOnlyExecutor-address-}[`++GovernorOnlyExecutor(account)++`] +* {xref-IGovernor-GovernorNonexistentProposal-uint256-}[`++GovernorNonexistentProposal(proposalId)++`] +* {xref-IGovernor-GovernorUnexpectedProposalState-uint256-enum-IGovernor-ProposalState-bytes32-}[`++GovernorUnexpectedProposalState(proposalId, current, expectedStates)++`] +* {xref-IGovernor-GovernorInvalidVotingPeriod-uint256-}[`++GovernorInvalidVotingPeriod(votingPeriod)++`] +* {xref-IGovernor-GovernorInsufficientProposerVotes-address-uint256-uint256-}[`++GovernorInsufficientProposerVotes(proposer, votes, threshold)++`] +* {xref-IGovernor-GovernorRestrictedProposer-address-}[`++GovernorRestrictedProposer(proposer)++`] +* {xref-IGovernor-GovernorInvalidVoteType--}[`++GovernorInvalidVoteType()++`] +* {xref-IGovernor-GovernorQueueNotImplemented--}[`++GovernorQueueNotImplemented()++`] +* {xref-IGovernor-GovernorNotQueuedProposal-uint256-}[`++GovernorNotQueuedProposal(proposalId)++`] +* {xref-IGovernor-GovernorAlreadyQueuedProposal-uint256-}[`++GovernorAlreadyQueuedProposal(proposalId)++`] +* {xref-IGovernor-GovernorInvalidSignature-address-}[`++GovernorInvalidSignature(voter)++`] + +[.contract-subindex-inherited] +.IERC6372 + +[.contract-subindex-inherited] +.Nonces +* {xref-Nonces-InvalidAccountNonce-address-uint256-}[`++InvalidAccountNonce(account, currentNonce)++`] + +[.contract-subindex-inherited] +.EIP712 + +[.contract-subindex-inherited] +.IERC5267 + +[.contract-subindex-inherited] +.ERC165 + +[.contract-subindex-inherited] +.IERC165 + +-- + +[.contract-item] +[[GovernorVotes-constructor-contract-IVotes-]] +==== `[.contract-item-name]#++constructor++#++(contract IVotes tokenAddress)++` [.item-kind]#internal# + +[.contract-item] +[[GovernorVotes-token--]] +==== `[.contract-item-name]#++token++#++() → contract IERC5805++` [.item-kind]#public# + +The token that voting power is sourced from. + +[.contract-item] +[[GovernorVotes-clock--]] +==== `[.contract-item-name]#++clock++#++() → uint48++` [.item-kind]#public# + +Clock (as specified in EIP-6372) is set to match the token's clock. Fallback to block numbers if the token +does not implement EIP-6372. + +[.contract-item] +[[GovernorVotes-CLOCK_MODE--]] +==== `[.contract-item-name]#++CLOCK_MODE++#++() → string++` [.item-kind]#public# + +Machine-readable description of the clock as specified in EIP-6372. + +[.contract-item] +[[GovernorVotes-_getVotes-address-uint256-bytes-]] +==== `[.contract-item-name]#++_getVotes++#++(address account, uint256 timepoint, bytes) → uint256++` [.item-kind]#internal# + +:QuorumNumeratorUpdated: pass:normal[xref:#GovernorVotesQuorumFraction-QuorumNumeratorUpdated-uint256-uint256-[`++QuorumNumeratorUpdated++`]] +:GovernorInvalidQuorumFraction: pass:normal[xref:#GovernorVotesQuorumFraction-GovernorInvalidQuorumFraction-uint256-uint256-[`++GovernorInvalidQuorumFraction++`]] +:constructor: pass:normal[xref:#GovernorVotesQuorumFraction-constructor-uint256-[`++constructor++`]] +:quorumNumerator: pass:normal[xref:#GovernorVotesQuorumFraction-quorumNumerator--[`++quorumNumerator++`]] +:quorumNumerator: pass:normal[xref:#GovernorVotesQuorumFraction-quorumNumerator-uint256-[`++quorumNumerator++`]] +:quorumDenominator: pass:normal[xref:#GovernorVotesQuorumFraction-quorumDenominator--[`++quorumDenominator++`]] +:quorum: pass:normal[xref:#GovernorVotesQuorumFraction-quorum-uint256-[`++quorum++`]] +:updateQuorumNumerator: pass:normal[xref:#GovernorVotesQuorumFraction-updateQuorumNumerator-uint256-[`++updateQuorumNumerator++`]] +:_updateQuorumNumerator: pass:normal[xref:#GovernorVotesQuorumFraction-_updateQuorumNumerator-uint256-[`++_updateQuorumNumerator++`]] + +[.contract] +[[GovernorVotesQuorumFraction]] +=== `++GovernorVotesQuorumFraction++` link:https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v5.0.0-rc.0/contracts/governance/extensions/GovernorVotesQuorumFraction.sol[{github-icon},role=heading-link] + +[.hljs-theme-light.nopadding] +```solidity +import "@openzeppelin/contracts/governance/extensions/GovernorVotesQuorumFraction.sol"; +``` + +Extension of {Governor} for voting weight extraction from an {ERC20Votes} token and a quorum expressed as a +fraction of the total supply. + +[.contract-index] +.Functions +-- +* {xref-GovernorVotesQuorumFraction-constructor-uint256-}[`++constructor(quorumNumeratorValue)++`] +* {xref-GovernorVotesQuorumFraction-quorumNumerator--}[`++quorumNumerator()++`] +* {xref-GovernorVotesQuorumFraction-quorumNumerator-uint256-}[`++quorumNumerator(timepoint)++`] +* {xref-GovernorVotesQuorumFraction-quorumDenominator--}[`++quorumDenominator()++`] +* {xref-GovernorVotesQuorumFraction-quorum-uint256-}[`++quorum(timepoint)++`] +* {xref-GovernorVotesQuorumFraction-updateQuorumNumerator-uint256-}[`++updateQuorumNumerator(newQuorumNumerator)++`] +* {xref-GovernorVotesQuorumFraction-_updateQuorumNumerator-uint256-}[`++_updateQuorumNumerator(newQuorumNumerator)++`] + +[.contract-subindex-inherited] +.GovernorVotes +* {xref-GovernorVotes-token--}[`++token()++`] +* {xref-GovernorVotes-clock--}[`++clock()++`] +* {xref-GovernorVotes-CLOCK_MODE--}[`++CLOCK_MODE()++`] +* {xref-GovernorVotes-_getVotes-address-uint256-bytes-}[`++_getVotes(account, timepoint, )++`] + +[.contract-subindex-inherited] +.Governor +* {xref-Governor-receive--}[`++receive()++`] +* {xref-Governor-supportsInterface-bytes4-}[`++supportsInterface(interfaceId)++`] +* {xref-Governor-name--}[`++name()++`] +* {xref-Governor-version--}[`++version()++`] +* {xref-Governor-hashProposal-address---uint256---bytes---bytes32-}[`++hashProposal(targets, values, calldatas, descriptionHash)++`] +* {xref-Governor-state-uint256-}[`++state(proposalId)++`] +* {xref-Governor-proposalThreshold--}[`++proposalThreshold()++`] +* {xref-Governor-proposalSnapshot-uint256-}[`++proposalSnapshot(proposalId)++`] +* {xref-Governor-proposalDeadline-uint256-}[`++proposalDeadline(proposalId)++`] +* {xref-Governor-proposalProposer-uint256-}[`++proposalProposer(proposalId)++`] +* {xref-Governor-proposalEta-uint256-}[`++proposalEta(proposalId)++`] +* {xref-Governor-proposalNeedsQueuing-uint256-}[`++proposalNeedsQueuing()++`] +* {xref-Governor-_checkGovernance--}[`++_checkGovernance()++`] +* {xref-Governor-_quorumReached-uint256-}[`++_quorumReached(proposalId)++`] +* {xref-Governor-_voteSucceeded-uint256-}[`++_voteSucceeded(proposalId)++`] +* {xref-Governor-_countVote-uint256-address-uint8-uint256-bytes-}[`++_countVote(proposalId, account, support, weight, params)++`] +* {xref-Governor-_defaultParams--}[`++_defaultParams()++`] +* {xref-Governor-propose-address---uint256---bytes---string-}[`++propose(targets, values, calldatas, description)++`] +* {xref-Governor-_propose-address---uint256---bytes---string-address-}[`++_propose(targets, values, calldatas, description, proposer)++`] +* {xref-Governor-queue-address---uint256---bytes---bytes32-}[`++queue(targets, values, calldatas, descriptionHash)++`] +* {xref-Governor-_queueOperations-uint256-address---uint256---bytes---bytes32-}[`++_queueOperations(, , , , )++`] +* {xref-Governor-execute-address---uint256---bytes---bytes32-}[`++execute(targets, values, calldatas, descriptionHash)++`] +* {xref-Governor-_executeOperations-uint256-address---uint256---bytes---bytes32-}[`++_executeOperations(, targets, values, calldatas, )++`] +* {xref-Governor-cancel-address---uint256---bytes---bytes32-}[`++cancel(targets, values, calldatas, descriptionHash)++`] +* {xref-Governor-_cancel-address---uint256---bytes---bytes32-}[`++_cancel(targets, values, calldatas, descriptionHash)++`] +* {xref-Governor-getVotes-address-uint256-}[`++getVotes(account, timepoint)++`] +* {xref-Governor-getVotesWithParams-address-uint256-bytes-}[`++getVotesWithParams(account, timepoint, params)++`] +* {xref-Governor-castVote-uint256-uint8-}[`++castVote(proposalId, support)++`] +* {xref-Governor-castVoteWithReason-uint256-uint8-string-}[`++castVoteWithReason(proposalId, support, reason)++`] +* {xref-Governor-castVoteWithReasonAndParams-uint256-uint8-string-bytes-}[`++castVoteWithReasonAndParams(proposalId, support, reason, params)++`] +* {xref-Governor-castVoteBySig-uint256-uint8-address-bytes-}[`++castVoteBySig(proposalId, support, voter, signature)++`] +* {xref-Governor-castVoteWithReasonAndParamsBySig-uint256-uint8-address-string-bytes-bytes-}[`++castVoteWithReasonAndParamsBySig(proposalId, support, voter, reason, params, signature)++`] +* {xref-Governor-_castVote-uint256-address-uint8-string-}[`++_castVote(proposalId, account, support, reason)++`] +* {xref-Governor-_castVote-uint256-address-uint8-string-bytes-}[`++_castVote(proposalId, account, support, reason, params)++`] +* {xref-Governor-relay-address-uint256-bytes-}[`++relay(target, value, data)++`] +* {xref-Governor-_executor--}[`++_executor()++`] +* {xref-Governor-onERC721Received-address-address-uint256-bytes-}[`++onERC721Received(, , , )++`] +* {xref-Governor-onERC1155Received-address-address-uint256-uint256-bytes-}[`++onERC1155Received(, , , , )++`] +* {xref-Governor-onERC1155BatchReceived-address-address-uint256---uint256---bytes-}[`++onERC1155BatchReceived(, , , , )++`] +* {xref-Governor-_encodeStateBitmap-enum-IGovernor-ProposalState-}[`++_encodeStateBitmap(proposalState)++`] +* {xref-Governor-_isValidDescriptionForProposer-address-string-}[`++_isValidDescriptionForProposer(proposer, description)++`] +* {xref-Governor-votingDelay--}[`++votingDelay()++`] +* {xref-Governor-votingPeriod--}[`++votingPeriod()++`] + +[.contract-subindex-inherited] +.IERC1155Receiver + +[.contract-subindex-inherited] +.IERC721Receiver + +[.contract-subindex-inherited] +.IGovernor +* {xref-IGovernor-COUNTING_MODE--}[`++COUNTING_MODE()++`] +* {xref-IGovernor-hasVoted-uint256-address-}[`++hasVoted(proposalId, account)++`] + +[.contract-subindex-inherited] +.IERC6372 + +[.contract-subindex-inherited] +.Nonces +* {xref-Nonces-nonces-address-}[`++nonces(owner)++`] +* {xref-Nonces-_useNonce-address-}[`++_useNonce(owner)++`] +* {xref-Nonces-_useCheckedNonce-address-uint256-}[`++_useCheckedNonce(owner, nonce)++`] + +[.contract-subindex-inherited] +.EIP712 +* {xref-EIP712-_domainSeparatorV4--}[`++_domainSeparatorV4()++`] +* {xref-EIP712-_hashTypedDataV4-bytes32-}[`++_hashTypedDataV4(structHash)++`] +* {xref-EIP712-eip712Domain--}[`++eip712Domain()++`] +* {xref-EIP712-_EIP712Name--}[`++_EIP712Name()++`] +* {xref-EIP712-_EIP712Version--}[`++_EIP712Version()++`] + +[.contract-subindex-inherited] +.IERC5267 + +[.contract-subindex-inherited] +.ERC165 + +[.contract-subindex-inherited] +.IERC165 + +-- + +[.contract-index] +.Events +-- +* {xref-GovernorVotesQuorumFraction-QuorumNumeratorUpdated-uint256-uint256-}[`++QuorumNumeratorUpdated(oldQuorumNumerator, newQuorumNumerator)++`] + +[.contract-subindex-inherited] +.GovernorVotes + +[.contract-subindex-inherited] +.Governor + +[.contract-subindex-inherited] +.IERC1155Receiver + +[.contract-subindex-inherited] +.IERC721Receiver + +[.contract-subindex-inherited] +.IGovernor +* {xref-IGovernor-ProposalCreated-uint256-address-address---uint256---string---bytes---uint256-uint256-string-}[`++ProposalCreated(proposalId, proposer, targets, values, signatures, calldatas, voteStart, voteEnd, description)++`] +* {xref-IGovernor-ProposalQueued-uint256-uint256-}[`++ProposalQueued(proposalId, etaSeconds)++`] +* {xref-IGovernor-ProposalExecuted-uint256-}[`++ProposalExecuted(proposalId)++`] +* {xref-IGovernor-ProposalCanceled-uint256-}[`++ProposalCanceled(proposalId)++`] +* {xref-IGovernor-VoteCast-address-uint256-uint8-uint256-string-}[`++VoteCast(voter, proposalId, support, weight, reason)++`] +* {xref-IGovernor-VoteCastWithParams-address-uint256-uint8-uint256-string-bytes-}[`++VoteCastWithParams(voter, proposalId, support, weight, reason, params)++`] + +[.contract-subindex-inherited] +.IERC6372 + +[.contract-subindex-inherited] +.Nonces + +[.contract-subindex-inherited] +.EIP712 + +[.contract-subindex-inherited] +.IERC5267 +* {xref-IERC5267-EIP712DomainChanged--}[`++EIP712DomainChanged()++`] + +[.contract-subindex-inherited] +.ERC165 + +[.contract-subindex-inherited] +.IERC165 + +-- + +[.contract-index] +.Errors +-- +* {xref-GovernorVotesQuorumFraction-GovernorInvalidQuorumFraction-uint256-uint256-}[`++GovernorInvalidQuorumFraction(quorumNumerator, quorumDenominator)++`] + +[.contract-subindex-inherited] +.GovernorVotes + +[.contract-subindex-inherited] +.Governor + +[.contract-subindex-inherited] +.IERC1155Receiver + +[.contract-subindex-inherited] +.IERC721Receiver + +[.contract-subindex-inherited] +.IGovernor +* {xref-IGovernor-GovernorInvalidProposalLength-uint256-uint256-uint256-}[`++GovernorInvalidProposalLength(targets, calldatas, values)++`] +* {xref-IGovernor-GovernorAlreadyCastVote-address-}[`++GovernorAlreadyCastVote(voter)++`] +* {xref-IGovernor-GovernorDisabledDeposit--}[`++GovernorDisabledDeposit()++`] +* {xref-IGovernor-GovernorOnlyProposer-address-}[`++GovernorOnlyProposer(account)++`] +* {xref-IGovernor-GovernorOnlyExecutor-address-}[`++GovernorOnlyExecutor(account)++`] +* {xref-IGovernor-GovernorNonexistentProposal-uint256-}[`++GovernorNonexistentProposal(proposalId)++`] +* {xref-IGovernor-GovernorUnexpectedProposalState-uint256-enum-IGovernor-ProposalState-bytes32-}[`++GovernorUnexpectedProposalState(proposalId, current, expectedStates)++`] +* {xref-IGovernor-GovernorInvalidVotingPeriod-uint256-}[`++GovernorInvalidVotingPeriod(votingPeriod)++`] +* {xref-IGovernor-GovernorInsufficientProposerVotes-address-uint256-uint256-}[`++GovernorInsufficientProposerVotes(proposer, votes, threshold)++`] +* {xref-IGovernor-GovernorRestrictedProposer-address-}[`++GovernorRestrictedProposer(proposer)++`] +* {xref-IGovernor-GovernorInvalidVoteType--}[`++GovernorInvalidVoteType()++`] +* {xref-IGovernor-GovernorQueueNotImplemented--}[`++GovernorQueueNotImplemented()++`] +* {xref-IGovernor-GovernorNotQueuedProposal-uint256-}[`++GovernorNotQueuedProposal(proposalId)++`] +* {xref-IGovernor-GovernorAlreadyQueuedProposal-uint256-}[`++GovernorAlreadyQueuedProposal(proposalId)++`] +* {xref-IGovernor-GovernorInvalidSignature-address-}[`++GovernorInvalidSignature(voter)++`] + +[.contract-subindex-inherited] +.IERC6372 + +[.contract-subindex-inherited] +.Nonces +* {xref-Nonces-InvalidAccountNonce-address-uint256-}[`++InvalidAccountNonce(account, currentNonce)++`] + +[.contract-subindex-inherited] +.EIP712 + +[.contract-subindex-inherited] +.IERC5267 + +[.contract-subindex-inherited] +.ERC165 + +[.contract-subindex-inherited] +.IERC165 + +-- + +[.contract-item] +[[GovernorVotesQuorumFraction-constructor-uint256-]] +==== `[.contract-item-name]#++constructor++#++(uint256 quorumNumeratorValue)++` [.item-kind]#internal# + +Initialize quorum as a fraction of the token's total supply. + +The fraction is specified as `numerator / denominator`. By default the denominator is 100, so quorum is +specified as a percent: a numerator of 10 corresponds to quorum being 10% of total supply. The denominator can be +customized by overriding {quorumDenominator}. + +[.contract-item] +[[GovernorVotesQuorumFraction-quorumNumerator--]] +==== `[.contract-item-name]#++quorumNumerator++#++() → uint256++` [.item-kind]#public# + +Returns the current quorum numerator. See {quorumDenominator}. + +[.contract-item] +[[GovernorVotesQuorumFraction-quorumNumerator-uint256-]] +==== `[.contract-item-name]#++quorumNumerator++#++(uint256 timepoint) → uint256++` [.item-kind]#public# + +Returns the quorum numerator at a specific timepoint. See {quorumDenominator}. + +[.contract-item] +[[GovernorVotesQuorumFraction-quorumDenominator--]] +==== `[.contract-item-name]#++quorumDenominator++#++() → uint256++` [.item-kind]#public# + +Returns the quorum denominator. Defaults to 100, but may be overridden. + +[.contract-item] +[[GovernorVotesQuorumFraction-quorum-uint256-]] +==== `[.contract-item-name]#++quorum++#++(uint256 timepoint) → uint256++` [.item-kind]#public# + +Returns the quorum for a timepoint, in terms of number of votes: `supply * numerator / denominator`. + +[.contract-item] +[[GovernorVotesQuorumFraction-updateQuorumNumerator-uint256-]] +==== `[.contract-item-name]#++updateQuorumNumerator++#++(uint256 newQuorumNumerator)++` [.item-kind]#external# + +Changes the quorum numerator. + +Emits a {QuorumNumeratorUpdated} event. + +Requirements: + +- Must be called through a governance proposal. +- New numerator must be smaller or equal to the denominator. + +[.contract-item] +[[GovernorVotesQuorumFraction-_updateQuorumNumerator-uint256-]] +==== `[.contract-item-name]#++_updateQuorumNumerator++#++(uint256 newQuorumNumerator)++` [.item-kind]#internal# + +Changes the quorum numerator. + +Emits a {QuorumNumeratorUpdated} event. + +Requirements: + +- New numerator must be smaller or equal to the denominator. + +[.contract-item] +[[GovernorVotesQuorumFraction-QuorumNumeratorUpdated-uint256-uint256-]] +==== `[.contract-item-name]#++QuorumNumeratorUpdated++#++(uint256 oldQuorumNumerator, uint256 newQuorumNumerator)++` [.item-kind]#event# + +[.contract-item] +[[GovernorVotesQuorumFraction-GovernorInvalidQuorumFraction-uint256-uint256-]] +==== `[.contract-item-name]#++GovernorInvalidQuorumFraction++#++(uint256 quorumNumerator, uint256 quorumDenominator)++` [.item-kind]#error# + +The quorum set is not a valid fraction. + +=== Extensions + +:TimelockChange: pass:normal[xref:#GovernorTimelockControl-TimelockChange-address-address-[`++TimelockChange++`]] +:constructor: pass:normal[xref:#GovernorTimelockControl-constructor-contract-TimelockController-[`++constructor++`]] +:state: pass:normal[xref:#GovernorTimelockControl-state-uint256-[`++state++`]] +:timelock: pass:normal[xref:#GovernorTimelockControl-timelock--[`++timelock++`]] +:proposalNeedsQueuing: pass:normal[xref:#GovernorTimelockControl-proposalNeedsQueuing-uint256-[`++proposalNeedsQueuing++`]] +:_queueOperations: pass:normal[xref:#GovernorTimelockControl-_queueOperations-uint256-address---uint256---bytes---bytes32-[`++_queueOperations++`]] +:_executeOperations: pass:normal[xref:#GovernorTimelockControl-_executeOperations-uint256-address---uint256---bytes---bytes32-[`++_executeOperations++`]] +:_cancel: pass:normal[xref:#GovernorTimelockControl-_cancel-address---uint256---bytes---bytes32-[`++_cancel++`]] +:_executor: pass:normal[xref:#GovernorTimelockControl-_executor--[`++_executor++`]] +:updateTimelock: pass:normal[xref:#GovernorTimelockControl-updateTimelock-contract-TimelockController-[`++updateTimelock++`]] + +[.contract] +[[GovernorTimelockControl]] +=== `++GovernorTimelockControl++` link:https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v5.0.0-rc.0/contracts/governance/extensions/GovernorTimelockControl.sol[{github-icon},role=heading-link] + +[.hljs-theme-light.nopadding] +```solidity +import "@openzeppelin/contracts/governance/extensions/GovernorTimelockControl.sol"; +``` + +Extension of {Governor} that binds the execution process to an instance of {TimelockController}. This adds a +delay, enforced by the {TimelockController} to all successful proposal (in addition to the voting duration). The +{Governor} needs the proposer (and ideally the executor) roles for the {Governor} to work properly. + +Using this model means the proposal will be operated by the {TimelockController} and not by the {Governor}. Thus, +the assets and permissions must be attached to the {TimelockController}. Any asset sent to the {Governor} will be +inaccessible from a proposal, unless executed via {Governor-relay}. + +WARNING: Setting up the TimelockController to have additional proposers or cancellers besides the governor is very +risky, as it grants them the ability to: 1) execute operations as the timelock, and thus possibly performing +operations or accessing funds that are expected to only be accessible through a vote, and 2) block governance +proposals that have been approved by the voters, effectively executing a Denial of Service attack. + +NOTE: `AccessManager` does not support scheduling more than one operation with the same target and calldata at +the same time. See {AccessManager-schedule} for a workaround. + +[.contract-index] +.Functions +-- +* {xref-GovernorTimelockControl-constructor-contract-TimelockController-}[`++constructor(timelockAddress)++`] +* {xref-GovernorTimelockControl-state-uint256-}[`++state(proposalId)++`] +* {xref-GovernorTimelockControl-timelock--}[`++timelock()++`] +* {xref-GovernorTimelockControl-proposalNeedsQueuing-uint256-}[`++proposalNeedsQueuing()++`] +* {xref-GovernorTimelockControl-_queueOperations-uint256-address---uint256---bytes---bytes32-}[`++_queueOperations(proposalId, targets, values, calldatas, descriptionHash)++`] +* {xref-GovernorTimelockControl-_executeOperations-uint256-address---uint256---bytes---bytes32-}[`++_executeOperations(proposalId, targets, values, calldatas, descriptionHash)++`] +* {xref-GovernorTimelockControl-_cancel-address---uint256---bytes---bytes32-}[`++_cancel(targets, values, calldatas, descriptionHash)++`] +* {xref-GovernorTimelockControl-_executor--}[`++_executor()++`] +* {xref-GovernorTimelockControl-updateTimelock-contract-TimelockController-}[`++updateTimelock(newTimelock)++`] + +[.contract-subindex-inherited] +.Governor +* {xref-Governor-receive--}[`++receive()++`] +* {xref-Governor-supportsInterface-bytes4-}[`++supportsInterface(interfaceId)++`] +* {xref-Governor-name--}[`++name()++`] +* {xref-Governor-version--}[`++version()++`] +* {xref-Governor-hashProposal-address---uint256---bytes---bytes32-}[`++hashProposal(targets, values, calldatas, descriptionHash)++`] +* {xref-Governor-proposalThreshold--}[`++proposalThreshold()++`] +* {xref-Governor-proposalSnapshot-uint256-}[`++proposalSnapshot(proposalId)++`] +* {xref-Governor-proposalDeadline-uint256-}[`++proposalDeadline(proposalId)++`] +* {xref-Governor-proposalProposer-uint256-}[`++proposalProposer(proposalId)++`] +* {xref-Governor-proposalEta-uint256-}[`++proposalEta(proposalId)++`] +* {xref-Governor-_checkGovernance--}[`++_checkGovernance()++`] +* {xref-Governor-_quorumReached-uint256-}[`++_quorumReached(proposalId)++`] +* {xref-Governor-_voteSucceeded-uint256-}[`++_voteSucceeded(proposalId)++`] +* {xref-Governor-_getVotes-address-uint256-bytes-}[`++_getVotes(account, timepoint, params)++`] +* {xref-Governor-_countVote-uint256-address-uint8-uint256-bytes-}[`++_countVote(proposalId, account, support, weight, params)++`] +* {xref-Governor-_defaultParams--}[`++_defaultParams()++`] +* {xref-Governor-propose-address---uint256---bytes---string-}[`++propose(targets, values, calldatas, description)++`] +* {xref-Governor-_propose-address---uint256---bytes---string-address-}[`++_propose(targets, values, calldatas, description, proposer)++`] +* {xref-Governor-queue-address---uint256---bytes---bytes32-}[`++queue(targets, values, calldatas, descriptionHash)++`] +* {xref-Governor-execute-address---uint256---bytes---bytes32-}[`++execute(targets, values, calldatas, descriptionHash)++`] +* {xref-Governor-cancel-address---uint256---bytes---bytes32-}[`++cancel(targets, values, calldatas, descriptionHash)++`] +* {xref-Governor-getVotes-address-uint256-}[`++getVotes(account, timepoint)++`] +* {xref-Governor-getVotesWithParams-address-uint256-bytes-}[`++getVotesWithParams(account, timepoint, params)++`] +* {xref-Governor-castVote-uint256-uint8-}[`++castVote(proposalId, support)++`] +* {xref-Governor-castVoteWithReason-uint256-uint8-string-}[`++castVoteWithReason(proposalId, support, reason)++`] +* {xref-Governor-castVoteWithReasonAndParams-uint256-uint8-string-bytes-}[`++castVoteWithReasonAndParams(proposalId, support, reason, params)++`] +* {xref-Governor-castVoteBySig-uint256-uint8-address-bytes-}[`++castVoteBySig(proposalId, support, voter, signature)++`] +* {xref-Governor-castVoteWithReasonAndParamsBySig-uint256-uint8-address-string-bytes-bytes-}[`++castVoteWithReasonAndParamsBySig(proposalId, support, voter, reason, params, signature)++`] +* {xref-Governor-_castVote-uint256-address-uint8-string-}[`++_castVote(proposalId, account, support, reason)++`] +* {xref-Governor-_castVote-uint256-address-uint8-string-bytes-}[`++_castVote(proposalId, account, support, reason, params)++`] +* {xref-Governor-relay-address-uint256-bytes-}[`++relay(target, value, data)++`] +* {xref-Governor-onERC721Received-address-address-uint256-bytes-}[`++onERC721Received(, , , )++`] +* {xref-Governor-onERC1155Received-address-address-uint256-uint256-bytes-}[`++onERC1155Received(, , , , )++`] +* {xref-Governor-onERC1155BatchReceived-address-address-uint256---uint256---bytes-}[`++onERC1155BatchReceived(, , , , )++`] +* {xref-Governor-_encodeStateBitmap-enum-IGovernor-ProposalState-}[`++_encodeStateBitmap(proposalState)++`] +* {xref-Governor-_isValidDescriptionForProposer-address-string-}[`++_isValidDescriptionForProposer(proposer, description)++`] +* {xref-Governor-clock--}[`++clock()++`] +* {xref-Governor-CLOCK_MODE--}[`++CLOCK_MODE()++`] +* {xref-Governor-votingDelay--}[`++votingDelay()++`] +* {xref-Governor-votingPeriod--}[`++votingPeriod()++`] +* {xref-Governor-quorum-uint256-}[`++quorum(timepoint)++`] + +[.contract-subindex-inherited] +.IERC1155Receiver + +[.contract-subindex-inherited] +.IERC721Receiver + +[.contract-subindex-inherited] +.IGovernor +* {xref-IGovernor-COUNTING_MODE--}[`++COUNTING_MODE()++`] +* {xref-IGovernor-hasVoted-uint256-address-}[`++hasVoted(proposalId, account)++`] + +[.contract-subindex-inherited] +.IERC6372 + +[.contract-subindex-inherited] +.Nonces +* {xref-Nonces-nonces-address-}[`++nonces(owner)++`] +* {xref-Nonces-_useNonce-address-}[`++_useNonce(owner)++`] +* {xref-Nonces-_useCheckedNonce-address-uint256-}[`++_useCheckedNonce(owner, nonce)++`] + +[.contract-subindex-inherited] +.EIP712 +* {xref-EIP712-_domainSeparatorV4--}[`++_domainSeparatorV4()++`] +* {xref-EIP712-_hashTypedDataV4-bytes32-}[`++_hashTypedDataV4(structHash)++`] +* {xref-EIP712-eip712Domain--}[`++eip712Domain()++`] +* {xref-EIP712-_EIP712Name--}[`++_EIP712Name()++`] +* {xref-EIP712-_EIP712Version--}[`++_EIP712Version()++`] + +[.contract-subindex-inherited] +.IERC5267 + +[.contract-subindex-inherited] +.ERC165 + +[.contract-subindex-inherited] +.IERC165 + +-- + +[.contract-index] +.Events +-- +* {xref-GovernorTimelockControl-TimelockChange-address-address-}[`++TimelockChange(oldTimelock, newTimelock)++`] + +[.contract-subindex-inherited] +.Governor + +[.contract-subindex-inherited] +.IERC1155Receiver + +[.contract-subindex-inherited] +.IERC721Receiver + +[.contract-subindex-inherited] +.IGovernor +* {xref-IGovernor-ProposalCreated-uint256-address-address---uint256---string---bytes---uint256-uint256-string-}[`++ProposalCreated(proposalId, proposer, targets, values, signatures, calldatas, voteStart, voteEnd, description)++`] +* {xref-IGovernor-ProposalQueued-uint256-uint256-}[`++ProposalQueued(proposalId, etaSeconds)++`] +* {xref-IGovernor-ProposalExecuted-uint256-}[`++ProposalExecuted(proposalId)++`] +* {xref-IGovernor-ProposalCanceled-uint256-}[`++ProposalCanceled(proposalId)++`] +* {xref-IGovernor-VoteCast-address-uint256-uint8-uint256-string-}[`++VoteCast(voter, proposalId, support, weight, reason)++`] +* {xref-IGovernor-VoteCastWithParams-address-uint256-uint8-uint256-string-bytes-}[`++VoteCastWithParams(voter, proposalId, support, weight, reason, params)++`] + +[.contract-subindex-inherited] +.IERC6372 + +[.contract-subindex-inherited] +.Nonces + +[.contract-subindex-inherited] +.EIP712 + +[.contract-subindex-inherited] +.IERC5267 +* {xref-IERC5267-EIP712DomainChanged--}[`++EIP712DomainChanged()++`] + +[.contract-subindex-inherited] +.ERC165 + +[.contract-subindex-inherited] +.IERC165 + +-- + +[.contract-index] +.Errors +-- + +[.contract-subindex-inherited] +.Governor + +[.contract-subindex-inherited] +.IERC1155Receiver + +[.contract-subindex-inherited] +.IERC721Receiver + +[.contract-subindex-inherited] +.IGovernor +* {xref-IGovernor-GovernorInvalidProposalLength-uint256-uint256-uint256-}[`++GovernorInvalidProposalLength(targets, calldatas, values)++`] +* {xref-IGovernor-GovernorAlreadyCastVote-address-}[`++GovernorAlreadyCastVote(voter)++`] +* {xref-IGovernor-GovernorDisabledDeposit--}[`++GovernorDisabledDeposit()++`] +* {xref-IGovernor-GovernorOnlyProposer-address-}[`++GovernorOnlyProposer(account)++`] +* {xref-IGovernor-GovernorOnlyExecutor-address-}[`++GovernorOnlyExecutor(account)++`] +* {xref-IGovernor-GovernorNonexistentProposal-uint256-}[`++GovernorNonexistentProposal(proposalId)++`] +* {xref-IGovernor-GovernorUnexpectedProposalState-uint256-enum-IGovernor-ProposalState-bytes32-}[`++GovernorUnexpectedProposalState(proposalId, current, expectedStates)++`] +* {xref-IGovernor-GovernorInvalidVotingPeriod-uint256-}[`++GovernorInvalidVotingPeriod(votingPeriod)++`] +* {xref-IGovernor-GovernorInsufficientProposerVotes-address-uint256-uint256-}[`++GovernorInsufficientProposerVotes(proposer, votes, threshold)++`] +* {xref-IGovernor-GovernorRestrictedProposer-address-}[`++GovernorRestrictedProposer(proposer)++`] +* {xref-IGovernor-GovernorInvalidVoteType--}[`++GovernorInvalidVoteType()++`] +* {xref-IGovernor-GovernorQueueNotImplemented--}[`++GovernorQueueNotImplemented()++`] +* {xref-IGovernor-GovernorNotQueuedProposal-uint256-}[`++GovernorNotQueuedProposal(proposalId)++`] +* {xref-IGovernor-GovernorAlreadyQueuedProposal-uint256-}[`++GovernorAlreadyQueuedProposal(proposalId)++`] +* {xref-IGovernor-GovernorInvalidSignature-address-}[`++GovernorInvalidSignature(voter)++`] + +[.contract-subindex-inherited] +.IERC6372 + +[.contract-subindex-inherited] +.Nonces +* {xref-Nonces-InvalidAccountNonce-address-uint256-}[`++InvalidAccountNonce(account, currentNonce)++`] + +[.contract-subindex-inherited] +.EIP712 + +[.contract-subindex-inherited] +.IERC5267 + +[.contract-subindex-inherited] +.ERC165 + +[.contract-subindex-inherited] +.IERC165 + +-- + +[.contract-item] +[[GovernorTimelockControl-constructor-contract-TimelockController-]] +==== `[.contract-item-name]#++constructor++#++(contract TimelockController timelockAddress)++` [.item-kind]#internal# + +Set the timelock. + +[.contract-item] +[[GovernorTimelockControl-state-uint256-]] +==== `[.contract-item-name]#++state++#++(uint256 proposalId) → enum IGovernor.ProposalState++` [.item-kind]#public# + +Overridden version of the {Governor-state} function that considers the status reported by the timelock. + +[.contract-item] +[[GovernorTimelockControl-timelock--]] +==== `[.contract-item-name]#++timelock++#++() → address++` [.item-kind]#public# + +Public accessor to check the address of the timelock + +[.contract-item] +[[GovernorTimelockControl-proposalNeedsQueuing-uint256-]] +==== `[.contract-item-name]#++proposalNeedsQueuing++#++(uint256) → bool++` [.item-kind]#public# + +See {IGovernor-proposalNeedsQueuing}. + +[.contract-item] +[[GovernorTimelockControl-_queueOperations-uint256-address---uint256---bytes---bytes32-]] +==== `[.contract-item-name]#++_queueOperations++#++(uint256 proposalId, address[] targets, uint256[] values, bytes[] calldatas, bytes32 descriptionHash) → uint48++` [.item-kind]#internal# + +Function to queue a proposal to the timelock. + +[.contract-item] +[[GovernorTimelockControl-_executeOperations-uint256-address---uint256---bytes---bytes32-]] +==== `[.contract-item-name]#++_executeOperations++#++(uint256 proposalId, address[] targets, uint256[] values, bytes[] calldatas, bytes32 descriptionHash)++` [.item-kind]#internal# + +Overridden version of the {Governor-_executeOperations} function that runs the already queued proposal +through the timelock. + +[.contract-item] +[[GovernorTimelockControl-_cancel-address---uint256---bytes---bytes32-]] +==== `[.contract-item-name]#++_cancel++#++(address[] targets, uint256[] values, bytes[] calldatas, bytes32 descriptionHash) → uint256++` [.item-kind]#internal# + +Overridden version of the {Governor-_cancel} function to cancel the timelocked proposal if it has already +been queued. + +[.contract-item] +[[GovernorTimelockControl-_executor--]] +==== `[.contract-item-name]#++_executor++#++() → address++` [.item-kind]#internal# + +Address through which the governor executes action. In this case, the timelock. + +[.contract-item] +[[GovernorTimelockControl-updateTimelock-contract-TimelockController-]] +==== `[.contract-item-name]#++updateTimelock++#++(contract TimelockController newTimelock)++` [.item-kind]#external# + +Public endpoint to update the underlying timelock instance. Restricted to the timelock itself, so updates +must be proposed, scheduled, and executed through governance proposals. + +CAUTION: It is not recommended to change the timelock while there are other queued governance proposals. + +[.contract-item] +[[GovernorTimelockControl-TimelockChange-address-address-]] +==== `[.contract-item-name]#++TimelockChange++#++(address oldTimelock, address newTimelock)++` [.item-kind]#event# + +Emitted when the timelock controller used for proposal execution is modified. + +:TimelockChange: pass:normal[xref:#GovernorTimelockCompound-TimelockChange-address-address-[`++TimelockChange++`]] +:constructor: pass:normal[xref:#GovernorTimelockCompound-constructor-contract-ICompoundTimelock-[`++constructor++`]] +:state: pass:normal[xref:#GovernorTimelockCompound-state-uint256-[`++state++`]] +:timelock: pass:normal[xref:#GovernorTimelockCompound-timelock--[`++timelock++`]] +:proposalNeedsQueuing: pass:normal[xref:#GovernorTimelockCompound-proposalNeedsQueuing-uint256-[`++proposalNeedsQueuing++`]] +:_queueOperations: pass:normal[xref:#GovernorTimelockCompound-_queueOperations-uint256-address---uint256---bytes---bytes32-[`++_queueOperations++`]] +:_executeOperations: pass:normal[xref:#GovernorTimelockCompound-_executeOperations-uint256-address---uint256---bytes---bytes32-[`++_executeOperations++`]] +:_cancel: pass:normal[xref:#GovernorTimelockCompound-_cancel-address---uint256---bytes---bytes32-[`++_cancel++`]] +:_executor: pass:normal[xref:#GovernorTimelockCompound-_executor--[`++_executor++`]] +:__acceptAdmin: pass:normal[xref:#GovernorTimelockCompound-__acceptAdmin--[`++__acceptAdmin++`]] +:updateTimelock: pass:normal[xref:#GovernorTimelockCompound-updateTimelock-contract-ICompoundTimelock-[`++updateTimelock++`]] + +[.contract] +[[GovernorTimelockCompound]] +=== `++GovernorTimelockCompound++` link:https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v5.0.0-rc.0/contracts/governance/extensions/GovernorTimelockCompound.sol[{github-icon},role=heading-link] + +[.hljs-theme-light.nopadding] +```solidity +import "@openzeppelin/contracts/governance/extensions/GovernorTimelockCompound.sol"; +``` + +Extension of {Governor} that binds the execution process to a Compound Timelock. This adds a delay, enforced by +the external timelock to all successful proposal (in addition to the voting duration). The {Governor} needs to be +the admin of the timelock for any operation to be performed. A public, unrestricted, +{GovernorTimelockCompound-__acceptAdmin} is available to accept ownership of the timelock. + +Using this model means the proposal will be operated by the {TimelockController} and not by the {Governor}. Thus, +the assets and permissions must be attached to the {TimelockController}. Any asset sent to the {Governor} will be +inaccessible. + +[.contract-index] +.Functions +-- +* {xref-GovernorTimelockCompound-constructor-contract-ICompoundTimelock-}[`++constructor(timelockAddress)++`] +* {xref-GovernorTimelockCompound-state-uint256-}[`++state(proposalId)++`] +* {xref-GovernorTimelockCompound-timelock--}[`++timelock()++`] +* {xref-GovernorTimelockCompound-proposalNeedsQueuing-uint256-}[`++proposalNeedsQueuing()++`] +* {xref-GovernorTimelockCompound-_queueOperations-uint256-address---uint256---bytes---bytes32-}[`++_queueOperations(proposalId, targets, values, calldatas, )++`] +* {xref-GovernorTimelockCompound-_executeOperations-uint256-address---uint256---bytes---bytes32-}[`++_executeOperations(proposalId, targets, values, calldatas, )++`] +* {xref-GovernorTimelockCompound-_cancel-address---uint256---bytes---bytes32-}[`++_cancel(targets, values, calldatas, descriptionHash)++`] +* {xref-GovernorTimelockCompound-_executor--}[`++_executor()++`] +* {xref-GovernorTimelockCompound-__acceptAdmin--}[`++__acceptAdmin()++`] +* {xref-GovernorTimelockCompound-updateTimelock-contract-ICompoundTimelock-}[`++updateTimelock(newTimelock)++`] + +[.contract-subindex-inherited] +.Governor +* {xref-Governor-receive--}[`++receive()++`] +* {xref-Governor-supportsInterface-bytes4-}[`++supportsInterface(interfaceId)++`] +* {xref-Governor-name--}[`++name()++`] +* {xref-Governor-version--}[`++version()++`] +* {xref-Governor-hashProposal-address---uint256---bytes---bytes32-}[`++hashProposal(targets, values, calldatas, descriptionHash)++`] +* {xref-Governor-proposalThreshold--}[`++proposalThreshold()++`] +* {xref-Governor-proposalSnapshot-uint256-}[`++proposalSnapshot(proposalId)++`] +* {xref-Governor-proposalDeadline-uint256-}[`++proposalDeadline(proposalId)++`] +* {xref-Governor-proposalProposer-uint256-}[`++proposalProposer(proposalId)++`] +* {xref-Governor-proposalEta-uint256-}[`++proposalEta(proposalId)++`] +* {xref-Governor-_checkGovernance--}[`++_checkGovernance()++`] +* {xref-Governor-_quorumReached-uint256-}[`++_quorumReached(proposalId)++`] +* {xref-Governor-_voteSucceeded-uint256-}[`++_voteSucceeded(proposalId)++`] +* {xref-Governor-_getVotes-address-uint256-bytes-}[`++_getVotes(account, timepoint, params)++`] +* {xref-Governor-_countVote-uint256-address-uint8-uint256-bytes-}[`++_countVote(proposalId, account, support, weight, params)++`] +* {xref-Governor-_defaultParams--}[`++_defaultParams()++`] +* {xref-Governor-propose-address---uint256---bytes---string-}[`++propose(targets, values, calldatas, description)++`] +* {xref-Governor-_propose-address---uint256---bytes---string-address-}[`++_propose(targets, values, calldatas, description, proposer)++`] +* {xref-Governor-queue-address---uint256---bytes---bytes32-}[`++queue(targets, values, calldatas, descriptionHash)++`] +* {xref-Governor-execute-address---uint256---bytes---bytes32-}[`++execute(targets, values, calldatas, descriptionHash)++`] +* {xref-Governor-cancel-address---uint256---bytes---bytes32-}[`++cancel(targets, values, calldatas, descriptionHash)++`] +* {xref-Governor-getVotes-address-uint256-}[`++getVotes(account, timepoint)++`] +* {xref-Governor-getVotesWithParams-address-uint256-bytes-}[`++getVotesWithParams(account, timepoint, params)++`] +* {xref-Governor-castVote-uint256-uint8-}[`++castVote(proposalId, support)++`] +* {xref-Governor-castVoteWithReason-uint256-uint8-string-}[`++castVoteWithReason(proposalId, support, reason)++`] +* {xref-Governor-castVoteWithReasonAndParams-uint256-uint8-string-bytes-}[`++castVoteWithReasonAndParams(proposalId, support, reason, params)++`] +* {xref-Governor-castVoteBySig-uint256-uint8-address-bytes-}[`++castVoteBySig(proposalId, support, voter, signature)++`] +* {xref-Governor-castVoteWithReasonAndParamsBySig-uint256-uint8-address-string-bytes-bytes-}[`++castVoteWithReasonAndParamsBySig(proposalId, support, voter, reason, params, signature)++`] +* {xref-Governor-_castVote-uint256-address-uint8-string-}[`++_castVote(proposalId, account, support, reason)++`] +* {xref-Governor-_castVote-uint256-address-uint8-string-bytes-}[`++_castVote(proposalId, account, support, reason, params)++`] +* {xref-Governor-relay-address-uint256-bytes-}[`++relay(target, value, data)++`] +* {xref-Governor-onERC721Received-address-address-uint256-bytes-}[`++onERC721Received(, , , )++`] +* {xref-Governor-onERC1155Received-address-address-uint256-uint256-bytes-}[`++onERC1155Received(, , , , )++`] +* {xref-Governor-onERC1155BatchReceived-address-address-uint256---uint256---bytes-}[`++onERC1155BatchReceived(, , , , )++`] +* {xref-Governor-_encodeStateBitmap-enum-IGovernor-ProposalState-}[`++_encodeStateBitmap(proposalState)++`] +* {xref-Governor-_isValidDescriptionForProposer-address-string-}[`++_isValidDescriptionForProposer(proposer, description)++`] +* {xref-Governor-clock--}[`++clock()++`] +* {xref-Governor-CLOCK_MODE--}[`++CLOCK_MODE()++`] +* {xref-Governor-votingDelay--}[`++votingDelay()++`] +* {xref-Governor-votingPeriod--}[`++votingPeriod()++`] +* {xref-Governor-quorum-uint256-}[`++quorum(timepoint)++`] + +[.contract-subindex-inherited] +.IERC1155Receiver + +[.contract-subindex-inherited] +.IERC721Receiver + +[.contract-subindex-inherited] +.IGovernor +* {xref-IGovernor-COUNTING_MODE--}[`++COUNTING_MODE()++`] +* {xref-IGovernor-hasVoted-uint256-address-}[`++hasVoted(proposalId, account)++`] + +[.contract-subindex-inherited] +.IERC6372 + +[.contract-subindex-inherited] +.Nonces +* {xref-Nonces-nonces-address-}[`++nonces(owner)++`] +* {xref-Nonces-_useNonce-address-}[`++_useNonce(owner)++`] +* {xref-Nonces-_useCheckedNonce-address-uint256-}[`++_useCheckedNonce(owner, nonce)++`] + +[.contract-subindex-inherited] +.EIP712 +* {xref-EIP712-_domainSeparatorV4--}[`++_domainSeparatorV4()++`] +* {xref-EIP712-_hashTypedDataV4-bytes32-}[`++_hashTypedDataV4(structHash)++`] +* {xref-EIP712-eip712Domain--}[`++eip712Domain()++`] +* {xref-EIP712-_EIP712Name--}[`++_EIP712Name()++`] +* {xref-EIP712-_EIP712Version--}[`++_EIP712Version()++`] + +[.contract-subindex-inherited] +.IERC5267 + +[.contract-subindex-inherited] +.ERC165 + +[.contract-subindex-inherited] +.IERC165 + +-- + +[.contract-index] +.Events +-- +* {xref-GovernorTimelockCompound-TimelockChange-address-address-}[`++TimelockChange(oldTimelock, newTimelock)++`] + +[.contract-subindex-inherited] +.Governor + +[.contract-subindex-inherited] +.IERC1155Receiver + +[.contract-subindex-inherited] +.IERC721Receiver + +[.contract-subindex-inherited] +.IGovernor +* {xref-IGovernor-ProposalCreated-uint256-address-address---uint256---string---bytes---uint256-uint256-string-}[`++ProposalCreated(proposalId, proposer, targets, values, signatures, calldatas, voteStart, voteEnd, description)++`] +* {xref-IGovernor-ProposalQueued-uint256-uint256-}[`++ProposalQueued(proposalId, etaSeconds)++`] +* {xref-IGovernor-ProposalExecuted-uint256-}[`++ProposalExecuted(proposalId)++`] +* {xref-IGovernor-ProposalCanceled-uint256-}[`++ProposalCanceled(proposalId)++`] +* {xref-IGovernor-VoteCast-address-uint256-uint8-uint256-string-}[`++VoteCast(voter, proposalId, support, weight, reason)++`] +* {xref-IGovernor-VoteCastWithParams-address-uint256-uint8-uint256-string-bytes-}[`++VoteCastWithParams(voter, proposalId, support, weight, reason, params)++`] + +[.contract-subindex-inherited] +.IERC6372 + +[.contract-subindex-inherited] +.Nonces + +[.contract-subindex-inherited] +.EIP712 + +[.contract-subindex-inherited] +.IERC5267 +* {xref-IERC5267-EIP712DomainChanged--}[`++EIP712DomainChanged()++`] + +[.contract-subindex-inherited] +.ERC165 + +[.contract-subindex-inherited] +.IERC165 + +-- + +[.contract-index] +.Errors +-- + +[.contract-subindex-inherited] +.Governor + +[.contract-subindex-inherited] +.IERC1155Receiver + +[.contract-subindex-inherited] +.IERC721Receiver + +[.contract-subindex-inherited] +.IGovernor +* {xref-IGovernor-GovernorInvalidProposalLength-uint256-uint256-uint256-}[`++GovernorInvalidProposalLength(targets, calldatas, values)++`] +* {xref-IGovernor-GovernorAlreadyCastVote-address-}[`++GovernorAlreadyCastVote(voter)++`] +* {xref-IGovernor-GovernorDisabledDeposit--}[`++GovernorDisabledDeposit()++`] +* {xref-IGovernor-GovernorOnlyProposer-address-}[`++GovernorOnlyProposer(account)++`] +* {xref-IGovernor-GovernorOnlyExecutor-address-}[`++GovernorOnlyExecutor(account)++`] +* {xref-IGovernor-GovernorNonexistentProposal-uint256-}[`++GovernorNonexistentProposal(proposalId)++`] +* {xref-IGovernor-GovernorUnexpectedProposalState-uint256-enum-IGovernor-ProposalState-bytes32-}[`++GovernorUnexpectedProposalState(proposalId, current, expectedStates)++`] +* {xref-IGovernor-GovernorInvalidVotingPeriod-uint256-}[`++GovernorInvalidVotingPeriod(votingPeriod)++`] +* {xref-IGovernor-GovernorInsufficientProposerVotes-address-uint256-uint256-}[`++GovernorInsufficientProposerVotes(proposer, votes, threshold)++`] +* {xref-IGovernor-GovernorRestrictedProposer-address-}[`++GovernorRestrictedProposer(proposer)++`] +* {xref-IGovernor-GovernorInvalidVoteType--}[`++GovernorInvalidVoteType()++`] +* {xref-IGovernor-GovernorQueueNotImplemented--}[`++GovernorQueueNotImplemented()++`] +* {xref-IGovernor-GovernorNotQueuedProposal-uint256-}[`++GovernorNotQueuedProposal(proposalId)++`] +* {xref-IGovernor-GovernorAlreadyQueuedProposal-uint256-}[`++GovernorAlreadyQueuedProposal(proposalId)++`] +* {xref-IGovernor-GovernorInvalidSignature-address-}[`++GovernorInvalidSignature(voter)++`] + +[.contract-subindex-inherited] +.IERC6372 + +[.contract-subindex-inherited] +.Nonces +* {xref-Nonces-InvalidAccountNonce-address-uint256-}[`++InvalidAccountNonce(account, currentNonce)++`] + +[.contract-subindex-inherited] +.EIP712 + +[.contract-subindex-inherited] +.IERC5267 + +[.contract-subindex-inherited] +.ERC165 + +[.contract-subindex-inherited] +.IERC165 + +-- + +[.contract-item] +[[GovernorTimelockCompound-constructor-contract-ICompoundTimelock-]] +==== `[.contract-item-name]#++constructor++#++(contract ICompoundTimelock timelockAddress)++` [.item-kind]#internal# + +Set the timelock. + +[.contract-item] +[[GovernorTimelockCompound-state-uint256-]] +==== `[.contract-item-name]#++state++#++(uint256 proposalId) → enum IGovernor.ProposalState++` [.item-kind]#public# + +Overridden version of the {Governor-state} function with added support for the `Expired` state. + +[.contract-item] +[[GovernorTimelockCompound-timelock--]] +==== `[.contract-item-name]#++timelock++#++() → address++` [.item-kind]#public# + +Public accessor to check the address of the timelock + +[.contract-item] +[[GovernorTimelockCompound-proposalNeedsQueuing-uint256-]] +==== `[.contract-item-name]#++proposalNeedsQueuing++#++(uint256) → bool++` [.item-kind]#public# + +See {IGovernor-proposalNeedsQueuing}. + +[.contract-item] +[[GovernorTimelockCompound-_queueOperations-uint256-address---uint256---bytes---bytes32-]] +==== `[.contract-item-name]#++_queueOperations++#++(uint256 proposalId, address[] targets, uint256[] values, bytes[] calldatas, bytes32) → uint48++` [.item-kind]#internal# + +Function to queue a proposal to the timelock. + +[.contract-item] +[[GovernorTimelockCompound-_executeOperations-uint256-address---uint256---bytes---bytes32-]] +==== `[.contract-item-name]#++_executeOperations++#++(uint256 proposalId, address[] targets, uint256[] values, bytes[] calldatas, bytes32)++` [.item-kind]#internal# + +Overridden version of the {Governor-_executeOperations} function that run the already queued proposal +through the timelock. + +[.contract-item] +[[GovernorTimelockCompound-_cancel-address---uint256---bytes---bytes32-]] +==== `[.contract-item-name]#++_cancel++#++(address[] targets, uint256[] values, bytes[] calldatas, bytes32 descriptionHash) → uint256++` [.item-kind]#internal# + +Overridden version of the {Governor-_cancel} function to cancel the timelocked proposal if it has already +been queued. + +[.contract-item] +[[GovernorTimelockCompound-_executor--]] +==== `[.contract-item-name]#++_executor++#++() → address++` [.item-kind]#internal# + +Address through which the governor executes action. In this case, the timelock. + +[.contract-item] +[[GovernorTimelockCompound-__acceptAdmin--]] +==== `[.contract-item-name]#++__acceptAdmin++#++()++` [.item-kind]#public# + +Accept admin right over the timelock. + +[.contract-item] +[[GovernorTimelockCompound-updateTimelock-contract-ICompoundTimelock-]] +==== `[.contract-item-name]#++updateTimelock++#++(contract ICompoundTimelock newTimelock)++` [.item-kind]#external# + +Public endpoint to update the underlying timelock instance. Restricted to the timelock itself, so updates +must be proposed, scheduled, and executed through governance proposals. + +For security reasons, the timelock must be handed over to another admin before setting up a new one. The two +operations (hand over the timelock) and do the update can be batched in a single proposal. + +Note that if the timelock admin has been handed over in a previous operation, we refuse updates made through the +timelock if admin of the timelock has already been accepted and the operation is executed outside the scope of +governance. + +CAUTION: It is not recommended to change the timelock while there are other queued governance proposals. + +[.contract-item] +[[GovernorTimelockCompound-TimelockChange-address-address-]] +==== `[.contract-item-name]#++TimelockChange++#++(address oldTimelock, address newTimelock)++` [.item-kind]#event# + +Emitted when the timelock controller used for proposal execution is modified. + +:VotingDelaySet: pass:normal[xref:#GovernorSettings-VotingDelaySet-uint256-uint256-[`++VotingDelaySet++`]] +:VotingPeriodSet: pass:normal[xref:#GovernorSettings-VotingPeriodSet-uint256-uint256-[`++VotingPeriodSet++`]] +:ProposalThresholdSet: pass:normal[xref:#GovernorSettings-ProposalThresholdSet-uint256-uint256-[`++ProposalThresholdSet++`]] +:constructor: pass:normal[xref:#GovernorSettings-constructor-uint48-uint32-uint256-[`++constructor++`]] +:votingDelay: pass:normal[xref:#GovernorSettings-votingDelay--[`++votingDelay++`]] +:votingPeriod: pass:normal[xref:#GovernorSettings-votingPeriod--[`++votingPeriod++`]] +:proposalThreshold: pass:normal[xref:#GovernorSettings-proposalThreshold--[`++proposalThreshold++`]] +:setVotingDelay: pass:normal[xref:#GovernorSettings-setVotingDelay-uint48-[`++setVotingDelay++`]] +:setVotingPeriod: pass:normal[xref:#GovernorSettings-setVotingPeriod-uint32-[`++setVotingPeriod++`]] +:setProposalThreshold: pass:normal[xref:#GovernorSettings-setProposalThreshold-uint256-[`++setProposalThreshold++`]] +:_setVotingDelay: pass:normal[xref:#GovernorSettings-_setVotingDelay-uint48-[`++_setVotingDelay++`]] +:_setVotingPeriod: pass:normal[xref:#GovernorSettings-_setVotingPeriod-uint32-[`++_setVotingPeriod++`]] +:_setProposalThreshold: pass:normal[xref:#GovernorSettings-_setProposalThreshold-uint256-[`++_setProposalThreshold++`]] + +[.contract] +[[GovernorSettings]] +=== `++GovernorSettings++` link:https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v5.0.0-rc.0/contracts/governance/extensions/GovernorSettings.sol[{github-icon},role=heading-link] + +[.hljs-theme-light.nopadding] +```solidity +import "@openzeppelin/contracts/governance/extensions/GovernorSettings.sol"; +``` + +Extension of {Governor} for settings updatable through governance. + +[.contract-index] +.Functions +-- +* {xref-GovernorSettings-constructor-uint48-uint32-uint256-}[`++constructor(initialVotingDelay, initialVotingPeriod, initialProposalThreshold)++`] +* {xref-GovernorSettings-votingDelay--}[`++votingDelay()++`] +* {xref-GovernorSettings-votingPeriod--}[`++votingPeriod()++`] +* {xref-GovernorSettings-proposalThreshold--}[`++proposalThreshold()++`] +* {xref-GovernorSettings-setVotingDelay-uint48-}[`++setVotingDelay(newVotingDelay)++`] +* {xref-GovernorSettings-setVotingPeriod-uint32-}[`++setVotingPeriod(newVotingPeriod)++`] +* {xref-GovernorSettings-setProposalThreshold-uint256-}[`++setProposalThreshold(newProposalThreshold)++`] +* {xref-GovernorSettings-_setVotingDelay-uint48-}[`++_setVotingDelay(newVotingDelay)++`] +* {xref-GovernorSettings-_setVotingPeriod-uint32-}[`++_setVotingPeriod(newVotingPeriod)++`] +* {xref-GovernorSettings-_setProposalThreshold-uint256-}[`++_setProposalThreshold(newProposalThreshold)++`] + +[.contract-subindex-inherited] +.Governor +* {xref-Governor-receive--}[`++receive()++`] +* {xref-Governor-supportsInterface-bytes4-}[`++supportsInterface(interfaceId)++`] +* {xref-Governor-name--}[`++name()++`] +* {xref-Governor-version--}[`++version()++`] +* {xref-Governor-hashProposal-address---uint256---bytes---bytes32-}[`++hashProposal(targets, values, calldatas, descriptionHash)++`] +* {xref-Governor-state-uint256-}[`++state(proposalId)++`] +* {xref-Governor-proposalSnapshot-uint256-}[`++proposalSnapshot(proposalId)++`] +* {xref-Governor-proposalDeadline-uint256-}[`++proposalDeadline(proposalId)++`] +* {xref-Governor-proposalProposer-uint256-}[`++proposalProposer(proposalId)++`] +* {xref-Governor-proposalEta-uint256-}[`++proposalEta(proposalId)++`] +* {xref-Governor-proposalNeedsQueuing-uint256-}[`++proposalNeedsQueuing()++`] +* {xref-Governor-_checkGovernance--}[`++_checkGovernance()++`] +* {xref-Governor-_quorumReached-uint256-}[`++_quorumReached(proposalId)++`] +* {xref-Governor-_voteSucceeded-uint256-}[`++_voteSucceeded(proposalId)++`] +* {xref-Governor-_getVotes-address-uint256-bytes-}[`++_getVotes(account, timepoint, params)++`] +* {xref-Governor-_countVote-uint256-address-uint8-uint256-bytes-}[`++_countVote(proposalId, account, support, weight, params)++`] +* {xref-Governor-_defaultParams--}[`++_defaultParams()++`] +* {xref-Governor-propose-address---uint256---bytes---string-}[`++propose(targets, values, calldatas, description)++`] +* {xref-Governor-_propose-address---uint256---bytes---string-address-}[`++_propose(targets, values, calldatas, description, proposer)++`] +* {xref-Governor-queue-address---uint256---bytes---bytes32-}[`++queue(targets, values, calldatas, descriptionHash)++`] +* {xref-Governor-_queueOperations-uint256-address---uint256---bytes---bytes32-}[`++_queueOperations(, , , , )++`] +* {xref-Governor-execute-address---uint256---bytes---bytes32-}[`++execute(targets, values, calldatas, descriptionHash)++`] +* {xref-Governor-_executeOperations-uint256-address---uint256---bytes---bytes32-}[`++_executeOperations(, targets, values, calldatas, )++`] +* {xref-Governor-cancel-address---uint256---bytes---bytes32-}[`++cancel(targets, values, calldatas, descriptionHash)++`] +* {xref-Governor-_cancel-address---uint256---bytes---bytes32-}[`++_cancel(targets, values, calldatas, descriptionHash)++`] +* {xref-Governor-getVotes-address-uint256-}[`++getVotes(account, timepoint)++`] +* {xref-Governor-getVotesWithParams-address-uint256-bytes-}[`++getVotesWithParams(account, timepoint, params)++`] +* {xref-Governor-castVote-uint256-uint8-}[`++castVote(proposalId, support)++`] +* {xref-Governor-castVoteWithReason-uint256-uint8-string-}[`++castVoteWithReason(proposalId, support, reason)++`] +* {xref-Governor-castVoteWithReasonAndParams-uint256-uint8-string-bytes-}[`++castVoteWithReasonAndParams(proposalId, support, reason, params)++`] +* {xref-Governor-castVoteBySig-uint256-uint8-address-bytes-}[`++castVoteBySig(proposalId, support, voter, signature)++`] +* {xref-Governor-castVoteWithReasonAndParamsBySig-uint256-uint8-address-string-bytes-bytes-}[`++castVoteWithReasonAndParamsBySig(proposalId, support, voter, reason, params, signature)++`] +* {xref-Governor-_castVote-uint256-address-uint8-string-}[`++_castVote(proposalId, account, support, reason)++`] +* {xref-Governor-_castVote-uint256-address-uint8-string-bytes-}[`++_castVote(proposalId, account, support, reason, params)++`] +* {xref-Governor-relay-address-uint256-bytes-}[`++relay(target, value, data)++`] +* {xref-Governor-_executor--}[`++_executor()++`] +* {xref-Governor-onERC721Received-address-address-uint256-bytes-}[`++onERC721Received(, , , )++`] +* {xref-Governor-onERC1155Received-address-address-uint256-uint256-bytes-}[`++onERC1155Received(, , , , )++`] +* {xref-Governor-onERC1155BatchReceived-address-address-uint256---uint256---bytes-}[`++onERC1155BatchReceived(, , , , )++`] +* {xref-Governor-_encodeStateBitmap-enum-IGovernor-ProposalState-}[`++_encodeStateBitmap(proposalState)++`] +* {xref-Governor-_isValidDescriptionForProposer-address-string-}[`++_isValidDescriptionForProposer(proposer, description)++`] +* {xref-Governor-clock--}[`++clock()++`] +* {xref-Governor-CLOCK_MODE--}[`++CLOCK_MODE()++`] +* {xref-Governor-quorum-uint256-}[`++quorum(timepoint)++`] + +[.contract-subindex-inherited] +.IERC1155Receiver + +[.contract-subindex-inherited] +.IERC721Receiver + +[.contract-subindex-inherited] +.IGovernor +* {xref-IGovernor-COUNTING_MODE--}[`++COUNTING_MODE()++`] +* {xref-IGovernor-hasVoted-uint256-address-}[`++hasVoted(proposalId, account)++`] + +[.contract-subindex-inherited] +.IERC6372 + +[.contract-subindex-inherited] +.Nonces +* {xref-Nonces-nonces-address-}[`++nonces(owner)++`] +* {xref-Nonces-_useNonce-address-}[`++_useNonce(owner)++`] +* {xref-Nonces-_useCheckedNonce-address-uint256-}[`++_useCheckedNonce(owner, nonce)++`] + +[.contract-subindex-inherited] +.EIP712 +* {xref-EIP712-_domainSeparatorV4--}[`++_domainSeparatorV4()++`] +* {xref-EIP712-_hashTypedDataV4-bytes32-}[`++_hashTypedDataV4(structHash)++`] +* {xref-EIP712-eip712Domain--}[`++eip712Domain()++`] +* {xref-EIP712-_EIP712Name--}[`++_EIP712Name()++`] +* {xref-EIP712-_EIP712Version--}[`++_EIP712Version()++`] + +[.contract-subindex-inherited] +.IERC5267 + +[.contract-subindex-inherited] +.ERC165 + +[.contract-subindex-inherited] +.IERC165 + +-- + +[.contract-index] +.Events +-- +* {xref-GovernorSettings-VotingDelaySet-uint256-uint256-}[`++VotingDelaySet(oldVotingDelay, newVotingDelay)++`] +* {xref-GovernorSettings-VotingPeriodSet-uint256-uint256-}[`++VotingPeriodSet(oldVotingPeriod, newVotingPeriod)++`] +* {xref-GovernorSettings-ProposalThresholdSet-uint256-uint256-}[`++ProposalThresholdSet(oldProposalThreshold, newProposalThreshold)++`] + +[.contract-subindex-inherited] +.Governor + +[.contract-subindex-inherited] +.IERC1155Receiver + +[.contract-subindex-inherited] +.IERC721Receiver + +[.contract-subindex-inherited] +.IGovernor +* {xref-IGovernor-ProposalCreated-uint256-address-address---uint256---string---bytes---uint256-uint256-string-}[`++ProposalCreated(proposalId, proposer, targets, values, signatures, calldatas, voteStart, voteEnd, description)++`] +* {xref-IGovernor-ProposalQueued-uint256-uint256-}[`++ProposalQueued(proposalId, etaSeconds)++`] +* {xref-IGovernor-ProposalExecuted-uint256-}[`++ProposalExecuted(proposalId)++`] +* {xref-IGovernor-ProposalCanceled-uint256-}[`++ProposalCanceled(proposalId)++`] +* {xref-IGovernor-VoteCast-address-uint256-uint8-uint256-string-}[`++VoteCast(voter, proposalId, support, weight, reason)++`] +* {xref-IGovernor-VoteCastWithParams-address-uint256-uint8-uint256-string-bytes-}[`++VoteCastWithParams(voter, proposalId, support, weight, reason, params)++`] + +[.contract-subindex-inherited] +.IERC6372 + +[.contract-subindex-inherited] +.Nonces + +[.contract-subindex-inherited] +.EIP712 + +[.contract-subindex-inherited] +.IERC5267 +* {xref-IERC5267-EIP712DomainChanged--}[`++EIP712DomainChanged()++`] + +[.contract-subindex-inherited] +.ERC165 + +[.contract-subindex-inherited] +.IERC165 + +-- + +[.contract-index] +.Errors +-- + +[.contract-subindex-inherited] +.Governor + +[.contract-subindex-inherited] +.IERC1155Receiver + +[.contract-subindex-inherited] +.IERC721Receiver + +[.contract-subindex-inherited] +.IGovernor +* {xref-IGovernor-GovernorInvalidProposalLength-uint256-uint256-uint256-}[`++GovernorInvalidProposalLength(targets, calldatas, values)++`] +* {xref-IGovernor-GovernorAlreadyCastVote-address-}[`++GovernorAlreadyCastVote(voter)++`] +* {xref-IGovernor-GovernorDisabledDeposit--}[`++GovernorDisabledDeposit()++`] +* {xref-IGovernor-GovernorOnlyProposer-address-}[`++GovernorOnlyProposer(account)++`] +* {xref-IGovernor-GovernorOnlyExecutor-address-}[`++GovernorOnlyExecutor(account)++`] +* {xref-IGovernor-GovernorNonexistentProposal-uint256-}[`++GovernorNonexistentProposal(proposalId)++`] +* {xref-IGovernor-GovernorUnexpectedProposalState-uint256-enum-IGovernor-ProposalState-bytes32-}[`++GovernorUnexpectedProposalState(proposalId, current, expectedStates)++`] +* {xref-IGovernor-GovernorInvalidVotingPeriod-uint256-}[`++GovernorInvalidVotingPeriod(votingPeriod)++`] +* {xref-IGovernor-GovernorInsufficientProposerVotes-address-uint256-uint256-}[`++GovernorInsufficientProposerVotes(proposer, votes, threshold)++`] +* {xref-IGovernor-GovernorRestrictedProposer-address-}[`++GovernorRestrictedProposer(proposer)++`] +* {xref-IGovernor-GovernorInvalidVoteType--}[`++GovernorInvalidVoteType()++`] +* {xref-IGovernor-GovernorQueueNotImplemented--}[`++GovernorQueueNotImplemented()++`] +* {xref-IGovernor-GovernorNotQueuedProposal-uint256-}[`++GovernorNotQueuedProposal(proposalId)++`] +* {xref-IGovernor-GovernorAlreadyQueuedProposal-uint256-}[`++GovernorAlreadyQueuedProposal(proposalId)++`] +* {xref-IGovernor-GovernorInvalidSignature-address-}[`++GovernorInvalidSignature(voter)++`] + +[.contract-subindex-inherited] +.IERC6372 + +[.contract-subindex-inherited] +.Nonces +* {xref-Nonces-InvalidAccountNonce-address-uint256-}[`++InvalidAccountNonce(account, currentNonce)++`] + +[.contract-subindex-inherited] +.EIP712 + +[.contract-subindex-inherited] +.IERC5267 + +[.contract-subindex-inherited] +.ERC165 + +[.contract-subindex-inherited] +.IERC165 + +-- + +[.contract-item] +[[GovernorSettings-constructor-uint48-uint32-uint256-]] +==== `[.contract-item-name]#++constructor++#++(uint48 initialVotingDelay, uint32 initialVotingPeriod, uint256 initialProposalThreshold)++` [.item-kind]#internal# + +Initialize the governance parameters. + +[.contract-item] +[[GovernorSettings-votingDelay--]] +==== `[.contract-item-name]#++votingDelay++#++() → uint256++` [.item-kind]#public# + +See {IGovernor-votingDelay}. + +[.contract-item] +[[GovernorSettings-votingPeriod--]] +==== `[.contract-item-name]#++votingPeriod++#++() → uint256++` [.item-kind]#public# + +See {IGovernor-votingPeriod}. + +[.contract-item] +[[GovernorSettings-proposalThreshold--]] +==== `[.contract-item-name]#++proposalThreshold++#++() → uint256++` [.item-kind]#public# + +See {Governor-proposalThreshold}. + +[.contract-item] +[[GovernorSettings-setVotingDelay-uint48-]] +==== `[.contract-item-name]#++setVotingDelay++#++(uint48 newVotingDelay)++` [.item-kind]#public# + +Update the voting delay. This operation can only be performed through a governance proposal. + +Emits a {VotingDelaySet} event. + +[.contract-item] +[[GovernorSettings-setVotingPeriod-uint32-]] +==== `[.contract-item-name]#++setVotingPeriod++#++(uint32 newVotingPeriod)++` [.item-kind]#public# + +Update the voting period. This operation can only be performed through a governance proposal. + +Emits a {VotingPeriodSet} event. + +[.contract-item] +[[GovernorSettings-setProposalThreshold-uint256-]] +==== `[.contract-item-name]#++setProposalThreshold++#++(uint256 newProposalThreshold)++` [.item-kind]#public# + +Update the proposal threshold. This operation can only be performed through a governance proposal. + +Emits a {ProposalThresholdSet} event. + +[.contract-item] +[[GovernorSettings-_setVotingDelay-uint48-]] +==== `[.contract-item-name]#++_setVotingDelay++#++(uint48 newVotingDelay)++` [.item-kind]#internal# + +Internal setter for the voting delay. + +Emits a {VotingDelaySet} event. + +[.contract-item] +[[GovernorSettings-_setVotingPeriod-uint32-]] +==== `[.contract-item-name]#++_setVotingPeriod++#++(uint32 newVotingPeriod)++` [.item-kind]#internal# + +Internal setter for the voting period. + +Emits a {VotingPeriodSet} event. + +[.contract-item] +[[GovernorSettings-_setProposalThreshold-uint256-]] +==== `[.contract-item-name]#++_setProposalThreshold++#++(uint256 newProposalThreshold)++` [.item-kind]#internal# + +Internal setter for the proposal threshold. + +Emits a {ProposalThresholdSet} event. + +[.contract-item] +[[GovernorSettings-VotingDelaySet-uint256-uint256-]] +==== `[.contract-item-name]#++VotingDelaySet++#++(uint256 oldVotingDelay, uint256 newVotingDelay)++` [.item-kind]#event# + +[.contract-item] +[[GovernorSettings-VotingPeriodSet-uint256-uint256-]] +==== `[.contract-item-name]#++VotingPeriodSet++#++(uint256 oldVotingPeriod, uint256 newVotingPeriod)++` [.item-kind]#event# + +[.contract-item] +[[GovernorSettings-ProposalThresholdSet-uint256-uint256-]] +==== `[.contract-item-name]#++ProposalThresholdSet++#++(uint256 oldProposalThreshold, uint256 newProposalThreshold)++` [.item-kind]#event# + +:ProposalExtended: pass:normal[xref:#GovernorPreventLateQuorum-ProposalExtended-uint256-uint64-[`++ProposalExtended++`]] +:LateQuorumVoteExtensionSet: pass:normal[xref:#GovernorPreventLateQuorum-LateQuorumVoteExtensionSet-uint64-uint64-[`++LateQuorumVoteExtensionSet++`]] +:constructor: pass:normal[xref:#GovernorPreventLateQuorum-constructor-uint48-[`++constructor++`]] +:proposalDeadline: pass:normal[xref:#GovernorPreventLateQuorum-proposalDeadline-uint256-[`++proposalDeadline++`]] +:_castVote: pass:normal[xref:#GovernorPreventLateQuorum-_castVote-uint256-address-uint8-string-bytes-[`++_castVote++`]] +:lateQuorumVoteExtension: pass:normal[xref:#GovernorPreventLateQuorum-lateQuorumVoteExtension--[`++lateQuorumVoteExtension++`]] +:setLateQuorumVoteExtension: pass:normal[xref:#GovernorPreventLateQuorum-setLateQuorumVoteExtension-uint48-[`++setLateQuorumVoteExtension++`]] +:_setLateQuorumVoteExtension: pass:normal[xref:#GovernorPreventLateQuorum-_setLateQuorumVoteExtension-uint48-[`++_setLateQuorumVoteExtension++`]] + +[.contract] +[[GovernorPreventLateQuorum]] +=== `++GovernorPreventLateQuorum++` link:https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v5.0.0-rc.0/contracts/governance/extensions/GovernorPreventLateQuorum.sol[{github-icon},role=heading-link] + +[.hljs-theme-light.nopadding] +```solidity +import "@openzeppelin/contracts/governance/extensions/GovernorPreventLateQuorum.sol"; +``` + +A module that ensures there is a minimum voting period after quorum is reached. This prevents a large voter from +swaying a vote and triggering quorum at the last minute, by ensuring there is always time for other voters to react +and try to oppose the decision. + +If a vote causes quorum to be reached, the proposal's voting period may be extended so that it does not end before at +least a specified time has passed (the "vote extension" parameter). This parameter can be set through a governance +proposal. + +[.contract-index] +.Functions +-- +* {xref-GovernorPreventLateQuorum-constructor-uint48-}[`++constructor(initialVoteExtension)++`] +* {xref-GovernorPreventLateQuorum-proposalDeadline-uint256-}[`++proposalDeadline(proposalId)++`] +* {xref-GovernorPreventLateQuorum-_castVote-uint256-address-uint8-string-bytes-}[`++_castVote(proposalId, account, support, reason, params)++`] +* {xref-GovernorPreventLateQuorum-lateQuorumVoteExtension--}[`++lateQuorumVoteExtension()++`] +* {xref-GovernorPreventLateQuorum-setLateQuorumVoteExtension-uint48-}[`++setLateQuorumVoteExtension(newVoteExtension)++`] +* {xref-GovernorPreventLateQuorum-_setLateQuorumVoteExtension-uint48-}[`++_setLateQuorumVoteExtension(newVoteExtension)++`] + +[.contract-subindex-inherited] +.Governor +* {xref-Governor-receive--}[`++receive()++`] +* {xref-Governor-supportsInterface-bytes4-}[`++supportsInterface(interfaceId)++`] +* {xref-Governor-name--}[`++name()++`] +* {xref-Governor-version--}[`++version()++`] +* {xref-Governor-hashProposal-address---uint256---bytes---bytes32-}[`++hashProposal(targets, values, calldatas, descriptionHash)++`] +* {xref-Governor-state-uint256-}[`++state(proposalId)++`] +* {xref-Governor-proposalThreshold--}[`++proposalThreshold()++`] +* {xref-Governor-proposalSnapshot-uint256-}[`++proposalSnapshot(proposalId)++`] +* {xref-Governor-proposalProposer-uint256-}[`++proposalProposer(proposalId)++`] +* {xref-Governor-proposalEta-uint256-}[`++proposalEta(proposalId)++`] +* {xref-Governor-proposalNeedsQueuing-uint256-}[`++proposalNeedsQueuing()++`] +* {xref-Governor-_checkGovernance--}[`++_checkGovernance()++`] +* {xref-Governor-_quorumReached-uint256-}[`++_quorumReached(proposalId)++`] +* {xref-Governor-_voteSucceeded-uint256-}[`++_voteSucceeded(proposalId)++`] +* {xref-Governor-_getVotes-address-uint256-bytes-}[`++_getVotes(account, timepoint, params)++`] +* {xref-Governor-_countVote-uint256-address-uint8-uint256-bytes-}[`++_countVote(proposalId, account, support, weight, params)++`] +* {xref-Governor-_defaultParams--}[`++_defaultParams()++`] +* {xref-Governor-propose-address---uint256---bytes---string-}[`++propose(targets, values, calldatas, description)++`] +* {xref-Governor-_propose-address---uint256---bytes---string-address-}[`++_propose(targets, values, calldatas, description, proposer)++`] +* {xref-Governor-queue-address---uint256---bytes---bytes32-}[`++queue(targets, values, calldatas, descriptionHash)++`] +* {xref-Governor-_queueOperations-uint256-address---uint256---bytes---bytes32-}[`++_queueOperations(, , , , )++`] +* {xref-Governor-execute-address---uint256---bytes---bytes32-}[`++execute(targets, values, calldatas, descriptionHash)++`] +* {xref-Governor-_executeOperations-uint256-address---uint256---bytes---bytes32-}[`++_executeOperations(, targets, values, calldatas, )++`] +* {xref-Governor-cancel-address---uint256---bytes---bytes32-}[`++cancel(targets, values, calldatas, descriptionHash)++`] +* {xref-Governor-_cancel-address---uint256---bytes---bytes32-}[`++_cancel(targets, values, calldatas, descriptionHash)++`] +* {xref-Governor-getVotes-address-uint256-}[`++getVotes(account, timepoint)++`] +* {xref-Governor-getVotesWithParams-address-uint256-bytes-}[`++getVotesWithParams(account, timepoint, params)++`] +* {xref-Governor-castVote-uint256-uint8-}[`++castVote(proposalId, support)++`] +* {xref-Governor-castVoteWithReason-uint256-uint8-string-}[`++castVoteWithReason(proposalId, support, reason)++`] +* {xref-Governor-castVoteWithReasonAndParams-uint256-uint8-string-bytes-}[`++castVoteWithReasonAndParams(proposalId, support, reason, params)++`] +* {xref-Governor-castVoteBySig-uint256-uint8-address-bytes-}[`++castVoteBySig(proposalId, support, voter, signature)++`] +* {xref-Governor-castVoteWithReasonAndParamsBySig-uint256-uint8-address-string-bytes-bytes-}[`++castVoteWithReasonAndParamsBySig(proposalId, support, voter, reason, params, signature)++`] +* {xref-Governor-_castVote-uint256-address-uint8-string-}[`++_castVote(proposalId, account, support, reason)++`] +* {xref-Governor-relay-address-uint256-bytes-}[`++relay(target, value, data)++`] +* {xref-Governor-_executor--}[`++_executor()++`] +* {xref-Governor-onERC721Received-address-address-uint256-bytes-}[`++onERC721Received(, , , )++`] +* {xref-Governor-onERC1155Received-address-address-uint256-uint256-bytes-}[`++onERC1155Received(, , , , )++`] +* {xref-Governor-onERC1155BatchReceived-address-address-uint256---uint256---bytes-}[`++onERC1155BatchReceived(, , , , )++`] +* {xref-Governor-_encodeStateBitmap-enum-IGovernor-ProposalState-}[`++_encodeStateBitmap(proposalState)++`] +* {xref-Governor-_isValidDescriptionForProposer-address-string-}[`++_isValidDescriptionForProposer(proposer, description)++`] +* {xref-Governor-clock--}[`++clock()++`] +* {xref-Governor-CLOCK_MODE--}[`++CLOCK_MODE()++`] +* {xref-Governor-votingDelay--}[`++votingDelay()++`] +* {xref-Governor-votingPeriod--}[`++votingPeriod()++`] +* {xref-Governor-quorum-uint256-}[`++quorum(timepoint)++`] + +[.contract-subindex-inherited] +.IERC1155Receiver + +[.contract-subindex-inherited] +.IERC721Receiver + +[.contract-subindex-inherited] +.IGovernor +* {xref-IGovernor-COUNTING_MODE--}[`++COUNTING_MODE()++`] +* {xref-IGovernor-hasVoted-uint256-address-}[`++hasVoted(proposalId, account)++`] + +[.contract-subindex-inherited] +.IERC6372 + +[.contract-subindex-inherited] +.Nonces +* {xref-Nonces-nonces-address-}[`++nonces(owner)++`] +* {xref-Nonces-_useNonce-address-}[`++_useNonce(owner)++`] +* {xref-Nonces-_useCheckedNonce-address-uint256-}[`++_useCheckedNonce(owner, nonce)++`] + +[.contract-subindex-inherited] +.EIP712 +* {xref-EIP712-_domainSeparatorV4--}[`++_domainSeparatorV4()++`] +* {xref-EIP712-_hashTypedDataV4-bytes32-}[`++_hashTypedDataV4(structHash)++`] +* {xref-EIP712-eip712Domain--}[`++eip712Domain()++`] +* {xref-EIP712-_EIP712Name--}[`++_EIP712Name()++`] +* {xref-EIP712-_EIP712Version--}[`++_EIP712Version()++`] + +[.contract-subindex-inherited] +.IERC5267 + +[.contract-subindex-inherited] +.ERC165 + +[.contract-subindex-inherited] +.IERC165 + +-- + +[.contract-index] +.Events +-- +* {xref-GovernorPreventLateQuorum-ProposalExtended-uint256-uint64-}[`++ProposalExtended(proposalId, extendedDeadline)++`] +* {xref-GovernorPreventLateQuorum-LateQuorumVoteExtensionSet-uint64-uint64-}[`++LateQuorumVoteExtensionSet(oldVoteExtension, newVoteExtension)++`] + +[.contract-subindex-inherited] +.Governor + +[.contract-subindex-inherited] +.IERC1155Receiver + +[.contract-subindex-inherited] +.IERC721Receiver + +[.contract-subindex-inherited] +.IGovernor +* {xref-IGovernor-ProposalCreated-uint256-address-address---uint256---string---bytes---uint256-uint256-string-}[`++ProposalCreated(proposalId, proposer, targets, values, signatures, calldatas, voteStart, voteEnd, description)++`] +* {xref-IGovernor-ProposalQueued-uint256-uint256-}[`++ProposalQueued(proposalId, etaSeconds)++`] +* {xref-IGovernor-ProposalExecuted-uint256-}[`++ProposalExecuted(proposalId)++`] +* {xref-IGovernor-ProposalCanceled-uint256-}[`++ProposalCanceled(proposalId)++`] +* {xref-IGovernor-VoteCast-address-uint256-uint8-uint256-string-}[`++VoteCast(voter, proposalId, support, weight, reason)++`] +* {xref-IGovernor-VoteCastWithParams-address-uint256-uint8-uint256-string-bytes-}[`++VoteCastWithParams(voter, proposalId, support, weight, reason, params)++`] + +[.contract-subindex-inherited] +.IERC6372 + +[.contract-subindex-inherited] +.Nonces + +[.contract-subindex-inherited] +.EIP712 + +[.contract-subindex-inherited] +.IERC5267 +* {xref-IERC5267-EIP712DomainChanged--}[`++EIP712DomainChanged()++`] + +[.contract-subindex-inherited] +.ERC165 + +[.contract-subindex-inherited] +.IERC165 + +-- + +[.contract-index] +.Errors +-- + +[.contract-subindex-inherited] +.Governor + +[.contract-subindex-inherited] +.IERC1155Receiver + +[.contract-subindex-inherited] +.IERC721Receiver + +[.contract-subindex-inherited] +.IGovernor +* {xref-IGovernor-GovernorInvalidProposalLength-uint256-uint256-uint256-}[`++GovernorInvalidProposalLength(targets, calldatas, values)++`] +* {xref-IGovernor-GovernorAlreadyCastVote-address-}[`++GovernorAlreadyCastVote(voter)++`] +* {xref-IGovernor-GovernorDisabledDeposit--}[`++GovernorDisabledDeposit()++`] +* {xref-IGovernor-GovernorOnlyProposer-address-}[`++GovernorOnlyProposer(account)++`] +* {xref-IGovernor-GovernorOnlyExecutor-address-}[`++GovernorOnlyExecutor(account)++`] +* {xref-IGovernor-GovernorNonexistentProposal-uint256-}[`++GovernorNonexistentProposal(proposalId)++`] +* {xref-IGovernor-GovernorUnexpectedProposalState-uint256-enum-IGovernor-ProposalState-bytes32-}[`++GovernorUnexpectedProposalState(proposalId, current, expectedStates)++`] +* {xref-IGovernor-GovernorInvalidVotingPeriod-uint256-}[`++GovernorInvalidVotingPeriod(votingPeriod)++`] +* {xref-IGovernor-GovernorInsufficientProposerVotes-address-uint256-uint256-}[`++GovernorInsufficientProposerVotes(proposer, votes, threshold)++`] +* {xref-IGovernor-GovernorRestrictedProposer-address-}[`++GovernorRestrictedProposer(proposer)++`] +* {xref-IGovernor-GovernorInvalidVoteType--}[`++GovernorInvalidVoteType()++`] +* {xref-IGovernor-GovernorQueueNotImplemented--}[`++GovernorQueueNotImplemented()++`] +* {xref-IGovernor-GovernorNotQueuedProposal-uint256-}[`++GovernorNotQueuedProposal(proposalId)++`] +* {xref-IGovernor-GovernorAlreadyQueuedProposal-uint256-}[`++GovernorAlreadyQueuedProposal(proposalId)++`] +* {xref-IGovernor-GovernorInvalidSignature-address-}[`++GovernorInvalidSignature(voter)++`] + +[.contract-subindex-inherited] +.IERC6372 + +[.contract-subindex-inherited] +.Nonces +* {xref-Nonces-InvalidAccountNonce-address-uint256-}[`++InvalidAccountNonce(account, currentNonce)++`] + +[.contract-subindex-inherited] +.EIP712 + +[.contract-subindex-inherited] +.IERC5267 + +[.contract-subindex-inherited] +.ERC165 + +[.contract-subindex-inherited] +.IERC165 + +-- + +[.contract-item] +[[GovernorPreventLateQuorum-constructor-uint48-]] +==== `[.contract-item-name]#++constructor++#++(uint48 initialVoteExtension)++` [.item-kind]#internal# + +Initializes the vote extension parameter: the time in either number of blocks or seconds (depending on the +governor clock mode) that is required to pass since the moment a proposal reaches quorum until its voting period +ends. If necessary the voting period will be extended beyond the one set during proposal creation. + +[.contract-item] +[[GovernorPreventLateQuorum-proposalDeadline-uint256-]] +==== `[.contract-item-name]#++proposalDeadline++#++(uint256 proposalId) → uint256++` [.item-kind]#public# + +Returns the proposal deadline, which may have been extended beyond that set at proposal creation, if the +proposal reached quorum late in the voting period. See {Governor-proposalDeadline}. + +[.contract-item] +[[GovernorPreventLateQuorum-_castVote-uint256-address-uint8-string-bytes-]] +==== `[.contract-item-name]#++_castVote++#++(uint256 proposalId, address account, uint8 support, string reason, bytes params) → uint256++` [.item-kind]#internal# + +Casts a vote and detects if it caused quorum to be reached, potentially extending the voting period. See +{Governor-_castVote}. + +May emit a {ProposalExtended} event. + +[.contract-item] +[[GovernorPreventLateQuorum-lateQuorumVoteExtension--]] +==== `[.contract-item-name]#++lateQuorumVoteExtension++#++() → uint48++` [.item-kind]#public# + +Returns the current value of the vote extension parameter: the number of blocks that are required to pass +from the time a proposal reaches quorum until its voting period ends. + +[.contract-item] +[[GovernorPreventLateQuorum-setLateQuorumVoteExtension-uint48-]] +==== `[.contract-item-name]#++setLateQuorumVoteExtension++#++(uint48 newVoteExtension)++` [.item-kind]#public# + +Changes the {lateQuorumVoteExtension}. This operation can only be performed by the governance executor, +generally through a governance proposal. + +Emits a {LateQuorumVoteExtensionSet} event. + +[.contract-item] +[[GovernorPreventLateQuorum-_setLateQuorumVoteExtension-uint48-]] +==== `[.contract-item-name]#++_setLateQuorumVoteExtension++#++(uint48 newVoteExtension)++` [.item-kind]#internal# + +Changes the {lateQuorumVoteExtension}. This is an internal function that can be exposed in a public function +like {setLateQuorumVoteExtension} if another access control mechanism is needed. + +Emits a {LateQuorumVoteExtensionSet} event. + +[.contract-item] +[[GovernorPreventLateQuorum-ProposalExtended-uint256-uint64-]] +==== `[.contract-item-name]#++ProposalExtended++#++(uint256 indexed proposalId, uint64 extendedDeadline)++` [.item-kind]#event# + +Emitted when a proposal deadline is pushed back due to reaching quorum late in its voting period. + +[.contract-item] +[[GovernorPreventLateQuorum-LateQuorumVoteExtensionSet-uint64-uint64-]] +==== `[.contract-item-name]#++LateQuorumVoteExtensionSet++#++(uint64 oldVoteExtension, uint64 newVoteExtension)++` [.item-kind]#event# + +Emitted when the {lateQuorumVoteExtension} parameter is changed. + +:ProposalDetails: pass:normal[xref:#GovernorStorage-ProposalDetails[`++ProposalDetails++`]] +:_propose: pass:normal[xref:#GovernorStorage-_propose-address---uint256---bytes---string-address-[`++_propose++`]] +:queue: pass:normal[xref:#GovernorStorage-queue-uint256-[`++queue++`]] +:execute: pass:normal[xref:#GovernorStorage-execute-uint256-[`++execute++`]] +:cancel: pass:normal[xref:#GovernorStorage-cancel-uint256-[`++cancel++`]] +:proposalCount: pass:normal[xref:#GovernorStorage-proposalCount--[`++proposalCount++`]] +:proposalDetails: pass:normal[xref:#GovernorStorage-proposalDetails-uint256-[`++proposalDetails++`]] +:proposalDetailsAt: pass:normal[xref:#GovernorStorage-proposalDetailsAt-uint256-[`++proposalDetailsAt++`]] + +[.contract] +[[GovernorStorage]] +=== `++GovernorStorage++` link:https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v5.0.0-rc.0/contracts/governance/extensions/GovernorStorage.sol[{github-icon},role=heading-link] + +[.hljs-theme-light.nopadding] +```solidity +import "@openzeppelin/contracts/governance/extensions/GovernorStorage.sol"; +``` + +Extension of {Governor} that implements storage of proposal details. This modules also provides primitives for +the enumerability of proposals. + +Use cases for this module include: +- UIs that explore the proposal state without relying on event indexing. +- Using only the proposalId as an argument in the {Governor-queue} and {Governor-execute} functions for L2 chains + where storage is cheap compared to calldata. + +[.contract-index] +.Functions +-- +* {xref-GovernorStorage-_propose-address---uint256---bytes---string-address-}[`++_propose(targets, values, calldatas, description, proposer)++`] +* {xref-GovernorStorage-queue-uint256-}[`++queue(proposalId)++`] +* {xref-GovernorStorage-execute-uint256-}[`++execute(proposalId)++`] +* {xref-GovernorStorage-cancel-uint256-}[`++cancel(proposalId)++`] +* {xref-GovernorStorage-proposalCount--}[`++proposalCount()++`] +* {xref-GovernorStorage-proposalDetails-uint256-}[`++proposalDetails(proposalId)++`] +* {xref-GovernorStorage-proposalDetailsAt-uint256-}[`++proposalDetailsAt(index)++`] + +[.contract-subindex-inherited] +.Governor +* {xref-Governor-receive--}[`++receive()++`] +* {xref-Governor-supportsInterface-bytes4-}[`++supportsInterface(interfaceId)++`] +* {xref-Governor-name--}[`++name()++`] +* {xref-Governor-version--}[`++version()++`] +* {xref-Governor-hashProposal-address---uint256---bytes---bytes32-}[`++hashProposal(targets, values, calldatas, descriptionHash)++`] +* {xref-Governor-state-uint256-}[`++state(proposalId)++`] +* {xref-Governor-proposalThreshold--}[`++proposalThreshold()++`] +* {xref-Governor-proposalSnapshot-uint256-}[`++proposalSnapshot(proposalId)++`] +* {xref-Governor-proposalDeadline-uint256-}[`++proposalDeadline(proposalId)++`] +* {xref-Governor-proposalProposer-uint256-}[`++proposalProposer(proposalId)++`] +* {xref-Governor-proposalEta-uint256-}[`++proposalEta(proposalId)++`] +* {xref-Governor-proposalNeedsQueuing-uint256-}[`++proposalNeedsQueuing()++`] +* {xref-Governor-_checkGovernance--}[`++_checkGovernance()++`] +* {xref-Governor-_quorumReached-uint256-}[`++_quorumReached(proposalId)++`] +* {xref-Governor-_voteSucceeded-uint256-}[`++_voteSucceeded(proposalId)++`] +* {xref-Governor-_getVotes-address-uint256-bytes-}[`++_getVotes(account, timepoint, params)++`] +* {xref-Governor-_countVote-uint256-address-uint8-uint256-bytes-}[`++_countVote(proposalId, account, support, weight, params)++`] +* {xref-Governor-_defaultParams--}[`++_defaultParams()++`] +* {xref-Governor-propose-address---uint256---bytes---string-}[`++propose(targets, values, calldatas, description)++`] +* {xref-Governor-queue-address---uint256---bytes---bytes32-}[`++queue(targets, values, calldatas, descriptionHash)++`] +* {xref-Governor-_queueOperations-uint256-address---uint256---bytes---bytes32-}[`++_queueOperations(, , , , )++`] +* {xref-Governor-execute-address---uint256---bytes---bytes32-}[`++execute(targets, values, calldatas, descriptionHash)++`] +* {xref-Governor-_executeOperations-uint256-address---uint256---bytes---bytes32-}[`++_executeOperations(, targets, values, calldatas, )++`] +* {xref-Governor-cancel-address---uint256---bytes---bytes32-}[`++cancel(targets, values, calldatas, descriptionHash)++`] +* {xref-Governor-_cancel-address---uint256---bytes---bytes32-}[`++_cancel(targets, values, calldatas, descriptionHash)++`] +* {xref-Governor-getVotes-address-uint256-}[`++getVotes(account, timepoint)++`] +* {xref-Governor-getVotesWithParams-address-uint256-bytes-}[`++getVotesWithParams(account, timepoint, params)++`] +* {xref-Governor-castVote-uint256-uint8-}[`++castVote(proposalId, support)++`] +* {xref-Governor-castVoteWithReason-uint256-uint8-string-}[`++castVoteWithReason(proposalId, support, reason)++`] +* {xref-Governor-castVoteWithReasonAndParams-uint256-uint8-string-bytes-}[`++castVoteWithReasonAndParams(proposalId, support, reason, params)++`] +* {xref-Governor-castVoteBySig-uint256-uint8-address-bytes-}[`++castVoteBySig(proposalId, support, voter, signature)++`] +* {xref-Governor-castVoteWithReasonAndParamsBySig-uint256-uint8-address-string-bytes-bytes-}[`++castVoteWithReasonAndParamsBySig(proposalId, support, voter, reason, params, signature)++`] +* {xref-Governor-_castVote-uint256-address-uint8-string-}[`++_castVote(proposalId, account, support, reason)++`] +* {xref-Governor-_castVote-uint256-address-uint8-string-bytes-}[`++_castVote(proposalId, account, support, reason, params)++`] +* {xref-Governor-relay-address-uint256-bytes-}[`++relay(target, value, data)++`] +* {xref-Governor-_executor--}[`++_executor()++`] +* {xref-Governor-onERC721Received-address-address-uint256-bytes-}[`++onERC721Received(, , , )++`] +* {xref-Governor-onERC1155Received-address-address-uint256-uint256-bytes-}[`++onERC1155Received(, , , , )++`] +* {xref-Governor-onERC1155BatchReceived-address-address-uint256---uint256---bytes-}[`++onERC1155BatchReceived(, , , , )++`] +* {xref-Governor-_encodeStateBitmap-enum-IGovernor-ProposalState-}[`++_encodeStateBitmap(proposalState)++`] +* {xref-Governor-_isValidDescriptionForProposer-address-string-}[`++_isValidDescriptionForProposer(proposer, description)++`] +* {xref-Governor-clock--}[`++clock()++`] +* {xref-Governor-CLOCK_MODE--}[`++CLOCK_MODE()++`] +* {xref-Governor-votingDelay--}[`++votingDelay()++`] +* {xref-Governor-votingPeriod--}[`++votingPeriod()++`] +* {xref-Governor-quorum-uint256-}[`++quorum(timepoint)++`] + +[.contract-subindex-inherited] +.IERC1155Receiver + +[.contract-subindex-inherited] +.IERC721Receiver + +[.contract-subindex-inherited] +.IGovernor +* {xref-IGovernor-COUNTING_MODE--}[`++COUNTING_MODE()++`] +* {xref-IGovernor-hasVoted-uint256-address-}[`++hasVoted(proposalId, account)++`] + +[.contract-subindex-inherited] +.IERC6372 + +[.contract-subindex-inherited] +.Nonces +* {xref-Nonces-nonces-address-}[`++nonces(owner)++`] +* {xref-Nonces-_useNonce-address-}[`++_useNonce(owner)++`] +* {xref-Nonces-_useCheckedNonce-address-uint256-}[`++_useCheckedNonce(owner, nonce)++`] + +[.contract-subindex-inherited] +.EIP712 +* {xref-EIP712-_domainSeparatorV4--}[`++_domainSeparatorV4()++`] +* {xref-EIP712-_hashTypedDataV4-bytes32-}[`++_hashTypedDataV4(structHash)++`] +* {xref-EIP712-eip712Domain--}[`++eip712Domain()++`] +* {xref-EIP712-_EIP712Name--}[`++_EIP712Name()++`] +* {xref-EIP712-_EIP712Version--}[`++_EIP712Version()++`] + +[.contract-subindex-inherited] +.IERC5267 + +[.contract-subindex-inherited] +.ERC165 + +[.contract-subindex-inherited] +.IERC165 + +-- + +[.contract-index] +.Events +-- + +[.contract-subindex-inherited] +.Governor + +[.contract-subindex-inherited] +.IERC1155Receiver + +[.contract-subindex-inherited] +.IERC721Receiver + +[.contract-subindex-inherited] +.IGovernor +* {xref-IGovernor-ProposalCreated-uint256-address-address---uint256---string---bytes---uint256-uint256-string-}[`++ProposalCreated(proposalId, proposer, targets, values, signatures, calldatas, voteStart, voteEnd, description)++`] +* {xref-IGovernor-ProposalQueued-uint256-uint256-}[`++ProposalQueued(proposalId, etaSeconds)++`] +* {xref-IGovernor-ProposalExecuted-uint256-}[`++ProposalExecuted(proposalId)++`] +* {xref-IGovernor-ProposalCanceled-uint256-}[`++ProposalCanceled(proposalId)++`] +* {xref-IGovernor-VoteCast-address-uint256-uint8-uint256-string-}[`++VoteCast(voter, proposalId, support, weight, reason)++`] +* {xref-IGovernor-VoteCastWithParams-address-uint256-uint8-uint256-string-bytes-}[`++VoteCastWithParams(voter, proposalId, support, weight, reason, params)++`] + +[.contract-subindex-inherited] +.IERC6372 + +[.contract-subindex-inherited] +.Nonces + +[.contract-subindex-inherited] +.EIP712 + +[.contract-subindex-inherited] +.IERC5267 +* {xref-IERC5267-EIP712DomainChanged--}[`++EIP712DomainChanged()++`] + +[.contract-subindex-inherited] +.ERC165 + +[.contract-subindex-inherited] +.IERC165 + +-- + +[.contract-index] +.Errors +-- + +[.contract-subindex-inherited] +.Governor + +[.contract-subindex-inherited] +.IERC1155Receiver + +[.contract-subindex-inherited] +.IERC721Receiver + +[.contract-subindex-inherited] +.IGovernor +* {xref-IGovernor-GovernorInvalidProposalLength-uint256-uint256-uint256-}[`++GovernorInvalidProposalLength(targets, calldatas, values)++`] +* {xref-IGovernor-GovernorAlreadyCastVote-address-}[`++GovernorAlreadyCastVote(voter)++`] +* {xref-IGovernor-GovernorDisabledDeposit--}[`++GovernorDisabledDeposit()++`] +* {xref-IGovernor-GovernorOnlyProposer-address-}[`++GovernorOnlyProposer(account)++`] +* {xref-IGovernor-GovernorOnlyExecutor-address-}[`++GovernorOnlyExecutor(account)++`] +* {xref-IGovernor-GovernorNonexistentProposal-uint256-}[`++GovernorNonexistentProposal(proposalId)++`] +* {xref-IGovernor-GovernorUnexpectedProposalState-uint256-enum-IGovernor-ProposalState-bytes32-}[`++GovernorUnexpectedProposalState(proposalId, current, expectedStates)++`] +* {xref-IGovernor-GovernorInvalidVotingPeriod-uint256-}[`++GovernorInvalidVotingPeriod(votingPeriod)++`] +* {xref-IGovernor-GovernorInsufficientProposerVotes-address-uint256-uint256-}[`++GovernorInsufficientProposerVotes(proposer, votes, threshold)++`] +* {xref-IGovernor-GovernorRestrictedProposer-address-}[`++GovernorRestrictedProposer(proposer)++`] +* {xref-IGovernor-GovernorInvalidVoteType--}[`++GovernorInvalidVoteType()++`] +* {xref-IGovernor-GovernorQueueNotImplemented--}[`++GovernorQueueNotImplemented()++`] +* {xref-IGovernor-GovernorNotQueuedProposal-uint256-}[`++GovernorNotQueuedProposal(proposalId)++`] +* {xref-IGovernor-GovernorAlreadyQueuedProposal-uint256-}[`++GovernorAlreadyQueuedProposal(proposalId)++`] +* {xref-IGovernor-GovernorInvalidSignature-address-}[`++GovernorInvalidSignature(voter)++`] + +[.contract-subindex-inherited] +.IERC6372 + +[.contract-subindex-inherited] +.Nonces +* {xref-Nonces-InvalidAccountNonce-address-uint256-}[`++InvalidAccountNonce(account, currentNonce)++`] + +[.contract-subindex-inherited] +.EIP712 + +[.contract-subindex-inherited] +.IERC5267 + +[.contract-subindex-inherited] +.ERC165 + +[.contract-subindex-inherited] +.IERC165 + +-- + +[.contract-item] +[[GovernorStorage-_propose-address---uint256---bytes---string-address-]] +==== `[.contract-item-name]#++_propose++#++(address[] targets, uint256[] values, bytes[] calldatas, string description, address proposer) → uint256++` [.item-kind]#internal# + +Hook into the proposing mechanism + +[.contract-item] +[[GovernorStorage-queue-uint256-]] +==== `[.contract-item-name]#++queue++#++(uint256 proposalId)++` [.item-kind]#public# + +Version of {IGovernorTimelock-queue} with only `proposalId` as an argument. + +[.contract-item] +[[GovernorStorage-execute-uint256-]] +==== `[.contract-item-name]#++execute++#++(uint256 proposalId)++` [.item-kind]#public# + +Version of {IGovernor-execute} with only `proposalId` as an argument. + +[.contract-item] +[[GovernorStorage-cancel-uint256-]] +==== `[.contract-item-name]#++cancel++#++(uint256 proposalId)++` [.item-kind]#public# + +ProposalId version of {IGovernor-cancel}. + +[.contract-item] +[[GovernorStorage-proposalCount--]] +==== `[.contract-item-name]#++proposalCount++#++() → uint256++` [.item-kind]#public# + +Returns the number of stored proposals. + +[.contract-item] +[[GovernorStorage-proposalDetails-uint256-]] +==== `[.contract-item-name]#++proposalDetails++#++(uint256 proposalId) → address[], uint256[], bytes[], bytes32++` [.item-kind]#public# + +Returns the details of a proposalId. Reverts if `proposalId` is not a known proposal. + +[.contract-item] +[[GovernorStorage-proposalDetailsAt-uint256-]] +==== `[.contract-item-name]#++proposalDetailsAt++#++(uint256 index) → uint256, address[], uint256[], bytes[], bytes32++` [.item-kind]#public# + +Returns the details (including the proposalId) of a proposal given its sequential index. + +== Utils + +:ERC6372InconsistentClock: pass:normal[xref:#Votes-ERC6372InconsistentClock--[`++ERC6372InconsistentClock++`]] +:ERC5805FutureLookup: pass:normal[xref:#Votes-ERC5805FutureLookup-uint256-uint48-[`++ERC5805FutureLookup++`]] +:clock: pass:normal[xref:#Votes-clock--[`++clock++`]] +:CLOCK_MODE: pass:normal[xref:#Votes-CLOCK_MODE--[`++CLOCK_MODE++`]] +:getVotes: pass:normal[xref:#Votes-getVotes-address-[`++getVotes++`]] +:getPastVotes: pass:normal[xref:#Votes-getPastVotes-address-uint256-[`++getPastVotes++`]] +:getPastTotalSupply: pass:normal[xref:#Votes-getPastTotalSupply-uint256-[`++getPastTotalSupply++`]] +:_getTotalSupply: pass:normal[xref:#Votes-_getTotalSupply--[`++_getTotalSupply++`]] +:delegates: pass:normal[xref:#Votes-delegates-address-[`++delegates++`]] +:delegate: pass:normal[xref:#Votes-delegate-address-[`++delegate++`]] +:delegateBySig: pass:normal[xref:#Votes-delegateBySig-address-uint256-uint256-uint8-bytes32-bytes32-[`++delegateBySig++`]] +:_delegate: pass:normal[xref:#Votes-_delegate-address-address-[`++_delegate++`]] +:_transferVotingUnits: pass:normal[xref:#Votes-_transferVotingUnits-address-address-uint256-[`++_transferVotingUnits++`]] +:_numCheckpoints: pass:normal[xref:#Votes-_numCheckpoints-address-[`++_numCheckpoints++`]] +:_checkpoints: pass:normal[xref:#Votes-_checkpoints-address-uint32-[`++_checkpoints++`]] +:_getVotingUnits: pass:normal[xref:#Votes-_getVotingUnits-address-[`++_getVotingUnits++`]] + +[.contract] +[[Votes]] +=== `++Votes++` link:https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v5.0.0-rc.0/contracts/governance/utils/Votes.sol[{github-icon},role=heading-link] + +[.hljs-theme-light.nopadding] +```solidity +import "@openzeppelin/contracts/governance/utils/Votes.sol"; +``` + +This is a base abstract contract that tracks voting units, which are a measure of voting power that can be +transferred, and provides a system of vote delegation, where an account can delegate its voting units to a sort of +"representative" that will pool delegated voting units from different accounts and can then use it to vote in +decisions. In fact, voting units _must_ be delegated in order to count as actual votes, and an account has to +delegate those votes to itself if it wishes to participate in decisions and does not have a trusted representative. + +This contract is often combined with a token contract such that voting units correspond to token units. For an +example, see {ERC721Votes}. + +The full history of delegate votes is tracked on-chain so that governance protocols can consider votes as distributed +at a particular block number to protect against flash loans and double voting. The opt-in delegate system makes the +cost of this history tracking optional. + +When using this module the derived contract must implement {_getVotingUnits} (for example, make it return +{ERC721-balanceOf}), and can use {_transferVotingUnits} to track a change in the distribution of those units (in the +previous example, it would be included in {ERC721-_beforeTokenTransfer}). + +[.contract-index] +.Functions +-- +* {xref-Votes-clock--}[`++clock()++`] +* {xref-Votes-CLOCK_MODE--}[`++CLOCK_MODE()++`] +* {xref-Votes-getVotes-address-}[`++getVotes(account)++`] +* {xref-Votes-getPastVotes-address-uint256-}[`++getPastVotes(account, timepoint)++`] +* {xref-Votes-getPastTotalSupply-uint256-}[`++getPastTotalSupply(timepoint)++`] +* {xref-Votes-_getTotalSupply--}[`++_getTotalSupply()++`] +* {xref-Votes-delegates-address-}[`++delegates(account)++`] +* {xref-Votes-delegate-address-}[`++delegate(delegatee)++`] +* {xref-Votes-delegateBySig-address-uint256-uint256-uint8-bytes32-bytes32-}[`++delegateBySig(delegatee, nonce, expiry, v, r, s)++`] +* {xref-Votes-_delegate-address-address-}[`++_delegate(account, delegatee)++`] +* {xref-Votes-_transferVotingUnits-address-address-uint256-}[`++_transferVotingUnits(from, to, amount)++`] +* {xref-Votes-_numCheckpoints-address-}[`++_numCheckpoints(account)++`] +* {xref-Votes-_checkpoints-address-uint32-}[`++_checkpoints(account, pos)++`] +* {xref-Votes-_getVotingUnits-address-}[`++_getVotingUnits()++`] + +[.contract-subindex-inherited] +.IERC5805 + +[.contract-subindex-inherited] +.IVotes + +[.contract-subindex-inherited] +.IERC6372 + +[.contract-subindex-inherited] +.Nonces +* {xref-Nonces-nonces-address-}[`++nonces(owner)++`] +* {xref-Nonces-_useNonce-address-}[`++_useNonce(owner)++`] +* {xref-Nonces-_useCheckedNonce-address-uint256-}[`++_useCheckedNonce(owner, nonce)++`] + +[.contract-subindex-inherited] +.EIP712 +* {xref-EIP712-_domainSeparatorV4--}[`++_domainSeparatorV4()++`] +* {xref-EIP712-_hashTypedDataV4-bytes32-}[`++_hashTypedDataV4(structHash)++`] +* {xref-EIP712-eip712Domain--}[`++eip712Domain()++`] +* {xref-EIP712-_EIP712Name--}[`++_EIP712Name()++`] +* {xref-EIP712-_EIP712Version--}[`++_EIP712Version()++`] + +[.contract-subindex-inherited] +.IERC5267 + +-- + +[.contract-index] +.Events +-- + +[.contract-subindex-inherited] +.IERC5805 + +[.contract-subindex-inherited] +.IVotes +* {xref-IVotes-DelegateChanged-address-address-address-}[`++DelegateChanged(delegator, fromDelegate, toDelegate)++`] +* {xref-IVotes-DelegateVotesChanged-address-uint256-uint256-}[`++DelegateVotesChanged(delegate, previousVotes, newVotes)++`] + +[.contract-subindex-inherited] +.IERC6372 + +[.contract-subindex-inherited] +.Nonces + +[.contract-subindex-inherited] +.EIP712 + +[.contract-subindex-inherited] +.IERC5267 +* {xref-IERC5267-EIP712DomainChanged--}[`++EIP712DomainChanged()++`] + +-- + +[.contract-index] +.Errors +-- +* {xref-Votes-ERC6372InconsistentClock--}[`++ERC6372InconsistentClock()++`] +* {xref-Votes-ERC5805FutureLookup-uint256-uint48-}[`++ERC5805FutureLookup(timepoint, clock)++`] + +[.contract-subindex-inherited] +.IERC5805 + +[.contract-subindex-inherited] +.IVotes +* {xref-IVotes-VotesExpiredSignature-uint256-}[`++VotesExpiredSignature(expiry)++`] + +[.contract-subindex-inherited] +.IERC6372 + +[.contract-subindex-inherited] +.Nonces +* {xref-Nonces-InvalidAccountNonce-address-uint256-}[`++InvalidAccountNonce(account, currentNonce)++`] + +[.contract-subindex-inherited] +.EIP712 + +[.contract-subindex-inherited] +.IERC5267 + +-- + +[.contract-item] +[[Votes-clock--]] +==== `[.contract-item-name]#++clock++#++() → uint48++` [.item-kind]#public# + +Clock used for flagging checkpoints. Can be overridden to implement timestamp based +checkpoints (and voting), in which case {CLOCK_MODE} should be overridden as well to match. + +[.contract-item] +[[Votes-CLOCK_MODE--]] +==== `[.contract-item-name]#++CLOCK_MODE++#++() → string++` [.item-kind]#public# + +Machine-readable description of the clock as specified in EIP-6372. + +[.contract-item] +[[Votes-getVotes-address-]] +==== `[.contract-item-name]#++getVotes++#++(address account) → uint256++` [.item-kind]#public# + +Returns the current amount of votes that `account` has. + +[.contract-item] +[[Votes-getPastVotes-address-uint256-]] +==== `[.contract-item-name]#++getPastVotes++#++(address account, uint256 timepoint) → uint256++` [.item-kind]#public# + +Returns the amount of votes that `account` had at a specific moment in the past. If the `clock()` is +configured to use block numbers, this will return the value at the end of the corresponding block. + +Requirements: + +- `timepoint` must be in the past. If operating using block numbers, the block must be already mined. + +[.contract-item] +[[Votes-getPastTotalSupply-uint256-]] +==== `[.contract-item-name]#++getPastTotalSupply++#++(uint256 timepoint) → uint256++` [.item-kind]#public# + +Returns the total supply of votes available at a specific moment in the past. If the `clock()` is +configured to use block numbers, this will return the value at the end of the corresponding block. + +NOTE: This value is the sum of all available votes, which is not necessarily the sum of all delegated votes. +Votes that have not been delegated are still part of total supply, even though they would not participate in a +vote. + +Requirements: + +- `timepoint` must be in the past. If operating using block numbers, the block must be already mined. + +[.contract-item] +[[Votes-_getTotalSupply--]] +==== `[.contract-item-name]#++_getTotalSupply++#++() → uint256++` [.item-kind]#internal# + +Returns the current total supply of votes. + +[.contract-item] +[[Votes-delegates-address-]] +==== `[.contract-item-name]#++delegates++#++(address account) → address++` [.item-kind]#public# + +Returns the delegate that `account` has chosen. + +[.contract-item] +[[Votes-delegate-address-]] +==== `[.contract-item-name]#++delegate++#++(address delegatee)++` [.item-kind]#public# + +Delegates votes from the sender to `delegatee`. + +[.contract-item] +[[Votes-delegateBySig-address-uint256-uint256-uint8-bytes32-bytes32-]] +==== `[.contract-item-name]#++delegateBySig++#++(address delegatee, uint256 nonce, uint256 expiry, uint8 v, bytes32 r, bytes32 s)++` [.item-kind]#public# + +Delegates votes from signer to `delegatee`. + +[.contract-item] +[[Votes-_delegate-address-address-]] +==== `[.contract-item-name]#++_delegate++#++(address account, address delegatee)++` [.item-kind]#internal# + +Delegate all of `account`'s voting units to `delegatee`. + +Emits events {IVotes-DelegateChanged} and {IVotes-DelegateVotesChanged}. + +[.contract-item] +[[Votes-_transferVotingUnits-address-address-uint256-]] +==== `[.contract-item-name]#++_transferVotingUnits++#++(address from, address to, uint256 amount)++` [.item-kind]#internal# + +Transfers, mints, or burns voting units. To register a mint, `from` should be zero. To register a burn, `to` +should be zero. Total supply of voting units will be adjusted with mints and burns. + +[.contract-item] +[[Votes-_numCheckpoints-address-]] +==== `[.contract-item-name]#++_numCheckpoints++#++(address account) → uint32++` [.item-kind]#internal# + +Get number of checkpoints for `account`. + +[.contract-item] +[[Votes-_checkpoints-address-uint32-]] +==== `[.contract-item-name]#++_checkpoints++#++(address account, uint32 pos) → struct Checkpoints.Checkpoint208++` [.item-kind]#internal# + +Get the `pos`-th checkpoint for `account`. + +[.contract-item] +[[Votes-_getVotingUnits-address-]] +==== `[.contract-item-name]#++_getVotingUnits++#++(address) → uint256++` [.item-kind]#internal# + +Must return the voting units held by an account. + +[.contract-item] +[[Votes-ERC6372InconsistentClock--]] +==== `[.contract-item-name]#++ERC6372InconsistentClock++#++()++` [.item-kind]#error# + +The clock was incorrectly modified. + +[.contract-item] +[[Votes-ERC5805FutureLookup-uint256-uint48-]] +==== `[.contract-item-name]#++ERC5805FutureLookup++#++(uint256 timepoint, uint48 clock)++` [.item-kind]#error# + +Lookup to future votes is not available. + +== Timelock + +In a governance system, the {TimelockController} contract is in charge of introducing a delay between a proposal and its execution. It can be used with or without a {Governor}. + +:PROPOSER_ROLE: pass:normal[xref:#TimelockController-PROPOSER_ROLE-bytes32[`++PROPOSER_ROLE++`]] +:EXECUTOR_ROLE: pass:normal[xref:#TimelockController-EXECUTOR_ROLE-bytes32[`++EXECUTOR_ROLE++`]] +:CANCELLER_ROLE: pass:normal[xref:#TimelockController-CANCELLER_ROLE-bytes32[`++CANCELLER_ROLE++`]] +:_DONE_TIMESTAMP: pass:normal[xref:#TimelockController-_DONE_TIMESTAMP-uint256[`++_DONE_TIMESTAMP++`]] +:OperationState: pass:normal[xref:#TimelockController-OperationState[`++OperationState++`]] +:TimelockInvalidOperationLength: pass:normal[xref:#TimelockController-TimelockInvalidOperationLength-uint256-uint256-uint256-[`++TimelockInvalidOperationLength++`]] +:TimelockInsufficientDelay: pass:normal[xref:#TimelockController-TimelockInsufficientDelay-uint256-uint256-[`++TimelockInsufficientDelay++`]] +:TimelockUnexpectedOperationState: pass:normal[xref:#TimelockController-TimelockUnexpectedOperationState-bytes32-bytes32-[`++TimelockUnexpectedOperationState++`]] +:TimelockUnexecutedPredecessor: pass:normal[xref:#TimelockController-TimelockUnexecutedPredecessor-bytes32-[`++TimelockUnexecutedPredecessor++`]] +:TimelockUnauthorizedCaller: pass:normal[xref:#TimelockController-TimelockUnauthorizedCaller-address-[`++TimelockUnauthorizedCaller++`]] +:CallScheduled: pass:normal[xref:#TimelockController-CallScheduled-bytes32-uint256-address-uint256-bytes-bytes32-uint256-[`++CallScheduled++`]] +:CallExecuted: pass:normal[xref:#TimelockController-CallExecuted-bytes32-uint256-address-uint256-bytes-[`++CallExecuted++`]] +:CallSalt: pass:normal[xref:#TimelockController-CallSalt-bytes32-bytes32-[`++CallSalt++`]] +:Cancelled: pass:normal[xref:#TimelockController-Cancelled-bytes32-[`++Cancelled++`]] +:MinDelayChange: pass:normal[xref:#TimelockController-MinDelayChange-uint256-uint256-[`++MinDelayChange++`]] +:constructor: pass:normal[xref:#TimelockController-constructor-uint256-address---address---address-[`++constructor++`]] +:onlyRoleOrOpenRole: pass:normal[xref:#TimelockController-onlyRoleOrOpenRole-bytes32-[`++onlyRoleOrOpenRole++`]] +:receive: pass:normal[xref:#TimelockController-receive--[`++receive++`]] +:supportsInterface: pass:normal[xref:#TimelockController-supportsInterface-bytes4-[`++supportsInterface++`]] +:isOperation: pass:normal[xref:#TimelockController-isOperation-bytes32-[`++isOperation++`]] +:isOperationPending: pass:normal[xref:#TimelockController-isOperationPending-bytes32-[`++isOperationPending++`]] +:isOperationReady: pass:normal[xref:#TimelockController-isOperationReady-bytes32-[`++isOperationReady++`]] +:isOperationDone: pass:normal[xref:#TimelockController-isOperationDone-bytes32-[`++isOperationDone++`]] +:getTimestamp: pass:normal[xref:#TimelockController-getTimestamp-bytes32-[`++getTimestamp++`]] +:getOperationState: pass:normal[xref:#TimelockController-getOperationState-bytes32-[`++getOperationState++`]] +:getMinDelay: pass:normal[xref:#TimelockController-getMinDelay--[`++getMinDelay++`]] +:hashOperation: pass:normal[xref:#TimelockController-hashOperation-address-uint256-bytes-bytes32-bytes32-[`++hashOperation++`]] +:hashOperationBatch: pass:normal[xref:#TimelockController-hashOperationBatch-address---uint256---bytes---bytes32-bytes32-[`++hashOperationBatch++`]] +:schedule: pass:normal[xref:#TimelockController-schedule-address-uint256-bytes-bytes32-bytes32-uint256-[`++schedule++`]] +:scheduleBatch: pass:normal[xref:#TimelockController-scheduleBatch-address---uint256---bytes---bytes32-bytes32-uint256-[`++scheduleBatch++`]] +:cancel: pass:normal[xref:#TimelockController-cancel-bytes32-[`++cancel++`]] +:execute: pass:normal[xref:#TimelockController-execute-address-uint256-bytes-bytes32-bytes32-[`++execute++`]] +:executeBatch: pass:normal[xref:#TimelockController-executeBatch-address---uint256---bytes---bytes32-bytes32-[`++executeBatch++`]] +:_execute: pass:normal[xref:#TimelockController-_execute-address-uint256-bytes-[`++_execute++`]] +:updateDelay: pass:normal[xref:#TimelockController-updateDelay-uint256-[`++updateDelay++`]] +:_encodeStateBitmap: pass:normal[xref:#TimelockController-_encodeStateBitmap-enum-TimelockController-OperationState-[`++_encodeStateBitmap++`]] + +[.contract] +[[TimelockController]] +=== `++TimelockController++` link:https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v5.0.0-rc.0/contracts/governance/TimelockController.sol[{github-icon},role=heading-link] + +[.hljs-theme-light.nopadding] +```solidity +import "@openzeppelin/contracts/governance/TimelockController.sol"; +``` + +Contract module which acts as a timelocked controller. When set as the +owner of an `Ownable` smart contract, it enforces a timelock on all +`onlyOwner` maintenance operations. This gives time for users of the +controlled contract to exit before a potentially dangerous maintenance +operation is applied. + +By default, this contract is self administered, meaning administration tasks +have to go through the timelock process. The proposer (resp executor) role +is in charge of proposing (resp executing) operations. A common use case is +to position this {TimelockController} as the owner of a smart contract, with +a multisig or a DAO as the sole proposer. + +[.contract-index] +.Modifiers +-- +* {xref-TimelockController-onlyRoleOrOpenRole-bytes32-}[`++onlyRoleOrOpenRole(role)++`] +-- + +[.contract-index] +.Functions +-- +* {xref-TimelockController-constructor-uint256-address---address---address-}[`++constructor(minDelay, proposers, executors, admin)++`] +* {xref-TimelockController-receive--}[`++receive()++`] +* {xref-TimelockController-supportsInterface-bytes4-}[`++supportsInterface(interfaceId)++`] +* {xref-TimelockController-isOperation-bytes32-}[`++isOperation(id)++`] +* {xref-TimelockController-isOperationPending-bytes32-}[`++isOperationPending(id)++`] +* {xref-TimelockController-isOperationReady-bytes32-}[`++isOperationReady(id)++`] +* {xref-TimelockController-isOperationDone-bytes32-}[`++isOperationDone(id)++`] +* {xref-TimelockController-getTimestamp-bytes32-}[`++getTimestamp(id)++`] +* {xref-TimelockController-getOperationState-bytes32-}[`++getOperationState(id)++`] +* {xref-TimelockController-getMinDelay--}[`++getMinDelay()++`] +* {xref-TimelockController-hashOperation-address-uint256-bytes-bytes32-bytes32-}[`++hashOperation(target, value, data, predecessor, salt)++`] +* {xref-TimelockController-hashOperationBatch-address---uint256---bytes---bytes32-bytes32-}[`++hashOperationBatch(targets, values, payloads, predecessor, salt)++`] +* {xref-TimelockController-schedule-address-uint256-bytes-bytes32-bytes32-uint256-}[`++schedule(target, value, data, predecessor, salt, delay)++`] +* {xref-TimelockController-scheduleBatch-address---uint256---bytes---bytes32-bytes32-uint256-}[`++scheduleBatch(targets, values, payloads, predecessor, salt, delay)++`] +* {xref-TimelockController-cancel-bytes32-}[`++cancel(id)++`] +* {xref-TimelockController-execute-address-uint256-bytes-bytes32-bytes32-}[`++execute(target, value, payload, predecessor, salt)++`] +* {xref-TimelockController-executeBatch-address---uint256---bytes---bytes32-bytes32-}[`++executeBatch(targets, values, payloads, predecessor, salt)++`] +* {xref-TimelockController-_execute-address-uint256-bytes-}[`++_execute(target, value, data)++`] +* {xref-TimelockController-updateDelay-uint256-}[`++updateDelay(newDelay)++`] +* {xref-TimelockController-_encodeStateBitmap-enum-TimelockController-OperationState-}[`++_encodeStateBitmap(operationState)++`] + +[.contract-subindex-inherited] +.ERC1155Holder +* {xref-ERC1155Holder-onERC1155Received-address-address-uint256-uint256-bytes-}[`++onERC1155Received(, , , , )++`] +* {xref-ERC1155Holder-onERC1155BatchReceived-address-address-uint256---uint256---bytes-}[`++onERC1155BatchReceived(, , , , )++`] + +[.contract-subindex-inherited] +.IERC1155Receiver + +[.contract-subindex-inherited] +.ERC721Holder +* {xref-ERC721Holder-onERC721Received-address-address-uint256-bytes-}[`++onERC721Received(, , , )++`] + +[.contract-subindex-inherited] +.IERC721Receiver + +[.contract-subindex-inherited] +.AccessControl +* {xref-AccessControl-hasRole-bytes32-address-}[`++hasRole(role, account)++`] +* {xref-AccessControl-_checkRole-bytes32-}[`++_checkRole(role)++`] +* {xref-AccessControl-_checkRole-bytes32-address-}[`++_checkRole(role, account)++`] +* {xref-AccessControl-getRoleAdmin-bytes32-}[`++getRoleAdmin(role)++`] +* {xref-AccessControl-grantRole-bytes32-address-}[`++grantRole(role, account)++`] +* {xref-AccessControl-revokeRole-bytes32-address-}[`++revokeRole(role, account)++`] +* {xref-AccessControl-renounceRole-bytes32-address-}[`++renounceRole(role, callerConfirmation)++`] +* {xref-AccessControl-_setRoleAdmin-bytes32-bytes32-}[`++_setRoleAdmin(role, adminRole)++`] +* {xref-AccessControl-_grantRole-bytes32-address-}[`++_grantRole(role, account)++`] +* {xref-AccessControl-_revokeRole-bytes32-address-}[`++_revokeRole(role, account)++`] + +[.contract-subindex-inherited] +.ERC165 + +[.contract-subindex-inherited] +.IERC165 + +[.contract-subindex-inherited] +.IAccessControl + +-- + +[.contract-index] +.Events +-- +* {xref-TimelockController-CallScheduled-bytes32-uint256-address-uint256-bytes-bytes32-uint256-}[`++CallScheduled(id, index, target, value, data, predecessor, delay)++`] +* {xref-TimelockController-CallExecuted-bytes32-uint256-address-uint256-bytes-}[`++CallExecuted(id, index, target, value, data)++`] +* {xref-TimelockController-CallSalt-bytes32-bytes32-}[`++CallSalt(id, salt)++`] +* {xref-TimelockController-Cancelled-bytes32-}[`++Cancelled(id)++`] +* {xref-TimelockController-MinDelayChange-uint256-uint256-}[`++MinDelayChange(oldDuration, newDuration)++`] + +[.contract-subindex-inherited] +.ERC1155Holder + +[.contract-subindex-inherited] +.IERC1155Receiver + +[.contract-subindex-inherited] +.ERC721Holder + +[.contract-subindex-inherited] +.IERC721Receiver + +[.contract-subindex-inherited] +.AccessControl + +[.contract-subindex-inherited] +.ERC165 + +[.contract-subindex-inherited] +.IERC165 + +[.contract-subindex-inherited] +.IAccessControl +* {xref-IAccessControl-RoleAdminChanged-bytes32-bytes32-bytes32-}[`++RoleAdminChanged(role, previousAdminRole, newAdminRole)++`] +* {xref-IAccessControl-RoleGranted-bytes32-address-address-}[`++RoleGranted(role, account, sender)++`] +* {xref-IAccessControl-RoleRevoked-bytes32-address-address-}[`++RoleRevoked(role, account, sender)++`] + +-- + +[.contract-index] +.Errors +-- +* {xref-TimelockController-TimelockInvalidOperationLength-uint256-uint256-uint256-}[`++TimelockInvalidOperationLength(targets, payloads, values)++`] +* {xref-TimelockController-TimelockInsufficientDelay-uint256-uint256-}[`++TimelockInsufficientDelay(delay, minDelay)++`] +* {xref-TimelockController-TimelockUnexpectedOperationState-bytes32-bytes32-}[`++TimelockUnexpectedOperationState(operationId, expectedStates)++`] +* {xref-TimelockController-TimelockUnexecutedPredecessor-bytes32-}[`++TimelockUnexecutedPredecessor(predecessorId)++`] +* {xref-TimelockController-TimelockUnauthorizedCaller-address-}[`++TimelockUnauthorizedCaller(caller)++`] + +[.contract-subindex-inherited] +.ERC1155Holder + +[.contract-subindex-inherited] +.IERC1155Receiver + +[.contract-subindex-inherited] +.ERC721Holder + +[.contract-subindex-inherited] +.IERC721Receiver + +[.contract-subindex-inherited] +.AccessControl + +[.contract-subindex-inherited] +.ERC165 + +[.contract-subindex-inherited] +.IERC165 + +[.contract-subindex-inherited] +.IAccessControl +* {xref-IAccessControl-AccessControlUnauthorizedAccount-address-bytes32-}[`++AccessControlUnauthorizedAccount(account, neededRole)++`] +* {xref-IAccessControl-AccessControlBadConfirmation--}[`++AccessControlBadConfirmation()++`] + +-- + +[.contract-item] +[[TimelockController-onlyRoleOrOpenRole-bytes32-]] +==== `[.contract-item-name]#++onlyRoleOrOpenRole++#++(bytes32 role)++` [.item-kind]#modifier# + +Modifier to make a function callable only by a certain role. In +addition to checking the sender's role, `address(0)` 's role is also +considered. Granting a role to `address(0)` is equivalent to enabling +this role for everyone. + +[.contract-item] +[[TimelockController-constructor-uint256-address---address---address-]] +==== `[.contract-item-name]#++constructor++#++(uint256 minDelay, address[] proposers, address[] executors, address admin)++` [.item-kind]#public# + +Initializes the contract with the following parameters: + +- `minDelay`: initial minimum delay in seconds for operations +- `proposers`: accounts to be granted proposer and canceller roles +- `executors`: accounts to be granted executor role +- `admin`: optional account to be granted admin role; disable with zero address + +IMPORTANT: The optional admin can aid with initial configuration of roles after deployment +without being subject to delay, but this role should be subsequently renounced in favor of +administration through timelocked proposals. Previous versions of this contract would assign +this admin to the deployer automatically and should be renounced as well. + +[.contract-item] +[[TimelockController-receive--]] +==== `[.contract-item-name]#++receive++#++()++` [.item-kind]#external# + +Contract might receive/hold ETH as part of the maintenance process. + +[.contract-item] +[[TimelockController-supportsInterface-bytes4-]] +==== `[.contract-item-name]#++supportsInterface++#++(bytes4 interfaceId) → bool++` [.item-kind]#public# + +See {IERC165-supportsInterface}. + +[.contract-item] +[[TimelockController-isOperation-bytes32-]] +==== `[.contract-item-name]#++isOperation++#++(bytes32 id) → bool++` [.item-kind]#public# + +Returns whether an id corresponds to a registered operation. This +includes both Waiting, Ready, and Done operations. + +[.contract-item] +[[TimelockController-isOperationPending-bytes32-]] +==== `[.contract-item-name]#++isOperationPending++#++(bytes32 id) → bool++` [.item-kind]#public# + +Returns whether an operation is pending or not. Note that a "pending" operation may also be "ready". + +[.contract-item] +[[TimelockController-isOperationReady-bytes32-]] +==== `[.contract-item-name]#++isOperationReady++#++(bytes32 id) → bool++` [.item-kind]#public# + +Returns whether an operation is ready for execution. Note that a "ready" operation is also "pending". + +[.contract-item] +[[TimelockController-isOperationDone-bytes32-]] +==== `[.contract-item-name]#++isOperationDone++#++(bytes32 id) → bool++` [.item-kind]#public# + +Returns whether an operation is done or not. + +[.contract-item] +[[TimelockController-getTimestamp-bytes32-]] +==== `[.contract-item-name]#++getTimestamp++#++(bytes32 id) → uint256++` [.item-kind]#public# + +Returns the timestamp at which an operation becomes ready (0 for +unset operations, 1 for done operations). + +[.contract-item] +[[TimelockController-getOperationState-bytes32-]] +==== `[.contract-item-name]#++getOperationState++#++(bytes32 id) → enum TimelockController.OperationState++` [.item-kind]#public# + +Returns operation state. + +[.contract-item] +[[TimelockController-getMinDelay--]] +==== `[.contract-item-name]#++getMinDelay++#++() → uint256++` [.item-kind]#public# + +Returns the minimum delay in seconds for an operation to become valid. + +This value can be changed by executing an operation that calls `updateDelay`. + +[.contract-item] +[[TimelockController-hashOperation-address-uint256-bytes-bytes32-bytes32-]] +==== `[.contract-item-name]#++hashOperation++#++(address target, uint256 value, bytes data, bytes32 predecessor, bytes32 salt) → bytes32++` [.item-kind]#public# + +Returns the identifier of an operation containing a single +transaction. + +[.contract-item] +[[TimelockController-hashOperationBatch-address---uint256---bytes---bytes32-bytes32-]] +==== `[.contract-item-name]#++hashOperationBatch++#++(address[] targets, uint256[] values, bytes[] payloads, bytes32 predecessor, bytes32 salt) → bytes32++` [.item-kind]#public# + +Returns the identifier of an operation containing a batch of +transactions. + +[.contract-item] +[[TimelockController-schedule-address-uint256-bytes-bytes32-bytes32-uint256-]] +==== `[.contract-item-name]#++schedule++#++(address target, uint256 value, bytes data, bytes32 predecessor, bytes32 salt, uint256 delay)++` [.item-kind]#public# + +Schedule an operation containing a single transaction. + +Emits {CallSalt} if salt is nonzero, and {CallScheduled}. + +Requirements: + +- the caller must have the 'proposer' role. + +[.contract-item] +[[TimelockController-scheduleBatch-address---uint256---bytes---bytes32-bytes32-uint256-]] +==== `[.contract-item-name]#++scheduleBatch++#++(address[] targets, uint256[] values, bytes[] payloads, bytes32 predecessor, bytes32 salt, uint256 delay)++` [.item-kind]#public# + +Schedule an operation containing a batch of transactions. + +Emits {CallSalt} if salt is nonzero, and one {CallScheduled} event per transaction in the batch. + +Requirements: + +- the caller must have the 'proposer' role. + +[.contract-item] +[[TimelockController-cancel-bytes32-]] +==== `[.contract-item-name]#++cancel++#++(bytes32 id)++` [.item-kind]#public# + +Cancel an operation. + +Requirements: + +- the caller must have the 'canceller' role. + +[.contract-item] +[[TimelockController-execute-address-uint256-bytes-bytes32-bytes32-]] +==== `[.contract-item-name]#++execute++#++(address target, uint256 value, bytes payload, bytes32 predecessor, bytes32 salt)++` [.item-kind]#public# + +Execute an (ready) operation containing a single transaction. + +Emits a {CallExecuted} event. + +Requirements: + +- the caller must have the 'executor' role. + +[.contract-item] +[[TimelockController-executeBatch-address---uint256---bytes---bytes32-bytes32-]] +==== `[.contract-item-name]#++executeBatch++#++(address[] targets, uint256[] values, bytes[] payloads, bytes32 predecessor, bytes32 salt)++` [.item-kind]#public# + +Execute an (ready) operation containing a batch of transactions. + +Emits one {CallExecuted} event per transaction in the batch. + +Requirements: + +- the caller must have the 'executor' role. + +[.contract-item] +[[TimelockController-_execute-address-uint256-bytes-]] +==== `[.contract-item-name]#++_execute++#++(address target, uint256 value, bytes data)++` [.item-kind]#internal# + +Execute an operation's call. + +[.contract-item] +[[TimelockController-updateDelay-uint256-]] +==== `[.contract-item-name]#++updateDelay++#++(uint256 newDelay)++` [.item-kind]#external# + +Changes the minimum timelock duration for future operations. + +Emits a {MinDelayChange} event. + +Requirements: + +- the caller must be the timelock itself. This can only be achieved by scheduling and later executing +an operation where the timelock is the target and the data is the ABI-encoded call to this function. + +[.contract-item] +[[TimelockController-_encodeStateBitmap-enum-TimelockController-OperationState-]] +==== `[.contract-item-name]#++_encodeStateBitmap++#++(enum TimelockController.OperationState operationState) → bytes32++` [.item-kind]#internal# + +Encodes a `OperationState` into a `bytes32` representation where each bit enabled corresponds to +the underlying position in the `OperationState` enum. For example: + +0x000...1000 + ^^^^^^----- ... + ^---- Done + ^--- Ready + ^-- Waiting + ^- Unset + +[.contract-item] +[[TimelockController-CallScheduled-bytes32-uint256-address-uint256-bytes-bytes32-uint256-]] +==== `[.contract-item-name]#++CallScheduled++#++(bytes32 indexed id, uint256 indexed index, address target, uint256 value, bytes data, bytes32 predecessor, uint256 delay)++` [.item-kind]#event# + +Emitted when a call is scheduled as part of operation `id`. + +[.contract-item] +[[TimelockController-CallExecuted-bytes32-uint256-address-uint256-bytes-]] +==== `[.contract-item-name]#++CallExecuted++#++(bytes32 indexed id, uint256 indexed index, address target, uint256 value, bytes data)++` [.item-kind]#event# + +Emitted when a call is performed as part of operation `id`. + +[.contract-item] +[[TimelockController-CallSalt-bytes32-bytes32-]] +==== `[.contract-item-name]#++CallSalt++#++(bytes32 indexed id, bytes32 salt)++` [.item-kind]#event# + +Emitted when new proposal is scheduled with non-zero salt. + +[.contract-item] +[[TimelockController-Cancelled-bytes32-]] +==== `[.contract-item-name]#++Cancelled++#++(bytes32 indexed id)++` [.item-kind]#event# + +Emitted when operation `id` is cancelled. + +[.contract-item] +[[TimelockController-MinDelayChange-uint256-uint256-]] +==== `[.contract-item-name]#++MinDelayChange++#++(uint256 oldDuration, uint256 newDuration)++` [.item-kind]#event# + +Emitted when the minimum delay for future operations is modified. + +[.contract-item] +[[TimelockController-TimelockInvalidOperationLength-uint256-uint256-uint256-]] +==== `[.contract-item-name]#++TimelockInvalidOperationLength++#++(uint256 targets, uint256 payloads, uint256 values)++` [.item-kind]#error# + +Mismatch between the parameters length for an operation call. + +[.contract-item] +[[TimelockController-TimelockInsufficientDelay-uint256-uint256-]] +==== `[.contract-item-name]#++TimelockInsufficientDelay++#++(uint256 delay, uint256 minDelay)++` [.item-kind]#error# + +The schedule operation doesn't meet the minimum delay. + +[.contract-item] +[[TimelockController-TimelockUnexpectedOperationState-bytes32-bytes32-]] +==== `[.contract-item-name]#++TimelockUnexpectedOperationState++#++(bytes32 operationId, bytes32 expectedStates)++` [.item-kind]#error# + +The current state of an operation is not as required. +The `expectedStates` is a bitmap with the bits enabled for each OperationState enum position +counting from right to left. + +See {_encodeStateBitmap}. + +[.contract-item] +[[TimelockController-TimelockUnexecutedPredecessor-bytes32-]] +==== `[.contract-item-name]#++TimelockUnexecutedPredecessor++#++(bytes32 predecessorId)++` [.item-kind]#error# + +The predecessor to an operation not yet done. + +[.contract-item] +[[TimelockController-TimelockUnauthorizedCaller-address-]] +==== `[.contract-item-name]#++TimelockUnauthorizedCaller++#++(address caller)++` [.item-kind]#error# + +The caller account is not authorized. + +[[timelock-terminology]] +==== Terminology + +* *Operation:* A transaction (or a set of transactions) that is the subject of the timelock. It has to be scheduled by a proposer and executed by an executor. The timelock enforces a minimum delay between the proposition and the execution (see xref:access-control.adoc#operation_lifecycle[operation lifecycle]). If the operation contains multiple transactions (batch mode), they are executed atomically. Operations are identified by the hash of their content. +* *Operation status:* +** *Unset:* An operation that is not part of the timelock mechanism. +** *Waiting:* An operation that has been scheduled, before the timer expires. +** *Ready:* An operation that has been scheduled, after the timer expires. +** *Pending:* An operation that is either waiting or ready. +** *Done:* An operation that has been executed. +* *Predecessor*: An (optional) dependency between operations. An operation can depend on another operation (its predecessor), forcing the execution order of these two operations. +* *Role*: +** *Admin:* An address (smart contract or EOA) that is in charge of granting the roles of Proposer and Executor. +** *Proposer:* An address (smart contract or EOA) that is in charge of scheduling (and cancelling) operations. +** *Executor:* An address (smart contract or EOA) that is in charge of executing operations once the timelock has expired. This role can be given to the zero address to allow anyone to execute operations. + +[[timelock-operation]] +==== Operation structure + +Operation executed by the xref:api:governance.adoc#TimelockController[`TimelockController`] can contain one or multiple subsequent calls. Depending on whether you need to multiple calls to be executed atomically, you can either use simple or batched operations. + +Both operations contain: + +* *Target*, the address of the smart contract that the timelock should operate on. +* *Value*, in wei, that should be sent with the transaction. Most of the time this will be 0. Ether can be deposited before-end or passed along when executing the transaction. +* *Data*, containing the encoded function selector and parameters of the call. This can be produced using a number of tools. For example, a maintenance operation granting role `ROLE` to `ACCOUNT` can be encoded using web3js as follows: + +```javascript +const data = timelock.contract.methods.grantRole(ROLE, ACCOUNT).encodeABI() +``` + +* *Predecessor*, that specifies a dependency between operations. This dependency is optional. Use `bytes32(0)` if the operation does not have any dependency. +* *Salt*, used to disambiguate two otherwise identical operations. This can be any random value. + +In the case of batched operations, `target`, `value` and `data` are specified as arrays, which must be of the same length. + +[[timelock-operation-lifecycle]] +==== Operation lifecycle + +Timelocked operations are identified by a unique id (their hash) and follow a specific lifecycle: + +`Unset` -> `Pending` -> `Pending` + `Ready` -> `Done` + +* By calling xref:api:governance.adoc#TimelockController-schedule-address-uint256-bytes-bytes32-bytes32-uint256-[`schedule`] (or xref:api:governance.adoc#TimelockController-scheduleBatch-address---uint256---bytes---bytes32-bytes32-uint256-[`scheduleBatch`]), a proposer moves the operation from the `Unset` to the `Pending` state. This starts a timer that must be longer than the minimum delay. The timer expires at a timestamp accessible through the xref:api:governance.adoc#TimelockController-getTimestamp-bytes32-[`getTimestamp`] method. +* Once the timer expires, the operation automatically gets the `Ready` state. At this point, it can be executed. +* By calling xref:api:governance.adoc#TimelockController-TimelockController-execute-address-uint256-bytes-bytes32-bytes32-[`execute`] (or xref:api:governance.adoc#TimelockController-executeBatch-address---uint256---bytes---bytes32-bytes32-[`executeBatch`]), an executor triggers the operation's underlying transactions and moves it to the `Done` state. If the operation has a predecessor, it has to be in the `Done` state for this transition to succeed. +* xref:api:governance.adoc#TimelockController-TimelockController-cancel-bytes32-[`cancel`] allows proposers to cancel any `Pending` operation. This resets the operation to the `Unset` state. It is thus possible for a proposer to re-schedule an operation that has been cancelled. In this case, the timer restarts when the operation is re-scheduled. + +Operations status can be queried using the functions: + +* xref:api:governance.adoc#TimelockController-isOperationPending-bytes32-[`isOperationPending(bytes32)`] +* xref:api:governance.adoc#TimelockController-isOperationReady-bytes32-[`isOperationReady(bytes32)`] +* xref:api:governance.adoc#TimelockController-isOperationDone-bytes32-[`isOperationDone(bytes32)`] + +[[timelock-roles]] +==== Roles + +[[timelock-admin]] +===== Admin + +The admins are in charge of managing proposers and executors. For the timelock to be self-governed, this role should only be given to the timelock itself. Upon deployment, the admin role can be granted to any address (in addition to the timelock itself). After further configuration and testing, this optional admin should renounce its role such that all further maintenance operations have to go through the timelock process. + +[[timelock-proposer]] +===== Proposer + +The proposers are in charge of scheduling (and cancelling) operations. This is a critical role, that should be given to governing entities. This could be an EOA, a multisig, or a DAO. + +WARNING: *Proposer fight:* Having multiple proposers, while providing redundancy in case one becomes unavailable, can be dangerous. As proposer have their say on all operations, they could cancel operations they disagree with, including operations to remove them for the proposers. + +This role is identified by the *PROPOSER_ROLE* value: `0xb09aa5aeb3702cfd50b6b62bc4532604938f21248a27a1d5ca736082b6819cc1` + +[[timelock-executor]] +===== Executor + +The executors are in charge of executing the operations scheduled by the proposers once the timelock expires. Logic dictates that multisig or DAO that are proposers should also be executors in order to guarantee operations that have been scheduled will eventually be executed. However, having additional executors can reduce the cost (the executing transaction does not require validation by the multisig or DAO that proposed it), while ensuring whoever is in charge of execution cannot trigger actions that have not been scheduled by the proposers. Alternatively, it is possible to allow _any_ address to execute a proposal once the timelock has expired by granting the executor role to the zero address. + +This role is identified by the *EXECUTOR_ROLE* value: `0xd8aa0f3194971a2a116679f7c2090f6939c8d4e01a2a8d7e41d55e5351469e63` + +WARNING: A live contract without at least one proposer and one executor is locked. Make sure these roles are filled by reliable entities before the deployer renounces its administrative rights in favour of the timelock contract itself. See the {AccessControl} documentation to learn more about role management. + diff --git a/docs/modules/api/pages/interfaces.adoc b/docs/modules/api/pages/interfaces.adoc new file mode 100644 index 000000000..870109f76 --- /dev/null +++ b/docs/modules/api/pages/interfaces.adoc @@ -0,0 +1,1410 @@ +:github-icon: pass:[] +:IERC20: pass:normal[xref:token/ERC20.adoc#IERC20[`IERC20`]] +:IERC20Errors: pass:normal[xref:interfaces.adoc#IERC20Errors[`IERC20Errors`]] +:IERC20Metadata: pass:normal[xref:token/ERC20.adoc#IERC20Metadata[`IERC20Metadata`]] +:IERC165: pass:normal[xref:utils.adoc#IERC165[`IERC165`]] +:IERC721: pass:normal[xref:token/ERC721.adoc#IERC721[`IERC721`]] +:IERC721Receiver: pass:normal[xref:token/ERC721.adoc#IERC721Receiver[`IERC721Receiver`]] +:IERC721Enumerable: pass:normal[xref:token/ERC721.adoc#IERC721Enumerable[`IERC721Enumerable`]] +:IERC721Metadata: pass:normal[xref:token/ERC721.adoc#IERC721Metadata[`IERC721Metadata`]] +:IERC721Errors: pass:normal[xref:interfaces.adoc#IERC721Errors[`IERC721Errors`]] +:IERC777: pass:normal[xref:interfaces.adoc#IERC777[`IERC777`]] +:IERC777Recipient: pass:normal[xref:interfaces.adoc#IERC777Recipient[`IERC777Recipient`]] +:IERC777Sender: pass:normal[xref:interfaces.adoc#IERC777Sender[`IERC777Sender`]] +:IERC1155: pass:normal[xref:token/ERC1155.adoc#IERC1155[`IERC1155`]] +:IERC1155Receiver: pass:normal[xref:token/ERC1155.adoc#IERC1155Receiver[`IERC1155Receiver`]] +:IERC1155MetadataURI: pass:normal[xref:token/ERC1155.adoc#IERC1155MetadataURI[`IERC1155MetadataURI`]] +:IERC1155Errors: pass:normal[xref:interfaces.adoc#IERC1155Errors[`IERC1155Errors`]] +:IERC1271: pass:normal[xref:interfaces.adoc#IERC1271[`IERC1271`]] +:IERC1363: pass:normal[xref:interfaces.adoc#IERC1363[`IERC1363`]] +:IERC1363Receiver: pass:normal[xref:interfaces.adoc#IERC1363Receiver[`IERC1363Receiver`]] +:IERC1363Spender: pass:normal[xref:interfaces.adoc#IERC1363Spender[`IERC1363Spender`]] +:IERC1820Implementer: pass:normal[xref:interfaces.adoc#IERC1820Implementer[`IERC1820Implementer`]] +:IERC1820Registry: pass:normal[xref:interfaces.adoc#IERC1820Registry[`IERC1820Registry`]] +:IERC1822Proxiable: pass:normal[xref:interfaces.adoc#IERC1822Proxiable[`IERC1822Proxiable`]] +:IERC2612: pass:normal[xref:interfaces.adoc#IERC2612[`IERC2612`]] +:IERC2981: pass:normal[xref:interfaces.adoc#IERC2981[`IERC2981`]] +:IERC3156FlashLender: pass:normal[xref:interfaces.adoc#IERC3156FlashLender[`IERC3156FlashLender`]] +:IERC3156FlashBorrower: pass:normal[xref:interfaces.adoc#IERC3156FlashBorrower[`IERC3156FlashBorrower`]] +:IERC4626: pass:normal[xref:interfaces.adoc#IERC4626[`IERC4626`]] +:IERC4906: pass:normal[xref:interfaces.adoc#IERC4906[`IERC4906`]] +:IERC5267: pass:normal[xref:interfaces.adoc#IERC5267[`IERC5267`]] +:IERC5313: pass:normal[xref:interfaces.adoc#IERC5313[`IERC5313`]] +:IERC5805: pass:normal[xref:interfaces.adoc#IERC5805[`IERC5805`]] +:IERC6372: pass:normal[xref:interfaces.adoc#IERC6372[`IERC6372`]] +:xref-IERC20Errors-ERC20InsufficientBalance-address-uint256-uint256-: xref:interfaces.adoc#IERC20Errors-ERC20InsufficientBalance-address-uint256-uint256- +:xref-IERC20Errors-ERC20InvalidSender-address-: xref:interfaces.adoc#IERC20Errors-ERC20InvalidSender-address- +:xref-IERC20Errors-ERC20InvalidReceiver-address-: xref:interfaces.adoc#IERC20Errors-ERC20InvalidReceiver-address- +:xref-IERC20Errors-ERC20InsufficientAllowance-address-uint256-uint256-: xref:interfaces.adoc#IERC20Errors-ERC20InsufficientAllowance-address-uint256-uint256- +:xref-IERC20Errors-ERC20InvalidApprover-address-: xref:interfaces.adoc#IERC20Errors-ERC20InvalidApprover-address- +:xref-IERC20Errors-ERC20InvalidSpender-address-: xref:interfaces.adoc#IERC20Errors-ERC20InvalidSpender-address- +:xref-IERC721Errors-ERC721InvalidOwner-address-: xref:interfaces.adoc#IERC721Errors-ERC721InvalidOwner-address- +:xref-IERC721Errors-ERC721NonexistentToken-uint256-: xref:interfaces.adoc#IERC721Errors-ERC721NonexistentToken-uint256- +:xref-IERC721Errors-ERC721IncorrectOwner-address-uint256-address-: xref:interfaces.adoc#IERC721Errors-ERC721IncorrectOwner-address-uint256-address- +:xref-IERC721Errors-ERC721InvalidSender-address-: xref:interfaces.adoc#IERC721Errors-ERC721InvalidSender-address- +:xref-IERC721Errors-ERC721InvalidReceiver-address-: xref:interfaces.adoc#IERC721Errors-ERC721InvalidReceiver-address- +:xref-IERC721Errors-ERC721InsufficientApproval-address-uint256-: xref:interfaces.adoc#IERC721Errors-ERC721InsufficientApproval-address-uint256- +:xref-IERC721Errors-ERC721InvalidApprover-address-: xref:interfaces.adoc#IERC721Errors-ERC721InvalidApprover-address- +:xref-IERC721Errors-ERC721InvalidOperator-address-: xref:interfaces.adoc#IERC721Errors-ERC721InvalidOperator-address- +:xref-IERC1155Errors-ERC1155InsufficientBalance-address-uint256-uint256-uint256-: xref:interfaces.adoc#IERC1155Errors-ERC1155InsufficientBalance-address-uint256-uint256-uint256- +:xref-IERC1155Errors-ERC1155InvalidSender-address-: xref:interfaces.adoc#IERC1155Errors-ERC1155InvalidSender-address- +:xref-IERC1155Errors-ERC1155InvalidReceiver-address-: xref:interfaces.adoc#IERC1155Errors-ERC1155InvalidReceiver-address- +:xref-IERC1155Errors-ERC1155MissingApprovalForAll-address-address-: xref:interfaces.adoc#IERC1155Errors-ERC1155MissingApprovalForAll-address-address- +:xref-IERC1155Errors-ERC1155InvalidApprover-address-: xref:interfaces.adoc#IERC1155Errors-ERC1155InvalidApprover-address- +:xref-IERC1155Errors-ERC1155InvalidOperator-address-: xref:interfaces.adoc#IERC1155Errors-ERC1155InvalidOperator-address- +:xref-IERC1155Errors-ERC1155InvalidArrayLength-uint256-uint256-: xref:interfaces.adoc#IERC1155Errors-ERC1155InvalidArrayLength-uint256-uint256- +:xref-IERC1271-isValidSignature-bytes32-bytes-: xref:interfaces.adoc#IERC1271-isValidSignature-bytes32-bytes- +:xref-IERC1363-transferAndCall-address-uint256-: xref:interfaces.adoc#IERC1363-transferAndCall-address-uint256- +:xref-IERC1363-transferAndCall-address-uint256-bytes-: xref:interfaces.adoc#IERC1363-transferAndCall-address-uint256-bytes- +:xref-IERC1363-transferFromAndCall-address-address-uint256-: xref:interfaces.adoc#IERC1363-transferFromAndCall-address-address-uint256- +:xref-IERC1363-transferFromAndCall-address-address-uint256-bytes-: xref:interfaces.adoc#IERC1363-transferFromAndCall-address-address-uint256-bytes- +:xref-IERC1363-approveAndCall-address-uint256-: xref:interfaces.adoc#IERC1363-approveAndCall-address-uint256- +:xref-IERC1363-approveAndCall-address-uint256-bytes-: xref:interfaces.adoc#IERC1363-approveAndCall-address-uint256-bytes- +:xref-IERC20-totalSupply--: xref:token/ERC20.adoc#IERC20-totalSupply-- +:xref-IERC20-balanceOf-address-: xref:token/ERC20.adoc#IERC20-balanceOf-address- +:xref-IERC20-transfer-address-uint256-: xref:token/ERC20.adoc#IERC20-transfer-address-uint256- +:xref-IERC20-allowance-address-address-: xref:token/ERC20.adoc#IERC20-allowance-address-address- +:xref-IERC20-approve-address-uint256-: xref:token/ERC20.adoc#IERC20-approve-address-uint256- +:xref-IERC20-transferFrom-address-address-uint256-: xref:token/ERC20.adoc#IERC20-transferFrom-address-address-uint256- +:xref-IERC165-supportsInterface-bytes4-: xref:utils.adoc#IERC165-supportsInterface-bytes4- +:xref-IERC20-Transfer-address-address-uint256-: xref:token/ERC20.adoc#IERC20-Transfer-address-address-uint256- +:xref-IERC20-Approval-address-address-uint256-: xref:token/ERC20.adoc#IERC20-Approval-address-address-uint256- +:IERC1363-transferAndCall: pass:normal[xref:interfaces.adoc#IERC1363-transferAndCall-address-uint256-bytes-[`IERC1363.transferAndCall`]] +:IERC1363-transferFromAndCall: pass:normal[xref:interfaces.adoc#IERC1363-transferFromAndCall-address-address-uint256-bytes-[`IERC1363.transferFromAndCall`]] +:xref-IERC1363Receiver-onTransferReceived-address-address-uint256-bytes-: xref:interfaces.adoc#IERC1363Receiver-onTransferReceived-address-address-uint256-bytes- +:IERC1363-approveAndCall: pass:normal[xref:interfaces.adoc#IERC1363-approveAndCall-address-uint256-bytes-[`IERC1363.approveAndCall`]] +:xref-IERC1363Spender-onApprovalReceived-address-uint256-bytes-: xref:interfaces.adoc#IERC1363Spender-onApprovalReceived-address-uint256-bytes- +:IERC1820Registry: pass:normal[xref:interfaces.adoc#IERC1820Registry[`IERC1820Registry`]] +:xref-IERC1820Implementer-canImplementInterfaceForAddress-bytes32-address-: xref:interfaces.adoc#IERC1820Implementer-canImplementInterfaceForAddress-bytes32-address- +:IERC1820Registry-setInterfaceImplementer: pass:normal[xref:interfaces.adoc#IERC1820Registry-setInterfaceImplementer-address-bytes32-address-[`IERC1820Registry.setInterfaceImplementer`]] +:IERC165: pass:normal[xref:utils.adoc#IERC165[`IERC165`]] +:xref-IERC1820Registry-setManager-address-address-: xref:interfaces.adoc#IERC1820Registry-setManager-address-address- +:xref-IERC1820Registry-getManager-address-: xref:interfaces.adoc#IERC1820Registry-getManager-address- +:xref-IERC1820Registry-setInterfaceImplementer-address-bytes32-address-: xref:interfaces.adoc#IERC1820Registry-setInterfaceImplementer-address-bytes32-address- +:xref-IERC1820Registry-getInterfaceImplementer-address-bytes32-: xref:interfaces.adoc#IERC1820Registry-getInterfaceImplementer-address-bytes32- +:xref-IERC1820Registry-interfaceHash-string-: xref:interfaces.adoc#IERC1820Registry-interfaceHash-string- +:xref-IERC1820Registry-updateERC165Cache-address-bytes4-: xref:interfaces.adoc#IERC1820Registry-updateERC165Cache-address-bytes4- +:xref-IERC1820Registry-implementsERC165Interface-address-bytes4-: xref:interfaces.adoc#IERC1820Registry-implementsERC165Interface-address-bytes4- +:xref-IERC1820Registry-implementsERC165InterfaceNoCache-address-bytes4-: xref:interfaces.adoc#IERC1820Registry-implementsERC165InterfaceNoCache-address-bytes4- +:xref-IERC1820Registry-InterfaceImplementerSet-address-bytes32-address-: xref:interfaces.adoc#IERC1820Registry-InterfaceImplementerSet-address-bytes32-address- +:xref-IERC1820Registry-ManagerChanged-address-address-: xref:interfaces.adoc#IERC1820Registry-ManagerChanged-address-address- +:IERC165: pass:normal[xref:utils.adoc#IERC165[`IERC165`]] +:IERC1820Implementer: pass:normal[xref:interfaces.adoc#IERC1820Implementer[`IERC1820Implementer`]] +:IERC1820Implementer-canImplementInterfaceForAddress: pass:normal[xref:interfaces.adoc#IERC1820Implementer-canImplementInterfaceForAddress-bytes32-address-[`IERC1820Implementer.canImplementInterfaceForAddress`]] +:IERC165: pass:normal[xref:utils.adoc#IERC165[`IERC165`]] +:xref-IERC1822Proxiable-proxiableUUID--: xref:interfaces.adoc#IERC1822Proxiable-proxiableUUID-- +:xref-IERC20Permit-permit-address-address-uint256-uint256-uint8-bytes32-bytes32-: xref:token/ERC20.adoc#IERC20Permit-permit-address-address-uint256-uint256-uint8-bytes32-bytes32- +:xref-IERC20Permit-nonces-address-: xref:token/ERC20.adoc#IERC20Permit-nonces-address- +:xref-IERC20Permit-DOMAIN_SEPARATOR--: xref:token/ERC20.adoc#IERC20Permit-DOMAIN_SEPARATOR-- +:xref-IERC2981-royaltyInfo-uint256-uint256-: xref:interfaces.adoc#IERC2981-royaltyInfo-uint256-uint256- +:xref-IERC165-supportsInterface-bytes4-: xref:utils.adoc#IERC165-supportsInterface-bytes4- +:xref-IERC3156FlashLender-maxFlashLoan-address-: xref:interfaces.adoc#IERC3156FlashLender-maxFlashLoan-address- +:xref-IERC3156FlashLender-flashFee-address-uint256-: xref:interfaces.adoc#IERC3156FlashLender-flashFee-address-uint256- +:xref-IERC3156FlashLender-flashLoan-contract-IERC3156FlashBorrower-address-uint256-bytes-: xref:interfaces.adoc#IERC3156FlashLender-flashLoan-contract-IERC3156FlashBorrower-address-uint256-bytes- +:xref-IERC3156FlashBorrower-onFlashLoan-address-address-uint256-uint256-bytes-: xref:interfaces.adoc#IERC3156FlashBorrower-onFlashLoan-address-address-uint256-uint256-bytes- +:xref-IERC4626-asset--: xref:interfaces.adoc#IERC4626-asset-- +:xref-IERC4626-totalAssets--: xref:interfaces.adoc#IERC4626-totalAssets-- +:xref-IERC4626-convertToShares-uint256-: xref:interfaces.adoc#IERC4626-convertToShares-uint256- +:xref-IERC4626-convertToAssets-uint256-: xref:interfaces.adoc#IERC4626-convertToAssets-uint256- +:xref-IERC4626-maxDeposit-address-: xref:interfaces.adoc#IERC4626-maxDeposit-address- +:xref-IERC4626-previewDeposit-uint256-: xref:interfaces.adoc#IERC4626-previewDeposit-uint256- +:xref-IERC4626-deposit-uint256-address-: xref:interfaces.adoc#IERC4626-deposit-uint256-address- +:xref-IERC4626-maxMint-address-: xref:interfaces.adoc#IERC4626-maxMint-address- +:xref-IERC4626-previewMint-uint256-: xref:interfaces.adoc#IERC4626-previewMint-uint256- +:xref-IERC4626-mint-uint256-address-: xref:interfaces.adoc#IERC4626-mint-uint256-address- +:xref-IERC4626-maxWithdraw-address-: xref:interfaces.adoc#IERC4626-maxWithdraw-address- +:xref-IERC4626-previewWithdraw-uint256-: xref:interfaces.adoc#IERC4626-previewWithdraw-uint256- +:xref-IERC4626-withdraw-uint256-address-address-: xref:interfaces.adoc#IERC4626-withdraw-uint256-address-address- +:xref-IERC4626-maxRedeem-address-: xref:interfaces.adoc#IERC4626-maxRedeem-address- +:xref-IERC4626-previewRedeem-uint256-: xref:interfaces.adoc#IERC4626-previewRedeem-uint256- +:xref-IERC4626-redeem-uint256-address-address-: xref:interfaces.adoc#IERC4626-redeem-uint256-address-address- +:xref-IERC20Metadata-name--: xref:token/ERC20.adoc#IERC20Metadata-name-- +:xref-IERC20Metadata-symbol--: xref:token/ERC20.adoc#IERC20Metadata-symbol-- +:xref-IERC20Metadata-decimals--: xref:token/ERC20.adoc#IERC20Metadata-decimals-- +:xref-IERC20-totalSupply--: xref:token/ERC20.adoc#IERC20-totalSupply-- +:xref-IERC20-balanceOf-address-: xref:token/ERC20.adoc#IERC20-balanceOf-address- +:xref-IERC20-transfer-address-uint256-: xref:token/ERC20.adoc#IERC20-transfer-address-uint256- +:xref-IERC20-allowance-address-address-: xref:token/ERC20.adoc#IERC20-allowance-address-address- +:xref-IERC20-approve-address-uint256-: xref:token/ERC20.adoc#IERC20-approve-address-uint256- +:xref-IERC20-transferFrom-address-address-uint256-: xref:token/ERC20.adoc#IERC20-transferFrom-address-address-uint256- +:xref-IERC4626-Deposit-address-address-uint256-uint256-: xref:interfaces.adoc#IERC4626-Deposit-address-address-uint256-uint256- +:xref-IERC4626-Withdraw-address-address-address-uint256-uint256-: xref:interfaces.adoc#IERC4626-Withdraw-address-address-address-uint256-uint256- +:xref-IERC20-Transfer-address-address-uint256-: xref:token/ERC20.adoc#IERC20-Transfer-address-address-uint256- +:xref-IERC20-Approval-address-address-uint256-: xref:token/ERC20.adoc#IERC20-Approval-address-address-uint256- +:xref-IERC5313-owner--: xref:interfaces.adoc#IERC5313-owner-- +:xref-IERC5267-eip712Domain--: xref:interfaces.adoc#IERC5267-eip712Domain-- +:xref-IERC5267-EIP712DomainChanged--: xref:interfaces.adoc#IERC5267-EIP712DomainChanged-- +:xref-IVotes-getVotes-address-: xref:governance.adoc#IVotes-getVotes-address- +:xref-IVotes-getPastVotes-address-uint256-: xref:governance.adoc#IVotes-getPastVotes-address-uint256- +:xref-IVotes-getPastTotalSupply-uint256-: xref:governance.adoc#IVotes-getPastTotalSupply-uint256- +:xref-IVotes-delegates-address-: xref:governance.adoc#IVotes-delegates-address- +:xref-IVotes-delegate-address-: xref:governance.adoc#IVotes-delegate-address- +:xref-IVotes-delegateBySig-address-uint256-uint256-uint8-bytes32-bytes32-: xref:governance.adoc#IVotes-delegateBySig-address-uint256-uint256-uint8-bytes32-bytes32- +:xref-IERC6372-clock--: xref:interfaces.adoc#IERC6372-clock-- +:xref-IERC6372-CLOCK_MODE--: xref:interfaces.adoc#IERC6372-CLOCK_MODE-- +:xref-IVotes-DelegateChanged-address-address-address-: xref:governance.adoc#IVotes-DelegateChanged-address-address-address- +:xref-IVotes-DelegateVotesChanged-address-uint256-uint256-: xref:governance.adoc#IVotes-DelegateVotesChanged-address-uint256-uint256- +:xref-IVotes-VotesExpiredSignature-uint256-: xref:governance.adoc#IVotes-VotesExpiredSignature-uint256- +:xref-IERC6372-clock--: xref:interfaces.adoc#IERC6372-clock-- +:xref-IERC6372-CLOCK_MODE--: xref:interfaces.adoc#IERC6372-CLOCK_MODE-- += Interfaces + +[.readme-notice] +NOTE: This document is better viewed at https://docs.openzeppelin.com/contracts/api/interfaces + +== List of standardized interfaces +These interfaces are available as `.sol` files, and also as compiler `.json` ABI files (through the npm package). These +are useful to interact with third party contracts that implement them. + +- {IERC20} +- {IERC20Errors} +- {IERC20Metadata} +- {IERC165} +- {IERC721} +- {IERC721Receiver} +- {IERC721Enumerable} +- {IERC721Metadata} +- {IERC721Errors} +- {IERC777} +- {IERC777Recipient} +- {IERC777Sender} +- {IERC1155} +- {IERC1155Receiver} +- {IERC1155MetadataURI} +- {IERC1155Errors} +- {IERC1271} +- {IERC1363} +- {IERC1363Receiver} +- {IERC1363Spender} +- {IERC1820Implementer} +- {IERC1820Registry} +- {IERC1822Proxiable} +- {IERC2612} +- {IERC2981} +- {IERC3156FlashLender} +- {IERC3156FlashBorrower} +- {IERC4626} +- {IERC4906} +- {IERC5267} +- {IERC5313} +- {IERC5805} +- {IERC6372} + +== Detailed ABI + +:ERC20InsufficientBalance: pass:normal[xref:#IERC20Errors-ERC20InsufficientBalance-address-uint256-uint256-[`++ERC20InsufficientBalance++`]] +:ERC20InvalidSender: pass:normal[xref:#IERC20Errors-ERC20InvalidSender-address-[`++ERC20InvalidSender++`]] +:ERC20InvalidReceiver: pass:normal[xref:#IERC20Errors-ERC20InvalidReceiver-address-[`++ERC20InvalidReceiver++`]] +:ERC20InsufficientAllowance: pass:normal[xref:#IERC20Errors-ERC20InsufficientAllowance-address-uint256-uint256-[`++ERC20InsufficientAllowance++`]] +:ERC20InvalidApprover: pass:normal[xref:#IERC20Errors-ERC20InvalidApprover-address-[`++ERC20InvalidApprover++`]] +:ERC20InvalidSpender: pass:normal[xref:#IERC20Errors-ERC20InvalidSpender-address-[`++ERC20InvalidSpender++`]] + +[.contract] +[[IERC20Errors]] +=== `++IERC20Errors++` link:https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v5.0.0-rc.0/contracts/interfaces/draft-IERC6093.sol[{github-icon},role=heading-link] + +[.hljs-theme-light.nopadding] +```solidity +import "@openzeppelin/contracts/interfaces/draft-IERC6093.sol"; +``` + +Standard ERC20 Errors +Interface of the https://eips.ethereum.org/EIPS/eip-6093[ERC-6093] custom errors for ERC20 tokens. + +[.contract-index] +.Errors +-- +* {xref-IERC20Errors-ERC20InsufficientBalance-address-uint256-uint256-}[`++ERC20InsufficientBalance(sender, balance, needed)++`] +* {xref-IERC20Errors-ERC20InvalidSender-address-}[`++ERC20InvalidSender(sender)++`] +* {xref-IERC20Errors-ERC20InvalidReceiver-address-}[`++ERC20InvalidReceiver(receiver)++`] +* {xref-IERC20Errors-ERC20InsufficientAllowance-address-uint256-uint256-}[`++ERC20InsufficientAllowance(spender, allowance, needed)++`] +* {xref-IERC20Errors-ERC20InvalidApprover-address-}[`++ERC20InvalidApprover(approver)++`] +* {xref-IERC20Errors-ERC20InvalidSpender-address-}[`++ERC20InvalidSpender(spender)++`] + +-- + +[.contract-item] +[[IERC20Errors-ERC20InsufficientBalance-address-uint256-uint256-]] +==== `[.contract-item-name]#++ERC20InsufficientBalance++#++(address sender, uint256 balance, uint256 needed)++` [.item-kind]#error# + +Indicates an error related to the current `balance` of a `sender`. Used in transfers. + +[.contract-item] +[[IERC20Errors-ERC20InvalidSender-address-]] +==== `[.contract-item-name]#++ERC20InvalidSender++#++(address sender)++` [.item-kind]#error# + +Indicates a failure with the token `sender`. Used in transfers. + +[.contract-item] +[[IERC20Errors-ERC20InvalidReceiver-address-]] +==== `[.contract-item-name]#++ERC20InvalidReceiver++#++(address receiver)++` [.item-kind]#error# + +Indicates a failure with the token `receiver`. Used in transfers. + +[.contract-item] +[[IERC20Errors-ERC20InsufficientAllowance-address-uint256-uint256-]] +==== `[.contract-item-name]#++ERC20InsufficientAllowance++#++(address spender, uint256 allowance, uint256 needed)++` [.item-kind]#error# + +Indicates a failure with the `spender`’s `allowance`. Used in transfers. + +[.contract-item] +[[IERC20Errors-ERC20InvalidApprover-address-]] +==== `[.contract-item-name]#++ERC20InvalidApprover++#++(address approver)++` [.item-kind]#error# + +Indicates a failure with the `approver` of a token to be approved. Used in approvals. + +[.contract-item] +[[IERC20Errors-ERC20InvalidSpender-address-]] +==== `[.contract-item-name]#++ERC20InvalidSpender++#++(address spender)++` [.item-kind]#error# + +Indicates a failure with the `spender` to be approved. Used in approvals. + +:ERC721InvalidOwner: pass:normal[xref:#IERC721Errors-ERC721InvalidOwner-address-[`++ERC721InvalidOwner++`]] +:ERC721NonexistentToken: pass:normal[xref:#IERC721Errors-ERC721NonexistentToken-uint256-[`++ERC721NonexistentToken++`]] +:ERC721IncorrectOwner: pass:normal[xref:#IERC721Errors-ERC721IncorrectOwner-address-uint256-address-[`++ERC721IncorrectOwner++`]] +:ERC721InvalidSender: pass:normal[xref:#IERC721Errors-ERC721InvalidSender-address-[`++ERC721InvalidSender++`]] +:ERC721InvalidReceiver: pass:normal[xref:#IERC721Errors-ERC721InvalidReceiver-address-[`++ERC721InvalidReceiver++`]] +:ERC721InsufficientApproval: pass:normal[xref:#IERC721Errors-ERC721InsufficientApproval-address-uint256-[`++ERC721InsufficientApproval++`]] +:ERC721InvalidApprover: pass:normal[xref:#IERC721Errors-ERC721InvalidApprover-address-[`++ERC721InvalidApprover++`]] +:ERC721InvalidOperator: pass:normal[xref:#IERC721Errors-ERC721InvalidOperator-address-[`++ERC721InvalidOperator++`]] + +[.contract] +[[IERC721Errors]] +=== `++IERC721Errors++` link:https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v5.0.0-rc.0/contracts/interfaces/draft-IERC6093.sol[{github-icon},role=heading-link] + +[.hljs-theme-light.nopadding] +```solidity +import "@openzeppelin/contracts/interfaces/draft-IERC6093.sol"; +``` + +Standard ERC721 Errors +Interface of the https://eips.ethereum.org/EIPS/eip-6093[ERC-6093] custom errors for ERC721 tokens. + +[.contract-index] +.Errors +-- +* {xref-IERC721Errors-ERC721InvalidOwner-address-}[`++ERC721InvalidOwner(owner)++`] +* {xref-IERC721Errors-ERC721NonexistentToken-uint256-}[`++ERC721NonexistentToken(tokenId)++`] +* {xref-IERC721Errors-ERC721IncorrectOwner-address-uint256-address-}[`++ERC721IncorrectOwner(sender, tokenId, owner)++`] +* {xref-IERC721Errors-ERC721InvalidSender-address-}[`++ERC721InvalidSender(sender)++`] +* {xref-IERC721Errors-ERC721InvalidReceiver-address-}[`++ERC721InvalidReceiver(receiver)++`] +* {xref-IERC721Errors-ERC721InsufficientApproval-address-uint256-}[`++ERC721InsufficientApproval(operator, tokenId)++`] +* {xref-IERC721Errors-ERC721InvalidApprover-address-}[`++ERC721InvalidApprover(approver)++`] +* {xref-IERC721Errors-ERC721InvalidOperator-address-}[`++ERC721InvalidOperator(operator)++`] + +-- + +[.contract-item] +[[IERC721Errors-ERC721InvalidOwner-address-]] +==== `[.contract-item-name]#++ERC721InvalidOwner++#++(address owner)++` [.item-kind]#error# + +Indicates that an address can't be an owner. For example, `address(0)` is a forbidden owner in EIP-20. +Used in balance queries. + +[.contract-item] +[[IERC721Errors-ERC721NonexistentToken-uint256-]] +==== `[.contract-item-name]#++ERC721NonexistentToken++#++(uint256 tokenId)++` [.item-kind]#error# + +Indicates a `tokenId` whose `owner` is the zero address. + +[.contract-item] +[[IERC721Errors-ERC721IncorrectOwner-address-uint256-address-]] +==== `[.contract-item-name]#++ERC721IncorrectOwner++#++(address sender, uint256 tokenId, address owner)++` [.item-kind]#error# + +Indicates an error related to the ownership over a particular token. Used in transfers. + +[.contract-item] +[[IERC721Errors-ERC721InvalidSender-address-]] +==== `[.contract-item-name]#++ERC721InvalidSender++#++(address sender)++` [.item-kind]#error# + +Indicates a failure with the token `sender`. Used in transfers. + +[.contract-item] +[[IERC721Errors-ERC721InvalidReceiver-address-]] +==== `[.contract-item-name]#++ERC721InvalidReceiver++#++(address receiver)++` [.item-kind]#error# + +Indicates a failure with the token `receiver`. Used in transfers. + +[.contract-item] +[[IERC721Errors-ERC721InsufficientApproval-address-uint256-]] +==== `[.contract-item-name]#++ERC721InsufficientApproval++#++(address operator, uint256 tokenId)++` [.item-kind]#error# + +Indicates a failure with the `operator`’s approval. Used in transfers. + +[.contract-item] +[[IERC721Errors-ERC721InvalidApprover-address-]] +==== `[.contract-item-name]#++ERC721InvalidApprover++#++(address approver)++` [.item-kind]#error# + +Indicates a failure with the `approver` of a token to be approved. Used in approvals. + +[.contract-item] +[[IERC721Errors-ERC721InvalidOperator-address-]] +==== `[.contract-item-name]#++ERC721InvalidOperator++#++(address operator)++` [.item-kind]#error# + +Indicates a failure with the `operator` to be approved. Used in approvals. + +:ERC1155InsufficientBalance: pass:normal[xref:#IERC1155Errors-ERC1155InsufficientBalance-address-uint256-uint256-uint256-[`++ERC1155InsufficientBalance++`]] +:ERC1155InvalidSender: pass:normal[xref:#IERC1155Errors-ERC1155InvalidSender-address-[`++ERC1155InvalidSender++`]] +:ERC1155InvalidReceiver: pass:normal[xref:#IERC1155Errors-ERC1155InvalidReceiver-address-[`++ERC1155InvalidReceiver++`]] +:ERC1155MissingApprovalForAll: pass:normal[xref:#IERC1155Errors-ERC1155MissingApprovalForAll-address-address-[`++ERC1155MissingApprovalForAll++`]] +:ERC1155InvalidApprover: pass:normal[xref:#IERC1155Errors-ERC1155InvalidApprover-address-[`++ERC1155InvalidApprover++`]] +:ERC1155InvalidOperator: pass:normal[xref:#IERC1155Errors-ERC1155InvalidOperator-address-[`++ERC1155InvalidOperator++`]] +:ERC1155InvalidArrayLength: pass:normal[xref:#IERC1155Errors-ERC1155InvalidArrayLength-uint256-uint256-[`++ERC1155InvalidArrayLength++`]] + +[.contract] +[[IERC1155Errors]] +=== `++IERC1155Errors++` link:https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v5.0.0-rc.0/contracts/interfaces/draft-IERC6093.sol[{github-icon},role=heading-link] + +[.hljs-theme-light.nopadding] +```solidity +import "@openzeppelin/contracts/interfaces/draft-IERC6093.sol"; +``` + +Standard ERC1155 Errors +Interface of the https://eips.ethereum.org/EIPS/eip-6093[ERC-6093] custom errors for ERC1155 tokens. + +[.contract-index] +.Errors +-- +* {xref-IERC1155Errors-ERC1155InsufficientBalance-address-uint256-uint256-uint256-}[`++ERC1155InsufficientBalance(sender, balance, needed, tokenId)++`] +* {xref-IERC1155Errors-ERC1155InvalidSender-address-}[`++ERC1155InvalidSender(sender)++`] +* {xref-IERC1155Errors-ERC1155InvalidReceiver-address-}[`++ERC1155InvalidReceiver(receiver)++`] +* {xref-IERC1155Errors-ERC1155MissingApprovalForAll-address-address-}[`++ERC1155MissingApprovalForAll(operator, owner)++`] +* {xref-IERC1155Errors-ERC1155InvalidApprover-address-}[`++ERC1155InvalidApprover(approver)++`] +* {xref-IERC1155Errors-ERC1155InvalidOperator-address-}[`++ERC1155InvalidOperator(operator)++`] +* {xref-IERC1155Errors-ERC1155InvalidArrayLength-uint256-uint256-}[`++ERC1155InvalidArrayLength(idsLength, valuesLength)++`] + +-- + +[.contract-item] +[[IERC1155Errors-ERC1155InsufficientBalance-address-uint256-uint256-uint256-]] +==== `[.contract-item-name]#++ERC1155InsufficientBalance++#++(address sender, uint256 balance, uint256 needed, uint256 tokenId)++` [.item-kind]#error# + +Indicates an error related to the current `balance` of a `sender`. Used in transfers. + +[.contract-item] +[[IERC1155Errors-ERC1155InvalidSender-address-]] +==== `[.contract-item-name]#++ERC1155InvalidSender++#++(address sender)++` [.item-kind]#error# + +Indicates a failure with the token `sender`. Used in transfers. + +[.contract-item] +[[IERC1155Errors-ERC1155InvalidReceiver-address-]] +==== `[.contract-item-name]#++ERC1155InvalidReceiver++#++(address receiver)++` [.item-kind]#error# + +Indicates a failure with the token `receiver`. Used in transfers. + +[.contract-item] +[[IERC1155Errors-ERC1155MissingApprovalForAll-address-address-]] +==== `[.contract-item-name]#++ERC1155MissingApprovalForAll++#++(address operator, address owner)++` [.item-kind]#error# + +Indicates a failure with the `operator`’s approval. Used in transfers. + +[.contract-item] +[[IERC1155Errors-ERC1155InvalidApprover-address-]] +==== `[.contract-item-name]#++ERC1155InvalidApprover++#++(address approver)++` [.item-kind]#error# + +Indicates a failure with the `approver` of a token to be approved. Used in approvals. + +[.contract-item] +[[IERC1155Errors-ERC1155InvalidOperator-address-]] +==== `[.contract-item-name]#++ERC1155InvalidOperator++#++(address operator)++` [.item-kind]#error# + +Indicates a failure with the `operator` to be approved. Used in approvals. + +[.contract-item] +[[IERC1155Errors-ERC1155InvalidArrayLength-uint256-uint256-]] +==== `[.contract-item-name]#++ERC1155InvalidArrayLength++#++(uint256 idsLength, uint256 valuesLength)++` [.item-kind]#error# + +Indicates an array length mismatch between ids and values in a safeBatchTransferFrom operation. +Used in batch transfers. + +:isValidSignature: pass:normal[xref:#IERC1271-isValidSignature-bytes32-bytes-[`++isValidSignature++`]] + +[.contract] +[[IERC1271]] +=== `++IERC1271++` link:https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v5.0.0-rc.0/contracts/interfaces/IERC1271.sol[{github-icon},role=heading-link] + +[.hljs-theme-light.nopadding] +```solidity +import "@openzeppelin/contracts/interfaces/IERC1271.sol"; +``` + +Interface of the ERC1271 standard signature validation method for +contracts as defined in https://eips.ethereum.org/EIPS/eip-1271[ERC-1271]. + +[.contract-index] +.Functions +-- +* {xref-IERC1271-isValidSignature-bytes32-bytes-}[`++isValidSignature(hash, signature)++`] + +-- + +[.contract-item] +[[IERC1271-isValidSignature-bytes32-bytes-]] +==== `[.contract-item-name]#++isValidSignature++#++(bytes32 hash, bytes signature) → bytes4 magicValue++` [.item-kind]#external# + +Should return whether the signature provided is valid for the provided data + +:transferAndCall: pass:normal[xref:#IERC1363-transferAndCall-address-uint256-[`++transferAndCall++`]] +:transferAndCall: pass:normal[xref:#IERC1363-transferAndCall-address-uint256-bytes-[`++transferAndCall++`]] +:transferFromAndCall: pass:normal[xref:#IERC1363-transferFromAndCall-address-address-uint256-[`++transferFromAndCall++`]] +:transferFromAndCall: pass:normal[xref:#IERC1363-transferFromAndCall-address-address-uint256-bytes-[`++transferFromAndCall++`]] +:approveAndCall: pass:normal[xref:#IERC1363-approveAndCall-address-uint256-[`++approveAndCall++`]] +:approveAndCall: pass:normal[xref:#IERC1363-approveAndCall-address-uint256-bytes-[`++approveAndCall++`]] + +[.contract] +[[IERC1363]] +=== `++IERC1363++` link:https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v5.0.0-rc.0/contracts/interfaces/IERC1363.sol[{github-icon},role=heading-link] + +[.hljs-theme-light.nopadding] +```solidity +import "@openzeppelin/contracts/interfaces/IERC1363.sol"; +``` + +Interface of an ERC1363 compliant contract, as defined in the +https://eips.ethereum.org/EIPS/eip-1363[EIP]. + +Defines a interface for ERC20 tokens that supports executing recipient +code after `transfer` or `transferFrom`, or spender code after `approve`. + +[.contract-index] +.Functions +-- +* {xref-IERC1363-transferAndCall-address-uint256-}[`++transferAndCall(to, amount)++`] +* {xref-IERC1363-transferAndCall-address-uint256-bytes-}[`++transferAndCall(to, amount, data)++`] +* {xref-IERC1363-transferFromAndCall-address-address-uint256-}[`++transferFromAndCall(from, to, amount)++`] +* {xref-IERC1363-transferFromAndCall-address-address-uint256-bytes-}[`++transferFromAndCall(from, to, amount, data)++`] +* {xref-IERC1363-approveAndCall-address-uint256-}[`++approveAndCall(spender, amount)++`] +* {xref-IERC1363-approveAndCall-address-uint256-bytes-}[`++approveAndCall(spender, amount, data)++`] + +[.contract-subindex-inherited] +.IERC20 +* {xref-IERC20-totalSupply--}[`++totalSupply()++`] +* {xref-IERC20-balanceOf-address-}[`++balanceOf(account)++`] +* {xref-IERC20-transfer-address-uint256-}[`++transfer(to, value)++`] +* {xref-IERC20-allowance-address-address-}[`++allowance(owner, spender)++`] +* {xref-IERC20-approve-address-uint256-}[`++approve(spender, value)++`] +* {xref-IERC20-transferFrom-address-address-uint256-}[`++transferFrom(from, to, value)++`] + +[.contract-subindex-inherited] +.IERC165 +* {xref-IERC165-supportsInterface-bytes4-}[`++supportsInterface(interfaceId)++`] + +-- + +[.contract-index] +.Events +-- + +[.contract-subindex-inherited] +.IERC20 +* {xref-IERC20-Transfer-address-address-uint256-}[`++Transfer(from, to, value)++`] +* {xref-IERC20-Approval-address-address-uint256-}[`++Approval(owner, spender, value)++`] + +[.contract-subindex-inherited] +.IERC165 + +-- + +[.contract-item] +[[IERC1363-transferAndCall-address-uint256-]] +==== `[.contract-item-name]#++transferAndCall++#++(address to, uint256 amount) → bool++` [.item-kind]#external# + +Transfer tokens from `msg.sender` to another address and then call `onTransferReceived` on receiver + +[.contract-item] +[[IERC1363-transferAndCall-address-uint256-bytes-]] +==== `[.contract-item-name]#++transferAndCall++#++(address to, uint256 amount, bytes data) → bool++` [.item-kind]#external# + +Transfer tokens from `msg.sender` to another address and then call `onTransferReceived` on receiver + +[.contract-item] +[[IERC1363-transferFromAndCall-address-address-uint256-]] +==== `[.contract-item-name]#++transferFromAndCall++#++(address from, address to, uint256 amount) → bool++` [.item-kind]#external# + +Transfer tokens from one address to another and then call `onTransferReceived` on receiver + +[.contract-item] +[[IERC1363-transferFromAndCall-address-address-uint256-bytes-]] +==== `[.contract-item-name]#++transferFromAndCall++#++(address from, address to, uint256 amount, bytes data) → bool++` [.item-kind]#external# + +Transfer tokens from one address to another and then call `onTransferReceived` on receiver + +[.contract-item] +[[IERC1363-approveAndCall-address-uint256-]] +==== `[.contract-item-name]#++approveAndCall++#++(address spender, uint256 amount) → bool++` [.item-kind]#external# + +Approve the passed address to spend the specified amount of tokens on behalf of msg.sender +and then call `onApprovalReceived` on spender. + +[.contract-item] +[[IERC1363-approveAndCall-address-uint256-bytes-]] +==== `[.contract-item-name]#++approveAndCall++#++(address spender, uint256 amount, bytes data) → bool++` [.item-kind]#external# + +Approve the passed address to spend the specified amount of tokens on behalf of msg.sender +and then call `onApprovalReceived` on spender. + +:onTransferReceived: pass:normal[xref:#IERC1363Receiver-onTransferReceived-address-address-uint256-bytes-[`++onTransferReceived++`]] + +[.contract] +[[IERC1363Receiver]] +=== `++IERC1363Receiver++` link:https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v5.0.0-rc.0/contracts/interfaces/IERC1363Receiver.sol[{github-icon},role=heading-link] + +[.hljs-theme-light.nopadding] +```solidity +import "@openzeppelin/contracts/interfaces/IERC1363Receiver.sol"; +``` + +Interface for any contract that wants to support {IERC1363-transferAndCall} +or {IERC1363-transferFromAndCall} from {ERC1363} token contracts. + +[.contract-index] +.Functions +-- +* {xref-IERC1363Receiver-onTransferReceived-address-address-uint256-bytes-}[`++onTransferReceived(operator, from, amount, data)++`] + +-- + +[.contract-item] +[[IERC1363Receiver-onTransferReceived-address-address-uint256-bytes-]] +==== `[.contract-item-name]#++onTransferReceived++#++(address operator, address from, uint256 amount, bytes data) → bytes4++` [.item-kind]#external# + +Any ERC1363 smart contract calls this function on the recipient +after a `transfer` or a `transferFrom`. This function MAY throw to revert and reject the +transfer. Return of other than the magic value MUST result in the +transaction being reverted. +Note: the token contract address is always the message sender. + +:onApprovalReceived: pass:normal[xref:#IERC1363Spender-onApprovalReceived-address-uint256-bytes-[`++onApprovalReceived++`]] + +[.contract] +[[IERC1363Spender]] +=== `++IERC1363Spender++` link:https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v5.0.0-rc.0/contracts/interfaces/IERC1363Spender.sol[{github-icon},role=heading-link] + +[.hljs-theme-light.nopadding] +```solidity +import "@openzeppelin/contracts/interfaces/IERC1363Spender.sol"; +``` + +Interface for any contract that wants to support {IERC1363-approveAndCall} +from {ERC1363} token contracts. + +[.contract-index] +.Functions +-- +* {xref-IERC1363Spender-onApprovalReceived-address-uint256-bytes-}[`++onApprovalReceived(owner, amount, data)++`] + +-- + +[.contract-item] +[[IERC1363Spender-onApprovalReceived-address-uint256-bytes-]] +==== `[.contract-item-name]#++onApprovalReceived++#++(address owner, uint256 amount, bytes data) → bytes4++` [.item-kind]#external# + +Any ERC1363 smart contract calls this function on the recipient +after an `approve`. This function MAY throw to revert and reject the +approval. Return of other than the magic value MUST result in the +transaction being reverted. +Note: the token contract address is always the message sender. + +:canImplementInterfaceForAddress: pass:normal[xref:#IERC1820Implementer-canImplementInterfaceForAddress-bytes32-address-[`++canImplementInterfaceForAddress++`]] + +[.contract] +[[IERC1820Implementer]] +=== `++IERC1820Implementer++` link:https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v5.0.0-rc.0/contracts/interfaces/IERC1820Implementer.sol[{github-icon},role=heading-link] + +[.hljs-theme-light.nopadding] +```solidity +import "@openzeppelin/contracts/interfaces/IERC1820Implementer.sol"; +``` + +Interface for an ERC1820 implementer, as defined in the +https://eips.ethereum.org/EIPS/eip-1820#interface-implementation-erc1820implementerinterface[EIP]. +Used by contracts that will be registered as implementers in the +{IERC1820Registry}. + +[.contract-index] +.Functions +-- +* {xref-IERC1820Implementer-canImplementInterfaceForAddress-bytes32-address-}[`++canImplementInterfaceForAddress(interfaceHash, account)++`] + +-- + +[.contract-item] +[[IERC1820Implementer-canImplementInterfaceForAddress-bytes32-address-]] +==== `[.contract-item-name]#++canImplementInterfaceForAddress++#++(bytes32 interfaceHash, address account) → bytes32++` [.item-kind]#external# + +Returns a special value (`ERC1820_ACCEPT_MAGIC`) if this contract +implements `interfaceHash` for `account`. + +See {IERC1820Registry-setInterfaceImplementer}. + +:InterfaceImplementerSet: pass:normal[xref:#IERC1820Registry-InterfaceImplementerSet-address-bytes32-address-[`++InterfaceImplementerSet++`]] +:ManagerChanged: pass:normal[xref:#IERC1820Registry-ManagerChanged-address-address-[`++ManagerChanged++`]] +:setManager: pass:normal[xref:#IERC1820Registry-setManager-address-address-[`++setManager++`]] +:getManager: pass:normal[xref:#IERC1820Registry-getManager-address-[`++getManager++`]] +:setInterfaceImplementer: pass:normal[xref:#IERC1820Registry-setInterfaceImplementer-address-bytes32-address-[`++setInterfaceImplementer++`]] +:getInterfaceImplementer: pass:normal[xref:#IERC1820Registry-getInterfaceImplementer-address-bytes32-[`++getInterfaceImplementer++`]] +:interfaceHash: pass:normal[xref:#IERC1820Registry-interfaceHash-string-[`++interfaceHash++`]] +:updateERC165Cache: pass:normal[xref:#IERC1820Registry-updateERC165Cache-address-bytes4-[`++updateERC165Cache++`]] +:implementsERC165Interface: pass:normal[xref:#IERC1820Registry-implementsERC165Interface-address-bytes4-[`++implementsERC165Interface++`]] +:implementsERC165InterfaceNoCache: pass:normal[xref:#IERC1820Registry-implementsERC165InterfaceNoCache-address-bytes4-[`++implementsERC165InterfaceNoCache++`]] + +[.contract] +[[IERC1820Registry]] +=== `++IERC1820Registry++` link:https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v5.0.0-rc.0/contracts/interfaces/IERC1820Registry.sol[{github-icon},role=heading-link] + +[.hljs-theme-light.nopadding] +```solidity +import "@openzeppelin/contracts/interfaces/IERC1820Registry.sol"; +``` + +Interface of the global ERC1820 Registry, as defined in the +https://eips.ethereum.org/EIPS/eip-1820[EIP]. Accounts may register +implementers for interfaces in this registry, as well as query support. + +Implementers may be shared by multiple accounts, and can also implement more +than a single interface for each account. Contracts can implement interfaces +for themselves, but externally-owned accounts (EOA) must delegate this to a +contract. + +{IERC165} interfaces can also be queried via the registry. + +For an in-depth explanation and source code analysis, see the EIP text. + +[.contract-index] +.Functions +-- +* {xref-IERC1820Registry-setManager-address-address-}[`++setManager(account, newManager)++`] +* {xref-IERC1820Registry-getManager-address-}[`++getManager(account)++`] +* {xref-IERC1820Registry-setInterfaceImplementer-address-bytes32-address-}[`++setInterfaceImplementer(account, _interfaceHash, implementer)++`] +* {xref-IERC1820Registry-getInterfaceImplementer-address-bytes32-}[`++getInterfaceImplementer(account, _interfaceHash)++`] +* {xref-IERC1820Registry-interfaceHash-string-}[`++interfaceHash(interfaceName)++`] +* {xref-IERC1820Registry-updateERC165Cache-address-bytes4-}[`++updateERC165Cache(account, interfaceId)++`] +* {xref-IERC1820Registry-implementsERC165Interface-address-bytes4-}[`++implementsERC165Interface(account, interfaceId)++`] +* {xref-IERC1820Registry-implementsERC165InterfaceNoCache-address-bytes4-}[`++implementsERC165InterfaceNoCache(account, interfaceId)++`] + +-- + +[.contract-index] +.Events +-- +* {xref-IERC1820Registry-InterfaceImplementerSet-address-bytes32-address-}[`++InterfaceImplementerSet(account, interfaceHash, implementer)++`] +* {xref-IERC1820Registry-ManagerChanged-address-address-}[`++ManagerChanged(account, newManager)++`] + +-- + +[.contract-item] +[[IERC1820Registry-setManager-address-address-]] +==== `[.contract-item-name]#++setManager++#++(address account, address newManager)++` [.item-kind]#external# + +Sets `newManager` as the manager for `account`. A manager of an +account is able to set interface implementers for it. + +By default, each account is its own manager. Passing a value of `0x0` in +`newManager` will reset the manager to this initial state. + +Emits a {ManagerChanged} event. + +Requirements: + +- the caller must be the current manager for `account`. + +[.contract-item] +[[IERC1820Registry-getManager-address-]] +==== `[.contract-item-name]#++getManager++#++(address account) → address++` [.item-kind]#external# + +Returns the manager for `account`. + +See {setManager}. + +[.contract-item] +[[IERC1820Registry-setInterfaceImplementer-address-bytes32-address-]] +==== `[.contract-item-name]#++setInterfaceImplementer++#++(address account, bytes32 _interfaceHash, address implementer)++` [.item-kind]#external# + +Sets the `implementer` contract as ``account``'s implementer for +`interfaceHash`. + +`account` being the zero address is an alias for the caller's address. +The zero address can also be used in `implementer` to remove an old one. + +See {interfaceHash} to learn how these are created. + +Emits an {InterfaceImplementerSet} event. + +Requirements: + +- the caller must be the current manager for `account`. +- `interfaceHash` must not be an {IERC165} interface id (i.e. it must not +end in 28 zeroes). +- `implementer` must implement {IERC1820Implementer} and return true when +queried for support, unless `implementer` is the caller. See +{IERC1820Implementer-canImplementInterfaceForAddress}. + +[.contract-item] +[[IERC1820Registry-getInterfaceImplementer-address-bytes32-]] +==== `[.contract-item-name]#++getInterfaceImplementer++#++(address account, bytes32 _interfaceHash) → address++` [.item-kind]#external# + +Returns the implementer of `interfaceHash` for `account`. If no such +implementer is registered, returns the zero address. + +If `interfaceHash` is an {IERC165} interface id (i.e. it ends with 28 +zeroes), `account` will be queried for support of it. + +`account` being the zero address is an alias for the caller's address. + +[.contract-item] +[[IERC1820Registry-interfaceHash-string-]] +==== `[.contract-item-name]#++interfaceHash++#++(string interfaceName) → bytes32++` [.item-kind]#external# + +Returns the interface hash for an `interfaceName`, as defined in the +corresponding +https://eips.ethereum.org/EIPS/eip-1820#interface-name[section of the EIP]. + +[.contract-item] +[[IERC1820Registry-updateERC165Cache-address-bytes4-]] +==== `[.contract-item-name]#++updateERC165Cache++#++(address account, bytes4 interfaceId)++` [.item-kind]#external# + +[.contract-item] +[[IERC1820Registry-implementsERC165Interface-address-bytes4-]] +==== `[.contract-item-name]#++implementsERC165Interface++#++(address account, bytes4 interfaceId) → bool++` [.item-kind]#external# + +[.contract-item] +[[IERC1820Registry-implementsERC165InterfaceNoCache-address-bytes4-]] +==== `[.contract-item-name]#++implementsERC165InterfaceNoCache++#++(address account, bytes4 interfaceId) → bool++` [.item-kind]#external# + +[.contract-item] +[[IERC1820Registry-InterfaceImplementerSet-address-bytes32-address-]] +==== `[.contract-item-name]#++InterfaceImplementerSet++#++(address indexed account, bytes32 indexed interfaceHash, address indexed implementer)++` [.item-kind]#event# + +[.contract-item] +[[IERC1820Registry-ManagerChanged-address-address-]] +==== `[.contract-item-name]#++ManagerChanged++#++(address indexed account, address indexed newManager)++` [.item-kind]#event# + +:proxiableUUID: pass:normal[xref:#IERC1822Proxiable-proxiableUUID--[`++proxiableUUID++`]] + +[.contract] +[[IERC1822Proxiable]] +=== `++IERC1822Proxiable++` link:https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v5.0.0-rc.0/contracts/interfaces/draft-IERC1822.sol[{github-icon},role=heading-link] + +[.hljs-theme-light.nopadding] +```solidity +import "@openzeppelin/contracts/interfaces/draft-IERC1822.sol"; +``` + +ERC1822: Universal Upgradeable Proxy Standard (UUPS) documents a method for upgradeability through a simplified +proxy whose upgrades are fully controlled by the current implementation. + +[.contract-index] +.Functions +-- +* {xref-IERC1822Proxiable-proxiableUUID--}[`++proxiableUUID()++`] + +-- + +[.contract-item] +[[IERC1822Proxiable-proxiableUUID--]] +==== `[.contract-item-name]#++proxiableUUID++#++() → bytes32++` [.item-kind]#external# + +Returns the storage slot that the proxiable contract assumes is being used to store the implementation +address. + +IMPORTANT: A proxy pointing at a proxiable contract should not be considered proxiable itself, because this risks +bricking a proxy that upgrades to it, by delegating to itself until out of gas. Thus it is critical that this +function revert if invoked through a proxy. + +[.contract] +[[IERC2612]] +=== `++IERC2612++` link:https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v5.0.0-rc.0/contracts/interfaces/IERC2612.sol[{github-icon},role=heading-link] + +[.hljs-theme-light.nopadding] +```solidity +import "@openzeppelin/contracts/interfaces/IERC2612.sol"; +``` + +[.contract-index] +.Functions +-- + +[.contract-subindex-inherited] +.IERC20Permit +* {xref-IERC20Permit-permit-address-address-uint256-uint256-uint8-bytes32-bytes32-}[`++permit(owner, spender, value, deadline, v, r, s)++`] +* {xref-IERC20Permit-nonces-address-}[`++nonces(owner)++`] +* {xref-IERC20Permit-DOMAIN_SEPARATOR--}[`++DOMAIN_SEPARATOR()++`] + +-- + +:royaltyInfo: pass:normal[xref:#IERC2981-royaltyInfo-uint256-uint256-[`++royaltyInfo++`]] + +[.contract] +[[IERC2981]] +=== `++IERC2981++` link:https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v5.0.0-rc.0/contracts/interfaces/IERC2981.sol[{github-icon},role=heading-link] + +[.hljs-theme-light.nopadding] +```solidity +import "@openzeppelin/contracts/interfaces/IERC2981.sol"; +``` + +Interface for the NFT Royalty Standard. + +A standardized way to retrieve royalty payment information for non-fungible tokens (NFTs) to enable universal +support for royalty payments across all NFT marketplaces and ecosystem participants. + +[.contract-index] +.Functions +-- +* {xref-IERC2981-royaltyInfo-uint256-uint256-}[`++royaltyInfo(tokenId, salePrice)++`] + +[.contract-subindex-inherited] +.IERC165 +* {xref-IERC165-supportsInterface-bytes4-}[`++supportsInterface(interfaceId)++`] + +-- + +[.contract-item] +[[IERC2981-royaltyInfo-uint256-uint256-]] +==== `[.contract-item-name]#++royaltyInfo++#++(uint256 tokenId, uint256 salePrice) → address receiver, uint256 royaltyAmount++` [.item-kind]#external# + +Returns how much royalty is owed and to whom, based on a sale price that may be denominated in any unit of +exchange. The royalty amount is denominated and should be paid in that same unit of exchange. + +:maxFlashLoan: pass:normal[xref:#IERC3156FlashLender-maxFlashLoan-address-[`++maxFlashLoan++`]] +:flashFee: pass:normal[xref:#IERC3156FlashLender-flashFee-address-uint256-[`++flashFee++`]] +:flashLoan: pass:normal[xref:#IERC3156FlashLender-flashLoan-contract-IERC3156FlashBorrower-address-uint256-bytes-[`++flashLoan++`]] + +[.contract] +[[IERC3156FlashLender]] +=== `++IERC3156FlashLender++` link:https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v5.0.0-rc.0/contracts/interfaces/IERC3156FlashLender.sol[{github-icon},role=heading-link] + +[.hljs-theme-light.nopadding] +```solidity +import "@openzeppelin/contracts/interfaces/IERC3156FlashLender.sol"; +``` + +Interface of the ERC3156 FlashLender, as defined in +https://eips.ethereum.org/EIPS/eip-3156[ERC-3156]. + +[.contract-index] +.Functions +-- +* {xref-IERC3156FlashLender-maxFlashLoan-address-}[`++maxFlashLoan(token)++`] +* {xref-IERC3156FlashLender-flashFee-address-uint256-}[`++flashFee(token, amount)++`] +* {xref-IERC3156FlashLender-flashLoan-contract-IERC3156FlashBorrower-address-uint256-bytes-}[`++flashLoan(receiver, token, amount, data)++`] + +-- + +[.contract-item] +[[IERC3156FlashLender-maxFlashLoan-address-]] +==== `[.contract-item-name]#++maxFlashLoan++#++(address token) → uint256++` [.item-kind]#external# + +The amount of currency available to be lended. + +[.contract-item] +[[IERC3156FlashLender-flashFee-address-uint256-]] +==== `[.contract-item-name]#++flashFee++#++(address token, uint256 amount) → uint256++` [.item-kind]#external# + +The fee to be charged for a given loan. + +[.contract-item] +[[IERC3156FlashLender-flashLoan-contract-IERC3156FlashBorrower-address-uint256-bytes-]] +==== `[.contract-item-name]#++flashLoan++#++(contract IERC3156FlashBorrower receiver, address token, uint256 amount, bytes data) → bool++` [.item-kind]#external# + +Initiate a flash loan. + +:onFlashLoan: pass:normal[xref:#IERC3156FlashBorrower-onFlashLoan-address-address-uint256-uint256-bytes-[`++onFlashLoan++`]] + +[.contract] +[[IERC3156FlashBorrower]] +=== `++IERC3156FlashBorrower++` link:https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v5.0.0-rc.0/contracts/interfaces/IERC3156FlashBorrower.sol[{github-icon},role=heading-link] + +[.hljs-theme-light.nopadding] +```solidity +import "@openzeppelin/contracts/interfaces/IERC3156FlashBorrower.sol"; +``` + +Interface of the ERC3156 FlashBorrower, as defined in +https://eips.ethereum.org/EIPS/eip-3156[ERC-3156]. + +[.contract-index] +.Functions +-- +* {xref-IERC3156FlashBorrower-onFlashLoan-address-address-uint256-uint256-bytes-}[`++onFlashLoan(initiator, token, amount, fee, data)++`] + +-- + +[.contract-item] +[[IERC3156FlashBorrower-onFlashLoan-address-address-uint256-uint256-bytes-]] +==== `[.contract-item-name]#++onFlashLoan++#++(address initiator, address token, uint256 amount, uint256 fee, bytes data) → bytes32++` [.item-kind]#external# + +Receive a flash loan. + +:Deposit: pass:normal[xref:#IERC4626-Deposit-address-address-uint256-uint256-[`++Deposit++`]] +:Withdraw: pass:normal[xref:#IERC4626-Withdraw-address-address-address-uint256-uint256-[`++Withdraw++`]] +:asset: pass:normal[xref:#IERC4626-asset--[`++asset++`]] +:totalAssets: pass:normal[xref:#IERC4626-totalAssets--[`++totalAssets++`]] +:convertToShares: pass:normal[xref:#IERC4626-convertToShares-uint256-[`++convertToShares++`]] +:convertToAssets: pass:normal[xref:#IERC4626-convertToAssets-uint256-[`++convertToAssets++`]] +:maxDeposit: pass:normal[xref:#IERC4626-maxDeposit-address-[`++maxDeposit++`]] +:previewDeposit: pass:normal[xref:#IERC4626-previewDeposit-uint256-[`++previewDeposit++`]] +:deposit: pass:normal[xref:#IERC4626-deposit-uint256-address-[`++deposit++`]] +:maxMint: pass:normal[xref:#IERC4626-maxMint-address-[`++maxMint++`]] +:previewMint: pass:normal[xref:#IERC4626-previewMint-uint256-[`++previewMint++`]] +:mint: pass:normal[xref:#IERC4626-mint-uint256-address-[`++mint++`]] +:maxWithdraw: pass:normal[xref:#IERC4626-maxWithdraw-address-[`++maxWithdraw++`]] +:previewWithdraw: pass:normal[xref:#IERC4626-previewWithdraw-uint256-[`++previewWithdraw++`]] +:withdraw: pass:normal[xref:#IERC4626-withdraw-uint256-address-address-[`++withdraw++`]] +:maxRedeem: pass:normal[xref:#IERC4626-maxRedeem-address-[`++maxRedeem++`]] +:previewRedeem: pass:normal[xref:#IERC4626-previewRedeem-uint256-[`++previewRedeem++`]] +:redeem: pass:normal[xref:#IERC4626-redeem-uint256-address-address-[`++redeem++`]] + +[.contract] +[[IERC4626]] +=== `++IERC4626++` link:https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v5.0.0-rc.0/contracts/interfaces/IERC4626.sol[{github-icon},role=heading-link] + +[.hljs-theme-light.nopadding] +```solidity +import "@openzeppelin/contracts/interfaces/IERC4626.sol"; +``` + +Interface of the ERC4626 "Tokenized Vault Standard", as defined in +https://eips.ethereum.org/EIPS/eip-4626[ERC-4626]. + +[.contract-index] +.Functions +-- +* {xref-IERC4626-asset--}[`++asset()++`] +* {xref-IERC4626-totalAssets--}[`++totalAssets()++`] +* {xref-IERC4626-convertToShares-uint256-}[`++convertToShares(assets)++`] +* {xref-IERC4626-convertToAssets-uint256-}[`++convertToAssets(shares)++`] +* {xref-IERC4626-maxDeposit-address-}[`++maxDeposit(receiver)++`] +* {xref-IERC4626-previewDeposit-uint256-}[`++previewDeposit(assets)++`] +* {xref-IERC4626-deposit-uint256-address-}[`++deposit(assets, receiver)++`] +* {xref-IERC4626-maxMint-address-}[`++maxMint(receiver)++`] +* {xref-IERC4626-previewMint-uint256-}[`++previewMint(shares)++`] +* {xref-IERC4626-mint-uint256-address-}[`++mint(shares, receiver)++`] +* {xref-IERC4626-maxWithdraw-address-}[`++maxWithdraw(owner)++`] +* {xref-IERC4626-previewWithdraw-uint256-}[`++previewWithdraw(assets)++`] +* {xref-IERC4626-withdraw-uint256-address-address-}[`++withdraw(assets, receiver, owner)++`] +* {xref-IERC4626-maxRedeem-address-}[`++maxRedeem(owner)++`] +* {xref-IERC4626-previewRedeem-uint256-}[`++previewRedeem(shares)++`] +* {xref-IERC4626-redeem-uint256-address-address-}[`++redeem(shares, receiver, owner)++`] + +[.contract-subindex-inherited] +.IERC20Metadata +* {xref-IERC20Metadata-name--}[`++name()++`] +* {xref-IERC20Metadata-symbol--}[`++symbol()++`] +* {xref-IERC20Metadata-decimals--}[`++decimals()++`] + +[.contract-subindex-inherited] +.IERC20 +* {xref-IERC20-totalSupply--}[`++totalSupply()++`] +* {xref-IERC20-balanceOf-address-}[`++balanceOf(account)++`] +* {xref-IERC20-transfer-address-uint256-}[`++transfer(to, value)++`] +* {xref-IERC20-allowance-address-address-}[`++allowance(owner, spender)++`] +* {xref-IERC20-approve-address-uint256-}[`++approve(spender, value)++`] +* {xref-IERC20-transferFrom-address-address-uint256-}[`++transferFrom(from, to, value)++`] + +-- + +[.contract-index] +.Events +-- +* {xref-IERC4626-Deposit-address-address-uint256-uint256-}[`++Deposit(sender, owner, assets, shares)++`] +* {xref-IERC4626-Withdraw-address-address-address-uint256-uint256-}[`++Withdraw(sender, receiver, owner, assets, shares)++`] + +[.contract-subindex-inherited] +.IERC20Metadata + +[.contract-subindex-inherited] +.IERC20 +* {xref-IERC20-Transfer-address-address-uint256-}[`++Transfer(from, to, value)++`] +* {xref-IERC20-Approval-address-address-uint256-}[`++Approval(owner, spender, value)++`] + +-- + +[.contract-item] +[[IERC4626-asset--]] +==== `[.contract-item-name]#++asset++#++() → address assetTokenAddress++` [.item-kind]#external# + +Returns the address of the underlying token used for the Vault for accounting, depositing, and withdrawing. + +- MUST be an ERC-20 token contract. +- MUST NOT revert. + +[.contract-item] +[[IERC4626-totalAssets--]] +==== `[.contract-item-name]#++totalAssets++#++() → uint256 totalManagedAssets++` [.item-kind]#external# + +Returns the total amount of the underlying asset that is “managed” by Vault. + +- SHOULD include any compounding that occurs from yield. +- MUST be inclusive of any fees that are charged against assets in the Vault. +- MUST NOT revert. + +[.contract-item] +[[IERC4626-convertToShares-uint256-]] +==== `[.contract-item-name]#++convertToShares++#++(uint256 assets) → uint256 shares++` [.item-kind]#external# + +Returns the amount of shares that the Vault would exchange for the amount of assets provided, in an ideal +scenario where all the conditions are met. + +- MUST NOT be inclusive of any fees that are charged against assets in the Vault. +- MUST NOT show any variations depending on the caller. +- MUST NOT reflect slippage or other on-chain conditions, when performing the actual exchange. +- MUST NOT revert. + +NOTE: This calculation MAY NOT reflect the “per-user” price-per-share, and instead should reflect the +“average-user’s” price-per-share, meaning what the average user should expect to see when exchanging to and +from. + +[.contract-item] +[[IERC4626-convertToAssets-uint256-]] +==== `[.contract-item-name]#++convertToAssets++#++(uint256 shares) → uint256 assets++` [.item-kind]#external# + +Returns the amount of assets that the Vault would exchange for the amount of shares provided, in an ideal +scenario where all the conditions are met. + +- MUST NOT be inclusive of any fees that are charged against assets in the Vault. +- MUST NOT show any variations depending on the caller. +- MUST NOT reflect slippage or other on-chain conditions, when performing the actual exchange. +- MUST NOT revert. + +NOTE: This calculation MAY NOT reflect the “per-user” price-per-share, and instead should reflect the +“average-user’s” price-per-share, meaning what the average user should expect to see when exchanging to and +from. + +[.contract-item] +[[IERC4626-maxDeposit-address-]] +==== `[.contract-item-name]#++maxDeposit++#++(address receiver) → uint256 maxAssets++` [.item-kind]#external# + +Returns the maximum amount of the underlying asset that can be deposited into the Vault for the receiver, +through a deposit call. + +- MUST return a limited value if receiver is subject to some deposit limit. +- MUST return 2 ** 256 - 1 if there is no limit on the maximum amount of assets that may be deposited. +- MUST NOT revert. + +[.contract-item] +[[IERC4626-previewDeposit-uint256-]] +==== `[.contract-item-name]#++previewDeposit++#++(uint256 assets) → uint256 shares++` [.item-kind]#external# + +Allows an on-chain or off-chain user to simulate the effects of their deposit at the current block, given +current on-chain conditions. + +- MUST return as close to and no more than the exact amount of Vault shares that would be minted in a deposit + call in the same transaction. I.e. deposit should return the same or more shares as previewDeposit if called + in the same transaction. +- MUST NOT account for deposit limits like those returned from maxDeposit and should always act as though the + deposit would be accepted, regardless if the user has enough tokens approved, etc. +- MUST be inclusive of deposit fees. Integrators should be aware of the existence of deposit fees. +- MUST NOT revert. + +NOTE: any unfavorable discrepancy between convertToShares and previewDeposit SHOULD be considered slippage in +share price or some other type of condition, meaning the depositor will lose assets by depositing. + +[.contract-item] +[[IERC4626-deposit-uint256-address-]] +==== `[.contract-item-name]#++deposit++#++(uint256 assets, address receiver) → uint256 shares++` [.item-kind]#external# + +Mints shares Vault shares to receiver by depositing exactly amount of underlying tokens. + +- MUST emit the Deposit event. +- MAY support an additional flow in which the underlying tokens are owned by the Vault contract before the + deposit execution, and are accounted for during deposit. +- MUST revert if all of assets cannot be deposited (due to deposit limit being reached, slippage, the user not + approving enough underlying tokens to the Vault contract, etc). + +NOTE: most implementations will require pre-approval of the Vault with the Vault’s underlying asset token. + +[.contract-item] +[[IERC4626-maxMint-address-]] +==== `[.contract-item-name]#++maxMint++#++(address receiver) → uint256 maxShares++` [.item-kind]#external# + +Returns the maximum amount of the Vault shares that can be minted for the receiver, through a mint call. +- MUST return a limited value if receiver is subject to some mint limit. +- MUST return 2 ** 256 - 1 if there is no limit on the maximum amount of shares that may be minted. +- MUST NOT revert. + +[.contract-item] +[[IERC4626-previewMint-uint256-]] +==== `[.contract-item-name]#++previewMint++#++(uint256 shares) → uint256 assets++` [.item-kind]#external# + +Allows an on-chain or off-chain user to simulate the effects of their mint at the current block, given +current on-chain conditions. + +- MUST return as close to and no fewer than the exact amount of assets that would be deposited in a mint call + in the same transaction. I.e. mint should return the same or fewer assets as previewMint if called in the + same transaction. +- MUST NOT account for mint limits like those returned from maxMint and should always act as though the mint + would be accepted, regardless if the user has enough tokens approved, etc. +- MUST be inclusive of deposit fees. Integrators should be aware of the existence of deposit fees. +- MUST NOT revert. + +NOTE: any unfavorable discrepancy between convertToAssets and previewMint SHOULD be considered slippage in +share price or some other type of condition, meaning the depositor will lose assets by minting. + +[.contract-item] +[[IERC4626-mint-uint256-address-]] +==== `[.contract-item-name]#++mint++#++(uint256 shares, address receiver) → uint256 assets++` [.item-kind]#external# + +Mints exactly shares Vault shares to receiver by depositing amount of underlying tokens. + +- MUST emit the Deposit event. +- MAY support an additional flow in which the underlying tokens are owned by the Vault contract before the mint + execution, and are accounted for during mint. +- MUST revert if all of shares cannot be minted (due to deposit limit being reached, slippage, the user not + approving enough underlying tokens to the Vault contract, etc). + +NOTE: most implementations will require pre-approval of the Vault with the Vault’s underlying asset token. + +[.contract-item] +[[IERC4626-maxWithdraw-address-]] +==== `[.contract-item-name]#++maxWithdraw++#++(address owner) → uint256 maxAssets++` [.item-kind]#external# + +Returns the maximum amount of the underlying asset that can be withdrawn from the owner balance in the +Vault, through a withdraw call. + +- MUST return a limited value if owner is subject to some withdrawal limit or timelock. +- MUST NOT revert. + +[.contract-item] +[[IERC4626-previewWithdraw-uint256-]] +==== `[.contract-item-name]#++previewWithdraw++#++(uint256 assets) → uint256 shares++` [.item-kind]#external# + +Allows an on-chain or off-chain user to simulate the effects of their withdrawal at the current block, +given current on-chain conditions. + +- MUST return as close to and no fewer than the exact amount of Vault shares that would be burned in a withdraw + call in the same transaction. I.e. withdraw should return the same or fewer shares as previewWithdraw if + called + in the same transaction. +- MUST NOT account for withdrawal limits like those returned from maxWithdraw and should always act as though + the withdrawal would be accepted, regardless if the user has enough shares, etc. +- MUST be inclusive of withdrawal fees. Integrators should be aware of the existence of withdrawal fees. +- MUST NOT revert. + +NOTE: any unfavorable discrepancy between convertToShares and previewWithdraw SHOULD be considered slippage in +share price or some other type of condition, meaning the depositor will lose assets by depositing. + +[.contract-item] +[[IERC4626-withdraw-uint256-address-address-]] +==== `[.contract-item-name]#++withdraw++#++(uint256 assets, address receiver, address owner) → uint256 shares++` [.item-kind]#external# + +Burns shares from owner and sends exactly assets of underlying tokens to receiver. + +- MUST emit the Withdraw event. +- MAY support an additional flow in which the underlying tokens are owned by the Vault contract before the + withdraw execution, and are accounted for during withdraw. +- MUST revert if all of assets cannot be withdrawn (due to withdrawal limit being reached, slippage, the owner + not having enough shares, etc). + +Note that some implementations will require pre-requesting to the Vault before a withdrawal may be performed. +Those methods should be performed separately. + +[.contract-item] +[[IERC4626-maxRedeem-address-]] +==== `[.contract-item-name]#++maxRedeem++#++(address owner) → uint256 maxShares++` [.item-kind]#external# + +Returns the maximum amount of Vault shares that can be redeemed from the owner balance in the Vault, +through a redeem call. + +- MUST return a limited value if owner is subject to some withdrawal limit or timelock. +- MUST return balanceOf(owner) if owner is not subject to any withdrawal limit or timelock. +- MUST NOT revert. + +[.contract-item] +[[IERC4626-previewRedeem-uint256-]] +==== `[.contract-item-name]#++previewRedeem++#++(uint256 shares) → uint256 assets++` [.item-kind]#external# + +Allows an on-chain or off-chain user to simulate the effects of their redeemption at the current block, +given current on-chain conditions. + +- MUST return as close to and no more than the exact amount of assets that would be withdrawn in a redeem call + in the same transaction. I.e. redeem should return the same or more assets as previewRedeem if called in the + same transaction. +- MUST NOT account for redemption limits like those returned from maxRedeem and should always act as though the + redemption would be accepted, regardless if the user has enough shares, etc. +- MUST be inclusive of withdrawal fees. Integrators should be aware of the existence of withdrawal fees. +- MUST NOT revert. + +NOTE: any unfavorable discrepancy between convertToAssets and previewRedeem SHOULD be considered slippage in +share price or some other type of condition, meaning the depositor will lose assets by redeeming. + +[.contract-item] +[[IERC4626-redeem-uint256-address-address-]] +==== `[.contract-item-name]#++redeem++#++(uint256 shares, address receiver, address owner) → uint256 assets++` [.item-kind]#external# + +Burns exactly shares from owner and sends assets of underlying tokens to receiver. + +- MUST emit the Withdraw event. +- MAY support an additional flow in which the underlying tokens are owned by the Vault contract before the + redeem execution, and are accounted for during redeem. +- MUST revert if all of shares cannot be redeemed (due to withdrawal limit being reached, slippage, the owner + not having enough shares, etc). + +NOTE: some implementations will require pre-requesting to the Vault before a withdrawal may be performed. +Those methods should be performed separately. + +[.contract-item] +[[IERC4626-Deposit-address-address-uint256-uint256-]] +==== `[.contract-item-name]#++Deposit++#++(address indexed sender, address indexed owner, uint256 assets, uint256 shares)++` [.item-kind]#event# + +[.contract-item] +[[IERC4626-Withdraw-address-address-address-uint256-uint256-]] +==== `[.contract-item-name]#++Withdraw++#++(address indexed sender, address indexed receiver, address indexed owner, uint256 assets, uint256 shares)++` [.item-kind]#event# + +:owner: pass:normal[xref:#IERC5313-owner--[`++owner++`]] + +[.contract] +[[IERC5313]] +=== `++IERC5313++` link:https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v5.0.0-rc.0/contracts/interfaces/IERC5313.sol[{github-icon},role=heading-link] + +[.hljs-theme-light.nopadding] +```solidity +import "@openzeppelin/contracts/interfaces/IERC5313.sol"; +``` + +Interface for the Light Contract Ownership Standard. + +A standardized minimal interface required to identify an account that controls a contract + +[.contract-index] +.Functions +-- +* {xref-IERC5313-owner--}[`++owner()++`] + +-- + +[.contract-item] +[[IERC5313-owner--]] +==== `[.contract-item-name]#++owner++#++() → address++` [.item-kind]#external# + +Gets the address of the owner. + +:EIP712DomainChanged: pass:normal[xref:#IERC5267-EIP712DomainChanged--[`++EIP712DomainChanged++`]] +:eip712Domain: pass:normal[xref:#IERC5267-eip712Domain--[`++eip712Domain++`]] + +[.contract] +[[IERC5267]] +=== `++IERC5267++` link:https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v5.0.0-rc.0/contracts/interfaces/IERC5267.sol[{github-icon},role=heading-link] + +[.hljs-theme-light.nopadding] +```solidity +import "@openzeppelin/contracts/interfaces/IERC5267.sol"; +``` + +[.contract-index] +.Functions +-- +* {xref-IERC5267-eip712Domain--}[`++eip712Domain()++`] + +-- + +[.contract-index] +.Events +-- +* {xref-IERC5267-EIP712DomainChanged--}[`++EIP712DomainChanged()++`] + +-- + +[.contract-item] +[[IERC5267-eip712Domain--]] +==== `[.contract-item-name]#++eip712Domain++#++() → bytes1 fields, string name, string version, uint256 chainId, address verifyingContract, bytes32 salt, uint256[] extensions++` [.item-kind]#external# + +returns the fields and values that describe the domain separator used by this contract for EIP-712 +signature. + +[.contract-item] +[[IERC5267-EIP712DomainChanged--]] +==== `[.contract-item-name]#++EIP712DomainChanged++#++()++` [.item-kind]#event# + +MAY be emitted to signal that the domain could have changed. + +[.contract] +[[IERC5805]] +=== `++IERC5805++` link:https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v5.0.0-rc.0/contracts/interfaces/IERC5805.sol[{github-icon},role=heading-link] + +[.hljs-theme-light.nopadding] +```solidity +import "@openzeppelin/contracts/interfaces/IERC5805.sol"; +``` + +[.contract-index] +.Functions +-- + +[.contract-subindex-inherited] +.IVotes +* {xref-IVotes-getVotes-address-}[`++getVotes(account)++`] +* {xref-IVotes-getPastVotes-address-uint256-}[`++getPastVotes(account, timepoint)++`] +* {xref-IVotes-getPastTotalSupply-uint256-}[`++getPastTotalSupply(timepoint)++`] +* {xref-IVotes-delegates-address-}[`++delegates(account)++`] +* {xref-IVotes-delegate-address-}[`++delegate(delegatee)++`] +* {xref-IVotes-delegateBySig-address-uint256-uint256-uint8-bytes32-bytes32-}[`++delegateBySig(delegatee, nonce, expiry, v, r, s)++`] + +[.contract-subindex-inherited] +.IERC6372 +* {xref-IERC6372-clock--}[`++clock()++`] +* {xref-IERC6372-CLOCK_MODE--}[`++CLOCK_MODE()++`] + +-- + +[.contract-index] +.Events +-- + +[.contract-subindex-inherited] +.IVotes +* {xref-IVotes-DelegateChanged-address-address-address-}[`++DelegateChanged(delegator, fromDelegate, toDelegate)++`] +* {xref-IVotes-DelegateVotesChanged-address-uint256-uint256-}[`++DelegateVotesChanged(delegate, previousVotes, newVotes)++`] + +[.contract-subindex-inherited] +.IERC6372 + +-- + +[.contract-index] +.Errors +-- + +[.contract-subindex-inherited] +.IVotes +* {xref-IVotes-VotesExpiredSignature-uint256-}[`++VotesExpiredSignature(expiry)++`] + +[.contract-subindex-inherited] +.IERC6372 + +-- + +:clock: pass:normal[xref:#IERC6372-clock--[`++clock++`]] +:CLOCK_MODE: pass:normal[xref:#IERC6372-CLOCK_MODE--[`++CLOCK_MODE++`]] + +[.contract] +[[IERC6372]] +=== `++IERC6372++` link:https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v5.0.0-rc.0/contracts/interfaces/IERC6372.sol[{github-icon},role=heading-link] + +[.hljs-theme-light.nopadding] +```solidity +import "@openzeppelin/contracts/interfaces/IERC6372.sol"; +``` + +[.contract-index] +.Functions +-- +* {xref-IERC6372-clock--}[`++clock()++`] +* {xref-IERC6372-CLOCK_MODE--}[`++CLOCK_MODE()++`] + +-- + +[.contract-item] +[[IERC6372-clock--]] +==== `[.contract-item-name]#++clock++#++() → uint48++` [.item-kind]#external# + +Clock used for flagging checkpoints. Can be overridden to implement timestamp based checkpoints (and voting). + +[.contract-item] +[[IERC6372-CLOCK_MODE--]] +==== `[.contract-item-name]#++CLOCK_MODE++#++() → string++` [.item-kind]#external# + +Description of the clock + diff --git a/docs/modules/api/pages/metatx.adoc b/docs/modules/api/pages/metatx.adoc new file mode 100644 index 000000000..eeaaf542d --- /dev/null +++ b/docs/modules/api/pages/metatx.adoc @@ -0,0 +1,359 @@ +:github-icon: pass:[] +:xref-ERC2771Context-constructor-address-: xref:metatx.adoc#ERC2771Context-constructor-address- +:xref-ERC2771Context-trustedForwarder--: xref:metatx.adoc#ERC2771Context-trustedForwarder-- +:xref-ERC2771Context-isTrustedForwarder-address-: xref:metatx.adoc#ERC2771Context-isTrustedForwarder-address- +:xref-ERC2771Context-_msgSender--: xref:metatx.adoc#ERC2771Context-_msgSender-- +:xref-ERC2771Context-_msgData--: xref:metatx.adoc#ERC2771Context-_msgData-- +:ERC2771Context: pass:normal[xref:metatx.adoc#ERC2771Context[`ERC2771Context`]] +:xref-ERC2771Forwarder-constructor-string-: xref:metatx.adoc#ERC2771Forwarder-constructor-string- +:xref-ERC2771Forwarder-verify-struct-ERC2771Forwarder-ForwardRequestData-: xref:metatx.adoc#ERC2771Forwarder-verify-struct-ERC2771Forwarder-ForwardRequestData- +:xref-ERC2771Forwarder-execute-struct-ERC2771Forwarder-ForwardRequestData-: xref:metatx.adoc#ERC2771Forwarder-execute-struct-ERC2771Forwarder-ForwardRequestData- +:xref-ERC2771Forwarder-executeBatch-struct-ERC2771Forwarder-ForwardRequestData---address-payable-: xref:metatx.adoc#ERC2771Forwarder-executeBatch-struct-ERC2771Forwarder-ForwardRequestData---address-payable- +:xref-ERC2771Forwarder-_validate-struct-ERC2771Forwarder-ForwardRequestData-: xref:metatx.adoc#ERC2771Forwarder-_validate-struct-ERC2771Forwarder-ForwardRequestData- +:xref-ERC2771Forwarder-_recoverForwardRequestSigner-struct-ERC2771Forwarder-ForwardRequestData-: xref:metatx.adoc#ERC2771Forwarder-_recoverForwardRequestSigner-struct-ERC2771Forwarder-ForwardRequestData- +:xref-ERC2771Forwarder-_execute-struct-ERC2771Forwarder-ForwardRequestData-bool-: xref:metatx.adoc#ERC2771Forwarder-_execute-struct-ERC2771Forwarder-ForwardRequestData-bool- +:xref-Nonces-nonces-address-: xref:utils.adoc#Nonces-nonces-address- +:xref-Nonces-_useNonce-address-: xref:utils.adoc#Nonces-_useNonce-address- +:xref-Nonces-_useCheckedNonce-address-uint256-: xref:utils.adoc#Nonces-_useCheckedNonce-address-uint256- +:xref-EIP712-_domainSeparatorV4--: xref:utils.adoc#EIP712-_domainSeparatorV4-- +:xref-EIP712-_hashTypedDataV4-bytes32-: xref:utils.adoc#EIP712-_hashTypedDataV4-bytes32- +:xref-EIP712-eip712Domain--: xref:utils.adoc#EIP712-eip712Domain-- +:xref-EIP712-_EIP712Name--: xref:utils.adoc#EIP712-_EIP712Name-- +:xref-EIP712-_EIP712Version--: xref:utils.adoc#EIP712-_EIP712Version-- +:xref-ERC2771Forwarder-ExecutedForwardRequest-address-uint256-bool-: xref:metatx.adoc#ERC2771Forwarder-ExecutedForwardRequest-address-uint256-bool- +:xref-IERC5267-EIP712DomainChanged--: xref:interfaces.adoc#IERC5267-EIP712DomainChanged-- +:xref-ERC2771Forwarder-ERC2771ForwarderInvalidSigner-address-address-: xref:metatx.adoc#ERC2771Forwarder-ERC2771ForwarderInvalidSigner-address-address- +:xref-ERC2771Forwarder-ERC2771ForwarderMismatchedValue-uint256-uint256-: xref:metatx.adoc#ERC2771Forwarder-ERC2771ForwarderMismatchedValue-uint256-uint256- +:xref-ERC2771Forwarder-ERC2771ForwarderExpiredRequest-uint48-: xref:metatx.adoc#ERC2771Forwarder-ERC2771ForwarderExpiredRequest-uint48- +:xref-ERC2771Forwarder-ERC2771UntrustfulTarget-address-address-: xref:metatx.adoc#ERC2771Forwarder-ERC2771UntrustfulTarget-address-address- +:xref-Nonces-InvalidAccountNonce-address-uint256-: xref:utils.adoc#Nonces-InvalidAccountNonce-address-uint256- +:EIP712-constructor: pass:normal[xref:utils.adoc#EIP712-constructor-string-string-[`EIP712.constructor`]] +:ECDSA-tryRecover: pass:normal[xref:utils.adoc#ECDSA-tryRecover-bytes32-uint8-bytes32-bytes32-[`ECDSA.tryRecover`]] += Meta Transactions + +[.readme-notice] +NOTE: This document is better viewed at https://docs.openzeppelin.com/contracts/api/metatx + +== Core + +:constructor: pass:normal[xref:#ERC2771Context-constructor-address-[`++constructor++`]] +:trustedForwarder: pass:normal[xref:#ERC2771Context-trustedForwarder--[`++trustedForwarder++`]] +:isTrustedForwarder: pass:normal[xref:#ERC2771Context-isTrustedForwarder-address-[`++isTrustedForwarder++`]] +:_msgSender: pass:normal[xref:#ERC2771Context-_msgSender--[`++_msgSender++`]] +:_msgData: pass:normal[xref:#ERC2771Context-_msgData--[`++_msgData++`]] + +[.contract] +[[ERC2771Context]] +=== `++ERC2771Context++` link:https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v5.0.0-rc.0/contracts/metatx/ERC2771Context.sol[{github-icon},role=heading-link] + +[.hljs-theme-light.nopadding] +```solidity +import "@openzeppelin/contracts/metatx/ERC2771Context.sol"; +``` + +Context variant with ERC2771 support. + +WARNING: Avoid using this pattern in contracts that rely in a specific calldata length as they'll +be affected by any forwarder whose `msg.data` is suffixed with the `from` address according to the ERC2771 +specification adding the address size in bytes (20) to the calldata size. An example of an unexpected +behavior could be an unintended fallback (or another function) invocation while trying to invoke the `receive` +function only accessible if `msg.data.length == 0`. + +[.contract-index] +.Functions +-- +* {xref-ERC2771Context-constructor-address-}[`++constructor(trustedForwarder_)++`] +* {xref-ERC2771Context-trustedForwarder--}[`++trustedForwarder()++`] +* {xref-ERC2771Context-isTrustedForwarder-address-}[`++isTrustedForwarder(forwarder)++`] +* {xref-ERC2771Context-_msgSender--}[`++_msgSender()++`] +* {xref-ERC2771Context-_msgData--}[`++_msgData()++`] + +-- + +[.contract-item] +[[ERC2771Context-constructor-address-]] +==== `[.contract-item-name]#++constructor++#++(address trustedForwarder_)++` [.item-kind]#internal# + +[.contract-item] +[[ERC2771Context-trustedForwarder--]] +==== `[.contract-item-name]#++trustedForwarder++#++() → address++` [.item-kind]#public# + +Returns the address of the trusted forwarder. + +[.contract-item] +[[ERC2771Context-isTrustedForwarder-address-]] +==== `[.contract-item-name]#++isTrustedForwarder++#++(address forwarder) → bool++` [.item-kind]#public# + +Indicates whether any particular address is the trusted forwarder. + +[.contract-item] +[[ERC2771Context-_msgSender--]] +==== `[.contract-item-name]#++_msgSender++#++() → address sender++` [.item-kind]#internal# + +Override for `msg.sender`. Defaults to the original `msg.sender` whenever +a call is not performed by the trusted forwarder or the calldata length is less than +20 bytes (an address length). + +[.contract-item] +[[ERC2771Context-_msgData--]] +==== `[.contract-item-name]#++_msgData++#++() → bytes++` [.item-kind]#internal# + +Override for `msg.data`. Defaults to the original `msg.data` whenever +a call is not performed by the trusted forwarder or the calldata length is less than +20 bytes (an address length). + +== Utils + +:ForwardRequestData: pass:normal[xref:#ERC2771Forwarder-ForwardRequestData[`++ForwardRequestData++`]] +:_FORWARD_REQUEST_TYPEHASH: pass:normal[xref:#ERC2771Forwarder-_FORWARD_REQUEST_TYPEHASH-bytes32[`++_FORWARD_REQUEST_TYPEHASH++`]] +:ExecutedForwardRequest: pass:normal[xref:#ERC2771Forwarder-ExecutedForwardRequest-address-uint256-bool-[`++ExecutedForwardRequest++`]] +:ERC2771ForwarderInvalidSigner: pass:normal[xref:#ERC2771Forwarder-ERC2771ForwarderInvalidSigner-address-address-[`++ERC2771ForwarderInvalidSigner++`]] +:ERC2771ForwarderMismatchedValue: pass:normal[xref:#ERC2771Forwarder-ERC2771ForwarderMismatchedValue-uint256-uint256-[`++ERC2771ForwarderMismatchedValue++`]] +:ERC2771ForwarderExpiredRequest: pass:normal[xref:#ERC2771Forwarder-ERC2771ForwarderExpiredRequest-uint48-[`++ERC2771ForwarderExpiredRequest++`]] +:ERC2771UntrustfulTarget: pass:normal[xref:#ERC2771Forwarder-ERC2771UntrustfulTarget-address-address-[`++ERC2771UntrustfulTarget++`]] +:constructor: pass:normal[xref:#ERC2771Forwarder-constructor-string-[`++constructor++`]] +:verify: pass:normal[xref:#ERC2771Forwarder-verify-struct-ERC2771Forwarder-ForwardRequestData-[`++verify++`]] +:execute: pass:normal[xref:#ERC2771Forwarder-execute-struct-ERC2771Forwarder-ForwardRequestData-[`++execute++`]] +:executeBatch: pass:normal[xref:#ERC2771Forwarder-executeBatch-struct-ERC2771Forwarder-ForwardRequestData---address-payable-[`++executeBatch++`]] +:_validate: pass:normal[xref:#ERC2771Forwarder-_validate-struct-ERC2771Forwarder-ForwardRequestData-[`++_validate++`]] +:_recoverForwardRequestSigner: pass:normal[xref:#ERC2771Forwarder-_recoverForwardRequestSigner-struct-ERC2771Forwarder-ForwardRequestData-[`++_recoverForwardRequestSigner++`]] +:_execute: pass:normal[xref:#ERC2771Forwarder-_execute-struct-ERC2771Forwarder-ForwardRequestData-bool-[`++_execute++`]] + +[.contract] +[[ERC2771Forwarder]] +=== `++ERC2771Forwarder++` link:https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v5.0.0-rc.0/contracts/metatx/ERC2771Forwarder.sol[{github-icon},role=heading-link] + +[.hljs-theme-light.nopadding] +```solidity +import "@openzeppelin/contracts/metatx/ERC2771Forwarder.sol"; +``` + +A forwarder compatible with ERC2771 contracts. See {ERC2771Context}. + +This forwarder operates on forward requests that include: + +* `from`: An address to operate on behalf of. It is required to be equal to the request signer. +* `to`: The address that should be called. +* `value`: The amount of native token to attach with the requested call. +* `gas`: The amount of gas limit that will be forwarded with the requested call. +* `nonce`: A unique transaction ordering identifier to avoid replayability and request invalidation. +* `deadline`: A timestamp after which the request is not executable anymore. +* `data`: Encoded `msg.data` to send with the requested call. + +Relayers are able to submit batches if they are processing a high volume of requests. With high +throughput, relayers may run into limitations of the chain such as limits on the number of +transactions in the mempool. In these cases the recommendation is to distribute the load among +multiple accounts. + +NOTE: Batching requests includes an optional refund for unused `msg.value` that is achieved by +performing a call with empty calldata. While this is within the bounds of ERC-2771 compliance, +if the refund receiver happens to consider the forwarder a trusted forwarder, it MUST properly +handle `msg.data.length == 0`. `ERC2771Context` in OpenZeppelin Contracts versions prior to 4.9.3 +do not handle this properly. + +==== Security Considerations + +If a relayer submits a forward request, it should be willing to pay up to 100% of the gas amount +specified in the request. This contract does not implement any kind of retribution for this gas, +and it is assumed that there is an out of band incentive for relayers to pay for execution on +behalf of signers. Often, the relayer is operated by a project that will consider it a user +acquisition cost. + +By offering to pay for gas, relayers are at risk of having that gas used by an attacker toward +some other purpose that is not aligned with the expected out of band incentives. If you operate a +relayer, consider whitelisting target contracts and function selectors. When relaying ERC-721 or +ERC-1155 transfers specifically, consider rejecting the use of the `data` field, since it can be +used to execute arbitrary code. + +[.contract-index] +.Functions +-- +* {xref-ERC2771Forwarder-constructor-string-}[`++constructor(name)++`] +* {xref-ERC2771Forwarder-verify-struct-ERC2771Forwarder-ForwardRequestData-}[`++verify(request)++`] +* {xref-ERC2771Forwarder-execute-struct-ERC2771Forwarder-ForwardRequestData-}[`++execute(request)++`] +* {xref-ERC2771Forwarder-executeBatch-struct-ERC2771Forwarder-ForwardRequestData---address-payable-}[`++executeBatch(requests, refundReceiver)++`] +* {xref-ERC2771Forwarder-_validate-struct-ERC2771Forwarder-ForwardRequestData-}[`++_validate(request)++`] +* {xref-ERC2771Forwarder-_recoverForwardRequestSigner-struct-ERC2771Forwarder-ForwardRequestData-}[`++_recoverForwardRequestSigner(request)++`] +* {xref-ERC2771Forwarder-_execute-struct-ERC2771Forwarder-ForwardRequestData-bool-}[`++_execute(request, requireValidRequest)++`] + +[.contract-subindex-inherited] +.Nonces +* {xref-Nonces-nonces-address-}[`++nonces(owner)++`] +* {xref-Nonces-_useNonce-address-}[`++_useNonce(owner)++`] +* {xref-Nonces-_useCheckedNonce-address-uint256-}[`++_useCheckedNonce(owner, nonce)++`] + +[.contract-subindex-inherited] +.EIP712 +* {xref-EIP712-_domainSeparatorV4--}[`++_domainSeparatorV4()++`] +* {xref-EIP712-_hashTypedDataV4-bytes32-}[`++_hashTypedDataV4(structHash)++`] +* {xref-EIP712-eip712Domain--}[`++eip712Domain()++`] +* {xref-EIP712-_EIP712Name--}[`++_EIP712Name()++`] +* {xref-EIP712-_EIP712Version--}[`++_EIP712Version()++`] + +[.contract-subindex-inherited] +.IERC5267 + +-- + +[.contract-index] +.Events +-- +* {xref-ERC2771Forwarder-ExecutedForwardRequest-address-uint256-bool-}[`++ExecutedForwardRequest(signer, nonce, success)++`] + +[.contract-subindex-inherited] +.Nonces + +[.contract-subindex-inherited] +.EIP712 + +[.contract-subindex-inherited] +.IERC5267 +* {xref-IERC5267-EIP712DomainChanged--}[`++EIP712DomainChanged()++`] + +-- + +[.contract-index] +.Errors +-- +* {xref-ERC2771Forwarder-ERC2771ForwarderInvalidSigner-address-address-}[`++ERC2771ForwarderInvalidSigner(signer, from)++`] +* {xref-ERC2771Forwarder-ERC2771ForwarderMismatchedValue-uint256-uint256-}[`++ERC2771ForwarderMismatchedValue(requestedValue, msgValue)++`] +* {xref-ERC2771Forwarder-ERC2771ForwarderExpiredRequest-uint48-}[`++ERC2771ForwarderExpiredRequest(deadline)++`] +* {xref-ERC2771Forwarder-ERC2771UntrustfulTarget-address-address-}[`++ERC2771UntrustfulTarget(target, forwarder)++`] + +[.contract-subindex-inherited] +.Nonces +* {xref-Nonces-InvalidAccountNonce-address-uint256-}[`++InvalidAccountNonce(account, currentNonce)++`] + +[.contract-subindex-inherited] +.EIP712 + +[.contract-subindex-inherited] +.IERC5267 + +-- + +[.contract-item] +[[ERC2771Forwarder-constructor-string-]] +==== `[.contract-item-name]#++constructor++#++(string name)++` [.item-kind]#public# + +See {EIP712-constructor}. + +[.contract-item] +[[ERC2771Forwarder-verify-struct-ERC2771Forwarder-ForwardRequestData-]] +==== `[.contract-item-name]#++verify++#++(struct ERC2771Forwarder.ForwardRequestData request) → bool++` [.item-kind]#public# + +Returns `true` if a request is valid for a provided `signature` at the current block timestamp. + +A transaction is considered valid when the target trusts this forwarder, the request hasn't expired +(deadline is not met), and the signer matches the `from` parameter of the signed request. + +NOTE: A request may return false here but it won't cause {executeBatch} to revert if a refund +receiver is provided. + +[.contract-item] +[[ERC2771Forwarder-execute-struct-ERC2771Forwarder-ForwardRequestData-]] +==== `[.contract-item-name]#++execute++#++(struct ERC2771Forwarder.ForwardRequestData request)++` [.item-kind]#public# + +Executes a `request` on behalf of `signature`'s signer using the ERC-2771 protocol. The gas +provided to the requested call may not be exactly the amount requested, but the call will not run +out of gas. Will revert if the request is invalid or the call reverts, in this case the nonce is not consumed. + +Requirements: + +- The request value should be equal to the provided `msg.value`. +- The request should be valid according to {verify}. + +[.contract-item] +[[ERC2771Forwarder-executeBatch-struct-ERC2771Forwarder-ForwardRequestData---address-payable-]] +==== `[.contract-item-name]#++executeBatch++#++(struct ERC2771Forwarder.ForwardRequestData[] requests, address payable refundReceiver)++` [.item-kind]#public# + +Batch version of {execute} with optional refunding and atomic execution. + +In case a batch contains at least one invalid request (see {verify}), the +request will be skipped and the `refundReceiver` parameter will receive back the +unused requested value at the end of the execution. This is done to prevent reverting +the entire batch when a request is invalid or has already been submitted. + +If the `refundReceiver` is the `address(0)`, this function will revert when at least +one of the requests was not valid instead of skipping it. This could be useful if +a batch is required to get executed atomically (at least at the top-level). For example, +refunding (and thus atomicity) can be opt-out if the relayer is using a service that avoids +including reverted transactions. + +Requirements: + +- The sum of the requests' values should be equal to the provided `msg.value`. +- All of the requests should be valid (see {verify}) when `refundReceiver` is the zero address. + +NOTE: Setting a zero `refundReceiver` guarantees an all-or-nothing requests execution only for +the first-level forwarded calls. In case a forwarded request calls to a contract with another +subcall, the second-level call may revert without the top-level call reverting. + +[.contract-item] +[[ERC2771Forwarder-_validate-struct-ERC2771Forwarder-ForwardRequestData-]] +==== `[.contract-item-name]#++_validate++#++(struct ERC2771Forwarder.ForwardRequestData request) → bool isTrustedForwarder, bool active, bool signerMatch, address signer++` [.item-kind]#internal# + +Validates if the provided request can be executed at current block timestamp with +the given `request.signature` on behalf of `request.signer`. + +[.contract-item] +[[ERC2771Forwarder-_recoverForwardRequestSigner-struct-ERC2771Forwarder-ForwardRequestData-]] +==== `[.contract-item-name]#++_recoverForwardRequestSigner++#++(struct ERC2771Forwarder.ForwardRequestData request) → bool, address++` [.item-kind]#internal# + +Returns a tuple with the recovered the signer of an EIP712 forward request message hash +and a boolean indicating if the signature is valid. + +NOTE: The signature is considered valid if {ECDSA-tryRecover} indicates no recover error for it. + +[.contract-item] +[[ERC2771Forwarder-_execute-struct-ERC2771Forwarder-ForwardRequestData-bool-]] +==== `[.contract-item-name]#++_execute++#++(struct ERC2771Forwarder.ForwardRequestData request, bool requireValidRequest) → bool success++` [.item-kind]#internal# + +Validates and executes a signed request returning the request call `success` value. + +Internal function without msg.value validation. + +Requirements: + +- The caller must have provided enough gas to forward with the call. +- The request must be valid (see {verify}) if the `requireValidRequest` is true. + +Emits an {ExecutedForwardRequest} event. + +IMPORTANT: Using this function doesn't check that all the `msg.value` was sent, potentially +leaving value stuck in the contract. + +[.contract-item] +[[ERC2771Forwarder-ExecutedForwardRequest-address-uint256-bool-]] +==== `[.contract-item-name]#++ExecutedForwardRequest++#++(address indexed signer, uint256 nonce, bool success)++` [.item-kind]#event# + +Emitted when a `ForwardRequest` is executed. + +NOTE: An unsuccessful forward request could be due to an invalid signature, an expired deadline, +or simply a revert in the requested call. The contract guarantees that the relayer is not able to force +the requested call to run out of gas. + +[.contract-item] +[[ERC2771Forwarder-ERC2771ForwarderInvalidSigner-address-address-]] +==== `[.contract-item-name]#++ERC2771ForwarderInvalidSigner++#++(address signer, address from)++` [.item-kind]#error# + +The request `from` doesn't match with the recovered `signer`. + +[.contract-item] +[[ERC2771Forwarder-ERC2771ForwarderMismatchedValue-uint256-uint256-]] +==== `[.contract-item-name]#++ERC2771ForwarderMismatchedValue++#++(uint256 requestedValue, uint256 msgValue)++` [.item-kind]#error# + +The `requestedValue` doesn't match with the available `msgValue`. + +[.contract-item] +[[ERC2771Forwarder-ERC2771ForwarderExpiredRequest-uint48-]] +==== `[.contract-item-name]#++ERC2771ForwarderExpiredRequest++#++(uint48 deadline)++` [.item-kind]#error# + +The request `deadline` has expired. + +[.contract-item] +[[ERC2771Forwarder-ERC2771UntrustfulTarget-address-address-]] +==== `[.contract-item-name]#++ERC2771UntrustfulTarget++#++(address target, address forwarder)++` [.item-kind]#error# + +The request target doesn't trust the `forwarder`. + diff --git a/docs/modules/api/pages/proxy.adoc b/docs/modules/api/pages/proxy.adoc new file mode 100644 index 000000000..775612ce7 --- /dev/null +++ b/docs/modules/api/pages/proxy.adoc @@ -0,0 +1,1251 @@ +:github-icon: pass:[] +:Proxy: pass:normal[xref:proxy.adoc#Proxy[`Proxy`]] +:ERC1967Utils: pass:normal[xref:proxy.adoc#ERC1967Utils[`ERC1967Utils`]] +:ERC1967Proxy: pass:normal[xref:proxy.adoc#ERC1967Proxy[`ERC1967Proxy`]] +:TransparentUpgradeableProxy: pass:normal[xref:proxy.adoc#TransparentUpgradeableProxy[`TransparentUpgradeableProxy`]] +:UUPSUpgradeable: pass:normal[xref:proxy.adoc#UUPSUpgradeable[`UUPSUpgradeable`]] +:BeaconProxy: pass:normal[xref:proxy.adoc#BeaconProxy[`BeaconProxy`]] +:UpgradeableBeacon: pass:normal[xref:proxy.adoc#UpgradeableBeacon[`UpgradeableBeacon`]] +:BeaconProxy: pass:normal[xref:proxy.adoc#BeaconProxy[`BeaconProxy`]] +:Clones: pass:normal[xref:proxy.adoc#Clones[`Clones`]] +:TransparentUpgradeableProxy: pass:normal[xref:proxy.adoc#TransparentUpgradeableProxy[`TransparentUpgradeableProxy`]] +:ERC1967Proxy: pass:normal[xref:proxy.adoc#ERC1967Proxy[`ERC1967Proxy`]] +:UUPSUpgradeable: pass:normal[xref:proxy.adoc#UUPSUpgradeable[`UUPSUpgradeable`]] +:xref-UUPSUpgradeable-_authorizeUpgrade-address-: xref:proxy.adoc#UUPSUpgradeable-_authorizeUpgrade-address- +:TransparentUpgradeableProxy: pass:normal[xref:proxy.adoc#TransparentUpgradeableProxy[`TransparentUpgradeableProxy`]] +:UUPSUpgradeable: pass:normal[xref:proxy.adoc#UUPSUpgradeable[`UUPSUpgradeable`]] +:xref-Proxy-_delegate-address-: xref:proxy.adoc#Proxy-_delegate-address- +:xref-Proxy-_implementation--: xref:proxy.adoc#Proxy-_implementation-- +:xref-Proxy-_fallback--: xref:proxy.adoc#Proxy-_fallback-- +:xref-Proxy-fallback--: xref:proxy.adoc#Proxy-fallback-- +:xref-ERC1967Proxy-constructor-address-bytes-: xref:proxy.adoc#ERC1967Proxy-constructor-address-bytes- +:xref-ERC1967Proxy-_implementation--: xref:proxy.adoc#ERC1967Proxy-_implementation-- +:xref-Proxy-_delegate-address-: xref:proxy.adoc#Proxy-_delegate-address- +:xref-Proxy-_fallback--: xref:proxy.adoc#Proxy-_fallback-- +:xref-Proxy-fallback--: xref:proxy.adoc#Proxy-fallback-- +:xref-ERC1967Utils-getImplementation--: xref:proxy.adoc#ERC1967Utils-getImplementation-- +:xref-ERC1967Utils-upgradeToAndCall-address-bytes-: xref:proxy.adoc#ERC1967Utils-upgradeToAndCall-address-bytes- +:xref-ERC1967Utils-getAdmin--: xref:proxy.adoc#ERC1967Utils-getAdmin-- +:xref-ERC1967Utils-changeAdmin-address-: xref:proxy.adoc#ERC1967Utils-changeAdmin-address- +:xref-ERC1967Utils-getBeacon--: xref:proxy.adoc#ERC1967Utils-getBeacon-- +:xref-ERC1967Utils-upgradeBeaconToAndCall-address-bytes-: xref:proxy.adoc#ERC1967Utils-upgradeBeaconToAndCall-address-bytes- +:xref-ERC1967Utils-Upgraded-address-: xref:proxy.adoc#ERC1967Utils-Upgraded-address- +:xref-ERC1967Utils-AdminChanged-address-address-: xref:proxy.adoc#ERC1967Utils-AdminChanged-address-address- +:xref-ERC1967Utils-BeaconUpgraded-address-: xref:proxy.adoc#ERC1967Utils-BeaconUpgraded-address- +:xref-ERC1967Utils-ERC1967InvalidImplementation-address-: xref:proxy.adoc#ERC1967Utils-ERC1967InvalidImplementation-address- +:xref-ERC1967Utils-ERC1967InvalidAdmin-address-: xref:proxy.adoc#ERC1967Utils-ERC1967InvalidAdmin-address- +:xref-ERC1967Utils-ERC1967InvalidBeacon-address-: xref:proxy.adoc#ERC1967Utils-ERC1967InvalidBeacon-address- +:xref-ERC1967Utils-ERC1967NonPayable--: xref:proxy.adoc#ERC1967Utils-ERC1967NonPayable-- +:IERC1967-Upgraded: pass:normal[xref:interfaces.adoc#IERC1967-Upgraded-address-[`IERC1967.Upgraded`]] +:IERC1967-AdminChanged: pass:normal[xref:interfaces.adoc#IERC1967-AdminChanged-address-address-[`IERC1967.AdminChanged`]] +:IERC1967-BeaconUpgraded: pass:normal[xref:interfaces.adoc#IERC1967-BeaconUpgraded-address-[`IERC1967.BeaconUpgraded`]] +:BeaconProxy: pass:normal[xref:proxy.adoc#BeaconProxy[`BeaconProxy`]] +:ProxyAdmin: pass:normal[xref:proxy.adoc#ProxyAdmin[`ProxyAdmin`]] +:ITransparentUpgradeableProxy-upgradeToAndCall: pass:normal[xref:proxy.adoc#ITransparentUpgradeableProxy-upgradeToAndCall-address-bytes-[`ITransparentUpgradeableProxy.upgradeToAndCall`]] +:ProxyAdmin: pass:normal[xref:proxy.adoc#ProxyAdmin[`ProxyAdmin`]] +:Context: pass:normal[xref:utils.adoc#Context[`Context`]] +:ProxyAdmin: pass:normal[xref:proxy.adoc#ProxyAdmin[`ProxyAdmin`]] +:ITransparentUpgradeableProxy: pass:normal[xref:proxy.adoc#ITransparentUpgradeableProxy[`ITransparentUpgradeableProxy`]] +:xref-TransparentUpgradeableProxy-constructor-address-address-bytes-: xref:proxy.adoc#TransparentUpgradeableProxy-constructor-address-address-bytes- +:xref-TransparentUpgradeableProxy-_proxyAdmin--: xref:proxy.adoc#TransparentUpgradeableProxy-_proxyAdmin-- +:xref-TransparentUpgradeableProxy-_fallback--: xref:proxy.adoc#TransparentUpgradeableProxy-_fallback-- +:xref-ERC1967Proxy-_implementation--: xref:proxy.adoc#ERC1967Proxy-_implementation-- +:xref-Proxy-_delegate-address-: xref:proxy.adoc#Proxy-_delegate-address- +:xref-Proxy-fallback--: xref:proxy.adoc#Proxy-fallback-- +:xref-TransparentUpgradeableProxy-ProxyDeniedAdminAccess--: xref:proxy.adoc#TransparentUpgradeableProxy-ProxyDeniedAdminAccess-- +:ProxyAdmin: pass:normal[xref:proxy.adoc#ProxyAdmin[`ProxyAdmin`]] +:ERC1967Proxy-constructor: pass:normal[xref:proxy.adoc#ERC1967Proxy-constructor-address-bytes-[`ERC1967Proxy.constructor`]] +:TransparentUpgradeableProxy: pass:normal[xref:proxy.adoc#TransparentUpgradeableProxy[`TransparentUpgradeableProxy`]] +:TransparentUpgradeableProxy: pass:normal[xref:proxy.adoc#TransparentUpgradeableProxy[`TransparentUpgradeableProxy`]] +:xref-ProxyAdmin-constructor-address-: xref:proxy.adoc#ProxyAdmin-constructor-address- +:xref-ProxyAdmin-upgradeAndCall-contract-ITransparentUpgradeableProxy-address-bytes-: xref:proxy.adoc#ProxyAdmin-upgradeAndCall-contract-ITransparentUpgradeableProxy-address-bytes- +:xref-Ownable-owner--: xref:access.adoc#Ownable-owner-- +:xref-Ownable-_checkOwner--: xref:access.adoc#Ownable-_checkOwner-- +:xref-Ownable-renounceOwnership--: xref:access.adoc#Ownable-renounceOwnership-- +:xref-Ownable-transferOwnership-address-: xref:access.adoc#Ownable-transferOwnership-address- +:xref-Ownable-_transferOwnership-address-: xref:access.adoc#Ownable-_transferOwnership-address- +:xref-Ownable-OwnershipTransferred-address-address-: xref:access.adoc#Ownable-OwnershipTransferred-address-address- +:xref-Ownable-OwnableUnauthorizedAccount-address-: xref:access.adoc#Ownable-OwnableUnauthorizedAccount-address- +:xref-Ownable-OwnableInvalidOwner-address-: xref:access.adoc#Ownable-OwnableInvalidOwner-address- +:TransparentUpgradeableProxy-_dispatchUpgradeToAndCall: pass:normal[xref:proxy.adoc#TransparentUpgradeableProxy-_dispatchUpgradeToAndCall--[`TransparentUpgradeableProxy._dispatchUpgradeToAndCall`]] +:UpgradeableBeacon: pass:normal[xref:proxy.adoc#UpgradeableBeacon[`UpgradeableBeacon`]] +:xref-BeaconProxy-constructor-address-bytes-: xref:proxy.adoc#BeaconProxy-constructor-address-bytes- +:xref-BeaconProxy-_implementation--: xref:proxy.adoc#BeaconProxy-_implementation-- +:xref-BeaconProxy-_getBeacon--: xref:proxy.adoc#BeaconProxy-_getBeacon-- +:xref-Proxy-_delegate-address-: xref:proxy.adoc#Proxy-_delegate-address- +:xref-Proxy-_fallback--: xref:proxy.adoc#Proxy-_fallback-- +:xref-Proxy-fallback--: xref:proxy.adoc#Proxy-fallback-- +:IBeacon: pass:normal[xref:proxy.adoc#IBeacon[`IBeacon`]] +:BeaconProxy: pass:normal[xref:proxy.adoc#BeaconProxy[`BeaconProxy`]] +:xref-IBeacon-implementation--: xref:proxy.adoc#IBeacon-implementation-- +:UpgradeableBeacon: pass:normal[xref:proxy.adoc#UpgradeableBeacon[`UpgradeableBeacon`]] +:BeaconProxy: pass:normal[xref:proxy.adoc#BeaconProxy[`BeaconProxy`]] +:xref-UpgradeableBeacon-constructor-address-address-: xref:proxy.adoc#UpgradeableBeacon-constructor-address-address- +:xref-UpgradeableBeacon-implementation--: xref:proxy.adoc#UpgradeableBeacon-implementation-- +:xref-UpgradeableBeacon-upgradeTo-address-: xref:proxy.adoc#UpgradeableBeacon-upgradeTo-address- +:xref-Ownable-owner--: xref:access.adoc#Ownable-owner-- +:xref-Ownable-_checkOwner--: xref:access.adoc#Ownable-_checkOwner-- +:xref-Ownable-renounceOwnership--: xref:access.adoc#Ownable-renounceOwnership-- +:xref-Ownable-transferOwnership-address-: xref:access.adoc#Ownable-transferOwnership-address- +:xref-Ownable-_transferOwnership-address-: xref:access.adoc#Ownable-_transferOwnership-address- +:xref-UpgradeableBeacon-Upgraded-address-: xref:proxy.adoc#UpgradeableBeacon-Upgraded-address- +:xref-Ownable-OwnershipTransferred-address-address-: xref:access.adoc#Ownable-OwnershipTransferred-address-address- +:xref-UpgradeableBeacon-BeaconInvalidImplementation-address-: xref:proxy.adoc#UpgradeableBeacon-BeaconInvalidImplementation-address- +:xref-Ownable-OwnableUnauthorizedAccount-address-: xref:access.adoc#Ownable-OwnableUnauthorizedAccount-address- +:xref-Ownable-OwnableInvalidOwner-address-: xref:access.adoc#Ownable-OwnableInvalidOwner-address- +:xref-Clones-clone-address-: xref:proxy.adoc#Clones-clone-address- +:xref-Clones-cloneDeterministic-address-bytes32-: xref:proxy.adoc#Clones-cloneDeterministic-address-bytes32- +:xref-Clones-predictDeterministicAddress-address-bytes32-address-: xref:proxy.adoc#Clones-predictDeterministicAddress-address-bytes32-address- +:xref-Clones-predictDeterministicAddress-address-bytes32-: xref:proxy.adoc#Clones-predictDeterministicAddress-address-bytes32- +:xref-Clones-ERC1167FailedCreateClone--: xref:proxy.adoc#Clones-ERC1167FailedCreateClone-- +:Clones-cloneDeterministic: pass:normal[xref:proxy.adoc#Clones-cloneDeterministic-address-bytes32-[`Clones.cloneDeterministic`]] +:Clones-cloneDeterministic: pass:normal[xref:proxy.adoc#Clones-cloneDeterministic-address-bytes32-[`Clones.cloneDeterministic`]] +:ERC1967Proxy-constructor: pass:normal[xref:proxy.adoc#ERC1967Proxy-constructor-address-bytes-[`ERC1967Proxy.constructor`]] +:xref-Initializable-initializer--: xref:proxy.adoc#Initializable-initializer-- +:xref-Initializable-reinitializer-uint64-: xref:proxy.adoc#Initializable-reinitializer-uint64- +:xref-Initializable-onlyInitializing--: xref:proxy.adoc#Initializable-onlyInitializing-- +:xref-Initializable-_checkInitializing--: xref:proxy.adoc#Initializable-_checkInitializing-- +:xref-Initializable-_disableInitializers--: xref:proxy.adoc#Initializable-_disableInitializers-- +:xref-Initializable-_getInitializedVersion--: xref:proxy.adoc#Initializable-_getInitializedVersion-- +:xref-Initializable-_isInitializing--: xref:proxy.adoc#Initializable-_isInitializing-- +:xref-Initializable-Initialized-uint64-: xref:proxy.adoc#Initializable-Initialized-uint64- +:xref-Initializable-InvalidInitialization--: xref:proxy.adoc#Initializable-InvalidInitialization-- +:xref-Initializable-NotInitializing--: xref:proxy.adoc#Initializable-NotInitializing-- +:ERC1967Proxy: pass:normal[xref:proxy.adoc#ERC1967Proxy[`ERC1967Proxy`]] +:xref-UUPSUpgradeable-onlyProxy--: xref:proxy.adoc#UUPSUpgradeable-onlyProxy-- +:xref-UUPSUpgradeable-notDelegated--: xref:proxy.adoc#UUPSUpgradeable-notDelegated-- +:xref-UUPSUpgradeable-proxiableUUID--: xref:proxy.adoc#UUPSUpgradeable-proxiableUUID-- +:xref-UUPSUpgradeable-upgradeToAndCall-address-bytes-: xref:proxy.adoc#UUPSUpgradeable-upgradeToAndCall-address-bytes- +:xref-UUPSUpgradeable-_checkProxy--: xref:proxy.adoc#UUPSUpgradeable-_checkProxy-- +:xref-UUPSUpgradeable-_checkNotDelegated--: xref:proxy.adoc#UUPSUpgradeable-_checkNotDelegated-- +:xref-UUPSUpgradeable-_authorizeUpgrade-address-: xref:proxy.adoc#UUPSUpgradeable-_authorizeUpgrade-address- +:xref-UUPSUpgradeable-UUPSUnauthorizedCallContext--: xref:proxy.adoc#UUPSUpgradeable-UUPSUnauthorizedCallContext-- +:xref-UUPSUpgradeable-UUPSUnsupportedProxiableUUID-bytes32-: xref:proxy.adoc#UUPSUpgradeable-UUPSUnsupportedProxiableUUID-bytes32- +:Ownable-onlyOwner: pass:normal[xref:access.adoc#Ownable-onlyOwner--[`Ownable.onlyOwner`]] += Proxies + +[.readme-notice] +NOTE: This document is better viewed at https://docs.openzeppelin.com/contracts/api/proxy + +This is a low-level set of contracts implementing different proxy patterns with and without upgradeability. For an in-depth overview of this pattern check out the xref:upgrades-plugins::proxies.adoc[Proxy Upgrade Pattern] page. + +Most of the proxies below are built on an abstract base contract. + +- {Proxy}: Abstract contract implementing the core delegation functionality. + +In order to avoid clashes with the storage variables of the implementation contract behind a proxy, we use https://eips.ethereum.org/EIPS/eip-1967[EIP1967] storage slots. + +- {ERC1967Utils}: Internal functions to get and set the storage slots defined in EIP1967. +- {ERC1967Proxy}: A proxy using EIP1967 storage slots. Not upgradeable by default. + +There are two alternative ways to add upgradeability to an ERC1967 proxy. Their differences are explained below in <>. + +- {TransparentUpgradeableProxy}: A proxy with a built-in immutable admin and upgrade interface. +- {UUPSUpgradeable}: An upgradeability mechanism to be included in the implementation contract. + +CAUTION: Using upgradeable proxies correctly and securely is a difficult task that requires deep knowledge of the proxy pattern, Solidity, and the EVM. Unless you want a lot of low level control, we recommend using the xref:upgrades-plugins::index.adoc[OpenZeppelin Upgrades Plugins] for Truffle and Hardhat. + +A different family of proxies are beacon proxies. This pattern, popularized by Dharma, allows multiple proxies to be upgraded to a different implementation in a single transaction. + +- {BeaconProxy}: A proxy that retrieves its implementation from a beacon contract. +- {UpgradeableBeacon}: A beacon contract with a built in admin that can upgrade the {BeaconProxy} pointing to it. + +In this pattern, the proxy contract doesn't hold the implementation address in storage like an ERC1967 proxy. Instead, the address is stored in a separate beacon contract. The `upgrade` operations are sent to the beacon instead of to the proxy contract, and all proxies that follow that beacon are automatically upgraded. + +Outside the realm of upgradeability, proxies can also be useful to make cheap contract clones, such as those created by an on-chain factory contract that creates many instances of the same contract. These instances are designed to be both cheap to deploy, and cheap to call. + +- {Clones}: A library that can deploy cheap minimal non-upgradeable proxies. + +[[transparent-vs-uups]] +== Transparent vs UUPS Proxies + +The original proxies included in OpenZeppelin followed the https://blog.openzeppelin.com/the-transparent-proxy-pattern/[Transparent Proxy Pattern]. While this pattern is still provided, our recommendation is now shifting towards UUPS proxies, which are both lightweight and versatile. The name UUPS comes from https://eips.ethereum.org/EIPS/eip-1822[EIP1822], which first documented the pattern. + +While both of these share the same interface for upgrades, in UUPS proxies the upgrade is handled by the implementation, and can eventually be removed. Transparent proxies, on the other hand, include the upgrade and admin logic in the proxy itself. This means {TransparentUpgradeableProxy} is more expensive to deploy than what is possible with UUPS proxies. + +UUPS proxies are implemented using an {ERC1967Proxy}. Note that this proxy is not by itself upgradeable. It is the role of the implementation to include, alongside the contract's logic, all the code necessary to update the implementation's address that is stored at a specific slot in the proxy's storage space. This is where the {UUPSUpgradeable} contract comes in. Inheriting from it (and overriding the {xref-UUPSUpgradeable-_authorizeUpgrade-address-}[`_authorizeUpgrade`] function with the relevant access control mechanism) will turn your contract into a UUPS compliant implementation. + +Note that since both proxies use the same storage slot for the implementation address, using a UUPS compliant implementation with a {TransparentUpgradeableProxy} might allow non-admins to perform upgrade operations. + +By default, the upgrade functionality included in {UUPSUpgradeable} contains a security mechanism that will prevent any upgrades to a non UUPS compliant implementation. This prevents upgrades to an implementation contract that wouldn't contain the necessary upgrade mechanism, as it would lock the upgradeability of the proxy forever. This security mechanism can be bypassed by either of: + +- Adding a flag mechanism in the implementation that will disable the upgrade function when triggered. +- Upgrading to an implementation that features an upgrade mechanism without the additional security check, and then upgrading again to another implementation without the upgrade mechanism. + +The current implementation of this security mechanism uses https://eips.ethereum.org/EIPS/eip-1822[EIP1822] to detect the storage slot used by the implementation. A previous implementation, now deprecated, relied on a rollback check. It is possible to upgrade from a contract using the old mechanism to a new one. The inverse is however not possible, as old implementations (before version 4.5) did not include the `ERC1822` interface. + +== Core + +:_delegate: pass:normal[xref:#Proxy-_delegate-address-[`++_delegate++`]] +:_implementation: pass:normal[xref:#Proxy-_implementation--[`++_implementation++`]] +:_fallback: pass:normal[xref:#Proxy-_fallback--[`++_fallback++`]] +:fallback: pass:normal[xref:#Proxy-fallback--[`++fallback++`]] + +[.contract] +[[Proxy]] +=== `++Proxy++` link:https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v5.0.0-rc.0/contracts/proxy/Proxy.sol[{github-icon},role=heading-link] + +[.hljs-theme-light.nopadding] +```solidity +import "@openzeppelin/contracts/proxy/Proxy.sol"; +``` + +This abstract contract provides a fallback function that delegates all calls to another contract using the EVM +instruction `delegatecall`. We refer to the second contract as the _implementation_ behind the proxy, and it has to +be specified by overriding the virtual {_implementation} function. + +Additionally, delegation to the implementation can be triggered manually through the {_fallback} function, or to a +different contract through the {_delegate} function. + +The success and return data of the delegated call will be returned back to the caller of the proxy. + +[.contract-index] +.Functions +-- +* {xref-Proxy-_delegate-address-}[`++_delegate(implementation)++`] +* {xref-Proxy-_implementation--}[`++_implementation()++`] +* {xref-Proxy-_fallback--}[`++_fallback()++`] +* {xref-Proxy-fallback--}[`++fallback()++`] + +-- + +[.contract-item] +[[Proxy-_delegate-address-]] +==== `[.contract-item-name]#++_delegate++#++(address implementation)++` [.item-kind]#internal# + +Delegates the current call to `implementation`. + +This function does not return to its internal call site, it will return directly to the external caller. + +[.contract-item] +[[Proxy-_implementation--]] +==== `[.contract-item-name]#++_implementation++#++() → address++` [.item-kind]#internal# + +This is a virtual function that should be overridden so it returns the address to which the fallback +function and {_fallback} should delegate. + +[.contract-item] +[[Proxy-_fallback--]] +==== `[.contract-item-name]#++_fallback++#++()++` [.item-kind]#internal# + +Delegates the current call to the address returned by `_implementation()`. + +This function does not return to its internal call site, it will return directly to the external caller. + +[.contract-item] +[[Proxy-fallback--]] +==== `[.contract-item-name]#++fallback++#++()++` [.item-kind]#external# + +Fallback function that delegates calls to the address returned by `_implementation()`. Will run if no other +function in the contract matches the call data. + +== ERC1967 + +:constructor: pass:normal[xref:#ERC1967Proxy-constructor-address-bytes-[`++constructor++`]] +:_implementation: pass:normal[xref:#ERC1967Proxy-_implementation--[`++_implementation++`]] + +[.contract] +[[ERC1967Proxy]] +=== `++ERC1967Proxy++` link:https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v5.0.0-rc.0/contracts/proxy/ERC1967/ERC1967Proxy.sol[{github-icon},role=heading-link] + +[.hljs-theme-light.nopadding] +```solidity +import "@openzeppelin/contracts/proxy/ERC1967/ERC1967Proxy.sol"; +``` + +This contract implements an upgradeable proxy. It is upgradeable because calls are delegated to an +implementation address that can be changed. This address is stored in storage in the location specified by +https://eips.ethereum.org/EIPS/eip-1967[EIP1967], so that it doesn't conflict with the storage layout of the +implementation behind the proxy. + +[.contract-index] +.Functions +-- +* {xref-ERC1967Proxy-constructor-address-bytes-}[`++constructor(implementation, _data)++`] +* {xref-ERC1967Proxy-_implementation--}[`++_implementation()++`] + +[.contract-subindex-inherited] +.Proxy +* {xref-Proxy-_delegate-address-}[`++_delegate(implementation)++`] +* {xref-Proxy-_fallback--}[`++_fallback()++`] +* {xref-Proxy-fallback--}[`++fallback()++`] + +-- + +[.contract-item] +[[ERC1967Proxy-constructor-address-bytes-]] +==== `[.contract-item-name]#++constructor++#++(address implementation, bytes _data)++` [.item-kind]#public# + +Initializes the upgradeable proxy with an initial implementation specified by `implementation`. + +If `_data` is nonempty, it's used as data in a delegate call to `implementation`. This will typically be an +encoded function call, and allows initializing the storage of the proxy like a Solidity constructor. + +Requirements: + +- If `data` is empty, `msg.value` must be zero. + +[.contract-item] +[[ERC1967Proxy-_implementation--]] +==== `[.contract-item-name]#++_implementation++#++() → address++` [.item-kind]#internal# + +Returns the current implementation address. + +TIP: To get this value clients can read directly from the storage slot shown below (specified by EIP1967) using +the https://eth.wiki/json-rpc/API#eth_getstorageat[`eth_getStorageAt`] RPC call. +`0x360894a13ba1a3210667c828492db98dca3e2076cc3735a920a3ca505d382bbc` + +:Upgraded: pass:normal[xref:#ERC1967Utils-Upgraded-address-[`++Upgraded++`]] +:AdminChanged: pass:normal[xref:#ERC1967Utils-AdminChanged-address-address-[`++AdminChanged++`]] +:BeaconUpgraded: pass:normal[xref:#ERC1967Utils-BeaconUpgraded-address-[`++BeaconUpgraded++`]] +:IMPLEMENTATION_SLOT: pass:normal[xref:#ERC1967Utils-IMPLEMENTATION_SLOT-bytes32[`++IMPLEMENTATION_SLOT++`]] +:ERC1967InvalidImplementation: pass:normal[xref:#ERC1967Utils-ERC1967InvalidImplementation-address-[`++ERC1967InvalidImplementation++`]] +:ERC1967InvalidAdmin: pass:normal[xref:#ERC1967Utils-ERC1967InvalidAdmin-address-[`++ERC1967InvalidAdmin++`]] +:ERC1967InvalidBeacon: pass:normal[xref:#ERC1967Utils-ERC1967InvalidBeacon-address-[`++ERC1967InvalidBeacon++`]] +:ERC1967NonPayable: pass:normal[xref:#ERC1967Utils-ERC1967NonPayable--[`++ERC1967NonPayable++`]] +:getImplementation: pass:normal[xref:#ERC1967Utils-getImplementation--[`++getImplementation++`]] +:upgradeToAndCall: pass:normal[xref:#ERC1967Utils-upgradeToAndCall-address-bytes-[`++upgradeToAndCall++`]] +:ADMIN_SLOT: pass:normal[xref:#ERC1967Utils-ADMIN_SLOT-bytes32[`++ADMIN_SLOT++`]] +:getAdmin: pass:normal[xref:#ERC1967Utils-getAdmin--[`++getAdmin++`]] +:changeAdmin: pass:normal[xref:#ERC1967Utils-changeAdmin-address-[`++changeAdmin++`]] +:BEACON_SLOT: pass:normal[xref:#ERC1967Utils-BEACON_SLOT-bytes32[`++BEACON_SLOT++`]] +:getBeacon: pass:normal[xref:#ERC1967Utils-getBeacon--[`++getBeacon++`]] +:upgradeBeaconToAndCall: pass:normal[xref:#ERC1967Utils-upgradeBeaconToAndCall-address-bytes-[`++upgradeBeaconToAndCall++`]] + +[.contract] +[[ERC1967Utils]] +=== `++ERC1967Utils++` link:https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v5.0.0-rc.0/contracts/proxy/ERC1967/ERC1967Utils.sol[{github-icon},role=heading-link] + +[.hljs-theme-light.nopadding] +```solidity +import "@openzeppelin/contracts/proxy/ERC1967/ERC1967Utils.sol"; +``` + +This abstract contract provides getters and event emitting update functions for +https://eips.ethereum.org/EIPS/eip-1967[EIP1967] slots. + +[.contract-index] +.Functions +-- +* {xref-ERC1967Utils-getImplementation--}[`++getImplementation()++`] +* {xref-ERC1967Utils-upgradeToAndCall-address-bytes-}[`++upgradeToAndCall(newImplementation, data)++`] +* {xref-ERC1967Utils-getAdmin--}[`++getAdmin()++`] +* {xref-ERC1967Utils-changeAdmin-address-}[`++changeAdmin(newAdmin)++`] +* {xref-ERC1967Utils-getBeacon--}[`++getBeacon()++`] +* {xref-ERC1967Utils-upgradeBeaconToAndCall-address-bytes-}[`++upgradeBeaconToAndCall(newBeacon, data)++`] + +-- + +[.contract-index] +.Events +-- +* {xref-ERC1967Utils-Upgraded-address-}[`++Upgraded(implementation)++`] +* {xref-ERC1967Utils-AdminChanged-address-address-}[`++AdminChanged(previousAdmin, newAdmin)++`] +* {xref-ERC1967Utils-BeaconUpgraded-address-}[`++BeaconUpgraded(beacon)++`] + +-- + +[.contract-index] +.Errors +-- +* {xref-ERC1967Utils-ERC1967InvalidImplementation-address-}[`++ERC1967InvalidImplementation(implementation)++`] +* {xref-ERC1967Utils-ERC1967InvalidAdmin-address-}[`++ERC1967InvalidAdmin(admin)++`] +* {xref-ERC1967Utils-ERC1967InvalidBeacon-address-}[`++ERC1967InvalidBeacon(beacon)++`] +* {xref-ERC1967Utils-ERC1967NonPayable--}[`++ERC1967NonPayable()++`] + +-- + +[.contract-item] +[[ERC1967Utils-getImplementation--]] +==== `[.contract-item-name]#++getImplementation++#++() → address++` [.item-kind]#internal# + +Returns the current implementation address. + +[.contract-item] +[[ERC1967Utils-upgradeToAndCall-address-bytes-]] +==== `[.contract-item-name]#++upgradeToAndCall++#++(address newImplementation, bytes data)++` [.item-kind]#internal# + +Performs implementation upgrade with additional setup call if data is nonempty. +This function is payable only if the setup call is performed, otherwise `msg.value` is rejected +to avoid stuck value in the contract. + +Emits an {IERC1967-Upgraded} event. + +[.contract-item] +[[ERC1967Utils-getAdmin--]] +==== `[.contract-item-name]#++getAdmin++#++() → address++` [.item-kind]#internal# + +Returns the current admin. + +TIP: To get this value clients can read directly from the storage slot shown below (specified by EIP1967) using +the https://eth.wiki/json-rpc/API#eth_getstorageat[`eth_getStorageAt`] RPC call. +`0xb53127684a568b3173ae13b9f8a6016e243e63b6e8ee1178d6a717850b5d6103` + +[.contract-item] +[[ERC1967Utils-changeAdmin-address-]] +==== `[.contract-item-name]#++changeAdmin++#++(address newAdmin)++` [.item-kind]#internal# + +Changes the admin of the proxy. + +Emits an {IERC1967-AdminChanged} event. + +[.contract-item] +[[ERC1967Utils-getBeacon--]] +==== `[.contract-item-name]#++getBeacon++#++() → address++` [.item-kind]#internal# + +Returns the current beacon. + +[.contract-item] +[[ERC1967Utils-upgradeBeaconToAndCall-address-bytes-]] +==== `[.contract-item-name]#++upgradeBeaconToAndCall++#++(address newBeacon, bytes data)++` [.item-kind]#internal# + +Change the beacon and trigger a setup call if data is nonempty. +This function is payable only if the setup call is performed, otherwise `msg.value` is rejected +to avoid stuck value in the contract. + +Emits an {IERC1967-BeaconUpgraded} event. + +CAUTION: Invoking this function has no effect on an instance of {BeaconProxy} since v5, since +it uses an immutable beacon without looking at the value of the ERC-1967 beacon slot for +efficiency. + +[.contract-item] +[[ERC1967Utils-Upgraded-address-]] +==== `[.contract-item-name]#++Upgraded++#++(address indexed implementation)++` [.item-kind]#event# + +Emitted when the implementation is upgraded. + +[.contract-item] +[[ERC1967Utils-AdminChanged-address-address-]] +==== `[.contract-item-name]#++AdminChanged++#++(address previousAdmin, address newAdmin)++` [.item-kind]#event# + +Emitted when the admin account has changed. + +[.contract-item] +[[ERC1967Utils-BeaconUpgraded-address-]] +==== `[.contract-item-name]#++BeaconUpgraded++#++(address indexed beacon)++` [.item-kind]#event# + +Emitted when the beacon is changed. + +[.contract-item] +[[ERC1967Utils-ERC1967InvalidImplementation-address-]] +==== `[.contract-item-name]#++ERC1967InvalidImplementation++#++(address implementation)++` [.item-kind]#error# + +The `implementation` of the proxy is invalid. + +[.contract-item] +[[ERC1967Utils-ERC1967InvalidAdmin-address-]] +==== `[.contract-item-name]#++ERC1967InvalidAdmin++#++(address admin)++` [.item-kind]#error# + +The `admin` of the proxy is invalid. + +[.contract-item] +[[ERC1967Utils-ERC1967InvalidBeacon-address-]] +==== `[.contract-item-name]#++ERC1967InvalidBeacon++#++(address beacon)++` [.item-kind]#error# + +The `beacon` of the proxy is invalid. + +[.contract-item] +[[ERC1967Utils-ERC1967NonPayable--]] +==== `[.contract-item-name]#++ERC1967NonPayable++#++()++` [.item-kind]#error# + +An upgrade function sees `msg.value > 0` that may be lost. + +== Transparent Proxy + +:ProxyDeniedAdminAccess: pass:normal[xref:#TransparentUpgradeableProxy-ProxyDeniedAdminAccess--[`++ProxyDeniedAdminAccess++`]] +:constructor: pass:normal[xref:#TransparentUpgradeableProxy-constructor-address-address-bytes-[`++constructor++`]] +:_proxyAdmin: pass:normal[xref:#TransparentUpgradeableProxy-_proxyAdmin--[`++_proxyAdmin++`]] +:_fallback: pass:normal[xref:#TransparentUpgradeableProxy-_fallback--[`++_fallback++`]] + +[.contract] +[[TransparentUpgradeableProxy]] +=== `++TransparentUpgradeableProxy++` link:https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v5.0.0-rc.0/contracts/proxy/transparent/TransparentUpgradeableProxy.sol[{github-icon},role=heading-link] + +[.hljs-theme-light.nopadding] +```solidity +import "@openzeppelin/contracts/proxy/transparent/TransparentUpgradeableProxy.sol"; +``` + +This contract implements a proxy that is upgradeable through an associated {ProxyAdmin} instance. + +To avoid https://medium.com/nomic-labs-blog/malicious-backdoors-in-ethereum-proxies-62629adf3357[proxy selector +clashing], which can potentially be used in an attack, this contract uses the +https://blog.openzeppelin.com/the-transparent-proxy-pattern/[transparent proxy pattern]. This pattern implies two +things that go hand in hand: + +1. If any account other than the admin calls the proxy, the call will be forwarded to the implementation, even if +that call matches the {ITransparentUpgradeableProxy-upgradeToAndCall} function exposed by the proxy itself. +2. If the admin calls the proxy, it can call the `upgradeToAndCall` function but any other call won't be forwarded to +the implementation. If the admin tries to call a function on the implementation it will fail with an error indicating +the proxy admin cannot fallback to the target implementation. + +These properties mean that the admin account can only be used for upgrading the proxy, so it's best if it's a +dedicated account that is not used for anything else. This will avoid headaches due to sudden errors when trying to +call a function from the proxy implementation. For this reason, the proxy deploys an instance of {ProxyAdmin} and +allows upgrades only if they come through it. You should think of the `ProxyAdmin` instance as the administrative +interface of the proxy, including the ability to change who can trigger upgrades by transferring ownership. + +NOTE: The real interface of this proxy is that defined in `ITransparentUpgradeableProxy`. This contract does not +inherit from that interface, and instead `upgradeToAndCall` is implicitly implemented using a custom dispatch +mechanism in `_fallback`. Consequently, the compiler will not produce an ABI for this contract. This is necessary to +fully implement transparency without decoding reverts caused by selector clashes between the proxy and the +implementation. + +NOTE: This proxy does not inherit from {Context} deliberately. The {ProxyAdmin} of this contract won't send a +meta-transaction in any way, and any other meta-transaction setup should be made in the implementation contract. + +IMPORTANT: This contract avoids unnecessary storage reads by setting the admin only during construction as an +immutable variable, preventing any changes thereafter. However, the admin slot defined in ERC-1967 can still be +overwritten by the implementation logic pointed to by this proxy. In such cases, the contract may end up in an +undesirable state where the admin slot is different from the actual admin. + +WARNING: It is not recommended to extend this contract to add additional external functions. If you do so, the +compiler will not check that there are no selector conflicts, due to the note above. A selector clash between any new +function and the functions declared in {ITransparentUpgradeableProxy} will be resolved in favor of the new one. This +could render the `upgradeToAndCall` function inaccessible, preventing upgradeability and compromising transparency. + +[.contract-index] +.Functions +-- +* {xref-TransparentUpgradeableProxy-constructor-address-address-bytes-}[`++constructor(_logic, initialOwner, _data)++`] +* {xref-TransparentUpgradeableProxy-_proxyAdmin--}[`++_proxyAdmin()++`] +* {xref-TransparentUpgradeableProxy-_fallback--}[`++_fallback()++`] + +[.contract-subindex-inherited] +.ERC1967Proxy +* {xref-ERC1967Proxy-_implementation--}[`++_implementation()++`] + +[.contract-subindex-inherited] +.Proxy +* {xref-Proxy-_delegate-address-}[`++_delegate(implementation)++`] +* {xref-Proxy-fallback--}[`++fallback()++`] + +-- + +[.contract-index] +.Errors +-- +* {xref-TransparentUpgradeableProxy-ProxyDeniedAdminAccess--}[`++ProxyDeniedAdminAccess()++`] + +[.contract-subindex-inherited] +.ERC1967Proxy + +[.contract-subindex-inherited] +.Proxy + +-- + +[.contract-item] +[[TransparentUpgradeableProxy-constructor-address-address-bytes-]] +==== `[.contract-item-name]#++constructor++#++(address _logic, address initialOwner, bytes _data)++` [.item-kind]#public# + +Initializes an upgradeable proxy managed by an instance of a {ProxyAdmin} with an `initialOwner`, +backed by the implementation at `_logic`, and optionally initialized with `_data` as explained in +{ERC1967Proxy-constructor}. + +[.contract-item] +[[TransparentUpgradeableProxy-_proxyAdmin--]] +==== `[.contract-item-name]#++_proxyAdmin++#++() → address++` [.item-kind]#internal# + +Returns the admin of this proxy. + +[.contract-item] +[[TransparentUpgradeableProxy-_fallback--]] +==== `[.contract-item-name]#++_fallback++#++()++` [.item-kind]#internal# + +If caller is the admin process the call internally, otherwise transparently fallback to the proxy behavior. + +[.contract-item] +[[TransparentUpgradeableProxy-ProxyDeniedAdminAccess--]] +==== `[.contract-item-name]#++ProxyDeniedAdminAccess++#++()++` [.item-kind]#error# + +The proxy caller is the current admin, and can't fallback to the proxy target. + +:UPGRADE_INTERFACE_VERSION: pass:normal[xref:#ProxyAdmin-UPGRADE_INTERFACE_VERSION-string[`++UPGRADE_INTERFACE_VERSION++`]] +:constructor: pass:normal[xref:#ProxyAdmin-constructor-address-[`++constructor++`]] +:upgradeAndCall: pass:normal[xref:#ProxyAdmin-upgradeAndCall-contract-ITransparentUpgradeableProxy-address-bytes-[`++upgradeAndCall++`]] + +[.contract] +[[ProxyAdmin]] +=== `++ProxyAdmin++` link:https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v5.0.0-rc.0/contracts/proxy/transparent/ProxyAdmin.sol[{github-icon},role=heading-link] + +[.hljs-theme-light.nopadding] +```solidity +import "@openzeppelin/contracts/proxy/transparent/ProxyAdmin.sol"; +``` + +This is an auxiliary contract meant to be assigned as the admin of a {TransparentUpgradeableProxy}. For an +explanation of why you would want to use this see the documentation for {TransparentUpgradeableProxy}. + +[.contract-index] +.Functions +-- +* {xref-ProxyAdmin-constructor-address-}[`++constructor(initialOwner)++`] +* {xref-ProxyAdmin-upgradeAndCall-contract-ITransparentUpgradeableProxy-address-bytes-}[`++upgradeAndCall(proxy, implementation, data)++`] + +[.contract-subindex-inherited] +.Ownable +* {xref-Ownable-owner--}[`++owner()++`] +* {xref-Ownable-_checkOwner--}[`++_checkOwner()++`] +* {xref-Ownable-renounceOwnership--}[`++renounceOwnership()++`] +* {xref-Ownable-transferOwnership-address-}[`++transferOwnership(newOwner)++`] +* {xref-Ownable-_transferOwnership-address-}[`++_transferOwnership(newOwner)++`] + +-- + +[.contract-index] +.Events +-- + +[.contract-subindex-inherited] +.Ownable +* {xref-Ownable-OwnershipTransferred-address-address-}[`++OwnershipTransferred(previousOwner, newOwner)++`] + +-- + +[.contract-index] +.Errors +-- + +[.contract-subindex-inherited] +.Ownable +* {xref-Ownable-OwnableUnauthorizedAccount-address-}[`++OwnableUnauthorizedAccount(account)++`] +* {xref-Ownable-OwnableInvalidOwner-address-}[`++OwnableInvalidOwner(owner)++`] + +-- + +[.contract-item] +[[ProxyAdmin-constructor-address-]] +==== `[.contract-item-name]#++constructor++#++(address initialOwner)++` [.item-kind]#public# + +Sets the initial owner who can perform upgrades. + +[.contract-item] +[[ProxyAdmin-upgradeAndCall-contract-ITransparentUpgradeableProxy-address-bytes-]] +==== `[.contract-item-name]#++upgradeAndCall++#++(contract ITransparentUpgradeableProxy proxy, address implementation, bytes data)++` [.item-kind]#public# + +Upgrades `proxy` to `implementation` and calls a function on the new implementation. +See {TransparentUpgradeableProxy-_dispatchUpgradeToAndCall}. + +Requirements: + +- This contract must be the admin of `proxy`. +- If `data` is empty, `msg.value` must be zero. + +== Beacon + +:constructor: pass:normal[xref:#BeaconProxy-constructor-address-bytes-[`++constructor++`]] +:_implementation: pass:normal[xref:#BeaconProxy-_implementation--[`++_implementation++`]] +:_getBeacon: pass:normal[xref:#BeaconProxy-_getBeacon--[`++_getBeacon++`]] + +[.contract] +[[BeaconProxy]] +=== `++BeaconProxy++` link:https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v5.0.0-rc.0/contracts/proxy/beacon/BeaconProxy.sol[{github-icon},role=heading-link] + +[.hljs-theme-light.nopadding] +```solidity +import "@openzeppelin/contracts/proxy/beacon/BeaconProxy.sol"; +``` + +This contract implements a proxy that gets the implementation address for each call from an {UpgradeableBeacon}. + +The beacon address can only be set once during construction, and cannot be changed afterwards. It is stored in an +immutable variable to avoid unnecessary storage reads, and also in the beacon storage slot specified by +https://eips.ethereum.org/EIPS/eip-1967[EIP1967] so that it can be accessed externally. + +CAUTION: Since the beacon address can never be changed, you must ensure that you either control the beacon, or trust +the beacon to not upgrade the implementation maliciously. + +IMPORTANT: Do not use the implementation logic to modify the beacon storage slot. Doing so would leave the proxy in +an inconsistent state where the beacon storage slot does not match the beacon address. + +[.contract-index] +.Functions +-- +* {xref-BeaconProxy-constructor-address-bytes-}[`++constructor(beacon, data)++`] +* {xref-BeaconProxy-_implementation--}[`++_implementation()++`] +* {xref-BeaconProxy-_getBeacon--}[`++_getBeacon()++`] + +[.contract-subindex-inherited] +.Proxy +* {xref-Proxy-_delegate-address-}[`++_delegate(implementation)++`] +* {xref-Proxy-_fallback--}[`++_fallback()++`] +* {xref-Proxy-fallback--}[`++fallback()++`] + +-- + +[.contract-item] +[[BeaconProxy-constructor-address-bytes-]] +==== `[.contract-item-name]#++constructor++#++(address beacon, bytes data)++` [.item-kind]#public# + +Initializes the proxy with `beacon`. + +If `data` is nonempty, it's used as data in a delegate call to the implementation returned by the beacon. This +will typically be an encoded function call, and allows initializing the storage of the proxy like a Solidity +constructor. + +Requirements: + +- `beacon` must be a contract with the interface {IBeacon}. +- If `data` is empty, `msg.value` must be zero. + +[.contract-item] +[[BeaconProxy-_implementation--]] +==== `[.contract-item-name]#++_implementation++#++() → address++` [.item-kind]#internal# + +Returns the current implementation address of the associated beacon. + +[.contract-item] +[[BeaconProxy-_getBeacon--]] +==== `[.contract-item-name]#++_getBeacon++#++() → address++` [.item-kind]#internal# + +Returns the beacon. + +:implementation: pass:normal[xref:#IBeacon-implementation--[`++implementation++`]] + +[.contract] +[[IBeacon]] +=== `++IBeacon++` link:https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v5.0.0-rc.0/contracts/proxy/beacon/IBeacon.sol[{github-icon},role=heading-link] + +[.hljs-theme-light.nopadding] +```solidity +import "@openzeppelin/contracts/proxy/beacon/IBeacon.sol"; +``` + +This is the interface that {BeaconProxy} expects of its beacon. + +[.contract-index] +.Functions +-- +* {xref-IBeacon-implementation--}[`++implementation()++`] + +-- + +[.contract-item] +[[IBeacon-implementation--]] +==== `[.contract-item-name]#++implementation++#++() → address++` [.item-kind]#external# + +Must return an address that can be used as a delegate call target. + +{UpgradeableBeacon} will check that this address is a contract. + +:BeaconInvalidImplementation: pass:normal[xref:#UpgradeableBeacon-BeaconInvalidImplementation-address-[`++BeaconInvalidImplementation++`]] +:Upgraded: pass:normal[xref:#UpgradeableBeacon-Upgraded-address-[`++Upgraded++`]] +:constructor: pass:normal[xref:#UpgradeableBeacon-constructor-address-address-[`++constructor++`]] +:implementation: pass:normal[xref:#UpgradeableBeacon-implementation--[`++implementation++`]] +:upgradeTo: pass:normal[xref:#UpgradeableBeacon-upgradeTo-address-[`++upgradeTo++`]] + +[.contract] +[[UpgradeableBeacon]] +=== `++UpgradeableBeacon++` link:https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v5.0.0-rc.0/contracts/proxy/beacon/UpgradeableBeacon.sol[{github-icon},role=heading-link] + +[.hljs-theme-light.nopadding] +```solidity +import "@openzeppelin/contracts/proxy/beacon/UpgradeableBeacon.sol"; +``` + +This contract is used in conjunction with one or more instances of {BeaconProxy} to determine their +implementation contract, which is where they will delegate all function calls. + +An owner is able to change the implementation the beacon points to, thus upgrading the proxies that use this beacon. + +[.contract-index] +.Functions +-- +* {xref-UpgradeableBeacon-constructor-address-address-}[`++constructor(implementation_, initialOwner)++`] +* {xref-UpgradeableBeacon-implementation--}[`++implementation()++`] +* {xref-UpgradeableBeacon-upgradeTo-address-}[`++upgradeTo(newImplementation)++`] + +[.contract-subindex-inherited] +.Ownable +* {xref-Ownable-owner--}[`++owner()++`] +* {xref-Ownable-_checkOwner--}[`++_checkOwner()++`] +* {xref-Ownable-renounceOwnership--}[`++renounceOwnership()++`] +* {xref-Ownable-transferOwnership-address-}[`++transferOwnership(newOwner)++`] +* {xref-Ownable-_transferOwnership-address-}[`++_transferOwnership(newOwner)++`] + +[.contract-subindex-inherited] +.IBeacon + +-- + +[.contract-index] +.Events +-- +* {xref-UpgradeableBeacon-Upgraded-address-}[`++Upgraded(implementation)++`] + +[.contract-subindex-inherited] +.Ownable +* {xref-Ownable-OwnershipTransferred-address-address-}[`++OwnershipTransferred(previousOwner, newOwner)++`] + +[.contract-subindex-inherited] +.IBeacon + +-- + +[.contract-index] +.Errors +-- +* {xref-UpgradeableBeacon-BeaconInvalidImplementation-address-}[`++BeaconInvalidImplementation(implementation)++`] + +[.contract-subindex-inherited] +.Ownable +* {xref-Ownable-OwnableUnauthorizedAccount-address-}[`++OwnableUnauthorizedAccount(account)++`] +* {xref-Ownable-OwnableInvalidOwner-address-}[`++OwnableInvalidOwner(owner)++`] + +[.contract-subindex-inherited] +.IBeacon + +-- + +[.contract-item] +[[UpgradeableBeacon-constructor-address-address-]] +==== `[.contract-item-name]#++constructor++#++(address implementation_, address initialOwner)++` [.item-kind]#public# + +Sets the address of the initial implementation, and the initial owner who can upgrade the beacon. + +[.contract-item] +[[UpgradeableBeacon-implementation--]] +==== `[.contract-item-name]#++implementation++#++() → address++` [.item-kind]#public# + +Returns the current implementation address. + +[.contract-item] +[[UpgradeableBeacon-upgradeTo-address-]] +==== `[.contract-item-name]#++upgradeTo++#++(address newImplementation)++` [.item-kind]#public# + +Upgrades the beacon to a new implementation. + +Emits an {Upgraded} event. + +Requirements: + +- msg.sender must be the owner of the contract. +- `newImplementation` must be a contract. + +[.contract-item] +[[UpgradeableBeacon-Upgraded-address-]] +==== `[.contract-item-name]#++Upgraded++#++(address indexed implementation)++` [.item-kind]#event# + +Emitted when the implementation returned by the beacon is changed. + +[.contract-item] +[[UpgradeableBeacon-BeaconInvalidImplementation-address-]] +==== `[.contract-item-name]#++BeaconInvalidImplementation++#++(address implementation)++` [.item-kind]#error# + +The `implementation` of the beacon is invalid. + +== Minimal Clones + +:ERC1167FailedCreateClone: pass:normal[xref:#Clones-ERC1167FailedCreateClone--[`++ERC1167FailedCreateClone++`]] +:clone: pass:normal[xref:#Clones-clone-address-[`++clone++`]] +:cloneDeterministic: pass:normal[xref:#Clones-cloneDeterministic-address-bytes32-[`++cloneDeterministic++`]] +:predictDeterministicAddress: pass:normal[xref:#Clones-predictDeterministicAddress-address-bytes32-address-[`++predictDeterministicAddress++`]] +:predictDeterministicAddress: pass:normal[xref:#Clones-predictDeterministicAddress-address-bytes32-[`++predictDeterministicAddress++`]] + +[.contract] +[[Clones]] +=== `++Clones++` link:https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v5.0.0-rc.0/contracts/proxy/Clones.sol[{github-icon},role=heading-link] + +[.hljs-theme-light.nopadding] +```solidity +import "@openzeppelin/contracts/proxy/Clones.sol"; +``` + +https://eips.ethereum.org/EIPS/eip-1167[EIP 1167] is a standard for +deploying minimal proxy contracts, also known as "clones". + +> To simply and cheaply clone contract functionality in an immutable way, this standard specifies +> a minimal bytecode implementation that delegates all calls to a known, fixed address. + +The library includes functions to deploy a proxy using either `create` (traditional deployment) or `create2` +(salted deterministic deployment). It also includes functions to predict the addresses of clones deployed using the +deterministic method. + +[.contract-index] +.Functions +-- +* {xref-Clones-clone-address-}[`++clone(implementation)++`] +* {xref-Clones-cloneDeterministic-address-bytes32-}[`++cloneDeterministic(implementation, salt)++`] +* {xref-Clones-predictDeterministicAddress-address-bytes32-address-}[`++predictDeterministicAddress(implementation, salt, deployer)++`] +* {xref-Clones-predictDeterministicAddress-address-bytes32-}[`++predictDeterministicAddress(implementation, salt)++`] + +-- + +[.contract-index] +.Errors +-- +* {xref-Clones-ERC1167FailedCreateClone--}[`++ERC1167FailedCreateClone()++`] + +-- + +[.contract-item] +[[Clones-clone-address-]] +==== `[.contract-item-name]#++clone++#++(address implementation) → address instance++` [.item-kind]#internal# + +Deploys and returns the address of a clone that mimics the behaviour of `implementation`. + +This function uses the create opcode, which should never revert. + +[.contract-item] +[[Clones-cloneDeterministic-address-bytes32-]] +==== `[.contract-item-name]#++cloneDeterministic++#++(address implementation, bytes32 salt) → address instance++` [.item-kind]#internal# + +Deploys and returns the address of a clone that mimics the behaviour of `implementation`. + +This function uses the create2 opcode and a `salt` to deterministically deploy +the clone. Using the same `implementation` and `salt` multiple time will revert, since +the clones cannot be deployed twice at the same address. + +[.contract-item] +[[Clones-predictDeterministicAddress-address-bytes32-address-]] +==== `[.contract-item-name]#++predictDeterministicAddress++#++(address implementation, bytes32 salt, address deployer) → address predicted++` [.item-kind]#internal# + +Computes the address of a clone deployed using {Clones-cloneDeterministic}. + +[.contract-item] +[[Clones-predictDeterministicAddress-address-bytes32-]] +==== `[.contract-item-name]#++predictDeterministicAddress++#++(address implementation, bytes32 salt) → address predicted++` [.item-kind]#internal# + +Computes the address of a clone deployed using {Clones-cloneDeterministic}. + +[.contract-item] +[[Clones-ERC1167FailedCreateClone--]] +==== `[.contract-item-name]#++ERC1167FailedCreateClone++#++()++` [.item-kind]#error# + +A clone instance deployment failed. + +== Utils + +:InitializableStorage: pass:normal[xref:#Initializable-InitializableStorage[`++InitializableStorage++`]] +:InvalidInitialization: pass:normal[xref:#Initializable-InvalidInitialization--[`++InvalidInitialization++`]] +:NotInitializing: pass:normal[xref:#Initializable-NotInitializing--[`++NotInitializing++`]] +:Initialized: pass:normal[xref:#Initializable-Initialized-uint64-[`++Initialized++`]] +:initializer: pass:normal[xref:#Initializable-initializer--[`++initializer++`]] +:reinitializer: pass:normal[xref:#Initializable-reinitializer-uint64-[`++reinitializer++`]] +:onlyInitializing: pass:normal[xref:#Initializable-onlyInitializing--[`++onlyInitializing++`]] +:_checkInitializing: pass:normal[xref:#Initializable-_checkInitializing--[`++_checkInitializing++`]] +:_disableInitializers: pass:normal[xref:#Initializable-_disableInitializers--[`++_disableInitializers++`]] +:_getInitializedVersion: pass:normal[xref:#Initializable-_getInitializedVersion--[`++_getInitializedVersion++`]] +:_isInitializing: pass:normal[xref:#Initializable-_isInitializing--[`++_isInitializing++`]] + +[.contract] +[[Initializable]] +=== `++Initializable++` link:https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v5.0.0-rc.0/contracts/proxy/utils/Initializable.sol[{github-icon},role=heading-link] + +[.hljs-theme-light.nopadding] +```solidity +import "@openzeppelin/contracts/proxy/utils/Initializable.sol"; +``` + +This is a base contract to aid in writing upgradeable contracts, or any kind of contract that will be deployed +behind a proxy. Since proxied contracts do not make use of a constructor, it's common to move constructor logic to an +external initializer function, usually called `initialize`. It then becomes necessary to protect this initializer +function so it can only be called once. The {initializer} modifier provided by this contract will have this effect. + +The initialization functions use a version number. Once a version number is used, it is consumed and cannot be +reused. This mechanism prevents re-execution of each "step" but allows the creation of new initialization steps in +case an upgrade adds a module that needs to be initialized. + +For example: + +[.hljs-theme-light.nopadding] +```solidity +contract MyToken is ERC20Upgradeable { + function initialize() initializer public { + __ERC20_init("MyToken", "MTK"); + } +} + +contract MyTokenV2 is MyToken, ERC20PermitUpgradeable { + function initializeV2() reinitializer(2) public { + __ERC20Permit_init("MyToken"); + } +} +``` + +TIP: To avoid leaving the proxy in an uninitialized state, the initializer function should be called as early as +possible by providing the encoded function call as the `_data` argument to {ERC1967Proxy-constructor}. + +CAUTION: When used with inheritance, manual care must be taken to not invoke a parent initializer twice, or to ensure +that all initializers are idempotent. This is not verified automatically as constructors are by Solidity. + +[CAUTION] +==== +Avoid leaving a contract uninitialized. + +An uninitialized contract can be taken over by an attacker. This applies to both a proxy and its implementation +contract, which may impact the proxy. To prevent the implementation contract from being used, you should invoke +the {_disableInitializers} function in the constructor to automatically lock it when it is deployed: + +[.hljs-theme-light.nopadding] +``` +/// @custom:oz-upgrades-unsafe-allow constructor +constructor() { + _disableInitializers(); +} +``` +==== + +[.contract-index] +.Modifiers +-- +* {xref-Initializable-initializer--}[`++initializer()++`] +* {xref-Initializable-reinitializer-uint64-}[`++reinitializer(version)++`] +* {xref-Initializable-onlyInitializing--}[`++onlyInitializing()++`] +-- + +[.contract-index] +.Functions +-- +* {xref-Initializable-_checkInitializing--}[`++_checkInitializing()++`] +* {xref-Initializable-_disableInitializers--}[`++_disableInitializers()++`] +* {xref-Initializable-_getInitializedVersion--}[`++_getInitializedVersion()++`] +* {xref-Initializable-_isInitializing--}[`++_isInitializing()++`] + +-- + +[.contract-index] +.Events +-- +* {xref-Initializable-Initialized-uint64-}[`++Initialized(version)++`] + +-- + +[.contract-index] +.Errors +-- +* {xref-Initializable-InvalidInitialization--}[`++InvalidInitialization()++`] +* {xref-Initializable-NotInitializing--}[`++NotInitializing()++`] + +-- + +[.contract-item] +[[Initializable-initializer--]] +==== `[.contract-item-name]#++initializer++#++()++` [.item-kind]#modifier# + +A modifier that defines a protected initializer function that can be invoked at most once. In its scope, +`onlyInitializing` functions can be used to initialize parent contracts. + +Similar to `reinitializer(1)`, except that in the context of a constructor an `initializer` may be invoked any +number of times. This behavior in the constructor can be useful during testing and is not expected to be used in +production. + +Emits an {Initialized} event. + +[.contract-item] +[[Initializable-reinitializer-uint64-]] +==== `[.contract-item-name]#++reinitializer++#++(uint64 version)++` [.item-kind]#modifier# + +A modifier that defines a protected reinitializer function that can be invoked at most once, and only if the +contract hasn't been initialized to a greater version before. In its scope, `onlyInitializing` functions can be +used to initialize parent contracts. + +A reinitializer may be used after the original initialization step. This is essential to configure modules that +are added through upgrades and that require initialization. + +When `version` is 1, this modifier is similar to `initializer`, except that functions marked with `reinitializer` +cannot be nested. If one is invoked in the context of another, execution will revert. + +Note that versions can jump in increments greater than 1; this implies that if multiple reinitializers coexist in +a contract, executing them in the right order is up to the developer or operator. + +WARNING: Setting the version to 2**64 - 1 will prevent any future reinitialization. + +Emits an {Initialized} event. + +[.contract-item] +[[Initializable-onlyInitializing--]] +==== `[.contract-item-name]#++onlyInitializing++#++()++` [.item-kind]#modifier# + +Modifier to protect an initialization function so that it can only be invoked by functions with the +{initializer} and {reinitializer} modifiers, directly or indirectly. + +[.contract-item] +[[Initializable-_checkInitializing--]] +==== `[.contract-item-name]#++_checkInitializing++#++()++` [.item-kind]#internal# + +Reverts if the contract is not in an initializing state. See {onlyInitializing}. + +[.contract-item] +[[Initializable-_disableInitializers--]] +==== `[.contract-item-name]#++_disableInitializers++#++()++` [.item-kind]#internal# + +Locks the contract, preventing any future reinitialization. This cannot be part of an initializer call. +Calling this in the constructor of a contract will prevent that contract from being initialized or reinitialized +to any version. It is recommended to use this to lock implementation contracts that are designed to be called +through proxies. + +Emits an {Initialized} event the first time it is successfully executed. + +[.contract-item] +[[Initializable-_getInitializedVersion--]] +==== `[.contract-item-name]#++_getInitializedVersion++#++() → uint64++` [.item-kind]#internal# + +Returns the highest version that has been initialized. See {reinitializer}. + +[.contract-item] +[[Initializable-_isInitializing--]] +==== `[.contract-item-name]#++_isInitializing++#++() → bool++` [.item-kind]#internal# + +Returns `true` if the contract is currently initializing. See {onlyInitializing}. + +[.contract-item] +[[Initializable-Initialized-uint64-]] +==== `[.contract-item-name]#++Initialized++#++(uint64 version)++` [.item-kind]#event# + +Triggered when the contract has been initialized or reinitialized. + +[.contract-item] +[[Initializable-InvalidInitialization--]] +==== `[.contract-item-name]#++InvalidInitialization++#++()++` [.item-kind]#error# + +The contract is already initialized. + +[.contract-item] +[[Initializable-NotInitializing--]] +==== `[.contract-item-name]#++NotInitializing++#++()++` [.item-kind]#error# + +The contract is not initializing. + +:UPGRADE_INTERFACE_VERSION: pass:normal[xref:#UUPSUpgradeable-UPGRADE_INTERFACE_VERSION-string[`++UPGRADE_INTERFACE_VERSION++`]] +:UUPSUnauthorizedCallContext: pass:normal[xref:#UUPSUpgradeable-UUPSUnauthorizedCallContext--[`++UUPSUnauthorizedCallContext++`]] +:UUPSUnsupportedProxiableUUID: pass:normal[xref:#UUPSUpgradeable-UUPSUnsupportedProxiableUUID-bytes32-[`++UUPSUnsupportedProxiableUUID++`]] +:onlyProxy: pass:normal[xref:#UUPSUpgradeable-onlyProxy--[`++onlyProxy++`]] +:notDelegated: pass:normal[xref:#UUPSUpgradeable-notDelegated--[`++notDelegated++`]] +:proxiableUUID: pass:normal[xref:#UUPSUpgradeable-proxiableUUID--[`++proxiableUUID++`]] +:upgradeToAndCall: pass:normal[xref:#UUPSUpgradeable-upgradeToAndCall-address-bytes-[`++upgradeToAndCall++`]] +:_checkProxy: pass:normal[xref:#UUPSUpgradeable-_checkProxy--[`++_checkProxy++`]] +:_checkNotDelegated: pass:normal[xref:#UUPSUpgradeable-_checkNotDelegated--[`++_checkNotDelegated++`]] +:_authorizeUpgrade: pass:normal[xref:#UUPSUpgradeable-_authorizeUpgrade-address-[`++_authorizeUpgrade++`]] + +[.contract] +[[UUPSUpgradeable]] +=== `++UUPSUpgradeable++` link:https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v5.0.0-rc.0/contracts/proxy/utils/UUPSUpgradeable.sol[{github-icon},role=heading-link] + +[.hljs-theme-light.nopadding] +```solidity +import "@openzeppelin/contracts/proxy/utils/UUPSUpgradeable.sol"; +``` + +An upgradeability mechanism designed for UUPS proxies. The functions included here can perform an upgrade of an +{ERC1967Proxy}, when this contract is set as the implementation behind such a proxy. + +A security mechanism ensures that an upgrade does not turn off upgradeability accidentally, although this risk is +reinstated if the upgrade retains upgradeability but removes the security mechanism, e.g. by replacing +`UUPSUpgradeable` with a custom implementation of upgrades. + +The {_authorizeUpgrade} function must be overridden to include access restriction to the upgrade mechanism. + +[.contract-index] +.Modifiers +-- +* {xref-UUPSUpgradeable-onlyProxy--}[`++onlyProxy()++`] +* {xref-UUPSUpgradeable-notDelegated--}[`++notDelegated()++`] +-- + +[.contract-index] +.Functions +-- +* {xref-UUPSUpgradeable-proxiableUUID--}[`++proxiableUUID()++`] +* {xref-UUPSUpgradeable-upgradeToAndCall-address-bytes-}[`++upgradeToAndCall(newImplementation, data)++`] +* {xref-UUPSUpgradeable-_checkProxy--}[`++_checkProxy()++`] +* {xref-UUPSUpgradeable-_checkNotDelegated--}[`++_checkNotDelegated()++`] +* {xref-UUPSUpgradeable-_authorizeUpgrade-address-}[`++_authorizeUpgrade(newImplementation)++`] + +[.contract-subindex-inherited] +.IERC1822Proxiable + +-- + +[.contract-index] +.Errors +-- +* {xref-UUPSUpgradeable-UUPSUnauthorizedCallContext--}[`++UUPSUnauthorizedCallContext()++`] +* {xref-UUPSUpgradeable-UUPSUnsupportedProxiableUUID-bytes32-}[`++UUPSUnsupportedProxiableUUID(slot)++`] + +[.contract-subindex-inherited] +.IERC1822Proxiable + +-- + +[.contract-item] +[[UUPSUpgradeable-onlyProxy--]] +==== `[.contract-item-name]#++onlyProxy++#++()++` [.item-kind]#modifier# + +Check that the execution is being performed through a delegatecall call and that the execution context is +a proxy contract with an implementation (as defined in ERC1967) pointing to self. This should only be the case +for UUPS and transparent proxies that are using the current contract as their implementation. Execution of a +function through ERC1167 minimal proxies (clones) would not normally pass this test, but is not guaranteed to +fail. + +[.contract-item] +[[UUPSUpgradeable-notDelegated--]] +==== `[.contract-item-name]#++notDelegated++#++()++` [.item-kind]#modifier# + +Check that the execution is not being performed through a delegate call. This allows a function to be +callable on the implementing contract but not through proxies. + +[.contract-item] +[[UUPSUpgradeable-proxiableUUID--]] +==== `[.contract-item-name]#++proxiableUUID++#++() → bytes32++` [.item-kind]#external# + +Implementation of the ERC1822 {proxiableUUID} function. This returns the storage slot used by the +implementation. It is used to validate the implementation's compatibility when performing an upgrade. + +IMPORTANT: A proxy pointing at a proxiable contract should not be considered proxiable itself, because this risks +bricking a proxy that upgrades to it, by delegating to itself until out of gas. Thus it is critical that this +function revert if invoked through a proxy. This is guaranteed by the `notDelegated` modifier. + +[.contract-item] +[[UUPSUpgradeable-upgradeToAndCall-address-bytes-]] +==== `[.contract-item-name]#++upgradeToAndCall++#++(address newImplementation, bytes data)++` [.item-kind]#public# + +Upgrade the implementation of the proxy to `newImplementation`, and subsequently execute the function call +encoded in `data`. + +Calls {_authorizeUpgrade}. + +Emits an {Upgraded} event. + +[.contract-item] +[[UUPSUpgradeable-_checkProxy--]] +==== `[.contract-item-name]#++_checkProxy++#++()++` [.item-kind]#internal# + +Reverts if the execution is not performed via delegatecall or the execution +context is not of a proxy with an ERC1967-compliant implementation pointing to self. +See {_onlyProxy}. + +[.contract-item] +[[UUPSUpgradeable-_checkNotDelegated--]] +==== `[.contract-item-name]#++_checkNotDelegated++#++()++` [.item-kind]#internal# + +Reverts if the execution is performed via delegatecall. +See {notDelegated}. + +[.contract-item] +[[UUPSUpgradeable-_authorizeUpgrade-address-]] +==== `[.contract-item-name]#++_authorizeUpgrade++#++(address newImplementation)++` [.item-kind]#internal# + +Function that should revert when `msg.sender` is not authorized to upgrade the contract. Called by +{upgradeToAndCall}. + +Normally, this function will use an xref:access.adoc[access control] modifier such as {Ownable-onlyOwner}. + +```solidity +function _authorizeUpgrade(address) internal onlyOwner {} +``` + +[.contract-item] +[[UUPSUpgradeable-UUPSUnauthorizedCallContext--]] +==== `[.contract-item-name]#++UUPSUnauthorizedCallContext++#++()++` [.item-kind]#error# + +The call is from an unauthorized context. + +[.contract-item] +[[UUPSUpgradeable-UUPSUnsupportedProxiableUUID-bytes32-]] +==== `[.contract-item-name]#++UUPSUnsupportedProxiableUUID++#++(bytes32 slot)++` [.item-kind]#error# + +The storage `slot` is unsupported as a UUID. + diff --git a/docs/modules/api/pages/token/ERC1155.adoc b/docs/modules/api/pages/token/ERC1155.adoc new file mode 100644 index 000000000..45a88cde3 --- /dev/null +++ b/docs/modules/api/pages/token/ERC1155.adoc @@ -0,0 +1,1496 @@ +:github-icon: pass:[] +:IERC1155: pass:normal[xref:token/ERC1155.adoc#IERC1155[`IERC1155`]] +:IERC1155MetadataURI: pass:normal[xref:token/ERC1155.adoc#IERC1155MetadataURI[`IERC1155MetadataURI`]] +:IERC1155Receiver: pass:normal[xref:token/ERC1155.adoc#IERC1155Receiver[`IERC1155Receiver`]] +:ERC1155: pass:normal[xref:token/ERC1155.adoc#ERC1155[`ERC1155`]] +:IERC1155: pass:normal[xref:token/ERC1155.adoc#IERC1155[`IERC1155`]] +:IERC1155MetadataURI: pass:normal[xref:token/ERC1155.adoc#IERC1155MetadataURI[`IERC1155MetadataURI`]] +:ERC1155Pausable: pass:normal[xref:token/ERC1155.adoc#ERC1155Pausable[`ERC1155Pausable`]] +:ERC1155Burnable: pass:normal[xref:token/ERC1155.adoc#ERC1155Burnable[`ERC1155Burnable`]] +:xref-IERC1155-balanceOf-address-uint256-: xref:token/ERC1155.adoc#IERC1155-balanceOf-address-uint256- +:xref-IERC1155-balanceOfBatch-address---uint256---: xref:token/ERC1155.adoc#IERC1155-balanceOfBatch-address---uint256--- +:xref-IERC1155-setApprovalForAll-address-bool-: xref:token/ERC1155.adoc#IERC1155-setApprovalForAll-address-bool- +:xref-IERC1155-isApprovedForAll-address-address-: xref:token/ERC1155.adoc#IERC1155-isApprovedForAll-address-address- +:xref-IERC1155-safeTransferFrom-address-address-uint256-uint256-bytes-: xref:token/ERC1155.adoc#IERC1155-safeTransferFrom-address-address-uint256-uint256-bytes- +:xref-IERC1155-safeBatchTransferFrom-address-address-uint256---uint256---bytes-: xref:token/ERC1155.adoc#IERC1155-safeBatchTransferFrom-address-address-uint256---uint256---bytes- +:xref-IERC165-supportsInterface-bytes4-: xref:utils.adoc#IERC165-supportsInterface-bytes4- +:xref-IERC1155-TransferSingle-address-address-address-uint256-uint256-: xref:token/ERC1155.adoc#IERC1155-TransferSingle-address-address-address-uint256-uint256- +:xref-IERC1155-TransferBatch-address-address-address-uint256---uint256---: xref:token/ERC1155.adoc#IERC1155-TransferBatch-address-address-address-uint256---uint256--- +:xref-IERC1155-ApprovalForAll-address-address-bool-: xref:token/ERC1155.adoc#IERC1155-ApprovalForAll-address-address-bool- +:xref-IERC1155-URI-string-uint256-: xref:token/ERC1155.adoc#IERC1155-URI-string-uint256- +:IERC1155Receiver-onERC1155Received: pass:normal[xref:token/ERC1155.adoc#IERC1155Receiver-onERC1155Received-address-address-uint256-uint256-bytes-[`IERC1155Receiver.onERC1155Received`]] +:IERC1155Receiver-onERC1155BatchReceived: pass:normal[xref:token/ERC1155.adoc#IERC1155Receiver-onERC1155BatchReceived-address-address-uint256---uint256---bytes-[`IERC1155Receiver.onERC1155BatchReceived`]] +:IERC1155MetadataURI-uri: pass:normal[xref:token/ERC1155.adoc#IERC1155MetadataURI-uri-uint256-[`IERC1155MetadataURI.uri`]] +:xref-IERC1155MetadataURI-uri-uint256-: xref:token/ERC1155.adoc#IERC1155MetadataURI-uri-uint256- +:xref-IERC1155-balanceOf-address-uint256-: xref:token/ERC1155.adoc#IERC1155-balanceOf-address-uint256- +:xref-IERC1155-balanceOfBatch-address---uint256---: xref:token/ERC1155.adoc#IERC1155-balanceOfBatch-address---uint256--- +:xref-IERC1155-setApprovalForAll-address-bool-: xref:token/ERC1155.adoc#IERC1155-setApprovalForAll-address-bool- +:xref-IERC1155-isApprovedForAll-address-address-: xref:token/ERC1155.adoc#IERC1155-isApprovedForAll-address-address- +:xref-IERC1155-safeTransferFrom-address-address-uint256-uint256-bytes-: xref:token/ERC1155.adoc#IERC1155-safeTransferFrom-address-address-uint256-uint256-bytes- +:xref-IERC1155-safeBatchTransferFrom-address-address-uint256---uint256---bytes-: xref:token/ERC1155.adoc#IERC1155-safeBatchTransferFrom-address-address-uint256---uint256---bytes- +:xref-IERC165-supportsInterface-bytes4-: xref:utils.adoc#IERC165-supportsInterface-bytes4- +:xref-IERC1155-TransferSingle-address-address-address-uint256-uint256-: xref:token/ERC1155.adoc#IERC1155-TransferSingle-address-address-address-uint256-uint256- +:xref-IERC1155-TransferBatch-address-address-address-uint256---uint256---: xref:token/ERC1155.adoc#IERC1155-TransferBatch-address-address-address-uint256---uint256--- +:xref-IERC1155-ApprovalForAll-address-address-bool-: xref:token/ERC1155.adoc#IERC1155-ApprovalForAll-address-address-bool- +:xref-IERC1155-URI-string-uint256-: xref:token/ERC1155.adoc#IERC1155-URI-string-uint256- +:xref-ERC1155-constructor-string-: xref:token/ERC1155.adoc#ERC1155-constructor-string- +:xref-ERC1155-supportsInterface-bytes4-: xref:token/ERC1155.adoc#ERC1155-supportsInterface-bytes4- +:xref-ERC1155-uri-uint256-: xref:token/ERC1155.adoc#ERC1155-uri-uint256- +:xref-ERC1155-balanceOf-address-uint256-: xref:token/ERC1155.adoc#ERC1155-balanceOf-address-uint256- +:xref-ERC1155-balanceOfBatch-address---uint256---: xref:token/ERC1155.adoc#ERC1155-balanceOfBatch-address---uint256--- +:xref-ERC1155-setApprovalForAll-address-bool-: xref:token/ERC1155.adoc#ERC1155-setApprovalForAll-address-bool- +:xref-ERC1155-isApprovedForAll-address-address-: xref:token/ERC1155.adoc#ERC1155-isApprovedForAll-address-address- +:xref-ERC1155-safeTransferFrom-address-address-uint256-uint256-bytes-: xref:token/ERC1155.adoc#ERC1155-safeTransferFrom-address-address-uint256-uint256-bytes- +:xref-ERC1155-safeBatchTransferFrom-address-address-uint256---uint256---bytes-: xref:token/ERC1155.adoc#ERC1155-safeBatchTransferFrom-address-address-uint256---uint256---bytes- +:xref-ERC1155-_update-address-address-uint256---uint256---: xref:token/ERC1155.adoc#ERC1155-_update-address-address-uint256---uint256--- +:xref-ERC1155-_updateWithAcceptanceCheck-address-address-uint256---uint256---bytes-: xref:token/ERC1155.adoc#ERC1155-_updateWithAcceptanceCheck-address-address-uint256---uint256---bytes- +:xref-ERC1155-_safeTransferFrom-address-address-uint256-uint256-bytes-: xref:token/ERC1155.adoc#ERC1155-_safeTransferFrom-address-address-uint256-uint256-bytes- +:xref-ERC1155-_safeBatchTransferFrom-address-address-uint256---uint256---bytes-: xref:token/ERC1155.adoc#ERC1155-_safeBatchTransferFrom-address-address-uint256---uint256---bytes- +:xref-ERC1155-_setURI-string-: xref:token/ERC1155.adoc#ERC1155-_setURI-string- +:xref-ERC1155-_mint-address-uint256-uint256-bytes-: xref:token/ERC1155.adoc#ERC1155-_mint-address-uint256-uint256-bytes- +:xref-ERC1155-_mintBatch-address-uint256---uint256---bytes-: xref:token/ERC1155.adoc#ERC1155-_mintBatch-address-uint256---uint256---bytes- +:xref-ERC1155-_burn-address-uint256-uint256-: xref:token/ERC1155.adoc#ERC1155-_burn-address-uint256-uint256- +:xref-ERC1155-_burnBatch-address-uint256---uint256---: xref:token/ERC1155.adoc#ERC1155-_burnBatch-address-uint256---uint256--- +:xref-ERC1155-_setApprovalForAll-address-address-bool-: xref:token/ERC1155.adoc#ERC1155-_setApprovalForAll-address-address-bool- +:xref-IERC1155-TransferSingle-address-address-address-uint256-uint256-: xref:token/ERC1155.adoc#IERC1155-TransferSingle-address-address-address-uint256-uint256- +:xref-IERC1155-TransferBatch-address-address-address-uint256---uint256---: xref:token/ERC1155.adoc#IERC1155-TransferBatch-address-address-address-uint256---uint256--- +:xref-IERC1155-ApprovalForAll-address-address-bool-: xref:token/ERC1155.adoc#IERC1155-ApprovalForAll-address-address-bool- +:xref-IERC1155-URI-string-uint256-: xref:token/ERC1155.adoc#IERC1155-URI-string-uint256- +:xref-IERC1155Errors-ERC1155InsufficientBalance-address-uint256-uint256-uint256-: xref:interfaces.adoc#IERC1155Errors-ERC1155InsufficientBalance-address-uint256-uint256-uint256- +:xref-IERC1155Errors-ERC1155InvalidSender-address-: xref:interfaces.adoc#IERC1155Errors-ERC1155InvalidSender-address- +:xref-IERC1155Errors-ERC1155InvalidReceiver-address-: xref:interfaces.adoc#IERC1155Errors-ERC1155InvalidReceiver-address- +:xref-IERC1155Errors-ERC1155MissingApprovalForAll-address-address-: xref:interfaces.adoc#IERC1155Errors-ERC1155MissingApprovalForAll-address-address- +:xref-IERC1155Errors-ERC1155InvalidApprover-address-: xref:interfaces.adoc#IERC1155Errors-ERC1155InvalidApprover-address- +:xref-IERC1155Errors-ERC1155InvalidOperator-address-: xref:interfaces.adoc#IERC1155Errors-ERC1155InvalidOperator-address- +:xref-IERC1155Errors-ERC1155InvalidArrayLength-uint256-uint256-: xref:interfaces.adoc#IERC1155Errors-ERC1155InvalidArrayLength-uint256-uint256- +:IERC165-supportsInterface: pass:normal[xref:utils.adoc#IERC165-supportsInterface-bytes4-[`IERC165.supportsInterface`]] +:IERC1155MetadataURI-uri: pass:normal[xref:token/ERC1155.adoc#IERC1155MetadataURI-uri-uint256-[`IERC1155MetadataURI.uri`]] +:IERC1155-balanceOf: pass:normal[xref:token/ERC1155.adoc#IERC1155-balanceOf-address-uint256-[`IERC1155.balanceOf`]] +:IERC1155-balanceOfBatch: pass:normal[xref:token/ERC1155.adoc#IERC1155-balanceOfBatch-address---uint256---[`IERC1155.balanceOfBatch`]] +:IERC1155-setApprovalForAll: pass:normal[xref:token/ERC1155.adoc#IERC1155-setApprovalForAll-address-bool-[`IERC1155.setApprovalForAll`]] +:IERC1155-isApprovedForAll: pass:normal[xref:token/ERC1155.adoc#IERC1155-isApprovedForAll-address-address-[`IERC1155.isApprovedForAll`]] +:IERC1155-safeTransferFrom: pass:normal[xref:token/ERC1155.adoc#IERC1155-safeTransferFrom-address-address-uint256-uint256-bytes-[`IERC1155.safeTransferFrom`]] +:IERC1155-safeBatchTransferFrom: pass:normal[xref:token/ERC1155.adoc#IERC1155-safeBatchTransferFrom-address-address-uint256---uint256---bytes-[`IERC1155.safeBatchTransferFrom`]] +:IERC1155Receiver-onERC1155Received: pass:normal[xref:token/ERC1155.adoc#IERC1155Receiver-onERC1155Received-address-address-uint256-uint256-bytes-[`IERC1155Receiver.onERC1155Received`]] +:IERC1155Receiver-onERC1155BatchReceived: pass:normal[xref:token/ERC1155.adoc#IERC1155Receiver-onERC1155BatchReceived-address-address-uint256---uint256---bytes-[`IERC1155Receiver.onERC1155BatchReceived`]] +:IERC1155Receiver-onERC1155Received: pass:normal[xref:token/ERC1155.adoc#IERC1155Receiver-onERC1155Received-address-address-uint256-uint256-bytes-[`IERC1155Receiver.onERC1155Received`]] +:IERC1155Receiver-onERC1155BatchReceived: pass:normal[xref:token/ERC1155.adoc#IERC1155Receiver-onERC1155BatchReceived-address-address-uint256---uint256---bytes-[`IERC1155Receiver.onERC1155BatchReceived`]] +:IERC1155Receiver-onERC1155Received: pass:normal[xref:token/ERC1155.adoc#IERC1155Receiver-onERC1155Received-address-address-uint256-uint256-bytes-[`IERC1155Receiver.onERC1155Received`]] +:IERC1155Receiver-onERC1155BatchReceived: pass:normal[xref:token/ERC1155.adoc#IERC1155Receiver-onERC1155BatchReceived-address-address-uint256---uint256---bytes-[`IERC1155Receiver.onERC1155BatchReceived`]] +:IERC1155Receiver-onERC1155Received: pass:normal[xref:token/ERC1155.adoc#IERC1155Receiver-onERC1155Received-address-address-uint256-uint256-bytes-[`IERC1155Receiver.onERC1155Received`]] +:IERC1155Receiver-onERC1155BatchReceived: pass:normal[xref:token/ERC1155.adoc#IERC1155Receiver-onERC1155BatchReceived-address-address-uint256---uint256---bytes-[`IERC1155Receiver.onERC1155BatchReceived`]] +:xref-IERC1155Receiver-onERC1155Received-address-address-uint256-uint256-bytes-: xref:token/ERC1155.adoc#IERC1155Receiver-onERC1155Received-address-address-uint256-uint256-bytes- +:xref-IERC1155Receiver-onERC1155BatchReceived-address-address-uint256---uint256---bytes-: xref:token/ERC1155.adoc#IERC1155Receiver-onERC1155BatchReceived-address-address-uint256---uint256---bytes- +:xref-IERC165-supportsInterface-bytes4-: xref:utils.adoc#IERC165-supportsInterface-bytes4- +:Pausable-_pause: pass:normal[xref:utils.adoc#Pausable-_pause--[`Pausable._pause`]] +:Pausable-_unpause: pass:normal[xref:utils.adoc#Pausable-_unpause--[`Pausable._unpause`]] +:AccessControl: pass:normal[xref:access.adoc#AccessControl[`AccessControl`]] +:Ownable: pass:normal[xref:access.adoc#Ownable[`Ownable`]] +:xref-ERC1155Pausable-_update-address-address-uint256---uint256---: xref:token/ERC1155.adoc#ERC1155Pausable-_update-address-address-uint256---uint256--- +:xref-Pausable-paused--: xref:utils.adoc#Pausable-paused-- +:xref-Pausable-_requireNotPaused--: xref:utils.adoc#Pausable-_requireNotPaused-- +:xref-Pausable-_requirePaused--: xref:utils.adoc#Pausable-_requirePaused-- +:xref-Pausable-_pause--: xref:utils.adoc#Pausable-_pause-- +:xref-Pausable-_unpause--: xref:utils.adoc#Pausable-_unpause-- +:xref-ERC1155-supportsInterface-bytes4-: xref:token/ERC1155.adoc#ERC1155-supportsInterface-bytes4- +:xref-ERC1155-uri-uint256-: xref:token/ERC1155.adoc#ERC1155-uri-uint256- +:xref-ERC1155-balanceOf-address-uint256-: xref:token/ERC1155.adoc#ERC1155-balanceOf-address-uint256- +:xref-ERC1155-balanceOfBatch-address---uint256---: xref:token/ERC1155.adoc#ERC1155-balanceOfBatch-address---uint256--- +:xref-ERC1155-setApprovalForAll-address-bool-: xref:token/ERC1155.adoc#ERC1155-setApprovalForAll-address-bool- +:xref-ERC1155-isApprovedForAll-address-address-: xref:token/ERC1155.adoc#ERC1155-isApprovedForAll-address-address- +:xref-ERC1155-safeTransferFrom-address-address-uint256-uint256-bytes-: xref:token/ERC1155.adoc#ERC1155-safeTransferFrom-address-address-uint256-uint256-bytes- +:xref-ERC1155-safeBatchTransferFrom-address-address-uint256---uint256---bytes-: xref:token/ERC1155.adoc#ERC1155-safeBatchTransferFrom-address-address-uint256---uint256---bytes- +:xref-ERC1155-_updateWithAcceptanceCheck-address-address-uint256---uint256---bytes-: xref:token/ERC1155.adoc#ERC1155-_updateWithAcceptanceCheck-address-address-uint256---uint256---bytes- +:xref-ERC1155-_safeTransferFrom-address-address-uint256-uint256-bytes-: xref:token/ERC1155.adoc#ERC1155-_safeTransferFrom-address-address-uint256-uint256-bytes- +:xref-ERC1155-_safeBatchTransferFrom-address-address-uint256---uint256---bytes-: xref:token/ERC1155.adoc#ERC1155-_safeBatchTransferFrom-address-address-uint256---uint256---bytes- +:xref-ERC1155-_setURI-string-: xref:token/ERC1155.adoc#ERC1155-_setURI-string- +:xref-ERC1155-_mint-address-uint256-uint256-bytes-: xref:token/ERC1155.adoc#ERC1155-_mint-address-uint256-uint256-bytes- +:xref-ERC1155-_mintBatch-address-uint256---uint256---bytes-: xref:token/ERC1155.adoc#ERC1155-_mintBatch-address-uint256---uint256---bytes- +:xref-ERC1155-_burn-address-uint256-uint256-: xref:token/ERC1155.adoc#ERC1155-_burn-address-uint256-uint256- +:xref-ERC1155-_burnBatch-address-uint256---uint256---: xref:token/ERC1155.adoc#ERC1155-_burnBatch-address-uint256---uint256--- +:xref-ERC1155-_setApprovalForAll-address-address-bool-: xref:token/ERC1155.adoc#ERC1155-_setApprovalForAll-address-address-bool- +:xref-Pausable-Paused-address-: xref:utils.adoc#Pausable-Paused-address- +:xref-Pausable-Unpaused-address-: xref:utils.adoc#Pausable-Unpaused-address- +:xref-IERC1155-TransferSingle-address-address-address-uint256-uint256-: xref:token/ERC1155.adoc#IERC1155-TransferSingle-address-address-address-uint256-uint256- +:xref-IERC1155-TransferBatch-address-address-address-uint256---uint256---: xref:token/ERC1155.adoc#IERC1155-TransferBatch-address-address-address-uint256---uint256--- +:xref-IERC1155-ApprovalForAll-address-address-bool-: xref:token/ERC1155.adoc#IERC1155-ApprovalForAll-address-address-bool- +:xref-IERC1155-URI-string-uint256-: xref:token/ERC1155.adoc#IERC1155-URI-string-uint256- +:xref-Pausable-EnforcedPause--: xref:utils.adoc#Pausable-EnforcedPause-- +:xref-Pausable-ExpectedPause--: xref:utils.adoc#Pausable-ExpectedPause-- +:xref-IERC1155Errors-ERC1155InsufficientBalance-address-uint256-uint256-uint256-: xref:interfaces.adoc#IERC1155Errors-ERC1155InsufficientBalance-address-uint256-uint256-uint256- +:xref-IERC1155Errors-ERC1155InvalidSender-address-: xref:interfaces.adoc#IERC1155Errors-ERC1155InvalidSender-address- +:xref-IERC1155Errors-ERC1155InvalidReceiver-address-: xref:interfaces.adoc#IERC1155Errors-ERC1155InvalidReceiver-address- +:xref-IERC1155Errors-ERC1155MissingApprovalForAll-address-address-: xref:interfaces.adoc#IERC1155Errors-ERC1155MissingApprovalForAll-address-address- +:xref-IERC1155Errors-ERC1155InvalidApprover-address-: xref:interfaces.adoc#IERC1155Errors-ERC1155InvalidApprover-address- +:xref-IERC1155Errors-ERC1155InvalidOperator-address-: xref:interfaces.adoc#IERC1155Errors-ERC1155InvalidOperator-address- +:xref-IERC1155Errors-ERC1155InvalidArrayLength-uint256-uint256-: xref:interfaces.adoc#IERC1155Errors-ERC1155InvalidArrayLength-uint256-uint256- +:ERC1155-_update: pass:normal[xref:token/ERC1155.adoc#ERC1155-_update-address-address-uint256---uint256---[`ERC1155._update`]] +:ERC1155: pass:normal[xref:token/ERC1155.adoc#ERC1155[`ERC1155`]] +:xref-ERC1155Burnable-burn-address-uint256-uint256-: xref:token/ERC1155.adoc#ERC1155Burnable-burn-address-uint256-uint256- +:xref-ERC1155Burnable-burnBatch-address-uint256---uint256---: xref:token/ERC1155.adoc#ERC1155Burnable-burnBatch-address-uint256---uint256--- +:xref-ERC1155-supportsInterface-bytes4-: xref:token/ERC1155.adoc#ERC1155-supportsInterface-bytes4- +:xref-ERC1155-uri-uint256-: xref:token/ERC1155.adoc#ERC1155-uri-uint256- +:xref-ERC1155-balanceOf-address-uint256-: xref:token/ERC1155.adoc#ERC1155-balanceOf-address-uint256- +:xref-ERC1155-balanceOfBatch-address---uint256---: xref:token/ERC1155.adoc#ERC1155-balanceOfBatch-address---uint256--- +:xref-ERC1155-setApprovalForAll-address-bool-: xref:token/ERC1155.adoc#ERC1155-setApprovalForAll-address-bool- +:xref-ERC1155-isApprovedForAll-address-address-: xref:token/ERC1155.adoc#ERC1155-isApprovedForAll-address-address- +:xref-ERC1155-safeTransferFrom-address-address-uint256-uint256-bytes-: xref:token/ERC1155.adoc#ERC1155-safeTransferFrom-address-address-uint256-uint256-bytes- +:xref-ERC1155-safeBatchTransferFrom-address-address-uint256---uint256---bytes-: xref:token/ERC1155.adoc#ERC1155-safeBatchTransferFrom-address-address-uint256---uint256---bytes- +:xref-ERC1155-_update-address-address-uint256---uint256---: xref:token/ERC1155.adoc#ERC1155-_update-address-address-uint256---uint256--- +:xref-ERC1155-_updateWithAcceptanceCheck-address-address-uint256---uint256---bytes-: xref:token/ERC1155.adoc#ERC1155-_updateWithAcceptanceCheck-address-address-uint256---uint256---bytes- +:xref-ERC1155-_safeTransferFrom-address-address-uint256-uint256-bytes-: xref:token/ERC1155.adoc#ERC1155-_safeTransferFrom-address-address-uint256-uint256-bytes- +:xref-ERC1155-_safeBatchTransferFrom-address-address-uint256---uint256---bytes-: xref:token/ERC1155.adoc#ERC1155-_safeBatchTransferFrom-address-address-uint256---uint256---bytes- +:xref-ERC1155-_setURI-string-: xref:token/ERC1155.adoc#ERC1155-_setURI-string- +:xref-ERC1155-_mint-address-uint256-uint256-bytes-: xref:token/ERC1155.adoc#ERC1155-_mint-address-uint256-uint256-bytes- +:xref-ERC1155-_mintBatch-address-uint256---uint256---bytes-: xref:token/ERC1155.adoc#ERC1155-_mintBatch-address-uint256---uint256---bytes- +:xref-ERC1155-_burn-address-uint256-uint256-: xref:token/ERC1155.adoc#ERC1155-_burn-address-uint256-uint256- +:xref-ERC1155-_burnBatch-address-uint256---uint256---: xref:token/ERC1155.adoc#ERC1155-_burnBatch-address-uint256---uint256--- +:xref-ERC1155-_setApprovalForAll-address-address-bool-: xref:token/ERC1155.adoc#ERC1155-_setApprovalForAll-address-address-bool- +:xref-IERC1155-TransferSingle-address-address-address-uint256-uint256-: xref:token/ERC1155.adoc#IERC1155-TransferSingle-address-address-address-uint256-uint256- +:xref-IERC1155-TransferBatch-address-address-address-uint256---uint256---: xref:token/ERC1155.adoc#IERC1155-TransferBatch-address-address-address-uint256---uint256--- +:xref-IERC1155-ApprovalForAll-address-address-bool-: xref:token/ERC1155.adoc#IERC1155-ApprovalForAll-address-address-bool- +:xref-IERC1155-URI-string-uint256-: xref:token/ERC1155.adoc#IERC1155-URI-string-uint256- +:xref-IERC1155Errors-ERC1155InsufficientBalance-address-uint256-uint256-uint256-: xref:interfaces.adoc#IERC1155Errors-ERC1155InsufficientBalance-address-uint256-uint256-uint256- +:xref-IERC1155Errors-ERC1155InvalidSender-address-: xref:interfaces.adoc#IERC1155Errors-ERC1155InvalidSender-address- +:xref-IERC1155Errors-ERC1155InvalidReceiver-address-: xref:interfaces.adoc#IERC1155Errors-ERC1155InvalidReceiver-address- +:xref-IERC1155Errors-ERC1155MissingApprovalForAll-address-address-: xref:interfaces.adoc#IERC1155Errors-ERC1155MissingApprovalForAll-address-address- +:xref-IERC1155Errors-ERC1155InvalidApprover-address-: xref:interfaces.adoc#IERC1155Errors-ERC1155InvalidApprover-address- +:xref-IERC1155Errors-ERC1155InvalidOperator-address-: xref:interfaces.adoc#IERC1155Errors-ERC1155InvalidOperator-address- +:xref-IERC1155Errors-ERC1155InvalidArrayLength-uint256-uint256-: xref:interfaces.adoc#IERC1155Errors-ERC1155InvalidArrayLength-uint256-uint256- +:xref-ERC1155Supply-totalSupply-uint256-: xref:token/ERC1155.adoc#ERC1155Supply-totalSupply-uint256- +:xref-ERC1155Supply-totalSupply--: xref:token/ERC1155.adoc#ERC1155Supply-totalSupply-- +:xref-ERC1155Supply-exists-uint256-: xref:token/ERC1155.adoc#ERC1155Supply-exists-uint256- +:xref-ERC1155Supply-_update-address-address-uint256---uint256---: xref:token/ERC1155.adoc#ERC1155Supply-_update-address-address-uint256---uint256--- +:xref-ERC1155-supportsInterface-bytes4-: xref:token/ERC1155.adoc#ERC1155-supportsInterface-bytes4- +:xref-ERC1155-uri-uint256-: xref:token/ERC1155.adoc#ERC1155-uri-uint256- +:xref-ERC1155-balanceOf-address-uint256-: xref:token/ERC1155.adoc#ERC1155-balanceOf-address-uint256- +:xref-ERC1155-balanceOfBatch-address---uint256---: xref:token/ERC1155.adoc#ERC1155-balanceOfBatch-address---uint256--- +:xref-ERC1155-setApprovalForAll-address-bool-: xref:token/ERC1155.adoc#ERC1155-setApprovalForAll-address-bool- +:xref-ERC1155-isApprovedForAll-address-address-: xref:token/ERC1155.adoc#ERC1155-isApprovedForAll-address-address- +:xref-ERC1155-safeTransferFrom-address-address-uint256-uint256-bytes-: xref:token/ERC1155.adoc#ERC1155-safeTransferFrom-address-address-uint256-uint256-bytes- +:xref-ERC1155-safeBatchTransferFrom-address-address-uint256---uint256---bytes-: xref:token/ERC1155.adoc#ERC1155-safeBatchTransferFrom-address-address-uint256---uint256---bytes- +:xref-ERC1155-_updateWithAcceptanceCheck-address-address-uint256---uint256---bytes-: xref:token/ERC1155.adoc#ERC1155-_updateWithAcceptanceCheck-address-address-uint256---uint256---bytes- +:xref-ERC1155-_safeTransferFrom-address-address-uint256-uint256-bytes-: xref:token/ERC1155.adoc#ERC1155-_safeTransferFrom-address-address-uint256-uint256-bytes- +:xref-ERC1155-_safeBatchTransferFrom-address-address-uint256---uint256---bytes-: xref:token/ERC1155.adoc#ERC1155-_safeBatchTransferFrom-address-address-uint256---uint256---bytes- +:xref-ERC1155-_setURI-string-: xref:token/ERC1155.adoc#ERC1155-_setURI-string- +:xref-ERC1155-_mint-address-uint256-uint256-bytes-: xref:token/ERC1155.adoc#ERC1155-_mint-address-uint256-uint256-bytes- +:xref-ERC1155-_mintBatch-address-uint256---uint256---bytes-: xref:token/ERC1155.adoc#ERC1155-_mintBatch-address-uint256---uint256---bytes- +:xref-ERC1155-_burn-address-uint256-uint256-: xref:token/ERC1155.adoc#ERC1155-_burn-address-uint256-uint256- +:xref-ERC1155-_burnBatch-address-uint256---uint256---: xref:token/ERC1155.adoc#ERC1155-_burnBatch-address-uint256---uint256--- +:xref-ERC1155-_setApprovalForAll-address-address-bool-: xref:token/ERC1155.adoc#ERC1155-_setApprovalForAll-address-address-bool- +:xref-IERC1155-TransferSingle-address-address-address-uint256-uint256-: xref:token/ERC1155.adoc#IERC1155-TransferSingle-address-address-address-uint256-uint256- +:xref-IERC1155-TransferBatch-address-address-address-uint256---uint256---: xref:token/ERC1155.adoc#IERC1155-TransferBatch-address-address-address-uint256---uint256--- +:xref-IERC1155-ApprovalForAll-address-address-bool-: xref:token/ERC1155.adoc#IERC1155-ApprovalForAll-address-address-bool- +:xref-IERC1155-URI-string-uint256-: xref:token/ERC1155.adoc#IERC1155-URI-string-uint256- +:xref-IERC1155Errors-ERC1155InsufficientBalance-address-uint256-uint256-uint256-: xref:interfaces.adoc#IERC1155Errors-ERC1155InsufficientBalance-address-uint256-uint256-uint256- +:xref-IERC1155Errors-ERC1155InvalidSender-address-: xref:interfaces.adoc#IERC1155Errors-ERC1155InvalidSender-address- +:xref-IERC1155Errors-ERC1155InvalidReceiver-address-: xref:interfaces.adoc#IERC1155Errors-ERC1155InvalidReceiver-address- +:xref-IERC1155Errors-ERC1155MissingApprovalForAll-address-address-: xref:interfaces.adoc#IERC1155Errors-ERC1155MissingApprovalForAll-address-address- +:xref-IERC1155Errors-ERC1155InvalidApprover-address-: xref:interfaces.adoc#IERC1155Errors-ERC1155InvalidApprover-address- +:xref-IERC1155Errors-ERC1155InvalidOperator-address-: xref:interfaces.adoc#IERC1155Errors-ERC1155InvalidOperator-address- +:xref-IERC1155Errors-ERC1155InvalidArrayLength-uint256-uint256-: xref:interfaces.adoc#IERC1155Errors-ERC1155InvalidArrayLength-uint256-uint256- +:ERC1155-_update: pass:normal[xref:token/ERC1155.adoc#ERC1155-_update-address-address-uint256---uint256---[`ERC1155._update`]] +:xref-ERC1155URIStorage-uri-uint256-: xref:token/ERC1155.adoc#ERC1155URIStorage-uri-uint256- +:xref-ERC1155URIStorage-_setURI-uint256-string-: xref:token/ERC1155.adoc#ERC1155URIStorage-_setURI-uint256-string- +:xref-ERC1155URIStorage-_setBaseURI-string-: xref:token/ERC1155.adoc#ERC1155URIStorage-_setBaseURI-string- +:xref-ERC1155-supportsInterface-bytes4-: xref:token/ERC1155.adoc#ERC1155-supportsInterface-bytes4- +:xref-ERC1155-balanceOf-address-uint256-: xref:token/ERC1155.adoc#ERC1155-balanceOf-address-uint256- +:xref-ERC1155-balanceOfBatch-address---uint256---: xref:token/ERC1155.adoc#ERC1155-balanceOfBatch-address---uint256--- +:xref-ERC1155-setApprovalForAll-address-bool-: xref:token/ERC1155.adoc#ERC1155-setApprovalForAll-address-bool- +:xref-ERC1155-isApprovedForAll-address-address-: xref:token/ERC1155.adoc#ERC1155-isApprovedForAll-address-address- +:xref-ERC1155-safeTransferFrom-address-address-uint256-uint256-bytes-: xref:token/ERC1155.adoc#ERC1155-safeTransferFrom-address-address-uint256-uint256-bytes- +:xref-ERC1155-safeBatchTransferFrom-address-address-uint256---uint256---bytes-: xref:token/ERC1155.adoc#ERC1155-safeBatchTransferFrom-address-address-uint256---uint256---bytes- +:xref-ERC1155-_update-address-address-uint256---uint256---: xref:token/ERC1155.adoc#ERC1155-_update-address-address-uint256---uint256--- +:xref-ERC1155-_updateWithAcceptanceCheck-address-address-uint256---uint256---bytes-: xref:token/ERC1155.adoc#ERC1155-_updateWithAcceptanceCheck-address-address-uint256---uint256---bytes- +:xref-ERC1155-_safeTransferFrom-address-address-uint256-uint256-bytes-: xref:token/ERC1155.adoc#ERC1155-_safeTransferFrom-address-address-uint256-uint256-bytes- +:xref-ERC1155-_safeBatchTransferFrom-address-address-uint256---uint256---bytes-: xref:token/ERC1155.adoc#ERC1155-_safeBatchTransferFrom-address-address-uint256---uint256---bytes- +:xref-ERC1155-_setURI-string-: xref:token/ERC1155.adoc#ERC1155-_setURI-string- +:xref-ERC1155-_mint-address-uint256-uint256-bytes-: xref:token/ERC1155.adoc#ERC1155-_mint-address-uint256-uint256-bytes- +:xref-ERC1155-_mintBatch-address-uint256---uint256---bytes-: xref:token/ERC1155.adoc#ERC1155-_mintBatch-address-uint256---uint256---bytes- +:xref-ERC1155-_burn-address-uint256-uint256-: xref:token/ERC1155.adoc#ERC1155-_burn-address-uint256-uint256- +:xref-ERC1155-_burnBatch-address-uint256---uint256---: xref:token/ERC1155.adoc#ERC1155-_burnBatch-address-uint256---uint256--- +:xref-ERC1155-_setApprovalForAll-address-address-bool-: xref:token/ERC1155.adoc#ERC1155-_setApprovalForAll-address-address-bool- +:xref-IERC1155-TransferSingle-address-address-address-uint256-uint256-: xref:token/ERC1155.adoc#IERC1155-TransferSingle-address-address-address-uint256-uint256- +:xref-IERC1155-TransferBatch-address-address-address-uint256---uint256---: xref:token/ERC1155.adoc#IERC1155-TransferBatch-address-address-address-uint256---uint256--- +:xref-IERC1155-ApprovalForAll-address-address-bool-: xref:token/ERC1155.adoc#IERC1155-ApprovalForAll-address-address-bool- +:xref-IERC1155-URI-string-uint256-: xref:token/ERC1155.adoc#IERC1155-URI-string-uint256- +:xref-IERC1155Errors-ERC1155InsufficientBalance-address-uint256-uint256-uint256-: xref:interfaces.adoc#IERC1155Errors-ERC1155InsufficientBalance-address-uint256-uint256-uint256- +:xref-IERC1155Errors-ERC1155InvalidSender-address-: xref:interfaces.adoc#IERC1155Errors-ERC1155InvalidSender-address- +:xref-IERC1155Errors-ERC1155InvalidReceiver-address-: xref:interfaces.adoc#IERC1155Errors-ERC1155InvalidReceiver-address- +:xref-IERC1155Errors-ERC1155MissingApprovalForAll-address-address-: xref:interfaces.adoc#IERC1155Errors-ERC1155MissingApprovalForAll-address-address- +:xref-IERC1155Errors-ERC1155InvalidApprover-address-: xref:interfaces.adoc#IERC1155Errors-ERC1155InvalidApprover-address- +:xref-IERC1155Errors-ERC1155InvalidOperator-address-: xref:interfaces.adoc#IERC1155Errors-ERC1155InvalidOperator-address- +:xref-IERC1155Errors-ERC1155InvalidArrayLength-uint256-uint256-: xref:interfaces.adoc#IERC1155Errors-ERC1155InvalidArrayLength-uint256-uint256- +:IERC1155MetadataURI-uri: pass:normal[xref:token/ERC1155.adoc#IERC1155MetadataURI-uri-uint256-[`IERC1155MetadataURI.uri`]] +:xref-ERC1155Holder-supportsInterface-bytes4-: xref:token/ERC1155.adoc#ERC1155Holder-supportsInterface-bytes4- +:xref-ERC1155Holder-onERC1155Received-address-address-uint256-uint256-bytes-: xref:token/ERC1155.adoc#ERC1155Holder-onERC1155Received-address-address-uint256-uint256-bytes- +:xref-ERC1155Holder-onERC1155BatchReceived-address-address-uint256---uint256---bytes-: xref:token/ERC1155.adoc#ERC1155Holder-onERC1155BatchReceived-address-address-uint256---uint256---bytes- +:IERC165-supportsInterface: pass:normal[xref:utils.adoc#IERC165-supportsInterface-bytes4-[`IERC165.supportsInterface`]] += ERC 1155 + +[.readme-notice] +NOTE: This document is better viewed at https://docs.openzeppelin.com/contracts/api/token/erc1155 + +This set of interfaces and contracts are all related to the https://eips.ethereum.org/EIPS/eip-1155[ERC1155 Multi Token Standard]. + +The EIP consists of three interfaces which fulfill different roles, found here as {IERC1155}, {IERC1155MetadataURI} and {IERC1155Receiver}. + +{ERC1155} implements the mandatory {IERC1155} interface, as well as the optional extension {IERC1155MetadataURI}, by relying on the substitution mechanism to use the same URI for all token types, dramatically reducing gas costs. + +Additionally there are multiple custom extensions, including: + +* designation of addresses that can pause token transfers for all users ({ERC1155Pausable}). +* destruction of own tokens ({ERC1155Burnable}). + +NOTE: This core set of contracts is designed to be unopinionated, allowing developers to access the internal functions in ERC1155 (such as <>) and expose them as external functions in the way they prefer. + +== Core + +:TransferSingle: pass:normal[xref:#IERC1155-TransferSingle-address-address-address-uint256-uint256-[`++TransferSingle++`]] +:TransferBatch: pass:normal[xref:#IERC1155-TransferBatch-address-address-address-uint256---uint256---[`++TransferBatch++`]] +:ApprovalForAll: pass:normal[xref:#IERC1155-ApprovalForAll-address-address-bool-[`++ApprovalForAll++`]] +:URI: pass:normal[xref:#IERC1155-URI-string-uint256-[`++URI++`]] +:balanceOf: pass:normal[xref:#IERC1155-balanceOf-address-uint256-[`++balanceOf++`]] +:balanceOfBatch: pass:normal[xref:#IERC1155-balanceOfBatch-address---uint256---[`++balanceOfBatch++`]] +:setApprovalForAll: pass:normal[xref:#IERC1155-setApprovalForAll-address-bool-[`++setApprovalForAll++`]] +:isApprovedForAll: pass:normal[xref:#IERC1155-isApprovedForAll-address-address-[`++isApprovedForAll++`]] +:safeTransferFrom: pass:normal[xref:#IERC1155-safeTransferFrom-address-address-uint256-uint256-bytes-[`++safeTransferFrom++`]] +:safeBatchTransferFrom: pass:normal[xref:#IERC1155-safeBatchTransferFrom-address-address-uint256---uint256---bytes-[`++safeBatchTransferFrom++`]] + +[.contract] +[[IERC1155]] +=== `++IERC1155++` link:https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v5.0.0-rc.0/contracts/token/ERC1155/IERC1155.sol[{github-icon},role=heading-link] + +[.hljs-theme-light.nopadding] +```solidity +import "@openzeppelin/contracts/token/ERC1155/IERC1155.sol"; +``` + +Required interface of an ERC1155 compliant contract, as defined in the +https://eips.ethereum.org/EIPS/eip-1155[EIP]. + +[.contract-index] +.Functions +-- +* {xref-IERC1155-balanceOf-address-uint256-}[`++balanceOf(account, id)++`] +* {xref-IERC1155-balanceOfBatch-address---uint256---}[`++balanceOfBatch(accounts, ids)++`] +* {xref-IERC1155-setApprovalForAll-address-bool-}[`++setApprovalForAll(operator, approved)++`] +* {xref-IERC1155-isApprovedForAll-address-address-}[`++isApprovedForAll(account, operator)++`] +* {xref-IERC1155-safeTransferFrom-address-address-uint256-uint256-bytes-}[`++safeTransferFrom(from, to, id, value, data)++`] +* {xref-IERC1155-safeBatchTransferFrom-address-address-uint256---uint256---bytes-}[`++safeBatchTransferFrom(from, to, ids, values, data)++`] + +[.contract-subindex-inherited] +.IERC165 +* {xref-IERC165-supportsInterface-bytes4-}[`++supportsInterface(interfaceId)++`] + +-- + +[.contract-index] +.Events +-- +* {xref-IERC1155-TransferSingle-address-address-address-uint256-uint256-}[`++TransferSingle(operator, from, to, id, value)++`] +* {xref-IERC1155-TransferBatch-address-address-address-uint256---uint256---}[`++TransferBatch(operator, from, to, ids, values)++`] +* {xref-IERC1155-ApprovalForAll-address-address-bool-}[`++ApprovalForAll(account, operator, approved)++`] +* {xref-IERC1155-URI-string-uint256-}[`++URI(value, id)++`] + +[.contract-subindex-inherited] +.IERC165 + +-- + +[.contract-item] +[[IERC1155-balanceOf-address-uint256-]] +==== `[.contract-item-name]#++balanceOf++#++(address account, uint256 id) → uint256++` [.item-kind]#external# + +Returns the value of tokens of token type `id` owned by `account`. + +Requirements: + +- `account` cannot be the zero address. + +[.contract-item] +[[IERC1155-balanceOfBatch-address---uint256---]] +==== `[.contract-item-name]#++balanceOfBatch++#++(address[] accounts, uint256[] ids) → uint256[]++` [.item-kind]#external# + +xref:ROOT:erc1155.adoc#batch-operations[Batched] version of {balanceOf}. + +Requirements: + +- `accounts` and `ids` must have the same length. + +[.contract-item] +[[IERC1155-setApprovalForAll-address-bool-]] +==== `[.contract-item-name]#++setApprovalForAll++#++(address operator, bool approved)++` [.item-kind]#external# + +Grants or revokes permission to `operator` to transfer the caller's tokens, according to `approved`, + +Emits an {ApprovalForAll} event. + +Requirements: + +- `operator` cannot be the caller. + +[.contract-item] +[[IERC1155-isApprovedForAll-address-address-]] +==== `[.contract-item-name]#++isApprovedForAll++#++(address account, address operator) → bool++` [.item-kind]#external# + +Returns true if `operator` is approved to transfer ``account``'s tokens. + +See {setApprovalForAll}. + +[.contract-item] +[[IERC1155-safeTransferFrom-address-address-uint256-uint256-bytes-]] +==== `[.contract-item-name]#++safeTransferFrom++#++(address from, address to, uint256 id, uint256 value, bytes data)++` [.item-kind]#external# + +Transfers a `value` amount of tokens of type `id` from `from` to `to`. + +WARNING: This function can potentially allow a reentrancy attack when transferring tokens +to an untrusted contract, when invoking {onERC1155Received} on the receiver. +Ensure to follow the checks-effects-interactions pattern and consider employing +reentrancy guards when interacting with untrusted contracts. + +Emits a {TransferSingle} event. + +Requirements: + +- `to` cannot be the zero address. +- If the caller is not `from`, it must have been approved to spend ``from``'s tokens via {setApprovalForAll}. +- `from` must have a balance of tokens of type `id` of at least `value` amount. +- If `to` refers to a smart contract, it must implement {IERC1155Receiver-onERC1155Received} and return the +acceptance magic value. + +[.contract-item] +[[IERC1155-safeBatchTransferFrom-address-address-uint256---uint256---bytes-]] +==== `[.contract-item-name]#++safeBatchTransferFrom++#++(address from, address to, uint256[] ids, uint256[] values, bytes data)++` [.item-kind]#external# + +xref:ROOT:erc1155.adoc#batch-operations[Batched] version of {safeTransferFrom}. + +WARNING: This function can potentially allow a reentrancy attack when transferring tokens +to an untrusted contract, when invoking {onERC1155BatchReceived} on the receiver. +Ensure to follow the checks-effects-interactions pattern and consider employing +reentrancy guards when interacting with untrusted contracts. + +Emits a {TransferBatch} event. + +Requirements: + +- `ids` and `values` must have the same length. +- If `to` refers to a smart contract, it must implement {IERC1155Receiver-onERC1155BatchReceived} and return the +acceptance magic value. + +[.contract-item] +[[IERC1155-TransferSingle-address-address-address-uint256-uint256-]] +==== `[.contract-item-name]#++TransferSingle++#++(address indexed operator, address indexed from, address indexed to, uint256 id, uint256 value)++` [.item-kind]#event# + +Emitted when `value` amount of tokens of type `id` are transferred from `from` to `to` by `operator`. + +[.contract-item] +[[IERC1155-TransferBatch-address-address-address-uint256---uint256---]] +==== `[.contract-item-name]#++TransferBatch++#++(address indexed operator, address indexed from, address indexed to, uint256[] ids, uint256[] values)++` [.item-kind]#event# + +Equivalent to multiple {TransferSingle} events, where `operator`, `from` and `to` are the same for all +transfers. + +[.contract-item] +[[IERC1155-ApprovalForAll-address-address-bool-]] +==== `[.contract-item-name]#++ApprovalForAll++#++(address indexed account, address indexed operator, bool approved)++` [.item-kind]#event# + +Emitted when `account` grants or revokes permission to `operator` to transfer their tokens, according to +`approved`. + +[.contract-item] +[[IERC1155-URI-string-uint256-]] +==== `[.contract-item-name]#++URI++#++(string value, uint256 indexed id)++` [.item-kind]#event# + +Emitted when the URI for token type `id` changes to `value`, if it is a non-programmatic URI. + +If an {URI} event was emitted for `id`, the standard +https://eips.ethereum.org/EIPS/eip-1155#metadata-extensions[guarantees] that `value` will equal the value +returned by {IERC1155MetadataURI-uri}. + +:uri: pass:normal[xref:#IERC1155MetadataURI-uri-uint256-[`++uri++`]] + +[.contract] +[[IERC1155MetadataURI]] +=== `++IERC1155MetadataURI++` link:https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v5.0.0-rc.0/contracts/token/ERC1155/extensions/IERC1155MetadataURI.sol[{github-icon},role=heading-link] + +[.hljs-theme-light.nopadding] +```solidity +import "@openzeppelin/contracts/token/ERC1155/extensions/IERC1155MetadataURI.sol"; +``` + +Interface of the optional ERC1155MetadataExtension interface, as defined +in the https://eips.ethereum.org/EIPS/eip-1155#metadata-extensions[EIP]. + +[.contract-index] +.Functions +-- +* {xref-IERC1155MetadataURI-uri-uint256-}[`++uri(id)++`] + +[.contract-subindex-inherited] +.IERC1155 +* {xref-IERC1155-balanceOf-address-uint256-}[`++balanceOf(account, id)++`] +* {xref-IERC1155-balanceOfBatch-address---uint256---}[`++balanceOfBatch(accounts, ids)++`] +* {xref-IERC1155-setApprovalForAll-address-bool-}[`++setApprovalForAll(operator, approved)++`] +* {xref-IERC1155-isApprovedForAll-address-address-}[`++isApprovedForAll(account, operator)++`] +* {xref-IERC1155-safeTransferFrom-address-address-uint256-uint256-bytes-}[`++safeTransferFrom(from, to, id, value, data)++`] +* {xref-IERC1155-safeBatchTransferFrom-address-address-uint256---uint256---bytes-}[`++safeBatchTransferFrom(from, to, ids, values, data)++`] + +[.contract-subindex-inherited] +.IERC165 +* {xref-IERC165-supportsInterface-bytes4-}[`++supportsInterface(interfaceId)++`] + +-- + +[.contract-index] +.Events +-- + +[.contract-subindex-inherited] +.IERC1155 +* {xref-IERC1155-TransferSingle-address-address-address-uint256-uint256-}[`++TransferSingle(operator, from, to, id, value)++`] +* {xref-IERC1155-TransferBatch-address-address-address-uint256---uint256---}[`++TransferBatch(operator, from, to, ids, values)++`] +* {xref-IERC1155-ApprovalForAll-address-address-bool-}[`++ApprovalForAll(account, operator, approved)++`] +* {xref-IERC1155-URI-string-uint256-}[`++URI(value, id)++`] + +[.contract-subindex-inherited] +.IERC165 + +-- + +[.contract-item] +[[IERC1155MetadataURI-uri-uint256-]] +==== `[.contract-item-name]#++uri++#++(uint256 id) → string++` [.item-kind]#external# + +Returns the URI for token type `id`. + +If the `\{id\}` substring is present in the URI, it must be replaced by +clients with the actual token type ID. + +:constructor: pass:normal[xref:#ERC1155-constructor-string-[`++constructor++`]] +:supportsInterface: pass:normal[xref:#ERC1155-supportsInterface-bytes4-[`++supportsInterface++`]] +:uri: pass:normal[xref:#ERC1155-uri-uint256-[`++uri++`]] +:balanceOf: pass:normal[xref:#ERC1155-balanceOf-address-uint256-[`++balanceOf++`]] +:balanceOfBatch: pass:normal[xref:#ERC1155-balanceOfBatch-address---uint256---[`++balanceOfBatch++`]] +:setApprovalForAll: pass:normal[xref:#ERC1155-setApprovalForAll-address-bool-[`++setApprovalForAll++`]] +:isApprovedForAll: pass:normal[xref:#ERC1155-isApprovedForAll-address-address-[`++isApprovedForAll++`]] +:safeTransferFrom: pass:normal[xref:#ERC1155-safeTransferFrom-address-address-uint256-uint256-bytes-[`++safeTransferFrom++`]] +:safeBatchTransferFrom: pass:normal[xref:#ERC1155-safeBatchTransferFrom-address-address-uint256---uint256---bytes-[`++safeBatchTransferFrom++`]] +:_update: pass:normal[xref:#ERC1155-_update-address-address-uint256---uint256---[`++_update++`]] +:_updateWithAcceptanceCheck: pass:normal[xref:#ERC1155-_updateWithAcceptanceCheck-address-address-uint256---uint256---bytes-[`++_updateWithAcceptanceCheck++`]] +:_safeTransferFrom: pass:normal[xref:#ERC1155-_safeTransferFrom-address-address-uint256-uint256-bytes-[`++_safeTransferFrom++`]] +:_safeBatchTransferFrom: pass:normal[xref:#ERC1155-_safeBatchTransferFrom-address-address-uint256---uint256---bytes-[`++_safeBatchTransferFrom++`]] +:_setURI: pass:normal[xref:#ERC1155-_setURI-string-[`++_setURI++`]] +:_mint: pass:normal[xref:#ERC1155-_mint-address-uint256-uint256-bytes-[`++_mint++`]] +:_mintBatch: pass:normal[xref:#ERC1155-_mintBatch-address-uint256---uint256---bytes-[`++_mintBatch++`]] +:_burn: pass:normal[xref:#ERC1155-_burn-address-uint256-uint256-[`++_burn++`]] +:_burnBatch: pass:normal[xref:#ERC1155-_burnBatch-address-uint256---uint256---[`++_burnBatch++`]] +:_setApprovalForAll: pass:normal[xref:#ERC1155-_setApprovalForAll-address-address-bool-[`++_setApprovalForAll++`]] + +[.contract] +[[ERC1155]] +=== `++ERC1155++` link:https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v5.0.0-rc.0/contracts/token/ERC1155/ERC1155.sol[{github-icon},role=heading-link] + +[.hljs-theme-light.nopadding] +```solidity +import "@openzeppelin/contracts/token/ERC1155/ERC1155.sol"; +``` + +Implementation of the basic standard multi-token. +See https://eips.ethereum.org/EIPS/eip-1155 +Originally based on code by Enjin: https://github.com/enjin/erc-1155 + +[.contract-index] +.Functions +-- +* {xref-ERC1155-constructor-string-}[`++constructor(uri_)++`] +* {xref-ERC1155-supportsInterface-bytes4-}[`++supportsInterface(interfaceId)++`] +* {xref-ERC1155-uri-uint256-}[`++uri()++`] +* {xref-ERC1155-balanceOf-address-uint256-}[`++balanceOf(account, id)++`] +* {xref-ERC1155-balanceOfBatch-address---uint256---}[`++balanceOfBatch(accounts, ids)++`] +* {xref-ERC1155-setApprovalForAll-address-bool-}[`++setApprovalForAll(operator, approved)++`] +* {xref-ERC1155-isApprovedForAll-address-address-}[`++isApprovedForAll(account, operator)++`] +* {xref-ERC1155-safeTransferFrom-address-address-uint256-uint256-bytes-}[`++safeTransferFrom(from, to, id, value, data)++`] +* {xref-ERC1155-safeBatchTransferFrom-address-address-uint256---uint256---bytes-}[`++safeBatchTransferFrom(from, to, ids, values, data)++`] +* {xref-ERC1155-_update-address-address-uint256---uint256---}[`++_update(from, to, ids, values)++`] +* {xref-ERC1155-_updateWithAcceptanceCheck-address-address-uint256---uint256---bytes-}[`++_updateWithAcceptanceCheck(from, to, ids, values, data)++`] +* {xref-ERC1155-_safeTransferFrom-address-address-uint256-uint256-bytes-}[`++_safeTransferFrom(from, to, id, value, data)++`] +* {xref-ERC1155-_safeBatchTransferFrom-address-address-uint256---uint256---bytes-}[`++_safeBatchTransferFrom(from, to, ids, values, data)++`] +* {xref-ERC1155-_setURI-string-}[`++_setURI(newuri)++`] +* {xref-ERC1155-_mint-address-uint256-uint256-bytes-}[`++_mint(to, id, value, data)++`] +* {xref-ERC1155-_mintBatch-address-uint256---uint256---bytes-}[`++_mintBatch(to, ids, values, data)++`] +* {xref-ERC1155-_burn-address-uint256-uint256-}[`++_burn(from, id, value)++`] +* {xref-ERC1155-_burnBatch-address-uint256---uint256---}[`++_burnBatch(from, ids, values)++`] +* {xref-ERC1155-_setApprovalForAll-address-address-bool-}[`++_setApprovalForAll(owner, operator, approved)++`] + +[.contract-subindex-inherited] +.IERC1155Errors + +[.contract-subindex-inherited] +.IERC1155MetadataURI + +[.contract-subindex-inherited] +.IERC1155 + +[.contract-subindex-inherited] +.ERC165 + +[.contract-subindex-inherited] +.IERC165 + +-- + +[.contract-index] +.Events +-- + +[.contract-subindex-inherited] +.IERC1155Errors + +[.contract-subindex-inherited] +.IERC1155MetadataURI + +[.contract-subindex-inherited] +.IERC1155 +* {xref-IERC1155-TransferSingle-address-address-address-uint256-uint256-}[`++TransferSingle(operator, from, to, id, value)++`] +* {xref-IERC1155-TransferBatch-address-address-address-uint256---uint256---}[`++TransferBatch(operator, from, to, ids, values)++`] +* {xref-IERC1155-ApprovalForAll-address-address-bool-}[`++ApprovalForAll(account, operator, approved)++`] +* {xref-IERC1155-URI-string-uint256-}[`++URI(value, id)++`] + +[.contract-subindex-inherited] +.ERC165 + +[.contract-subindex-inherited] +.IERC165 + +-- + +[.contract-index] +.Errors +-- + +[.contract-subindex-inherited] +.IERC1155Errors +* {xref-IERC1155Errors-ERC1155InsufficientBalance-address-uint256-uint256-uint256-}[`++ERC1155InsufficientBalance(sender, balance, needed, tokenId)++`] +* {xref-IERC1155Errors-ERC1155InvalidSender-address-}[`++ERC1155InvalidSender(sender)++`] +* {xref-IERC1155Errors-ERC1155InvalidReceiver-address-}[`++ERC1155InvalidReceiver(receiver)++`] +* {xref-IERC1155Errors-ERC1155MissingApprovalForAll-address-address-}[`++ERC1155MissingApprovalForAll(operator, owner)++`] +* {xref-IERC1155Errors-ERC1155InvalidApprover-address-}[`++ERC1155InvalidApprover(approver)++`] +* {xref-IERC1155Errors-ERC1155InvalidOperator-address-}[`++ERC1155InvalidOperator(operator)++`] +* {xref-IERC1155Errors-ERC1155InvalidArrayLength-uint256-uint256-}[`++ERC1155InvalidArrayLength(idsLength, valuesLength)++`] + +[.contract-subindex-inherited] +.IERC1155MetadataURI + +[.contract-subindex-inherited] +.IERC1155 + +[.contract-subindex-inherited] +.ERC165 + +[.contract-subindex-inherited] +.IERC165 + +-- + +[.contract-item] +[[ERC1155-constructor-string-]] +==== `[.contract-item-name]#++constructor++#++(string uri_)++` [.item-kind]#internal# + +See {_setURI}. + +[.contract-item] +[[ERC1155-supportsInterface-bytes4-]] +==== `[.contract-item-name]#++supportsInterface++#++(bytes4 interfaceId) → bool++` [.item-kind]#public# + +See {IERC165-supportsInterface}. + +[.contract-item] +[[ERC1155-uri-uint256-]] +==== `[.contract-item-name]#++uri++#++(uint256) → string++` [.item-kind]#public# + +See {IERC1155MetadataURI-uri}. + +This implementation returns the same URI for *all* token types. It relies +on the token type ID substitution mechanism +https://eips.ethereum.org/EIPS/eip-1155#metadata[defined in the EIP]. + +Clients calling this function must replace the `\{id\}` substring with the +actual token type ID. + +[.contract-item] +[[ERC1155-balanceOf-address-uint256-]] +==== `[.contract-item-name]#++balanceOf++#++(address account, uint256 id) → uint256++` [.item-kind]#public# + +See {IERC1155-balanceOf}. + +[.contract-item] +[[ERC1155-balanceOfBatch-address---uint256---]] +==== `[.contract-item-name]#++balanceOfBatch++#++(address[] accounts, uint256[] ids) → uint256[]++` [.item-kind]#public# + +See {IERC1155-balanceOfBatch}. + +Requirements: + +- `accounts` and `ids` must have the same length. + +[.contract-item] +[[ERC1155-setApprovalForAll-address-bool-]] +==== `[.contract-item-name]#++setApprovalForAll++#++(address operator, bool approved)++` [.item-kind]#public# + +See {IERC1155-setApprovalForAll}. + +[.contract-item] +[[ERC1155-isApprovedForAll-address-address-]] +==== `[.contract-item-name]#++isApprovedForAll++#++(address account, address operator) → bool++` [.item-kind]#public# + +See {IERC1155-isApprovedForAll}. + +[.contract-item] +[[ERC1155-safeTransferFrom-address-address-uint256-uint256-bytes-]] +==== `[.contract-item-name]#++safeTransferFrom++#++(address from, address to, uint256 id, uint256 value, bytes data)++` [.item-kind]#public# + +See {IERC1155-safeTransferFrom}. + +[.contract-item] +[[ERC1155-safeBatchTransferFrom-address-address-uint256---uint256---bytes-]] +==== `[.contract-item-name]#++safeBatchTransferFrom++#++(address from, address to, uint256[] ids, uint256[] values, bytes data)++` [.item-kind]#public# + +See {IERC1155-safeBatchTransferFrom}. + +[.contract-item] +[[ERC1155-_update-address-address-uint256---uint256---]] +==== `[.contract-item-name]#++_update++#++(address from, address to, uint256[] ids, uint256[] values)++` [.item-kind]#internal# + +Transfers a `value` amount of tokens of type `id` from `from` to `to`. Will mint (or burn) if `from` +(or `to`) is the zero address. + +Emits a {TransferSingle} event if the arrays contain one element, and {TransferBatch} otherwise. + +Requirements: + +- If `to` refers to a smart contract, it must implement either {IERC1155Receiver-onERC1155Received} + or {IERC1155Receiver-onERC1155BatchReceived} and return the acceptance magic value. +- `ids` and `values` must have the same length. + +NOTE: The ERC-1155 acceptance check is not performed in this function. See {_updateWithAcceptanceCheck} instead. + +[.contract-item] +[[ERC1155-_updateWithAcceptanceCheck-address-address-uint256---uint256---bytes-]] +==== `[.contract-item-name]#++_updateWithAcceptanceCheck++#++(address from, address to, uint256[] ids, uint256[] values, bytes data)++` [.item-kind]#internal# + +Version of {_update} that performs the token acceptance check by calling +{IERC1155Receiver-onERC1155Received} or {IERC1155Receiver-onERC1155BatchReceived} on the receiver address if it +contains code (eg. is a smart contract at the moment of execution). + +IMPORTANT: Overriding this function is discouraged because it poses a reentrancy risk from the receiver. So any +update to the contract state after this function would break the check-effect-interaction pattern. Consider +overriding {_update} instead. + +[.contract-item] +[[ERC1155-_safeTransferFrom-address-address-uint256-uint256-bytes-]] +==== `[.contract-item-name]#++_safeTransferFrom++#++(address from, address to, uint256 id, uint256 value, bytes data)++` [.item-kind]#internal# + +Transfers a `value` tokens of token type `id` from `from` to `to`. + +Emits a {TransferSingle} event. + +Requirements: + +- `to` cannot be the zero address. +- `from` must have a balance of tokens of type `id` of at least `value` amount. +- If `to` refers to a smart contract, it must implement {IERC1155Receiver-onERC1155Received} and return the +acceptance magic value. + +[.contract-item] +[[ERC1155-_safeBatchTransferFrom-address-address-uint256---uint256---bytes-]] +==== `[.contract-item-name]#++_safeBatchTransferFrom++#++(address from, address to, uint256[] ids, uint256[] values, bytes data)++` [.item-kind]#internal# + +xref:ROOT:erc1155.adoc#batch-operations[Batched] version of {_safeTransferFrom}. + +Emits a {TransferBatch} event. + +Requirements: + +- If `to` refers to a smart contract, it must implement {IERC1155Receiver-onERC1155BatchReceived} and return the +acceptance magic value. +- `ids` and `values` must have the same length. + +[.contract-item] +[[ERC1155-_setURI-string-]] +==== `[.contract-item-name]#++_setURI++#++(string newuri)++` [.item-kind]#internal# + +Sets a new URI for all token types, by relying on the token type ID +substitution mechanism +https://eips.ethereum.org/EIPS/eip-1155#metadata[defined in the EIP]. + +By this mechanism, any occurrence of the `\{id\}` substring in either the +URI or any of the values in the JSON file at said URI will be replaced by +clients with the token type ID. + +For example, the `https://token-cdn-domain/\{id\}.json` URI would be +interpreted by clients as +`https://token-cdn-domain/000000000000000000000000000000000000000000000000000000000004cce0.json` +for token type ID 0x4cce0. + +See {uri}. + +Because these URIs cannot be meaningfully represented by the {URI} event, +this function emits no events. + +[.contract-item] +[[ERC1155-_mint-address-uint256-uint256-bytes-]] +==== `[.contract-item-name]#++_mint++#++(address to, uint256 id, uint256 value, bytes data)++` [.item-kind]#internal# + +Creates a `value` amount of tokens of type `id`, and assigns them to `to`. + +Emits a {TransferSingle} event. + +Requirements: + +- `to` cannot be the zero address. +- If `to` refers to a smart contract, it must implement {IERC1155Receiver-onERC1155Received} and return the +acceptance magic value. + +[.contract-item] +[[ERC1155-_mintBatch-address-uint256---uint256---bytes-]] +==== `[.contract-item-name]#++_mintBatch++#++(address to, uint256[] ids, uint256[] values, bytes data)++` [.item-kind]#internal# + +xref:ROOT:erc1155.adoc#batch-operations[Batched] version of {_mint}. + +Emits a {TransferBatch} event. + +Requirements: + +- `ids` and `values` must have the same length. +- `to` cannot be the zero address. +- If `to` refers to a smart contract, it must implement {IERC1155Receiver-onERC1155BatchReceived} and return the +acceptance magic value. + +[.contract-item] +[[ERC1155-_burn-address-uint256-uint256-]] +==== `[.contract-item-name]#++_burn++#++(address from, uint256 id, uint256 value)++` [.item-kind]#internal# + +Destroys a `value` amount of tokens of type `id` from `from` + +Emits a {TransferSingle} event. + +Requirements: + +- `from` cannot be the zero address. +- `from` must have at least `value` amount of tokens of type `id`. + +[.contract-item] +[[ERC1155-_burnBatch-address-uint256---uint256---]] +==== `[.contract-item-name]#++_burnBatch++#++(address from, uint256[] ids, uint256[] values)++` [.item-kind]#internal# + +xref:ROOT:erc1155.adoc#batch-operations[Batched] version of {_burn}. + +Emits a {TransferBatch} event. + +Requirements: + +- `from` cannot be the zero address. +- `from` must have at least `value` amount of tokens of type `id`. +- `ids` and `values` must have the same length. + +[.contract-item] +[[ERC1155-_setApprovalForAll-address-address-bool-]] +==== `[.contract-item-name]#++_setApprovalForAll++#++(address owner, address operator, bool approved)++` [.item-kind]#internal# + +Approve `operator` to operate on all of `owner` tokens + +Emits an {ApprovalForAll} event. + +Requirements: + +- `operator` cannot be the zero address. + +:onERC1155Received: pass:normal[xref:#IERC1155Receiver-onERC1155Received-address-address-uint256-uint256-bytes-[`++onERC1155Received++`]] +:onERC1155BatchReceived: pass:normal[xref:#IERC1155Receiver-onERC1155BatchReceived-address-address-uint256---uint256---bytes-[`++onERC1155BatchReceived++`]] + +[.contract] +[[IERC1155Receiver]] +=== `++IERC1155Receiver++` link:https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v5.0.0-rc.0/contracts/token/ERC1155/IERC1155Receiver.sol[{github-icon},role=heading-link] + +[.hljs-theme-light.nopadding] +```solidity +import "@openzeppelin/contracts/token/ERC1155/IERC1155Receiver.sol"; +``` + +Interface that must be implemented by smart contracts in order to receive +ERC-1155 token transfers. + +[.contract-index] +.Functions +-- +* {xref-IERC1155Receiver-onERC1155Received-address-address-uint256-uint256-bytes-}[`++onERC1155Received(operator, from, id, value, data)++`] +* {xref-IERC1155Receiver-onERC1155BatchReceived-address-address-uint256---uint256---bytes-}[`++onERC1155BatchReceived(operator, from, ids, values, data)++`] + +[.contract-subindex-inherited] +.IERC165 +* {xref-IERC165-supportsInterface-bytes4-}[`++supportsInterface(interfaceId)++`] + +-- + +[.contract-item] +[[IERC1155Receiver-onERC1155Received-address-address-uint256-uint256-bytes-]] +==== `[.contract-item-name]#++onERC1155Received++#++(address operator, address from, uint256 id, uint256 value, bytes data) → bytes4++` [.item-kind]#external# + +Handles the receipt of a single ERC1155 token type. This function is +called at the end of a `safeTransferFrom` after the balance has been updated. + +NOTE: To accept the transfer, this must return +`bytes4(keccak256("onERC1155Received(address,address,uint256,uint256,bytes)"))` +(i.e. 0xf23a6e61, or its own function selector). + +[.contract-item] +[[IERC1155Receiver-onERC1155BatchReceived-address-address-uint256---uint256---bytes-]] +==== `[.contract-item-name]#++onERC1155BatchReceived++#++(address operator, address from, uint256[] ids, uint256[] values, bytes data) → bytes4++` [.item-kind]#external# + +Handles the receipt of a multiple ERC1155 token types. This function +is called at the end of a `safeBatchTransferFrom` after the balances have +been updated. + +NOTE: To accept the transfer(s), this must return +`bytes4(keccak256("onERC1155BatchReceived(address,address,uint256[],uint256[],bytes)"))` +(i.e. 0xbc197c81, or its own function selector). + +== Extensions + +:_update: pass:normal[xref:#ERC1155Pausable-_update-address-address-uint256---uint256---[`++_update++`]] + +[.contract] +[[ERC1155Pausable]] +=== `++ERC1155Pausable++` link:https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v5.0.0-rc.0/contracts/token/ERC1155/extensions/ERC1155Pausable.sol[{github-icon},role=heading-link] + +[.hljs-theme-light.nopadding] +```solidity +import "@openzeppelin/contracts/token/ERC1155/extensions/ERC1155Pausable.sol"; +``` + +ERC1155 token with pausable token transfers, minting and burning. + +Useful for scenarios such as preventing trades until the end of an evaluation +period, or having an emergency switch for freezing all token transfers in the +event of a large bug. + +IMPORTANT: This contract does not include public pause and unpause functions. In +addition to inheriting this contract, you must define both functions, invoking the +{Pausable-_pause} and {Pausable-_unpause} internal functions, with appropriate +access control, e.g. using {AccessControl} or {Ownable}. Not doing so will +make the contract pause mechanism of the contract unreachable, and thus unusable. + +[.contract-index] +.Functions +-- +* {xref-ERC1155Pausable-_update-address-address-uint256---uint256---}[`++_update(from, to, ids, values)++`] + +[.contract-subindex-inherited] +.Pausable +* {xref-Pausable-paused--}[`++paused()++`] +* {xref-Pausable-_requireNotPaused--}[`++_requireNotPaused()++`] +* {xref-Pausable-_requirePaused--}[`++_requirePaused()++`] +* {xref-Pausable-_pause--}[`++_pause()++`] +* {xref-Pausable-_unpause--}[`++_unpause()++`] + +[.contract-subindex-inherited] +.ERC1155 +* {xref-ERC1155-supportsInterface-bytes4-}[`++supportsInterface(interfaceId)++`] +* {xref-ERC1155-uri-uint256-}[`++uri()++`] +* {xref-ERC1155-balanceOf-address-uint256-}[`++balanceOf(account, id)++`] +* {xref-ERC1155-balanceOfBatch-address---uint256---}[`++balanceOfBatch(accounts, ids)++`] +* {xref-ERC1155-setApprovalForAll-address-bool-}[`++setApprovalForAll(operator, approved)++`] +* {xref-ERC1155-isApprovedForAll-address-address-}[`++isApprovedForAll(account, operator)++`] +* {xref-ERC1155-safeTransferFrom-address-address-uint256-uint256-bytes-}[`++safeTransferFrom(from, to, id, value, data)++`] +* {xref-ERC1155-safeBatchTransferFrom-address-address-uint256---uint256---bytes-}[`++safeBatchTransferFrom(from, to, ids, values, data)++`] +* {xref-ERC1155-_updateWithAcceptanceCheck-address-address-uint256---uint256---bytes-}[`++_updateWithAcceptanceCheck(from, to, ids, values, data)++`] +* {xref-ERC1155-_safeTransferFrom-address-address-uint256-uint256-bytes-}[`++_safeTransferFrom(from, to, id, value, data)++`] +* {xref-ERC1155-_safeBatchTransferFrom-address-address-uint256---uint256---bytes-}[`++_safeBatchTransferFrom(from, to, ids, values, data)++`] +* {xref-ERC1155-_setURI-string-}[`++_setURI(newuri)++`] +* {xref-ERC1155-_mint-address-uint256-uint256-bytes-}[`++_mint(to, id, value, data)++`] +* {xref-ERC1155-_mintBatch-address-uint256---uint256---bytes-}[`++_mintBatch(to, ids, values, data)++`] +* {xref-ERC1155-_burn-address-uint256-uint256-}[`++_burn(from, id, value)++`] +* {xref-ERC1155-_burnBatch-address-uint256---uint256---}[`++_burnBatch(from, ids, values)++`] +* {xref-ERC1155-_setApprovalForAll-address-address-bool-}[`++_setApprovalForAll(owner, operator, approved)++`] + +[.contract-subindex-inherited] +.IERC1155Errors + +[.contract-subindex-inherited] +.IERC1155MetadataURI + +[.contract-subindex-inherited] +.IERC1155 + +[.contract-subindex-inherited] +.ERC165 + +[.contract-subindex-inherited] +.IERC165 + +-- + +[.contract-index] +.Events +-- + +[.contract-subindex-inherited] +.Pausable +* {xref-Pausable-Paused-address-}[`++Paused(account)++`] +* {xref-Pausable-Unpaused-address-}[`++Unpaused(account)++`] + +[.contract-subindex-inherited] +.ERC1155 + +[.contract-subindex-inherited] +.IERC1155Errors + +[.contract-subindex-inherited] +.IERC1155MetadataURI + +[.contract-subindex-inherited] +.IERC1155 +* {xref-IERC1155-TransferSingle-address-address-address-uint256-uint256-}[`++TransferSingle(operator, from, to, id, value)++`] +* {xref-IERC1155-TransferBatch-address-address-address-uint256---uint256---}[`++TransferBatch(operator, from, to, ids, values)++`] +* {xref-IERC1155-ApprovalForAll-address-address-bool-}[`++ApprovalForAll(account, operator, approved)++`] +* {xref-IERC1155-URI-string-uint256-}[`++URI(value, id)++`] + +[.contract-subindex-inherited] +.ERC165 + +[.contract-subindex-inherited] +.IERC165 + +-- + +[.contract-index] +.Errors +-- + +[.contract-subindex-inherited] +.Pausable +* {xref-Pausable-EnforcedPause--}[`++EnforcedPause()++`] +* {xref-Pausable-ExpectedPause--}[`++ExpectedPause()++`] + +[.contract-subindex-inherited] +.ERC1155 + +[.contract-subindex-inherited] +.IERC1155Errors +* {xref-IERC1155Errors-ERC1155InsufficientBalance-address-uint256-uint256-uint256-}[`++ERC1155InsufficientBalance(sender, balance, needed, tokenId)++`] +* {xref-IERC1155Errors-ERC1155InvalidSender-address-}[`++ERC1155InvalidSender(sender)++`] +* {xref-IERC1155Errors-ERC1155InvalidReceiver-address-}[`++ERC1155InvalidReceiver(receiver)++`] +* {xref-IERC1155Errors-ERC1155MissingApprovalForAll-address-address-}[`++ERC1155MissingApprovalForAll(operator, owner)++`] +* {xref-IERC1155Errors-ERC1155InvalidApprover-address-}[`++ERC1155InvalidApprover(approver)++`] +* {xref-IERC1155Errors-ERC1155InvalidOperator-address-}[`++ERC1155InvalidOperator(operator)++`] +* {xref-IERC1155Errors-ERC1155InvalidArrayLength-uint256-uint256-}[`++ERC1155InvalidArrayLength(idsLength, valuesLength)++`] + +[.contract-subindex-inherited] +.IERC1155MetadataURI + +[.contract-subindex-inherited] +.IERC1155 + +[.contract-subindex-inherited] +.ERC165 + +[.contract-subindex-inherited] +.IERC165 + +-- + +[.contract-item] +[[ERC1155Pausable-_update-address-address-uint256---uint256---]] +==== `[.contract-item-name]#++_update++#++(address from, address to, uint256[] ids, uint256[] values)++` [.item-kind]#internal# + +See {ERC1155-_update}. + +Requirements: + +- the contract must not be paused. + +:burn: pass:normal[xref:#ERC1155Burnable-burn-address-uint256-uint256-[`++burn++`]] +:burnBatch: pass:normal[xref:#ERC1155Burnable-burnBatch-address-uint256---uint256---[`++burnBatch++`]] + +[.contract] +[[ERC1155Burnable]] +=== `++ERC1155Burnable++` link:https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v5.0.0-rc.0/contracts/token/ERC1155/extensions/ERC1155Burnable.sol[{github-icon},role=heading-link] + +[.hljs-theme-light.nopadding] +```solidity +import "@openzeppelin/contracts/token/ERC1155/extensions/ERC1155Burnable.sol"; +``` + +Extension of {ERC1155} that allows token holders to destroy both their +own tokens and those that they have been approved to use. + +[.contract-index] +.Functions +-- +* {xref-ERC1155Burnable-burn-address-uint256-uint256-}[`++burn(account, id, value)++`] +* {xref-ERC1155Burnable-burnBatch-address-uint256---uint256---}[`++burnBatch(account, ids, values)++`] + +[.contract-subindex-inherited] +.ERC1155 +* {xref-ERC1155-supportsInterface-bytes4-}[`++supportsInterface(interfaceId)++`] +* {xref-ERC1155-uri-uint256-}[`++uri()++`] +* {xref-ERC1155-balanceOf-address-uint256-}[`++balanceOf(account, id)++`] +* {xref-ERC1155-balanceOfBatch-address---uint256---}[`++balanceOfBatch(accounts, ids)++`] +* {xref-ERC1155-setApprovalForAll-address-bool-}[`++setApprovalForAll(operator, approved)++`] +* {xref-ERC1155-isApprovedForAll-address-address-}[`++isApprovedForAll(account, operator)++`] +* {xref-ERC1155-safeTransferFrom-address-address-uint256-uint256-bytes-}[`++safeTransferFrom(from, to, id, value, data)++`] +* {xref-ERC1155-safeBatchTransferFrom-address-address-uint256---uint256---bytes-}[`++safeBatchTransferFrom(from, to, ids, values, data)++`] +* {xref-ERC1155-_update-address-address-uint256---uint256---}[`++_update(from, to, ids, values)++`] +* {xref-ERC1155-_updateWithAcceptanceCheck-address-address-uint256---uint256---bytes-}[`++_updateWithAcceptanceCheck(from, to, ids, values, data)++`] +* {xref-ERC1155-_safeTransferFrom-address-address-uint256-uint256-bytes-}[`++_safeTransferFrom(from, to, id, value, data)++`] +* {xref-ERC1155-_safeBatchTransferFrom-address-address-uint256---uint256---bytes-}[`++_safeBatchTransferFrom(from, to, ids, values, data)++`] +* {xref-ERC1155-_setURI-string-}[`++_setURI(newuri)++`] +* {xref-ERC1155-_mint-address-uint256-uint256-bytes-}[`++_mint(to, id, value, data)++`] +* {xref-ERC1155-_mintBatch-address-uint256---uint256---bytes-}[`++_mintBatch(to, ids, values, data)++`] +* {xref-ERC1155-_burn-address-uint256-uint256-}[`++_burn(from, id, value)++`] +* {xref-ERC1155-_burnBatch-address-uint256---uint256---}[`++_burnBatch(from, ids, values)++`] +* {xref-ERC1155-_setApprovalForAll-address-address-bool-}[`++_setApprovalForAll(owner, operator, approved)++`] + +[.contract-subindex-inherited] +.IERC1155Errors + +[.contract-subindex-inherited] +.IERC1155MetadataURI + +[.contract-subindex-inherited] +.IERC1155 + +[.contract-subindex-inherited] +.ERC165 + +[.contract-subindex-inherited] +.IERC165 + +-- + +[.contract-index] +.Events +-- + +[.contract-subindex-inherited] +.ERC1155 + +[.contract-subindex-inherited] +.IERC1155Errors + +[.contract-subindex-inherited] +.IERC1155MetadataURI + +[.contract-subindex-inherited] +.IERC1155 +* {xref-IERC1155-TransferSingle-address-address-address-uint256-uint256-}[`++TransferSingle(operator, from, to, id, value)++`] +* {xref-IERC1155-TransferBatch-address-address-address-uint256---uint256---}[`++TransferBatch(operator, from, to, ids, values)++`] +* {xref-IERC1155-ApprovalForAll-address-address-bool-}[`++ApprovalForAll(account, operator, approved)++`] +* {xref-IERC1155-URI-string-uint256-}[`++URI(value, id)++`] + +[.contract-subindex-inherited] +.ERC165 + +[.contract-subindex-inherited] +.IERC165 + +-- + +[.contract-index] +.Errors +-- + +[.contract-subindex-inherited] +.ERC1155 + +[.contract-subindex-inherited] +.IERC1155Errors +* {xref-IERC1155Errors-ERC1155InsufficientBalance-address-uint256-uint256-uint256-}[`++ERC1155InsufficientBalance(sender, balance, needed, tokenId)++`] +* {xref-IERC1155Errors-ERC1155InvalidSender-address-}[`++ERC1155InvalidSender(sender)++`] +* {xref-IERC1155Errors-ERC1155InvalidReceiver-address-}[`++ERC1155InvalidReceiver(receiver)++`] +* {xref-IERC1155Errors-ERC1155MissingApprovalForAll-address-address-}[`++ERC1155MissingApprovalForAll(operator, owner)++`] +* {xref-IERC1155Errors-ERC1155InvalidApprover-address-}[`++ERC1155InvalidApprover(approver)++`] +* {xref-IERC1155Errors-ERC1155InvalidOperator-address-}[`++ERC1155InvalidOperator(operator)++`] +* {xref-IERC1155Errors-ERC1155InvalidArrayLength-uint256-uint256-}[`++ERC1155InvalidArrayLength(idsLength, valuesLength)++`] + +[.contract-subindex-inherited] +.IERC1155MetadataURI + +[.contract-subindex-inherited] +.IERC1155 + +[.contract-subindex-inherited] +.ERC165 + +[.contract-subindex-inherited] +.IERC165 + +-- + +[.contract-item] +[[ERC1155Burnable-burn-address-uint256-uint256-]] +==== `[.contract-item-name]#++burn++#++(address account, uint256 id, uint256 value)++` [.item-kind]#public# + +[.contract-item] +[[ERC1155Burnable-burnBatch-address-uint256---uint256---]] +==== `[.contract-item-name]#++burnBatch++#++(address account, uint256[] ids, uint256[] values)++` [.item-kind]#public# + +:totalSupply: pass:normal[xref:#ERC1155Supply-totalSupply-uint256-[`++totalSupply++`]] +:totalSupply: pass:normal[xref:#ERC1155Supply-totalSupply--[`++totalSupply++`]] +:exists: pass:normal[xref:#ERC1155Supply-exists-uint256-[`++exists++`]] +:_update: pass:normal[xref:#ERC1155Supply-_update-address-address-uint256---uint256---[`++_update++`]] + +[.contract] +[[ERC1155Supply]] +=== `++ERC1155Supply++` link:https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v5.0.0-rc.0/contracts/token/ERC1155/extensions/ERC1155Supply.sol[{github-icon},role=heading-link] + +[.hljs-theme-light.nopadding] +```solidity +import "@openzeppelin/contracts/token/ERC1155/extensions/ERC1155Supply.sol"; +``` + +Extension of ERC1155 that adds tracking of total supply per id. + +Useful for scenarios where Fungible and Non-fungible tokens have to be +clearly identified. Note: While a totalSupply of 1 might mean the +corresponding is an NFT, there is no guarantees that no other token with the +same id are not going to be minted. + +NOTE: This contract implies a global limit of 2**256 - 1 to the number of tokens +that can be minted. + +CAUTION: This extension should not be added in an upgrade to an already deployed contract. + +[.contract-index] +.Functions +-- +* {xref-ERC1155Supply-totalSupply-uint256-}[`++totalSupply(id)++`] +* {xref-ERC1155Supply-totalSupply--}[`++totalSupply()++`] +* {xref-ERC1155Supply-exists-uint256-}[`++exists(id)++`] +* {xref-ERC1155Supply-_update-address-address-uint256---uint256---}[`++_update(from, to, ids, values)++`] + +[.contract-subindex-inherited] +.ERC1155 +* {xref-ERC1155-supportsInterface-bytes4-}[`++supportsInterface(interfaceId)++`] +* {xref-ERC1155-uri-uint256-}[`++uri()++`] +* {xref-ERC1155-balanceOf-address-uint256-}[`++balanceOf(account, id)++`] +* {xref-ERC1155-balanceOfBatch-address---uint256---}[`++balanceOfBatch(accounts, ids)++`] +* {xref-ERC1155-setApprovalForAll-address-bool-}[`++setApprovalForAll(operator, approved)++`] +* {xref-ERC1155-isApprovedForAll-address-address-}[`++isApprovedForAll(account, operator)++`] +* {xref-ERC1155-safeTransferFrom-address-address-uint256-uint256-bytes-}[`++safeTransferFrom(from, to, id, value, data)++`] +* {xref-ERC1155-safeBatchTransferFrom-address-address-uint256---uint256---bytes-}[`++safeBatchTransferFrom(from, to, ids, values, data)++`] +* {xref-ERC1155-_updateWithAcceptanceCheck-address-address-uint256---uint256---bytes-}[`++_updateWithAcceptanceCheck(from, to, ids, values, data)++`] +* {xref-ERC1155-_safeTransferFrom-address-address-uint256-uint256-bytes-}[`++_safeTransferFrom(from, to, id, value, data)++`] +* {xref-ERC1155-_safeBatchTransferFrom-address-address-uint256---uint256---bytes-}[`++_safeBatchTransferFrom(from, to, ids, values, data)++`] +* {xref-ERC1155-_setURI-string-}[`++_setURI(newuri)++`] +* {xref-ERC1155-_mint-address-uint256-uint256-bytes-}[`++_mint(to, id, value, data)++`] +* {xref-ERC1155-_mintBatch-address-uint256---uint256---bytes-}[`++_mintBatch(to, ids, values, data)++`] +* {xref-ERC1155-_burn-address-uint256-uint256-}[`++_burn(from, id, value)++`] +* {xref-ERC1155-_burnBatch-address-uint256---uint256---}[`++_burnBatch(from, ids, values)++`] +* {xref-ERC1155-_setApprovalForAll-address-address-bool-}[`++_setApprovalForAll(owner, operator, approved)++`] + +[.contract-subindex-inherited] +.IERC1155Errors + +[.contract-subindex-inherited] +.IERC1155MetadataURI + +[.contract-subindex-inherited] +.IERC1155 + +[.contract-subindex-inherited] +.ERC165 + +[.contract-subindex-inherited] +.IERC165 + +-- + +[.contract-index] +.Events +-- + +[.contract-subindex-inherited] +.ERC1155 + +[.contract-subindex-inherited] +.IERC1155Errors + +[.contract-subindex-inherited] +.IERC1155MetadataURI + +[.contract-subindex-inherited] +.IERC1155 +* {xref-IERC1155-TransferSingle-address-address-address-uint256-uint256-}[`++TransferSingle(operator, from, to, id, value)++`] +* {xref-IERC1155-TransferBatch-address-address-address-uint256---uint256---}[`++TransferBatch(operator, from, to, ids, values)++`] +* {xref-IERC1155-ApprovalForAll-address-address-bool-}[`++ApprovalForAll(account, operator, approved)++`] +* {xref-IERC1155-URI-string-uint256-}[`++URI(value, id)++`] + +[.contract-subindex-inherited] +.ERC165 + +[.contract-subindex-inherited] +.IERC165 + +-- + +[.contract-index] +.Errors +-- + +[.contract-subindex-inherited] +.ERC1155 + +[.contract-subindex-inherited] +.IERC1155Errors +* {xref-IERC1155Errors-ERC1155InsufficientBalance-address-uint256-uint256-uint256-}[`++ERC1155InsufficientBalance(sender, balance, needed, tokenId)++`] +* {xref-IERC1155Errors-ERC1155InvalidSender-address-}[`++ERC1155InvalidSender(sender)++`] +* {xref-IERC1155Errors-ERC1155InvalidReceiver-address-}[`++ERC1155InvalidReceiver(receiver)++`] +* {xref-IERC1155Errors-ERC1155MissingApprovalForAll-address-address-}[`++ERC1155MissingApprovalForAll(operator, owner)++`] +* {xref-IERC1155Errors-ERC1155InvalidApprover-address-}[`++ERC1155InvalidApprover(approver)++`] +* {xref-IERC1155Errors-ERC1155InvalidOperator-address-}[`++ERC1155InvalidOperator(operator)++`] +* {xref-IERC1155Errors-ERC1155InvalidArrayLength-uint256-uint256-}[`++ERC1155InvalidArrayLength(idsLength, valuesLength)++`] + +[.contract-subindex-inherited] +.IERC1155MetadataURI + +[.contract-subindex-inherited] +.IERC1155 + +[.contract-subindex-inherited] +.ERC165 + +[.contract-subindex-inherited] +.IERC165 + +-- + +[.contract-item] +[[ERC1155Supply-totalSupply-uint256-]] +==== `[.contract-item-name]#++totalSupply++#++(uint256 id) → uint256++` [.item-kind]#public# + +Total value of tokens in with a given id. + +[.contract-item] +[[ERC1155Supply-totalSupply--]] +==== `[.contract-item-name]#++totalSupply++#++() → uint256++` [.item-kind]#public# + +Total value of tokens. + +[.contract-item] +[[ERC1155Supply-exists-uint256-]] +==== `[.contract-item-name]#++exists++#++(uint256 id) → bool++` [.item-kind]#public# + +Indicates whether any token exist with a given id, or not. + +[.contract-item] +[[ERC1155Supply-_update-address-address-uint256---uint256---]] +==== `[.contract-item-name]#++_update++#++(address from, address to, uint256[] ids, uint256[] values)++` [.item-kind]#internal# + +See {ERC1155-_update}. + +:uri: pass:normal[xref:#ERC1155URIStorage-uri-uint256-[`++uri++`]] +:_setURI: pass:normal[xref:#ERC1155URIStorage-_setURI-uint256-string-[`++_setURI++`]] +:_setBaseURI: pass:normal[xref:#ERC1155URIStorage-_setBaseURI-string-[`++_setBaseURI++`]] + +[.contract] +[[ERC1155URIStorage]] +=== `++ERC1155URIStorage++` link:https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v5.0.0-rc.0/contracts/token/ERC1155/extensions/ERC1155URIStorage.sol[{github-icon},role=heading-link] + +[.hljs-theme-light.nopadding] +```solidity +import "@openzeppelin/contracts/token/ERC1155/extensions/ERC1155URIStorage.sol"; +``` + +ERC1155 token with storage based token URI management. +Inspired by the ERC721URIStorage extension + +[.contract-index] +.Functions +-- +* {xref-ERC1155URIStorage-uri-uint256-}[`++uri(tokenId)++`] +* {xref-ERC1155URIStorage-_setURI-uint256-string-}[`++_setURI(tokenId, tokenURI)++`] +* {xref-ERC1155URIStorage-_setBaseURI-string-}[`++_setBaseURI(baseURI)++`] + +[.contract-subindex-inherited] +.ERC1155 +* {xref-ERC1155-supportsInterface-bytes4-}[`++supportsInterface(interfaceId)++`] +* {xref-ERC1155-balanceOf-address-uint256-}[`++balanceOf(account, id)++`] +* {xref-ERC1155-balanceOfBatch-address---uint256---}[`++balanceOfBatch(accounts, ids)++`] +* {xref-ERC1155-setApprovalForAll-address-bool-}[`++setApprovalForAll(operator, approved)++`] +* {xref-ERC1155-isApprovedForAll-address-address-}[`++isApprovedForAll(account, operator)++`] +* {xref-ERC1155-safeTransferFrom-address-address-uint256-uint256-bytes-}[`++safeTransferFrom(from, to, id, value, data)++`] +* {xref-ERC1155-safeBatchTransferFrom-address-address-uint256---uint256---bytes-}[`++safeBatchTransferFrom(from, to, ids, values, data)++`] +* {xref-ERC1155-_update-address-address-uint256---uint256---}[`++_update(from, to, ids, values)++`] +* {xref-ERC1155-_updateWithAcceptanceCheck-address-address-uint256---uint256---bytes-}[`++_updateWithAcceptanceCheck(from, to, ids, values, data)++`] +* {xref-ERC1155-_safeTransferFrom-address-address-uint256-uint256-bytes-}[`++_safeTransferFrom(from, to, id, value, data)++`] +* {xref-ERC1155-_safeBatchTransferFrom-address-address-uint256---uint256---bytes-}[`++_safeBatchTransferFrom(from, to, ids, values, data)++`] +* {xref-ERC1155-_setURI-string-}[`++_setURI(newuri)++`] +* {xref-ERC1155-_mint-address-uint256-uint256-bytes-}[`++_mint(to, id, value, data)++`] +* {xref-ERC1155-_mintBatch-address-uint256---uint256---bytes-}[`++_mintBatch(to, ids, values, data)++`] +* {xref-ERC1155-_burn-address-uint256-uint256-}[`++_burn(from, id, value)++`] +* {xref-ERC1155-_burnBatch-address-uint256---uint256---}[`++_burnBatch(from, ids, values)++`] +* {xref-ERC1155-_setApprovalForAll-address-address-bool-}[`++_setApprovalForAll(owner, operator, approved)++`] + +[.contract-subindex-inherited] +.IERC1155Errors + +[.contract-subindex-inherited] +.IERC1155MetadataURI + +[.contract-subindex-inherited] +.IERC1155 + +[.contract-subindex-inherited] +.ERC165 + +[.contract-subindex-inherited] +.IERC165 + +-- + +[.contract-index] +.Events +-- + +[.contract-subindex-inherited] +.ERC1155 + +[.contract-subindex-inherited] +.IERC1155Errors + +[.contract-subindex-inherited] +.IERC1155MetadataURI + +[.contract-subindex-inherited] +.IERC1155 +* {xref-IERC1155-TransferSingle-address-address-address-uint256-uint256-}[`++TransferSingle(operator, from, to, id, value)++`] +* {xref-IERC1155-TransferBatch-address-address-address-uint256---uint256---}[`++TransferBatch(operator, from, to, ids, values)++`] +* {xref-IERC1155-ApprovalForAll-address-address-bool-}[`++ApprovalForAll(account, operator, approved)++`] +* {xref-IERC1155-URI-string-uint256-}[`++URI(value, id)++`] + +[.contract-subindex-inherited] +.ERC165 + +[.contract-subindex-inherited] +.IERC165 + +-- + +[.contract-index] +.Errors +-- + +[.contract-subindex-inherited] +.ERC1155 + +[.contract-subindex-inherited] +.IERC1155Errors +* {xref-IERC1155Errors-ERC1155InsufficientBalance-address-uint256-uint256-uint256-}[`++ERC1155InsufficientBalance(sender, balance, needed, tokenId)++`] +* {xref-IERC1155Errors-ERC1155InvalidSender-address-}[`++ERC1155InvalidSender(sender)++`] +* {xref-IERC1155Errors-ERC1155InvalidReceiver-address-}[`++ERC1155InvalidReceiver(receiver)++`] +* {xref-IERC1155Errors-ERC1155MissingApprovalForAll-address-address-}[`++ERC1155MissingApprovalForAll(operator, owner)++`] +* {xref-IERC1155Errors-ERC1155InvalidApprover-address-}[`++ERC1155InvalidApprover(approver)++`] +* {xref-IERC1155Errors-ERC1155InvalidOperator-address-}[`++ERC1155InvalidOperator(operator)++`] +* {xref-IERC1155Errors-ERC1155InvalidArrayLength-uint256-uint256-}[`++ERC1155InvalidArrayLength(idsLength, valuesLength)++`] + +[.contract-subindex-inherited] +.IERC1155MetadataURI + +[.contract-subindex-inherited] +.IERC1155 + +[.contract-subindex-inherited] +.ERC165 + +[.contract-subindex-inherited] +.IERC165 + +-- + +[.contract-item] +[[ERC1155URIStorage-uri-uint256-]] +==== `[.contract-item-name]#++uri++#++(uint256 tokenId) → string++` [.item-kind]#public# + +See {IERC1155MetadataURI-uri}. + +This implementation returns the concatenation of the `_baseURI` +and the token-specific uri if the latter is set + +This enables the following behaviors: + +- if `_tokenURIs[tokenId]` is set, then the result is the concatenation + of `_baseURI` and `_tokenURIs[tokenId]` (keep in mind that `_baseURI` + is empty per default); + +- if `_tokenURIs[tokenId]` is NOT set then we fallback to `super.uri()` + which in most cases will contain `ERC1155._uri`; + +- if `_tokenURIs[tokenId]` is NOT set, and if the parents do not have a + uri value set, then the result is empty. + +[.contract-item] +[[ERC1155URIStorage-_setURI-uint256-string-]] +==== `[.contract-item-name]#++_setURI++#++(uint256 tokenId, string tokenURI)++` [.item-kind]#internal# + +Sets `tokenURI` as the tokenURI of `tokenId`. + +[.contract-item] +[[ERC1155URIStorage-_setBaseURI-string-]] +==== `[.contract-item-name]#++_setBaseURI++#++(string baseURI)++` [.item-kind]#internal# + +Sets `baseURI` as the `_baseURI` for all tokens + +== Utilities + +:supportsInterface: pass:normal[xref:#ERC1155Holder-supportsInterface-bytes4-[`++supportsInterface++`]] +:onERC1155Received: pass:normal[xref:#ERC1155Holder-onERC1155Received-address-address-uint256-uint256-bytes-[`++onERC1155Received++`]] +:onERC1155BatchReceived: pass:normal[xref:#ERC1155Holder-onERC1155BatchReceived-address-address-uint256---uint256---bytes-[`++onERC1155BatchReceived++`]] + +[.contract] +[[ERC1155Holder]] +=== `++ERC1155Holder++` link:https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v5.0.0-rc.0/contracts/token/ERC1155/utils/ERC1155Holder.sol[{github-icon},role=heading-link] + +[.hljs-theme-light.nopadding] +```solidity +import "@openzeppelin/contracts/token/ERC1155/utils/ERC1155Holder.sol"; +``` + +Simple implementation of `IERC1155Receiver` that will allow a contract to hold ERC1155 tokens. + +IMPORTANT: When inheriting this contract, you must include a way to use the received tokens, otherwise they will be +stuck. + +[.contract-index] +.Functions +-- +* {xref-ERC1155Holder-supportsInterface-bytes4-}[`++supportsInterface(interfaceId)++`] +* {xref-ERC1155Holder-onERC1155Received-address-address-uint256-uint256-bytes-}[`++onERC1155Received(, , , , )++`] +* {xref-ERC1155Holder-onERC1155BatchReceived-address-address-uint256---uint256---bytes-}[`++onERC1155BatchReceived(, , , , )++`] + +[.contract-subindex-inherited] +.IERC1155Receiver + +[.contract-subindex-inherited] +.ERC165 + +[.contract-subindex-inherited] +.IERC165 + +-- + +[.contract-item] +[[ERC1155Holder-supportsInterface-bytes4-]] +==== `[.contract-item-name]#++supportsInterface++#++(bytes4 interfaceId) → bool++` [.item-kind]#public# + +See {IERC165-supportsInterface}. + +[.contract-item] +[[ERC1155Holder-onERC1155Received-address-address-uint256-uint256-bytes-]] +==== `[.contract-item-name]#++onERC1155Received++#++(address, address, uint256, uint256, bytes) → bytes4++` [.item-kind]#public# + +[.contract-item] +[[ERC1155Holder-onERC1155BatchReceived-address-address-uint256---uint256---bytes-]] +==== `[.contract-item-name]#++onERC1155BatchReceived++#++(address, address, uint256[], uint256[], bytes) → bytes4++` [.item-kind]#public# + diff --git a/docs/modules/api/pages/token/ERC20.adoc b/docs/modules/api/pages/token/ERC20.adoc new file mode 100644 index 000000000..466992ee2 --- /dev/null +++ b/docs/modules/api/pages/token/ERC20.adoc @@ -0,0 +1,2670 @@ +:github-icon: pass:[] +:IERC20: pass:normal[xref:token/ERC20.adoc#IERC20[`IERC20`]] +:IERC20Metadata: pass:normal[xref:token/ERC20.adoc#IERC20Metadata[`IERC20Metadata`]] +:ERC20: pass:normal[xref:token/ERC20.adoc#ERC20[`ERC20`]] +:ERC20Permit: pass:normal[xref:token/ERC20.adoc#ERC20Permit[`ERC20Permit`]] +:ERC20Burnable: pass:normal[xref:token/ERC20.adoc#ERC20Burnable[`ERC20Burnable`]] +:ERC20Capped: pass:normal[xref:token/ERC20.adoc#ERC20Capped[`ERC20Capped`]] +:ERC20Pausable: pass:normal[xref:token/ERC20.adoc#ERC20Pausable[`ERC20Pausable`]] +:ERC20FlashMint: pass:normal[xref:token/ERC20.adoc#ERC20FlashMint[`ERC20FlashMint`]] +:ERC20Votes: pass:normal[xref:token/ERC20.adoc#ERC20Votes[`ERC20Votes`]] +:ERC20Wrapper: pass:normal[xref:token/ERC20.adoc#ERC20Wrapper[`ERC20Wrapper`]] +:ERC20Votes: pass:normal[xref:token/ERC20.adoc#ERC20Votes[`ERC20Votes`]] +:ERC4626: pass:normal[xref:token/ERC20.adoc#ERC4626[`ERC4626`]] +:SafeERC20: pass:normal[xref:token/ERC20.adoc#SafeERC20[`SafeERC20`]] +:VestingWallet: pass:normal[xref:finance.adoc#VestingWallet[`VestingWallet`]] +:xref-IERC20-totalSupply--: xref:token/ERC20.adoc#IERC20-totalSupply-- +:xref-IERC20-balanceOf-address-: xref:token/ERC20.adoc#IERC20-balanceOf-address- +:xref-IERC20-transfer-address-uint256-: xref:token/ERC20.adoc#IERC20-transfer-address-uint256- +:xref-IERC20-allowance-address-address-: xref:token/ERC20.adoc#IERC20-allowance-address-address- +:xref-IERC20-approve-address-uint256-: xref:token/ERC20.adoc#IERC20-approve-address-uint256- +:xref-IERC20-transferFrom-address-address-uint256-: xref:token/ERC20.adoc#IERC20-transferFrom-address-address-uint256- +:xref-IERC20-Transfer-address-address-uint256-: xref:token/ERC20.adoc#IERC20-Transfer-address-address-uint256- +:xref-IERC20-Approval-address-address-uint256-: xref:token/ERC20.adoc#IERC20-Approval-address-address-uint256- +:xref-IERC20Metadata-name--: xref:token/ERC20.adoc#IERC20Metadata-name-- +:xref-IERC20Metadata-symbol--: xref:token/ERC20.adoc#IERC20Metadata-symbol-- +:xref-IERC20Metadata-decimals--: xref:token/ERC20.adoc#IERC20Metadata-decimals-- +:xref-IERC20-totalSupply--: xref:token/ERC20.adoc#IERC20-totalSupply-- +:xref-IERC20-balanceOf-address-: xref:token/ERC20.adoc#IERC20-balanceOf-address- +:xref-IERC20-transfer-address-uint256-: xref:token/ERC20.adoc#IERC20-transfer-address-uint256- +:xref-IERC20-allowance-address-address-: xref:token/ERC20.adoc#IERC20-allowance-address-address- +:xref-IERC20-approve-address-uint256-: xref:token/ERC20.adoc#IERC20-approve-address-uint256- +:xref-IERC20-transferFrom-address-address-uint256-: xref:token/ERC20.adoc#IERC20-transferFrom-address-address-uint256- +:xref-IERC20-Transfer-address-address-uint256-: xref:token/ERC20.adoc#IERC20-Transfer-address-address-uint256- +:xref-IERC20-Approval-address-address-uint256-: xref:token/ERC20.adoc#IERC20-Approval-address-address-uint256- +:IERC20: pass:normal[xref:token/ERC20.adoc#IERC20[`IERC20`]] +:xref-ERC20-constructor-string-string-: xref:token/ERC20.adoc#ERC20-constructor-string-string- +:xref-ERC20-name--: xref:token/ERC20.adoc#ERC20-name-- +:xref-ERC20-symbol--: xref:token/ERC20.adoc#ERC20-symbol-- +:xref-ERC20-decimals--: xref:token/ERC20.adoc#ERC20-decimals-- +:xref-ERC20-totalSupply--: xref:token/ERC20.adoc#ERC20-totalSupply-- +:xref-ERC20-balanceOf-address-: xref:token/ERC20.adoc#ERC20-balanceOf-address- +:xref-ERC20-transfer-address-uint256-: xref:token/ERC20.adoc#ERC20-transfer-address-uint256- +:xref-ERC20-allowance-address-address-: xref:token/ERC20.adoc#ERC20-allowance-address-address- +:xref-ERC20-approve-address-uint256-: xref:token/ERC20.adoc#ERC20-approve-address-uint256- +:xref-ERC20-transferFrom-address-address-uint256-: xref:token/ERC20.adoc#ERC20-transferFrom-address-address-uint256- +:xref-ERC20-_transfer-address-address-uint256-: xref:token/ERC20.adoc#ERC20-_transfer-address-address-uint256- +:xref-ERC20-_update-address-address-uint256-: xref:token/ERC20.adoc#ERC20-_update-address-address-uint256- +:xref-ERC20-_mint-address-uint256-: xref:token/ERC20.adoc#ERC20-_mint-address-uint256- +:xref-ERC20-_burn-address-uint256-: xref:token/ERC20.adoc#ERC20-_burn-address-uint256- +:xref-ERC20-_approve-address-address-uint256-: xref:token/ERC20.adoc#ERC20-_approve-address-address-uint256- +:xref-ERC20-_approve-address-address-uint256-bool-: xref:token/ERC20.adoc#ERC20-_approve-address-address-uint256-bool- +:xref-ERC20-_spendAllowance-address-address-uint256-: xref:token/ERC20.adoc#ERC20-_spendAllowance-address-address-uint256- +:xref-IERC20-Transfer-address-address-uint256-: xref:token/ERC20.adoc#IERC20-Transfer-address-address-uint256- +:xref-IERC20-Approval-address-address-uint256-: xref:token/ERC20.adoc#IERC20-Approval-address-address-uint256- +:xref-IERC20Errors-ERC20InsufficientBalance-address-uint256-uint256-: xref:interfaces.adoc#IERC20Errors-ERC20InsufficientBalance-address-uint256-uint256- +:xref-IERC20Errors-ERC20InvalidSender-address-: xref:interfaces.adoc#IERC20Errors-ERC20InvalidSender-address- +:xref-IERC20Errors-ERC20InvalidReceiver-address-: xref:interfaces.adoc#IERC20Errors-ERC20InvalidReceiver-address- +:xref-IERC20Errors-ERC20InsufficientAllowance-address-uint256-uint256-: xref:interfaces.adoc#IERC20Errors-ERC20InsufficientAllowance-address-uint256-uint256- +:xref-IERC20Errors-ERC20InvalidApprover-address-: xref:interfaces.adoc#IERC20Errors-ERC20InvalidApprover-address- +:xref-IERC20Errors-ERC20InvalidSpender-address-: xref:interfaces.adoc#IERC20Errors-ERC20InvalidSpender-address- +:IERC20-balanceOf: pass:normal[xref:token/ERC20.adoc#IERC20-balanceOf-address-[`IERC20.balanceOf`]] +:IERC20-transfer: pass:normal[xref:token/ERC20.adoc#IERC20-transfer-address-uint256-[`IERC20.transfer`]] +:IERC20-totalSupply: pass:normal[xref:token/ERC20.adoc#IERC20-totalSupply--[`IERC20.totalSupply`]] +:IERC20-balanceOf: pass:normal[xref:token/ERC20.adoc#IERC20-balanceOf-address-[`IERC20.balanceOf`]] +:IERC20-transfer: pass:normal[xref:token/ERC20.adoc#IERC20-transfer-address-uint256-[`IERC20.transfer`]] +:IERC20-allowance: pass:normal[xref:token/ERC20.adoc#IERC20-allowance-address-address-[`IERC20.allowance`]] +:IERC20-approve: pass:normal[xref:token/ERC20.adoc#IERC20-approve-address-uint256-[`IERC20.approve`]] +:IERC20-transferFrom: pass:normal[xref:token/ERC20.adoc#IERC20-transferFrom-address-address-uint256-[`IERC20.transferFrom`]] +:ERC20: pass:normal[xref:token/ERC20.adoc#ERC20[`ERC20`]] +:IERC20-allowance: pass:normal[xref:token/ERC20.adoc#IERC20-allowance-address-address-[`IERC20.allowance`]] +:IERC20-approve: pass:normal[xref:token/ERC20.adoc#IERC20-approve-address-uint256-[`IERC20.approve`]] +:SafeERC20-safeTransferFrom: pass:normal[xref:token/ERC20.adoc#SafeERC20-safeTransferFrom-contract-IERC20-address-address-uint256-[`SafeERC20.safeTransferFrom`]] +:xref-IERC20Permit-permit-address-address-uint256-uint256-uint8-bytes32-bytes32-: xref:token/ERC20.adoc#IERC20Permit-permit-address-address-uint256-uint256-uint8-bytes32-bytes32- +:xref-IERC20Permit-nonces-address-: xref:token/ERC20.adoc#IERC20Permit-nonces-address- +:xref-IERC20Permit-DOMAIN_SEPARATOR--: xref:token/ERC20.adoc#IERC20Permit-DOMAIN_SEPARATOR-- +:IERC20-approve: pass:normal[xref:token/ERC20.adoc#IERC20-approve-address-uint256-[`IERC20.approve`]] +:EIP712: pass:normal[xref:utils.adoc#EIP712[`EIP712`]] +:IERC20-allowance: pass:normal[xref:token/ERC20.adoc#IERC20-allowance-address-address-[`IERC20.allowance`]] +:IERC20-approve: pass:normal[xref:token/ERC20.adoc#IERC20-approve-address-uint256-[`IERC20.approve`]] +:xref-ERC20Permit-constructor-string-: xref:token/ERC20.adoc#ERC20Permit-constructor-string- +:xref-ERC20Permit-permit-address-address-uint256-uint256-uint8-bytes32-bytes32-: xref:token/ERC20.adoc#ERC20Permit-permit-address-address-uint256-uint256-uint8-bytes32-bytes32- +:xref-ERC20Permit-nonces-address-: xref:token/ERC20.adoc#ERC20Permit-nonces-address- +:xref-ERC20Permit-DOMAIN_SEPARATOR--: xref:token/ERC20.adoc#ERC20Permit-DOMAIN_SEPARATOR-- +:xref-Nonces-_useNonce-address-: xref:utils.adoc#Nonces-_useNonce-address- +:xref-Nonces-_useCheckedNonce-address-uint256-: xref:utils.adoc#Nonces-_useCheckedNonce-address-uint256- +:xref-EIP712-_domainSeparatorV4--: xref:utils.adoc#EIP712-_domainSeparatorV4-- +:xref-EIP712-_hashTypedDataV4-bytes32-: xref:utils.adoc#EIP712-_hashTypedDataV4-bytes32- +:xref-EIP712-eip712Domain--: xref:utils.adoc#EIP712-eip712Domain-- +:xref-EIP712-_EIP712Name--: xref:utils.adoc#EIP712-_EIP712Name-- +:xref-EIP712-_EIP712Version--: xref:utils.adoc#EIP712-_EIP712Version-- +:xref-ERC20-name--: xref:token/ERC20.adoc#ERC20-name-- +:xref-ERC20-symbol--: xref:token/ERC20.adoc#ERC20-symbol-- +:xref-ERC20-decimals--: xref:token/ERC20.adoc#ERC20-decimals-- +:xref-ERC20-totalSupply--: xref:token/ERC20.adoc#ERC20-totalSupply-- +:xref-ERC20-balanceOf-address-: xref:token/ERC20.adoc#ERC20-balanceOf-address- +:xref-ERC20-transfer-address-uint256-: xref:token/ERC20.adoc#ERC20-transfer-address-uint256- +:xref-ERC20-allowance-address-address-: xref:token/ERC20.adoc#ERC20-allowance-address-address- +:xref-ERC20-approve-address-uint256-: xref:token/ERC20.adoc#ERC20-approve-address-uint256- +:xref-ERC20-transferFrom-address-address-uint256-: xref:token/ERC20.adoc#ERC20-transferFrom-address-address-uint256- +:xref-ERC20-_transfer-address-address-uint256-: xref:token/ERC20.adoc#ERC20-_transfer-address-address-uint256- +:xref-ERC20-_update-address-address-uint256-: xref:token/ERC20.adoc#ERC20-_update-address-address-uint256- +:xref-ERC20-_mint-address-uint256-: xref:token/ERC20.adoc#ERC20-_mint-address-uint256- +:xref-ERC20-_burn-address-uint256-: xref:token/ERC20.adoc#ERC20-_burn-address-uint256- +:xref-ERC20-_approve-address-address-uint256-: xref:token/ERC20.adoc#ERC20-_approve-address-address-uint256- +:xref-ERC20-_approve-address-address-uint256-bool-: xref:token/ERC20.adoc#ERC20-_approve-address-address-uint256-bool- +:xref-ERC20-_spendAllowance-address-address-uint256-: xref:token/ERC20.adoc#ERC20-_spendAllowance-address-address-uint256- +:xref-IERC5267-EIP712DomainChanged--: xref:interfaces.adoc#IERC5267-EIP712DomainChanged-- +:xref-IERC20-Transfer-address-address-uint256-: xref:token/ERC20.adoc#IERC20-Transfer-address-address-uint256- +:xref-IERC20-Approval-address-address-uint256-: xref:token/ERC20.adoc#IERC20-Approval-address-address-uint256- +:xref-ERC20Permit-ERC2612ExpiredSignature-uint256-: xref:token/ERC20.adoc#ERC20Permit-ERC2612ExpiredSignature-uint256- +:xref-ERC20Permit-ERC2612InvalidSigner-address-address-: xref:token/ERC20.adoc#ERC20Permit-ERC2612InvalidSigner-address-address- +:xref-Nonces-InvalidAccountNonce-address-uint256-: xref:utils.adoc#Nonces-InvalidAccountNonce-address-uint256- +:xref-IERC20Errors-ERC20InsufficientBalance-address-uint256-uint256-: xref:interfaces.adoc#IERC20Errors-ERC20InsufficientBalance-address-uint256-uint256- +:xref-IERC20Errors-ERC20InvalidSender-address-: xref:interfaces.adoc#IERC20Errors-ERC20InvalidSender-address- +:xref-IERC20Errors-ERC20InvalidReceiver-address-: xref:interfaces.adoc#IERC20Errors-ERC20InvalidReceiver-address- +:xref-IERC20Errors-ERC20InsufficientAllowance-address-uint256-uint256-: xref:interfaces.adoc#IERC20Errors-ERC20InsufficientAllowance-address-uint256-uint256- +:xref-IERC20Errors-ERC20InvalidApprover-address-: xref:interfaces.adoc#IERC20Errors-ERC20InvalidApprover-address- +:xref-IERC20Errors-ERC20InvalidSpender-address-: xref:interfaces.adoc#IERC20Errors-ERC20InvalidSpender-address- +:EIP712: pass:normal[xref:utils.adoc#EIP712[`EIP712`]] +:IERC20-approve: pass:normal[xref:token/ERC20.adoc#IERC20-approve-address-uint256-[`IERC20.approve`]] +:EIP712: pass:normal[xref:utils.adoc#EIP712[`EIP712`]] +:ERC20: pass:normal[xref:token/ERC20.adoc#ERC20[`ERC20`]] +:xref-ERC20Burnable-burn-uint256-: xref:token/ERC20.adoc#ERC20Burnable-burn-uint256- +:xref-ERC20Burnable-burnFrom-address-uint256-: xref:token/ERC20.adoc#ERC20Burnable-burnFrom-address-uint256- +:xref-ERC20-name--: xref:token/ERC20.adoc#ERC20-name-- +:xref-ERC20-symbol--: xref:token/ERC20.adoc#ERC20-symbol-- +:xref-ERC20-decimals--: xref:token/ERC20.adoc#ERC20-decimals-- +:xref-ERC20-totalSupply--: xref:token/ERC20.adoc#ERC20-totalSupply-- +:xref-ERC20-balanceOf-address-: xref:token/ERC20.adoc#ERC20-balanceOf-address- +:xref-ERC20-transfer-address-uint256-: xref:token/ERC20.adoc#ERC20-transfer-address-uint256- +:xref-ERC20-allowance-address-address-: xref:token/ERC20.adoc#ERC20-allowance-address-address- +:xref-ERC20-approve-address-uint256-: xref:token/ERC20.adoc#ERC20-approve-address-uint256- +:xref-ERC20-transferFrom-address-address-uint256-: xref:token/ERC20.adoc#ERC20-transferFrom-address-address-uint256- +:xref-ERC20-_transfer-address-address-uint256-: xref:token/ERC20.adoc#ERC20-_transfer-address-address-uint256- +:xref-ERC20-_update-address-address-uint256-: xref:token/ERC20.adoc#ERC20-_update-address-address-uint256- +:xref-ERC20-_mint-address-uint256-: xref:token/ERC20.adoc#ERC20-_mint-address-uint256- +:xref-ERC20-_burn-address-uint256-: xref:token/ERC20.adoc#ERC20-_burn-address-uint256- +:xref-ERC20-_approve-address-address-uint256-: xref:token/ERC20.adoc#ERC20-_approve-address-address-uint256- +:xref-ERC20-_approve-address-address-uint256-bool-: xref:token/ERC20.adoc#ERC20-_approve-address-address-uint256-bool- +:xref-ERC20-_spendAllowance-address-address-uint256-: xref:token/ERC20.adoc#ERC20-_spendAllowance-address-address-uint256- +:xref-IERC20-Transfer-address-address-uint256-: xref:token/ERC20.adoc#IERC20-Transfer-address-address-uint256- +:xref-IERC20-Approval-address-address-uint256-: xref:token/ERC20.adoc#IERC20-Approval-address-address-uint256- +:xref-IERC20Errors-ERC20InsufficientBalance-address-uint256-uint256-: xref:interfaces.adoc#IERC20Errors-ERC20InsufficientBalance-address-uint256-uint256- +:xref-IERC20Errors-ERC20InvalidSender-address-: xref:interfaces.adoc#IERC20Errors-ERC20InvalidSender-address- +:xref-IERC20Errors-ERC20InvalidReceiver-address-: xref:interfaces.adoc#IERC20Errors-ERC20InvalidReceiver-address- +:xref-IERC20Errors-ERC20InsufficientAllowance-address-uint256-uint256-: xref:interfaces.adoc#IERC20Errors-ERC20InsufficientAllowance-address-uint256-uint256- +:xref-IERC20Errors-ERC20InvalidApprover-address-: xref:interfaces.adoc#IERC20Errors-ERC20InvalidApprover-address- +:xref-IERC20Errors-ERC20InvalidSpender-address-: xref:interfaces.adoc#IERC20Errors-ERC20InvalidSpender-address- +:ERC20-_burn: pass:normal[xref:token/ERC20.adoc#ERC20-_burn-address-uint256-[`ERC20._burn`]] +:ERC20-_burn: pass:normal[xref:token/ERC20.adoc#ERC20-_burn-address-uint256-[`ERC20._burn`]] +:ERC20-allowance: pass:normal[xref:token/ERC20.adoc#ERC20-allowance-address-address-[`ERC20.allowance`]] +:ERC20: pass:normal[xref:token/ERC20.adoc#ERC20[`ERC20`]] +:xref-ERC20Capped-constructor-uint256-: xref:token/ERC20.adoc#ERC20Capped-constructor-uint256- +:xref-ERC20Capped-cap--: xref:token/ERC20.adoc#ERC20Capped-cap-- +:xref-ERC20Capped-_update-address-address-uint256-: xref:token/ERC20.adoc#ERC20Capped-_update-address-address-uint256- +:xref-ERC20-name--: xref:token/ERC20.adoc#ERC20-name-- +:xref-ERC20-symbol--: xref:token/ERC20.adoc#ERC20-symbol-- +:xref-ERC20-decimals--: xref:token/ERC20.adoc#ERC20-decimals-- +:xref-ERC20-totalSupply--: xref:token/ERC20.adoc#ERC20-totalSupply-- +:xref-ERC20-balanceOf-address-: xref:token/ERC20.adoc#ERC20-balanceOf-address- +:xref-ERC20-transfer-address-uint256-: xref:token/ERC20.adoc#ERC20-transfer-address-uint256- +:xref-ERC20-allowance-address-address-: xref:token/ERC20.adoc#ERC20-allowance-address-address- +:xref-ERC20-approve-address-uint256-: xref:token/ERC20.adoc#ERC20-approve-address-uint256- +:xref-ERC20-transferFrom-address-address-uint256-: xref:token/ERC20.adoc#ERC20-transferFrom-address-address-uint256- +:xref-ERC20-_transfer-address-address-uint256-: xref:token/ERC20.adoc#ERC20-_transfer-address-address-uint256- +:xref-ERC20-_mint-address-uint256-: xref:token/ERC20.adoc#ERC20-_mint-address-uint256- +:xref-ERC20-_burn-address-uint256-: xref:token/ERC20.adoc#ERC20-_burn-address-uint256- +:xref-ERC20-_approve-address-address-uint256-: xref:token/ERC20.adoc#ERC20-_approve-address-address-uint256- +:xref-ERC20-_approve-address-address-uint256-bool-: xref:token/ERC20.adoc#ERC20-_approve-address-address-uint256-bool- +:xref-ERC20-_spendAllowance-address-address-uint256-: xref:token/ERC20.adoc#ERC20-_spendAllowance-address-address-uint256- +:xref-IERC20-Transfer-address-address-uint256-: xref:token/ERC20.adoc#IERC20-Transfer-address-address-uint256- +:xref-IERC20-Approval-address-address-uint256-: xref:token/ERC20.adoc#IERC20-Approval-address-address-uint256- +:xref-ERC20Capped-ERC20ExceededCap-uint256-uint256-: xref:token/ERC20.adoc#ERC20Capped-ERC20ExceededCap-uint256-uint256- +:xref-ERC20Capped-ERC20InvalidCap-uint256-: xref:token/ERC20.adoc#ERC20Capped-ERC20InvalidCap-uint256- +:xref-IERC20Errors-ERC20InsufficientBalance-address-uint256-uint256-: xref:interfaces.adoc#IERC20Errors-ERC20InsufficientBalance-address-uint256-uint256- +:xref-IERC20Errors-ERC20InvalidSender-address-: xref:interfaces.adoc#IERC20Errors-ERC20InvalidSender-address- +:xref-IERC20Errors-ERC20InvalidReceiver-address-: xref:interfaces.adoc#IERC20Errors-ERC20InvalidReceiver-address- +:xref-IERC20Errors-ERC20InsufficientAllowance-address-uint256-uint256-: xref:interfaces.adoc#IERC20Errors-ERC20InsufficientAllowance-address-uint256-uint256- +:xref-IERC20Errors-ERC20InvalidApprover-address-: xref:interfaces.adoc#IERC20Errors-ERC20InvalidApprover-address- +:xref-IERC20Errors-ERC20InvalidSpender-address-: xref:interfaces.adoc#IERC20Errors-ERC20InvalidSpender-address- +:ERC20-_update: pass:normal[xref:token/ERC20.adoc#ERC20-_update-address-address-uint256-[`ERC20._update`]] +:Pausable-_pause: pass:normal[xref:utils.adoc#Pausable-_pause--[`Pausable._pause`]] +:Pausable-_unpause: pass:normal[xref:utils.adoc#Pausable-_unpause--[`Pausable._unpause`]] +:AccessControl: pass:normal[xref:access.adoc#AccessControl[`AccessControl`]] +:Ownable: pass:normal[xref:access.adoc#Ownable[`Ownable`]] +:xref-ERC20Pausable-_update-address-address-uint256-: xref:token/ERC20.adoc#ERC20Pausable-_update-address-address-uint256- +:xref-Pausable-paused--: xref:utils.adoc#Pausable-paused-- +:xref-Pausable-_requireNotPaused--: xref:utils.adoc#Pausable-_requireNotPaused-- +:xref-Pausable-_requirePaused--: xref:utils.adoc#Pausable-_requirePaused-- +:xref-Pausable-_pause--: xref:utils.adoc#Pausable-_pause-- +:xref-Pausable-_unpause--: xref:utils.adoc#Pausable-_unpause-- +:xref-ERC20-name--: xref:token/ERC20.adoc#ERC20-name-- +:xref-ERC20-symbol--: xref:token/ERC20.adoc#ERC20-symbol-- +:xref-ERC20-decimals--: xref:token/ERC20.adoc#ERC20-decimals-- +:xref-ERC20-totalSupply--: xref:token/ERC20.adoc#ERC20-totalSupply-- +:xref-ERC20-balanceOf-address-: xref:token/ERC20.adoc#ERC20-balanceOf-address- +:xref-ERC20-transfer-address-uint256-: xref:token/ERC20.adoc#ERC20-transfer-address-uint256- +:xref-ERC20-allowance-address-address-: xref:token/ERC20.adoc#ERC20-allowance-address-address- +:xref-ERC20-approve-address-uint256-: xref:token/ERC20.adoc#ERC20-approve-address-uint256- +:xref-ERC20-transferFrom-address-address-uint256-: xref:token/ERC20.adoc#ERC20-transferFrom-address-address-uint256- +:xref-ERC20-_transfer-address-address-uint256-: xref:token/ERC20.adoc#ERC20-_transfer-address-address-uint256- +:xref-ERC20-_mint-address-uint256-: xref:token/ERC20.adoc#ERC20-_mint-address-uint256- +:xref-ERC20-_burn-address-uint256-: xref:token/ERC20.adoc#ERC20-_burn-address-uint256- +:xref-ERC20-_approve-address-address-uint256-: xref:token/ERC20.adoc#ERC20-_approve-address-address-uint256- +:xref-ERC20-_approve-address-address-uint256-bool-: xref:token/ERC20.adoc#ERC20-_approve-address-address-uint256-bool- +:xref-ERC20-_spendAllowance-address-address-uint256-: xref:token/ERC20.adoc#ERC20-_spendAllowance-address-address-uint256- +:xref-Pausable-Paused-address-: xref:utils.adoc#Pausable-Paused-address- +:xref-Pausable-Unpaused-address-: xref:utils.adoc#Pausable-Unpaused-address- +:xref-IERC20-Transfer-address-address-uint256-: xref:token/ERC20.adoc#IERC20-Transfer-address-address-uint256- +:xref-IERC20-Approval-address-address-uint256-: xref:token/ERC20.adoc#IERC20-Approval-address-address-uint256- +:xref-Pausable-EnforcedPause--: xref:utils.adoc#Pausable-EnforcedPause-- +:xref-Pausable-ExpectedPause--: xref:utils.adoc#Pausable-ExpectedPause-- +:xref-IERC20Errors-ERC20InsufficientBalance-address-uint256-uint256-: xref:interfaces.adoc#IERC20Errors-ERC20InsufficientBalance-address-uint256-uint256- +:xref-IERC20Errors-ERC20InvalidSender-address-: xref:interfaces.adoc#IERC20Errors-ERC20InvalidSender-address- +:xref-IERC20Errors-ERC20InvalidReceiver-address-: xref:interfaces.adoc#IERC20Errors-ERC20InvalidReceiver-address- +:xref-IERC20Errors-ERC20InsufficientAllowance-address-uint256-uint256-: xref:interfaces.adoc#IERC20Errors-ERC20InsufficientAllowance-address-uint256-uint256- +:xref-IERC20Errors-ERC20InvalidApprover-address-: xref:interfaces.adoc#IERC20Errors-ERC20InvalidApprover-address- +:xref-IERC20Errors-ERC20InvalidSpender-address-: xref:interfaces.adoc#IERC20Errors-ERC20InvalidSpender-address- +:ERC20-_update: pass:normal[xref:token/ERC20.adoc#ERC20-_update-address-address-uint256-[`ERC20._update`]] +:xref-ERC20Votes-_maxSupply--: xref:token/ERC20.adoc#ERC20Votes-_maxSupply-- +:xref-ERC20Votes-_update-address-address-uint256-: xref:token/ERC20.adoc#ERC20Votes-_update-address-address-uint256- +:xref-ERC20Votes-_getVotingUnits-address-: xref:token/ERC20.adoc#ERC20Votes-_getVotingUnits-address- +:xref-ERC20Votes-numCheckpoints-address-: xref:token/ERC20.adoc#ERC20Votes-numCheckpoints-address- +:xref-ERC20Votes-checkpoints-address-uint32-: xref:token/ERC20.adoc#ERC20Votes-checkpoints-address-uint32- +:xref-Votes-clock--: xref:governance.adoc#Votes-clock-- +:xref-Votes-CLOCK_MODE--: xref:governance.adoc#Votes-CLOCK_MODE-- +:xref-Votes-getVotes-address-: xref:governance.adoc#Votes-getVotes-address- +:xref-Votes-getPastVotes-address-uint256-: xref:governance.adoc#Votes-getPastVotes-address-uint256- +:xref-Votes-getPastTotalSupply-uint256-: xref:governance.adoc#Votes-getPastTotalSupply-uint256- +:xref-Votes-_getTotalSupply--: xref:governance.adoc#Votes-_getTotalSupply-- +:xref-Votes-delegates-address-: xref:governance.adoc#Votes-delegates-address- +:xref-Votes-delegate-address-: xref:governance.adoc#Votes-delegate-address- +:xref-Votes-delegateBySig-address-uint256-uint256-uint8-bytes32-bytes32-: xref:governance.adoc#Votes-delegateBySig-address-uint256-uint256-uint8-bytes32-bytes32- +:xref-Votes-_delegate-address-address-: xref:governance.adoc#Votes-_delegate-address-address- +:xref-Votes-_transferVotingUnits-address-address-uint256-: xref:governance.adoc#Votes-_transferVotingUnits-address-address-uint256- +:xref-Votes-_numCheckpoints-address-: xref:governance.adoc#Votes-_numCheckpoints-address- +:xref-Votes-_checkpoints-address-uint32-: xref:governance.adoc#Votes-_checkpoints-address-uint32- +:xref-Nonces-nonces-address-: xref:utils.adoc#Nonces-nonces-address- +:xref-Nonces-_useNonce-address-: xref:utils.adoc#Nonces-_useNonce-address- +:xref-Nonces-_useCheckedNonce-address-uint256-: xref:utils.adoc#Nonces-_useCheckedNonce-address-uint256- +:xref-EIP712-_domainSeparatorV4--: xref:utils.adoc#EIP712-_domainSeparatorV4-- +:xref-EIP712-_hashTypedDataV4-bytes32-: xref:utils.adoc#EIP712-_hashTypedDataV4-bytes32- +:xref-EIP712-eip712Domain--: xref:utils.adoc#EIP712-eip712Domain-- +:xref-EIP712-_EIP712Name--: xref:utils.adoc#EIP712-_EIP712Name-- +:xref-EIP712-_EIP712Version--: xref:utils.adoc#EIP712-_EIP712Version-- +:xref-ERC20-name--: xref:token/ERC20.adoc#ERC20-name-- +:xref-ERC20-symbol--: xref:token/ERC20.adoc#ERC20-symbol-- +:xref-ERC20-decimals--: xref:token/ERC20.adoc#ERC20-decimals-- +:xref-ERC20-totalSupply--: xref:token/ERC20.adoc#ERC20-totalSupply-- +:xref-ERC20-balanceOf-address-: xref:token/ERC20.adoc#ERC20-balanceOf-address- +:xref-ERC20-transfer-address-uint256-: xref:token/ERC20.adoc#ERC20-transfer-address-uint256- +:xref-ERC20-allowance-address-address-: xref:token/ERC20.adoc#ERC20-allowance-address-address- +:xref-ERC20-approve-address-uint256-: xref:token/ERC20.adoc#ERC20-approve-address-uint256- +:xref-ERC20-transferFrom-address-address-uint256-: xref:token/ERC20.adoc#ERC20-transferFrom-address-address-uint256- +:xref-ERC20-_transfer-address-address-uint256-: xref:token/ERC20.adoc#ERC20-_transfer-address-address-uint256- +:xref-ERC20-_mint-address-uint256-: xref:token/ERC20.adoc#ERC20-_mint-address-uint256- +:xref-ERC20-_burn-address-uint256-: xref:token/ERC20.adoc#ERC20-_burn-address-uint256- +:xref-ERC20-_approve-address-address-uint256-: xref:token/ERC20.adoc#ERC20-_approve-address-address-uint256- +:xref-ERC20-_approve-address-address-uint256-bool-: xref:token/ERC20.adoc#ERC20-_approve-address-address-uint256-bool- +:xref-ERC20-_spendAllowance-address-address-uint256-: xref:token/ERC20.adoc#ERC20-_spendAllowance-address-address-uint256- +:xref-IVotes-DelegateChanged-address-address-address-: xref:governance.adoc#IVotes-DelegateChanged-address-address-address- +:xref-IVotes-DelegateVotesChanged-address-uint256-uint256-: xref:governance.adoc#IVotes-DelegateVotesChanged-address-uint256-uint256- +:xref-IERC5267-EIP712DomainChanged--: xref:interfaces.adoc#IERC5267-EIP712DomainChanged-- +:xref-IERC20-Transfer-address-address-uint256-: xref:token/ERC20.adoc#IERC20-Transfer-address-address-uint256- +:xref-IERC20-Approval-address-address-uint256-: xref:token/ERC20.adoc#IERC20-Approval-address-address-uint256- +:xref-ERC20Votes-ERC20ExceededSafeSupply-uint256-uint256-: xref:token/ERC20.adoc#ERC20Votes-ERC20ExceededSafeSupply-uint256-uint256- +:xref-Votes-ERC6372InconsistentClock--: xref:governance.adoc#Votes-ERC6372InconsistentClock-- +:xref-Votes-ERC5805FutureLookup-uint256-uint48-: xref:governance.adoc#Votes-ERC5805FutureLookup-uint256-uint48- +:xref-IVotes-VotesExpiredSignature-uint256-: xref:governance.adoc#IVotes-VotesExpiredSignature-uint256- +:xref-Nonces-InvalidAccountNonce-address-uint256-: xref:utils.adoc#Nonces-InvalidAccountNonce-address-uint256- +:xref-IERC20Errors-ERC20InsufficientBalance-address-uint256-uint256-: xref:interfaces.adoc#IERC20Errors-ERC20InsufficientBalance-address-uint256-uint256- +:xref-IERC20Errors-ERC20InvalidSender-address-: xref:interfaces.adoc#IERC20Errors-ERC20InvalidSender-address- +:xref-IERC20Errors-ERC20InvalidReceiver-address-: xref:interfaces.adoc#IERC20Errors-ERC20InvalidReceiver-address- +:xref-IERC20Errors-ERC20InsufficientAllowance-address-uint256-uint256-: xref:interfaces.adoc#IERC20Errors-ERC20InsufficientAllowance-address-uint256-uint256- +:xref-IERC20Errors-ERC20InvalidApprover-address-: xref:interfaces.adoc#IERC20Errors-ERC20InvalidApprover-address- +:xref-IERC20Errors-ERC20InvalidSpender-address-: xref:interfaces.adoc#IERC20Errors-ERC20InvalidSpender-address- +:Votes: pass:normal[xref:governance.adoc#Votes[`Votes`]] +:IVotes-DelegateVotesChanged: pass:normal[xref:governance.adoc#IVotes-DelegateVotesChanged-address-uint256-uint256-[`IVotes.DelegateVotesChanged`]] +:ERC20Votes: pass:normal[xref:token/ERC20.adoc#ERC20Votes[`ERC20Votes`]] +:xref-ERC20Wrapper-constructor-contract-IERC20-: xref:token/ERC20.adoc#ERC20Wrapper-constructor-contract-IERC20- +:xref-ERC20Wrapper-decimals--: xref:token/ERC20.adoc#ERC20Wrapper-decimals-- +:xref-ERC20Wrapper-underlying--: xref:token/ERC20.adoc#ERC20Wrapper-underlying-- +:xref-ERC20Wrapper-depositFor-address-uint256-: xref:token/ERC20.adoc#ERC20Wrapper-depositFor-address-uint256- +:xref-ERC20Wrapper-withdrawTo-address-uint256-: xref:token/ERC20.adoc#ERC20Wrapper-withdrawTo-address-uint256- +:xref-ERC20Wrapper-_recover-address-: xref:token/ERC20.adoc#ERC20Wrapper-_recover-address- +:xref-ERC20-name--: xref:token/ERC20.adoc#ERC20-name-- +:xref-ERC20-symbol--: xref:token/ERC20.adoc#ERC20-symbol-- +:xref-ERC20-totalSupply--: xref:token/ERC20.adoc#ERC20-totalSupply-- +:xref-ERC20-balanceOf-address-: xref:token/ERC20.adoc#ERC20-balanceOf-address- +:xref-ERC20-transfer-address-uint256-: xref:token/ERC20.adoc#ERC20-transfer-address-uint256- +:xref-ERC20-allowance-address-address-: xref:token/ERC20.adoc#ERC20-allowance-address-address- +:xref-ERC20-approve-address-uint256-: xref:token/ERC20.adoc#ERC20-approve-address-uint256- +:xref-ERC20-transferFrom-address-address-uint256-: xref:token/ERC20.adoc#ERC20-transferFrom-address-address-uint256- +:xref-ERC20-_transfer-address-address-uint256-: xref:token/ERC20.adoc#ERC20-_transfer-address-address-uint256- +:xref-ERC20-_update-address-address-uint256-: xref:token/ERC20.adoc#ERC20-_update-address-address-uint256- +:xref-ERC20-_mint-address-uint256-: xref:token/ERC20.adoc#ERC20-_mint-address-uint256- +:xref-ERC20-_burn-address-uint256-: xref:token/ERC20.adoc#ERC20-_burn-address-uint256- +:xref-ERC20-_approve-address-address-uint256-: xref:token/ERC20.adoc#ERC20-_approve-address-address-uint256- +:xref-ERC20-_approve-address-address-uint256-bool-: xref:token/ERC20.adoc#ERC20-_approve-address-address-uint256-bool- +:xref-ERC20-_spendAllowance-address-address-uint256-: xref:token/ERC20.adoc#ERC20-_spendAllowance-address-address-uint256- +:xref-IERC20-Transfer-address-address-uint256-: xref:token/ERC20.adoc#IERC20-Transfer-address-address-uint256- +:xref-IERC20-Approval-address-address-uint256-: xref:token/ERC20.adoc#IERC20-Approval-address-address-uint256- +:xref-ERC20Wrapper-ERC20InvalidUnderlying-address-: xref:token/ERC20.adoc#ERC20Wrapper-ERC20InvalidUnderlying-address- +:xref-IERC20Errors-ERC20InsufficientBalance-address-uint256-uint256-: xref:interfaces.adoc#IERC20Errors-ERC20InsufficientBalance-address-uint256-uint256- +:xref-IERC20Errors-ERC20InvalidSender-address-: xref:interfaces.adoc#IERC20Errors-ERC20InvalidSender-address- +:xref-IERC20Errors-ERC20InvalidReceiver-address-: xref:interfaces.adoc#IERC20Errors-ERC20InvalidReceiver-address- +:xref-IERC20Errors-ERC20InsufficientAllowance-address-uint256-uint256-: xref:interfaces.adoc#IERC20Errors-ERC20InsufficientAllowance-address-uint256-uint256- +:xref-IERC20Errors-ERC20InvalidApprover-address-: xref:interfaces.adoc#IERC20Errors-ERC20InvalidApprover-address- +:xref-IERC20Errors-ERC20InvalidSpender-address-: xref:interfaces.adoc#IERC20Errors-ERC20InvalidSpender-address- +:ERC20-decimals: pass:normal[xref:token/ERC20.adoc#ERC20-decimals--[`ERC20.decimals`]] +:ERC20Capped: pass:normal[xref:token/ERC20.adoc#ERC20Capped[`ERC20Capped`]] +:ERC20Votes: pass:normal[xref:token/ERC20.adoc#ERC20Votes[`ERC20Votes`]] +:xref-ERC20FlashMint-maxFlashLoan-address-: xref:token/ERC20.adoc#ERC20FlashMint-maxFlashLoan-address- +:xref-ERC20FlashMint-flashFee-address-uint256-: xref:token/ERC20.adoc#ERC20FlashMint-flashFee-address-uint256- +:xref-ERC20FlashMint-_flashFee-address-uint256-: xref:token/ERC20.adoc#ERC20FlashMint-_flashFee-address-uint256- +:xref-ERC20FlashMint-_flashFeeReceiver--: xref:token/ERC20.adoc#ERC20FlashMint-_flashFeeReceiver-- +:xref-ERC20FlashMint-flashLoan-contract-IERC3156FlashBorrower-address-uint256-bytes-: xref:token/ERC20.adoc#ERC20FlashMint-flashLoan-contract-IERC3156FlashBorrower-address-uint256-bytes- +:xref-ERC20-name--: xref:token/ERC20.adoc#ERC20-name-- +:xref-ERC20-symbol--: xref:token/ERC20.adoc#ERC20-symbol-- +:xref-ERC20-decimals--: xref:token/ERC20.adoc#ERC20-decimals-- +:xref-ERC20-totalSupply--: xref:token/ERC20.adoc#ERC20-totalSupply-- +:xref-ERC20-balanceOf-address-: xref:token/ERC20.adoc#ERC20-balanceOf-address- +:xref-ERC20-transfer-address-uint256-: xref:token/ERC20.adoc#ERC20-transfer-address-uint256- +:xref-ERC20-allowance-address-address-: xref:token/ERC20.adoc#ERC20-allowance-address-address- +:xref-ERC20-approve-address-uint256-: xref:token/ERC20.adoc#ERC20-approve-address-uint256- +:xref-ERC20-transferFrom-address-address-uint256-: xref:token/ERC20.adoc#ERC20-transferFrom-address-address-uint256- +:xref-ERC20-_transfer-address-address-uint256-: xref:token/ERC20.adoc#ERC20-_transfer-address-address-uint256- +:xref-ERC20-_update-address-address-uint256-: xref:token/ERC20.adoc#ERC20-_update-address-address-uint256- +:xref-ERC20-_mint-address-uint256-: xref:token/ERC20.adoc#ERC20-_mint-address-uint256- +:xref-ERC20-_burn-address-uint256-: xref:token/ERC20.adoc#ERC20-_burn-address-uint256- +:xref-ERC20-_approve-address-address-uint256-: xref:token/ERC20.adoc#ERC20-_approve-address-address-uint256- +:xref-ERC20-_approve-address-address-uint256-bool-: xref:token/ERC20.adoc#ERC20-_approve-address-address-uint256-bool- +:xref-ERC20-_spendAllowance-address-address-uint256-: xref:token/ERC20.adoc#ERC20-_spendAllowance-address-address-uint256- +:xref-IERC20-Transfer-address-address-uint256-: xref:token/ERC20.adoc#IERC20-Transfer-address-address-uint256- +:xref-IERC20-Approval-address-address-uint256-: xref:token/ERC20.adoc#IERC20-Approval-address-address-uint256- +:xref-ERC20FlashMint-ERC3156UnsupportedToken-address-: xref:token/ERC20.adoc#ERC20FlashMint-ERC3156UnsupportedToken-address- +:xref-ERC20FlashMint-ERC3156ExceededMaxLoan-uint256-: xref:token/ERC20.adoc#ERC20FlashMint-ERC3156ExceededMaxLoan-uint256- +:xref-ERC20FlashMint-ERC3156InvalidReceiver-address-: xref:token/ERC20.adoc#ERC20FlashMint-ERC3156InvalidReceiver-address- +:xref-IERC20Errors-ERC20InsufficientBalance-address-uint256-uint256-: xref:interfaces.adoc#IERC20Errors-ERC20InsufficientBalance-address-uint256-uint256- +:xref-IERC20Errors-ERC20InvalidSender-address-: xref:interfaces.adoc#IERC20Errors-ERC20InvalidSender-address- +:xref-IERC20Errors-ERC20InvalidReceiver-address-: xref:interfaces.adoc#IERC20Errors-ERC20InvalidReceiver-address- +:xref-IERC20Errors-ERC20InsufficientAllowance-address-uint256-uint256-: xref:interfaces.adoc#IERC20Errors-ERC20InsufficientAllowance-address-uint256-uint256- +:xref-IERC20Errors-ERC20InvalidApprover-address-: xref:interfaces.adoc#IERC20Errors-ERC20InvalidApprover-address- +:xref-IERC20Errors-ERC20InvalidSpender-address-: xref:interfaces.adoc#IERC20Errors-ERC20InvalidSpender-address- +:IERC3156FlashBorrower: pass:normal[xref:interfaces.adoc#IERC3156FlashBorrower[`IERC3156FlashBorrower`]] +:xref-ERC4626-constructor-contract-IERC20-: xref:token/ERC20.adoc#ERC4626-constructor-contract-IERC20- +:xref-ERC4626-decimals--: xref:token/ERC20.adoc#ERC4626-decimals-- +:xref-ERC4626-asset--: xref:token/ERC20.adoc#ERC4626-asset-- +:xref-ERC4626-totalAssets--: xref:token/ERC20.adoc#ERC4626-totalAssets-- +:xref-ERC4626-convertToShares-uint256-: xref:token/ERC20.adoc#ERC4626-convertToShares-uint256- +:xref-ERC4626-convertToAssets-uint256-: xref:token/ERC20.adoc#ERC4626-convertToAssets-uint256- +:xref-ERC4626-maxDeposit-address-: xref:token/ERC20.adoc#ERC4626-maxDeposit-address- +:xref-ERC4626-maxMint-address-: xref:token/ERC20.adoc#ERC4626-maxMint-address- +:xref-ERC4626-maxWithdraw-address-: xref:token/ERC20.adoc#ERC4626-maxWithdraw-address- +:xref-ERC4626-maxRedeem-address-: xref:token/ERC20.adoc#ERC4626-maxRedeem-address- +:xref-ERC4626-previewDeposit-uint256-: xref:token/ERC20.adoc#ERC4626-previewDeposit-uint256- +:xref-ERC4626-previewMint-uint256-: xref:token/ERC20.adoc#ERC4626-previewMint-uint256- +:xref-ERC4626-previewWithdraw-uint256-: xref:token/ERC20.adoc#ERC4626-previewWithdraw-uint256- +:xref-ERC4626-previewRedeem-uint256-: xref:token/ERC20.adoc#ERC4626-previewRedeem-uint256- +:xref-ERC4626-deposit-uint256-address-: xref:token/ERC20.adoc#ERC4626-deposit-uint256-address- +:xref-ERC4626-mint-uint256-address-: xref:token/ERC20.adoc#ERC4626-mint-uint256-address- +:xref-ERC4626-withdraw-uint256-address-address-: xref:token/ERC20.adoc#ERC4626-withdraw-uint256-address-address- +:xref-ERC4626-redeem-uint256-address-address-: xref:token/ERC20.adoc#ERC4626-redeem-uint256-address-address- +:xref-ERC4626-_convertToShares-uint256-enum-Math-Rounding-: xref:token/ERC20.adoc#ERC4626-_convertToShares-uint256-enum-Math-Rounding- +:xref-ERC4626-_convertToAssets-uint256-enum-Math-Rounding-: xref:token/ERC20.adoc#ERC4626-_convertToAssets-uint256-enum-Math-Rounding- +:xref-ERC4626-_deposit-address-address-uint256-uint256-: xref:token/ERC20.adoc#ERC4626-_deposit-address-address-uint256-uint256- +:xref-ERC4626-_withdraw-address-address-address-uint256-uint256-: xref:token/ERC20.adoc#ERC4626-_withdraw-address-address-address-uint256-uint256- +:xref-ERC4626-_decimalsOffset--: xref:token/ERC20.adoc#ERC4626-_decimalsOffset-- +:xref-ERC20-name--: xref:token/ERC20.adoc#ERC20-name-- +:xref-ERC20-symbol--: xref:token/ERC20.adoc#ERC20-symbol-- +:xref-ERC20-totalSupply--: xref:token/ERC20.adoc#ERC20-totalSupply-- +:xref-ERC20-balanceOf-address-: xref:token/ERC20.adoc#ERC20-balanceOf-address- +:xref-ERC20-transfer-address-uint256-: xref:token/ERC20.adoc#ERC20-transfer-address-uint256- +:xref-ERC20-allowance-address-address-: xref:token/ERC20.adoc#ERC20-allowance-address-address- +:xref-ERC20-approve-address-uint256-: xref:token/ERC20.adoc#ERC20-approve-address-uint256- +:xref-ERC20-transferFrom-address-address-uint256-: xref:token/ERC20.adoc#ERC20-transferFrom-address-address-uint256- +:xref-ERC20-_transfer-address-address-uint256-: xref:token/ERC20.adoc#ERC20-_transfer-address-address-uint256- +:xref-ERC20-_update-address-address-uint256-: xref:token/ERC20.adoc#ERC20-_update-address-address-uint256- +:xref-ERC20-_mint-address-uint256-: xref:token/ERC20.adoc#ERC20-_mint-address-uint256- +:xref-ERC20-_burn-address-uint256-: xref:token/ERC20.adoc#ERC20-_burn-address-uint256- +:xref-ERC20-_approve-address-address-uint256-: xref:token/ERC20.adoc#ERC20-_approve-address-address-uint256- +:xref-ERC20-_approve-address-address-uint256-bool-: xref:token/ERC20.adoc#ERC20-_approve-address-address-uint256-bool- +:xref-ERC20-_spendAllowance-address-address-uint256-: xref:token/ERC20.adoc#ERC20-_spendAllowance-address-address-uint256- +:xref-IERC4626-Deposit-address-address-uint256-uint256-: xref:interfaces.adoc#IERC4626-Deposit-address-address-uint256-uint256- +:xref-IERC4626-Withdraw-address-address-address-uint256-uint256-: xref:interfaces.adoc#IERC4626-Withdraw-address-address-address-uint256-uint256- +:xref-IERC20-Transfer-address-address-uint256-: xref:token/ERC20.adoc#IERC20-Transfer-address-address-uint256- +:xref-IERC20-Approval-address-address-uint256-: xref:token/ERC20.adoc#IERC20-Approval-address-address-uint256- +:xref-ERC4626-ERC4626ExceededMaxDeposit-address-uint256-uint256-: xref:token/ERC20.adoc#ERC4626-ERC4626ExceededMaxDeposit-address-uint256-uint256- +:xref-ERC4626-ERC4626ExceededMaxMint-address-uint256-uint256-: xref:token/ERC20.adoc#ERC4626-ERC4626ExceededMaxMint-address-uint256-uint256- +:xref-ERC4626-ERC4626ExceededMaxWithdraw-address-uint256-uint256-: xref:token/ERC20.adoc#ERC4626-ERC4626ExceededMaxWithdraw-address-uint256-uint256- +:xref-ERC4626-ERC4626ExceededMaxRedeem-address-uint256-uint256-: xref:token/ERC20.adoc#ERC4626-ERC4626ExceededMaxRedeem-address-uint256-uint256- +:xref-IERC20Errors-ERC20InsufficientBalance-address-uint256-uint256-: xref:interfaces.adoc#IERC20Errors-ERC20InsufficientBalance-address-uint256-uint256- +:xref-IERC20Errors-ERC20InvalidSender-address-: xref:interfaces.adoc#IERC20Errors-ERC20InvalidSender-address- +:xref-IERC20Errors-ERC20InvalidReceiver-address-: xref:interfaces.adoc#IERC20Errors-ERC20InvalidReceiver-address- +:xref-IERC20Errors-ERC20InsufficientAllowance-address-uint256-uint256-: xref:interfaces.adoc#IERC20Errors-ERC20InsufficientAllowance-address-uint256-uint256- +:xref-IERC20Errors-ERC20InvalidApprover-address-: xref:interfaces.adoc#IERC20Errors-ERC20InvalidApprover-address- +:xref-IERC20Errors-ERC20InvalidSpender-address-: xref:interfaces.adoc#IERC20Errors-ERC20InvalidSpender-address- +:IERC20Metadata-decimals: pass:normal[xref:token/ERC20.adoc#IERC20Metadata-decimals--[`IERC20Metadata.decimals`]] +:IERC4626-asset: pass:normal[xref:interfaces.adoc#IERC4626-asset--[`IERC4626.asset`]] +:IERC4626-totalAssets: pass:normal[xref:interfaces.adoc#IERC4626-totalAssets--[`IERC4626.totalAssets`]] +:IERC4626-convertToShares: pass:normal[xref:interfaces.adoc#IERC4626-convertToShares-uint256-[`IERC4626.convertToShares`]] +:IERC4626-convertToAssets: pass:normal[xref:interfaces.adoc#IERC4626-convertToAssets-uint256-[`IERC4626.convertToAssets`]] +:IERC4626-maxDeposit: pass:normal[xref:interfaces.adoc#IERC4626-maxDeposit-address-[`IERC4626.maxDeposit`]] +:IERC4626-maxMint: pass:normal[xref:interfaces.adoc#IERC4626-maxMint-address-[`IERC4626.maxMint`]] +:IERC4626-maxWithdraw: pass:normal[xref:interfaces.adoc#IERC4626-maxWithdraw-address-[`IERC4626.maxWithdraw`]] +:IERC4626-maxRedeem: pass:normal[xref:interfaces.adoc#IERC4626-maxRedeem-address-[`IERC4626.maxRedeem`]] +:IERC4626-previewDeposit: pass:normal[xref:interfaces.adoc#IERC4626-previewDeposit-uint256-[`IERC4626.previewDeposit`]] +:IERC4626-previewMint: pass:normal[xref:interfaces.adoc#IERC4626-previewMint-uint256-[`IERC4626.previewMint`]] +:IERC4626-previewWithdraw: pass:normal[xref:interfaces.adoc#IERC4626-previewWithdraw-uint256-[`IERC4626.previewWithdraw`]] +:IERC4626-previewRedeem: pass:normal[xref:interfaces.adoc#IERC4626-previewRedeem-uint256-[`IERC4626.previewRedeem`]] +:IERC4626-deposit: pass:normal[xref:interfaces.adoc#IERC4626-deposit-uint256-address-[`IERC4626.deposit`]] +:IERC4626-mint: pass:normal[xref:interfaces.adoc#IERC4626-mint-uint256-address-[`IERC4626.mint`]] +:IERC4626-withdraw: pass:normal[xref:interfaces.adoc#IERC4626-withdraw-uint256-address-address-[`IERC4626.withdraw`]] +:IERC4626-redeem: pass:normal[xref:interfaces.adoc#IERC4626-redeem-uint256-address-address-[`IERC4626.redeem`]] +:xref-SafeERC20-safeTransfer-contract-IERC20-address-uint256-: xref:token/ERC20.adoc#SafeERC20-safeTransfer-contract-IERC20-address-uint256- +:xref-SafeERC20-safeTransferFrom-contract-IERC20-address-address-uint256-: xref:token/ERC20.adoc#SafeERC20-safeTransferFrom-contract-IERC20-address-address-uint256- +:xref-SafeERC20-safeIncreaseAllowance-contract-IERC20-address-uint256-: xref:token/ERC20.adoc#SafeERC20-safeIncreaseAllowance-contract-IERC20-address-uint256- +:xref-SafeERC20-safeDecreaseAllowance-contract-IERC20-address-uint256-: xref:token/ERC20.adoc#SafeERC20-safeDecreaseAllowance-contract-IERC20-address-uint256- +:xref-SafeERC20-forceApprove-contract-IERC20-address-uint256-: xref:token/ERC20.adoc#SafeERC20-forceApprove-contract-IERC20-address-uint256- +:xref-SafeERC20-SafeERC20FailedOperation-address-: xref:token/ERC20.adoc#SafeERC20-SafeERC20FailedOperation-address- +:xref-SafeERC20-SafeERC20FailedDecreaseAllowance-address-uint256-uint256-: xref:token/ERC20.adoc#SafeERC20-SafeERC20FailedDecreaseAllowance-address-uint256-uint256- += ERC 20 + +[.readme-notice] +NOTE: This document is better viewed at https://docs.openzeppelin.com/contracts/api/token/erc20 + +This set of interfaces, contracts, and utilities are all related to the https://eips.ethereum.org/EIPS/eip-20[ERC20 Token Standard]. + +TIP: For an overview of ERC20 tokens and a walk through on how to create a token contract read our xref:ROOT:erc20.adoc[ERC20 guide]. + +There are a few core contracts that implement the behavior specified in the EIP: + +* {IERC20}: the interface all ERC20 implementations should conform to. +* {IERC20Metadata}: the extended ERC20 interface including the <>, <> and <> functions. +* {ERC20}: the implementation of the ERC20 interface, including the <>, <> and <> optional standard extension to the base interface. + +Additionally there are multiple custom extensions, including: + +* {ERC20Permit}: gasless approval of tokens (standardized as ERC2612). +* {ERC20Burnable}: destruction of own tokens. +* {ERC20Capped}: enforcement of a cap to the total supply when minting tokens. +* {ERC20Pausable}: ability to pause token transfers. +* {ERC20FlashMint}: token level support for flash loans through the minting and burning of ephemeral tokens (standardized as ERC3156). +* {ERC20Votes}: support for voting and vote delegation. +* {ERC20Wrapper}: wrapper to create an ERC20 backed by another ERC20, with deposit and withdraw methods. Useful in conjunction with {ERC20Votes}. +* {ERC4626}: tokenized vault that manages shares (represented as ERC20) that are backed by assets (another ERC20). + +Finally, there are some utilities to interact with ERC20 contracts in various ways: + +* {SafeERC20}: a wrapper around the interface that eliminates the need to handle boolean return values. + +Other utilities that support ERC20 assets can be found in codebase: + +* ERC20 tokens can be timelocked (held tokens for a beneficiary until a specified time) or vested (released following a given schedule) using a {VestingWallet}. + +NOTE: This core set of contracts is designed to be unopinionated, allowing developers to access the internal functions in ERC20 (such as <>) and expose them as external functions in the way they prefer. + +== Core + +:Transfer: pass:normal[xref:#IERC20-Transfer-address-address-uint256-[`++Transfer++`]] +:Approval: pass:normal[xref:#IERC20-Approval-address-address-uint256-[`++Approval++`]] +:totalSupply: pass:normal[xref:#IERC20-totalSupply--[`++totalSupply++`]] +:balanceOf: pass:normal[xref:#IERC20-balanceOf-address-[`++balanceOf++`]] +:transfer: pass:normal[xref:#IERC20-transfer-address-uint256-[`++transfer++`]] +:allowance: pass:normal[xref:#IERC20-allowance-address-address-[`++allowance++`]] +:approve: pass:normal[xref:#IERC20-approve-address-uint256-[`++approve++`]] +:transferFrom: pass:normal[xref:#IERC20-transferFrom-address-address-uint256-[`++transferFrom++`]] + +[.contract] +[[IERC20]] +=== `++IERC20++` link:https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v5.0.0-rc.0/contracts/token/ERC20/IERC20.sol[{github-icon},role=heading-link] + +[.hljs-theme-light.nopadding] +```solidity +import "@openzeppelin/contracts/token/ERC20/IERC20.sol"; +``` + +Interface of the ERC20 standard as defined in the EIP. + +[.contract-index] +.Functions +-- +* {xref-IERC20-totalSupply--}[`++totalSupply()++`] +* {xref-IERC20-balanceOf-address-}[`++balanceOf(account)++`] +* {xref-IERC20-transfer-address-uint256-}[`++transfer(to, value)++`] +* {xref-IERC20-allowance-address-address-}[`++allowance(owner, spender)++`] +* {xref-IERC20-approve-address-uint256-}[`++approve(spender, value)++`] +* {xref-IERC20-transferFrom-address-address-uint256-}[`++transferFrom(from, to, value)++`] + +-- + +[.contract-index] +.Events +-- +* {xref-IERC20-Transfer-address-address-uint256-}[`++Transfer(from, to, value)++`] +* {xref-IERC20-Approval-address-address-uint256-}[`++Approval(owner, spender, value)++`] + +-- + +[.contract-item] +[[IERC20-totalSupply--]] +==== `[.contract-item-name]#++totalSupply++#++() → uint256++` [.item-kind]#external# + +Returns the value of tokens in existence. + +[.contract-item] +[[IERC20-balanceOf-address-]] +==== `[.contract-item-name]#++balanceOf++#++(address account) → uint256++` [.item-kind]#external# + +Returns the value of tokens owned by `account`. + +[.contract-item] +[[IERC20-transfer-address-uint256-]] +==== `[.contract-item-name]#++transfer++#++(address to, uint256 value) → bool++` [.item-kind]#external# + +Moves a `value` amount of tokens from the caller's account to `to`. + +Returns a boolean value indicating whether the operation succeeded. + +Emits a {Transfer} event. + +[.contract-item] +[[IERC20-allowance-address-address-]] +==== `[.contract-item-name]#++allowance++#++(address owner, address spender) → uint256++` [.item-kind]#external# + +Returns the remaining number of tokens that `spender` will be +allowed to spend on behalf of `owner` through {transferFrom}. This is +zero by default. + +This value changes when {approve} or {transferFrom} are called. + +[.contract-item] +[[IERC20-approve-address-uint256-]] +==== `[.contract-item-name]#++approve++#++(address spender, uint256 value) → bool++` [.item-kind]#external# + +Sets a `value` amount of tokens as the allowance of `spender` over the +caller's tokens. + +Returns a boolean value indicating whether the operation succeeded. + +IMPORTANT: Beware that changing an allowance with this method brings the risk +that someone may use both the old and the new allowance by unfortunate +transaction ordering. One possible solution to mitigate this race +condition is to first reduce the spender's allowance to 0 and set the +desired value afterwards: +https://github.com/ethereum/EIPs/issues/20#issuecomment-263524729 + +Emits an {Approval} event. + +[.contract-item] +[[IERC20-transferFrom-address-address-uint256-]] +==== `[.contract-item-name]#++transferFrom++#++(address from, address to, uint256 value) → bool++` [.item-kind]#external# + +Moves a `value` amount of tokens from `from` to `to` using the +allowance mechanism. `value` is then deducted from the caller's +allowance. + +Returns a boolean value indicating whether the operation succeeded. + +Emits a {Transfer} event. + +[.contract-item] +[[IERC20-Transfer-address-address-uint256-]] +==== `[.contract-item-name]#++Transfer++#++(address indexed from, address indexed to, uint256 value)++` [.item-kind]#event# + +Emitted when `value` tokens are moved from one account (`from`) to +another (`to`). + +Note that `value` may be zero. + +[.contract-item] +[[IERC20-Approval-address-address-uint256-]] +==== `[.contract-item-name]#++Approval++#++(address indexed owner, address indexed spender, uint256 value)++` [.item-kind]#event# + +Emitted when the allowance of a `spender` for an `owner` is set by +a call to {approve}. `value` is the new allowance. + +:name: pass:normal[xref:#IERC20Metadata-name--[`++name++`]] +:symbol: pass:normal[xref:#IERC20Metadata-symbol--[`++symbol++`]] +:decimals: pass:normal[xref:#IERC20Metadata-decimals--[`++decimals++`]] + +[.contract] +[[IERC20Metadata]] +=== `++IERC20Metadata++` link:https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v5.0.0-rc.0/contracts/token/ERC20/extensions/IERC20Metadata.sol[{github-icon},role=heading-link] + +[.hljs-theme-light.nopadding] +```solidity +import "@openzeppelin/contracts/token/ERC20/extensions/IERC20Metadata.sol"; +``` + +Interface for the optional metadata functions from the ERC20 standard. + +[.contract-index] +.Functions +-- +* {xref-IERC20Metadata-name--}[`++name()++`] +* {xref-IERC20Metadata-symbol--}[`++symbol()++`] +* {xref-IERC20Metadata-decimals--}[`++decimals()++`] + +[.contract-subindex-inherited] +.IERC20 +* {xref-IERC20-totalSupply--}[`++totalSupply()++`] +* {xref-IERC20-balanceOf-address-}[`++balanceOf(account)++`] +* {xref-IERC20-transfer-address-uint256-}[`++transfer(to, value)++`] +* {xref-IERC20-allowance-address-address-}[`++allowance(owner, spender)++`] +* {xref-IERC20-approve-address-uint256-}[`++approve(spender, value)++`] +* {xref-IERC20-transferFrom-address-address-uint256-}[`++transferFrom(from, to, value)++`] + +-- + +[.contract-index] +.Events +-- + +[.contract-subindex-inherited] +.IERC20 +* {xref-IERC20-Transfer-address-address-uint256-}[`++Transfer(from, to, value)++`] +* {xref-IERC20-Approval-address-address-uint256-}[`++Approval(owner, spender, value)++`] + +-- + +[.contract-item] +[[IERC20Metadata-name--]] +==== `[.contract-item-name]#++name++#++() → string++` [.item-kind]#external# + +Returns the name of the token. + +[.contract-item] +[[IERC20Metadata-symbol--]] +==== `[.contract-item-name]#++symbol++#++() → string++` [.item-kind]#external# + +Returns the symbol of the token. + +[.contract-item] +[[IERC20Metadata-decimals--]] +==== `[.contract-item-name]#++decimals++#++() → uint8++` [.item-kind]#external# + +Returns the decimals places of the token. + +:constructor: pass:normal[xref:#ERC20-constructor-string-string-[`++constructor++`]] +:name: pass:normal[xref:#ERC20-name--[`++name++`]] +:symbol: pass:normal[xref:#ERC20-symbol--[`++symbol++`]] +:decimals: pass:normal[xref:#ERC20-decimals--[`++decimals++`]] +:totalSupply: pass:normal[xref:#ERC20-totalSupply--[`++totalSupply++`]] +:balanceOf: pass:normal[xref:#ERC20-balanceOf-address-[`++balanceOf++`]] +:transfer: pass:normal[xref:#ERC20-transfer-address-uint256-[`++transfer++`]] +:allowance: pass:normal[xref:#ERC20-allowance-address-address-[`++allowance++`]] +:approve: pass:normal[xref:#ERC20-approve-address-uint256-[`++approve++`]] +:transferFrom: pass:normal[xref:#ERC20-transferFrom-address-address-uint256-[`++transferFrom++`]] +:_transfer: pass:normal[xref:#ERC20-_transfer-address-address-uint256-[`++_transfer++`]] +:_update: pass:normal[xref:#ERC20-_update-address-address-uint256-[`++_update++`]] +:_mint: pass:normal[xref:#ERC20-_mint-address-uint256-[`++_mint++`]] +:_burn: pass:normal[xref:#ERC20-_burn-address-uint256-[`++_burn++`]] +:_approve: pass:normal[xref:#ERC20-_approve-address-address-uint256-[`++_approve++`]] +:_approve: pass:normal[xref:#ERC20-_approve-address-address-uint256-bool-[`++_approve++`]] +:_spendAllowance: pass:normal[xref:#ERC20-_spendAllowance-address-address-uint256-[`++_spendAllowance++`]] + +[.contract] +[[ERC20]] +=== `++ERC20++` link:https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v5.0.0-rc.0/contracts/token/ERC20/ERC20.sol[{github-icon},role=heading-link] + +[.hljs-theme-light.nopadding] +```solidity +import "@openzeppelin/contracts/token/ERC20/ERC20.sol"; +``` + +Implementation of the {IERC20} interface. + +This implementation is agnostic to the way tokens are created. This means +that a supply mechanism has to be added in a derived contract using {_mint}. + +TIP: For a detailed writeup see our guide +https://forum.openzeppelin.com/t/how-to-implement-erc20-supply-mechanisms/226[How +to implement supply mechanisms]. + +The default value of {decimals} is 18. To change this, you should override +this function so it returns a different value. + +We have followed general OpenZeppelin Contracts guidelines: functions revert +instead returning `false` on failure. This behavior is nonetheless +conventional and does not conflict with the expectations of ERC20 +applications. + +Additionally, an {Approval} event is emitted on calls to {transferFrom}. +This allows applications to reconstruct the allowance for all accounts just +by listening to said events. Other implementations of the EIP may not emit +these events, as it isn't required by the specification. + +[.contract-index] +.Functions +-- +* {xref-ERC20-constructor-string-string-}[`++constructor(name_, symbol_)++`] +* {xref-ERC20-name--}[`++name()++`] +* {xref-ERC20-symbol--}[`++symbol()++`] +* {xref-ERC20-decimals--}[`++decimals()++`] +* {xref-ERC20-totalSupply--}[`++totalSupply()++`] +* {xref-ERC20-balanceOf-address-}[`++balanceOf(account)++`] +* {xref-ERC20-transfer-address-uint256-}[`++transfer(to, value)++`] +* {xref-ERC20-allowance-address-address-}[`++allowance(owner, spender)++`] +* {xref-ERC20-approve-address-uint256-}[`++approve(spender, value)++`] +* {xref-ERC20-transferFrom-address-address-uint256-}[`++transferFrom(from, to, value)++`] +* {xref-ERC20-_transfer-address-address-uint256-}[`++_transfer(from, to, value)++`] +* {xref-ERC20-_update-address-address-uint256-}[`++_update(from, to, value)++`] +* {xref-ERC20-_mint-address-uint256-}[`++_mint(account, value)++`] +* {xref-ERC20-_burn-address-uint256-}[`++_burn(account, value)++`] +* {xref-ERC20-_approve-address-address-uint256-}[`++_approve(owner, spender, value)++`] +* {xref-ERC20-_approve-address-address-uint256-bool-}[`++_approve(owner, spender, value, emitEvent)++`] +* {xref-ERC20-_spendAllowance-address-address-uint256-}[`++_spendAllowance(owner, spender, value)++`] + +[.contract-subindex-inherited] +.IERC20Errors + +[.contract-subindex-inherited] +.IERC20Metadata + +[.contract-subindex-inherited] +.IERC20 + +-- + +[.contract-index] +.Events +-- + +[.contract-subindex-inherited] +.IERC20Errors + +[.contract-subindex-inherited] +.IERC20Metadata + +[.contract-subindex-inherited] +.IERC20 +* {xref-IERC20-Transfer-address-address-uint256-}[`++Transfer(from, to, value)++`] +* {xref-IERC20-Approval-address-address-uint256-}[`++Approval(owner, spender, value)++`] + +-- + +[.contract-index] +.Errors +-- + +[.contract-subindex-inherited] +.IERC20Errors +* {xref-IERC20Errors-ERC20InsufficientBalance-address-uint256-uint256-}[`++ERC20InsufficientBalance(sender, balance, needed)++`] +* {xref-IERC20Errors-ERC20InvalidSender-address-}[`++ERC20InvalidSender(sender)++`] +* {xref-IERC20Errors-ERC20InvalidReceiver-address-}[`++ERC20InvalidReceiver(receiver)++`] +* {xref-IERC20Errors-ERC20InsufficientAllowance-address-uint256-uint256-}[`++ERC20InsufficientAllowance(spender, allowance, needed)++`] +* {xref-IERC20Errors-ERC20InvalidApprover-address-}[`++ERC20InvalidApprover(approver)++`] +* {xref-IERC20Errors-ERC20InvalidSpender-address-}[`++ERC20InvalidSpender(spender)++`] + +[.contract-subindex-inherited] +.IERC20Metadata + +[.contract-subindex-inherited] +.IERC20 + +-- + +[.contract-item] +[[ERC20-constructor-string-string-]] +==== `[.contract-item-name]#++constructor++#++(string name_, string symbol_)++` [.item-kind]#internal# + +Sets the values for {name} and {symbol}. + +All two of these values are immutable: they can only be set once during +construction. + +[.contract-item] +[[ERC20-name--]] +==== `[.contract-item-name]#++name++#++() → string++` [.item-kind]#public# + +Returns the name of the token. + +[.contract-item] +[[ERC20-symbol--]] +==== `[.contract-item-name]#++symbol++#++() → string++` [.item-kind]#public# + +Returns the symbol of the token, usually a shorter version of the +name. + +[.contract-item] +[[ERC20-decimals--]] +==== `[.contract-item-name]#++decimals++#++() → uint8++` [.item-kind]#public# + +Returns the number of decimals used to get its user representation. +For example, if `decimals` equals `2`, a balance of `505` tokens should +be displayed to a user as `5.05` (`505 / 10 ** 2`). + +Tokens usually opt for a value of 18, imitating the relationship between +Ether and Wei. This is the default value returned by this function, unless +it's overridden. + +NOTE: This information is only used for _display_ purposes: it in +no way affects any of the arithmetic of the contract, including +{IERC20-balanceOf} and {IERC20-transfer}. + +[.contract-item] +[[ERC20-totalSupply--]] +==== `[.contract-item-name]#++totalSupply++#++() → uint256++` [.item-kind]#public# + +See {IERC20-totalSupply}. + +[.contract-item] +[[ERC20-balanceOf-address-]] +==== `[.contract-item-name]#++balanceOf++#++(address account) → uint256++` [.item-kind]#public# + +See {IERC20-balanceOf}. + +[.contract-item] +[[ERC20-transfer-address-uint256-]] +==== `[.contract-item-name]#++transfer++#++(address to, uint256 value) → bool++` [.item-kind]#public# + +See {IERC20-transfer}. + +Requirements: + +- `to` cannot be the zero address. +- the caller must have a balance of at least `value`. + +[.contract-item] +[[ERC20-allowance-address-address-]] +==== `[.contract-item-name]#++allowance++#++(address owner, address spender) → uint256++` [.item-kind]#public# + +See {IERC20-allowance}. + +[.contract-item] +[[ERC20-approve-address-uint256-]] +==== `[.contract-item-name]#++approve++#++(address spender, uint256 value) → bool++` [.item-kind]#public# + +See {IERC20-approve}. + +NOTE: If `value` is the maximum `uint256`, the allowance is not updated on +`transferFrom`. This is semantically equivalent to an infinite approval. + +Requirements: + +- `spender` cannot be the zero address. + +[.contract-item] +[[ERC20-transferFrom-address-address-uint256-]] +==== `[.contract-item-name]#++transferFrom++#++(address from, address to, uint256 value) → bool++` [.item-kind]#public# + +See {IERC20-transferFrom}. + +Emits an {Approval} event indicating the updated allowance. This is not +required by the EIP. See the note at the beginning of {ERC20}. + +NOTE: Does not update the allowance if the current allowance +is the maximum `uint256`. + +Requirements: + +- `from` and `to` cannot be the zero address. +- `from` must have a balance of at least `value`. +- the caller must have allowance for ``from``'s tokens of at least +`value`. + +[.contract-item] +[[ERC20-_transfer-address-address-uint256-]] +==== `[.contract-item-name]#++_transfer++#++(address from, address to, uint256 value)++` [.item-kind]#internal# + +Moves a `value` amount of tokens from `from` to `to`. + +This internal function is equivalent to {transfer}, and can be used to +e.g. implement automatic token fees, slashing mechanisms, etc. + +Emits a {Transfer} event. + +NOTE: This function is not virtual, {_update} should be overridden instead. + +[.contract-item] +[[ERC20-_update-address-address-uint256-]] +==== `[.contract-item-name]#++_update++#++(address from, address to, uint256 value)++` [.item-kind]#internal# + +Transfers a `value` amount of tokens from `from` to `to`, or alternatively mints (or burns) if `from` +(or `to`) is the zero address. All customizations to transfers, mints, and burns should be done by overriding +this function. + +Emits a {Transfer} event. + +[.contract-item] +[[ERC20-_mint-address-uint256-]] +==== `[.contract-item-name]#++_mint++#++(address account, uint256 value)++` [.item-kind]#internal# + +Creates a `value` amount of tokens and assigns them to `account`, by transferring it from address(0). +Relies on the `_update` mechanism + +Emits a {Transfer} event with `from` set to the zero address. + +NOTE: This function is not virtual, {_update} should be overridden instead. + +[.contract-item] +[[ERC20-_burn-address-uint256-]] +==== `[.contract-item-name]#++_burn++#++(address account, uint256 value)++` [.item-kind]#internal# + +Destroys a `value` amount of tokens from `account`, lowering the total supply. +Relies on the `_update` mechanism. + +Emits a {Transfer} event with `to` set to the zero address. + +NOTE: This function is not virtual, {_update} should be overridden instead + +[.contract-item] +[[ERC20-_approve-address-address-uint256-]] +==== `[.contract-item-name]#++_approve++#++(address owner, address spender, uint256 value)++` [.item-kind]#internal# + +Sets `value` as the allowance of `spender` over the `owner` s tokens. + +This internal function is equivalent to `approve`, and can be used to +e.g. set automatic allowances for certain subsystems, etc. + +Emits an {Approval} event. + +Requirements: + +- `owner` cannot be the zero address. +- `spender` cannot be the zero address. + +Overrides to this logic should be done to the variant with an additional `bool emitEvent` argument. + +[.contract-item] +[[ERC20-_approve-address-address-uint256-bool-]] +==== `[.contract-item-name]#++_approve++#++(address owner, address spender, uint256 value, bool emitEvent)++` [.item-kind]#internal# + +Variant of {_approve} with an optional flag to enable or disable the {Approval} event. + +By default (when calling {_approve}) the flag is set to true. On the other hand, approval changes made by +`_spendAllowance` during the `transferFrom` operation set the flag to false. This saves gas by not emitting any +`Approval` event during `transferFrom` operations. + +Anyone who wishes to continue emitting `Approval` events on the`transferFrom` operation can force the flag to +true using the following override: +``` +function _approve(address owner, address spender, uint256 value, bool) internal virtual override { + super._approve(owner, spender, value, true); +} +``` + +Requirements are the same as {_approve}. + +[.contract-item] +[[ERC20-_spendAllowance-address-address-uint256-]] +==== `[.contract-item-name]#++_spendAllowance++#++(address owner, address spender, uint256 value)++` [.item-kind]#internal# + +Updates `owner` s allowance for `spender` based on spent `value`. + +Does not update the allowance value in case of infinite allowance. +Revert if not enough allowance is available. + +Does not emit an {Approval} event. + +== Extensions + +:permit: pass:normal[xref:#IERC20Permit-permit-address-address-uint256-uint256-uint8-bytes32-bytes32-[`++permit++`]] +:nonces: pass:normal[xref:#IERC20Permit-nonces-address-[`++nonces++`]] +:DOMAIN_SEPARATOR: pass:normal[xref:#IERC20Permit-DOMAIN_SEPARATOR--[`++DOMAIN_SEPARATOR++`]] + +[.contract] +[[IERC20Permit]] +=== `++IERC20Permit++` link:https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v5.0.0-rc.0/contracts/token/ERC20/extensions/IERC20Permit.sol[{github-icon},role=heading-link] + +[.hljs-theme-light.nopadding] +```solidity +import "@openzeppelin/contracts/token/ERC20/extensions/IERC20Permit.sol"; +``` + +Interface of the ERC20 Permit extension allowing approvals to be made via signatures, as defined in +https://eips.ethereum.org/EIPS/eip-2612[EIP-2612]. + +Adds the {permit} method, which can be used to change an account's ERC20 allowance (see {IERC20-allowance}) by +presenting a message signed by the account. By not relying on {IERC20-approve}, the token holder account doesn't +need to send a transaction, and thus is not required to hold Ether at all. + +==== Security Considerations + +There are two important considerations concerning the use of `permit`. The first is that a valid permit signature +expresses an allowance, and it should not be assumed to convey additional meaning. In particular, it should not be +considered as an intention to spend the allowance in any specific way. The second is that because permits have +built-in replay protection and can be submitted by anyone, they can be frontrun. A protocol that uses permits should +take this into consideration and allow a `permit` call to fail. Combining these two aspects, a pattern that may be +generally recommended is: + +```solidity +function doThingWithPermit(..., uint256 value, uint256 deadline, uint8 v, bytes32 r, bytes32 s) public { + try token.permit(msg.sender, address(this), value, deadline, v, r, s) {} catch {} + doThing(..., value); +} + +function doThing(..., uint256 value) public { + token.safeTransferFrom(msg.sender, address(this), value); + ... +} +``` + +Observe that: 1) `msg.sender` is used as the owner, leaving no ambiguity as to the signer intent, and 2) the use of +`try/catch` allows the permit to fail and makes the code tolerant to frontrunning. (See also +{SafeERC20-safeTransferFrom}). + +Additionally, note that smart contract wallets (such as Argent or Safe) are not able to produce permit signatures, so +contracts should have entry points that don't rely on permit. + +[.contract-index] +.Functions +-- +* {xref-IERC20Permit-permit-address-address-uint256-uint256-uint8-bytes32-bytes32-}[`++permit(owner, spender, value, deadline, v, r, s)++`] +* {xref-IERC20Permit-nonces-address-}[`++nonces(owner)++`] +* {xref-IERC20Permit-DOMAIN_SEPARATOR--}[`++DOMAIN_SEPARATOR()++`] + +-- + +[.contract-item] +[[IERC20Permit-permit-address-address-uint256-uint256-uint8-bytes32-bytes32-]] +==== `[.contract-item-name]#++permit++#++(address owner, address spender, uint256 value, uint256 deadline, uint8 v, bytes32 r, bytes32 s)++` [.item-kind]#external# + +Sets `value` as the allowance of `spender` over ``owner``'s tokens, +given ``owner``'s signed approval. + +IMPORTANT: The same issues {IERC20-approve} has related to transaction +ordering also apply here. + +Emits an {Approval} event. + +Requirements: + +- `spender` cannot be the zero address. +- `deadline` must be a timestamp in the future. +- `v`, `r` and `s` must be a valid `secp256k1` signature from `owner` +over the EIP712-formatted function arguments. +- the signature must use ``owner``'s current nonce (see {nonces}). + +For more information on the signature format, see the +https://eips.ethereum.org/EIPS/eip-2612#specification[relevant EIP +section]. + +CAUTION: See Security Considerations above. + +[.contract-item] +[[IERC20Permit-nonces-address-]] +==== `[.contract-item-name]#++nonces++#++(address owner) → uint256++` [.item-kind]#external# + +Returns the current nonce for `owner`. This value must be +included whenever a signature is generated for {permit}. + +Every successful call to {permit} increases ``owner``'s nonce by one. This +prevents a signature from being used multiple times. + +[.contract-item] +[[IERC20Permit-DOMAIN_SEPARATOR--]] +==== `[.contract-item-name]#++DOMAIN_SEPARATOR++#++() → bytes32++` [.item-kind]#external# + +Returns the domain separator used in the encoding of the signature for {permit}, as defined by {EIP712}. + +:ERC2612ExpiredSignature: pass:normal[xref:#ERC20Permit-ERC2612ExpiredSignature-uint256-[`++ERC2612ExpiredSignature++`]] +:ERC2612InvalidSigner: pass:normal[xref:#ERC20Permit-ERC2612InvalidSigner-address-address-[`++ERC2612InvalidSigner++`]] +:constructor: pass:normal[xref:#ERC20Permit-constructor-string-[`++constructor++`]] +:permit: pass:normal[xref:#ERC20Permit-permit-address-address-uint256-uint256-uint8-bytes32-bytes32-[`++permit++`]] +:nonces: pass:normal[xref:#ERC20Permit-nonces-address-[`++nonces++`]] +:DOMAIN_SEPARATOR: pass:normal[xref:#ERC20Permit-DOMAIN_SEPARATOR--[`++DOMAIN_SEPARATOR++`]] + +[.contract] +[[ERC20Permit]] +=== `++ERC20Permit++` link:https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v5.0.0-rc.0/contracts/token/ERC20/extensions/ERC20Permit.sol[{github-icon},role=heading-link] + +[.hljs-theme-light.nopadding] +```solidity +import "@openzeppelin/contracts/token/ERC20/extensions/ERC20Permit.sol"; +``` + +Implementation of the ERC20 Permit extension allowing approvals to be made via signatures, as defined in +https://eips.ethereum.org/EIPS/eip-2612[EIP-2612]. + +Adds the {permit} method, which can be used to change an account's ERC20 allowance (see {IERC20-allowance}) by +presenting a message signed by the account. By not relying on `{IERC20-approve}`, the token holder account doesn't +need to send a transaction, and thus is not required to hold Ether at all. + +[.contract-index] +.Functions +-- +* {xref-ERC20Permit-constructor-string-}[`++constructor(name)++`] +* {xref-ERC20Permit-permit-address-address-uint256-uint256-uint8-bytes32-bytes32-}[`++permit(owner, spender, value, deadline, v, r, s)++`] +* {xref-ERC20Permit-nonces-address-}[`++nonces(owner)++`] +* {xref-ERC20Permit-DOMAIN_SEPARATOR--}[`++DOMAIN_SEPARATOR()++`] + +[.contract-subindex-inherited] +.Nonces +* {xref-Nonces-_useNonce-address-}[`++_useNonce(owner)++`] +* {xref-Nonces-_useCheckedNonce-address-uint256-}[`++_useCheckedNonce(owner, nonce)++`] + +[.contract-subindex-inherited] +.EIP712 +* {xref-EIP712-_domainSeparatorV4--}[`++_domainSeparatorV4()++`] +* {xref-EIP712-_hashTypedDataV4-bytes32-}[`++_hashTypedDataV4(structHash)++`] +* {xref-EIP712-eip712Domain--}[`++eip712Domain()++`] +* {xref-EIP712-_EIP712Name--}[`++_EIP712Name()++`] +* {xref-EIP712-_EIP712Version--}[`++_EIP712Version()++`] + +[.contract-subindex-inherited] +.IERC5267 + +[.contract-subindex-inherited] +.IERC20Permit + +[.contract-subindex-inherited] +.ERC20 +* {xref-ERC20-name--}[`++name()++`] +* {xref-ERC20-symbol--}[`++symbol()++`] +* {xref-ERC20-decimals--}[`++decimals()++`] +* {xref-ERC20-totalSupply--}[`++totalSupply()++`] +* {xref-ERC20-balanceOf-address-}[`++balanceOf(account)++`] +* {xref-ERC20-transfer-address-uint256-}[`++transfer(to, value)++`] +* {xref-ERC20-allowance-address-address-}[`++allowance(owner, spender)++`] +* {xref-ERC20-approve-address-uint256-}[`++approve(spender, value)++`] +* {xref-ERC20-transferFrom-address-address-uint256-}[`++transferFrom(from, to, value)++`] +* {xref-ERC20-_transfer-address-address-uint256-}[`++_transfer(from, to, value)++`] +* {xref-ERC20-_update-address-address-uint256-}[`++_update(from, to, value)++`] +* {xref-ERC20-_mint-address-uint256-}[`++_mint(account, value)++`] +* {xref-ERC20-_burn-address-uint256-}[`++_burn(account, value)++`] +* {xref-ERC20-_approve-address-address-uint256-}[`++_approve(owner, spender, value)++`] +* {xref-ERC20-_approve-address-address-uint256-bool-}[`++_approve(owner, spender, value, emitEvent)++`] +* {xref-ERC20-_spendAllowance-address-address-uint256-}[`++_spendAllowance(owner, spender, value)++`] + +[.contract-subindex-inherited] +.IERC20Errors + +[.contract-subindex-inherited] +.IERC20Metadata + +[.contract-subindex-inherited] +.IERC20 + +-- + +[.contract-index] +.Events +-- + +[.contract-subindex-inherited] +.Nonces + +[.contract-subindex-inherited] +.EIP712 + +[.contract-subindex-inherited] +.IERC5267 +* {xref-IERC5267-EIP712DomainChanged--}[`++EIP712DomainChanged()++`] + +[.contract-subindex-inherited] +.IERC20Permit + +[.contract-subindex-inherited] +.ERC20 + +[.contract-subindex-inherited] +.IERC20Errors + +[.contract-subindex-inherited] +.IERC20Metadata + +[.contract-subindex-inherited] +.IERC20 +* {xref-IERC20-Transfer-address-address-uint256-}[`++Transfer(from, to, value)++`] +* {xref-IERC20-Approval-address-address-uint256-}[`++Approval(owner, spender, value)++`] + +-- + +[.contract-index] +.Errors +-- +* {xref-ERC20Permit-ERC2612ExpiredSignature-uint256-}[`++ERC2612ExpiredSignature(deadline)++`] +* {xref-ERC20Permit-ERC2612InvalidSigner-address-address-}[`++ERC2612InvalidSigner(signer, owner)++`] + +[.contract-subindex-inherited] +.Nonces +* {xref-Nonces-InvalidAccountNonce-address-uint256-}[`++InvalidAccountNonce(account, currentNonce)++`] + +[.contract-subindex-inherited] +.EIP712 + +[.contract-subindex-inherited] +.IERC5267 + +[.contract-subindex-inherited] +.IERC20Permit + +[.contract-subindex-inherited] +.ERC20 + +[.contract-subindex-inherited] +.IERC20Errors +* {xref-IERC20Errors-ERC20InsufficientBalance-address-uint256-uint256-}[`++ERC20InsufficientBalance(sender, balance, needed)++`] +* {xref-IERC20Errors-ERC20InvalidSender-address-}[`++ERC20InvalidSender(sender)++`] +* {xref-IERC20Errors-ERC20InvalidReceiver-address-}[`++ERC20InvalidReceiver(receiver)++`] +* {xref-IERC20Errors-ERC20InsufficientAllowance-address-uint256-uint256-}[`++ERC20InsufficientAllowance(spender, allowance, needed)++`] +* {xref-IERC20Errors-ERC20InvalidApprover-address-}[`++ERC20InvalidApprover(approver)++`] +* {xref-IERC20Errors-ERC20InvalidSpender-address-}[`++ERC20InvalidSpender(spender)++`] + +[.contract-subindex-inherited] +.IERC20Metadata + +[.contract-subindex-inherited] +.IERC20 + +-- + +[.contract-item] +[[ERC20Permit-constructor-string-]] +==== `[.contract-item-name]#++constructor++#++(string name)++` [.item-kind]#internal# + +Initializes the {EIP712} domain separator using the `name` parameter, and setting `version` to `"1"`. + +It's a good idea to use the same `name` that is defined as the ERC20 token name. + +[.contract-item] +[[ERC20Permit-permit-address-address-uint256-uint256-uint8-bytes32-bytes32-]] +==== `[.contract-item-name]#++permit++#++(address owner, address spender, uint256 value, uint256 deadline, uint8 v, bytes32 r, bytes32 s)++` [.item-kind]#public# + +Sets `value` as the allowance of `spender` over ``owner``'s tokens, +given ``owner``'s signed approval. + +IMPORTANT: The same issues {IERC20-approve} has related to transaction +ordering also apply here. + +Emits an {Approval} event. + +Requirements: + +- `spender` cannot be the zero address. +- `deadline` must be a timestamp in the future. +- `v`, `r` and `s` must be a valid `secp256k1` signature from `owner` +over the EIP712-formatted function arguments. +- the signature must use ``owner``'s current nonce (see {nonces}). + +For more information on the signature format, see the +https://eips.ethereum.org/EIPS/eip-2612#specification[relevant EIP +section]. + +CAUTION: See Security Considerations above. + +[.contract-item] +[[ERC20Permit-nonces-address-]] +==== `[.contract-item-name]#++nonces++#++(address owner) → uint256++` [.item-kind]#public# + +Returns the current nonce for `owner`. This value must be +included whenever a signature is generated for {permit}. + +Every successful call to {permit} increases ``owner``'s nonce by one. This +prevents a signature from being used multiple times. + +[.contract-item] +[[ERC20Permit-DOMAIN_SEPARATOR--]] +==== `[.contract-item-name]#++DOMAIN_SEPARATOR++#++() → bytes32++` [.item-kind]#external# + +Returns the domain separator used in the encoding of the signature for {permit}, as defined by {EIP712}. + +[.contract-item] +[[ERC20Permit-ERC2612ExpiredSignature-uint256-]] +==== `[.contract-item-name]#++ERC2612ExpiredSignature++#++(uint256 deadline)++` [.item-kind]#error# + +Permit deadline has expired. + +[.contract-item] +[[ERC20Permit-ERC2612InvalidSigner-address-address-]] +==== `[.contract-item-name]#++ERC2612InvalidSigner++#++(address signer, address owner)++` [.item-kind]#error# + +Mismatched signature. + +:burn: pass:normal[xref:#ERC20Burnable-burn-uint256-[`++burn++`]] +:burnFrom: pass:normal[xref:#ERC20Burnable-burnFrom-address-uint256-[`++burnFrom++`]] + +[.contract] +[[ERC20Burnable]] +=== `++ERC20Burnable++` link:https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v5.0.0-rc.0/contracts/token/ERC20/extensions/ERC20Burnable.sol[{github-icon},role=heading-link] + +[.hljs-theme-light.nopadding] +```solidity +import "@openzeppelin/contracts/token/ERC20/extensions/ERC20Burnable.sol"; +``` + +Extension of {ERC20} that allows token holders to destroy both their own +tokens and those that they have an allowance for, in a way that can be +recognized off-chain (via event analysis). + +[.contract-index] +.Functions +-- +* {xref-ERC20Burnable-burn-uint256-}[`++burn(value)++`] +* {xref-ERC20Burnable-burnFrom-address-uint256-}[`++burnFrom(account, value)++`] + +[.contract-subindex-inherited] +.ERC20 +* {xref-ERC20-name--}[`++name()++`] +* {xref-ERC20-symbol--}[`++symbol()++`] +* {xref-ERC20-decimals--}[`++decimals()++`] +* {xref-ERC20-totalSupply--}[`++totalSupply()++`] +* {xref-ERC20-balanceOf-address-}[`++balanceOf(account)++`] +* {xref-ERC20-transfer-address-uint256-}[`++transfer(to, value)++`] +* {xref-ERC20-allowance-address-address-}[`++allowance(owner, spender)++`] +* {xref-ERC20-approve-address-uint256-}[`++approve(spender, value)++`] +* {xref-ERC20-transferFrom-address-address-uint256-}[`++transferFrom(from, to, value)++`] +* {xref-ERC20-_transfer-address-address-uint256-}[`++_transfer(from, to, value)++`] +* {xref-ERC20-_update-address-address-uint256-}[`++_update(from, to, value)++`] +* {xref-ERC20-_mint-address-uint256-}[`++_mint(account, value)++`] +* {xref-ERC20-_burn-address-uint256-}[`++_burn(account, value)++`] +* {xref-ERC20-_approve-address-address-uint256-}[`++_approve(owner, spender, value)++`] +* {xref-ERC20-_approve-address-address-uint256-bool-}[`++_approve(owner, spender, value, emitEvent)++`] +* {xref-ERC20-_spendAllowance-address-address-uint256-}[`++_spendAllowance(owner, spender, value)++`] + +[.contract-subindex-inherited] +.IERC20Errors + +[.contract-subindex-inherited] +.IERC20Metadata + +[.contract-subindex-inherited] +.IERC20 + +-- + +[.contract-index] +.Events +-- + +[.contract-subindex-inherited] +.ERC20 + +[.contract-subindex-inherited] +.IERC20Errors + +[.contract-subindex-inherited] +.IERC20Metadata + +[.contract-subindex-inherited] +.IERC20 +* {xref-IERC20-Transfer-address-address-uint256-}[`++Transfer(from, to, value)++`] +* {xref-IERC20-Approval-address-address-uint256-}[`++Approval(owner, spender, value)++`] + +-- + +[.contract-index] +.Errors +-- + +[.contract-subindex-inherited] +.ERC20 + +[.contract-subindex-inherited] +.IERC20Errors +* {xref-IERC20Errors-ERC20InsufficientBalance-address-uint256-uint256-}[`++ERC20InsufficientBalance(sender, balance, needed)++`] +* {xref-IERC20Errors-ERC20InvalidSender-address-}[`++ERC20InvalidSender(sender)++`] +* {xref-IERC20Errors-ERC20InvalidReceiver-address-}[`++ERC20InvalidReceiver(receiver)++`] +* {xref-IERC20Errors-ERC20InsufficientAllowance-address-uint256-uint256-}[`++ERC20InsufficientAllowance(spender, allowance, needed)++`] +* {xref-IERC20Errors-ERC20InvalidApprover-address-}[`++ERC20InvalidApprover(approver)++`] +* {xref-IERC20Errors-ERC20InvalidSpender-address-}[`++ERC20InvalidSpender(spender)++`] + +[.contract-subindex-inherited] +.IERC20Metadata + +[.contract-subindex-inherited] +.IERC20 + +-- + +[.contract-item] +[[ERC20Burnable-burn-uint256-]] +==== `[.contract-item-name]#++burn++#++(uint256 value)++` [.item-kind]#public# + +Destroys a `value` amount of tokens from the caller. + +See {ERC20-_burn}. + +[.contract-item] +[[ERC20Burnable-burnFrom-address-uint256-]] +==== `[.contract-item-name]#++burnFrom++#++(address account, uint256 value)++` [.item-kind]#public# + +Destroys a `value` amount of tokens from `account`, deducting from +the caller's allowance. + +See {ERC20-_burn} and {ERC20-allowance}. + +Requirements: + +- the caller must have allowance for ``accounts``'s tokens of at least +`value`. + +:ERC20ExceededCap: pass:normal[xref:#ERC20Capped-ERC20ExceededCap-uint256-uint256-[`++ERC20ExceededCap++`]] +:ERC20InvalidCap: pass:normal[xref:#ERC20Capped-ERC20InvalidCap-uint256-[`++ERC20InvalidCap++`]] +:constructor: pass:normal[xref:#ERC20Capped-constructor-uint256-[`++constructor++`]] +:cap: pass:normal[xref:#ERC20Capped-cap--[`++cap++`]] +:_update: pass:normal[xref:#ERC20Capped-_update-address-address-uint256-[`++_update++`]] + +[.contract] +[[ERC20Capped]] +=== `++ERC20Capped++` link:https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v5.0.0-rc.0/contracts/token/ERC20/extensions/ERC20Capped.sol[{github-icon},role=heading-link] + +[.hljs-theme-light.nopadding] +```solidity +import "@openzeppelin/contracts/token/ERC20/extensions/ERC20Capped.sol"; +``` + +Extension of {ERC20} that adds a cap to the supply of tokens. + +[.contract-index] +.Functions +-- +* {xref-ERC20Capped-constructor-uint256-}[`++constructor(cap_)++`] +* {xref-ERC20Capped-cap--}[`++cap()++`] +* {xref-ERC20Capped-_update-address-address-uint256-}[`++_update(from, to, value)++`] + +[.contract-subindex-inherited] +.ERC20 +* {xref-ERC20-name--}[`++name()++`] +* {xref-ERC20-symbol--}[`++symbol()++`] +* {xref-ERC20-decimals--}[`++decimals()++`] +* {xref-ERC20-totalSupply--}[`++totalSupply()++`] +* {xref-ERC20-balanceOf-address-}[`++balanceOf(account)++`] +* {xref-ERC20-transfer-address-uint256-}[`++transfer(to, value)++`] +* {xref-ERC20-allowance-address-address-}[`++allowance(owner, spender)++`] +* {xref-ERC20-approve-address-uint256-}[`++approve(spender, value)++`] +* {xref-ERC20-transferFrom-address-address-uint256-}[`++transferFrom(from, to, value)++`] +* {xref-ERC20-_transfer-address-address-uint256-}[`++_transfer(from, to, value)++`] +* {xref-ERC20-_mint-address-uint256-}[`++_mint(account, value)++`] +* {xref-ERC20-_burn-address-uint256-}[`++_burn(account, value)++`] +* {xref-ERC20-_approve-address-address-uint256-}[`++_approve(owner, spender, value)++`] +* {xref-ERC20-_approve-address-address-uint256-bool-}[`++_approve(owner, spender, value, emitEvent)++`] +* {xref-ERC20-_spendAllowance-address-address-uint256-}[`++_spendAllowance(owner, spender, value)++`] + +[.contract-subindex-inherited] +.IERC20Errors + +[.contract-subindex-inherited] +.IERC20Metadata + +[.contract-subindex-inherited] +.IERC20 + +-- + +[.contract-index] +.Events +-- + +[.contract-subindex-inherited] +.ERC20 + +[.contract-subindex-inherited] +.IERC20Errors + +[.contract-subindex-inherited] +.IERC20Metadata + +[.contract-subindex-inherited] +.IERC20 +* {xref-IERC20-Transfer-address-address-uint256-}[`++Transfer(from, to, value)++`] +* {xref-IERC20-Approval-address-address-uint256-}[`++Approval(owner, spender, value)++`] + +-- + +[.contract-index] +.Errors +-- +* {xref-ERC20Capped-ERC20ExceededCap-uint256-uint256-}[`++ERC20ExceededCap(increasedSupply, cap)++`] +* {xref-ERC20Capped-ERC20InvalidCap-uint256-}[`++ERC20InvalidCap(cap)++`] + +[.contract-subindex-inherited] +.ERC20 + +[.contract-subindex-inherited] +.IERC20Errors +* {xref-IERC20Errors-ERC20InsufficientBalance-address-uint256-uint256-}[`++ERC20InsufficientBalance(sender, balance, needed)++`] +* {xref-IERC20Errors-ERC20InvalidSender-address-}[`++ERC20InvalidSender(sender)++`] +* {xref-IERC20Errors-ERC20InvalidReceiver-address-}[`++ERC20InvalidReceiver(receiver)++`] +* {xref-IERC20Errors-ERC20InsufficientAllowance-address-uint256-uint256-}[`++ERC20InsufficientAllowance(spender, allowance, needed)++`] +* {xref-IERC20Errors-ERC20InvalidApprover-address-}[`++ERC20InvalidApprover(approver)++`] +* {xref-IERC20Errors-ERC20InvalidSpender-address-}[`++ERC20InvalidSpender(spender)++`] + +[.contract-subindex-inherited] +.IERC20Metadata + +[.contract-subindex-inherited] +.IERC20 + +-- + +[.contract-item] +[[ERC20Capped-constructor-uint256-]] +==== `[.contract-item-name]#++constructor++#++(uint256 cap_)++` [.item-kind]#internal# + +Sets the value of the `cap`. This value is immutable, it can only be +set once during construction. + +[.contract-item] +[[ERC20Capped-cap--]] +==== `[.contract-item-name]#++cap++#++() → uint256++` [.item-kind]#public# + +Returns the cap on the token's total supply. + +[.contract-item] +[[ERC20Capped-_update-address-address-uint256-]] +==== `[.contract-item-name]#++_update++#++(address from, address to, uint256 value)++` [.item-kind]#internal# + +See {ERC20-_update}. + +[.contract-item] +[[ERC20Capped-ERC20ExceededCap-uint256-uint256-]] +==== `[.contract-item-name]#++ERC20ExceededCap++#++(uint256 increasedSupply, uint256 cap)++` [.item-kind]#error# + +Total supply cap has been exceeded. + +[.contract-item] +[[ERC20Capped-ERC20InvalidCap-uint256-]] +==== `[.contract-item-name]#++ERC20InvalidCap++#++(uint256 cap)++` [.item-kind]#error# + +The supplied cap is not a valid cap. + +:_update: pass:normal[xref:#ERC20Pausable-_update-address-address-uint256-[`++_update++`]] + +[.contract] +[[ERC20Pausable]] +=== `++ERC20Pausable++` link:https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v5.0.0-rc.0/contracts/token/ERC20/extensions/ERC20Pausable.sol[{github-icon},role=heading-link] + +[.hljs-theme-light.nopadding] +```solidity +import "@openzeppelin/contracts/token/ERC20/extensions/ERC20Pausable.sol"; +``` + +ERC20 token with pausable token transfers, minting and burning. + +Useful for scenarios such as preventing trades until the end of an evaluation +period, or having an emergency switch for freezing all token transfers in the +event of a large bug. + +IMPORTANT: This contract does not include public pause and unpause functions. In +addition to inheriting this contract, you must define both functions, invoking the +{Pausable-_pause} and {Pausable-_unpause} internal functions, with appropriate +access control, e.g. using {AccessControl} or {Ownable}. Not doing so will +make the contract pause mechanism of the contract unreachable, and thus unusable. + +[.contract-index] +.Functions +-- +* {xref-ERC20Pausable-_update-address-address-uint256-}[`++_update(from, to, value)++`] + +[.contract-subindex-inherited] +.Pausable +* {xref-Pausable-paused--}[`++paused()++`] +* {xref-Pausable-_requireNotPaused--}[`++_requireNotPaused()++`] +* {xref-Pausable-_requirePaused--}[`++_requirePaused()++`] +* {xref-Pausable-_pause--}[`++_pause()++`] +* {xref-Pausable-_unpause--}[`++_unpause()++`] + +[.contract-subindex-inherited] +.ERC20 +* {xref-ERC20-name--}[`++name()++`] +* {xref-ERC20-symbol--}[`++symbol()++`] +* {xref-ERC20-decimals--}[`++decimals()++`] +* {xref-ERC20-totalSupply--}[`++totalSupply()++`] +* {xref-ERC20-balanceOf-address-}[`++balanceOf(account)++`] +* {xref-ERC20-transfer-address-uint256-}[`++transfer(to, value)++`] +* {xref-ERC20-allowance-address-address-}[`++allowance(owner, spender)++`] +* {xref-ERC20-approve-address-uint256-}[`++approve(spender, value)++`] +* {xref-ERC20-transferFrom-address-address-uint256-}[`++transferFrom(from, to, value)++`] +* {xref-ERC20-_transfer-address-address-uint256-}[`++_transfer(from, to, value)++`] +* {xref-ERC20-_mint-address-uint256-}[`++_mint(account, value)++`] +* {xref-ERC20-_burn-address-uint256-}[`++_burn(account, value)++`] +* {xref-ERC20-_approve-address-address-uint256-}[`++_approve(owner, spender, value)++`] +* {xref-ERC20-_approve-address-address-uint256-bool-}[`++_approve(owner, spender, value, emitEvent)++`] +* {xref-ERC20-_spendAllowance-address-address-uint256-}[`++_spendAllowance(owner, spender, value)++`] + +[.contract-subindex-inherited] +.IERC20Errors + +[.contract-subindex-inherited] +.IERC20Metadata + +[.contract-subindex-inherited] +.IERC20 + +-- + +[.contract-index] +.Events +-- + +[.contract-subindex-inherited] +.Pausable +* {xref-Pausable-Paused-address-}[`++Paused(account)++`] +* {xref-Pausable-Unpaused-address-}[`++Unpaused(account)++`] + +[.contract-subindex-inherited] +.ERC20 + +[.contract-subindex-inherited] +.IERC20Errors + +[.contract-subindex-inherited] +.IERC20Metadata + +[.contract-subindex-inherited] +.IERC20 +* {xref-IERC20-Transfer-address-address-uint256-}[`++Transfer(from, to, value)++`] +* {xref-IERC20-Approval-address-address-uint256-}[`++Approval(owner, spender, value)++`] + +-- + +[.contract-index] +.Errors +-- + +[.contract-subindex-inherited] +.Pausable +* {xref-Pausable-EnforcedPause--}[`++EnforcedPause()++`] +* {xref-Pausable-ExpectedPause--}[`++ExpectedPause()++`] + +[.contract-subindex-inherited] +.ERC20 + +[.contract-subindex-inherited] +.IERC20Errors +* {xref-IERC20Errors-ERC20InsufficientBalance-address-uint256-uint256-}[`++ERC20InsufficientBalance(sender, balance, needed)++`] +* {xref-IERC20Errors-ERC20InvalidSender-address-}[`++ERC20InvalidSender(sender)++`] +* {xref-IERC20Errors-ERC20InvalidReceiver-address-}[`++ERC20InvalidReceiver(receiver)++`] +* {xref-IERC20Errors-ERC20InsufficientAllowance-address-uint256-uint256-}[`++ERC20InsufficientAllowance(spender, allowance, needed)++`] +* {xref-IERC20Errors-ERC20InvalidApprover-address-}[`++ERC20InvalidApprover(approver)++`] +* {xref-IERC20Errors-ERC20InvalidSpender-address-}[`++ERC20InvalidSpender(spender)++`] + +[.contract-subindex-inherited] +.IERC20Metadata + +[.contract-subindex-inherited] +.IERC20 + +-- + +[.contract-item] +[[ERC20Pausable-_update-address-address-uint256-]] +==== `[.contract-item-name]#++_update++#++(address from, address to, uint256 value)++` [.item-kind]#internal# + +See {ERC20-_update}. + +Requirements: + +- the contract must not be paused. + +:ERC20ExceededSafeSupply: pass:normal[xref:#ERC20Votes-ERC20ExceededSafeSupply-uint256-uint256-[`++ERC20ExceededSafeSupply++`]] +:_maxSupply: pass:normal[xref:#ERC20Votes-_maxSupply--[`++_maxSupply++`]] +:_update: pass:normal[xref:#ERC20Votes-_update-address-address-uint256-[`++_update++`]] +:_getVotingUnits: pass:normal[xref:#ERC20Votes-_getVotingUnits-address-[`++_getVotingUnits++`]] +:numCheckpoints: pass:normal[xref:#ERC20Votes-numCheckpoints-address-[`++numCheckpoints++`]] +:checkpoints: pass:normal[xref:#ERC20Votes-checkpoints-address-uint32-[`++checkpoints++`]] + +[.contract] +[[ERC20Votes]] +=== `++ERC20Votes++` link:https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v5.0.0-rc.0/contracts/token/ERC20/extensions/ERC20Votes.sol[{github-icon},role=heading-link] + +[.hljs-theme-light.nopadding] +```solidity +import "@openzeppelin/contracts/token/ERC20/extensions/ERC20Votes.sol"; +``` + +Extension of ERC20 to support Compound-like voting and delegation. This version is more generic than Compound's, +and supports token supply up to 2^208^ - 1, while COMP is limited to 2^96^ - 1. + +NOTE: This contract does not provide interface compatibility with Compound's COMP token. + +This extension keeps a history (checkpoints) of each account's vote power. Vote power can be delegated either +by calling the {delegate} function directly, or by providing a signature to be used with {delegateBySig}. Voting +power can be queried through the public accessors {getVotes} and {getPastVotes}. + +By default, token balance does not account for voting power. This makes transfers cheaper. The downside is that it +requires users to delegate to themselves in order to activate checkpoints and have their voting power tracked. + +[.contract-index] +.Functions +-- +* {xref-ERC20Votes-_maxSupply--}[`++_maxSupply()++`] +* {xref-ERC20Votes-_update-address-address-uint256-}[`++_update(from, to, value)++`] +* {xref-ERC20Votes-_getVotingUnits-address-}[`++_getVotingUnits(account)++`] +* {xref-ERC20Votes-numCheckpoints-address-}[`++numCheckpoints(account)++`] +* {xref-ERC20Votes-checkpoints-address-uint32-}[`++checkpoints(account, pos)++`] + +[.contract-subindex-inherited] +.Votes +* {xref-Votes-clock--}[`++clock()++`] +* {xref-Votes-CLOCK_MODE--}[`++CLOCK_MODE()++`] +* {xref-Votes-getVotes-address-}[`++getVotes(account)++`] +* {xref-Votes-getPastVotes-address-uint256-}[`++getPastVotes(account, timepoint)++`] +* {xref-Votes-getPastTotalSupply-uint256-}[`++getPastTotalSupply(timepoint)++`] +* {xref-Votes-_getTotalSupply--}[`++_getTotalSupply()++`] +* {xref-Votes-delegates-address-}[`++delegates(account)++`] +* {xref-Votes-delegate-address-}[`++delegate(delegatee)++`] +* {xref-Votes-delegateBySig-address-uint256-uint256-uint8-bytes32-bytes32-}[`++delegateBySig(delegatee, nonce, expiry, v, r, s)++`] +* {xref-Votes-_delegate-address-address-}[`++_delegate(account, delegatee)++`] +* {xref-Votes-_transferVotingUnits-address-address-uint256-}[`++_transferVotingUnits(from, to, amount)++`] +* {xref-Votes-_numCheckpoints-address-}[`++_numCheckpoints(account)++`] +* {xref-Votes-_checkpoints-address-uint32-}[`++_checkpoints(account, pos)++`] + +[.contract-subindex-inherited] +.IERC5805 + +[.contract-subindex-inherited] +.IVotes + +[.contract-subindex-inherited] +.IERC6372 + +[.contract-subindex-inherited] +.Nonces +* {xref-Nonces-nonces-address-}[`++nonces(owner)++`] +* {xref-Nonces-_useNonce-address-}[`++_useNonce(owner)++`] +* {xref-Nonces-_useCheckedNonce-address-uint256-}[`++_useCheckedNonce(owner, nonce)++`] + +[.contract-subindex-inherited] +.EIP712 +* {xref-EIP712-_domainSeparatorV4--}[`++_domainSeparatorV4()++`] +* {xref-EIP712-_hashTypedDataV4-bytes32-}[`++_hashTypedDataV4(structHash)++`] +* {xref-EIP712-eip712Domain--}[`++eip712Domain()++`] +* {xref-EIP712-_EIP712Name--}[`++_EIP712Name()++`] +* {xref-EIP712-_EIP712Version--}[`++_EIP712Version()++`] + +[.contract-subindex-inherited] +.IERC5267 + +[.contract-subindex-inherited] +.ERC20 +* {xref-ERC20-name--}[`++name()++`] +* {xref-ERC20-symbol--}[`++symbol()++`] +* {xref-ERC20-decimals--}[`++decimals()++`] +* {xref-ERC20-totalSupply--}[`++totalSupply()++`] +* {xref-ERC20-balanceOf-address-}[`++balanceOf(account)++`] +* {xref-ERC20-transfer-address-uint256-}[`++transfer(to, value)++`] +* {xref-ERC20-allowance-address-address-}[`++allowance(owner, spender)++`] +* {xref-ERC20-approve-address-uint256-}[`++approve(spender, value)++`] +* {xref-ERC20-transferFrom-address-address-uint256-}[`++transferFrom(from, to, value)++`] +* {xref-ERC20-_transfer-address-address-uint256-}[`++_transfer(from, to, value)++`] +* {xref-ERC20-_mint-address-uint256-}[`++_mint(account, value)++`] +* {xref-ERC20-_burn-address-uint256-}[`++_burn(account, value)++`] +* {xref-ERC20-_approve-address-address-uint256-}[`++_approve(owner, spender, value)++`] +* {xref-ERC20-_approve-address-address-uint256-bool-}[`++_approve(owner, spender, value, emitEvent)++`] +* {xref-ERC20-_spendAllowance-address-address-uint256-}[`++_spendAllowance(owner, spender, value)++`] + +[.contract-subindex-inherited] +.IERC20Errors + +[.contract-subindex-inherited] +.IERC20Metadata + +[.contract-subindex-inherited] +.IERC20 + +-- + +[.contract-index] +.Events +-- + +[.contract-subindex-inherited] +.Votes + +[.contract-subindex-inherited] +.IERC5805 + +[.contract-subindex-inherited] +.IVotes +* {xref-IVotes-DelegateChanged-address-address-address-}[`++DelegateChanged(delegator, fromDelegate, toDelegate)++`] +* {xref-IVotes-DelegateVotesChanged-address-uint256-uint256-}[`++DelegateVotesChanged(delegate, previousVotes, newVotes)++`] + +[.contract-subindex-inherited] +.IERC6372 + +[.contract-subindex-inherited] +.Nonces + +[.contract-subindex-inherited] +.EIP712 + +[.contract-subindex-inherited] +.IERC5267 +* {xref-IERC5267-EIP712DomainChanged--}[`++EIP712DomainChanged()++`] + +[.contract-subindex-inherited] +.ERC20 + +[.contract-subindex-inherited] +.IERC20Errors + +[.contract-subindex-inherited] +.IERC20Metadata + +[.contract-subindex-inherited] +.IERC20 +* {xref-IERC20-Transfer-address-address-uint256-}[`++Transfer(from, to, value)++`] +* {xref-IERC20-Approval-address-address-uint256-}[`++Approval(owner, spender, value)++`] + +-- + +[.contract-index] +.Errors +-- +* {xref-ERC20Votes-ERC20ExceededSafeSupply-uint256-uint256-}[`++ERC20ExceededSafeSupply(increasedSupply, cap)++`] + +[.contract-subindex-inherited] +.Votes +* {xref-Votes-ERC6372InconsistentClock--}[`++ERC6372InconsistentClock()++`] +* {xref-Votes-ERC5805FutureLookup-uint256-uint48-}[`++ERC5805FutureLookup(timepoint, clock)++`] + +[.contract-subindex-inherited] +.IERC5805 + +[.contract-subindex-inherited] +.IVotes +* {xref-IVotes-VotesExpiredSignature-uint256-}[`++VotesExpiredSignature(expiry)++`] + +[.contract-subindex-inherited] +.IERC6372 + +[.contract-subindex-inherited] +.Nonces +* {xref-Nonces-InvalidAccountNonce-address-uint256-}[`++InvalidAccountNonce(account, currentNonce)++`] + +[.contract-subindex-inherited] +.EIP712 + +[.contract-subindex-inherited] +.IERC5267 + +[.contract-subindex-inherited] +.ERC20 + +[.contract-subindex-inherited] +.IERC20Errors +* {xref-IERC20Errors-ERC20InsufficientBalance-address-uint256-uint256-}[`++ERC20InsufficientBalance(sender, balance, needed)++`] +* {xref-IERC20Errors-ERC20InvalidSender-address-}[`++ERC20InvalidSender(sender)++`] +* {xref-IERC20Errors-ERC20InvalidReceiver-address-}[`++ERC20InvalidReceiver(receiver)++`] +* {xref-IERC20Errors-ERC20InsufficientAllowance-address-uint256-uint256-}[`++ERC20InsufficientAllowance(spender, allowance, needed)++`] +* {xref-IERC20Errors-ERC20InvalidApprover-address-}[`++ERC20InvalidApprover(approver)++`] +* {xref-IERC20Errors-ERC20InvalidSpender-address-}[`++ERC20InvalidSpender(spender)++`] + +[.contract-subindex-inherited] +.IERC20Metadata + +[.contract-subindex-inherited] +.IERC20 + +-- + +[.contract-item] +[[ERC20Votes-_maxSupply--]] +==== `[.contract-item-name]#++_maxSupply++#++() → uint256++` [.item-kind]#internal# + +Maximum token supply. Defaults to `type(uint208).max` (2^208^ - 1). + +This maximum is enforced in {_update}. It limits the total supply of the token, which is otherwise a uint256, +so that checkpoints can be stored in the Trace208 structure used by {{Votes}}. Increasing this value will not +remove the underlying limitation, and will cause {_update} to fail because of a math overflow in +{_transferVotingUnits}. An override could be used to further restrict the total supply (to a lower value) if +additional logic requires it. When resolving override conflicts on this function, the minimum should be +returned. + +[.contract-item] +[[ERC20Votes-_update-address-address-uint256-]] +==== `[.contract-item-name]#++_update++#++(address from, address to, uint256 value)++` [.item-kind]#internal# + +Move voting power when tokens are transferred. + +Emits a {IVotes-DelegateVotesChanged} event. + +[.contract-item] +[[ERC20Votes-_getVotingUnits-address-]] +==== `[.contract-item-name]#++_getVotingUnits++#++(address account) → uint256++` [.item-kind]#internal# + +Returns the voting units of an `account`. + +WARNING: Overriding this function may compromise the internal vote accounting. +`ERC20Votes` assumes tokens map to voting units 1:1 and this is not easy to change. + +[.contract-item] +[[ERC20Votes-numCheckpoints-address-]] +==== `[.contract-item-name]#++numCheckpoints++#++(address account) → uint32++` [.item-kind]#public# + +Get number of checkpoints for `account`. + +[.contract-item] +[[ERC20Votes-checkpoints-address-uint32-]] +==== `[.contract-item-name]#++checkpoints++#++(address account, uint32 pos) → struct Checkpoints.Checkpoint208++` [.item-kind]#public# + +Get the `pos`-th checkpoint for `account`. + +[.contract-item] +[[ERC20Votes-ERC20ExceededSafeSupply-uint256-uint256-]] +==== `[.contract-item-name]#++ERC20ExceededSafeSupply++#++(uint256 increasedSupply, uint256 cap)++` [.item-kind]#error# + +Total supply cap has been exceeded, introducing a risk of votes overflowing. + +:ERC20InvalidUnderlying: pass:normal[xref:#ERC20Wrapper-ERC20InvalidUnderlying-address-[`++ERC20InvalidUnderlying++`]] +:constructor: pass:normal[xref:#ERC20Wrapper-constructor-contract-IERC20-[`++constructor++`]] +:decimals: pass:normal[xref:#ERC20Wrapper-decimals--[`++decimals++`]] +:underlying: pass:normal[xref:#ERC20Wrapper-underlying--[`++underlying++`]] +:depositFor: pass:normal[xref:#ERC20Wrapper-depositFor-address-uint256-[`++depositFor++`]] +:withdrawTo: pass:normal[xref:#ERC20Wrapper-withdrawTo-address-uint256-[`++withdrawTo++`]] +:_recover: pass:normal[xref:#ERC20Wrapper-_recover-address-[`++_recover++`]] + +[.contract] +[[ERC20Wrapper]] +=== `++ERC20Wrapper++` link:https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v5.0.0-rc.0/contracts/token/ERC20/extensions/ERC20Wrapper.sol[{github-icon},role=heading-link] + +[.hljs-theme-light.nopadding] +```solidity +import "@openzeppelin/contracts/token/ERC20/extensions/ERC20Wrapper.sol"; +``` + +Extension of the ERC20 token contract to support token wrapping. + +Users can deposit and withdraw "underlying tokens" and receive a matching number of "wrapped tokens". This is useful +in conjunction with other modules. For example, combining this wrapping mechanism with {ERC20Votes} will allow the +wrapping of an existing "basic" ERC20 into a governance token. + +[.contract-index] +.Functions +-- +* {xref-ERC20Wrapper-constructor-contract-IERC20-}[`++constructor(underlyingToken)++`] +* {xref-ERC20Wrapper-decimals--}[`++decimals()++`] +* {xref-ERC20Wrapper-underlying--}[`++underlying()++`] +* {xref-ERC20Wrapper-depositFor-address-uint256-}[`++depositFor(account, value)++`] +* {xref-ERC20Wrapper-withdrawTo-address-uint256-}[`++withdrawTo(account, value)++`] +* {xref-ERC20Wrapper-_recover-address-}[`++_recover(account)++`] + +[.contract-subindex-inherited] +.ERC20 +* {xref-ERC20-name--}[`++name()++`] +* {xref-ERC20-symbol--}[`++symbol()++`] +* {xref-ERC20-totalSupply--}[`++totalSupply()++`] +* {xref-ERC20-balanceOf-address-}[`++balanceOf(account)++`] +* {xref-ERC20-transfer-address-uint256-}[`++transfer(to, value)++`] +* {xref-ERC20-allowance-address-address-}[`++allowance(owner, spender)++`] +* {xref-ERC20-approve-address-uint256-}[`++approve(spender, value)++`] +* {xref-ERC20-transferFrom-address-address-uint256-}[`++transferFrom(from, to, value)++`] +* {xref-ERC20-_transfer-address-address-uint256-}[`++_transfer(from, to, value)++`] +* {xref-ERC20-_update-address-address-uint256-}[`++_update(from, to, value)++`] +* {xref-ERC20-_mint-address-uint256-}[`++_mint(account, value)++`] +* {xref-ERC20-_burn-address-uint256-}[`++_burn(account, value)++`] +* {xref-ERC20-_approve-address-address-uint256-}[`++_approve(owner, spender, value)++`] +* {xref-ERC20-_approve-address-address-uint256-bool-}[`++_approve(owner, spender, value, emitEvent)++`] +* {xref-ERC20-_spendAllowance-address-address-uint256-}[`++_spendAllowance(owner, spender, value)++`] + +[.contract-subindex-inherited] +.IERC20Errors + +[.contract-subindex-inherited] +.IERC20Metadata + +[.contract-subindex-inherited] +.IERC20 + +-- + +[.contract-index] +.Events +-- + +[.contract-subindex-inherited] +.ERC20 + +[.contract-subindex-inherited] +.IERC20Errors + +[.contract-subindex-inherited] +.IERC20Metadata + +[.contract-subindex-inherited] +.IERC20 +* {xref-IERC20-Transfer-address-address-uint256-}[`++Transfer(from, to, value)++`] +* {xref-IERC20-Approval-address-address-uint256-}[`++Approval(owner, spender, value)++`] + +-- + +[.contract-index] +.Errors +-- +* {xref-ERC20Wrapper-ERC20InvalidUnderlying-address-}[`++ERC20InvalidUnderlying(token)++`] + +[.contract-subindex-inherited] +.ERC20 + +[.contract-subindex-inherited] +.IERC20Errors +* {xref-IERC20Errors-ERC20InsufficientBalance-address-uint256-uint256-}[`++ERC20InsufficientBalance(sender, balance, needed)++`] +* {xref-IERC20Errors-ERC20InvalidSender-address-}[`++ERC20InvalidSender(sender)++`] +* {xref-IERC20Errors-ERC20InvalidReceiver-address-}[`++ERC20InvalidReceiver(receiver)++`] +* {xref-IERC20Errors-ERC20InsufficientAllowance-address-uint256-uint256-}[`++ERC20InsufficientAllowance(spender, allowance, needed)++`] +* {xref-IERC20Errors-ERC20InvalidApprover-address-}[`++ERC20InvalidApprover(approver)++`] +* {xref-IERC20Errors-ERC20InvalidSpender-address-}[`++ERC20InvalidSpender(spender)++`] + +[.contract-subindex-inherited] +.IERC20Metadata + +[.contract-subindex-inherited] +.IERC20 + +-- + +[.contract-item] +[[ERC20Wrapper-constructor-contract-IERC20-]] +==== `[.contract-item-name]#++constructor++#++(contract IERC20 underlyingToken)++` [.item-kind]#internal# + +[.contract-item] +[[ERC20Wrapper-decimals--]] +==== `[.contract-item-name]#++decimals++#++() → uint8++` [.item-kind]#public# + +See {ERC20-decimals}. + +[.contract-item] +[[ERC20Wrapper-underlying--]] +==== `[.contract-item-name]#++underlying++#++() → contract IERC20++` [.item-kind]#public# + +Returns the address of the underlying ERC-20 token that is being wrapped. + +[.contract-item] +[[ERC20Wrapper-depositFor-address-uint256-]] +==== `[.contract-item-name]#++depositFor++#++(address account, uint256 value) → bool++` [.item-kind]#public# + +Allow a user to deposit underlying tokens and mint the corresponding number of wrapped tokens. + +[.contract-item] +[[ERC20Wrapper-withdrawTo-address-uint256-]] +==== `[.contract-item-name]#++withdrawTo++#++(address account, uint256 value) → bool++` [.item-kind]#public# + +Allow a user to burn a number of wrapped tokens and withdraw the corresponding number of underlying tokens. + +[.contract-item] +[[ERC20Wrapper-_recover-address-]] +==== `[.contract-item-name]#++_recover++#++(address account) → uint256++` [.item-kind]#internal# + +Mint wrapped token to cover any underlyingTokens that would have been transferred by mistake. Internal +function that can be exposed with access control if desired. + +[.contract-item] +[[ERC20Wrapper-ERC20InvalidUnderlying-address-]] +==== `[.contract-item-name]#++ERC20InvalidUnderlying++#++(address token)++` [.item-kind]#error# + +The underlying token couldn't be wrapped. + +:ERC3156UnsupportedToken: pass:normal[xref:#ERC20FlashMint-ERC3156UnsupportedToken-address-[`++ERC3156UnsupportedToken++`]] +:ERC3156ExceededMaxLoan: pass:normal[xref:#ERC20FlashMint-ERC3156ExceededMaxLoan-uint256-[`++ERC3156ExceededMaxLoan++`]] +:ERC3156InvalidReceiver: pass:normal[xref:#ERC20FlashMint-ERC3156InvalidReceiver-address-[`++ERC3156InvalidReceiver++`]] +:maxFlashLoan: pass:normal[xref:#ERC20FlashMint-maxFlashLoan-address-[`++maxFlashLoan++`]] +:flashFee: pass:normal[xref:#ERC20FlashMint-flashFee-address-uint256-[`++flashFee++`]] +:_flashFee: pass:normal[xref:#ERC20FlashMint-_flashFee-address-uint256-[`++_flashFee++`]] +:_flashFeeReceiver: pass:normal[xref:#ERC20FlashMint-_flashFeeReceiver--[`++_flashFeeReceiver++`]] +:flashLoan: pass:normal[xref:#ERC20FlashMint-flashLoan-contract-IERC3156FlashBorrower-address-uint256-bytes-[`++flashLoan++`]] + +[.contract] +[[ERC20FlashMint]] +=== `++ERC20FlashMint++` link:https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v5.0.0-rc.0/contracts/token/ERC20/extensions/ERC20FlashMint.sol[{github-icon},role=heading-link] + +[.hljs-theme-light.nopadding] +```solidity +import "@openzeppelin/contracts/token/ERC20/extensions/ERC20FlashMint.sol"; +``` + +Implementation of the ERC3156 Flash loans extension, as defined in +https://eips.ethereum.org/EIPS/eip-3156[ERC-3156]. + +Adds the {flashLoan} method, which provides flash loan support at the token +level. By default there is no fee, but this can be changed by overriding {flashFee}. + +NOTE: When this extension is used along with the {ERC20Capped} or {ERC20Votes} extensions, +{maxFlashLoan} will not correctly reflect the maximum that can be flash minted. We recommend +overriding {maxFlashLoan} so that it correctly reflects the supply cap. + +[.contract-index] +.Functions +-- +* {xref-ERC20FlashMint-maxFlashLoan-address-}[`++maxFlashLoan(token)++`] +* {xref-ERC20FlashMint-flashFee-address-uint256-}[`++flashFee(token, value)++`] +* {xref-ERC20FlashMint-_flashFee-address-uint256-}[`++_flashFee(token, value)++`] +* {xref-ERC20FlashMint-_flashFeeReceiver--}[`++_flashFeeReceiver()++`] +* {xref-ERC20FlashMint-flashLoan-contract-IERC3156FlashBorrower-address-uint256-bytes-}[`++flashLoan(receiver, token, value, data)++`] + +[.contract-subindex-inherited] +.IERC3156FlashLender + +[.contract-subindex-inherited] +.ERC20 +* {xref-ERC20-name--}[`++name()++`] +* {xref-ERC20-symbol--}[`++symbol()++`] +* {xref-ERC20-decimals--}[`++decimals()++`] +* {xref-ERC20-totalSupply--}[`++totalSupply()++`] +* {xref-ERC20-balanceOf-address-}[`++balanceOf(account)++`] +* {xref-ERC20-transfer-address-uint256-}[`++transfer(to, value)++`] +* {xref-ERC20-allowance-address-address-}[`++allowance(owner, spender)++`] +* {xref-ERC20-approve-address-uint256-}[`++approve(spender, value)++`] +* {xref-ERC20-transferFrom-address-address-uint256-}[`++transferFrom(from, to, value)++`] +* {xref-ERC20-_transfer-address-address-uint256-}[`++_transfer(from, to, value)++`] +* {xref-ERC20-_update-address-address-uint256-}[`++_update(from, to, value)++`] +* {xref-ERC20-_mint-address-uint256-}[`++_mint(account, value)++`] +* {xref-ERC20-_burn-address-uint256-}[`++_burn(account, value)++`] +* {xref-ERC20-_approve-address-address-uint256-}[`++_approve(owner, spender, value)++`] +* {xref-ERC20-_approve-address-address-uint256-bool-}[`++_approve(owner, spender, value, emitEvent)++`] +* {xref-ERC20-_spendAllowance-address-address-uint256-}[`++_spendAllowance(owner, spender, value)++`] + +[.contract-subindex-inherited] +.IERC20Errors + +[.contract-subindex-inherited] +.IERC20Metadata + +[.contract-subindex-inherited] +.IERC20 + +-- + +[.contract-index] +.Events +-- + +[.contract-subindex-inherited] +.IERC3156FlashLender + +[.contract-subindex-inherited] +.ERC20 + +[.contract-subindex-inherited] +.IERC20Errors + +[.contract-subindex-inherited] +.IERC20Metadata + +[.contract-subindex-inherited] +.IERC20 +* {xref-IERC20-Transfer-address-address-uint256-}[`++Transfer(from, to, value)++`] +* {xref-IERC20-Approval-address-address-uint256-}[`++Approval(owner, spender, value)++`] + +-- + +[.contract-index] +.Errors +-- +* {xref-ERC20FlashMint-ERC3156UnsupportedToken-address-}[`++ERC3156UnsupportedToken(token)++`] +* {xref-ERC20FlashMint-ERC3156ExceededMaxLoan-uint256-}[`++ERC3156ExceededMaxLoan(maxLoan)++`] +* {xref-ERC20FlashMint-ERC3156InvalidReceiver-address-}[`++ERC3156InvalidReceiver(receiver)++`] + +[.contract-subindex-inherited] +.IERC3156FlashLender + +[.contract-subindex-inherited] +.ERC20 + +[.contract-subindex-inherited] +.IERC20Errors +* {xref-IERC20Errors-ERC20InsufficientBalance-address-uint256-uint256-}[`++ERC20InsufficientBalance(sender, balance, needed)++`] +* {xref-IERC20Errors-ERC20InvalidSender-address-}[`++ERC20InvalidSender(sender)++`] +* {xref-IERC20Errors-ERC20InvalidReceiver-address-}[`++ERC20InvalidReceiver(receiver)++`] +* {xref-IERC20Errors-ERC20InsufficientAllowance-address-uint256-uint256-}[`++ERC20InsufficientAllowance(spender, allowance, needed)++`] +* {xref-IERC20Errors-ERC20InvalidApprover-address-}[`++ERC20InvalidApprover(approver)++`] +* {xref-IERC20Errors-ERC20InvalidSpender-address-}[`++ERC20InvalidSpender(spender)++`] + +[.contract-subindex-inherited] +.IERC20Metadata + +[.contract-subindex-inherited] +.IERC20 + +-- + +[.contract-item] +[[ERC20FlashMint-maxFlashLoan-address-]] +==== `[.contract-item-name]#++maxFlashLoan++#++(address token) → uint256++` [.item-kind]#public# + +Returns the maximum amount of tokens available for loan. + +[.contract-item] +[[ERC20FlashMint-flashFee-address-uint256-]] +==== `[.contract-item-name]#++flashFee++#++(address token, uint256 value) → uint256++` [.item-kind]#public# + +Returns the fee applied when doing flash loans. This function calls +the {_flashFee} function which returns the fee applied when doing flash +loans. + +[.contract-item] +[[ERC20FlashMint-_flashFee-address-uint256-]] +==== `[.contract-item-name]#++_flashFee++#++(address token, uint256 value) → uint256++` [.item-kind]#internal# + +Returns the fee applied when doing flash loans. By default this +implementation has 0 fees. This function can be overloaded to make +the flash loan mechanism deflationary. + +[.contract-item] +[[ERC20FlashMint-_flashFeeReceiver--]] +==== `[.contract-item-name]#++_flashFeeReceiver++#++() → address++` [.item-kind]#internal# + +Returns the receiver address of the flash fee. By default this +implementation returns the address(0) which means the fee amount will be burnt. +This function can be overloaded to change the fee receiver. + +[.contract-item] +[[ERC20FlashMint-flashLoan-contract-IERC3156FlashBorrower-address-uint256-bytes-]] +==== `[.contract-item-name]#++flashLoan++#++(contract IERC3156FlashBorrower receiver, address token, uint256 value, bytes data) → bool++` [.item-kind]#public# + +Performs a flash loan. New tokens are minted and sent to the +`receiver`, who is required to implement the {IERC3156FlashBorrower} +interface. By the end of the flash loan, the receiver is expected to own +value + fee tokens and have them approved back to the token contract itself so +they can be burned. + +[.contract-item] +[[ERC20FlashMint-ERC3156UnsupportedToken-address-]] +==== `[.contract-item-name]#++ERC3156UnsupportedToken++#++(address token)++` [.item-kind]#error# + +The loan token is not valid. + +[.contract-item] +[[ERC20FlashMint-ERC3156ExceededMaxLoan-uint256-]] +==== `[.contract-item-name]#++ERC3156ExceededMaxLoan++#++(uint256 maxLoan)++` [.item-kind]#error# + +The requested loan exceeds the max loan value for `token`. + +[.contract-item] +[[ERC20FlashMint-ERC3156InvalidReceiver-address-]] +==== `[.contract-item-name]#++ERC3156InvalidReceiver++#++(address receiver)++` [.item-kind]#error# + +The receiver of a flashloan is not a valid {onFlashLoan} implementer. + +:ERC4626ExceededMaxDeposit: pass:normal[xref:#ERC4626-ERC4626ExceededMaxDeposit-address-uint256-uint256-[`++ERC4626ExceededMaxDeposit++`]] +:ERC4626ExceededMaxMint: pass:normal[xref:#ERC4626-ERC4626ExceededMaxMint-address-uint256-uint256-[`++ERC4626ExceededMaxMint++`]] +:ERC4626ExceededMaxWithdraw: pass:normal[xref:#ERC4626-ERC4626ExceededMaxWithdraw-address-uint256-uint256-[`++ERC4626ExceededMaxWithdraw++`]] +:ERC4626ExceededMaxRedeem: pass:normal[xref:#ERC4626-ERC4626ExceededMaxRedeem-address-uint256-uint256-[`++ERC4626ExceededMaxRedeem++`]] +:constructor: pass:normal[xref:#ERC4626-constructor-contract-IERC20-[`++constructor++`]] +:decimals: pass:normal[xref:#ERC4626-decimals--[`++decimals++`]] +:asset: pass:normal[xref:#ERC4626-asset--[`++asset++`]] +:totalAssets: pass:normal[xref:#ERC4626-totalAssets--[`++totalAssets++`]] +:convertToShares: pass:normal[xref:#ERC4626-convertToShares-uint256-[`++convertToShares++`]] +:convertToAssets: pass:normal[xref:#ERC4626-convertToAssets-uint256-[`++convertToAssets++`]] +:maxDeposit: pass:normal[xref:#ERC4626-maxDeposit-address-[`++maxDeposit++`]] +:maxMint: pass:normal[xref:#ERC4626-maxMint-address-[`++maxMint++`]] +:maxWithdraw: pass:normal[xref:#ERC4626-maxWithdraw-address-[`++maxWithdraw++`]] +:maxRedeem: pass:normal[xref:#ERC4626-maxRedeem-address-[`++maxRedeem++`]] +:previewDeposit: pass:normal[xref:#ERC4626-previewDeposit-uint256-[`++previewDeposit++`]] +:previewMint: pass:normal[xref:#ERC4626-previewMint-uint256-[`++previewMint++`]] +:previewWithdraw: pass:normal[xref:#ERC4626-previewWithdraw-uint256-[`++previewWithdraw++`]] +:previewRedeem: pass:normal[xref:#ERC4626-previewRedeem-uint256-[`++previewRedeem++`]] +:deposit: pass:normal[xref:#ERC4626-deposit-uint256-address-[`++deposit++`]] +:mint: pass:normal[xref:#ERC4626-mint-uint256-address-[`++mint++`]] +:withdraw: pass:normal[xref:#ERC4626-withdraw-uint256-address-address-[`++withdraw++`]] +:redeem: pass:normal[xref:#ERC4626-redeem-uint256-address-address-[`++redeem++`]] +:_convertToShares: pass:normal[xref:#ERC4626-_convertToShares-uint256-enum-Math-Rounding-[`++_convertToShares++`]] +:_convertToAssets: pass:normal[xref:#ERC4626-_convertToAssets-uint256-enum-Math-Rounding-[`++_convertToAssets++`]] +:_deposit: pass:normal[xref:#ERC4626-_deposit-address-address-uint256-uint256-[`++_deposit++`]] +:_withdraw: pass:normal[xref:#ERC4626-_withdraw-address-address-address-uint256-uint256-[`++_withdraw++`]] +:_decimalsOffset: pass:normal[xref:#ERC4626-_decimalsOffset--[`++_decimalsOffset++`]] + +[.contract] +[[ERC4626]] +=== `++ERC4626++` link:https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v5.0.0-rc.0/contracts/token/ERC20/extensions/ERC4626.sol[{github-icon},role=heading-link] + +[.hljs-theme-light.nopadding] +```solidity +import "@openzeppelin/contracts/token/ERC20/extensions/ERC4626.sol"; +``` + +Implementation of the ERC4626 "Tokenized Vault Standard" as defined in +https://eips.ethereum.org/EIPS/eip-4626[EIP-4626]. + +This extension allows the minting and burning of "shares" (represented using the ERC20 inheritance) in exchange for +underlying "assets" through standardized {deposit}, {mint}, {redeem} and {burn} workflows. This contract extends +the ERC20 standard. Any additional extensions included along it would affect the "shares" token represented by this +contract and not the "assets" token which is an independent contract. + +[CAUTION] +==== +In empty (or nearly empty) ERC-4626 vaults, deposits are at high risk of being stolen through frontrunning +with a "donation" to the vault that inflates the price of a share. This is variously known as a donation or inflation +attack and is essentially a problem of slippage. Vault deployers can protect against this attack by making an initial +deposit of a non-trivial amount of the asset, such that price manipulation becomes infeasible. Withdrawals may +similarly be affected by slippage. Users can protect against this attack as well as unexpected slippage in general by +verifying the amount received is as expected, using a wrapper that performs these checks such as +https://github.com/fei-protocol/ERC4626#erc4626router-and-base[ERC4626Router]. + +Since v4.9, this implementation uses virtual assets and shares to mitigate that risk. The `_decimalsOffset()` +corresponds to an offset in the decimal representation between the underlying asset's decimals and the vault +decimals. This offset also determines the rate of virtual shares to virtual assets in the vault, which itself +determines the initial exchange rate. While not fully preventing the attack, analysis shows that the default offset +(0) makes it non-profitable, as a result of the value being captured by the virtual shares (out of the attacker's +donation) matching the attacker's expected gains. With a larger offset, the attack becomes orders of magnitude more +expensive than it is profitable. More details about the underlying math can be found +xref:erc4626.adoc#inflation-attack[here]. + +The drawback of this approach is that the virtual shares do capture (a very small) part of the value being accrued +to the vault. Also, if the vault experiences losses, the users try to exit the vault, the virtual shares and assets +will cause the first user to exit to experience reduced losses in detriment to the last users that will experience +bigger losses. Developers willing to revert back to the pre-v4.9 behavior just need to override the +`_convertToShares` and `_convertToAssets` functions. + +To learn more, check out our xref:ROOT:erc4626.adoc[ERC-4626 guide]. +==== + +[.contract-index] +.Functions +-- +* {xref-ERC4626-constructor-contract-IERC20-}[`++constructor(asset_)++`] +* {xref-ERC4626-decimals--}[`++decimals()++`] +* {xref-ERC4626-asset--}[`++asset()++`] +* {xref-ERC4626-totalAssets--}[`++totalAssets()++`] +* {xref-ERC4626-convertToShares-uint256-}[`++convertToShares(assets)++`] +* {xref-ERC4626-convertToAssets-uint256-}[`++convertToAssets(shares)++`] +* {xref-ERC4626-maxDeposit-address-}[`++maxDeposit()++`] +* {xref-ERC4626-maxMint-address-}[`++maxMint()++`] +* {xref-ERC4626-maxWithdraw-address-}[`++maxWithdraw(owner)++`] +* {xref-ERC4626-maxRedeem-address-}[`++maxRedeem(owner)++`] +* {xref-ERC4626-previewDeposit-uint256-}[`++previewDeposit(assets)++`] +* {xref-ERC4626-previewMint-uint256-}[`++previewMint(shares)++`] +* {xref-ERC4626-previewWithdraw-uint256-}[`++previewWithdraw(assets)++`] +* {xref-ERC4626-previewRedeem-uint256-}[`++previewRedeem(shares)++`] +* {xref-ERC4626-deposit-uint256-address-}[`++deposit(assets, receiver)++`] +* {xref-ERC4626-mint-uint256-address-}[`++mint(shares, receiver)++`] +* {xref-ERC4626-withdraw-uint256-address-address-}[`++withdraw(assets, receiver, owner)++`] +* {xref-ERC4626-redeem-uint256-address-address-}[`++redeem(shares, receiver, owner)++`] +* {xref-ERC4626-_convertToShares-uint256-enum-Math-Rounding-}[`++_convertToShares(assets, rounding)++`] +* {xref-ERC4626-_convertToAssets-uint256-enum-Math-Rounding-}[`++_convertToAssets(shares, rounding)++`] +* {xref-ERC4626-_deposit-address-address-uint256-uint256-}[`++_deposit(caller, receiver, assets, shares)++`] +* {xref-ERC4626-_withdraw-address-address-address-uint256-uint256-}[`++_withdraw(caller, receiver, owner, assets, shares)++`] +* {xref-ERC4626-_decimalsOffset--}[`++_decimalsOffset()++`] + +[.contract-subindex-inherited] +.IERC4626 + +[.contract-subindex-inherited] +.ERC20 +* {xref-ERC20-name--}[`++name()++`] +* {xref-ERC20-symbol--}[`++symbol()++`] +* {xref-ERC20-totalSupply--}[`++totalSupply()++`] +* {xref-ERC20-balanceOf-address-}[`++balanceOf(account)++`] +* {xref-ERC20-transfer-address-uint256-}[`++transfer(to, value)++`] +* {xref-ERC20-allowance-address-address-}[`++allowance(owner, spender)++`] +* {xref-ERC20-approve-address-uint256-}[`++approve(spender, value)++`] +* {xref-ERC20-transferFrom-address-address-uint256-}[`++transferFrom(from, to, value)++`] +* {xref-ERC20-_transfer-address-address-uint256-}[`++_transfer(from, to, value)++`] +* {xref-ERC20-_update-address-address-uint256-}[`++_update(from, to, value)++`] +* {xref-ERC20-_mint-address-uint256-}[`++_mint(account, value)++`] +* {xref-ERC20-_burn-address-uint256-}[`++_burn(account, value)++`] +* {xref-ERC20-_approve-address-address-uint256-}[`++_approve(owner, spender, value)++`] +* {xref-ERC20-_approve-address-address-uint256-bool-}[`++_approve(owner, spender, value, emitEvent)++`] +* {xref-ERC20-_spendAllowance-address-address-uint256-}[`++_spendAllowance(owner, spender, value)++`] + +[.contract-subindex-inherited] +.IERC20Errors + +[.contract-subindex-inherited] +.IERC20Metadata + +[.contract-subindex-inherited] +.IERC20 + +-- + +[.contract-index] +.Events +-- + +[.contract-subindex-inherited] +.IERC4626 +* {xref-IERC4626-Deposit-address-address-uint256-uint256-}[`++Deposit(sender, owner, assets, shares)++`] +* {xref-IERC4626-Withdraw-address-address-address-uint256-uint256-}[`++Withdraw(sender, receiver, owner, assets, shares)++`] + +[.contract-subindex-inherited] +.ERC20 + +[.contract-subindex-inherited] +.IERC20Errors + +[.contract-subindex-inherited] +.IERC20Metadata + +[.contract-subindex-inherited] +.IERC20 +* {xref-IERC20-Transfer-address-address-uint256-}[`++Transfer(from, to, value)++`] +* {xref-IERC20-Approval-address-address-uint256-}[`++Approval(owner, spender, value)++`] + +-- + +[.contract-index] +.Errors +-- +* {xref-ERC4626-ERC4626ExceededMaxDeposit-address-uint256-uint256-}[`++ERC4626ExceededMaxDeposit(receiver, assets, max)++`] +* {xref-ERC4626-ERC4626ExceededMaxMint-address-uint256-uint256-}[`++ERC4626ExceededMaxMint(receiver, shares, max)++`] +* {xref-ERC4626-ERC4626ExceededMaxWithdraw-address-uint256-uint256-}[`++ERC4626ExceededMaxWithdraw(owner, assets, max)++`] +* {xref-ERC4626-ERC4626ExceededMaxRedeem-address-uint256-uint256-}[`++ERC4626ExceededMaxRedeem(owner, shares, max)++`] + +[.contract-subindex-inherited] +.IERC4626 + +[.contract-subindex-inherited] +.ERC20 + +[.contract-subindex-inherited] +.IERC20Errors +* {xref-IERC20Errors-ERC20InsufficientBalance-address-uint256-uint256-}[`++ERC20InsufficientBalance(sender, balance, needed)++`] +* {xref-IERC20Errors-ERC20InvalidSender-address-}[`++ERC20InvalidSender(sender)++`] +* {xref-IERC20Errors-ERC20InvalidReceiver-address-}[`++ERC20InvalidReceiver(receiver)++`] +* {xref-IERC20Errors-ERC20InsufficientAllowance-address-uint256-uint256-}[`++ERC20InsufficientAllowance(spender, allowance, needed)++`] +* {xref-IERC20Errors-ERC20InvalidApprover-address-}[`++ERC20InvalidApprover(approver)++`] +* {xref-IERC20Errors-ERC20InvalidSpender-address-}[`++ERC20InvalidSpender(spender)++`] + +[.contract-subindex-inherited] +.IERC20Metadata + +[.contract-subindex-inherited] +.IERC20 + +-- + +[.contract-item] +[[ERC4626-constructor-contract-IERC20-]] +==== `[.contract-item-name]#++constructor++#++(contract IERC20 asset_)++` [.item-kind]#internal# + +Set the underlying asset contract. This must be an ERC20-compatible contract (ERC20 or ERC777). + +[.contract-item] +[[ERC4626-decimals--]] +==== `[.contract-item-name]#++decimals++#++() → uint8++` [.item-kind]#public# + +Decimals are computed by adding the decimal offset on top of the underlying asset's decimals. This +"original" value is cached during construction of the vault contract. If this read operation fails (e.g., the +asset has not been created yet), a default of 18 is used to represent the underlying asset's decimals. + +See {IERC20Metadata-decimals}. + +[.contract-item] +[[ERC4626-asset--]] +==== `[.contract-item-name]#++asset++#++() → address++` [.item-kind]#public# + +See {IERC4626-asset}. + +[.contract-item] +[[ERC4626-totalAssets--]] +==== `[.contract-item-name]#++totalAssets++#++() → uint256++` [.item-kind]#public# + +See {IERC4626-totalAssets}. + +[.contract-item] +[[ERC4626-convertToShares-uint256-]] +==== `[.contract-item-name]#++convertToShares++#++(uint256 assets) → uint256++` [.item-kind]#public# + +See {IERC4626-convertToShares}. + +[.contract-item] +[[ERC4626-convertToAssets-uint256-]] +==== `[.contract-item-name]#++convertToAssets++#++(uint256 shares) → uint256++` [.item-kind]#public# + +See {IERC4626-convertToAssets}. + +[.contract-item] +[[ERC4626-maxDeposit-address-]] +==== `[.contract-item-name]#++maxDeposit++#++(address) → uint256++` [.item-kind]#public# + +See {IERC4626-maxDeposit}. + +[.contract-item] +[[ERC4626-maxMint-address-]] +==== `[.contract-item-name]#++maxMint++#++(address) → uint256++` [.item-kind]#public# + +See {IERC4626-maxMint}. + +[.contract-item] +[[ERC4626-maxWithdraw-address-]] +==== `[.contract-item-name]#++maxWithdraw++#++(address owner) → uint256++` [.item-kind]#public# + +See {IERC4626-maxWithdraw}. + +[.contract-item] +[[ERC4626-maxRedeem-address-]] +==== `[.contract-item-name]#++maxRedeem++#++(address owner) → uint256++` [.item-kind]#public# + +See {IERC4626-maxRedeem}. + +[.contract-item] +[[ERC4626-previewDeposit-uint256-]] +==== `[.contract-item-name]#++previewDeposit++#++(uint256 assets) → uint256++` [.item-kind]#public# + +See {IERC4626-previewDeposit}. + +[.contract-item] +[[ERC4626-previewMint-uint256-]] +==== `[.contract-item-name]#++previewMint++#++(uint256 shares) → uint256++` [.item-kind]#public# + +See {IERC4626-previewMint}. + +[.contract-item] +[[ERC4626-previewWithdraw-uint256-]] +==== `[.contract-item-name]#++previewWithdraw++#++(uint256 assets) → uint256++` [.item-kind]#public# + +See {IERC4626-previewWithdraw}. + +[.contract-item] +[[ERC4626-previewRedeem-uint256-]] +==== `[.contract-item-name]#++previewRedeem++#++(uint256 shares) → uint256++` [.item-kind]#public# + +See {IERC4626-previewRedeem}. + +[.contract-item] +[[ERC4626-deposit-uint256-address-]] +==== `[.contract-item-name]#++deposit++#++(uint256 assets, address receiver) → uint256++` [.item-kind]#public# + +See {IERC4626-deposit}. + +[.contract-item] +[[ERC4626-mint-uint256-address-]] +==== `[.contract-item-name]#++mint++#++(uint256 shares, address receiver) → uint256++` [.item-kind]#public# + +See {IERC4626-mint}. + +As opposed to {deposit}, minting is allowed even if the vault is in a state where the price of a share is zero. +In this case, the shares will be minted without requiring any assets to be deposited. + +[.contract-item] +[[ERC4626-withdraw-uint256-address-address-]] +==== `[.contract-item-name]#++withdraw++#++(uint256 assets, address receiver, address owner) → uint256++` [.item-kind]#public# + +See {IERC4626-withdraw}. + +[.contract-item] +[[ERC4626-redeem-uint256-address-address-]] +==== `[.contract-item-name]#++redeem++#++(uint256 shares, address receiver, address owner) → uint256++` [.item-kind]#public# + +See {IERC4626-redeem}. + +[.contract-item] +[[ERC4626-_convertToShares-uint256-enum-Math-Rounding-]] +==== `[.contract-item-name]#++_convertToShares++#++(uint256 assets, enum Math.Rounding rounding) → uint256++` [.item-kind]#internal# + +Internal conversion function (from assets to shares) with support for rounding direction. + +[.contract-item] +[[ERC4626-_convertToAssets-uint256-enum-Math-Rounding-]] +==== `[.contract-item-name]#++_convertToAssets++#++(uint256 shares, enum Math.Rounding rounding) → uint256++` [.item-kind]#internal# + +Internal conversion function (from shares to assets) with support for rounding direction. + +[.contract-item] +[[ERC4626-_deposit-address-address-uint256-uint256-]] +==== `[.contract-item-name]#++_deposit++#++(address caller, address receiver, uint256 assets, uint256 shares)++` [.item-kind]#internal# + +Deposit/mint common workflow. + +[.contract-item] +[[ERC4626-_withdraw-address-address-address-uint256-uint256-]] +==== `[.contract-item-name]#++_withdraw++#++(address caller, address receiver, address owner, uint256 assets, uint256 shares)++` [.item-kind]#internal# + +Withdraw/redeem common workflow. + +[.contract-item] +[[ERC4626-_decimalsOffset--]] +==== `[.contract-item-name]#++_decimalsOffset++#++() → uint8++` [.item-kind]#internal# + +[.contract-item] +[[ERC4626-ERC4626ExceededMaxDeposit-address-uint256-uint256-]] +==== `[.contract-item-name]#++ERC4626ExceededMaxDeposit++#++(address receiver, uint256 assets, uint256 max)++` [.item-kind]#error# + +Attempted to deposit more assets than the max amount for `receiver`. + +[.contract-item] +[[ERC4626-ERC4626ExceededMaxMint-address-uint256-uint256-]] +==== `[.contract-item-name]#++ERC4626ExceededMaxMint++#++(address receiver, uint256 shares, uint256 max)++` [.item-kind]#error# + +Attempted to mint more shares than the max amount for `receiver`. + +[.contract-item] +[[ERC4626-ERC4626ExceededMaxWithdraw-address-uint256-uint256-]] +==== `[.contract-item-name]#++ERC4626ExceededMaxWithdraw++#++(address owner, uint256 assets, uint256 max)++` [.item-kind]#error# + +Attempted to withdraw more assets than the max amount for `receiver`. + +[.contract-item] +[[ERC4626-ERC4626ExceededMaxRedeem-address-uint256-uint256-]] +==== `[.contract-item-name]#++ERC4626ExceededMaxRedeem++#++(address owner, uint256 shares, uint256 max)++` [.item-kind]#error# + +Attempted to redeem more shares than the max amount for `receiver`. + +== Utilities + +:SafeERC20FailedOperation: pass:normal[xref:#SafeERC20-SafeERC20FailedOperation-address-[`++SafeERC20FailedOperation++`]] +:SafeERC20FailedDecreaseAllowance: pass:normal[xref:#SafeERC20-SafeERC20FailedDecreaseAllowance-address-uint256-uint256-[`++SafeERC20FailedDecreaseAllowance++`]] +:safeTransfer: pass:normal[xref:#SafeERC20-safeTransfer-contract-IERC20-address-uint256-[`++safeTransfer++`]] +:safeTransferFrom: pass:normal[xref:#SafeERC20-safeTransferFrom-contract-IERC20-address-address-uint256-[`++safeTransferFrom++`]] +:safeIncreaseAllowance: pass:normal[xref:#SafeERC20-safeIncreaseAllowance-contract-IERC20-address-uint256-[`++safeIncreaseAllowance++`]] +:safeDecreaseAllowance: pass:normal[xref:#SafeERC20-safeDecreaseAllowance-contract-IERC20-address-uint256-[`++safeDecreaseAllowance++`]] +:forceApprove: pass:normal[xref:#SafeERC20-forceApprove-contract-IERC20-address-uint256-[`++forceApprove++`]] + +[.contract] +[[SafeERC20]] +=== `++SafeERC20++` link:https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v5.0.0-rc.0/contracts/token/ERC20/utils/SafeERC20.sol[{github-icon},role=heading-link] + +[.hljs-theme-light.nopadding] +```solidity +import "@openzeppelin/contracts/token/ERC20/utils/SafeERC20.sol"; +``` + +Wrappers around ERC20 operations that throw on failure (when the token +contract returns false). Tokens that return no value (and instead revert or +throw on failure) are also supported, non-reverting calls are assumed to be +successful. +To use this library you can add a `using SafeERC20 for IERC20;` statement to your contract, +which allows you to call the safe operations as `token.safeTransfer(...)`, etc. + +[.contract-index] +.Functions +-- +* {xref-SafeERC20-safeTransfer-contract-IERC20-address-uint256-}[`++safeTransfer(token, to, value)++`] +* {xref-SafeERC20-safeTransferFrom-contract-IERC20-address-address-uint256-}[`++safeTransferFrom(token, from, to, value)++`] +* {xref-SafeERC20-safeIncreaseAllowance-contract-IERC20-address-uint256-}[`++safeIncreaseAllowance(token, spender, value)++`] +* {xref-SafeERC20-safeDecreaseAllowance-contract-IERC20-address-uint256-}[`++safeDecreaseAllowance(token, spender, requestedDecrease)++`] +* {xref-SafeERC20-forceApprove-contract-IERC20-address-uint256-}[`++forceApprove(token, spender, value)++`] + +-- + +[.contract-index] +.Errors +-- +* {xref-SafeERC20-SafeERC20FailedOperation-address-}[`++SafeERC20FailedOperation(token)++`] +* {xref-SafeERC20-SafeERC20FailedDecreaseAllowance-address-uint256-uint256-}[`++SafeERC20FailedDecreaseAllowance(spender, currentAllowance, requestedDecrease)++`] + +-- + +[.contract-item] +[[SafeERC20-safeTransfer-contract-IERC20-address-uint256-]] +==== `[.contract-item-name]#++safeTransfer++#++(contract IERC20 token, address to, uint256 value)++` [.item-kind]#internal# + +Transfer `value` amount of `token` from the calling contract to `to`. If `token` returns no value, +non-reverting calls are assumed to be successful. + +[.contract-item] +[[SafeERC20-safeTransferFrom-contract-IERC20-address-address-uint256-]] +==== `[.contract-item-name]#++safeTransferFrom++#++(contract IERC20 token, address from, address to, uint256 value)++` [.item-kind]#internal# + +Transfer `value` amount of `token` from `from` to `to`, spending the approval given by `from` to the +calling contract. If `token` returns no value, non-reverting calls are assumed to be successful. + +[.contract-item] +[[SafeERC20-safeIncreaseAllowance-contract-IERC20-address-uint256-]] +==== `[.contract-item-name]#++safeIncreaseAllowance++#++(contract IERC20 token, address spender, uint256 value)++` [.item-kind]#internal# + +Increase the calling contract's allowance toward `spender` by `value`. If `token` returns no value, +non-reverting calls are assumed to be successful. + +[.contract-item] +[[SafeERC20-safeDecreaseAllowance-contract-IERC20-address-uint256-]] +==== `[.contract-item-name]#++safeDecreaseAllowance++#++(contract IERC20 token, address spender, uint256 requestedDecrease)++` [.item-kind]#internal# + +Decrease the calling contract's allowance toward `spender` by `requestedDecrease`. If `token` returns no +value, non-reverting calls are assumed to be successful. + +[.contract-item] +[[SafeERC20-forceApprove-contract-IERC20-address-uint256-]] +==== `[.contract-item-name]#++forceApprove++#++(contract IERC20 token, address spender, uint256 value)++` [.item-kind]#internal# + +Set the calling contract's allowance toward `spender` to `value`. If `token` returns no value, +non-reverting calls are assumed to be successful. Meant to be used with tokens that require the approval +to be set to zero before setting it to a non-zero value, such as USDT. + +[.contract-item] +[[SafeERC20-SafeERC20FailedOperation-address-]] +==== `[.contract-item-name]#++SafeERC20FailedOperation++#++(address token)++` [.item-kind]#error# + +An operation with an ERC20 token failed. + +[.contract-item] +[[SafeERC20-SafeERC20FailedDecreaseAllowance-address-uint256-uint256-]] +==== `[.contract-item-name]#++SafeERC20FailedDecreaseAllowance++#++(address spender, uint256 currentAllowance, uint256 requestedDecrease)++` [.item-kind]#error# + +Indicates a failed `decreaseAllowance` request. + diff --git a/docs/modules/api/pages/token/ERC721.adoc b/docs/modules/api/pages/token/ERC721.adoc new file mode 100644 index 000000000..a270b2b20 --- /dev/null +++ b/docs/modules/api/pages/token/ERC721.adoc @@ -0,0 +1,2991 @@ +:github-icon: pass:[] +:IERC721: pass:normal[xref:token/ERC721.adoc#IERC721[`IERC721`]] +:IERC721Metadata: pass:normal[xref:token/ERC721.adoc#IERC721Metadata[`IERC721Metadata`]] +:IERC721Enumerable: pass:normal[xref:token/ERC721.adoc#IERC721Enumerable[`IERC721Enumerable`]] +:IERC721Receiver: pass:normal[xref:token/ERC721.adoc#IERC721Receiver[`IERC721Receiver`]] +:ERC721: pass:normal[xref:token/ERC721.adoc#ERC721[`ERC721`]] +:ERC721Enumerable: pass:normal[xref:token/ERC721.adoc#ERC721Enumerable[`ERC721Enumerable`]] +:ERC721Holder: pass:normal[xref:token/ERC721.adoc#ERC721Holder[`ERC721Holder`]] +:ERC721Consecutive: pass:normal[xref:token/ERC721.adoc#ERC721Consecutive[`ERC721Consecutive`]] +:ERC721URIStorage: pass:normal[xref:token/ERC721.adoc#ERC721URIStorage[`ERC721URIStorage`]] +:ERC721Votes: pass:normal[xref:token/ERC721.adoc#ERC721Votes[`ERC721Votes`]] +:ERC721Royalty: pass:normal[xref:token/ERC721.adoc#ERC721Royalty[`ERC721Royalty`]] +:ERC721Pausable: pass:normal[xref:token/ERC721.adoc#ERC721Pausable[`ERC721Pausable`]] +:ERC721Burnable: pass:normal[xref:token/ERC721.adoc#ERC721Burnable[`ERC721Burnable`]] +:ERC721Wrapper: pass:normal[xref:token/ERC721.adoc#ERC721Wrapper[`ERC721Wrapper`]] +:ERC721Votes: pass:normal[xref:token/ERC721.adoc#ERC721Votes[`ERC721Votes`]] +:xref-IERC721-balanceOf-address-: xref:token/ERC721.adoc#IERC721-balanceOf-address- +:xref-IERC721-ownerOf-uint256-: xref:token/ERC721.adoc#IERC721-ownerOf-uint256- +:xref-IERC721-safeTransferFrom-address-address-uint256-bytes-: xref:token/ERC721.adoc#IERC721-safeTransferFrom-address-address-uint256-bytes- +:xref-IERC721-safeTransferFrom-address-address-uint256-: xref:token/ERC721.adoc#IERC721-safeTransferFrom-address-address-uint256- +:xref-IERC721-transferFrom-address-address-uint256-: xref:token/ERC721.adoc#IERC721-transferFrom-address-address-uint256- +:xref-IERC721-approve-address-uint256-: xref:token/ERC721.adoc#IERC721-approve-address-uint256- +:xref-IERC721-setApprovalForAll-address-bool-: xref:token/ERC721.adoc#IERC721-setApprovalForAll-address-bool- +:xref-IERC721-getApproved-uint256-: xref:token/ERC721.adoc#IERC721-getApproved-uint256- +:xref-IERC721-isApprovedForAll-address-address-: xref:token/ERC721.adoc#IERC721-isApprovedForAll-address-address- +:xref-IERC165-supportsInterface-bytes4-: xref:utils.adoc#IERC165-supportsInterface-bytes4- +:xref-IERC721-Transfer-address-address-uint256-: xref:token/ERC721.adoc#IERC721-Transfer-address-address-uint256- +:xref-IERC721-Approval-address-address-uint256-: xref:token/ERC721.adoc#IERC721-Approval-address-address-uint256- +:xref-IERC721-ApprovalForAll-address-address-bool-: xref:token/ERC721.adoc#IERC721-ApprovalForAll-address-address-bool- +:IERC721Receiver-onERC721Received: pass:normal[xref:token/ERC721.adoc#IERC721Receiver-onERC721Received-address-address-uint256-bytes-[`IERC721Receiver.onERC721Received`]] +:IERC721Receiver-onERC721Received: pass:normal[xref:token/ERC721.adoc#IERC721Receiver-onERC721Received-address-address-uint256-bytes-[`IERC721Receiver.onERC721Received`]] +:xref-IERC721Metadata-name--: xref:token/ERC721.adoc#IERC721Metadata-name-- +:xref-IERC721Metadata-symbol--: xref:token/ERC721.adoc#IERC721Metadata-symbol-- +:xref-IERC721Metadata-tokenURI-uint256-: xref:token/ERC721.adoc#IERC721Metadata-tokenURI-uint256- +:xref-IERC721-balanceOf-address-: xref:token/ERC721.adoc#IERC721-balanceOf-address- +:xref-IERC721-ownerOf-uint256-: xref:token/ERC721.adoc#IERC721-ownerOf-uint256- +:xref-IERC721-safeTransferFrom-address-address-uint256-bytes-: xref:token/ERC721.adoc#IERC721-safeTransferFrom-address-address-uint256-bytes- +:xref-IERC721-safeTransferFrom-address-address-uint256-: xref:token/ERC721.adoc#IERC721-safeTransferFrom-address-address-uint256- +:xref-IERC721-transferFrom-address-address-uint256-: xref:token/ERC721.adoc#IERC721-transferFrom-address-address-uint256- +:xref-IERC721-approve-address-uint256-: xref:token/ERC721.adoc#IERC721-approve-address-uint256- +:xref-IERC721-setApprovalForAll-address-bool-: xref:token/ERC721.adoc#IERC721-setApprovalForAll-address-bool- +:xref-IERC721-getApproved-uint256-: xref:token/ERC721.adoc#IERC721-getApproved-uint256- +:xref-IERC721-isApprovedForAll-address-address-: xref:token/ERC721.adoc#IERC721-isApprovedForAll-address-address- +:xref-IERC165-supportsInterface-bytes4-: xref:utils.adoc#IERC165-supportsInterface-bytes4- +:xref-IERC721-Transfer-address-address-uint256-: xref:token/ERC721.adoc#IERC721-Transfer-address-address-uint256- +:xref-IERC721-Approval-address-address-uint256-: xref:token/ERC721.adoc#IERC721-Approval-address-address-uint256- +:xref-IERC721-ApprovalForAll-address-address-bool-: xref:token/ERC721.adoc#IERC721-ApprovalForAll-address-address-bool- +:xref-IERC721Enumerable-totalSupply--: xref:token/ERC721.adoc#IERC721Enumerable-totalSupply-- +:xref-IERC721Enumerable-tokenOfOwnerByIndex-address-uint256-: xref:token/ERC721.adoc#IERC721Enumerable-tokenOfOwnerByIndex-address-uint256- +:xref-IERC721Enumerable-tokenByIndex-uint256-: xref:token/ERC721.adoc#IERC721Enumerable-tokenByIndex-uint256- +:xref-IERC721-balanceOf-address-: xref:token/ERC721.adoc#IERC721-balanceOf-address- +:xref-IERC721-ownerOf-uint256-: xref:token/ERC721.adoc#IERC721-ownerOf-uint256- +:xref-IERC721-safeTransferFrom-address-address-uint256-bytes-: xref:token/ERC721.adoc#IERC721-safeTransferFrom-address-address-uint256-bytes- +:xref-IERC721-safeTransferFrom-address-address-uint256-: xref:token/ERC721.adoc#IERC721-safeTransferFrom-address-address-uint256- +:xref-IERC721-transferFrom-address-address-uint256-: xref:token/ERC721.adoc#IERC721-transferFrom-address-address-uint256- +:xref-IERC721-approve-address-uint256-: xref:token/ERC721.adoc#IERC721-approve-address-uint256- +:xref-IERC721-setApprovalForAll-address-bool-: xref:token/ERC721.adoc#IERC721-setApprovalForAll-address-bool- +:xref-IERC721-getApproved-uint256-: xref:token/ERC721.adoc#IERC721-getApproved-uint256- +:xref-IERC721-isApprovedForAll-address-address-: xref:token/ERC721.adoc#IERC721-isApprovedForAll-address-address- +:xref-IERC165-supportsInterface-bytes4-: xref:utils.adoc#IERC165-supportsInterface-bytes4- +:xref-IERC721-Transfer-address-address-uint256-: xref:token/ERC721.adoc#IERC721-Transfer-address-address-uint256- +:xref-IERC721-Approval-address-address-uint256-: xref:token/ERC721.adoc#IERC721-Approval-address-address-uint256- +:xref-IERC721-ApprovalForAll-address-address-bool-: xref:token/ERC721.adoc#IERC721-ApprovalForAll-address-address-bool- +:ERC721Enumerable: pass:normal[xref:token/ERC721.adoc#ERC721Enumerable[`ERC721Enumerable`]] +:xref-ERC721-constructor-string-string-: xref:token/ERC721.adoc#ERC721-constructor-string-string- +:xref-ERC721-supportsInterface-bytes4-: xref:token/ERC721.adoc#ERC721-supportsInterface-bytes4- +:xref-ERC721-balanceOf-address-: xref:token/ERC721.adoc#ERC721-balanceOf-address- +:xref-ERC721-ownerOf-uint256-: xref:token/ERC721.adoc#ERC721-ownerOf-uint256- +:xref-ERC721-name--: xref:token/ERC721.adoc#ERC721-name-- +:xref-ERC721-symbol--: xref:token/ERC721.adoc#ERC721-symbol-- +:xref-ERC721-tokenURI-uint256-: xref:token/ERC721.adoc#ERC721-tokenURI-uint256- +:xref-ERC721-_baseURI--: xref:token/ERC721.adoc#ERC721-_baseURI-- +:xref-ERC721-approve-address-uint256-: xref:token/ERC721.adoc#ERC721-approve-address-uint256- +:xref-ERC721-getApproved-uint256-: xref:token/ERC721.adoc#ERC721-getApproved-uint256- +:xref-ERC721-setApprovalForAll-address-bool-: xref:token/ERC721.adoc#ERC721-setApprovalForAll-address-bool- +:xref-ERC721-isApprovedForAll-address-address-: xref:token/ERC721.adoc#ERC721-isApprovedForAll-address-address- +:xref-ERC721-transferFrom-address-address-uint256-: xref:token/ERC721.adoc#ERC721-transferFrom-address-address-uint256- +:xref-ERC721-safeTransferFrom-address-address-uint256-: xref:token/ERC721.adoc#ERC721-safeTransferFrom-address-address-uint256- +:xref-ERC721-safeTransferFrom-address-address-uint256-bytes-: xref:token/ERC721.adoc#ERC721-safeTransferFrom-address-address-uint256-bytes- +:xref-ERC721-_ownerOf-uint256-: xref:token/ERC721.adoc#ERC721-_ownerOf-uint256- +:xref-ERC721-_getApproved-uint256-: xref:token/ERC721.adoc#ERC721-_getApproved-uint256- +:xref-ERC721-_isAuthorized-address-address-uint256-: xref:token/ERC721.adoc#ERC721-_isAuthorized-address-address-uint256- +:xref-ERC721-_checkAuthorized-address-address-uint256-: xref:token/ERC721.adoc#ERC721-_checkAuthorized-address-address-uint256- +:xref-ERC721-_increaseBalance-address-uint128-: xref:token/ERC721.adoc#ERC721-_increaseBalance-address-uint128- +:xref-ERC721-_update-address-uint256-address-: xref:token/ERC721.adoc#ERC721-_update-address-uint256-address- +:xref-ERC721-_mint-address-uint256-: xref:token/ERC721.adoc#ERC721-_mint-address-uint256- +:xref-ERC721-_safeMint-address-uint256-: xref:token/ERC721.adoc#ERC721-_safeMint-address-uint256- +:xref-ERC721-_safeMint-address-uint256-bytes-: xref:token/ERC721.adoc#ERC721-_safeMint-address-uint256-bytes- +:xref-ERC721-_burn-uint256-: xref:token/ERC721.adoc#ERC721-_burn-uint256- +:xref-ERC721-_transfer-address-address-uint256-: xref:token/ERC721.adoc#ERC721-_transfer-address-address-uint256- +:xref-ERC721-_safeTransfer-address-address-uint256-: xref:token/ERC721.adoc#ERC721-_safeTransfer-address-address-uint256- +:xref-ERC721-_safeTransfer-address-address-uint256-bytes-: xref:token/ERC721.adoc#ERC721-_safeTransfer-address-address-uint256-bytes- +:xref-ERC721-_approve-address-uint256-address-: xref:token/ERC721.adoc#ERC721-_approve-address-uint256-address- +:xref-ERC721-_approve-address-uint256-address-bool-: xref:token/ERC721.adoc#ERC721-_approve-address-uint256-address-bool- +:xref-ERC721-_setApprovalForAll-address-address-bool-: xref:token/ERC721.adoc#ERC721-_setApprovalForAll-address-address-bool- +:xref-ERC721-_requireOwned-uint256-: xref:token/ERC721.adoc#ERC721-_requireOwned-uint256- +:xref-IERC721-Transfer-address-address-uint256-: xref:token/ERC721.adoc#IERC721-Transfer-address-address-uint256- +:xref-IERC721-Approval-address-address-uint256-: xref:token/ERC721.adoc#IERC721-Approval-address-address-uint256- +:xref-IERC721-ApprovalForAll-address-address-bool-: xref:token/ERC721.adoc#IERC721-ApprovalForAll-address-address-bool- +:xref-IERC721Errors-ERC721InvalidOwner-address-: xref:interfaces.adoc#IERC721Errors-ERC721InvalidOwner-address- +:xref-IERC721Errors-ERC721NonexistentToken-uint256-: xref:interfaces.adoc#IERC721Errors-ERC721NonexistentToken-uint256- +:xref-IERC721Errors-ERC721IncorrectOwner-address-uint256-address-: xref:interfaces.adoc#IERC721Errors-ERC721IncorrectOwner-address-uint256-address- +:xref-IERC721Errors-ERC721InvalidSender-address-: xref:interfaces.adoc#IERC721Errors-ERC721InvalidSender-address- +:xref-IERC721Errors-ERC721InvalidReceiver-address-: xref:interfaces.adoc#IERC721Errors-ERC721InvalidReceiver-address- +:xref-IERC721Errors-ERC721InsufficientApproval-address-uint256-: xref:interfaces.adoc#IERC721Errors-ERC721InsufficientApproval-address-uint256- +:xref-IERC721Errors-ERC721InvalidApprover-address-: xref:interfaces.adoc#IERC721Errors-ERC721InvalidApprover-address- +:xref-IERC721Errors-ERC721InvalidOperator-address-: xref:interfaces.adoc#IERC721Errors-ERC721InvalidOperator-address- +:IERC165-supportsInterface: pass:normal[xref:utils.adoc#IERC165-supportsInterface-bytes4-[`IERC165.supportsInterface`]] +:IERC721-balanceOf: pass:normal[xref:token/ERC721.adoc#IERC721-balanceOf-address-[`IERC721.balanceOf`]] +:IERC721-ownerOf: pass:normal[xref:token/ERC721.adoc#IERC721-ownerOf-uint256-[`IERC721.ownerOf`]] +:IERC721Metadata-name: pass:normal[xref:token/ERC721.adoc#IERC721Metadata-name--[`IERC721Metadata.name`]] +:IERC721Metadata-symbol: pass:normal[xref:token/ERC721.adoc#IERC721Metadata-symbol--[`IERC721Metadata.symbol`]] +:IERC721Metadata-tokenURI: pass:normal[xref:token/ERC721.adoc#IERC721Metadata-tokenURI-uint256-[`IERC721Metadata.tokenURI`]] +:IERC721-approve: pass:normal[xref:token/ERC721.adoc#IERC721-approve-address-uint256-[`IERC721.approve`]] +:IERC721-getApproved: pass:normal[xref:token/ERC721.adoc#IERC721-getApproved-uint256-[`IERC721.getApproved`]] +:IERC721-setApprovalForAll: pass:normal[xref:token/ERC721.adoc#IERC721-setApprovalForAll-address-bool-[`IERC721.setApprovalForAll`]] +:IERC721-isApprovedForAll: pass:normal[xref:token/ERC721.adoc#IERC721-isApprovedForAll-address-address-[`IERC721.isApprovedForAll`]] +:IERC721-transferFrom: pass:normal[xref:token/ERC721.adoc#IERC721-transferFrom-address-address-uint256-[`IERC721.transferFrom`]] +:IERC721-safeTransferFrom: pass:normal[xref:token/ERC721.adoc#IERC721-safeTransferFrom-address-address-uint256-[`IERC721.safeTransferFrom`]] +:IERC721-safeTransferFrom: pass:normal[xref:token/ERC721.adoc#IERC721-safeTransferFrom-address-address-uint256-[`IERC721.safeTransferFrom`]] +:IERC721Receiver-onERC721Received: pass:normal[xref:token/ERC721.adoc#IERC721Receiver-onERC721Received-address-address-uint256-bytes-[`IERC721Receiver.onERC721Received`]] +:xref-ERC721-_safeMint-address-uint256-: xref:token/ERC721.adoc#ERC721-_safeMint-address-uint256- +:IERC721Receiver-onERC721Received: pass:normal[xref:token/ERC721.adoc#IERC721Receiver-onERC721Received-address-address-uint256-bytes-[`IERC721Receiver.onERC721Received`]] +:IERC721Receiver-onERC721Received: pass:normal[xref:token/ERC721.adoc#IERC721Receiver-onERC721Received-address-address-uint256-bytes-[`IERC721Receiver.onERC721Received`]] +:IERC721Receiver-onERC721Received: pass:normal[xref:token/ERC721.adoc#IERC721Receiver-onERC721Received-address-address-uint256-bytes-[`IERC721Receiver.onERC721Received`]] +:xref-ERC721-_safeTransfer-address-address-uint256-: xref:token/ERC721.adoc#ERC721-_safeTransfer-address-address-uint256- +:IERC721Receiver-onERC721Received: pass:normal[xref:token/ERC721.adoc#IERC721Receiver-onERC721Received-address-address-uint256-bytes-[`IERC721Receiver.onERC721Received`]] +:ERC721: pass:normal[xref:token/ERC721.adoc#ERC721[`ERC721`]] +:xref-ERC721Enumerable-supportsInterface-bytes4-: xref:token/ERC721.adoc#ERC721Enumerable-supportsInterface-bytes4- +:xref-ERC721Enumerable-tokenOfOwnerByIndex-address-uint256-: xref:token/ERC721.adoc#ERC721Enumerable-tokenOfOwnerByIndex-address-uint256- +:xref-ERC721Enumerable-totalSupply--: xref:token/ERC721.adoc#ERC721Enumerable-totalSupply-- +:xref-ERC721Enumerable-tokenByIndex-uint256-: xref:token/ERC721.adoc#ERC721Enumerable-tokenByIndex-uint256- +:xref-ERC721Enumerable-_update-address-uint256-address-: xref:token/ERC721.adoc#ERC721Enumerable-_update-address-uint256-address- +:xref-ERC721Enumerable-_increaseBalance-address-uint128-: xref:token/ERC721.adoc#ERC721Enumerable-_increaseBalance-address-uint128- +:xref-ERC721-balanceOf-address-: xref:token/ERC721.adoc#ERC721-balanceOf-address- +:xref-ERC721-ownerOf-uint256-: xref:token/ERC721.adoc#ERC721-ownerOf-uint256- +:xref-ERC721-name--: xref:token/ERC721.adoc#ERC721-name-- +:xref-ERC721-symbol--: xref:token/ERC721.adoc#ERC721-symbol-- +:xref-ERC721-tokenURI-uint256-: xref:token/ERC721.adoc#ERC721-tokenURI-uint256- +:xref-ERC721-_baseURI--: xref:token/ERC721.adoc#ERC721-_baseURI-- +:xref-ERC721-approve-address-uint256-: xref:token/ERC721.adoc#ERC721-approve-address-uint256- +:xref-ERC721-getApproved-uint256-: xref:token/ERC721.adoc#ERC721-getApproved-uint256- +:xref-ERC721-setApprovalForAll-address-bool-: xref:token/ERC721.adoc#ERC721-setApprovalForAll-address-bool- +:xref-ERC721-isApprovedForAll-address-address-: xref:token/ERC721.adoc#ERC721-isApprovedForAll-address-address- +:xref-ERC721-transferFrom-address-address-uint256-: xref:token/ERC721.adoc#ERC721-transferFrom-address-address-uint256- +:xref-ERC721-safeTransferFrom-address-address-uint256-: xref:token/ERC721.adoc#ERC721-safeTransferFrom-address-address-uint256- +:xref-ERC721-safeTransferFrom-address-address-uint256-bytes-: xref:token/ERC721.adoc#ERC721-safeTransferFrom-address-address-uint256-bytes- +:xref-ERC721-_ownerOf-uint256-: xref:token/ERC721.adoc#ERC721-_ownerOf-uint256- +:xref-ERC721-_getApproved-uint256-: xref:token/ERC721.adoc#ERC721-_getApproved-uint256- +:xref-ERC721-_isAuthorized-address-address-uint256-: xref:token/ERC721.adoc#ERC721-_isAuthorized-address-address-uint256- +:xref-ERC721-_checkAuthorized-address-address-uint256-: xref:token/ERC721.adoc#ERC721-_checkAuthorized-address-address-uint256- +:xref-ERC721-_mint-address-uint256-: xref:token/ERC721.adoc#ERC721-_mint-address-uint256- +:xref-ERC721-_safeMint-address-uint256-: xref:token/ERC721.adoc#ERC721-_safeMint-address-uint256- +:xref-ERC721-_safeMint-address-uint256-bytes-: xref:token/ERC721.adoc#ERC721-_safeMint-address-uint256-bytes- +:xref-ERC721-_burn-uint256-: xref:token/ERC721.adoc#ERC721-_burn-uint256- +:xref-ERC721-_transfer-address-address-uint256-: xref:token/ERC721.adoc#ERC721-_transfer-address-address-uint256- +:xref-ERC721-_safeTransfer-address-address-uint256-: xref:token/ERC721.adoc#ERC721-_safeTransfer-address-address-uint256- +:xref-ERC721-_safeTransfer-address-address-uint256-bytes-: xref:token/ERC721.adoc#ERC721-_safeTransfer-address-address-uint256-bytes- +:xref-ERC721-_approve-address-uint256-address-: xref:token/ERC721.adoc#ERC721-_approve-address-uint256-address- +:xref-ERC721-_approve-address-uint256-address-bool-: xref:token/ERC721.adoc#ERC721-_approve-address-uint256-address-bool- +:xref-ERC721-_setApprovalForAll-address-address-bool-: xref:token/ERC721.adoc#ERC721-_setApprovalForAll-address-address-bool- +:xref-ERC721-_requireOwned-uint256-: xref:token/ERC721.adoc#ERC721-_requireOwned-uint256- +:xref-IERC721-Transfer-address-address-uint256-: xref:token/ERC721.adoc#IERC721-Transfer-address-address-uint256- +:xref-IERC721-Approval-address-address-uint256-: xref:token/ERC721.adoc#IERC721-Approval-address-address-uint256- +:xref-IERC721-ApprovalForAll-address-address-bool-: xref:token/ERC721.adoc#IERC721-ApprovalForAll-address-address-bool- +:xref-ERC721Enumerable-ERC721OutOfBoundsIndex-address-uint256-: xref:token/ERC721.adoc#ERC721Enumerable-ERC721OutOfBoundsIndex-address-uint256- +:xref-ERC721Enumerable-ERC721EnumerableForbiddenBatchMint--: xref:token/ERC721.adoc#ERC721Enumerable-ERC721EnumerableForbiddenBatchMint-- +:xref-IERC721Errors-ERC721InvalidOwner-address-: xref:interfaces.adoc#IERC721Errors-ERC721InvalidOwner-address- +:xref-IERC721Errors-ERC721NonexistentToken-uint256-: xref:interfaces.adoc#IERC721Errors-ERC721NonexistentToken-uint256- +:xref-IERC721Errors-ERC721IncorrectOwner-address-uint256-address-: xref:interfaces.adoc#IERC721Errors-ERC721IncorrectOwner-address-uint256-address- +:xref-IERC721Errors-ERC721InvalidSender-address-: xref:interfaces.adoc#IERC721Errors-ERC721InvalidSender-address- +:xref-IERC721Errors-ERC721InvalidReceiver-address-: xref:interfaces.adoc#IERC721Errors-ERC721InvalidReceiver-address- +:xref-IERC721Errors-ERC721InsufficientApproval-address-uint256-: xref:interfaces.adoc#IERC721Errors-ERC721InsufficientApproval-address-uint256- +:xref-IERC721Errors-ERC721InvalidApprover-address-: xref:interfaces.adoc#IERC721Errors-ERC721InvalidApprover-address- +:xref-IERC721Errors-ERC721InvalidOperator-address-: xref:interfaces.adoc#IERC721Errors-ERC721InvalidOperator-address- +:IERC165-supportsInterface: pass:normal[xref:utils.adoc#IERC165-supportsInterface-bytes4-[`IERC165.supportsInterface`]] +:IERC721Enumerable-tokenOfOwnerByIndex: pass:normal[xref:token/ERC721.adoc#IERC721Enumerable-tokenOfOwnerByIndex-address-uint256-[`IERC721Enumerable.tokenOfOwnerByIndex`]] +:IERC721Enumerable-totalSupply: pass:normal[xref:token/ERC721.adoc#IERC721Enumerable-totalSupply--[`IERC721Enumerable.totalSupply`]] +:IERC721Enumerable-tokenByIndex: pass:normal[xref:token/ERC721.adoc#IERC721Enumerable-tokenByIndex-uint256-[`IERC721Enumerable.tokenByIndex`]] +:ERC721-_update: pass:normal[xref:token/ERC721.adoc#ERC721-_update-address-uint256-address-[`ERC721._update`]] +:xref-IERC721Receiver-onERC721Received-address-address-uint256-bytes-: xref:token/ERC721.adoc#IERC721Receiver-onERC721Received-address-address-uint256-bytes- +:IERC721: pass:normal[xref:token/ERC721.adoc#IERC721[`IERC721`]] +:IERC721-safeTransferFrom: pass:normal[xref:token/ERC721.adoc#IERC721-safeTransferFrom-address-address-uint256-[`IERC721.safeTransferFrom`]] +:Pausable-_pause: pass:normal[xref:utils.adoc#Pausable-_pause--[`Pausable._pause`]] +:Pausable-_unpause: pass:normal[xref:utils.adoc#Pausable-_unpause--[`Pausable._unpause`]] +:AccessControl: pass:normal[xref:access.adoc#AccessControl[`AccessControl`]] +:Ownable: pass:normal[xref:access.adoc#Ownable[`Ownable`]] +:xref-ERC721Pausable-_update-address-uint256-address-: xref:token/ERC721.adoc#ERC721Pausable-_update-address-uint256-address- +:xref-Pausable-paused--: xref:utils.adoc#Pausable-paused-- +:xref-Pausable-_requireNotPaused--: xref:utils.adoc#Pausable-_requireNotPaused-- +:xref-Pausable-_requirePaused--: xref:utils.adoc#Pausable-_requirePaused-- +:xref-Pausable-_pause--: xref:utils.adoc#Pausable-_pause-- +:xref-Pausable-_unpause--: xref:utils.adoc#Pausable-_unpause-- +:xref-ERC721-supportsInterface-bytes4-: xref:token/ERC721.adoc#ERC721-supportsInterface-bytes4- +:xref-ERC721-balanceOf-address-: xref:token/ERC721.adoc#ERC721-balanceOf-address- +:xref-ERC721-ownerOf-uint256-: xref:token/ERC721.adoc#ERC721-ownerOf-uint256- +:xref-ERC721-name--: xref:token/ERC721.adoc#ERC721-name-- +:xref-ERC721-symbol--: xref:token/ERC721.adoc#ERC721-symbol-- +:xref-ERC721-tokenURI-uint256-: xref:token/ERC721.adoc#ERC721-tokenURI-uint256- +:xref-ERC721-_baseURI--: xref:token/ERC721.adoc#ERC721-_baseURI-- +:xref-ERC721-approve-address-uint256-: xref:token/ERC721.adoc#ERC721-approve-address-uint256- +:xref-ERC721-getApproved-uint256-: xref:token/ERC721.adoc#ERC721-getApproved-uint256- +:xref-ERC721-setApprovalForAll-address-bool-: xref:token/ERC721.adoc#ERC721-setApprovalForAll-address-bool- +:xref-ERC721-isApprovedForAll-address-address-: xref:token/ERC721.adoc#ERC721-isApprovedForAll-address-address- +:xref-ERC721-transferFrom-address-address-uint256-: xref:token/ERC721.adoc#ERC721-transferFrom-address-address-uint256- +:xref-ERC721-safeTransferFrom-address-address-uint256-: xref:token/ERC721.adoc#ERC721-safeTransferFrom-address-address-uint256- +:xref-ERC721-safeTransferFrom-address-address-uint256-bytes-: xref:token/ERC721.adoc#ERC721-safeTransferFrom-address-address-uint256-bytes- +:xref-ERC721-_ownerOf-uint256-: xref:token/ERC721.adoc#ERC721-_ownerOf-uint256- +:xref-ERC721-_getApproved-uint256-: xref:token/ERC721.adoc#ERC721-_getApproved-uint256- +:xref-ERC721-_isAuthorized-address-address-uint256-: xref:token/ERC721.adoc#ERC721-_isAuthorized-address-address-uint256- +:xref-ERC721-_checkAuthorized-address-address-uint256-: xref:token/ERC721.adoc#ERC721-_checkAuthorized-address-address-uint256- +:xref-ERC721-_increaseBalance-address-uint128-: xref:token/ERC721.adoc#ERC721-_increaseBalance-address-uint128- +:xref-ERC721-_mint-address-uint256-: xref:token/ERC721.adoc#ERC721-_mint-address-uint256- +:xref-ERC721-_safeMint-address-uint256-: xref:token/ERC721.adoc#ERC721-_safeMint-address-uint256- +:xref-ERC721-_safeMint-address-uint256-bytes-: xref:token/ERC721.adoc#ERC721-_safeMint-address-uint256-bytes- +:xref-ERC721-_burn-uint256-: xref:token/ERC721.adoc#ERC721-_burn-uint256- +:xref-ERC721-_transfer-address-address-uint256-: xref:token/ERC721.adoc#ERC721-_transfer-address-address-uint256- +:xref-ERC721-_safeTransfer-address-address-uint256-: xref:token/ERC721.adoc#ERC721-_safeTransfer-address-address-uint256- +:xref-ERC721-_safeTransfer-address-address-uint256-bytes-: xref:token/ERC721.adoc#ERC721-_safeTransfer-address-address-uint256-bytes- +:xref-ERC721-_approve-address-uint256-address-: xref:token/ERC721.adoc#ERC721-_approve-address-uint256-address- +:xref-ERC721-_approve-address-uint256-address-bool-: xref:token/ERC721.adoc#ERC721-_approve-address-uint256-address-bool- +:xref-ERC721-_setApprovalForAll-address-address-bool-: xref:token/ERC721.adoc#ERC721-_setApprovalForAll-address-address-bool- +:xref-ERC721-_requireOwned-uint256-: xref:token/ERC721.adoc#ERC721-_requireOwned-uint256- +:xref-Pausable-Paused-address-: xref:utils.adoc#Pausable-Paused-address- +:xref-Pausable-Unpaused-address-: xref:utils.adoc#Pausable-Unpaused-address- +:xref-IERC721-Transfer-address-address-uint256-: xref:token/ERC721.adoc#IERC721-Transfer-address-address-uint256- +:xref-IERC721-Approval-address-address-uint256-: xref:token/ERC721.adoc#IERC721-Approval-address-address-uint256- +:xref-IERC721-ApprovalForAll-address-address-bool-: xref:token/ERC721.adoc#IERC721-ApprovalForAll-address-address-bool- +:xref-Pausable-EnforcedPause--: xref:utils.adoc#Pausable-EnforcedPause-- +:xref-Pausable-ExpectedPause--: xref:utils.adoc#Pausable-ExpectedPause-- +:xref-IERC721Errors-ERC721InvalidOwner-address-: xref:interfaces.adoc#IERC721Errors-ERC721InvalidOwner-address- +:xref-IERC721Errors-ERC721NonexistentToken-uint256-: xref:interfaces.adoc#IERC721Errors-ERC721NonexistentToken-uint256- +:xref-IERC721Errors-ERC721IncorrectOwner-address-uint256-address-: xref:interfaces.adoc#IERC721Errors-ERC721IncorrectOwner-address-uint256-address- +:xref-IERC721Errors-ERC721InvalidSender-address-: xref:interfaces.adoc#IERC721Errors-ERC721InvalidSender-address- +:xref-IERC721Errors-ERC721InvalidReceiver-address-: xref:interfaces.adoc#IERC721Errors-ERC721InvalidReceiver-address- +:xref-IERC721Errors-ERC721InsufficientApproval-address-uint256-: xref:interfaces.adoc#IERC721Errors-ERC721InsufficientApproval-address-uint256- +:xref-IERC721Errors-ERC721InvalidApprover-address-: xref:interfaces.adoc#IERC721Errors-ERC721InvalidApprover-address- +:xref-IERC721Errors-ERC721InvalidOperator-address-: xref:interfaces.adoc#IERC721Errors-ERC721InvalidOperator-address- +:ERC721-_update: pass:normal[xref:token/ERC721.adoc#ERC721-_update-address-uint256-address-[`ERC721._update`]] +:xref-ERC721Burnable-burn-uint256-: xref:token/ERC721.adoc#ERC721Burnable-burn-uint256- +:xref-ERC721-supportsInterface-bytes4-: xref:token/ERC721.adoc#ERC721-supportsInterface-bytes4- +:xref-ERC721-balanceOf-address-: xref:token/ERC721.adoc#ERC721-balanceOf-address- +:xref-ERC721-ownerOf-uint256-: xref:token/ERC721.adoc#ERC721-ownerOf-uint256- +:xref-ERC721-name--: xref:token/ERC721.adoc#ERC721-name-- +:xref-ERC721-symbol--: xref:token/ERC721.adoc#ERC721-symbol-- +:xref-ERC721-tokenURI-uint256-: xref:token/ERC721.adoc#ERC721-tokenURI-uint256- +:xref-ERC721-_baseURI--: xref:token/ERC721.adoc#ERC721-_baseURI-- +:xref-ERC721-approve-address-uint256-: xref:token/ERC721.adoc#ERC721-approve-address-uint256- +:xref-ERC721-getApproved-uint256-: xref:token/ERC721.adoc#ERC721-getApproved-uint256- +:xref-ERC721-setApprovalForAll-address-bool-: xref:token/ERC721.adoc#ERC721-setApprovalForAll-address-bool- +:xref-ERC721-isApprovedForAll-address-address-: xref:token/ERC721.adoc#ERC721-isApprovedForAll-address-address- +:xref-ERC721-transferFrom-address-address-uint256-: xref:token/ERC721.adoc#ERC721-transferFrom-address-address-uint256- +:xref-ERC721-safeTransferFrom-address-address-uint256-: xref:token/ERC721.adoc#ERC721-safeTransferFrom-address-address-uint256- +:xref-ERC721-safeTransferFrom-address-address-uint256-bytes-: xref:token/ERC721.adoc#ERC721-safeTransferFrom-address-address-uint256-bytes- +:xref-ERC721-_ownerOf-uint256-: xref:token/ERC721.adoc#ERC721-_ownerOf-uint256- +:xref-ERC721-_getApproved-uint256-: xref:token/ERC721.adoc#ERC721-_getApproved-uint256- +:xref-ERC721-_isAuthorized-address-address-uint256-: xref:token/ERC721.adoc#ERC721-_isAuthorized-address-address-uint256- +:xref-ERC721-_checkAuthorized-address-address-uint256-: xref:token/ERC721.adoc#ERC721-_checkAuthorized-address-address-uint256- +:xref-ERC721-_increaseBalance-address-uint128-: xref:token/ERC721.adoc#ERC721-_increaseBalance-address-uint128- +:xref-ERC721-_update-address-uint256-address-: xref:token/ERC721.adoc#ERC721-_update-address-uint256-address- +:xref-ERC721-_mint-address-uint256-: xref:token/ERC721.adoc#ERC721-_mint-address-uint256- +:xref-ERC721-_safeMint-address-uint256-: xref:token/ERC721.adoc#ERC721-_safeMint-address-uint256- +:xref-ERC721-_safeMint-address-uint256-bytes-: xref:token/ERC721.adoc#ERC721-_safeMint-address-uint256-bytes- +:xref-ERC721-_burn-uint256-: xref:token/ERC721.adoc#ERC721-_burn-uint256- +:xref-ERC721-_transfer-address-address-uint256-: xref:token/ERC721.adoc#ERC721-_transfer-address-address-uint256- +:xref-ERC721-_safeTransfer-address-address-uint256-: xref:token/ERC721.adoc#ERC721-_safeTransfer-address-address-uint256- +:xref-ERC721-_safeTransfer-address-address-uint256-bytes-: xref:token/ERC721.adoc#ERC721-_safeTransfer-address-address-uint256-bytes- +:xref-ERC721-_approve-address-uint256-address-: xref:token/ERC721.adoc#ERC721-_approve-address-uint256-address- +:xref-ERC721-_approve-address-uint256-address-bool-: xref:token/ERC721.adoc#ERC721-_approve-address-uint256-address-bool- +:xref-ERC721-_setApprovalForAll-address-address-bool-: xref:token/ERC721.adoc#ERC721-_setApprovalForAll-address-address-bool- +:xref-ERC721-_requireOwned-uint256-: xref:token/ERC721.adoc#ERC721-_requireOwned-uint256- +:xref-IERC721-Transfer-address-address-uint256-: xref:token/ERC721.adoc#IERC721-Transfer-address-address-uint256- +:xref-IERC721-Approval-address-address-uint256-: xref:token/ERC721.adoc#IERC721-Approval-address-address-uint256- +:xref-IERC721-ApprovalForAll-address-address-bool-: xref:token/ERC721.adoc#IERC721-ApprovalForAll-address-address-bool- +:xref-IERC721Errors-ERC721InvalidOwner-address-: xref:interfaces.adoc#IERC721Errors-ERC721InvalidOwner-address- +:xref-IERC721Errors-ERC721NonexistentToken-uint256-: xref:interfaces.adoc#IERC721Errors-ERC721NonexistentToken-uint256- +:xref-IERC721Errors-ERC721IncorrectOwner-address-uint256-address-: xref:interfaces.adoc#IERC721Errors-ERC721IncorrectOwner-address-uint256-address- +:xref-IERC721Errors-ERC721InvalidSender-address-: xref:interfaces.adoc#IERC721Errors-ERC721InvalidSender-address- +:xref-IERC721Errors-ERC721InvalidReceiver-address-: xref:interfaces.adoc#IERC721Errors-ERC721InvalidReceiver-address- +:xref-IERC721Errors-ERC721InsufficientApproval-address-uint256-: xref:interfaces.adoc#IERC721Errors-ERC721InsufficientApproval-address-uint256- +:xref-IERC721Errors-ERC721InvalidApprover-address-: xref:interfaces.adoc#IERC721Errors-ERC721InvalidApprover-address- +:xref-IERC721Errors-ERC721InvalidOperator-address-: xref:interfaces.adoc#IERC721Errors-ERC721InvalidOperator-address- +:ERC721-_burn: pass:normal[xref:token/ERC721.adoc#ERC721-_burn-uint256-[`ERC721._burn`]] +:xref-ERC721Consecutive-_maxBatchSize--: xref:token/ERC721.adoc#ERC721Consecutive-_maxBatchSize-- +:xref-ERC721Consecutive-_ownerOf-uint256-: xref:token/ERC721.adoc#ERC721Consecutive-_ownerOf-uint256- +:xref-ERC721Consecutive-_mintConsecutive-address-uint96-: xref:token/ERC721.adoc#ERC721Consecutive-_mintConsecutive-address-uint96- +:xref-ERC721Consecutive-_update-address-uint256-address-: xref:token/ERC721.adoc#ERC721Consecutive-_update-address-uint256-address- +:xref-ERC721Consecutive-_firstConsecutiveId--: xref:token/ERC721.adoc#ERC721Consecutive-_firstConsecutiveId-- +:xref-ERC721-supportsInterface-bytes4-: xref:token/ERC721.adoc#ERC721-supportsInterface-bytes4- +:xref-ERC721-balanceOf-address-: xref:token/ERC721.adoc#ERC721-balanceOf-address- +:xref-ERC721-ownerOf-uint256-: xref:token/ERC721.adoc#ERC721-ownerOf-uint256- +:xref-ERC721-name--: xref:token/ERC721.adoc#ERC721-name-- +:xref-ERC721-symbol--: xref:token/ERC721.adoc#ERC721-symbol-- +:xref-ERC721-tokenURI-uint256-: xref:token/ERC721.adoc#ERC721-tokenURI-uint256- +:xref-ERC721-_baseURI--: xref:token/ERC721.adoc#ERC721-_baseURI-- +:xref-ERC721-approve-address-uint256-: xref:token/ERC721.adoc#ERC721-approve-address-uint256- +:xref-ERC721-getApproved-uint256-: xref:token/ERC721.adoc#ERC721-getApproved-uint256- +:xref-ERC721-setApprovalForAll-address-bool-: xref:token/ERC721.adoc#ERC721-setApprovalForAll-address-bool- +:xref-ERC721-isApprovedForAll-address-address-: xref:token/ERC721.adoc#ERC721-isApprovedForAll-address-address- +:xref-ERC721-transferFrom-address-address-uint256-: xref:token/ERC721.adoc#ERC721-transferFrom-address-address-uint256- +:xref-ERC721-safeTransferFrom-address-address-uint256-: xref:token/ERC721.adoc#ERC721-safeTransferFrom-address-address-uint256- +:xref-ERC721-safeTransferFrom-address-address-uint256-bytes-: xref:token/ERC721.adoc#ERC721-safeTransferFrom-address-address-uint256-bytes- +:xref-ERC721-_getApproved-uint256-: xref:token/ERC721.adoc#ERC721-_getApproved-uint256- +:xref-ERC721-_isAuthorized-address-address-uint256-: xref:token/ERC721.adoc#ERC721-_isAuthorized-address-address-uint256- +:xref-ERC721-_checkAuthorized-address-address-uint256-: xref:token/ERC721.adoc#ERC721-_checkAuthorized-address-address-uint256- +:xref-ERC721-_increaseBalance-address-uint128-: xref:token/ERC721.adoc#ERC721-_increaseBalance-address-uint128- +:xref-ERC721-_mint-address-uint256-: xref:token/ERC721.adoc#ERC721-_mint-address-uint256- +:xref-ERC721-_safeMint-address-uint256-: xref:token/ERC721.adoc#ERC721-_safeMint-address-uint256- +:xref-ERC721-_safeMint-address-uint256-bytes-: xref:token/ERC721.adoc#ERC721-_safeMint-address-uint256-bytes- +:xref-ERC721-_burn-uint256-: xref:token/ERC721.adoc#ERC721-_burn-uint256- +:xref-ERC721-_transfer-address-address-uint256-: xref:token/ERC721.adoc#ERC721-_transfer-address-address-uint256- +:xref-ERC721-_safeTransfer-address-address-uint256-: xref:token/ERC721.adoc#ERC721-_safeTransfer-address-address-uint256- +:xref-ERC721-_safeTransfer-address-address-uint256-bytes-: xref:token/ERC721.adoc#ERC721-_safeTransfer-address-address-uint256-bytes- +:xref-ERC721-_approve-address-uint256-address-: xref:token/ERC721.adoc#ERC721-_approve-address-uint256-address- +:xref-ERC721-_approve-address-uint256-address-bool-: xref:token/ERC721.adoc#ERC721-_approve-address-uint256-address-bool- +:xref-ERC721-_setApprovalForAll-address-address-bool-: xref:token/ERC721.adoc#ERC721-_setApprovalForAll-address-address-bool- +:xref-ERC721-_requireOwned-uint256-: xref:token/ERC721.adoc#ERC721-_requireOwned-uint256- +:xref-IERC721-Transfer-address-address-uint256-: xref:token/ERC721.adoc#IERC721-Transfer-address-address-uint256- +:xref-IERC721-Approval-address-address-uint256-: xref:token/ERC721.adoc#IERC721-Approval-address-address-uint256- +:xref-IERC721-ApprovalForAll-address-address-bool-: xref:token/ERC721.adoc#IERC721-ApprovalForAll-address-address-bool- +:xref-IERC2309-ConsecutiveTransfer-uint256-uint256-address-address-: xref:interfaces.adoc#IERC2309-ConsecutiveTransfer-uint256-uint256-address-address- +:xref-ERC721Consecutive-ERC721ForbiddenBatchMint--: xref:token/ERC721.adoc#ERC721Consecutive-ERC721ForbiddenBatchMint-- +:xref-ERC721Consecutive-ERC721ExceededMaxBatchMint-uint256-uint256-: xref:token/ERC721.adoc#ERC721Consecutive-ERC721ExceededMaxBatchMint-uint256-uint256- +:xref-ERC721Consecutive-ERC721ForbiddenMint--: xref:token/ERC721.adoc#ERC721Consecutive-ERC721ForbiddenMint-- +:xref-ERC721Consecutive-ERC721ForbiddenBatchBurn--: xref:token/ERC721.adoc#ERC721Consecutive-ERC721ForbiddenBatchBurn-- +:xref-IERC721Errors-ERC721InvalidOwner-address-: xref:interfaces.adoc#IERC721Errors-ERC721InvalidOwner-address- +:xref-IERC721Errors-ERC721NonexistentToken-uint256-: xref:interfaces.adoc#IERC721Errors-ERC721NonexistentToken-uint256- +:xref-IERC721Errors-ERC721IncorrectOwner-address-uint256-address-: xref:interfaces.adoc#IERC721Errors-ERC721IncorrectOwner-address-uint256-address- +:xref-IERC721Errors-ERC721InvalidSender-address-: xref:interfaces.adoc#IERC721Errors-ERC721InvalidSender-address- +:xref-IERC721Errors-ERC721InvalidReceiver-address-: xref:interfaces.adoc#IERC721Errors-ERC721InvalidReceiver-address- +:xref-IERC721Errors-ERC721InsufficientApproval-address-uint256-: xref:interfaces.adoc#IERC721Errors-ERC721InsufficientApproval-address-uint256- +:xref-IERC721Errors-ERC721InvalidApprover-address-: xref:interfaces.adoc#IERC721Errors-ERC721InvalidApprover-address- +:xref-IERC721Errors-ERC721InvalidOperator-address-: xref:interfaces.adoc#IERC721Errors-ERC721InvalidOperator-address- +:ERC721-_ownerOf: pass:normal[xref:token/ERC721.adoc#ERC721-_ownerOf-uint256-[`ERC721._ownerOf`]] +:IERC2309-ConsecutiveTransfer: pass:normal[xref:interfaces.adoc#IERC2309-ConsecutiveTransfer-uint256-uint256-address-address-[`IERC2309.ConsecutiveTransfer`]] +:ERC721-_update: pass:normal[xref:token/ERC721.adoc#ERC721-_update-address-uint256-address-[`ERC721._update`]] +:ERC721Consecutive: pass:normal[xref:token/ERC721.adoc#ERC721Consecutive[`ERC721Consecutive`]] +:IERC721-Transfer: pass:normal[xref:token/ERC721.adoc#IERC721-Transfer-address-address-uint256-[`IERC721.Transfer`]] +:xref-ERC721URIStorage-supportsInterface-bytes4-: xref:token/ERC721.adoc#ERC721URIStorage-supportsInterface-bytes4- +:xref-ERC721URIStorage-tokenURI-uint256-: xref:token/ERC721.adoc#ERC721URIStorage-tokenURI-uint256- +:xref-ERC721URIStorage-_setTokenURI-uint256-string-: xref:token/ERC721.adoc#ERC721URIStorage-_setTokenURI-uint256-string- +:xref-ERC721-balanceOf-address-: xref:token/ERC721.adoc#ERC721-balanceOf-address- +:xref-ERC721-ownerOf-uint256-: xref:token/ERC721.adoc#ERC721-ownerOf-uint256- +:xref-ERC721-name--: xref:token/ERC721.adoc#ERC721-name-- +:xref-ERC721-symbol--: xref:token/ERC721.adoc#ERC721-symbol-- +:xref-ERC721-_baseURI--: xref:token/ERC721.adoc#ERC721-_baseURI-- +:xref-ERC721-approve-address-uint256-: xref:token/ERC721.adoc#ERC721-approve-address-uint256- +:xref-ERC721-getApproved-uint256-: xref:token/ERC721.adoc#ERC721-getApproved-uint256- +:xref-ERC721-setApprovalForAll-address-bool-: xref:token/ERC721.adoc#ERC721-setApprovalForAll-address-bool- +:xref-ERC721-isApprovedForAll-address-address-: xref:token/ERC721.adoc#ERC721-isApprovedForAll-address-address- +:xref-ERC721-transferFrom-address-address-uint256-: xref:token/ERC721.adoc#ERC721-transferFrom-address-address-uint256- +:xref-ERC721-safeTransferFrom-address-address-uint256-: xref:token/ERC721.adoc#ERC721-safeTransferFrom-address-address-uint256- +:xref-ERC721-safeTransferFrom-address-address-uint256-bytes-: xref:token/ERC721.adoc#ERC721-safeTransferFrom-address-address-uint256-bytes- +:xref-ERC721-_ownerOf-uint256-: xref:token/ERC721.adoc#ERC721-_ownerOf-uint256- +:xref-ERC721-_getApproved-uint256-: xref:token/ERC721.adoc#ERC721-_getApproved-uint256- +:xref-ERC721-_isAuthorized-address-address-uint256-: xref:token/ERC721.adoc#ERC721-_isAuthorized-address-address-uint256- +:xref-ERC721-_checkAuthorized-address-address-uint256-: xref:token/ERC721.adoc#ERC721-_checkAuthorized-address-address-uint256- +:xref-ERC721-_increaseBalance-address-uint128-: xref:token/ERC721.adoc#ERC721-_increaseBalance-address-uint128- +:xref-ERC721-_update-address-uint256-address-: xref:token/ERC721.adoc#ERC721-_update-address-uint256-address- +:xref-ERC721-_mint-address-uint256-: xref:token/ERC721.adoc#ERC721-_mint-address-uint256- +:xref-ERC721-_safeMint-address-uint256-: xref:token/ERC721.adoc#ERC721-_safeMint-address-uint256- +:xref-ERC721-_safeMint-address-uint256-bytes-: xref:token/ERC721.adoc#ERC721-_safeMint-address-uint256-bytes- +:xref-ERC721-_burn-uint256-: xref:token/ERC721.adoc#ERC721-_burn-uint256- +:xref-ERC721-_transfer-address-address-uint256-: xref:token/ERC721.adoc#ERC721-_transfer-address-address-uint256- +:xref-ERC721-_safeTransfer-address-address-uint256-: xref:token/ERC721.adoc#ERC721-_safeTransfer-address-address-uint256- +:xref-ERC721-_safeTransfer-address-address-uint256-bytes-: xref:token/ERC721.adoc#ERC721-_safeTransfer-address-address-uint256-bytes- +:xref-ERC721-_approve-address-uint256-address-: xref:token/ERC721.adoc#ERC721-_approve-address-uint256-address- +:xref-ERC721-_approve-address-uint256-address-bool-: xref:token/ERC721.adoc#ERC721-_approve-address-uint256-address-bool- +:xref-ERC721-_setApprovalForAll-address-address-bool-: xref:token/ERC721.adoc#ERC721-_setApprovalForAll-address-address-bool- +:xref-ERC721-_requireOwned-uint256-: xref:token/ERC721.adoc#ERC721-_requireOwned-uint256- +:xref-IERC4906-MetadataUpdate-uint256-: xref:interfaces.adoc#IERC4906-MetadataUpdate-uint256- +:xref-IERC4906-BatchMetadataUpdate-uint256-uint256-: xref:interfaces.adoc#IERC4906-BatchMetadataUpdate-uint256-uint256- +:xref-IERC721-Transfer-address-address-uint256-: xref:token/ERC721.adoc#IERC721-Transfer-address-address-uint256- +:xref-IERC721-Approval-address-address-uint256-: xref:token/ERC721.adoc#IERC721-Approval-address-address-uint256- +:xref-IERC721-ApprovalForAll-address-address-bool-: xref:token/ERC721.adoc#IERC721-ApprovalForAll-address-address-bool- +:xref-IERC721Errors-ERC721InvalidOwner-address-: xref:interfaces.adoc#IERC721Errors-ERC721InvalidOwner-address- +:xref-IERC721Errors-ERC721NonexistentToken-uint256-: xref:interfaces.adoc#IERC721Errors-ERC721NonexistentToken-uint256- +:xref-IERC721Errors-ERC721IncorrectOwner-address-uint256-address-: xref:interfaces.adoc#IERC721Errors-ERC721IncorrectOwner-address-uint256-address- +:xref-IERC721Errors-ERC721InvalidSender-address-: xref:interfaces.adoc#IERC721Errors-ERC721InvalidSender-address- +:xref-IERC721Errors-ERC721InvalidReceiver-address-: xref:interfaces.adoc#IERC721Errors-ERC721InvalidReceiver-address- +:xref-IERC721Errors-ERC721InsufficientApproval-address-uint256-: xref:interfaces.adoc#IERC721Errors-ERC721InsufficientApproval-address-uint256- +:xref-IERC721Errors-ERC721InvalidApprover-address-: xref:interfaces.adoc#IERC721Errors-ERC721InvalidApprover-address- +:xref-IERC721Errors-ERC721InvalidOperator-address-: xref:interfaces.adoc#IERC721Errors-ERC721InvalidOperator-address- +:IERC165-supportsInterface: pass:normal[xref:utils.adoc#IERC165-supportsInterface-bytes4-[`IERC165.supportsInterface`]] +:IERC721Metadata-tokenURI: pass:normal[xref:token/ERC721.adoc#IERC721Metadata-tokenURI-uint256-[`IERC721Metadata.tokenURI`]] +:Votes: pass:normal[xref:governance.adoc#Votes[`Votes`]] +:xref-ERC721Votes-_update-address-uint256-address-: xref:token/ERC721.adoc#ERC721Votes-_update-address-uint256-address- +:xref-ERC721Votes-_getVotingUnits-address-: xref:token/ERC721.adoc#ERC721Votes-_getVotingUnits-address- +:xref-ERC721Votes-_increaseBalance-address-uint128-: xref:token/ERC721.adoc#ERC721Votes-_increaseBalance-address-uint128- +:xref-Votes-clock--: xref:governance.adoc#Votes-clock-- +:xref-Votes-CLOCK_MODE--: xref:governance.adoc#Votes-CLOCK_MODE-- +:xref-Votes-getVotes-address-: xref:governance.adoc#Votes-getVotes-address- +:xref-Votes-getPastVotes-address-uint256-: xref:governance.adoc#Votes-getPastVotes-address-uint256- +:xref-Votes-getPastTotalSupply-uint256-: xref:governance.adoc#Votes-getPastTotalSupply-uint256- +:xref-Votes-_getTotalSupply--: xref:governance.adoc#Votes-_getTotalSupply-- +:xref-Votes-delegates-address-: xref:governance.adoc#Votes-delegates-address- +:xref-Votes-delegate-address-: xref:governance.adoc#Votes-delegate-address- +:xref-Votes-delegateBySig-address-uint256-uint256-uint8-bytes32-bytes32-: xref:governance.adoc#Votes-delegateBySig-address-uint256-uint256-uint8-bytes32-bytes32- +:xref-Votes-_delegate-address-address-: xref:governance.adoc#Votes-_delegate-address-address- +:xref-Votes-_transferVotingUnits-address-address-uint256-: xref:governance.adoc#Votes-_transferVotingUnits-address-address-uint256- +:xref-Votes-_numCheckpoints-address-: xref:governance.adoc#Votes-_numCheckpoints-address- +:xref-Votes-_checkpoints-address-uint32-: xref:governance.adoc#Votes-_checkpoints-address-uint32- +:xref-Nonces-nonces-address-: xref:utils.adoc#Nonces-nonces-address- +:xref-Nonces-_useNonce-address-: xref:utils.adoc#Nonces-_useNonce-address- +:xref-Nonces-_useCheckedNonce-address-uint256-: xref:utils.adoc#Nonces-_useCheckedNonce-address-uint256- +:xref-EIP712-_domainSeparatorV4--: xref:utils.adoc#EIP712-_domainSeparatorV4-- +:xref-EIP712-_hashTypedDataV4-bytes32-: xref:utils.adoc#EIP712-_hashTypedDataV4-bytes32- +:xref-EIP712-eip712Domain--: xref:utils.adoc#EIP712-eip712Domain-- +:xref-EIP712-_EIP712Name--: xref:utils.adoc#EIP712-_EIP712Name-- +:xref-EIP712-_EIP712Version--: xref:utils.adoc#EIP712-_EIP712Version-- +:xref-ERC721-supportsInterface-bytes4-: xref:token/ERC721.adoc#ERC721-supportsInterface-bytes4- +:xref-ERC721-balanceOf-address-: xref:token/ERC721.adoc#ERC721-balanceOf-address- +:xref-ERC721-ownerOf-uint256-: xref:token/ERC721.adoc#ERC721-ownerOf-uint256- +:xref-ERC721-name--: xref:token/ERC721.adoc#ERC721-name-- +:xref-ERC721-symbol--: xref:token/ERC721.adoc#ERC721-symbol-- +:xref-ERC721-tokenURI-uint256-: xref:token/ERC721.adoc#ERC721-tokenURI-uint256- +:xref-ERC721-_baseURI--: xref:token/ERC721.adoc#ERC721-_baseURI-- +:xref-ERC721-approve-address-uint256-: xref:token/ERC721.adoc#ERC721-approve-address-uint256- +:xref-ERC721-getApproved-uint256-: xref:token/ERC721.adoc#ERC721-getApproved-uint256- +:xref-ERC721-setApprovalForAll-address-bool-: xref:token/ERC721.adoc#ERC721-setApprovalForAll-address-bool- +:xref-ERC721-isApprovedForAll-address-address-: xref:token/ERC721.adoc#ERC721-isApprovedForAll-address-address- +:xref-ERC721-transferFrom-address-address-uint256-: xref:token/ERC721.adoc#ERC721-transferFrom-address-address-uint256- +:xref-ERC721-safeTransferFrom-address-address-uint256-: xref:token/ERC721.adoc#ERC721-safeTransferFrom-address-address-uint256- +:xref-ERC721-safeTransferFrom-address-address-uint256-bytes-: xref:token/ERC721.adoc#ERC721-safeTransferFrom-address-address-uint256-bytes- +:xref-ERC721-_ownerOf-uint256-: xref:token/ERC721.adoc#ERC721-_ownerOf-uint256- +:xref-ERC721-_getApproved-uint256-: xref:token/ERC721.adoc#ERC721-_getApproved-uint256- +:xref-ERC721-_isAuthorized-address-address-uint256-: xref:token/ERC721.adoc#ERC721-_isAuthorized-address-address-uint256- +:xref-ERC721-_checkAuthorized-address-address-uint256-: xref:token/ERC721.adoc#ERC721-_checkAuthorized-address-address-uint256- +:xref-ERC721-_mint-address-uint256-: xref:token/ERC721.adoc#ERC721-_mint-address-uint256- +:xref-ERC721-_safeMint-address-uint256-: xref:token/ERC721.adoc#ERC721-_safeMint-address-uint256- +:xref-ERC721-_safeMint-address-uint256-bytes-: xref:token/ERC721.adoc#ERC721-_safeMint-address-uint256-bytes- +:xref-ERC721-_burn-uint256-: xref:token/ERC721.adoc#ERC721-_burn-uint256- +:xref-ERC721-_transfer-address-address-uint256-: xref:token/ERC721.adoc#ERC721-_transfer-address-address-uint256- +:xref-ERC721-_safeTransfer-address-address-uint256-: xref:token/ERC721.adoc#ERC721-_safeTransfer-address-address-uint256- +:xref-ERC721-_safeTransfer-address-address-uint256-bytes-: xref:token/ERC721.adoc#ERC721-_safeTransfer-address-address-uint256-bytes- +:xref-ERC721-_approve-address-uint256-address-: xref:token/ERC721.adoc#ERC721-_approve-address-uint256-address- +:xref-ERC721-_approve-address-uint256-address-bool-: xref:token/ERC721.adoc#ERC721-_approve-address-uint256-address-bool- +:xref-ERC721-_setApprovalForAll-address-address-bool-: xref:token/ERC721.adoc#ERC721-_setApprovalForAll-address-address-bool- +:xref-ERC721-_requireOwned-uint256-: xref:token/ERC721.adoc#ERC721-_requireOwned-uint256- +:xref-IVotes-DelegateChanged-address-address-address-: xref:governance.adoc#IVotes-DelegateChanged-address-address-address- +:xref-IVotes-DelegateVotesChanged-address-uint256-uint256-: xref:governance.adoc#IVotes-DelegateVotesChanged-address-uint256-uint256- +:xref-IERC5267-EIP712DomainChanged--: xref:interfaces.adoc#IERC5267-EIP712DomainChanged-- +:xref-IERC721-Transfer-address-address-uint256-: xref:token/ERC721.adoc#IERC721-Transfer-address-address-uint256- +:xref-IERC721-Approval-address-address-uint256-: xref:token/ERC721.adoc#IERC721-Approval-address-address-uint256- +:xref-IERC721-ApprovalForAll-address-address-bool-: xref:token/ERC721.adoc#IERC721-ApprovalForAll-address-address-bool- +:xref-Votes-ERC6372InconsistentClock--: xref:governance.adoc#Votes-ERC6372InconsistentClock-- +:xref-Votes-ERC5805FutureLookup-uint256-uint48-: xref:governance.adoc#Votes-ERC5805FutureLookup-uint256-uint48- +:xref-IVotes-VotesExpiredSignature-uint256-: xref:governance.adoc#IVotes-VotesExpiredSignature-uint256- +:xref-Nonces-InvalidAccountNonce-address-uint256-: xref:utils.adoc#Nonces-InvalidAccountNonce-address-uint256- +:xref-IERC721Errors-ERC721InvalidOwner-address-: xref:interfaces.adoc#IERC721Errors-ERC721InvalidOwner-address- +:xref-IERC721Errors-ERC721NonexistentToken-uint256-: xref:interfaces.adoc#IERC721Errors-ERC721NonexistentToken-uint256- +:xref-IERC721Errors-ERC721IncorrectOwner-address-uint256-address-: xref:interfaces.adoc#IERC721Errors-ERC721IncorrectOwner-address-uint256-address- +:xref-IERC721Errors-ERC721InvalidSender-address-: xref:interfaces.adoc#IERC721Errors-ERC721InvalidSender-address- +:xref-IERC721Errors-ERC721InvalidReceiver-address-: xref:interfaces.adoc#IERC721Errors-ERC721InvalidReceiver-address- +:xref-IERC721Errors-ERC721InsufficientApproval-address-uint256-: xref:interfaces.adoc#IERC721Errors-ERC721InsufficientApproval-address-uint256- +:xref-IERC721Errors-ERC721InvalidApprover-address-: xref:interfaces.adoc#IERC721Errors-ERC721InvalidApprover-address- +:xref-IERC721Errors-ERC721InvalidOperator-address-: xref:interfaces.adoc#IERC721Errors-ERC721InvalidOperator-address- +:ERC721-_update: pass:normal[xref:token/ERC721.adoc#ERC721-_update-address-uint256-address-[`ERC721._update`]] +:IVotes-DelegateVotesChanged: pass:normal[xref:governance.adoc#IVotes-DelegateVotesChanged-address-uint256-uint256-[`IVotes.DelegateVotesChanged`]] +:ERC721-_increaseBalance: pass:normal[xref:token/ERC721.adoc#ERC721-_increaseBalance-address-uint128-[`ERC721._increaseBalance`]] +:ERC2981-_setDefaultRoyalty: pass:normal[xref:token/common.adoc#ERC2981-_setDefaultRoyalty-address-uint96-[`ERC2981._setDefaultRoyalty`]] +:ERC2981-_setTokenRoyalty: pass:normal[xref:token/common.adoc#ERC2981-_setTokenRoyalty-uint256-address-uint96-[`ERC2981._setTokenRoyalty`]] +:xref-ERC721Royalty-supportsInterface-bytes4-: xref:token/ERC721.adoc#ERC721Royalty-supportsInterface-bytes4- +:xref-ERC721-balanceOf-address-: xref:token/ERC721.adoc#ERC721-balanceOf-address- +:xref-ERC721-ownerOf-uint256-: xref:token/ERC721.adoc#ERC721-ownerOf-uint256- +:xref-ERC721-name--: xref:token/ERC721.adoc#ERC721-name-- +:xref-ERC721-symbol--: xref:token/ERC721.adoc#ERC721-symbol-- +:xref-ERC721-tokenURI-uint256-: xref:token/ERC721.adoc#ERC721-tokenURI-uint256- +:xref-ERC721-_baseURI--: xref:token/ERC721.adoc#ERC721-_baseURI-- +:xref-ERC721-approve-address-uint256-: xref:token/ERC721.adoc#ERC721-approve-address-uint256- +:xref-ERC721-getApproved-uint256-: xref:token/ERC721.adoc#ERC721-getApproved-uint256- +:xref-ERC721-setApprovalForAll-address-bool-: xref:token/ERC721.adoc#ERC721-setApprovalForAll-address-bool- +:xref-ERC721-isApprovedForAll-address-address-: xref:token/ERC721.adoc#ERC721-isApprovedForAll-address-address- +:xref-ERC721-transferFrom-address-address-uint256-: xref:token/ERC721.adoc#ERC721-transferFrom-address-address-uint256- +:xref-ERC721-safeTransferFrom-address-address-uint256-: xref:token/ERC721.adoc#ERC721-safeTransferFrom-address-address-uint256- +:xref-ERC721-safeTransferFrom-address-address-uint256-bytes-: xref:token/ERC721.adoc#ERC721-safeTransferFrom-address-address-uint256-bytes- +:xref-ERC721-_ownerOf-uint256-: xref:token/ERC721.adoc#ERC721-_ownerOf-uint256- +:xref-ERC721-_getApproved-uint256-: xref:token/ERC721.adoc#ERC721-_getApproved-uint256- +:xref-ERC721-_isAuthorized-address-address-uint256-: xref:token/ERC721.adoc#ERC721-_isAuthorized-address-address-uint256- +:xref-ERC721-_checkAuthorized-address-address-uint256-: xref:token/ERC721.adoc#ERC721-_checkAuthorized-address-address-uint256- +:xref-ERC721-_increaseBalance-address-uint128-: xref:token/ERC721.adoc#ERC721-_increaseBalance-address-uint128- +:xref-ERC721-_update-address-uint256-address-: xref:token/ERC721.adoc#ERC721-_update-address-uint256-address- +:xref-ERC721-_mint-address-uint256-: xref:token/ERC721.adoc#ERC721-_mint-address-uint256- +:xref-ERC721-_safeMint-address-uint256-: xref:token/ERC721.adoc#ERC721-_safeMint-address-uint256- +:xref-ERC721-_safeMint-address-uint256-bytes-: xref:token/ERC721.adoc#ERC721-_safeMint-address-uint256-bytes- +:xref-ERC721-_burn-uint256-: xref:token/ERC721.adoc#ERC721-_burn-uint256- +:xref-ERC721-_transfer-address-address-uint256-: xref:token/ERC721.adoc#ERC721-_transfer-address-address-uint256- +:xref-ERC721-_safeTransfer-address-address-uint256-: xref:token/ERC721.adoc#ERC721-_safeTransfer-address-address-uint256- +:xref-ERC721-_safeTransfer-address-address-uint256-bytes-: xref:token/ERC721.adoc#ERC721-_safeTransfer-address-address-uint256-bytes- +:xref-ERC721-_approve-address-uint256-address-: xref:token/ERC721.adoc#ERC721-_approve-address-uint256-address- +:xref-ERC721-_approve-address-uint256-address-bool-: xref:token/ERC721.adoc#ERC721-_approve-address-uint256-address-bool- +:xref-ERC721-_setApprovalForAll-address-address-bool-: xref:token/ERC721.adoc#ERC721-_setApprovalForAll-address-address-bool- +:xref-ERC721-_requireOwned-uint256-: xref:token/ERC721.adoc#ERC721-_requireOwned-uint256- +:xref-ERC2981-royaltyInfo-uint256-uint256-: xref:token/common.adoc#ERC2981-royaltyInfo-uint256-uint256- +:xref-ERC2981-_feeDenominator--: xref:token/common.adoc#ERC2981-_feeDenominator-- +:xref-ERC2981-_setDefaultRoyalty-address-uint96-: xref:token/common.adoc#ERC2981-_setDefaultRoyalty-address-uint96- +:xref-ERC2981-_deleteDefaultRoyalty--: xref:token/common.adoc#ERC2981-_deleteDefaultRoyalty-- +:xref-ERC2981-_setTokenRoyalty-uint256-address-uint96-: xref:token/common.adoc#ERC2981-_setTokenRoyalty-uint256-address-uint96- +:xref-ERC2981-_resetTokenRoyalty-uint256-: xref:token/common.adoc#ERC2981-_resetTokenRoyalty-uint256- +:xref-IERC721-Transfer-address-address-uint256-: xref:token/ERC721.adoc#IERC721-Transfer-address-address-uint256- +:xref-IERC721-Approval-address-address-uint256-: xref:token/ERC721.adoc#IERC721-Approval-address-address-uint256- +:xref-IERC721-ApprovalForAll-address-address-bool-: xref:token/ERC721.adoc#IERC721-ApprovalForAll-address-address-bool- +:xref-IERC721Errors-ERC721InvalidOwner-address-: xref:interfaces.adoc#IERC721Errors-ERC721InvalidOwner-address- +:xref-IERC721Errors-ERC721NonexistentToken-uint256-: xref:interfaces.adoc#IERC721Errors-ERC721NonexistentToken-uint256- +:xref-IERC721Errors-ERC721IncorrectOwner-address-uint256-address-: xref:interfaces.adoc#IERC721Errors-ERC721IncorrectOwner-address-uint256-address- +:xref-IERC721Errors-ERC721InvalidSender-address-: xref:interfaces.adoc#IERC721Errors-ERC721InvalidSender-address- +:xref-IERC721Errors-ERC721InvalidReceiver-address-: xref:interfaces.adoc#IERC721Errors-ERC721InvalidReceiver-address- +:xref-IERC721Errors-ERC721InsufficientApproval-address-uint256-: xref:interfaces.adoc#IERC721Errors-ERC721InsufficientApproval-address-uint256- +:xref-IERC721Errors-ERC721InvalidApprover-address-: xref:interfaces.adoc#IERC721Errors-ERC721InvalidApprover-address- +:xref-IERC721Errors-ERC721InvalidOperator-address-: xref:interfaces.adoc#IERC721Errors-ERC721InvalidOperator-address- +:xref-ERC2981-ERC2981InvalidDefaultRoyalty-uint256-uint256-: xref:token/common.adoc#ERC2981-ERC2981InvalidDefaultRoyalty-uint256-uint256- +:xref-ERC2981-ERC2981InvalidDefaultRoyaltyReceiver-address-: xref:token/common.adoc#ERC2981-ERC2981InvalidDefaultRoyaltyReceiver-address- +:xref-ERC2981-ERC2981InvalidTokenRoyalty-uint256-uint256-uint256-: xref:token/common.adoc#ERC2981-ERC2981InvalidTokenRoyalty-uint256-uint256-uint256- +:xref-ERC2981-ERC2981InvalidTokenRoyaltyReceiver-uint256-address-: xref:token/common.adoc#ERC2981-ERC2981InvalidTokenRoyaltyReceiver-uint256-address- +:IERC165-supportsInterface: pass:normal[xref:utils.adoc#IERC165-supportsInterface-bytes4-[`IERC165.supportsInterface`]] +:ERC721Votes: pass:normal[xref:token/ERC721.adoc#ERC721Votes[`ERC721Votes`]] +:xref-ERC721Wrapper-constructor-contract-IERC721-: xref:token/ERC721.adoc#ERC721Wrapper-constructor-contract-IERC721- +:xref-ERC721Wrapper-depositFor-address-uint256---: xref:token/ERC721.adoc#ERC721Wrapper-depositFor-address-uint256--- +:xref-ERC721Wrapper-withdrawTo-address-uint256---: xref:token/ERC721.adoc#ERC721Wrapper-withdrawTo-address-uint256--- +:xref-ERC721Wrapper-onERC721Received-address-address-uint256-bytes-: xref:token/ERC721.adoc#ERC721Wrapper-onERC721Received-address-address-uint256-bytes- +:xref-ERC721Wrapper-_recover-address-uint256-: xref:token/ERC721.adoc#ERC721Wrapper-_recover-address-uint256- +:xref-ERC721Wrapper-underlying--: xref:token/ERC721.adoc#ERC721Wrapper-underlying-- +:xref-ERC721-supportsInterface-bytes4-: xref:token/ERC721.adoc#ERC721-supportsInterface-bytes4- +:xref-ERC721-balanceOf-address-: xref:token/ERC721.adoc#ERC721-balanceOf-address- +:xref-ERC721-ownerOf-uint256-: xref:token/ERC721.adoc#ERC721-ownerOf-uint256- +:xref-ERC721-name--: xref:token/ERC721.adoc#ERC721-name-- +:xref-ERC721-symbol--: xref:token/ERC721.adoc#ERC721-symbol-- +:xref-ERC721-tokenURI-uint256-: xref:token/ERC721.adoc#ERC721-tokenURI-uint256- +:xref-ERC721-_baseURI--: xref:token/ERC721.adoc#ERC721-_baseURI-- +:xref-ERC721-approve-address-uint256-: xref:token/ERC721.adoc#ERC721-approve-address-uint256- +:xref-ERC721-getApproved-uint256-: xref:token/ERC721.adoc#ERC721-getApproved-uint256- +:xref-ERC721-setApprovalForAll-address-bool-: xref:token/ERC721.adoc#ERC721-setApprovalForAll-address-bool- +:xref-ERC721-isApprovedForAll-address-address-: xref:token/ERC721.adoc#ERC721-isApprovedForAll-address-address- +:xref-ERC721-transferFrom-address-address-uint256-: xref:token/ERC721.adoc#ERC721-transferFrom-address-address-uint256- +:xref-ERC721-safeTransferFrom-address-address-uint256-: xref:token/ERC721.adoc#ERC721-safeTransferFrom-address-address-uint256- +:xref-ERC721-safeTransferFrom-address-address-uint256-bytes-: xref:token/ERC721.adoc#ERC721-safeTransferFrom-address-address-uint256-bytes- +:xref-ERC721-_ownerOf-uint256-: xref:token/ERC721.adoc#ERC721-_ownerOf-uint256- +:xref-ERC721-_getApproved-uint256-: xref:token/ERC721.adoc#ERC721-_getApproved-uint256- +:xref-ERC721-_isAuthorized-address-address-uint256-: xref:token/ERC721.adoc#ERC721-_isAuthorized-address-address-uint256- +:xref-ERC721-_checkAuthorized-address-address-uint256-: xref:token/ERC721.adoc#ERC721-_checkAuthorized-address-address-uint256- +:xref-ERC721-_increaseBalance-address-uint128-: xref:token/ERC721.adoc#ERC721-_increaseBalance-address-uint128- +:xref-ERC721-_update-address-uint256-address-: xref:token/ERC721.adoc#ERC721-_update-address-uint256-address- +:xref-ERC721-_mint-address-uint256-: xref:token/ERC721.adoc#ERC721-_mint-address-uint256- +:xref-ERC721-_safeMint-address-uint256-: xref:token/ERC721.adoc#ERC721-_safeMint-address-uint256- +:xref-ERC721-_safeMint-address-uint256-bytes-: xref:token/ERC721.adoc#ERC721-_safeMint-address-uint256-bytes- +:xref-ERC721-_burn-uint256-: xref:token/ERC721.adoc#ERC721-_burn-uint256- +:xref-ERC721-_transfer-address-address-uint256-: xref:token/ERC721.adoc#ERC721-_transfer-address-address-uint256- +:xref-ERC721-_safeTransfer-address-address-uint256-: xref:token/ERC721.adoc#ERC721-_safeTransfer-address-address-uint256- +:xref-ERC721-_safeTransfer-address-address-uint256-bytes-: xref:token/ERC721.adoc#ERC721-_safeTransfer-address-address-uint256-bytes- +:xref-ERC721-_approve-address-uint256-address-: xref:token/ERC721.adoc#ERC721-_approve-address-uint256-address- +:xref-ERC721-_approve-address-uint256-address-bool-: xref:token/ERC721.adoc#ERC721-_approve-address-uint256-address-bool- +:xref-ERC721-_setApprovalForAll-address-address-bool-: xref:token/ERC721.adoc#ERC721-_setApprovalForAll-address-address-bool- +:xref-ERC721-_requireOwned-uint256-: xref:token/ERC721.adoc#ERC721-_requireOwned-uint256- +:xref-IERC721-Transfer-address-address-uint256-: xref:token/ERC721.adoc#IERC721-Transfer-address-address-uint256- +:xref-IERC721-Approval-address-address-uint256-: xref:token/ERC721.adoc#IERC721-Approval-address-address-uint256- +:xref-IERC721-ApprovalForAll-address-address-bool-: xref:token/ERC721.adoc#IERC721-ApprovalForAll-address-address-bool- +:xref-ERC721Wrapper-ERC721UnsupportedToken-address-: xref:token/ERC721.adoc#ERC721Wrapper-ERC721UnsupportedToken-address- +:xref-IERC721Errors-ERC721InvalidOwner-address-: xref:interfaces.adoc#IERC721Errors-ERC721InvalidOwner-address- +:xref-IERC721Errors-ERC721NonexistentToken-uint256-: xref:interfaces.adoc#IERC721Errors-ERC721NonexistentToken-uint256- +:xref-IERC721Errors-ERC721IncorrectOwner-address-uint256-address-: xref:interfaces.adoc#IERC721Errors-ERC721IncorrectOwner-address-uint256-address- +:xref-IERC721Errors-ERC721InvalidSender-address-: xref:interfaces.adoc#IERC721Errors-ERC721InvalidSender-address- +:xref-IERC721Errors-ERC721InvalidReceiver-address-: xref:interfaces.adoc#IERC721Errors-ERC721InvalidReceiver-address- +:xref-IERC721Errors-ERC721InsufficientApproval-address-uint256-: xref:interfaces.adoc#IERC721Errors-ERC721InsufficientApproval-address-uint256- +:xref-IERC721Errors-ERC721InvalidApprover-address-: xref:interfaces.adoc#IERC721Errors-ERC721InvalidApprover-address- +:xref-IERC721Errors-ERC721InvalidOperator-address-: xref:interfaces.adoc#IERC721Errors-ERC721InvalidOperator-address- +:IERC721Receiver-onERC721Received: pass:normal[xref:token/ERC721.adoc#IERC721Receiver-onERC721Received-address-address-uint256-bytes-[`IERC721Receiver.onERC721Received`]] +:IERC721-transferFrom: pass:normal[xref:token/ERC721.adoc#IERC721-transferFrom-address-address-uint256-[`IERC721.transferFrom`]] +:ERC721Wrapper-_recover: pass:normal[xref:token/ERC721.adoc#ERC721Wrapper-_recover-address-uint256-[`ERC721Wrapper._recover`]] +:IERC721Receiver: pass:normal[xref:token/ERC721.adoc#IERC721Receiver[`IERC721Receiver`]] +:IERC721-safeTransferFrom: pass:normal[xref:token/ERC721.adoc#IERC721-safeTransferFrom-address-address-uint256-[`IERC721.safeTransferFrom`]] +:IERC721-approve: pass:normal[xref:token/ERC721.adoc#IERC721-approve-address-uint256-[`IERC721.approve`]] +:IERC721-setApprovalForAll: pass:normal[xref:token/ERC721.adoc#IERC721-setApprovalForAll-address-bool-[`IERC721.setApprovalForAll`]] +:xref-ERC721Holder-onERC721Received-address-address-uint256-bytes-: xref:token/ERC721.adoc#ERC721Holder-onERC721Received-address-address-uint256-bytes- +:IERC721Receiver-onERC721Received: pass:normal[xref:token/ERC721.adoc#IERC721Receiver-onERC721Received-address-address-uint256-bytes-[`IERC721Receiver.onERC721Received`]] += ERC 721 + +[.readme-notice] +NOTE: This document is better viewed at https://docs.openzeppelin.com/contracts/api/token/erc721 + +This set of interfaces, contracts, and utilities are all related to the https://eips.ethereum.org/EIPS/eip-721[ERC721 Non-Fungible Token Standard]. + +TIP: For a walk through on how to create an ERC721 token read our xref:ROOT:erc721.adoc[ERC721 guide]. + +The EIP specifies four interfaces: + +* {IERC721}: Core functionality required in all compliant implementation. +* {IERC721Metadata}: Optional extension that adds name, symbol, and token URI, almost always included. +* {IERC721Enumerable}: Optional extension that allows enumerating the tokens on chain, often not included since it requires large gas overhead. +* {IERC721Receiver}: An interface that must be implemented by contracts if they want to accept tokens through `safeTransferFrom`. + +OpenZeppelin Contracts provides implementations of all four interfaces: + +* {ERC721}: The core and metadata extensions, with a base URI mechanism. +* {ERC721Enumerable}: The enumerable extension. +* {ERC721Holder}: A bare bones implementation of the receiver interface. + +Additionally there are a few of other extensions: + +* {ERC721Consecutive}: An implementation of https://eips.ethereum.org/EIPS/eip-2309[ERC2309] for minting batchs of tokens during construction, in accordance with ERC721. +* {ERC721URIStorage}: A more flexible but more expensive way of storing metadata. +* {ERC721Votes}: Support for voting and vote delegation. +* {ERC721Royalty}: A way to signal royalty information following ERC2981. +* {ERC721Pausable}: A primitive to pause contract operation. +* {ERC721Burnable}: A way for token holders to burn their own tokens. +* {ERC721Wrapper}: Wrapper to create an ERC721 backed by another ERC721, with deposit and withdraw methods. Useful in conjunction with {ERC721Votes}. + +NOTE: This core set of contracts is designed to be unopinionated, allowing developers to access the internal functions in ERC721 (such as <>) and expose them as external functions in the way they prefer. + +== Core + +:Transfer: pass:normal[xref:#IERC721-Transfer-address-address-uint256-[`++Transfer++`]] +:Approval: pass:normal[xref:#IERC721-Approval-address-address-uint256-[`++Approval++`]] +:ApprovalForAll: pass:normal[xref:#IERC721-ApprovalForAll-address-address-bool-[`++ApprovalForAll++`]] +:balanceOf: pass:normal[xref:#IERC721-balanceOf-address-[`++balanceOf++`]] +:ownerOf: pass:normal[xref:#IERC721-ownerOf-uint256-[`++ownerOf++`]] +:safeTransferFrom: pass:normal[xref:#IERC721-safeTransferFrom-address-address-uint256-bytes-[`++safeTransferFrom++`]] +:safeTransferFrom: pass:normal[xref:#IERC721-safeTransferFrom-address-address-uint256-[`++safeTransferFrom++`]] +:transferFrom: pass:normal[xref:#IERC721-transferFrom-address-address-uint256-[`++transferFrom++`]] +:approve: pass:normal[xref:#IERC721-approve-address-uint256-[`++approve++`]] +:setApprovalForAll: pass:normal[xref:#IERC721-setApprovalForAll-address-bool-[`++setApprovalForAll++`]] +:getApproved: pass:normal[xref:#IERC721-getApproved-uint256-[`++getApproved++`]] +:isApprovedForAll: pass:normal[xref:#IERC721-isApprovedForAll-address-address-[`++isApprovedForAll++`]] + +[.contract] +[[IERC721]] +=== `++IERC721++` link:https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v5.0.0-rc.0/contracts/token/ERC721/IERC721.sol[{github-icon},role=heading-link] + +[.hljs-theme-light.nopadding] +```solidity +import "@openzeppelin/contracts/token/ERC721/IERC721.sol"; +``` + +Required interface of an ERC721 compliant contract. + +[.contract-index] +.Functions +-- +* {xref-IERC721-balanceOf-address-}[`++balanceOf(owner)++`] +* {xref-IERC721-ownerOf-uint256-}[`++ownerOf(tokenId)++`] +* {xref-IERC721-safeTransferFrom-address-address-uint256-bytes-}[`++safeTransferFrom(from, to, tokenId, data)++`] +* {xref-IERC721-safeTransferFrom-address-address-uint256-}[`++safeTransferFrom(from, to, tokenId)++`] +* {xref-IERC721-transferFrom-address-address-uint256-}[`++transferFrom(from, to, tokenId)++`] +* {xref-IERC721-approve-address-uint256-}[`++approve(to, tokenId)++`] +* {xref-IERC721-setApprovalForAll-address-bool-}[`++setApprovalForAll(operator, approved)++`] +* {xref-IERC721-getApproved-uint256-}[`++getApproved(tokenId)++`] +* {xref-IERC721-isApprovedForAll-address-address-}[`++isApprovedForAll(owner, operator)++`] + +[.contract-subindex-inherited] +.IERC165 +* {xref-IERC165-supportsInterface-bytes4-}[`++supportsInterface(interfaceId)++`] + +-- + +[.contract-index] +.Events +-- +* {xref-IERC721-Transfer-address-address-uint256-}[`++Transfer(from, to, tokenId)++`] +* {xref-IERC721-Approval-address-address-uint256-}[`++Approval(owner, approved, tokenId)++`] +* {xref-IERC721-ApprovalForAll-address-address-bool-}[`++ApprovalForAll(owner, operator, approved)++`] + +[.contract-subindex-inherited] +.IERC165 + +-- + +[.contract-item] +[[IERC721-balanceOf-address-]] +==== `[.contract-item-name]#++balanceOf++#++(address owner) → uint256 balance++` [.item-kind]#external# + +Returns the number of tokens in ``owner``'s account. + +[.contract-item] +[[IERC721-ownerOf-uint256-]] +==== `[.contract-item-name]#++ownerOf++#++(uint256 tokenId) → address owner++` [.item-kind]#external# + +Returns the owner of the `tokenId` token. + +Requirements: + +- `tokenId` must exist. + +[.contract-item] +[[IERC721-safeTransferFrom-address-address-uint256-bytes-]] +==== `[.contract-item-name]#++safeTransferFrom++#++(address from, address to, uint256 tokenId, bytes data)++` [.item-kind]#external# + +Safely transfers `tokenId` token from `from` to `to`. + +Requirements: + +- `from` cannot be the zero address. +- `to` cannot be the zero address. +- `tokenId` token must exist and be owned by `from`. +- If the caller is not `from`, it must be approved to move this token by either {approve} or {setApprovalForAll}. +- If `to` refers to a smart contract, it must implement {IERC721Receiver-onERC721Received}, which is called upon + a safe transfer. + +Emits a {Transfer} event. + +[.contract-item] +[[IERC721-safeTransferFrom-address-address-uint256-]] +==== `[.contract-item-name]#++safeTransferFrom++#++(address from, address to, uint256 tokenId)++` [.item-kind]#external# + +Safely transfers `tokenId` token from `from` to `to`, checking first that contract recipients +are aware of the ERC721 protocol to prevent tokens from being forever locked. + +Requirements: + +- `from` cannot be the zero address. +- `to` cannot be the zero address. +- `tokenId` token must exist and be owned by `from`. +- If the caller is not `from`, it must have been allowed to move this token by either {approve} or + {setApprovalForAll}. +- If `to` refers to a smart contract, it must implement {IERC721Receiver-onERC721Received}, which is called upon + a safe transfer. + +Emits a {Transfer} event. + +[.contract-item] +[[IERC721-transferFrom-address-address-uint256-]] +==== `[.contract-item-name]#++transferFrom++#++(address from, address to, uint256 tokenId)++` [.item-kind]#external# + +Transfers `tokenId` token from `from` to `to`. + +WARNING: Note that the caller is responsible to confirm that the recipient is capable of receiving ERC721 +or else they may be permanently lost. Usage of {safeTransferFrom} prevents loss, though the caller must +understand this adds an external call which potentially creates a reentrancy vulnerability. + +Requirements: + +- `from` cannot be the zero address. +- `to` cannot be the zero address. +- `tokenId` token must be owned by `from`. +- If the caller is not `from`, it must be approved to move this token by either {approve} or {setApprovalForAll}. + +Emits a {Transfer} event. + +[.contract-item] +[[IERC721-approve-address-uint256-]] +==== `[.contract-item-name]#++approve++#++(address to, uint256 tokenId)++` [.item-kind]#external# + +Gives permission to `to` to transfer `tokenId` token to another account. +The approval is cleared when the token is transferred. + +Only a single account can be approved at a time, so approving the zero address clears previous approvals. + +Requirements: + +- The caller must own the token or be an approved operator. +- `tokenId` must exist. + +Emits an {Approval} event. + +[.contract-item] +[[IERC721-setApprovalForAll-address-bool-]] +==== `[.contract-item-name]#++setApprovalForAll++#++(address operator, bool approved)++` [.item-kind]#external# + +Approve or remove `operator` as an operator for the caller. +Operators can call {transferFrom} or {safeTransferFrom} for any token owned by the caller. + +Requirements: + +- The `operator` cannot be the address zero. + +Emits an {ApprovalForAll} event. + +[.contract-item] +[[IERC721-getApproved-uint256-]] +==== `[.contract-item-name]#++getApproved++#++(uint256 tokenId) → address operator++` [.item-kind]#external# + +Returns the account approved for `tokenId` token. + +Requirements: + +- `tokenId` must exist. + +[.contract-item] +[[IERC721-isApprovedForAll-address-address-]] +==== `[.contract-item-name]#++isApprovedForAll++#++(address owner, address operator) → bool++` [.item-kind]#external# + +Returns if the `operator` is allowed to manage all of the assets of `owner`. + +See {setApprovalForAll} + +[.contract-item] +[[IERC721-Transfer-address-address-uint256-]] +==== `[.contract-item-name]#++Transfer++#++(address indexed from, address indexed to, uint256 indexed tokenId)++` [.item-kind]#event# + +Emitted when `tokenId` token is transferred from `from` to `to`. + +[.contract-item] +[[IERC721-Approval-address-address-uint256-]] +==== `[.contract-item-name]#++Approval++#++(address indexed owner, address indexed approved, uint256 indexed tokenId)++` [.item-kind]#event# + +Emitted when `owner` enables `approved` to manage the `tokenId` token. + +[.contract-item] +[[IERC721-ApprovalForAll-address-address-bool-]] +==== `[.contract-item-name]#++ApprovalForAll++#++(address indexed owner, address indexed operator, bool approved)++` [.item-kind]#event# + +Emitted when `owner` enables or disables (`approved`) `operator` to manage all of its assets. + +:name: pass:normal[xref:#IERC721Metadata-name--[`++name++`]] +:symbol: pass:normal[xref:#IERC721Metadata-symbol--[`++symbol++`]] +:tokenURI: pass:normal[xref:#IERC721Metadata-tokenURI-uint256-[`++tokenURI++`]] + +[.contract] +[[IERC721Metadata]] +=== `++IERC721Metadata++` link:https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v5.0.0-rc.0/contracts/token/ERC721/extensions/IERC721Metadata.sol[{github-icon},role=heading-link] + +[.hljs-theme-light.nopadding] +```solidity +import "@openzeppelin/contracts/token/ERC721/extensions/IERC721Metadata.sol"; +``` + +See https://eips.ethereum.org/EIPS/eip-721 + +[.contract-index] +.Functions +-- +* {xref-IERC721Metadata-name--}[`++name()++`] +* {xref-IERC721Metadata-symbol--}[`++symbol()++`] +* {xref-IERC721Metadata-tokenURI-uint256-}[`++tokenURI(tokenId)++`] + +[.contract-subindex-inherited] +.IERC721 +* {xref-IERC721-balanceOf-address-}[`++balanceOf(owner)++`] +* {xref-IERC721-ownerOf-uint256-}[`++ownerOf(tokenId)++`] +* {xref-IERC721-safeTransferFrom-address-address-uint256-bytes-}[`++safeTransferFrom(from, to, tokenId, data)++`] +* {xref-IERC721-safeTransferFrom-address-address-uint256-}[`++safeTransferFrom(from, to, tokenId)++`] +* {xref-IERC721-transferFrom-address-address-uint256-}[`++transferFrom(from, to, tokenId)++`] +* {xref-IERC721-approve-address-uint256-}[`++approve(to, tokenId)++`] +* {xref-IERC721-setApprovalForAll-address-bool-}[`++setApprovalForAll(operator, approved)++`] +* {xref-IERC721-getApproved-uint256-}[`++getApproved(tokenId)++`] +* {xref-IERC721-isApprovedForAll-address-address-}[`++isApprovedForAll(owner, operator)++`] + +[.contract-subindex-inherited] +.IERC165 +* {xref-IERC165-supportsInterface-bytes4-}[`++supportsInterface(interfaceId)++`] + +-- + +[.contract-index] +.Events +-- + +[.contract-subindex-inherited] +.IERC721 +* {xref-IERC721-Transfer-address-address-uint256-}[`++Transfer(from, to, tokenId)++`] +* {xref-IERC721-Approval-address-address-uint256-}[`++Approval(owner, approved, tokenId)++`] +* {xref-IERC721-ApprovalForAll-address-address-bool-}[`++ApprovalForAll(owner, operator, approved)++`] + +[.contract-subindex-inherited] +.IERC165 + +-- + +[.contract-item] +[[IERC721Metadata-name--]] +==== `[.contract-item-name]#++name++#++() → string++` [.item-kind]#external# + +Returns the token collection name. + +[.contract-item] +[[IERC721Metadata-symbol--]] +==== `[.contract-item-name]#++symbol++#++() → string++` [.item-kind]#external# + +Returns the token collection symbol. + +[.contract-item] +[[IERC721Metadata-tokenURI-uint256-]] +==== `[.contract-item-name]#++tokenURI++#++(uint256 tokenId) → string++` [.item-kind]#external# + +Returns the Uniform Resource Identifier (URI) for `tokenId` token. + +:totalSupply: pass:normal[xref:#IERC721Enumerable-totalSupply--[`++totalSupply++`]] +:tokenOfOwnerByIndex: pass:normal[xref:#IERC721Enumerable-tokenOfOwnerByIndex-address-uint256-[`++tokenOfOwnerByIndex++`]] +:tokenByIndex: pass:normal[xref:#IERC721Enumerable-tokenByIndex-uint256-[`++tokenByIndex++`]] + +[.contract] +[[IERC721Enumerable]] +=== `++IERC721Enumerable++` link:https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v5.0.0-rc.0/contracts/token/ERC721/extensions/IERC721Enumerable.sol[{github-icon},role=heading-link] + +[.hljs-theme-light.nopadding] +```solidity +import "@openzeppelin/contracts/token/ERC721/extensions/IERC721Enumerable.sol"; +``` + +See https://eips.ethereum.org/EIPS/eip-721 + +[.contract-index] +.Functions +-- +* {xref-IERC721Enumerable-totalSupply--}[`++totalSupply()++`] +* {xref-IERC721Enumerable-tokenOfOwnerByIndex-address-uint256-}[`++tokenOfOwnerByIndex(owner, index)++`] +* {xref-IERC721Enumerable-tokenByIndex-uint256-}[`++tokenByIndex(index)++`] + +[.contract-subindex-inherited] +.IERC721 +* {xref-IERC721-balanceOf-address-}[`++balanceOf(owner)++`] +* {xref-IERC721-ownerOf-uint256-}[`++ownerOf(tokenId)++`] +* {xref-IERC721-safeTransferFrom-address-address-uint256-bytes-}[`++safeTransferFrom(from, to, tokenId, data)++`] +* {xref-IERC721-safeTransferFrom-address-address-uint256-}[`++safeTransferFrom(from, to, tokenId)++`] +* {xref-IERC721-transferFrom-address-address-uint256-}[`++transferFrom(from, to, tokenId)++`] +* {xref-IERC721-approve-address-uint256-}[`++approve(to, tokenId)++`] +* {xref-IERC721-setApprovalForAll-address-bool-}[`++setApprovalForAll(operator, approved)++`] +* {xref-IERC721-getApproved-uint256-}[`++getApproved(tokenId)++`] +* {xref-IERC721-isApprovedForAll-address-address-}[`++isApprovedForAll(owner, operator)++`] + +[.contract-subindex-inherited] +.IERC165 +* {xref-IERC165-supportsInterface-bytes4-}[`++supportsInterface(interfaceId)++`] + +-- + +[.contract-index] +.Events +-- + +[.contract-subindex-inherited] +.IERC721 +* {xref-IERC721-Transfer-address-address-uint256-}[`++Transfer(from, to, tokenId)++`] +* {xref-IERC721-Approval-address-address-uint256-}[`++Approval(owner, approved, tokenId)++`] +* {xref-IERC721-ApprovalForAll-address-address-bool-}[`++ApprovalForAll(owner, operator, approved)++`] + +[.contract-subindex-inherited] +.IERC165 + +-- + +[.contract-item] +[[IERC721Enumerable-totalSupply--]] +==== `[.contract-item-name]#++totalSupply++#++() → uint256++` [.item-kind]#external# + +Returns the total amount of tokens stored by the contract. + +[.contract-item] +[[IERC721Enumerable-tokenOfOwnerByIndex-address-uint256-]] +==== `[.contract-item-name]#++tokenOfOwnerByIndex++#++(address owner, uint256 index) → uint256++` [.item-kind]#external# + +Returns a token ID owned by `owner` at a given `index` of its token list. +Use along with {balanceOf} to enumerate all of ``owner``'s tokens. + +[.contract-item] +[[IERC721Enumerable-tokenByIndex-uint256-]] +==== `[.contract-item-name]#++tokenByIndex++#++(uint256 index) → uint256++` [.item-kind]#external# + +Returns a token ID at a given `index` of all the tokens stored by the contract. +Use along with {totalSupply} to enumerate all tokens. + +:constructor: pass:normal[xref:#ERC721-constructor-string-string-[`++constructor++`]] +:supportsInterface: pass:normal[xref:#ERC721-supportsInterface-bytes4-[`++supportsInterface++`]] +:balanceOf: pass:normal[xref:#ERC721-balanceOf-address-[`++balanceOf++`]] +:ownerOf: pass:normal[xref:#ERC721-ownerOf-uint256-[`++ownerOf++`]] +:name: pass:normal[xref:#ERC721-name--[`++name++`]] +:symbol: pass:normal[xref:#ERC721-symbol--[`++symbol++`]] +:tokenURI: pass:normal[xref:#ERC721-tokenURI-uint256-[`++tokenURI++`]] +:_baseURI: pass:normal[xref:#ERC721-_baseURI--[`++_baseURI++`]] +:approve: pass:normal[xref:#ERC721-approve-address-uint256-[`++approve++`]] +:getApproved: pass:normal[xref:#ERC721-getApproved-uint256-[`++getApproved++`]] +:setApprovalForAll: pass:normal[xref:#ERC721-setApprovalForAll-address-bool-[`++setApprovalForAll++`]] +:isApprovedForAll: pass:normal[xref:#ERC721-isApprovedForAll-address-address-[`++isApprovedForAll++`]] +:transferFrom: pass:normal[xref:#ERC721-transferFrom-address-address-uint256-[`++transferFrom++`]] +:safeTransferFrom: pass:normal[xref:#ERC721-safeTransferFrom-address-address-uint256-[`++safeTransferFrom++`]] +:safeTransferFrom: pass:normal[xref:#ERC721-safeTransferFrom-address-address-uint256-bytes-[`++safeTransferFrom++`]] +:_ownerOf: pass:normal[xref:#ERC721-_ownerOf-uint256-[`++_ownerOf++`]] +:_getApproved: pass:normal[xref:#ERC721-_getApproved-uint256-[`++_getApproved++`]] +:_isAuthorized: pass:normal[xref:#ERC721-_isAuthorized-address-address-uint256-[`++_isAuthorized++`]] +:_checkAuthorized: pass:normal[xref:#ERC721-_checkAuthorized-address-address-uint256-[`++_checkAuthorized++`]] +:_increaseBalance: pass:normal[xref:#ERC721-_increaseBalance-address-uint128-[`++_increaseBalance++`]] +:_update: pass:normal[xref:#ERC721-_update-address-uint256-address-[`++_update++`]] +:_mint: pass:normal[xref:#ERC721-_mint-address-uint256-[`++_mint++`]] +:_safeMint: pass:normal[xref:#ERC721-_safeMint-address-uint256-[`++_safeMint++`]] +:_safeMint: pass:normal[xref:#ERC721-_safeMint-address-uint256-bytes-[`++_safeMint++`]] +:_burn: pass:normal[xref:#ERC721-_burn-uint256-[`++_burn++`]] +:_transfer: pass:normal[xref:#ERC721-_transfer-address-address-uint256-[`++_transfer++`]] +:_safeTransfer: pass:normal[xref:#ERC721-_safeTransfer-address-address-uint256-[`++_safeTransfer++`]] +:_safeTransfer: pass:normal[xref:#ERC721-_safeTransfer-address-address-uint256-bytes-[`++_safeTransfer++`]] +:_approve: pass:normal[xref:#ERC721-_approve-address-uint256-address-[`++_approve++`]] +:_approve: pass:normal[xref:#ERC721-_approve-address-uint256-address-bool-[`++_approve++`]] +:_setApprovalForAll: pass:normal[xref:#ERC721-_setApprovalForAll-address-address-bool-[`++_setApprovalForAll++`]] +:_requireOwned: pass:normal[xref:#ERC721-_requireOwned-uint256-[`++_requireOwned++`]] + +[.contract] +[[ERC721]] +=== `++ERC721++` link:https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v5.0.0-rc.0/contracts/token/ERC721/ERC721.sol[{github-icon},role=heading-link] + +[.hljs-theme-light.nopadding] +```solidity +import "@openzeppelin/contracts/token/ERC721/ERC721.sol"; +``` + +Implementation of https://eips.ethereum.org/EIPS/eip-721[ERC721] Non-Fungible Token Standard, including +the Metadata extension, but not including the Enumerable extension, which is available separately as +{ERC721Enumerable}. + +[.contract-index] +.Functions +-- +* {xref-ERC721-constructor-string-string-}[`++constructor(name_, symbol_)++`] +* {xref-ERC721-supportsInterface-bytes4-}[`++supportsInterface(interfaceId)++`] +* {xref-ERC721-balanceOf-address-}[`++balanceOf(owner)++`] +* {xref-ERC721-ownerOf-uint256-}[`++ownerOf(tokenId)++`] +* {xref-ERC721-name--}[`++name()++`] +* {xref-ERC721-symbol--}[`++symbol()++`] +* {xref-ERC721-tokenURI-uint256-}[`++tokenURI(tokenId)++`] +* {xref-ERC721-_baseURI--}[`++_baseURI()++`] +* {xref-ERC721-approve-address-uint256-}[`++approve(to, tokenId)++`] +* {xref-ERC721-getApproved-uint256-}[`++getApproved(tokenId)++`] +* {xref-ERC721-setApprovalForAll-address-bool-}[`++setApprovalForAll(operator, approved)++`] +* {xref-ERC721-isApprovedForAll-address-address-}[`++isApprovedForAll(owner, operator)++`] +* {xref-ERC721-transferFrom-address-address-uint256-}[`++transferFrom(from, to, tokenId)++`] +* {xref-ERC721-safeTransferFrom-address-address-uint256-}[`++safeTransferFrom(from, to, tokenId)++`] +* {xref-ERC721-safeTransferFrom-address-address-uint256-bytes-}[`++safeTransferFrom(from, to, tokenId, data)++`] +* {xref-ERC721-_ownerOf-uint256-}[`++_ownerOf(tokenId)++`] +* {xref-ERC721-_getApproved-uint256-}[`++_getApproved(tokenId)++`] +* {xref-ERC721-_isAuthorized-address-address-uint256-}[`++_isAuthorized(owner, spender, tokenId)++`] +* {xref-ERC721-_checkAuthorized-address-address-uint256-}[`++_checkAuthorized(owner, spender, tokenId)++`] +* {xref-ERC721-_increaseBalance-address-uint128-}[`++_increaseBalance(account, value)++`] +* {xref-ERC721-_update-address-uint256-address-}[`++_update(to, tokenId, auth)++`] +* {xref-ERC721-_mint-address-uint256-}[`++_mint(to, tokenId)++`] +* {xref-ERC721-_safeMint-address-uint256-}[`++_safeMint(to, tokenId)++`] +* {xref-ERC721-_safeMint-address-uint256-bytes-}[`++_safeMint(to, tokenId, data)++`] +* {xref-ERC721-_burn-uint256-}[`++_burn(tokenId)++`] +* {xref-ERC721-_transfer-address-address-uint256-}[`++_transfer(from, to, tokenId)++`] +* {xref-ERC721-_safeTransfer-address-address-uint256-}[`++_safeTransfer(from, to, tokenId)++`] +* {xref-ERC721-_safeTransfer-address-address-uint256-bytes-}[`++_safeTransfer(from, to, tokenId, data)++`] +* {xref-ERC721-_approve-address-uint256-address-}[`++_approve(to, tokenId, auth)++`] +* {xref-ERC721-_approve-address-uint256-address-bool-}[`++_approve(to, tokenId, auth, emitEvent)++`] +* {xref-ERC721-_setApprovalForAll-address-address-bool-}[`++_setApprovalForAll(owner, operator, approved)++`] +* {xref-ERC721-_requireOwned-uint256-}[`++_requireOwned(tokenId)++`] + +[.contract-subindex-inherited] +.IERC721Errors + +[.contract-subindex-inherited] +.IERC721Metadata + +[.contract-subindex-inherited] +.IERC721 + +[.contract-subindex-inherited] +.ERC165 + +[.contract-subindex-inherited] +.IERC165 + +-- + +[.contract-index] +.Events +-- + +[.contract-subindex-inherited] +.IERC721Errors + +[.contract-subindex-inherited] +.IERC721Metadata + +[.contract-subindex-inherited] +.IERC721 +* {xref-IERC721-Transfer-address-address-uint256-}[`++Transfer(from, to, tokenId)++`] +* {xref-IERC721-Approval-address-address-uint256-}[`++Approval(owner, approved, tokenId)++`] +* {xref-IERC721-ApprovalForAll-address-address-bool-}[`++ApprovalForAll(owner, operator, approved)++`] + +[.contract-subindex-inherited] +.ERC165 + +[.contract-subindex-inherited] +.IERC165 + +-- + +[.contract-index] +.Errors +-- + +[.contract-subindex-inherited] +.IERC721Errors +* {xref-IERC721Errors-ERC721InvalidOwner-address-}[`++ERC721InvalidOwner(owner)++`] +* {xref-IERC721Errors-ERC721NonexistentToken-uint256-}[`++ERC721NonexistentToken(tokenId)++`] +* {xref-IERC721Errors-ERC721IncorrectOwner-address-uint256-address-}[`++ERC721IncorrectOwner(sender, tokenId, owner)++`] +* {xref-IERC721Errors-ERC721InvalidSender-address-}[`++ERC721InvalidSender(sender)++`] +* {xref-IERC721Errors-ERC721InvalidReceiver-address-}[`++ERC721InvalidReceiver(receiver)++`] +* {xref-IERC721Errors-ERC721InsufficientApproval-address-uint256-}[`++ERC721InsufficientApproval(operator, tokenId)++`] +* {xref-IERC721Errors-ERC721InvalidApprover-address-}[`++ERC721InvalidApprover(approver)++`] +* {xref-IERC721Errors-ERC721InvalidOperator-address-}[`++ERC721InvalidOperator(operator)++`] + +[.contract-subindex-inherited] +.IERC721Metadata + +[.contract-subindex-inherited] +.IERC721 + +[.contract-subindex-inherited] +.ERC165 + +[.contract-subindex-inherited] +.IERC165 + +-- + +[.contract-item] +[[ERC721-constructor-string-string-]] +==== `[.contract-item-name]#++constructor++#++(string name_, string symbol_)++` [.item-kind]#internal# + +Initializes the contract by setting a `name` and a `symbol` to the token collection. + +[.contract-item] +[[ERC721-supportsInterface-bytes4-]] +==== `[.contract-item-name]#++supportsInterface++#++(bytes4 interfaceId) → bool++` [.item-kind]#public# + +See {IERC165-supportsInterface}. + +[.contract-item] +[[ERC721-balanceOf-address-]] +==== `[.contract-item-name]#++balanceOf++#++(address owner) → uint256++` [.item-kind]#public# + +See {IERC721-balanceOf}. + +[.contract-item] +[[ERC721-ownerOf-uint256-]] +==== `[.contract-item-name]#++ownerOf++#++(uint256 tokenId) → address++` [.item-kind]#public# + +See {IERC721-ownerOf}. + +[.contract-item] +[[ERC721-name--]] +==== `[.contract-item-name]#++name++#++() → string++` [.item-kind]#public# + +See {IERC721Metadata-name}. + +[.contract-item] +[[ERC721-symbol--]] +==== `[.contract-item-name]#++symbol++#++() → string++` [.item-kind]#public# + +See {IERC721Metadata-symbol}. + +[.contract-item] +[[ERC721-tokenURI-uint256-]] +==== `[.contract-item-name]#++tokenURI++#++(uint256 tokenId) → string++` [.item-kind]#public# + +See {IERC721Metadata-tokenURI}. + +[.contract-item] +[[ERC721-_baseURI--]] +==== `[.contract-item-name]#++_baseURI++#++() → string++` [.item-kind]#internal# + +Base URI for computing {tokenURI}. If set, the resulting URI for each +token will be the concatenation of the `baseURI` and the `tokenId`. Empty +by default, can be overridden in child contracts. + +[.contract-item] +[[ERC721-approve-address-uint256-]] +==== `[.contract-item-name]#++approve++#++(address to, uint256 tokenId)++` [.item-kind]#public# + +See {IERC721-approve}. + +[.contract-item] +[[ERC721-getApproved-uint256-]] +==== `[.contract-item-name]#++getApproved++#++(uint256 tokenId) → address++` [.item-kind]#public# + +See {IERC721-getApproved}. + +[.contract-item] +[[ERC721-setApprovalForAll-address-bool-]] +==== `[.contract-item-name]#++setApprovalForAll++#++(address operator, bool approved)++` [.item-kind]#public# + +See {IERC721-setApprovalForAll}. + +[.contract-item] +[[ERC721-isApprovedForAll-address-address-]] +==== `[.contract-item-name]#++isApprovedForAll++#++(address owner, address operator) → bool++` [.item-kind]#public# + +See {IERC721-isApprovedForAll}. + +[.contract-item] +[[ERC721-transferFrom-address-address-uint256-]] +==== `[.contract-item-name]#++transferFrom++#++(address from, address to, uint256 tokenId)++` [.item-kind]#public# + +See {IERC721-transferFrom}. + +[.contract-item] +[[ERC721-safeTransferFrom-address-address-uint256-]] +==== `[.contract-item-name]#++safeTransferFrom++#++(address from, address to, uint256 tokenId)++` [.item-kind]#public# + +See {IERC721-safeTransferFrom}. + +[.contract-item] +[[ERC721-safeTransferFrom-address-address-uint256-bytes-]] +==== `[.contract-item-name]#++safeTransferFrom++#++(address from, address to, uint256 tokenId, bytes data)++` [.item-kind]#public# + +See {IERC721-safeTransferFrom}. + +[.contract-item] +[[ERC721-_ownerOf-uint256-]] +==== `[.contract-item-name]#++_ownerOf++#++(uint256 tokenId) → address++` [.item-kind]#internal# + +Returns the owner of the `tokenId`. Does NOT revert if token doesn't exist + +IMPORTANT: Any overrides to this function that add ownership of tokens not tracked by the +core ERC721 logic MUST be matched with the use of {_increaseBalance} to keep balances +consistent with ownership. The invariant to preserve is that for any address `a` the value returned by +`balanceOf(a)` must be equal to the number of tokens such that `_ownerOf(tokenId)` is `a`. + +[.contract-item] +[[ERC721-_getApproved-uint256-]] +==== `[.contract-item-name]#++_getApproved++#++(uint256 tokenId) → address++` [.item-kind]#internal# + +Returns the approved address for `tokenId`. Returns 0 if `tokenId` is not minted. + +[.contract-item] +[[ERC721-_isAuthorized-address-address-uint256-]] +==== `[.contract-item-name]#++_isAuthorized++#++(address owner, address spender, uint256 tokenId) → bool++` [.item-kind]#internal# + +Returns whether `spender` is allowed to manage `owner`'s tokens, or `tokenId` in +particular (ignoring whether it is owned by `owner`). + +WARNING: This function assumes that `owner` is the actual owner of `tokenId` and does not verify this +assumption. + +[.contract-item] +[[ERC721-_checkAuthorized-address-address-uint256-]] +==== `[.contract-item-name]#++_checkAuthorized++#++(address owner, address spender, uint256 tokenId)++` [.item-kind]#internal# + +Checks if `spender` can operate on `tokenId`, assuming the provided `owner` is the actual owner. +Reverts if `spender` does not have approval from the provided `owner` for the given token or for all its assets +the `spender` for the specific `tokenId`. + +WARNING: This function assumes that `owner` is the actual owner of `tokenId` and does not verify this +assumption. + +[.contract-item] +[[ERC721-_increaseBalance-address-uint128-]] +==== `[.contract-item-name]#++_increaseBalance++#++(address account, uint128 value)++` [.item-kind]#internal# + +Unsafe write access to the balances, used by extensions that "mint" tokens using an {ownerOf} override. + +NOTE: the value is limited to type(uint128).max. This protect against _balance overflow. It is unrealistic that +a uint256 would ever overflow from increments when these increments are bounded to uint128 values. + +WARNING: Increasing an account's balance using this function tends to be paired with an override of the +{_ownerOf} function to resolve the ownership of the corresponding tokens so that balances and ownership +remain consistent with one another. + +[.contract-item] +[[ERC721-_update-address-uint256-address-]] +==== `[.contract-item-name]#++_update++#++(address to, uint256 tokenId, address auth) → address++` [.item-kind]#internal# + +Transfers `tokenId` from its current owner to `to`, or alternatively mints (or burns) if the current owner +(or `to`) is the zero address. Returns the owner of the `tokenId` before the update. + +The `auth` argument is optional. If the value passed is non 0, then this function will check that +`auth` is either the owner of the token, or approved to operate on the token (by the owner). + +Emits a {Transfer} event. + +NOTE: If overriding this function in a way that tracks balances, see also {_increaseBalance}. + +[.contract-item] +[[ERC721-_mint-address-uint256-]] +==== `[.contract-item-name]#++_mint++#++(address to, uint256 tokenId)++` [.item-kind]#internal# + +Mints `tokenId` and transfers it to `to`. + +WARNING: Usage of this method is discouraged, use {_safeMint} whenever possible + +Requirements: + +- `tokenId` must not exist. +- `to` cannot be the zero address. + +Emits a {Transfer} event. + +[.contract-item] +[[ERC721-_safeMint-address-uint256-]] +==== `[.contract-item-name]#++_safeMint++#++(address to, uint256 tokenId)++` [.item-kind]#internal# + +Mints `tokenId`, transfers it to `to` and checks for `to` acceptance. + +Requirements: + +- `tokenId` must not exist. +- If `to` refers to a smart contract, it must implement {IERC721Receiver-onERC721Received}, which is called upon a safe transfer. + +Emits a {Transfer} event. + +[.contract-item] +[[ERC721-_safeMint-address-uint256-bytes-]] +==== `[.contract-item-name]#++_safeMint++#++(address to, uint256 tokenId, bytes data)++` [.item-kind]#internal# + +Same as {xref-ERC721-_safeMint-address-uint256-}[`_safeMint`], with an additional `data` parameter which is +forwarded in {IERC721Receiver-onERC721Received} to contract recipients. + +[.contract-item] +[[ERC721-_burn-uint256-]] +==== `[.contract-item-name]#++_burn++#++(uint256 tokenId)++` [.item-kind]#internal# + +Destroys `tokenId`. +The approval is cleared when the token is burned. +This is an internal function that does not check if the sender is authorized to operate on the token. + +Requirements: + +- `tokenId` must exist. + +Emits a {Transfer} event. + +[.contract-item] +[[ERC721-_transfer-address-address-uint256-]] +==== `[.contract-item-name]#++_transfer++#++(address from, address to, uint256 tokenId)++` [.item-kind]#internal# + +Transfers `tokenId` from `from` to `to`. + As opposed to {transferFrom}, this imposes no restrictions on msg.sender. + +Requirements: + +- `to` cannot be the zero address. +- `tokenId` token must be owned by `from`. + +Emits a {Transfer} event. + +[.contract-item] +[[ERC721-_safeTransfer-address-address-uint256-]] +==== `[.contract-item-name]#++_safeTransfer++#++(address from, address to, uint256 tokenId)++` [.item-kind]#internal# + +Safely transfers `tokenId` token from `from` to `to`, checking that contract recipients +are aware of the ERC721 standard to prevent tokens from being forever locked. + +`data` is additional data, it has no specified format and it is sent in call to `to`. + +This internal function is like {safeTransferFrom} in the sense that it invokes +{IERC721Receiver-onERC721Received} on the receiver, and can be used to e.g. +implement alternative mechanisms to perform token transfer, such as signature-based. + +Requirements: + +- `tokenId` token must exist and be owned by `from`. +- `to` cannot be the zero address. +- `from` cannot be the zero address. +- If `to` refers to a smart contract, it must implement {IERC721Receiver-onERC721Received}, which is called upon a safe transfer. + +Emits a {Transfer} event. + +[.contract-item] +[[ERC721-_safeTransfer-address-address-uint256-bytes-]] +==== `[.contract-item-name]#++_safeTransfer++#++(address from, address to, uint256 tokenId, bytes data)++` [.item-kind]#internal# + +Same as {xref-ERC721-_safeTransfer-address-address-uint256-}[`_safeTransfer`], with an additional `data` parameter which is +forwarded in {IERC721Receiver-onERC721Received} to contract recipients. + +[.contract-item] +[[ERC721-_approve-address-uint256-address-]] +==== `[.contract-item-name]#++_approve++#++(address to, uint256 tokenId, address auth)++` [.item-kind]#internal# + +Approve `to` to operate on `tokenId` + +The `auth` argument is optional. If the value passed is non 0, then this function will check that `auth` is +either the owner of the token, or approved to operate on all tokens held by this owner. + +Emits an {Approval} event. + +Overrides to this logic should be done to the variant with an additional `bool emitEvent` argument. + +[.contract-item] +[[ERC721-_approve-address-uint256-address-bool-]] +==== `[.contract-item-name]#++_approve++#++(address to, uint256 tokenId, address auth, bool emitEvent)++` [.item-kind]#internal# + +Variant of `_approve` with an optional flag to enable or disable the {Approval} event. The event is not +emitted in the context of transfers. + +[.contract-item] +[[ERC721-_setApprovalForAll-address-address-bool-]] +==== `[.contract-item-name]#++_setApprovalForAll++#++(address owner, address operator, bool approved)++` [.item-kind]#internal# + +Approve `operator` to operate on all of `owner` tokens + +Requirements: +- operator can't be the address zero. + +Emits an {ApprovalForAll} event. + +[.contract-item] +[[ERC721-_requireOwned-uint256-]] +==== `[.contract-item-name]#++_requireOwned++#++(uint256 tokenId) → address++` [.item-kind]#internal# + +Reverts if the `tokenId` doesn't have a current owner (it hasn't been minted, or it has been burned). +Returns the owner. + +Overrides to ownership logic should be done to {_ownerOf}. + +:ERC721OutOfBoundsIndex: pass:normal[xref:#ERC721Enumerable-ERC721OutOfBoundsIndex-address-uint256-[`++ERC721OutOfBoundsIndex++`]] +:ERC721EnumerableForbiddenBatchMint: pass:normal[xref:#ERC721Enumerable-ERC721EnumerableForbiddenBatchMint--[`++ERC721EnumerableForbiddenBatchMint++`]] +:supportsInterface: pass:normal[xref:#ERC721Enumerable-supportsInterface-bytes4-[`++supportsInterface++`]] +:tokenOfOwnerByIndex: pass:normal[xref:#ERC721Enumerable-tokenOfOwnerByIndex-address-uint256-[`++tokenOfOwnerByIndex++`]] +:totalSupply: pass:normal[xref:#ERC721Enumerable-totalSupply--[`++totalSupply++`]] +:tokenByIndex: pass:normal[xref:#ERC721Enumerable-tokenByIndex-uint256-[`++tokenByIndex++`]] +:_update: pass:normal[xref:#ERC721Enumerable-_update-address-uint256-address-[`++_update++`]] +:_increaseBalance: pass:normal[xref:#ERC721Enumerable-_increaseBalance-address-uint128-[`++_increaseBalance++`]] + +[.contract] +[[ERC721Enumerable]] +=== `++ERC721Enumerable++` link:https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v5.0.0-rc.0/contracts/token/ERC721/extensions/ERC721Enumerable.sol[{github-icon},role=heading-link] + +[.hljs-theme-light.nopadding] +```solidity +import "@openzeppelin/contracts/token/ERC721/extensions/ERC721Enumerable.sol"; +``` + +This implements an optional extension of {ERC721} defined in the EIP that adds enumerability +of all the token ids in the contract as well as all token ids owned by each account. + +CAUTION: `ERC721` extensions that implement custom `balanceOf` logic, such as `ERC721Consecutive`, +interfere with enumerability and should not be used together with `ERC721Enumerable`. + +[.contract-index] +.Functions +-- +* {xref-ERC721Enumerable-supportsInterface-bytes4-}[`++supportsInterface(interfaceId)++`] +* {xref-ERC721Enumerable-tokenOfOwnerByIndex-address-uint256-}[`++tokenOfOwnerByIndex(owner, index)++`] +* {xref-ERC721Enumerable-totalSupply--}[`++totalSupply()++`] +* {xref-ERC721Enumerable-tokenByIndex-uint256-}[`++tokenByIndex(index)++`] +* {xref-ERC721Enumerable-_update-address-uint256-address-}[`++_update(to, tokenId, auth)++`] +* {xref-ERC721Enumerable-_increaseBalance-address-uint128-}[`++_increaseBalance(account, amount)++`] + +[.contract-subindex-inherited] +.IERC721Enumerable + +[.contract-subindex-inherited] +.ERC721 +* {xref-ERC721-balanceOf-address-}[`++balanceOf(owner)++`] +* {xref-ERC721-ownerOf-uint256-}[`++ownerOf(tokenId)++`] +* {xref-ERC721-name--}[`++name()++`] +* {xref-ERC721-symbol--}[`++symbol()++`] +* {xref-ERC721-tokenURI-uint256-}[`++tokenURI(tokenId)++`] +* {xref-ERC721-_baseURI--}[`++_baseURI()++`] +* {xref-ERC721-approve-address-uint256-}[`++approve(to, tokenId)++`] +* {xref-ERC721-getApproved-uint256-}[`++getApproved(tokenId)++`] +* {xref-ERC721-setApprovalForAll-address-bool-}[`++setApprovalForAll(operator, approved)++`] +* {xref-ERC721-isApprovedForAll-address-address-}[`++isApprovedForAll(owner, operator)++`] +* {xref-ERC721-transferFrom-address-address-uint256-}[`++transferFrom(from, to, tokenId)++`] +* {xref-ERC721-safeTransferFrom-address-address-uint256-}[`++safeTransferFrom(from, to, tokenId)++`] +* {xref-ERC721-safeTransferFrom-address-address-uint256-bytes-}[`++safeTransferFrom(from, to, tokenId, data)++`] +* {xref-ERC721-_ownerOf-uint256-}[`++_ownerOf(tokenId)++`] +* {xref-ERC721-_getApproved-uint256-}[`++_getApproved(tokenId)++`] +* {xref-ERC721-_isAuthorized-address-address-uint256-}[`++_isAuthorized(owner, spender, tokenId)++`] +* {xref-ERC721-_checkAuthorized-address-address-uint256-}[`++_checkAuthorized(owner, spender, tokenId)++`] +* {xref-ERC721-_mint-address-uint256-}[`++_mint(to, tokenId)++`] +* {xref-ERC721-_safeMint-address-uint256-}[`++_safeMint(to, tokenId)++`] +* {xref-ERC721-_safeMint-address-uint256-bytes-}[`++_safeMint(to, tokenId, data)++`] +* {xref-ERC721-_burn-uint256-}[`++_burn(tokenId)++`] +* {xref-ERC721-_transfer-address-address-uint256-}[`++_transfer(from, to, tokenId)++`] +* {xref-ERC721-_safeTransfer-address-address-uint256-}[`++_safeTransfer(from, to, tokenId)++`] +* {xref-ERC721-_safeTransfer-address-address-uint256-bytes-}[`++_safeTransfer(from, to, tokenId, data)++`] +* {xref-ERC721-_approve-address-uint256-address-}[`++_approve(to, tokenId, auth)++`] +* {xref-ERC721-_approve-address-uint256-address-bool-}[`++_approve(to, tokenId, auth, emitEvent)++`] +* {xref-ERC721-_setApprovalForAll-address-address-bool-}[`++_setApprovalForAll(owner, operator, approved)++`] +* {xref-ERC721-_requireOwned-uint256-}[`++_requireOwned(tokenId)++`] + +[.contract-subindex-inherited] +.IERC721Errors + +[.contract-subindex-inherited] +.IERC721Metadata + +[.contract-subindex-inherited] +.IERC721 + +[.contract-subindex-inherited] +.ERC165 + +[.contract-subindex-inherited] +.IERC165 + +-- + +[.contract-index] +.Events +-- + +[.contract-subindex-inherited] +.IERC721Enumerable + +[.contract-subindex-inherited] +.ERC721 + +[.contract-subindex-inherited] +.IERC721Errors + +[.contract-subindex-inherited] +.IERC721Metadata + +[.contract-subindex-inherited] +.IERC721 +* {xref-IERC721-Transfer-address-address-uint256-}[`++Transfer(from, to, tokenId)++`] +* {xref-IERC721-Approval-address-address-uint256-}[`++Approval(owner, approved, tokenId)++`] +* {xref-IERC721-ApprovalForAll-address-address-bool-}[`++ApprovalForAll(owner, operator, approved)++`] + +[.contract-subindex-inherited] +.ERC165 + +[.contract-subindex-inherited] +.IERC165 + +-- + +[.contract-index] +.Errors +-- +* {xref-ERC721Enumerable-ERC721OutOfBoundsIndex-address-uint256-}[`++ERC721OutOfBoundsIndex(owner, index)++`] +* {xref-ERC721Enumerable-ERC721EnumerableForbiddenBatchMint--}[`++ERC721EnumerableForbiddenBatchMint()++`] + +[.contract-subindex-inherited] +.IERC721Enumerable + +[.contract-subindex-inherited] +.ERC721 + +[.contract-subindex-inherited] +.IERC721Errors +* {xref-IERC721Errors-ERC721InvalidOwner-address-}[`++ERC721InvalidOwner(owner)++`] +* {xref-IERC721Errors-ERC721NonexistentToken-uint256-}[`++ERC721NonexistentToken(tokenId)++`] +* {xref-IERC721Errors-ERC721IncorrectOwner-address-uint256-address-}[`++ERC721IncorrectOwner(sender, tokenId, owner)++`] +* {xref-IERC721Errors-ERC721InvalidSender-address-}[`++ERC721InvalidSender(sender)++`] +* {xref-IERC721Errors-ERC721InvalidReceiver-address-}[`++ERC721InvalidReceiver(receiver)++`] +* {xref-IERC721Errors-ERC721InsufficientApproval-address-uint256-}[`++ERC721InsufficientApproval(operator, tokenId)++`] +* {xref-IERC721Errors-ERC721InvalidApprover-address-}[`++ERC721InvalidApprover(approver)++`] +* {xref-IERC721Errors-ERC721InvalidOperator-address-}[`++ERC721InvalidOperator(operator)++`] + +[.contract-subindex-inherited] +.IERC721Metadata + +[.contract-subindex-inherited] +.IERC721 + +[.contract-subindex-inherited] +.ERC165 + +[.contract-subindex-inherited] +.IERC165 + +-- + +[.contract-item] +[[ERC721Enumerable-supportsInterface-bytes4-]] +==== `[.contract-item-name]#++supportsInterface++#++(bytes4 interfaceId) → bool++` [.item-kind]#public# + +See {IERC165-supportsInterface}. + +[.contract-item] +[[ERC721Enumerable-tokenOfOwnerByIndex-address-uint256-]] +==== `[.contract-item-name]#++tokenOfOwnerByIndex++#++(address owner, uint256 index) → uint256++` [.item-kind]#public# + +See {IERC721Enumerable-tokenOfOwnerByIndex}. + +[.contract-item] +[[ERC721Enumerable-totalSupply--]] +==== `[.contract-item-name]#++totalSupply++#++() → uint256++` [.item-kind]#public# + +See {IERC721Enumerable-totalSupply}. + +[.contract-item] +[[ERC721Enumerable-tokenByIndex-uint256-]] +==== `[.contract-item-name]#++tokenByIndex++#++(uint256 index) → uint256++` [.item-kind]#public# + +See {IERC721Enumerable-tokenByIndex}. + +[.contract-item] +[[ERC721Enumerable-_update-address-uint256-address-]] +==== `[.contract-item-name]#++_update++#++(address to, uint256 tokenId, address auth) → address++` [.item-kind]#internal# + +See {ERC721-_update}. + +[.contract-item] +[[ERC721Enumerable-_increaseBalance-address-uint128-]] +==== `[.contract-item-name]#++_increaseBalance++#++(address account, uint128 amount)++` [.item-kind]#internal# + +[.contract-item] +[[ERC721Enumerable-ERC721OutOfBoundsIndex-address-uint256-]] +==== `[.contract-item-name]#++ERC721OutOfBoundsIndex++#++(address owner, uint256 index)++` [.item-kind]#error# + +An `owner`'s token query was out of bounds for `index`. + +NOTE: The owner being `address(0)` indicates a global out of bounds index. + +[.contract-item] +[[ERC721Enumerable-ERC721EnumerableForbiddenBatchMint--]] +==== `[.contract-item-name]#++ERC721EnumerableForbiddenBatchMint++#++()++` [.item-kind]#error# + +Batch mint is not allowed. + +:onERC721Received: pass:normal[xref:#IERC721Receiver-onERC721Received-address-address-uint256-bytes-[`++onERC721Received++`]] + +[.contract] +[[IERC721Receiver]] +=== `++IERC721Receiver++` link:https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v5.0.0-rc.0/contracts/token/ERC721/IERC721Receiver.sol[{github-icon},role=heading-link] + +[.hljs-theme-light.nopadding] +```solidity +import "@openzeppelin/contracts/token/ERC721/IERC721Receiver.sol"; +``` + +Interface for any contract that wants to support safeTransfers +from ERC721 asset contracts. + +[.contract-index] +.Functions +-- +* {xref-IERC721Receiver-onERC721Received-address-address-uint256-bytes-}[`++onERC721Received(operator, from, tokenId, data)++`] + +-- + +[.contract-item] +[[IERC721Receiver-onERC721Received-address-address-uint256-bytes-]] +==== `[.contract-item-name]#++onERC721Received++#++(address operator, address from, uint256 tokenId, bytes data) → bytes4++` [.item-kind]#external# + +Whenever an {IERC721} `tokenId` token is transferred to this contract via {IERC721-safeTransferFrom} +by `operator` from `from`, this function is called. + +It must return its Solidity selector to confirm the token transfer. +If any other value is returned or the interface is not implemented by the recipient, the transfer will be +reverted. + +The selector can be obtained in Solidity with `IERC721Receiver.onERC721Received.selector`. + +== Extensions + +:_update: pass:normal[xref:#ERC721Pausable-_update-address-uint256-address-[`++_update++`]] + +[.contract] +[[ERC721Pausable]] +=== `++ERC721Pausable++` link:https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v5.0.0-rc.0/contracts/token/ERC721/extensions/ERC721Pausable.sol[{github-icon},role=heading-link] + +[.hljs-theme-light.nopadding] +```solidity +import "@openzeppelin/contracts/token/ERC721/extensions/ERC721Pausable.sol"; +``` + +ERC721 token with pausable token transfers, minting and burning. + +Useful for scenarios such as preventing trades until the end of an evaluation +period, or having an emergency switch for freezing all token transfers in the +event of a large bug. + +IMPORTANT: This contract does not include public pause and unpause functions. In +addition to inheriting this contract, you must define both functions, invoking the +{Pausable-_pause} and {Pausable-_unpause} internal functions, with appropriate +access control, e.g. using {AccessControl} or {Ownable}. Not doing so will +make the contract pause mechanism of the contract unreachable, and thus unusable. + +[.contract-index] +.Functions +-- +* {xref-ERC721Pausable-_update-address-uint256-address-}[`++_update(to, tokenId, auth)++`] + +[.contract-subindex-inherited] +.Pausable +* {xref-Pausable-paused--}[`++paused()++`] +* {xref-Pausable-_requireNotPaused--}[`++_requireNotPaused()++`] +* {xref-Pausable-_requirePaused--}[`++_requirePaused()++`] +* {xref-Pausable-_pause--}[`++_pause()++`] +* {xref-Pausable-_unpause--}[`++_unpause()++`] + +[.contract-subindex-inherited] +.ERC721 +* {xref-ERC721-supportsInterface-bytes4-}[`++supportsInterface(interfaceId)++`] +* {xref-ERC721-balanceOf-address-}[`++balanceOf(owner)++`] +* {xref-ERC721-ownerOf-uint256-}[`++ownerOf(tokenId)++`] +* {xref-ERC721-name--}[`++name()++`] +* {xref-ERC721-symbol--}[`++symbol()++`] +* {xref-ERC721-tokenURI-uint256-}[`++tokenURI(tokenId)++`] +* {xref-ERC721-_baseURI--}[`++_baseURI()++`] +* {xref-ERC721-approve-address-uint256-}[`++approve(to, tokenId)++`] +* {xref-ERC721-getApproved-uint256-}[`++getApproved(tokenId)++`] +* {xref-ERC721-setApprovalForAll-address-bool-}[`++setApprovalForAll(operator, approved)++`] +* {xref-ERC721-isApprovedForAll-address-address-}[`++isApprovedForAll(owner, operator)++`] +* {xref-ERC721-transferFrom-address-address-uint256-}[`++transferFrom(from, to, tokenId)++`] +* {xref-ERC721-safeTransferFrom-address-address-uint256-}[`++safeTransferFrom(from, to, tokenId)++`] +* {xref-ERC721-safeTransferFrom-address-address-uint256-bytes-}[`++safeTransferFrom(from, to, tokenId, data)++`] +* {xref-ERC721-_ownerOf-uint256-}[`++_ownerOf(tokenId)++`] +* {xref-ERC721-_getApproved-uint256-}[`++_getApproved(tokenId)++`] +* {xref-ERC721-_isAuthorized-address-address-uint256-}[`++_isAuthorized(owner, spender, tokenId)++`] +* {xref-ERC721-_checkAuthorized-address-address-uint256-}[`++_checkAuthorized(owner, spender, tokenId)++`] +* {xref-ERC721-_increaseBalance-address-uint128-}[`++_increaseBalance(account, value)++`] +* {xref-ERC721-_mint-address-uint256-}[`++_mint(to, tokenId)++`] +* {xref-ERC721-_safeMint-address-uint256-}[`++_safeMint(to, tokenId)++`] +* {xref-ERC721-_safeMint-address-uint256-bytes-}[`++_safeMint(to, tokenId, data)++`] +* {xref-ERC721-_burn-uint256-}[`++_burn(tokenId)++`] +* {xref-ERC721-_transfer-address-address-uint256-}[`++_transfer(from, to, tokenId)++`] +* {xref-ERC721-_safeTransfer-address-address-uint256-}[`++_safeTransfer(from, to, tokenId)++`] +* {xref-ERC721-_safeTransfer-address-address-uint256-bytes-}[`++_safeTransfer(from, to, tokenId, data)++`] +* {xref-ERC721-_approve-address-uint256-address-}[`++_approve(to, tokenId, auth)++`] +* {xref-ERC721-_approve-address-uint256-address-bool-}[`++_approve(to, tokenId, auth, emitEvent)++`] +* {xref-ERC721-_setApprovalForAll-address-address-bool-}[`++_setApprovalForAll(owner, operator, approved)++`] +* {xref-ERC721-_requireOwned-uint256-}[`++_requireOwned(tokenId)++`] + +[.contract-subindex-inherited] +.IERC721Errors + +[.contract-subindex-inherited] +.IERC721Metadata + +[.contract-subindex-inherited] +.IERC721 + +[.contract-subindex-inherited] +.ERC165 + +[.contract-subindex-inherited] +.IERC165 + +-- + +[.contract-index] +.Events +-- + +[.contract-subindex-inherited] +.Pausable +* {xref-Pausable-Paused-address-}[`++Paused(account)++`] +* {xref-Pausable-Unpaused-address-}[`++Unpaused(account)++`] + +[.contract-subindex-inherited] +.ERC721 + +[.contract-subindex-inherited] +.IERC721Errors + +[.contract-subindex-inherited] +.IERC721Metadata + +[.contract-subindex-inherited] +.IERC721 +* {xref-IERC721-Transfer-address-address-uint256-}[`++Transfer(from, to, tokenId)++`] +* {xref-IERC721-Approval-address-address-uint256-}[`++Approval(owner, approved, tokenId)++`] +* {xref-IERC721-ApprovalForAll-address-address-bool-}[`++ApprovalForAll(owner, operator, approved)++`] + +[.contract-subindex-inherited] +.ERC165 + +[.contract-subindex-inherited] +.IERC165 + +-- + +[.contract-index] +.Errors +-- + +[.contract-subindex-inherited] +.Pausable +* {xref-Pausable-EnforcedPause--}[`++EnforcedPause()++`] +* {xref-Pausable-ExpectedPause--}[`++ExpectedPause()++`] + +[.contract-subindex-inherited] +.ERC721 + +[.contract-subindex-inherited] +.IERC721Errors +* {xref-IERC721Errors-ERC721InvalidOwner-address-}[`++ERC721InvalidOwner(owner)++`] +* {xref-IERC721Errors-ERC721NonexistentToken-uint256-}[`++ERC721NonexistentToken(tokenId)++`] +* {xref-IERC721Errors-ERC721IncorrectOwner-address-uint256-address-}[`++ERC721IncorrectOwner(sender, tokenId, owner)++`] +* {xref-IERC721Errors-ERC721InvalidSender-address-}[`++ERC721InvalidSender(sender)++`] +* {xref-IERC721Errors-ERC721InvalidReceiver-address-}[`++ERC721InvalidReceiver(receiver)++`] +* {xref-IERC721Errors-ERC721InsufficientApproval-address-uint256-}[`++ERC721InsufficientApproval(operator, tokenId)++`] +* {xref-IERC721Errors-ERC721InvalidApprover-address-}[`++ERC721InvalidApprover(approver)++`] +* {xref-IERC721Errors-ERC721InvalidOperator-address-}[`++ERC721InvalidOperator(operator)++`] + +[.contract-subindex-inherited] +.IERC721Metadata + +[.contract-subindex-inherited] +.IERC721 + +[.contract-subindex-inherited] +.ERC165 + +[.contract-subindex-inherited] +.IERC165 + +-- + +[.contract-item] +[[ERC721Pausable-_update-address-uint256-address-]] +==== `[.contract-item-name]#++_update++#++(address to, uint256 tokenId, address auth) → address++` [.item-kind]#internal# + +See {ERC721-_update}. + +Requirements: + +- the contract must not be paused. + +:burn: pass:normal[xref:#ERC721Burnable-burn-uint256-[`++burn++`]] + +[.contract] +[[ERC721Burnable]] +=== `++ERC721Burnable++` link:https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v5.0.0-rc.0/contracts/token/ERC721/extensions/ERC721Burnable.sol[{github-icon},role=heading-link] + +[.hljs-theme-light.nopadding] +```solidity +import "@openzeppelin/contracts/token/ERC721/extensions/ERC721Burnable.sol"; +``` + +ERC721 Token that can be burned (destroyed). + +[.contract-index] +.Functions +-- +* {xref-ERC721Burnable-burn-uint256-}[`++burn(tokenId)++`] + +[.contract-subindex-inherited] +.ERC721 +* {xref-ERC721-supportsInterface-bytes4-}[`++supportsInterface(interfaceId)++`] +* {xref-ERC721-balanceOf-address-}[`++balanceOf(owner)++`] +* {xref-ERC721-ownerOf-uint256-}[`++ownerOf(tokenId)++`] +* {xref-ERC721-name--}[`++name()++`] +* {xref-ERC721-symbol--}[`++symbol()++`] +* {xref-ERC721-tokenURI-uint256-}[`++tokenURI(tokenId)++`] +* {xref-ERC721-_baseURI--}[`++_baseURI()++`] +* {xref-ERC721-approve-address-uint256-}[`++approve(to, tokenId)++`] +* {xref-ERC721-getApproved-uint256-}[`++getApproved(tokenId)++`] +* {xref-ERC721-setApprovalForAll-address-bool-}[`++setApprovalForAll(operator, approved)++`] +* {xref-ERC721-isApprovedForAll-address-address-}[`++isApprovedForAll(owner, operator)++`] +* {xref-ERC721-transferFrom-address-address-uint256-}[`++transferFrom(from, to, tokenId)++`] +* {xref-ERC721-safeTransferFrom-address-address-uint256-}[`++safeTransferFrom(from, to, tokenId)++`] +* {xref-ERC721-safeTransferFrom-address-address-uint256-bytes-}[`++safeTransferFrom(from, to, tokenId, data)++`] +* {xref-ERC721-_ownerOf-uint256-}[`++_ownerOf(tokenId)++`] +* {xref-ERC721-_getApproved-uint256-}[`++_getApproved(tokenId)++`] +* {xref-ERC721-_isAuthorized-address-address-uint256-}[`++_isAuthorized(owner, spender, tokenId)++`] +* {xref-ERC721-_checkAuthorized-address-address-uint256-}[`++_checkAuthorized(owner, spender, tokenId)++`] +* {xref-ERC721-_increaseBalance-address-uint128-}[`++_increaseBalance(account, value)++`] +* {xref-ERC721-_update-address-uint256-address-}[`++_update(to, tokenId, auth)++`] +* {xref-ERC721-_mint-address-uint256-}[`++_mint(to, tokenId)++`] +* {xref-ERC721-_safeMint-address-uint256-}[`++_safeMint(to, tokenId)++`] +* {xref-ERC721-_safeMint-address-uint256-bytes-}[`++_safeMint(to, tokenId, data)++`] +* {xref-ERC721-_burn-uint256-}[`++_burn(tokenId)++`] +* {xref-ERC721-_transfer-address-address-uint256-}[`++_transfer(from, to, tokenId)++`] +* {xref-ERC721-_safeTransfer-address-address-uint256-}[`++_safeTransfer(from, to, tokenId)++`] +* {xref-ERC721-_safeTransfer-address-address-uint256-bytes-}[`++_safeTransfer(from, to, tokenId, data)++`] +* {xref-ERC721-_approve-address-uint256-address-}[`++_approve(to, tokenId, auth)++`] +* {xref-ERC721-_approve-address-uint256-address-bool-}[`++_approve(to, tokenId, auth, emitEvent)++`] +* {xref-ERC721-_setApprovalForAll-address-address-bool-}[`++_setApprovalForAll(owner, operator, approved)++`] +* {xref-ERC721-_requireOwned-uint256-}[`++_requireOwned(tokenId)++`] + +[.contract-subindex-inherited] +.IERC721Errors + +[.contract-subindex-inherited] +.IERC721Metadata + +[.contract-subindex-inherited] +.IERC721 + +[.contract-subindex-inherited] +.ERC165 + +[.contract-subindex-inherited] +.IERC165 + +-- + +[.contract-index] +.Events +-- + +[.contract-subindex-inherited] +.ERC721 + +[.contract-subindex-inherited] +.IERC721Errors + +[.contract-subindex-inherited] +.IERC721Metadata + +[.contract-subindex-inherited] +.IERC721 +* {xref-IERC721-Transfer-address-address-uint256-}[`++Transfer(from, to, tokenId)++`] +* {xref-IERC721-Approval-address-address-uint256-}[`++Approval(owner, approved, tokenId)++`] +* {xref-IERC721-ApprovalForAll-address-address-bool-}[`++ApprovalForAll(owner, operator, approved)++`] + +[.contract-subindex-inherited] +.ERC165 + +[.contract-subindex-inherited] +.IERC165 + +-- + +[.contract-index] +.Errors +-- + +[.contract-subindex-inherited] +.ERC721 + +[.contract-subindex-inherited] +.IERC721Errors +* {xref-IERC721Errors-ERC721InvalidOwner-address-}[`++ERC721InvalidOwner(owner)++`] +* {xref-IERC721Errors-ERC721NonexistentToken-uint256-}[`++ERC721NonexistentToken(tokenId)++`] +* {xref-IERC721Errors-ERC721IncorrectOwner-address-uint256-address-}[`++ERC721IncorrectOwner(sender, tokenId, owner)++`] +* {xref-IERC721Errors-ERC721InvalidSender-address-}[`++ERC721InvalidSender(sender)++`] +* {xref-IERC721Errors-ERC721InvalidReceiver-address-}[`++ERC721InvalidReceiver(receiver)++`] +* {xref-IERC721Errors-ERC721InsufficientApproval-address-uint256-}[`++ERC721InsufficientApproval(operator, tokenId)++`] +* {xref-IERC721Errors-ERC721InvalidApprover-address-}[`++ERC721InvalidApprover(approver)++`] +* {xref-IERC721Errors-ERC721InvalidOperator-address-}[`++ERC721InvalidOperator(operator)++`] + +[.contract-subindex-inherited] +.IERC721Metadata + +[.contract-subindex-inherited] +.IERC721 + +[.contract-subindex-inherited] +.ERC165 + +[.contract-subindex-inherited] +.IERC165 + +-- + +[.contract-item] +[[ERC721Burnable-burn-uint256-]] +==== `[.contract-item-name]#++burn++#++(uint256 tokenId)++` [.item-kind]#public# + +Burns `tokenId`. See {ERC721-_burn}. + +Requirements: + +- The caller must own `tokenId` or be an approved operator. + +:ERC721ForbiddenBatchMint: pass:normal[xref:#ERC721Consecutive-ERC721ForbiddenBatchMint--[`++ERC721ForbiddenBatchMint++`]] +:ERC721ExceededMaxBatchMint: pass:normal[xref:#ERC721Consecutive-ERC721ExceededMaxBatchMint-uint256-uint256-[`++ERC721ExceededMaxBatchMint++`]] +:ERC721ForbiddenMint: pass:normal[xref:#ERC721Consecutive-ERC721ForbiddenMint--[`++ERC721ForbiddenMint++`]] +:ERC721ForbiddenBatchBurn: pass:normal[xref:#ERC721Consecutive-ERC721ForbiddenBatchBurn--[`++ERC721ForbiddenBatchBurn++`]] +:_maxBatchSize: pass:normal[xref:#ERC721Consecutive-_maxBatchSize--[`++_maxBatchSize++`]] +:_ownerOf: pass:normal[xref:#ERC721Consecutive-_ownerOf-uint256-[`++_ownerOf++`]] +:_mintConsecutive: pass:normal[xref:#ERC721Consecutive-_mintConsecutive-address-uint96-[`++_mintConsecutive++`]] +:_update: pass:normal[xref:#ERC721Consecutive-_update-address-uint256-address-[`++_update++`]] +:_firstConsecutiveId: pass:normal[xref:#ERC721Consecutive-_firstConsecutiveId--[`++_firstConsecutiveId++`]] + +[.contract] +[[ERC721Consecutive]] +=== `++ERC721Consecutive++` link:https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v5.0.0-rc.0/contracts/token/ERC721/extensions/ERC721Consecutive.sol[{github-icon},role=heading-link] + +[.hljs-theme-light.nopadding] +```solidity +import "@openzeppelin/contracts/token/ERC721/extensions/ERC721Consecutive.sol"; +``` + +Implementation of the ERC2309 "Consecutive Transfer Extension" as defined in +https://eips.ethereum.org/EIPS/eip-2309[EIP-2309]. + +This extension allows the minting of large batches of tokens, during contract construction only. For upgradeable +contracts this implies that batch minting is only available during proxy deployment, and not in subsequent upgrades. +These batches are limited to 5000 tokens at a time by default to accommodate off-chain indexers. + +Using this extension removes the ability to mint single tokens during contract construction. This ability is +regained after construction. During construction, only batch minting is allowed. + +IMPORTANT: This extension does not call the {_update} function for tokens minted in batch. Any logic added to this +function through overrides will not be triggered when token are minted in batch. You may want to also override +{_increaseBalance} or {_mintConsecutive} to account for these mints. + +IMPORTANT: When overriding {_mintConsecutive}, be careful about call ordering. {ownerOf} may return invalid +values during the {_mintConsecutive} execution if the super call is not called first. To be safe, execute the +super call before your custom logic. + +[.contract-index] +.Functions +-- +* {xref-ERC721Consecutive-_maxBatchSize--}[`++_maxBatchSize()++`] +* {xref-ERC721Consecutive-_ownerOf-uint256-}[`++_ownerOf(tokenId)++`] +* {xref-ERC721Consecutive-_mintConsecutive-address-uint96-}[`++_mintConsecutive(to, batchSize)++`] +* {xref-ERC721Consecutive-_update-address-uint256-address-}[`++_update(to, tokenId, auth)++`] +* {xref-ERC721Consecutive-_firstConsecutiveId--}[`++_firstConsecutiveId()++`] + +[.contract-subindex-inherited] +.ERC721 +* {xref-ERC721-supportsInterface-bytes4-}[`++supportsInterface(interfaceId)++`] +* {xref-ERC721-balanceOf-address-}[`++balanceOf(owner)++`] +* {xref-ERC721-ownerOf-uint256-}[`++ownerOf(tokenId)++`] +* {xref-ERC721-name--}[`++name()++`] +* {xref-ERC721-symbol--}[`++symbol()++`] +* {xref-ERC721-tokenURI-uint256-}[`++tokenURI(tokenId)++`] +* {xref-ERC721-_baseURI--}[`++_baseURI()++`] +* {xref-ERC721-approve-address-uint256-}[`++approve(to, tokenId)++`] +* {xref-ERC721-getApproved-uint256-}[`++getApproved(tokenId)++`] +* {xref-ERC721-setApprovalForAll-address-bool-}[`++setApprovalForAll(operator, approved)++`] +* {xref-ERC721-isApprovedForAll-address-address-}[`++isApprovedForAll(owner, operator)++`] +* {xref-ERC721-transferFrom-address-address-uint256-}[`++transferFrom(from, to, tokenId)++`] +* {xref-ERC721-safeTransferFrom-address-address-uint256-}[`++safeTransferFrom(from, to, tokenId)++`] +* {xref-ERC721-safeTransferFrom-address-address-uint256-bytes-}[`++safeTransferFrom(from, to, tokenId, data)++`] +* {xref-ERC721-_getApproved-uint256-}[`++_getApproved(tokenId)++`] +* {xref-ERC721-_isAuthorized-address-address-uint256-}[`++_isAuthorized(owner, spender, tokenId)++`] +* {xref-ERC721-_checkAuthorized-address-address-uint256-}[`++_checkAuthorized(owner, spender, tokenId)++`] +* {xref-ERC721-_increaseBalance-address-uint128-}[`++_increaseBalance(account, value)++`] +* {xref-ERC721-_mint-address-uint256-}[`++_mint(to, tokenId)++`] +* {xref-ERC721-_safeMint-address-uint256-}[`++_safeMint(to, tokenId)++`] +* {xref-ERC721-_safeMint-address-uint256-bytes-}[`++_safeMint(to, tokenId, data)++`] +* {xref-ERC721-_burn-uint256-}[`++_burn(tokenId)++`] +* {xref-ERC721-_transfer-address-address-uint256-}[`++_transfer(from, to, tokenId)++`] +* {xref-ERC721-_safeTransfer-address-address-uint256-}[`++_safeTransfer(from, to, tokenId)++`] +* {xref-ERC721-_safeTransfer-address-address-uint256-bytes-}[`++_safeTransfer(from, to, tokenId, data)++`] +* {xref-ERC721-_approve-address-uint256-address-}[`++_approve(to, tokenId, auth)++`] +* {xref-ERC721-_approve-address-uint256-address-bool-}[`++_approve(to, tokenId, auth, emitEvent)++`] +* {xref-ERC721-_setApprovalForAll-address-address-bool-}[`++_setApprovalForAll(owner, operator, approved)++`] +* {xref-ERC721-_requireOwned-uint256-}[`++_requireOwned(tokenId)++`] + +[.contract-subindex-inherited] +.IERC721Errors + +[.contract-subindex-inherited] +.IERC721Metadata + +[.contract-subindex-inherited] +.IERC721 + +[.contract-subindex-inherited] +.ERC165 + +[.contract-subindex-inherited] +.IERC165 + +[.contract-subindex-inherited] +.IERC2309 + +-- + +[.contract-index] +.Events +-- + +[.contract-subindex-inherited] +.ERC721 + +[.contract-subindex-inherited] +.IERC721Errors + +[.contract-subindex-inherited] +.IERC721Metadata + +[.contract-subindex-inherited] +.IERC721 +* {xref-IERC721-Transfer-address-address-uint256-}[`++Transfer(from, to, tokenId)++`] +* {xref-IERC721-Approval-address-address-uint256-}[`++Approval(owner, approved, tokenId)++`] +* {xref-IERC721-ApprovalForAll-address-address-bool-}[`++ApprovalForAll(owner, operator, approved)++`] + +[.contract-subindex-inherited] +.ERC165 + +[.contract-subindex-inherited] +.IERC165 + +[.contract-subindex-inherited] +.IERC2309 +* {xref-IERC2309-ConsecutiveTransfer-uint256-uint256-address-address-}[`++ConsecutiveTransfer(fromTokenId, toTokenId, fromAddress, toAddress)++`] + +-- + +[.contract-index] +.Errors +-- +* {xref-ERC721Consecutive-ERC721ForbiddenBatchMint--}[`++ERC721ForbiddenBatchMint()++`] +* {xref-ERC721Consecutive-ERC721ExceededMaxBatchMint-uint256-uint256-}[`++ERC721ExceededMaxBatchMint(batchSize, maxBatch)++`] +* {xref-ERC721Consecutive-ERC721ForbiddenMint--}[`++ERC721ForbiddenMint()++`] +* {xref-ERC721Consecutive-ERC721ForbiddenBatchBurn--}[`++ERC721ForbiddenBatchBurn()++`] + +[.contract-subindex-inherited] +.ERC721 + +[.contract-subindex-inherited] +.IERC721Errors +* {xref-IERC721Errors-ERC721InvalidOwner-address-}[`++ERC721InvalidOwner(owner)++`] +* {xref-IERC721Errors-ERC721NonexistentToken-uint256-}[`++ERC721NonexistentToken(tokenId)++`] +* {xref-IERC721Errors-ERC721IncorrectOwner-address-uint256-address-}[`++ERC721IncorrectOwner(sender, tokenId, owner)++`] +* {xref-IERC721Errors-ERC721InvalidSender-address-}[`++ERC721InvalidSender(sender)++`] +* {xref-IERC721Errors-ERC721InvalidReceiver-address-}[`++ERC721InvalidReceiver(receiver)++`] +* {xref-IERC721Errors-ERC721InsufficientApproval-address-uint256-}[`++ERC721InsufficientApproval(operator, tokenId)++`] +* {xref-IERC721Errors-ERC721InvalidApprover-address-}[`++ERC721InvalidApprover(approver)++`] +* {xref-IERC721Errors-ERC721InvalidOperator-address-}[`++ERC721InvalidOperator(operator)++`] + +[.contract-subindex-inherited] +.IERC721Metadata + +[.contract-subindex-inherited] +.IERC721 + +[.contract-subindex-inherited] +.ERC165 + +[.contract-subindex-inherited] +.IERC165 + +[.contract-subindex-inherited] +.IERC2309 + +-- + +[.contract-item] +[[ERC721Consecutive-_maxBatchSize--]] +==== `[.contract-item-name]#++_maxBatchSize++#++() → uint96++` [.item-kind]#internal# + +Maximum size of a batch of consecutive tokens. This is designed to limit stress on off-chain indexing +services that have to record one entry per token, and have protections against "unreasonably large" batches of +tokens. + +NOTE: Overriding the default value of 5000 will not cause on-chain issues, but may result in the asset not being +correctly supported by off-chain indexing services (including marketplaces). + +[.contract-item] +[[ERC721Consecutive-_ownerOf-uint256-]] +==== `[.contract-item-name]#++_ownerOf++#++(uint256 tokenId) → address++` [.item-kind]#internal# + +See {ERC721-_ownerOf}. Override that checks the sequential ownership structure for tokens that have +been minted as part of a batch, and not yet transferred. + +[.contract-item] +[[ERC721Consecutive-_mintConsecutive-address-uint96-]] +==== `[.contract-item-name]#++_mintConsecutive++#++(address to, uint96 batchSize) → uint96++` [.item-kind]#internal# + +Mint a batch of tokens of length `batchSize` for `to`. Returns the token id of the first token minted in the +batch; if `batchSize` is 0, returns the number of consecutive ids minted so far. + +Requirements: + +- `batchSize` must not be greater than {_maxBatchSize}. +- The function is called in the constructor of the contract (directly or indirectly). + +CAUTION: Does not emit a `Transfer` event. This is ERC721 compliant as long as it is done inside of the +constructor, which is enforced by this function. + +CAUTION: Does not invoke `onERC721Received` on the receiver. + +Emits a {IERC2309-ConsecutiveTransfer} event. + +[.contract-item] +[[ERC721Consecutive-_update-address-uint256-address-]] +==== `[.contract-item-name]#++_update++#++(address to, uint256 tokenId, address auth) → address++` [.item-kind]#internal# + +See {ERC721-_update}. Override version that restricts normal minting to after construction. + +WARNING: Using {ERC721Consecutive} prevents minting during construction in favor of {_mintConsecutive}. +After construction, {_mintConsecutive} is no longer available and minting through {_update} becomes available. + +[.contract-item] +[[ERC721Consecutive-_firstConsecutiveId--]] +==== `[.contract-item-name]#++_firstConsecutiveId++#++() → uint96++` [.item-kind]#internal# + +Used to offset the first token id in {_nextConsecutiveId} + +[.contract-item] +[[ERC721Consecutive-ERC721ForbiddenBatchMint--]] +==== `[.contract-item-name]#++ERC721ForbiddenBatchMint++#++()++` [.item-kind]#error# + +Batch mint is restricted to the constructor. +Any batch mint not emitting the {IERC721-Transfer} event outside of the constructor +is non-ERC721 compliant. + +[.contract-item] +[[ERC721Consecutive-ERC721ExceededMaxBatchMint-uint256-uint256-]] +==== `[.contract-item-name]#++ERC721ExceededMaxBatchMint++#++(uint256 batchSize, uint256 maxBatch)++` [.item-kind]#error# + +Exceeds the max amount of mints per batch. + +[.contract-item] +[[ERC721Consecutive-ERC721ForbiddenMint--]] +==== `[.contract-item-name]#++ERC721ForbiddenMint++#++()++` [.item-kind]#error# + +Individual minting is not allowed. + +[.contract-item] +[[ERC721Consecutive-ERC721ForbiddenBatchBurn--]] +==== `[.contract-item-name]#++ERC721ForbiddenBatchBurn++#++()++` [.item-kind]#error# + +Batch burn is not supported. + +:supportsInterface: pass:normal[xref:#ERC721URIStorage-supportsInterface-bytes4-[`++supportsInterface++`]] +:tokenURI: pass:normal[xref:#ERC721URIStorage-tokenURI-uint256-[`++tokenURI++`]] +:_setTokenURI: pass:normal[xref:#ERC721URIStorage-_setTokenURI-uint256-string-[`++_setTokenURI++`]] + +[.contract] +[[ERC721URIStorage]] +=== `++ERC721URIStorage++` link:https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v5.0.0-rc.0/contracts/token/ERC721/extensions/ERC721URIStorage.sol[{github-icon},role=heading-link] + +[.hljs-theme-light.nopadding] +```solidity +import "@openzeppelin/contracts/token/ERC721/extensions/ERC721URIStorage.sol"; +``` + +ERC721 token with storage based token URI management. + +[.contract-index] +.Functions +-- +* {xref-ERC721URIStorage-supportsInterface-bytes4-}[`++supportsInterface(interfaceId)++`] +* {xref-ERC721URIStorage-tokenURI-uint256-}[`++tokenURI(tokenId)++`] +* {xref-ERC721URIStorage-_setTokenURI-uint256-string-}[`++_setTokenURI(tokenId, _tokenURI)++`] + +[.contract-subindex-inherited] +.ERC721 +* {xref-ERC721-balanceOf-address-}[`++balanceOf(owner)++`] +* {xref-ERC721-ownerOf-uint256-}[`++ownerOf(tokenId)++`] +* {xref-ERC721-name--}[`++name()++`] +* {xref-ERC721-symbol--}[`++symbol()++`] +* {xref-ERC721-_baseURI--}[`++_baseURI()++`] +* {xref-ERC721-approve-address-uint256-}[`++approve(to, tokenId)++`] +* {xref-ERC721-getApproved-uint256-}[`++getApproved(tokenId)++`] +* {xref-ERC721-setApprovalForAll-address-bool-}[`++setApprovalForAll(operator, approved)++`] +* {xref-ERC721-isApprovedForAll-address-address-}[`++isApprovedForAll(owner, operator)++`] +* {xref-ERC721-transferFrom-address-address-uint256-}[`++transferFrom(from, to, tokenId)++`] +* {xref-ERC721-safeTransferFrom-address-address-uint256-}[`++safeTransferFrom(from, to, tokenId)++`] +* {xref-ERC721-safeTransferFrom-address-address-uint256-bytes-}[`++safeTransferFrom(from, to, tokenId, data)++`] +* {xref-ERC721-_ownerOf-uint256-}[`++_ownerOf(tokenId)++`] +* {xref-ERC721-_getApproved-uint256-}[`++_getApproved(tokenId)++`] +* {xref-ERC721-_isAuthorized-address-address-uint256-}[`++_isAuthorized(owner, spender, tokenId)++`] +* {xref-ERC721-_checkAuthorized-address-address-uint256-}[`++_checkAuthorized(owner, spender, tokenId)++`] +* {xref-ERC721-_increaseBalance-address-uint128-}[`++_increaseBalance(account, value)++`] +* {xref-ERC721-_update-address-uint256-address-}[`++_update(to, tokenId, auth)++`] +* {xref-ERC721-_mint-address-uint256-}[`++_mint(to, tokenId)++`] +* {xref-ERC721-_safeMint-address-uint256-}[`++_safeMint(to, tokenId)++`] +* {xref-ERC721-_safeMint-address-uint256-bytes-}[`++_safeMint(to, tokenId, data)++`] +* {xref-ERC721-_burn-uint256-}[`++_burn(tokenId)++`] +* {xref-ERC721-_transfer-address-address-uint256-}[`++_transfer(from, to, tokenId)++`] +* {xref-ERC721-_safeTransfer-address-address-uint256-}[`++_safeTransfer(from, to, tokenId)++`] +* {xref-ERC721-_safeTransfer-address-address-uint256-bytes-}[`++_safeTransfer(from, to, tokenId, data)++`] +* {xref-ERC721-_approve-address-uint256-address-}[`++_approve(to, tokenId, auth)++`] +* {xref-ERC721-_approve-address-uint256-address-bool-}[`++_approve(to, tokenId, auth, emitEvent)++`] +* {xref-ERC721-_setApprovalForAll-address-address-bool-}[`++_setApprovalForAll(owner, operator, approved)++`] +* {xref-ERC721-_requireOwned-uint256-}[`++_requireOwned(tokenId)++`] + +[.contract-subindex-inherited] +.IERC721Errors + +[.contract-subindex-inherited] +.IERC721Metadata + +[.contract-subindex-inherited] +.IERC4906 + +[.contract-subindex-inherited] +.IERC721 + +[.contract-subindex-inherited] +.ERC165 + +[.contract-subindex-inherited] +.IERC165 + +-- + +[.contract-index] +.Events +-- + +[.contract-subindex-inherited] +.ERC721 + +[.contract-subindex-inherited] +.IERC721Errors + +[.contract-subindex-inherited] +.IERC721Metadata + +[.contract-subindex-inherited] +.IERC4906 +* {xref-IERC4906-MetadataUpdate-uint256-}[`++MetadataUpdate(_tokenId)++`] +* {xref-IERC4906-BatchMetadataUpdate-uint256-uint256-}[`++BatchMetadataUpdate(_fromTokenId, _toTokenId)++`] + +[.contract-subindex-inherited] +.IERC721 +* {xref-IERC721-Transfer-address-address-uint256-}[`++Transfer(from, to, tokenId)++`] +* {xref-IERC721-Approval-address-address-uint256-}[`++Approval(owner, approved, tokenId)++`] +* {xref-IERC721-ApprovalForAll-address-address-bool-}[`++ApprovalForAll(owner, operator, approved)++`] + +[.contract-subindex-inherited] +.ERC165 + +[.contract-subindex-inherited] +.IERC165 + +-- + +[.contract-index] +.Errors +-- + +[.contract-subindex-inherited] +.ERC721 + +[.contract-subindex-inherited] +.IERC721Errors +* {xref-IERC721Errors-ERC721InvalidOwner-address-}[`++ERC721InvalidOwner(owner)++`] +* {xref-IERC721Errors-ERC721NonexistentToken-uint256-}[`++ERC721NonexistentToken(tokenId)++`] +* {xref-IERC721Errors-ERC721IncorrectOwner-address-uint256-address-}[`++ERC721IncorrectOwner(sender, tokenId, owner)++`] +* {xref-IERC721Errors-ERC721InvalidSender-address-}[`++ERC721InvalidSender(sender)++`] +* {xref-IERC721Errors-ERC721InvalidReceiver-address-}[`++ERC721InvalidReceiver(receiver)++`] +* {xref-IERC721Errors-ERC721InsufficientApproval-address-uint256-}[`++ERC721InsufficientApproval(operator, tokenId)++`] +* {xref-IERC721Errors-ERC721InvalidApprover-address-}[`++ERC721InvalidApprover(approver)++`] +* {xref-IERC721Errors-ERC721InvalidOperator-address-}[`++ERC721InvalidOperator(operator)++`] + +[.contract-subindex-inherited] +.IERC721Metadata + +[.contract-subindex-inherited] +.IERC4906 + +[.contract-subindex-inherited] +.IERC721 + +[.contract-subindex-inherited] +.ERC165 + +[.contract-subindex-inherited] +.IERC165 + +-- + +[.contract-item] +[[ERC721URIStorage-supportsInterface-bytes4-]] +==== `[.contract-item-name]#++supportsInterface++#++(bytes4 interfaceId) → bool++` [.item-kind]#public# + +See {IERC165-supportsInterface} + +[.contract-item] +[[ERC721URIStorage-tokenURI-uint256-]] +==== `[.contract-item-name]#++tokenURI++#++(uint256 tokenId) → string++` [.item-kind]#public# + +See {IERC721Metadata-tokenURI}. + +[.contract-item] +[[ERC721URIStorage-_setTokenURI-uint256-string-]] +==== `[.contract-item-name]#++_setTokenURI++#++(uint256 tokenId, string _tokenURI)++` [.item-kind]#internal# + +Sets `_tokenURI` as the tokenURI of `tokenId`. + +Emits {MetadataUpdate}. + +:_update: pass:normal[xref:#ERC721Votes-_update-address-uint256-address-[`++_update++`]] +:_getVotingUnits: pass:normal[xref:#ERC721Votes-_getVotingUnits-address-[`++_getVotingUnits++`]] +:_increaseBalance: pass:normal[xref:#ERC721Votes-_increaseBalance-address-uint128-[`++_increaseBalance++`]] + +[.contract] +[[ERC721Votes]] +=== `++ERC721Votes++` link:https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v5.0.0-rc.0/contracts/token/ERC721/extensions/ERC721Votes.sol[{github-icon},role=heading-link] + +[.hljs-theme-light.nopadding] +```solidity +import "@openzeppelin/contracts/token/ERC721/extensions/ERC721Votes.sol"; +``` + +Extension of ERC721 to support voting and delegation as implemented by {Votes}, where each individual NFT counts +as 1 vote unit. + +Tokens do not count as votes until they are delegated, because votes must be tracked which incurs an additional cost +on every transfer. Token holders can either delegate to a trusted representative who will decide how to make use of +the votes in governance decisions, or they can delegate to themselves to be their own representative. + +[.contract-index] +.Functions +-- +* {xref-ERC721Votes-_update-address-uint256-address-}[`++_update(to, tokenId, auth)++`] +* {xref-ERC721Votes-_getVotingUnits-address-}[`++_getVotingUnits(account)++`] +* {xref-ERC721Votes-_increaseBalance-address-uint128-}[`++_increaseBalance(account, amount)++`] + +[.contract-subindex-inherited] +.Votes +* {xref-Votes-clock--}[`++clock()++`] +* {xref-Votes-CLOCK_MODE--}[`++CLOCK_MODE()++`] +* {xref-Votes-getVotes-address-}[`++getVotes(account)++`] +* {xref-Votes-getPastVotes-address-uint256-}[`++getPastVotes(account, timepoint)++`] +* {xref-Votes-getPastTotalSupply-uint256-}[`++getPastTotalSupply(timepoint)++`] +* {xref-Votes-_getTotalSupply--}[`++_getTotalSupply()++`] +* {xref-Votes-delegates-address-}[`++delegates(account)++`] +* {xref-Votes-delegate-address-}[`++delegate(delegatee)++`] +* {xref-Votes-delegateBySig-address-uint256-uint256-uint8-bytes32-bytes32-}[`++delegateBySig(delegatee, nonce, expiry, v, r, s)++`] +* {xref-Votes-_delegate-address-address-}[`++_delegate(account, delegatee)++`] +* {xref-Votes-_transferVotingUnits-address-address-uint256-}[`++_transferVotingUnits(from, to, amount)++`] +* {xref-Votes-_numCheckpoints-address-}[`++_numCheckpoints(account)++`] +* {xref-Votes-_checkpoints-address-uint32-}[`++_checkpoints(account, pos)++`] + +[.contract-subindex-inherited] +.IERC5805 + +[.contract-subindex-inherited] +.IVotes + +[.contract-subindex-inherited] +.IERC6372 + +[.contract-subindex-inherited] +.Nonces +* {xref-Nonces-nonces-address-}[`++nonces(owner)++`] +* {xref-Nonces-_useNonce-address-}[`++_useNonce(owner)++`] +* {xref-Nonces-_useCheckedNonce-address-uint256-}[`++_useCheckedNonce(owner, nonce)++`] + +[.contract-subindex-inherited] +.EIP712 +* {xref-EIP712-_domainSeparatorV4--}[`++_domainSeparatorV4()++`] +* {xref-EIP712-_hashTypedDataV4-bytes32-}[`++_hashTypedDataV4(structHash)++`] +* {xref-EIP712-eip712Domain--}[`++eip712Domain()++`] +* {xref-EIP712-_EIP712Name--}[`++_EIP712Name()++`] +* {xref-EIP712-_EIP712Version--}[`++_EIP712Version()++`] + +[.contract-subindex-inherited] +.IERC5267 + +[.contract-subindex-inherited] +.ERC721 +* {xref-ERC721-supportsInterface-bytes4-}[`++supportsInterface(interfaceId)++`] +* {xref-ERC721-balanceOf-address-}[`++balanceOf(owner)++`] +* {xref-ERC721-ownerOf-uint256-}[`++ownerOf(tokenId)++`] +* {xref-ERC721-name--}[`++name()++`] +* {xref-ERC721-symbol--}[`++symbol()++`] +* {xref-ERC721-tokenURI-uint256-}[`++tokenURI(tokenId)++`] +* {xref-ERC721-_baseURI--}[`++_baseURI()++`] +* {xref-ERC721-approve-address-uint256-}[`++approve(to, tokenId)++`] +* {xref-ERC721-getApproved-uint256-}[`++getApproved(tokenId)++`] +* {xref-ERC721-setApprovalForAll-address-bool-}[`++setApprovalForAll(operator, approved)++`] +* {xref-ERC721-isApprovedForAll-address-address-}[`++isApprovedForAll(owner, operator)++`] +* {xref-ERC721-transferFrom-address-address-uint256-}[`++transferFrom(from, to, tokenId)++`] +* {xref-ERC721-safeTransferFrom-address-address-uint256-}[`++safeTransferFrom(from, to, tokenId)++`] +* {xref-ERC721-safeTransferFrom-address-address-uint256-bytes-}[`++safeTransferFrom(from, to, tokenId, data)++`] +* {xref-ERC721-_ownerOf-uint256-}[`++_ownerOf(tokenId)++`] +* {xref-ERC721-_getApproved-uint256-}[`++_getApproved(tokenId)++`] +* {xref-ERC721-_isAuthorized-address-address-uint256-}[`++_isAuthorized(owner, spender, tokenId)++`] +* {xref-ERC721-_checkAuthorized-address-address-uint256-}[`++_checkAuthorized(owner, spender, tokenId)++`] +* {xref-ERC721-_mint-address-uint256-}[`++_mint(to, tokenId)++`] +* {xref-ERC721-_safeMint-address-uint256-}[`++_safeMint(to, tokenId)++`] +* {xref-ERC721-_safeMint-address-uint256-bytes-}[`++_safeMint(to, tokenId, data)++`] +* {xref-ERC721-_burn-uint256-}[`++_burn(tokenId)++`] +* {xref-ERC721-_transfer-address-address-uint256-}[`++_transfer(from, to, tokenId)++`] +* {xref-ERC721-_safeTransfer-address-address-uint256-}[`++_safeTransfer(from, to, tokenId)++`] +* {xref-ERC721-_safeTransfer-address-address-uint256-bytes-}[`++_safeTransfer(from, to, tokenId, data)++`] +* {xref-ERC721-_approve-address-uint256-address-}[`++_approve(to, tokenId, auth)++`] +* {xref-ERC721-_approve-address-uint256-address-bool-}[`++_approve(to, tokenId, auth, emitEvent)++`] +* {xref-ERC721-_setApprovalForAll-address-address-bool-}[`++_setApprovalForAll(owner, operator, approved)++`] +* {xref-ERC721-_requireOwned-uint256-}[`++_requireOwned(tokenId)++`] + +[.contract-subindex-inherited] +.IERC721Errors + +[.contract-subindex-inherited] +.IERC721Metadata + +[.contract-subindex-inherited] +.IERC721 + +[.contract-subindex-inherited] +.ERC165 + +[.contract-subindex-inherited] +.IERC165 + +-- + +[.contract-index] +.Events +-- + +[.contract-subindex-inherited] +.Votes + +[.contract-subindex-inherited] +.IERC5805 + +[.contract-subindex-inherited] +.IVotes +* {xref-IVotes-DelegateChanged-address-address-address-}[`++DelegateChanged(delegator, fromDelegate, toDelegate)++`] +* {xref-IVotes-DelegateVotesChanged-address-uint256-uint256-}[`++DelegateVotesChanged(delegate, previousVotes, newVotes)++`] + +[.contract-subindex-inherited] +.IERC6372 + +[.contract-subindex-inherited] +.Nonces + +[.contract-subindex-inherited] +.EIP712 + +[.contract-subindex-inherited] +.IERC5267 +* {xref-IERC5267-EIP712DomainChanged--}[`++EIP712DomainChanged()++`] + +[.contract-subindex-inherited] +.ERC721 + +[.contract-subindex-inherited] +.IERC721Errors + +[.contract-subindex-inherited] +.IERC721Metadata + +[.contract-subindex-inherited] +.IERC721 +* {xref-IERC721-Transfer-address-address-uint256-}[`++Transfer(from, to, tokenId)++`] +* {xref-IERC721-Approval-address-address-uint256-}[`++Approval(owner, approved, tokenId)++`] +* {xref-IERC721-ApprovalForAll-address-address-bool-}[`++ApprovalForAll(owner, operator, approved)++`] + +[.contract-subindex-inherited] +.ERC165 + +[.contract-subindex-inherited] +.IERC165 + +-- + +[.contract-index] +.Errors +-- + +[.contract-subindex-inherited] +.Votes +* {xref-Votes-ERC6372InconsistentClock--}[`++ERC6372InconsistentClock()++`] +* {xref-Votes-ERC5805FutureLookup-uint256-uint48-}[`++ERC5805FutureLookup(timepoint, clock)++`] + +[.contract-subindex-inherited] +.IERC5805 + +[.contract-subindex-inherited] +.IVotes +* {xref-IVotes-VotesExpiredSignature-uint256-}[`++VotesExpiredSignature(expiry)++`] + +[.contract-subindex-inherited] +.IERC6372 + +[.contract-subindex-inherited] +.Nonces +* {xref-Nonces-InvalidAccountNonce-address-uint256-}[`++InvalidAccountNonce(account, currentNonce)++`] + +[.contract-subindex-inherited] +.EIP712 + +[.contract-subindex-inherited] +.IERC5267 + +[.contract-subindex-inherited] +.ERC721 + +[.contract-subindex-inherited] +.IERC721Errors +* {xref-IERC721Errors-ERC721InvalidOwner-address-}[`++ERC721InvalidOwner(owner)++`] +* {xref-IERC721Errors-ERC721NonexistentToken-uint256-}[`++ERC721NonexistentToken(tokenId)++`] +* {xref-IERC721Errors-ERC721IncorrectOwner-address-uint256-address-}[`++ERC721IncorrectOwner(sender, tokenId, owner)++`] +* {xref-IERC721Errors-ERC721InvalidSender-address-}[`++ERC721InvalidSender(sender)++`] +* {xref-IERC721Errors-ERC721InvalidReceiver-address-}[`++ERC721InvalidReceiver(receiver)++`] +* {xref-IERC721Errors-ERC721InsufficientApproval-address-uint256-}[`++ERC721InsufficientApproval(operator, tokenId)++`] +* {xref-IERC721Errors-ERC721InvalidApprover-address-}[`++ERC721InvalidApprover(approver)++`] +* {xref-IERC721Errors-ERC721InvalidOperator-address-}[`++ERC721InvalidOperator(operator)++`] + +[.contract-subindex-inherited] +.IERC721Metadata + +[.contract-subindex-inherited] +.IERC721 + +[.contract-subindex-inherited] +.ERC165 + +[.contract-subindex-inherited] +.IERC165 + +-- + +[.contract-item] +[[ERC721Votes-_update-address-uint256-address-]] +==== `[.contract-item-name]#++_update++#++(address to, uint256 tokenId, address auth) → address++` [.item-kind]#internal# + +See {ERC721-_update}. Adjusts votes when tokens are transferred. + +Emits a {IVotes-DelegateVotesChanged} event. + +[.contract-item] +[[ERC721Votes-_getVotingUnits-address-]] +==== `[.contract-item-name]#++_getVotingUnits++#++(address account) → uint256++` [.item-kind]#internal# + +Returns the balance of `account`. + +WARNING: Overriding this function will likely result in incorrect vote tracking. + +[.contract-item] +[[ERC721Votes-_increaseBalance-address-uint128-]] +==== `[.contract-item-name]#++_increaseBalance++#++(address account, uint128 amount)++` [.item-kind]#internal# + +See {ERC721-_increaseBalance}. We need that to account tokens that were minted in batch. + +:supportsInterface: pass:normal[xref:#ERC721Royalty-supportsInterface-bytes4-[`++supportsInterface++`]] + +[.contract] +[[ERC721Royalty]] +=== `++ERC721Royalty++` link:https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v5.0.0-rc.0/contracts/token/ERC721/extensions/ERC721Royalty.sol[{github-icon},role=heading-link] + +[.hljs-theme-light.nopadding] +```solidity +import "@openzeppelin/contracts/token/ERC721/extensions/ERC721Royalty.sol"; +``` + +Extension of ERC721 with the ERC2981 NFT Royalty Standard, a standardized way to retrieve royalty payment +information. + +Royalty information can be specified globally for all token ids via {ERC2981-_setDefaultRoyalty}, and/or individually +for specific token ids via {ERC2981-_setTokenRoyalty}. The latter takes precedence over the first. + +IMPORTANT: ERC-2981 only specifies a way to signal royalty information and does not enforce its payment. See +https://eips.ethereum.org/EIPS/eip-2981#optional-royalty-payments[Rationale] in the EIP. Marketplaces are expected to +voluntarily pay royalties together with sales, but note that this standard is not yet widely supported. + +[.contract-index] +.Functions +-- +* {xref-ERC721Royalty-supportsInterface-bytes4-}[`++supportsInterface(interfaceId)++`] + +[.contract-subindex-inherited] +.ERC721 +* {xref-ERC721-balanceOf-address-}[`++balanceOf(owner)++`] +* {xref-ERC721-ownerOf-uint256-}[`++ownerOf(tokenId)++`] +* {xref-ERC721-name--}[`++name()++`] +* {xref-ERC721-symbol--}[`++symbol()++`] +* {xref-ERC721-tokenURI-uint256-}[`++tokenURI(tokenId)++`] +* {xref-ERC721-_baseURI--}[`++_baseURI()++`] +* {xref-ERC721-approve-address-uint256-}[`++approve(to, tokenId)++`] +* {xref-ERC721-getApproved-uint256-}[`++getApproved(tokenId)++`] +* {xref-ERC721-setApprovalForAll-address-bool-}[`++setApprovalForAll(operator, approved)++`] +* {xref-ERC721-isApprovedForAll-address-address-}[`++isApprovedForAll(owner, operator)++`] +* {xref-ERC721-transferFrom-address-address-uint256-}[`++transferFrom(from, to, tokenId)++`] +* {xref-ERC721-safeTransferFrom-address-address-uint256-}[`++safeTransferFrom(from, to, tokenId)++`] +* {xref-ERC721-safeTransferFrom-address-address-uint256-bytes-}[`++safeTransferFrom(from, to, tokenId, data)++`] +* {xref-ERC721-_ownerOf-uint256-}[`++_ownerOf(tokenId)++`] +* {xref-ERC721-_getApproved-uint256-}[`++_getApproved(tokenId)++`] +* {xref-ERC721-_isAuthorized-address-address-uint256-}[`++_isAuthorized(owner, spender, tokenId)++`] +* {xref-ERC721-_checkAuthorized-address-address-uint256-}[`++_checkAuthorized(owner, spender, tokenId)++`] +* {xref-ERC721-_increaseBalance-address-uint128-}[`++_increaseBalance(account, value)++`] +* {xref-ERC721-_update-address-uint256-address-}[`++_update(to, tokenId, auth)++`] +* {xref-ERC721-_mint-address-uint256-}[`++_mint(to, tokenId)++`] +* {xref-ERC721-_safeMint-address-uint256-}[`++_safeMint(to, tokenId)++`] +* {xref-ERC721-_safeMint-address-uint256-bytes-}[`++_safeMint(to, tokenId, data)++`] +* {xref-ERC721-_burn-uint256-}[`++_burn(tokenId)++`] +* {xref-ERC721-_transfer-address-address-uint256-}[`++_transfer(from, to, tokenId)++`] +* {xref-ERC721-_safeTransfer-address-address-uint256-}[`++_safeTransfer(from, to, tokenId)++`] +* {xref-ERC721-_safeTransfer-address-address-uint256-bytes-}[`++_safeTransfer(from, to, tokenId, data)++`] +* {xref-ERC721-_approve-address-uint256-address-}[`++_approve(to, tokenId, auth)++`] +* {xref-ERC721-_approve-address-uint256-address-bool-}[`++_approve(to, tokenId, auth, emitEvent)++`] +* {xref-ERC721-_setApprovalForAll-address-address-bool-}[`++_setApprovalForAll(owner, operator, approved)++`] +* {xref-ERC721-_requireOwned-uint256-}[`++_requireOwned(tokenId)++`] + +[.contract-subindex-inherited] +.IERC721Errors + +[.contract-subindex-inherited] +.IERC721Metadata + +[.contract-subindex-inherited] +.IERC721 + +[.contract-subindex-inherited] +.ERC2981 +* {xref-ERC2981-royaltyInfo-uint256-uint256-}[`++royaltyInfo(tokenId, salePrice)++`] +* {xref-ERC2981-_feeDenominator--}[`++_feeDenominator()++`] +* {xref-ERC2981-_setDefaultRoyalty-address-uint96-}[`++_setDefaultRoyalty(receiver, feeNumerator)++`] +* {xref-ERC2981-_deleteDefaultRoyalty--}[`++_deleteDefaultRoyalty()++`] +* {xref-ERC2981-_setTokenRoyalty-uint256-address-uint96-}[`++_setTokenRoyalty(tokenId, receiver, feeNumerator)++`] +* {xref-ERC2981-_resetTokenRoyalty-uint256-}[`++_resetTokenRoyalty(tokenId)++`] + +[.contract-subindex-inherited] +.ERC165 + +[.contract-subindex-inherited] +.IERC2981 + +[.contract-subindex-inherited] +.IERC165 + +-- + +[.contract-index] +.Events +-- + +[.contract-subindex-inherited] +.ERC721 + +[.contract-subindex-inherited] +.IERC721Errors + +[.contract-subindex-inherited] +.IERC721Metadata + +[.contract-subindex-inherited] +.IERC721 +* {xref-IERC721-Transfer-address-address-uint256-}[`++Transfer(from, to, tokenId)++`] +* {xref-IERC721-Approval-address-address-uint256-}[`++Approval(owner, approved, tokenId)++`] +* {xref-IERC721-ApprovalForAll-address-address-bool-}[`++ApprovalForAll(owner, operator, approved)++`] + +[.contract-subindex-inherited] +.ERC2981 + +[.contract-subindex-inherited] +.ERC165 + +[.contract-subindex-inherited] +.IERC2981 + +[.contract-subindex-inherited] +.IERC165 + +-- + +[.contract-index] +.Errors +-- + +[.contract-subindex-inherited] +.ERC721 + +[.contract-subindex-inherited] +.IERC721Errors +* {xref-IERC721Errors-ERC721InvalidOwner-address-}[`++ERC721InvalidOwner(owner)++`] +* {xref-IERC721Errors-ERC721NonexistentToken-uint256-}[`++ERC721NonexistentToken(tokenId)++`] +* {xref-IERC721Errors-ERC721IncorrectOwner-address-uint256-address-}[`++ERC721IncorrectOwner(sender, tokenId, owner)++`] +* {xref-IERC721Errors-ERC721InvalidSender-address-}[`++ERC721InvalidSender(sender)++`] +* {xref-IERC721Errors-ERC721InvalidReceiver-address-}[`++ERC721InvalidReceiver(receiver)++`] +* {xref-IERC721Errors-ERC721InsufficientApproval-address-uint256-}[`++ERC721InsufficientApproval(operator, tokenId)++`] +* {xref-IERC721Errors-ERC721InvalidApprover-address-}[`++ERC721InvalidApprover(approver)++`] +* {xref-IERC721Errors-ERC721InvalidOperator-address-}[`++ERC721InvalidOperator(operator)++`] + +[.contract-subindex-inherited] +.IERC721Metadata + +[.contract-subindex-inherited] +.IERC721 + +[.contract-subindex-inherited] +.ERC2981 +* {xref-ERC2981-ERC2981InvalidDefaultRoyalty-uint256-uint256-}[`++ERC2981InvalidDefaultRoyalty(numerator, denominator)++`] +* {xref-ERC2981-ERC2981InvalidDefaultRoyaltyReceiver-address-}[`++ERC2981InvalidDefaultRoyaltyReceiver(receiver)++`] +* {xref-ERC2981-ERC2981InvalidTokenRoyalty-uint256-uint256-uint256-}[`++ERC2981InvalidTokenRoyalty(tokenId, numerator, denominator)++`] +* {xref-ERC2981-ERC2981InvalidTokenRoyaltyReceiver-uint256-address-}[`++ERC2981InvalidTokenRoyaltyReceiver(tokenId, receiver)++`] + +[.contract-subindex-inherited] +.ERC165 + +[.contract-subindex-inherited] +.IERC2981 + +[.contract-subindex-inherited] +.IERC165 + +-- + +[.contract-item] +[[ERC721Royalty-supportsInterface-bytes4-]] +==== `[.contract-item-name]#++supportsInterface++#++(bytes4 interfaceId) → bool++` [.item-kind]#public# + +See {IERC165-supportsInterface}. + +:ERC721UnsupportedToken: pass:normal[xref:#ERC721Wrapper-ERC721UnsupportedToken-address-[`++ERC721UnsupportedToken++`]] +:constructor: pass:normal[xref:#ERC721Wrapper-constructor-contract-IERC721-[`++constructor++`]] +:depositFor: pass:normal[xref:#ERC721Wrapper-depositFor-address-uint256---[`++depositFor++`]] +:withdrawTo: pass:normal[xref:#ERC721Wrapper-withdrawTo-address-uint256---[`++withdrawTo++`]] +:onERC721Received: pass:normal[xref:#ERC721Wrapper-onERC721Received-address-address-uint256-bytes-[`++onERC721Received++`]] +:_recover: pass:normal[xref:#ERC721Wrapper-_recover-address-uint256-[`++_recover++`]] +:underlying: pass:normal[xref:#ERC721Wrapper-underlying--[`++underlying++`]] + +[.contract] +[[ERC721Wrapper]] +=== `++ERC721Wrapper++` link:https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v5.0.0-rc.0/contracts/token/ERC721/extensions/ERC721Wrapper.sol[{github-icon},role=heading-link] + +[.hljs-theme-light.nopadding] +```solidity +import "@openzeppelin/contracts/token/ERC721/extensions/ERC721Wrapper.sol"; +``` + +Extension of the ERC721 token contract to support token wrapping. + +Users can deposit and withdraw an "underlying token" and receive a "wrapped token" with a matching tokenId. This is +useful in conjunction with other modules. For example, combining this wrapping mechanism with {ERC721Votes} will allow +the wrapping of an existing "basic" ERC721 into a governance token. + +[.contract-index] +.Functions +-- +* {xref-ERC721Wrapper-constructor-contract-IERC721-}[`++constructor(underlyingToken)++`] +* {xref-ERC721Wrapper-depositFor-address-uint256---}[`++depositFor(account, tokenIds)++`] +* {xref-ERC721Wrapper-withdrawTo-address-uint256---}[`++withdrawTo(account, tokenIds)++`] +* {xref-ERC721Wrapper-onERC721Received-address-address-uint256-bytes-}[`++onERC721Received(, from, tokenId, )++`] +* {xref-ERC721Wrapper-_recover-address-uint256-}[`++_recover(account, tokenId)++`] +* {xref-ERC721Wrapper-underlying--}[`++underlying()++`] + +[.contract-subindex-inherited] +.IERC721Receiver + +[.contract-subindex-inherited] +.ERC721 +* {xref-ERC721-supportsInterface-bytes4-}[`++supportsInterface(interfaceId)++`] +* {xref-ERC721-balanceOf-address-}[`++balanceOf(owner)++`] +* {xref-ERC721-ownerOf-uint256-}[`++ownerOf(tokenId)++`] +* {xref-ERC721-name--}[`++name()++`] +* {xref-ERC721-symbol--}[`++symbol()++`] +* {xref-ERC721-tokenURI-uint256-}[`++tokenURI(tokenId)++`] +* {xref-ERC721-_baseURI--}[`++_baseURI()++`] +* {xref-ERC721-approve-address-uint256-}[`++approve(to, tokenId)++`] +* {xref-ERC721-getApproved-uint256-}[`++getApproved(tokenId)++`] +* {xref-ERC721-setApprovalForAll-address-bool-}[`++setApprovalForAll(operator, approved)++`] +* {xref-ERC721-isApprovedForAll-address-address-}[`++isApprovedForAll(owner, operator)++`] +* {xref-ERC721-transferFrom-address-address-uint256-}[`++transferFrom(from, to, tokenId)++`] +* {xref-ERC721-safeTransferFrom-address-address-uint256-}[`++safeTransferFrom(from, to, tokenId)++`] +* {xref-ERC721-safeTransferFrom-address-address-uint256-bytes-}[`++safeTransferFrom(from, to, tokenId, data)++`] +* {xref-ERC721-_ownerOf-uint256-}[`++_ownerOf(tokenId)++`] +* {xref-ERC721-_getApproved-uint256-}[`++_getApproved(tokenId)++`] +* {xref-ERC721-_isAuthorized-address-address-uint256-}[`++_isAuthorized(owner, spender, tokenId)++`] +* {xref-ERC721-_checkAuthorized-address-address-uint256-}[`++_checkAuthorized(owner, spender, tokenId)++`] +* {xref-ERC721-_increaseBalance-address-uint128-}[`++_increaseBalance(account, value)++`] +* {xref-ERC721-_update-address-uint256-address-}[`++_update(to, tokenId, auth)++`] +* {xref-ERC721-_mint-address-uint256-}[`++_mint(to, tokenId)++`] +* {xref-ERC721-_safeMint-address-uint256-}[`++_safeMint(to, tokenId)++`] +* {xref-ERC721-_safeMint-address-uint256-bytes-}[`++_safeMint(to, tokenId, data)++`] +* {xref-ERC721-_burn-uint256-}[`++_burn(tokenId)++`] +* {xref-ERC721-_transfer-address-address-uint256-}[`++_transfer(from, to, tokenId)++`] +* {xref-ERC721-_safeTransfer-address-address-uint256-}[`++_safeTransfer(from, to, tokenId)++`] +* {xref-ERC721-_safeTransfer-address-address-uint256-bytes-}[`++_safeTransfer(from, to, tokenId, data)++`] +* {xref-ERC721-_approve-address-uint256-address-}[`++_approve(to, tokenId, auth)++`] +* {xref-ERC721-_approve-address-uint256-address-bool-}[`++_approve(to, tokenId, auth, emitEvent)++`] +* {xref-ERC721-_setApprovalForAll-address-address-bool-}[`++_setApprovalForAll(owner, operator, approved)++`] +* {xref-ERC721-_requireOwned-uint256-}[`++_requireOwned(tokenId)++`] + +[.contract-subindex-inherited] +.IERC721Errors + +[.contract-subindex-inherited] +.IERC721Metadata + +[.contract-subindex-inherited] +.IERC721 + +[.contract-subindex-inherited] +.ERC165 + +[.contract-subindex-inherited] +.IERC165 + +-- + +[.contract-index] +.Events +-- + +[.contract-subindex-inherited] +.IERC721Receiver + +[.contract-subindex-inherited] +.ERC721 + +[.contract-subindex-inherited] +.IERC721Errors + +[.contract-subindex-inherited] +.IERC721Metadata + +[.contract-subindex-inherited] +.IERC721 +* {xref-IERC721-Transfer-address-address-uint256-}[`++Transfer(from, to, tokenId)++`] +* {xref-IERC721-Approval-address-address-uint256-}[`++Approval(owner, approved, tokenId)++`] +* {xref-IERC721-ApprovalForAll-address-address-bool-}[`++ApprovalForAll(owner, operator, approved)++`] + +[.contract-subindex-inherited] +.ERC165 + +[.contract-subindex-inherited] +.IERC165 + +-- + +[.contract-index] +.Errors +-- +* {xref-ERC721Wrapper-ERC721UnsupportedToken-address-}[`++ERC721UnsupportedToken(token)++`] + +[.contract-subindex-inherited] +.IERC721Receiver + +[.contract-subindex-inherited] +.ERC721 + +[.contract-subindex-inherited] +.IERC721Errors +* {xref-IERC721Errors-ERC721InvalidOwner-address-}[`++ERC721InvalidOwner(owner)++`] +* {xref-IERC721Errors-ERC721NonexistentToken-uint256-}[`++ERC721NonexistentToken(tokenId)++`] +* {xref-IERC721Errors-ERC721IncorrectOwner-address-uint256-address-}[`++ERC721IncorrectOwner(sender, tokenId, owner)++`] +* {xref-IERC721Errors-ERC721InvalidSender-address-}[`++ERC721InvalidSender(sender)++`] +* {xref-IERC721Errors-ERC721InvalidReceiver-address-}[`++ERC721InvalidReceiver(receiver)++`] +* {xref-IERC721Errors-ERC721InsufficientApproval-address-uint256-}[`++ERC721InsufficientApproval(operator, tokenId)++`] +* {xref-IERC721Errors-ERC721InvalidApprover-address-}[`++ERC721InvalidApprover(approver)++`] +* {xref-IERC721Errors-ERC721InvalidOperator-address-}[`++ERC721InvalidOperator(operator)++`] + +[.contract-subindex-inherited] +.IERC721Metadata + +[.contract-subindex-inherited] +.IERC721 + +[.contract-subindex-inherited] +.ERC165 + +[.contract-subindex-inherited] +.IERC165 + +-- + +[.contract-item] +[[ERC721Wrapper-constructor-contract-IERC721-]] +==== `[.contract-item-name]#++constructor++#++(contract IERC721 underlyingToken)++` [.item-kind]#internal# + +[.contract-item] +[[ERC721Wrapper-depositFor-address-uint256---]] +==== `[.contract-item-name]#++depositFor++#++(address account, uint256[] tokenIds) → bool++` [.item-kind]#public# + +Allow a user to deposit underlying tokens and mint the corresponding tokenIds. + +[.contract-item] +[[ERC721Wrapper-withdrawTo-address-uint256---]] +==== `[.contract-item-name]#++withdrawTo++#++(address account, uint256[] tokenIds) → bool++` [.item-kind]#public# + +Allow a user to burn wrapped tokens and withdraw the corresponding tokenIds of the underlying tokens. + +[.contract-item] +[[ERC721Wrapper-onERC721Received-address-address-uint256-bytes-]] +==== `[.contract-item-name]#++onERC721Received++#++(address, address from, uint256 tokenId, bytes) → bytes4++` [.item-kind]#public# + +Overrides {IERC721Receiver-onERC721Received} to allow minting on direct ERC721 transfers to +this contract. + +In case there's data attached, it validates that the operator is this contract, so only trusted data +is accepted from {depositFor}. + +WARNING: Doesn't work with unsafe transfers (eg. {IERC721-transferFrom}). Use {ERC721Wrapper-_recover} +for recovering in that scenario. + +[.contract-item] +[[ERC721Wrapper-_recover-address-uint256-]] +==== `[.contract-item-name]#++_recover++#++(address account, uint256 tokenId) → uint256++` [.item-kind]#internal# + +Mint a wrapped token to cover any underlyingToken that would have been transferred by mistake. Internal +function that can be exposed with access control if desired. + +[.contract-item] +[[ERC721Wrapper-underlying--]] +==== `[.contract-item-name]#++underlying++#++() → contract IERC721++` [.item-kind]#public# + +Returns the underlying token. + +[.contract-item] +[[ERC721Wrapper-ERC721UnsupportedToken-address-]] +==== `[.contract-item-name]#++ERC721UnsupportedToken++#++(address token)++` [.item-kind]#error# + +The received ERC721 token couldn't be wrapped. + +== Utilities + +:onERC721Received: pass:normal[xref:#ERC721Holder-onERC721Received-address-address-uint256-bytes-[`++onERC721Received++`]] + +[.contract] +[[ERC721Holder]] +=== `++ERC721Holder++` link:https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v5.0.0-rc.0/contracts/token/ERC721/utils/ERC721Holder.sol[{github-icon},role=heading-link] + +[.hljs-theme-light.nopadding] +```solidity +import "@openzeppelin/contracts/token/ERC721/utils/ERC721Holder.sol"; +``` + +Implementation of the {IERC721Receiver} interface. + +Accepts all token transfers. +Make sure the contract is able to use its token with {IERC721-safeTransferFrom}, {IERC721-approve} or +{IERC721-setApprovalForAll}. + +[.contract-index] +.Functions +-- +* {xref-ERC721Holder-onERC721Received-address-address-uint256-bytes-}[`++onERC721Received(, , , )++`] + +[.contract-subindex-inherited] +.IERC721Receiver + +-- + +[.contract-item] +[[ERC721Holder-onERC721Received-address-address-uint256-bytes-]] +==== `[.contract-item-name]#++onERC721Received++#++(address, address, uint256, bytes) → bytes4++` [.item-kind]#public# + +See {IERC721Receiver-onERC721Received}. + +Always returns `IERC721Receiver.onERC721Received.selector`. + diff --git a/docs/modules/api/pages/token/common.adoc b/docs/modules/api/pages/token/common.adoc new file mode 100644 index 000000000..719c3869f --- /dev/null +++ b/docs/modules/api/pages/token/common.adoc @@ -0,0 +1,178 @@ +:github-icon: pass:[] +:ERC2981: pass:normal[xref:token/common.adoc#ERC2981[`ERC2981`]] +:ERC721Royalty: pass:normal[xref:token/ERC721.adoc#ERC721Royalty[`ERC721Royalty`]] +:xref-ERC2981-supportsInterface-bytes4-: xref:token/common.adoc#ERC2981-supportsInterface-bytes4- +:xref-ERC2981-royaltyInfo-uint256-uint256-: xref:token/common.adoc#ERC2981-royaltyInfo-uint256-uint256- +:xref-ERC2981-_feeDenominator--: xref:token/common.adoc#ERC2981-_feeDenominator-- +:xref-ERC2981-_setDefaultRoyalty-address-uint96-: xref:token/common.adoc#ERC2981-_setDefaultRoyalty-address-uint96- +:xref-ERC2981-_deleteDefaultRoyalty--: xref:token/common.adoc#ERC2981-_deleteDefaultRoyalty-- +:xref-ERC2981-_setTokenRoyalty-uint256-address-uint96-: xref:token/common.adoc#ERC2981-_setTokenRoyalty-uint256-address-uint96- +:xref-ERC2981-_resetTokenRoyalty-uint256-: xref:token/common.adoc#ERC2981-_resetTokenRoyalty-uint256- +:xref-ERC2981-ERC2981InvalidDefaultRoyalty-uint256-uint256-: xref:token/common.adoc#ERC2981-ERC2981InvalidDefaultRoyalty-uint256-uint256- +:xref-ERC2981-ERC2981InvalidDefaultRoyaltyReceiver-address-: xref:token/common.adoc#ERC2981-ERC2981InvalidDefaultRoyaltyReceiver-address- +:xref-ERC2981-ERC2981InvalidTokenRoyalty-uint256-uint256-uint256-: xref:token/common.adoc#ERC2981-ERC2981InvalidTokenRoyalty-uint256-uint256-uint256- +:xref-ERC2981-ERC2981InvalidTokenRoyaltyReceiver-uint256-address-: xref:token/common.adoc#ERC2981-ERC2981InvalidTokenRoyaltyReceiver-uint256-address- +:IERC165-supportsInterface: pass:normal[xref:utils.adoc#IERC165-supportsInterface-bytes4-[`IERC165.supportsInterface`]] += Common (Tokens) + +Functionality that is common to multiple token standards. + +* {ERC2981}: NFT Royalties compatible with both ERC721 and ERC1155. +** For ERC721 consider {ERC721Royalty} which clears the royalty information from storage on burn. + +== Contracts + +:RoyaltyInfo: pass:normal[xref:#ERC2981-RoyaltyInfo[`++RoyaltyInfo++`]] +:ERC2981InvalidDefaultRoyalty: pass:normal[xref:#ERC2981-ERC2981InvalidDefaultRoyalty-uint256-uint256-[`++ERC2981InvalidDefaultRoyalty++`]] +:ERC2981InvalidDefaultRoyaltyReceiver: pass:normal[xref:#ERC2981-ERC2981InvalidDefaultRoyaltyReceiver-address-[`++ERC2981InvalidDefaultRoyaltyReceiver++`]] +:ERC2981InvalidTokenRoyalty: pass:normal[xref:#ERC2981-ERC2981InvalidTokenRoyalty-uint256-uint256-uint256-[`++ERC2981InvalidTokenRoyalty++`]] +:ERC2981InvalidTokenRoyaltyReceiver: pass:normal[xref:#ERC2981-ERC2981InvalidTokenRoyaltyReceiver-uint256-address-[`++ERC2981InvalidTokenRoyaltyReceiver++`]] +:supportsInterface: pass:normal[xref:#ERC2981-supportsInterface-bytes4-[`++supportsInterface++`]] +:royaltyInfo: pass:normal[xref:#ERC2981-royaltyInfo-uint256-uint256-[`++royaltyInfo++`]] +:_feeDenominator: pass:normal[xref:#ERC2981-_feeDenominator--[`++_feeDenominator++`]] +:_setDefaultRoyalty: pass:normal[xref:#ERC2981-_setDefaultRoyalty-address-uint96-[`++_setDefaultRoyalty++`]] +:_deleteDefaultRoyalty: pass:normal[xref:#ERC2981-_deleteDefaultRoyalty--[`++_deleteDefaultRoyalty++`]] +:_setTokenRoyalty: pass:normal[xref:#ERC2981-_setTokenRoyalty-uint256-address-uint96-[`++_setTokenRoyalty++`]] +:_resetTokenRoyalty: pass:normal[xref:#ERC2981-_resetTokenRoyalty-uint256-[`++_resetTokenRoyalty++`]] + +[.contract] +[[ERC2981]] +=== `++ERC2981++` link:https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v5.0.0-rc.0/contracts/token/common/ERC2981.sol[{github-icon},role=heading-link] + +[.hljs-theme-light.nopadding] +```solidity +import "@openzeppelin/contracts/token/common/ERC2981.sol"; +``` + +Implementation of the NFT Royalty Standard, a standardized way to retrieve royalty payment information. + +Royalty information can be specified globally for all token ids via {_setDefaultRoyalty}, and/or individually for +specific token ids via {_setTokenRoyalty}. The latter takes precedence over the first. + +Royalty is specified as a fraction of sale price. {_feeDenominator} is overridable but defaults to 10000, meaning the +fee is specified in basis points by default. + +IMPORTANT: ERC-2981 only specifies a way to signal royalty information and does not enforce its payment. See +https://eips.ethereum.org/EIPS/eip-2981#optional-royalty-payments[Rationale] in the EIP. Marketplaces are expected to +voluntarily pay royalties together with sales, but note that this standard is not yet widely supported. + +[.contract-index] +.Functions +-- +* {xref-ERC2981-supportsInterface-bytes4-}[`++supportsInterface(interfaceId)++`] +* {xref-ERC2981-royaltyInfo-uint256-uint256-}[`++royaltyInfo(tokenId, salePrice)++`] +* {xref-ERC2981-_feeDenominator--}[`++_feeDenominator()++`] +* {xref-ERC2981-_setDefaultRoyalty-address-uint96-}[`++_setDefaultRoyalty(receiver, feeNumerator)++`] +* {xref-ERC2981-_deleteDefaultRoyalty--}[`++_deleteDefaultRoyalty()++`] +* {xref-ERC2981-_setTokenRoyalty-uint256-address-uint96-}[`++_setTokenRoyalty(tokenId, receiver, feeNumerator)++`] +* {xref-ERC2981-_resetTokenRoyalty-uint256-}[`++_resetTokenRoyalty(tokenId)++`] + +[.contract-subindex-inherited] +.ERC165 + +[.contract-subindex-inherited] +.IERC2981 + +[.contract-subindex-inherited] +.IERC165 + +-- + +[.contract-index] +.Errors +-- +* {xref-ERC2981-ERC2981InvalidDefaultRoyalty-uint256-uint256-}[`++ERC2981InvalidDefaultRoyalty(numerator, denominator)++`] +* {xref-ERC2981-ERC2981InvalidDefaultRoyaltyReceiver-address-}[`++ERC2981InvalidDefaultRoyaltyReceiver(receiver)++`] +* {xref-ERC2981-ERC2981InvalidTokenRoyalty-uint256-uint256-uint256-}[`++ERC2981InvalidTokenRoyalty(tokenId, numerator, denominator)++`] +* {xref-ERC2981-ERC2981InvalidTokenRoyaltyReceiver-uint256-address-}[`++ERC2981InvalidTokenRoyaltyReceiver(tokenId, receiver)++`] + +[.contract-subindex-inherited] +.ERC165 + +[.contract-subindex-inherited] +.IERC2981 + +[.contract-subindex-inherited] +.IERC165 + +-- + +[.contract-item] +[[ERC2981-supportsInterface-bytes4-]] +==== `[.contract-item-name]#++supportsInterface++#++(bytes4 interfaceId) → bool++` [.item-kind]#public# + +See {IERC165-supportsInterface}. + +[.contract-item] +[[ERC2981-royaltyInfo-uint256-uint256-]] +==== `[.contract-item-name]#++royaltyInfo++#++(uint256 tokenId, uint256 salePrice) → address, uint256++` [.item-kind]#public# + +Returns how much royalty is owed and to whom, based on a sale price that may be denominated in any unit of +exchange. The royalty amount is denominated and should be paid in that same unit of exchange. + +[.contract-item] +[[ERC2981-_feeDenominator--]] +==== `[.contract-item-name]#++_feeDenominator++#++() → uint96++` [.item-kind]#internal# + +The denominator with which to interpret the fee set in {_setTokenRoyalty} and {_setDefaultRoyalty} as a +fraction of the sale price. Defaults to 10000 so fees are expressed in basis points, but may be customized by an +override. + +[.contract-item] +[[ERC2981-_setDefaultRoyalty-address-uint96-]] +==== `[.contract-item-name]#++_setDefaultRoyalty++#++(address receiver, uint96 feeNumerator)++` [.item-kind]#internal# + +Sets the royalty information that all ids in this contract will default to. + +Requirements: + +- `receiver` cannot be the zero address. +- `feeNumerator` cannot be greater than the fee denominator. + +[.contract-item] +[[ERC2981-_deleteDefaultRoyalty--]] +==== `[.contract-item-name]#++_deleteDefaultRoyalty++#++()++` [.item-kind]#internal# + +Removes default royalty information. + +[.contract-item] +[[ERC2981-_setTokenRoyalty-uint256-address-uint96-]] +==== `[.contract-item-name]#++_setTokenRoyalty++#++(uint256 tokenId, address receiver, uint96 feeNumerator)++` [.item-kind]#internal# + +Sets the royalty information for a specific token id, overriding the global default. + +Requirements: + +- `receiver` cannot be the zero address. +- `feeNumerator` cannot be greater than the fee denominator. + +[.contract-item] +[[ERC2981-_resetTokenRoyalty-uint256-]] +==== `[.contract-item-name]#++_resetTokenRoyalty++#++(uint256 tokenId)++` [.item-kind]#internal# + +Resets royalty information for the token id back to the global default. + +[.contract-item] +[[ERC2981-ERC2981InvalidDefaultRoyalty-uint256-uint256-]] +==== `[.contract-item-name]#++ERC2981InvalidDefaultRoyalty++#++(uint256 numerator, uint256 denominator)++` [.item-kind]#error# + +The default royalty set is invalid (eg. (numerator / denominator) >= 1). + +[.contract-item] +[[ERC2981-ERC2981InvalidDefaultRoyaltyReceiver-address-]] +==== `[.contract-item-name]#++ERC2981InvalidDefaultRoyaltyReceiver++#++(address receiver)++` [.item-kind]#error# + +The default royalty receiver is invalid. + +[.contract-item] +[[ERC2981-ERC2981InvalidTokenRoyalty-uint256-uint256-uint256-]] +==== `[.contract-item-name]#++ERC2981InvalidTokenRoyalty++#++(uint256 tokenId, uint256 numerator, uint256 denominator)++` [.item-kind]#error# + +The royalty set for an specific `tokenId` is invalid (eg. (numerator / denominator) >= 1). + +[.contract-item] +[[ERC2981-ERC2981InvalidTokenRoyaltyReceiver-uint256-address-]] +==== `[.contract-item-name]#++ERC2981InvalidTokenRoyaltyReceiver++#++(uint256 tokenId, address receiver)++` [.item-kind]#error# + +The royalty receiver for `tokenId` is invalid. + diff --git a/docs/modules/api/pages/utils.adoc b/docs/modules/api/pages/utils.adoc new file mode 100644 index 000000000..f2b08f944 --- /dev/null +++ b/docs/modules/api/pages/utils.adoc @@ -0,0 +1,4497 @@ +:github-icon: pass:[] +:ReentrancyGuard: pass:normal[xref:utils.adoc#ReentrancyGuard[`ReentrancyGuard`]] +:Pausable: pass:normal[xref:utils.adoc#Pausable[`Pausable`]] +:SafeCast: pass:normal[xref:utils.adoc#SafeCast[`SafeCast`]] +:Math: pass:normal[xref:utils.adoc#Math[`Math`]] +:SignedMath: pass:normal[xref:utils.adoc#SignedMath[`SignedMath`]] +:Multicall: pass:normal[xref:utils.adoc#Multicall[`Multicall`]] +:Create2: pass:normal[xref:utils.adoc#Create2[`Create2`]] +:EnumerableMap: pass:normal[xref:utils.adoc#EnumerableMap[`EnumerableMap`]] +:EnumerableSet: pass:normal[xref:utils.adoc#EnumerableSet[`EnumerableSet`]] +:EnumerableMap: pass:normal[xref:utils.adoc#EnumerableMap[`EnumerableMap`]] +:EnumerableMap: pass:normal[xref:utils.adoc#EnumerableMap[`EnumerableMap`]] +:EnumerableSet: pass:normal[xref:utils.adoc#EnumerableSet[`EnumerableSet`]] +:xref-Math-tryAdd-uint256-uint256-: xref:utils.adoc#Math-tryAdd-uint256-uint256- +:xref-Math-trySub-uint256-uint256-: xref:utils.adoc#Math-trySub-uint256-uint256- +:xref-Math-tryMul-uint256-uint256-: xref:utils.adoc#Math-tryMul-uint256-uint256- +:xref-Math-tryDiv-uint256-uint256-: xref:utils.adoc#Math-tryDiv-uint256-uint256- +:xref-Math-tryMod-uint256-uint256-: xref:utils.adoc#Math-tryMod-uint256-uint256- +:xref-Math-max-uint256-uint256-: xref:utils.adoc#Math-max-uint256-uint256- +:xref-Math-min-uint256-uint256-: xref:utils.adoc#Math-min-uint256-uint256- +:xref-Math-average-uint256-uint256-: xref:utils.adoc#Math-average-uint256-uint256- +:xref-Math-ceilDiv-uint256-uint256-: xref:utils.adoc#Math-ceilDiv-uint256-uint256- +:xref-Math-mulDiv-uint256-uint256-uint256-: xref:utils.adoc#Math-mulDiv-uint256-uint256-uint256- +:xref-Math-mulDiv-uint256-uint256-uint256-enum-Math-Rounding-: xref:utils.adoc#Math-mulDiv-uint256-uint256-uint256-enum-Math-Rounding- +:xref-Math-sqrt-uint256-: xref:utils.adoc#Math-sqrt-uint256- +:xref-Math-sqrt-uint256-enum-Math-Rounding-: xref:utils.adoc#Math-sqrt-uint256-enum-Math-Rounding- +:xref-Math-log2-uint256-: xref:utils.adoc#Math-log2-uint256- +:xref-Math-log2-uint256-enum-Math-Rounding-: xref:utils.adoc#Math-log2-uint256-enum-Math-Rounding- +:xref-Math-log10-uint256-: xref:utils.adoc#Math-log10-uint256- +:xref-Math-log10-uint256-enum-Math-Rounding-: xref:utils.adoc#Math-log10-uint256-enum-Math-Rounding- +:xref-Math-log256-uint256-: xref:utils.adoc#Math-log256-uint256- +:xref-Math-log256-uint256-enum-Math-Rounding-: xref:utils.adoc#Math-log256-uint256-enum-Math-Rounding- +:xref-Math-unsignedRoundsUp-enum-Math-Rounding-: xref:utils.adoc#Math-unsignedRoundsUp-enum-Math-Rounding- +:xref-Math-MathOverflowedMulDiv--: xref:utils.adoc#Math-MathOverflowedMulDiv-- +:xref-SignedMath-max-int256-int256-: xref:utils.adoc#SignedMath-max-int256-int256- +:xref-SignedMath-min-int256-int256-: xref:utils.adoc#SignedMath-min-int256-int256- +:xref-SignedMath-average-int256-int256-: xref:utils.adoc#SignedMath-average-int256-int256- +:xref-SignedMath-abs-int256-: xref:utils.adoc#SignedMath-abs-int256- +:xref-SafeCast-toUint248-uint256-: xref:utils.adoc#SafeCast-toUint248-uint256- +:xref-SafeCast-toUint240-uint256-: xref:utils.adoc#SafeCast-toUint240-uint256- +:xref-SafeCast-toUint232-uint256-: xref:utils.adoc#SafeCast-toUint232-uint256- +:xref-SafeCast-toUint224-uint256-: xref:utils.adoc#SafeCast-toUint224-uint256- +:xref-SafeCast-toUint216-uint256-: xref:utils.adoc#SafeCast-toUint216-uint256- +:xref-SafeCast-toUint208-uint256-: xref:utils.adoc#SafeCast-toUint208-uint256- +:xref-SafeCast-toUint200-uint256-: xref:utils.adoc#SafeCast-toUint200-uint256- +:xref-SafeCast-toUint192-uint256-: xref:utils.adoc#SafeCast-toUint192-uint256- +:xref-SafeCast-toUint184-uint256-: xref:utils.adoc#SafeCast-toUint184-uint256- +:xref-SafeCast-toUint176-uint256-: xref:utils.adoc#SafeCast-toUint176-uint256- +:xref-SafeCast-toUint168-uint256-: xref:utils.adoc#SafeCast-toUint168-uint256- +:xref-SafeCast-toUint160-uint256-: xref:utils.adoc#SafeCast-toUint160-uint256- +:xref-SafeCast-toUint152-uint256-: xref:utils.adoc#SafeCast-toUint152-uint256- +:xref-SafeCast-toUint144-uint256-: xref:utils.adoc#SafeCast-toUint144-uint256- +:xref-SafeCast-toUint136-uint256-: xref:utils.adoc#SafeCast-toUint136-uint256- +:xref-SafeCast-toUint128-uint256-: xref:utils.adoc#SafeCast-toUint128-uint256- +:xref-SafeCast-toUint120-uint256-: xref:utils.adoc#SafeCast-toUint120-uint256- +:xref-SafeCast-toUint112-uint256-: xref:utils.adoc#SafeCast-toUint112-uint256- +:xref-SafeCast-toUint104-uint256-: xref:utils.adoc#SafeCast-toUint104-uint256- +:xref-SafeCast-toUint96-uint256-: xref:utils.adoc#SafeCast-toUint96-uint256- +:xref-SafeCast-toUint88-uint256-: xref:utils.adoc#SafeCast-toUint88-uint256- +:xref-SafeCast-toUint80-uint256-: xref:utils.adoc#SafeCast-toUint80-uint256- +:xref-SafeCast-toUint72-uint256-: xref:utils.adoc#SafeCast-toUint72-uint256- +:xref-SafeCast-toUint64-uint256-: xref:utils.adoc#SafeCast-toUint64-uint256- +:xref-SafeCast-toUint56-uint256-: xref:utils.adoc#SafeCast-toUint56-uint256- +:xref-SafeCast-toUint48-uint256-: xref:utils.adoc#SafeCast-toUint48-uint256- +:xref-SafeCast-toUint40-uint256-: xref:utils.adoc#SafeCast-toUint40-uint256- +:xref-SafeCast-toUint32-uint256-: xref:utils.adoc#SafeCast-toUint32-uint256- +:xref-SafeCast-toUint24-uint256-: xref:utils.adoc#SafeCast-toUint24-uint256- +:xref-SafeCast-toUint16-uint256-: xref:utils.adoc#SafeCast-toUint16-uint256- +:xref-SafeCast-toUint8-uint256-: xref:utils.adoc#SafeCast-toUint8-uint256- +:xref-SafeCast-toUint256-int256-: xref:utils.adoc#SafeCast-toUint256-int256- +:xref-SafeCast-toInt248-int256-: xref:utils.adoc#SafeCast-toInt248-int256- +:xref-SafeCast-toInt240-int256-: xref:utils.adoc#SafeCast-toInt240-int256- +:xref-SafeCast-toInt232-int256-: xref:utils.adoc#SafeCast-toInt232-int256- +:xref-SafeCast-toInt224-int256-: xref:utils.adoc#SafeCast-toInt224-int256- +:xref-SafeCast-toInt216-int256-: xref:utils.adoc#SafeCast-toInt216-int256- +:xref-SafeCast-toInt208-int256-: xref:utils.adoc#SafeCast-toInt208-int256- +:xref-SafeCast-toInt200-int256-: xref:utils.adoc#SafeCast-toInt200-int256- +:xref-SafeCast-toInt192-int256-: xref:utils.adoc#SafeCast-toInt192-int256- +:xref-SafeCast-toInt184-int256-: xref:utils.adoc#SafeCast-toInt184-int256- +:xref-SafeCast-toInt176-int256-: xref:utils.adoc#SafeCast-toInt176-int256- +:xref-SafeCast-toInt168-int256-: xref:utils.adoc#SafeCast-toInt168-int256- +:xref-SafeCast-toInt160-int256-: xref:utils.adoc#SafeCast-toInt160-int256- +:xref-SafeCast-toInt152-int256-: xref:utils.adoc#SafeCast-toInt152-int256- +:xref-SafeCast-toInt144-int256-: xref:utils.adoc#SafeCast-toInt144-int256- +:xref-SafeCast-toInt136-int256-: xref:utils.adoc#SafeCast-toInt136-int256- +:xref-SafeCast-toInt128-int256-: xref:utils.adoc#SafeCast-toInt128-int256- +:xref-SafeCast-toInt120-int256-: xref:utils.adoc#SafeCast-toInt120-int256- +:xref-SafeCast-toInt112-int256-: xref:utils.adoc#SafeCast-toInt112-int256- +:xref-SafeCast-toInt104-int256-: xref:utils.adoc#SafeCast-toInt104-int256- +:xref-SafeCast-toInt96-int256-: xref:utils.adoc#SafeCast-toInt96-int256- +:xref-SafeCast-toInt88-int256-: xref:utils.adoc#SafeCast-toInt88-int256- +:xref-SafeCast-toInt80-int256-: xref:utils.adoc#SafeCast-toInt80-int256- +:xref-SafeCast-toInt72-int256-: xref:utils.adoc#SafeCast-toInt72-int256- +:xref-SafeCast-toInt64-int256-: xref:utils.adoc#SafeCast-toInt64-int256- +:xref-SafeCast-toInt56-int256-: xref:utils.adoc#SafeCast-toInt56-int256- +:xref-SafeCast-toInt48-int256-: xref:utils.adoc#SafeCast-toInt48-int256- +:xref-SafeCast-toInt40-int256-: xref:utils.adoc#SafeCast-toInt40-int256- +:xref-SafeCast-toInt32-int256-: xref:utils.adoc#SafeCast-toInt32-int256- +:xref-SafeCast-toInt24-int256-: xref:utils.adoc#SafeCast-toInt24-int256- +:xref-SafeCast-toInt16-int256-: xref:utils.adoc#SafeCast-toInt16-int256- +:xref-SafeCast-toInt8-int256-: xref:utils.adoc#SafeCast-toInt8-int256- +:xref-SafeCast-toInt256-uint256-: xref:utils.adoc#SafeCast-toInt256-uint256- +:xref-SafeCast-SafeCastOverflowedUintDowncast-uint8-uint256-: xref:utils.adoc#SafeCast-SafeCastOverflowedUintDowncast-uint8-uint256- +:xref-SafeCast-SafeCastOverflowedIntToUint-int256-: xref:utils.adoc#SafeCast-SafeCastOverflowedIntToUint-int256- +:xref-SafeCast-SafeCastOverflowedIntDowncast-uint8-int256-: xref:utils.adoc#SafeCast-SafeCastOverflowedIntDowncast-uint8-int256- +:xref-SafeCast-SafeCastOverflowedUintToInt-uint256-: xref:utils.adoc#SafeCast-SafeCastOverflowedUintToInt-uint256- +:xref-ECDSA-tryRecover-bytes32-bytes-: xref:utils.adoc#ECDSA-tryRecover-bytes32-bytes- +:xref-ECDSA-recover-bytes32-bytes-: xref:utils.adoc#ECDSA-recover-bytes32-bytes- +:xref-ECDSA-tryRecover-bytes32-bytes32-bytes32-: xref:utils.adoc#ECDSA-tryRecover-bytes32-bytes32-bytes32- +:xref-ECDSA-recover-bytes32-bytes32-bytes32-: xref:utils.adoc#ECDSA-recover-bytes32-bytes32-bytes32- +:xref-ECDSA-tryRecover-bytes32-uint8-bytes32-bytes32-: xref:utils.adoc#ECDSA-tryRecover-bytes32-uint8-bytes32-bytes32- +:xref-ECDSA-recover-bytes32-uint8-bytes32-bytes32-: xref:utils.adoc#ECDSA-recover-bytes32-uint8-bytes32-bytes32- +:xref-ECDSA-ECDSAInvalidSignature--: xref:utils.adoc#ECDSA-ECDSAInvalidSignature-- +:xref-ECDSA-ECDSAInvalidSignatureLength-uint256-: xref:utils.adoc#ECDSA-ECDSAInvalidSignatureLength-uint256- +:xref-ECDSA-ECDSAInvalidSignatureS-bytes32-: xref:utils.adoc#ECDSA-ECDSAInvalidSignatureS-bytes32- +:MessageHashUtils-toEthSignedMessageHash: pass:normal[xref:utils.adoc#MessageHashUtils-toEthSignedMessageHash-bytes-[`MessageHashUtils.toEthSignedMessageHash`]] +:MessageHashUtils-toEthSignedMessageHash: pass:normal[xref:utils.adoc#MessageHashUtils-toEthSignedMessageHash-bytes-[`MessageHashUtils.toEthSignedMessageHash`]] +:ECDSA-tryRecover: pass:normal[xref:utils.adoc#ECDSA-tryRecover-bytes32-uint8-bytes32-bytes32-[`ECDSA.tryRecover`]] +:ECDSA-recover: pass:normal[xref:utils.adoc#ECDSA-recover-bytes32-uint8-bytes32-bytes32-[`ECDSA.recover`]] +:ECDSA-tryRecover: pass:normal[xref:utils.adoc#ECDSA-tryRecover-bytes32-uint8-bytes32-bytes32-[`ECDSA.tryRecover`]] +:ECDSA-recover: pass:normal[xref:utils.adoc#ECDSA-recover-bytes32-uint8-bytes32-bytes32-[`ECDSA.recover`]] +:ECDSA: pass:normal[xref:utils.adoc#ECDSA[`ECDSA`]] +:xref-MessageHashUtils-toEthSignedMessageHash-bytes32-: xref:utils.adoc#MessageHashUtils-toEthSignedMessageHash-bytes32- +:xref-MessageHashUtils-toEthSignedMessageHash-bytes-: xref:utils.adoc#MessageHashUtils-toEthSignedMessageHash-bytes- +:xref-MessageHashUtils-toDataWithIntendedValidatorHash-address-bytes-: xref:utils.adoc#MessageHashUtils-toDataWithIntendedValidatorHash-address-bytes- +:xref-MessageHashUtils-toTypedDataHash-bytes32-bytes32-: xref:utils.adoc#MessageHashUtils-toTypedDataHash-bytes32-bytes32- +:ECDSA-recover: pass:normal[xref:utils.adoc#ECDSA-recover-bytes32-uint8-bytes32-bytes32-[`ECDSA.recover`]] +:ECDSA-recover: pass:normal[xref:utils.adoc#ECDSA-recover-bytes32-uint8-bytes32-bytes32-[`ECDSA.recover`]] +:ECDSA-recover: pass:normal[xref:utils.adoc#ECDSA-recover-bytes32-uint8-bytes32-bytes32-[`ECDSA.recover`]] +:ECDSA-recover: pass:normal[xref:utils.adoc#ECDSA-recover-bytes32-uint8-bytes32-bytes32-[`ECDSA.recover`]] +:xref-SignatureChecker-isValidSignatureNow-address-bytes32-bytes-: xref:utils.adoc#SignatureChecker-isValidSignatureNow-address-bytes32-bytes- +:xref-SignatureChecker-isValidERC1271SignatureNow-address-bytes32-bytes-: xref:utils.adoc#SignatureChecker-isValidERC1271SignatureNow-address-bytes32-bytes- +:xref-MerkleProof-verify-bytes32---bytes32-bytes32-: xref:utils.adoc#MerkleProof-verify-bytes32---bytes32-bytes32- +:xref-MerkleProof-verifyCalldata-bytes32---bytes32-bytes32-: xref:utils.adoc#MerkleProof-verifyCalldata-bytes32---bytes32-bytes32- +:xref-MerkleProof-processProof-bytes32---bytes32-: xref:utils.adoc#MerkleProof-processProof-bytes32---bytes32- +:xref-MerkleProof-processProofCalldata-bytes32---bytes32-: xref:utils.adoc#MerkleProof-processProofCalldata-bytes32---bytes32- +:xref-MerkleProof-multiProofVerify-bytes32---bool---bytes32-bytes32---: xref:utils.adoc#MerkleProof-multiProofVerify-bytes32---bool---bytes32-bytes32--- +:xref-MerkleProof-multiProofVerifyCalldata-bytes32---bool---bytes32-bytes32---: xref:utils.adoc#MerkleProof-multiProofVerifyCalldata-bytes32---bool---bytes32-bytes32--- +:xref-MerkleProof-processMultiProof-bytes32---bool---bytes32---: xref:utils.adoc#MerkleProof-processMultiProof-bytes32---bool---bytes32--- +:xref-MerkleProof-processMultiProofCalldata-bytes32---bool---bytes32---: xref:utils.adoc#MerkleProof-processMultiProofCalldata-bytes32---bool---bytes32--- +:xref-MerkleProof-MerkleProofInvalidMultiproof--: xref:utils.adoc#MerkleProof-MerkleProofInvalidMultiproof-- +:xref-EIP712-constructor-string-string-: xref:utils.adoc#EIP712-constructor-string-string- +:xref-EIP712-_domainSeparatorV4--: xref:utils.adoc#EIP712-_domainSeparatorV4-- +:xref-EIP712-_hashTypedDataV4-bytes32-: xref:utils.adoc#EIP712-_hashTypedDataV4-bytes32- +:xref-EIP712-eip712Domain--: xref:utils.adoc#EIP712-eip712Domain-- +:xref-EIP712-_EIP712Name--: xref:utils.adoc#EIP712-_EIP712Name-- +:xref-EIP712-_EIP712Version--: xref:utils.adoc#EIP712-_EIP712Version-- +:xref-IERC5267-EIP712DomainChanged--: xref:interfaces.adoc#IERC5267-EIP712DomainChanged-- +:ECDSA-recover: pass:normal[xref:utils.adoc#ECDSA-recover-bytes32-uint8-bytes32-bytes32-[`ECDSA.recover`]] +:xref-ReentrancyGuard-nonReentrant--: xref:utils.adoc#ReentrancyGuard-nonReentrant-- +:xref-ReentrancyGuard-constructor--: xref:utils.adoc#ReentrancyGuard-constructor-- +:xref-ReentrancyGuard-_reentrancyGuardEntered--: xref:utils.adoc#ReentrancyGuard-_reentrancyGuardEntered-- +:xref-ReentrancyGuard-ReentrancyGuardReentrantCall--: xref:utils.adoc#ReentrancyGuard-ReentrancyGuardReentrantCall-- +:xref-Pausable-whenNotPaused--: xref:utils.adoc#Pausable-whenNotPaused-- +:xref-Pausable-whenPaused--: xref:utils.adoc#Pausable-whenPaused-- +:xref-Pausable-constructor--: xref:utils.adoc#Pausable-constructor-- +:xref-Pausable-paused--: xref:utils.adoc#Pausable-paused-- +:xref-Pausable-_requireNotPaused--: xref:utils.adoc#Pausable-_requireNotPaused-- +:xref-Pausable-_requirePaused--: xref:utils.adoc#Pausable-_requirePaused-- +:xref-Pausable-_pause--: xref:utils.adoc#Pausable-_pause-- +:xref-Pausable-_unpause--: xref:utils.adoc#Pausable-_unpause-- +:xref-Pausable-Paused-address-: xref:utils.adoc#Pausable-Paused-address- +:xref-Pausable-Unpaused-address-: xref:utils.adoc#Pausable-Unpaused-address- +:xref-Pausable-EnforcedPause--: xref:utils.adoc#Pausable-EnforcedPause-- +:xref-Pausable-ExpectedPause--: xref:utils.adoc#Pausable-ExpectedPause-- +:ERC165Checker: pass:normal[xref:utils.adoc#ERC165Checker[`ERC165Checker`]] +:ERC165: pass:normal[xref:utils.adoc#ERC165[`ERC165`]] +:xref-IERC165-supportsInterface-bytes4-: xref:utils.adoc#IERC165-supportsInterface-bytes4- +:IERC165: pass:normal[xref:utils.adoc#IERC165[`IERC165`]] +:xref-ERC165-supportsInterface-bytes4-: xref:utils.adoc#ERC165-supportsInterface-bytes4- +:IERC165-supportsInterface: pass:normal[xref:utils.adoc#IERC165-supportsInterface-bytes4-[`IERC165.supportsInterface`]] +:IERC165: pass:normal[xref:utils.adoc#IERC165[`IERC165`]] +:xref-ERC165Checker-supportsERC165-address-: xref:utils.adoc#ERC165Checker-supportsERC165-address- +:xref-ERC165Checker-supportsInterface-address-bytes4-: xref:utils.adoc#ERC165Checker-supportsInterface-address-bytes4- +:xref-ERC165Checker-getSupportedInterfaces-address-bytes4---: xref:utils.adoc#ERC165Checker-getSupportedInterfaces-address-bytes4--- +:xref-ERC165Checker-supportsAllInterfaces-address-bytes4---: xref:utils.adoc#ERC165Checker-supportsAllInterfaces-address-bytes4--- +:xref-ERC165Checker-supportsERC165InterfaceUnchecked-address-bytes4-: xref:utils.adoc#ERC165Checker-supportsERC165InterfaceUnchecked-address-bytes4- +:IERC165: pass:normal[xref:utils.adoc#IERC165[`IERC165`]] +:IERC165: pass:normal[xref:utils.adoc#IERC165[`IERC165`]] +:IERC165-supportsInterface: pass:normal[xref:utils.adoc#IERC165-supportsInterface-bytes4-[`IERC165.supportsInterface`]] +:IERC165-supportsInterface: pass:normal[xref:utils.adoc#IERC165-supportsInterface-bytes4-[`IERC165.supportsInterface`]] +:IERC165: pass:normal[xref:utils.adoc#IERC165[`IERC165`]] +:IERC165: pass:normal[xref:utils.adoc#IERC165[`IERC165`]] +:IERC165-supportsInterface: pass:normal[xref:utils.adoc#IERC165-supportsInterface-bytes4-[`IERC165.supportsInterface`]] +:xref-BitMaps-get-struct-BitMaps-BitMap-uint256-: xref:utils.adoc#BitMaps-get-struct-BitMaps-BitMap-uint256- +:xref-BitMaps-setTo-struct-BitMaps-BitMap-uint256-bool-: xref:utils.adoc#BitMaps-setTo-struct-BitMaps-BitMap-uint256-bool- +:xref-BitMaps-set-struct-BitMaps-BitMap-uint256-: xref:utils.adoc#BitMaps-set-struct-BitMaps-BitMap-uint256- +:xref-BitMaps-unset-struct-BitMaps-BitMap-uint256-: xref:utils.adoc#BitMaps-unset-struct-BitMaps-BitMap-uint256- +:xref-EnumerableMap-set-struct-EnumerableMap-Bytes32ToBytes32Map-bytes32-bytes32-: xref:utils.adoc#EnumerableMap-set-struct-EnumerableMap-Bytes32ToBytes32Map-bytes32-bytes32- +:xref-EnumerableMap-remove-struct-EnumerableMap-Bytes32ToBytes32Map-bytes32-: xref:utils.adoc#EnumerableMap-remove-struct-EnumerableMap-Bytes32ToBytes32Map-bytes32- +:xref-EnumerableMap-contains-struct-EnumerableMap-Bytes32ToBytes32Map-bytes32-: xref:utils.adoc#EnumerableMap-contains-struct-EnumerableMap-Bytes32ToBytes32Map-bytes32- +:xref-EnumerableMap-length-struct-EnumerableMap-Bytes32ToBytes32Map-: xref:utils.adoc#EnumerableMap-length-struct-EnumerableMap-Bytes32ToBytes32Map- +:xref-EnumerableMap-at-struct-EnumerableMap-Bytes32ToBytes32Map-uint256-: xref:utils.adoc#EnumerableMap-at-struct-EnumerableMap-Bytes32ToBytes32Map-uint256- +:xref-EnumerableMap-tryGet-struct-EnumerableMap-Bytes32ToBytes32Map-bytes32-: xref:utils.adoc#EnumerableMap-tryGet-struct-EnumerableMap-Bytes32ToBytes32Map-bytes32- +:xref-EnumerableMap-get-struct-EnumerableMap-Bytes32ToBytes32Map-bytes32-: xref:utils.adoc#EnumerableMap-get-struct-EnumerableMap-Bytes32ToBytes32Map-bytes32- +:xref-EnumerableMap-keys-struct-EnumerableMap-Bytes32ToBytes32Map-: xref:utils.adoc#EnumerableMap-keys-struct-EnumerableMap-Bytes32ToBytes32Map- +:xref-EnumerableMap-set-struct-EnumerableMap-UintToUintMap-uint256-uint256-: xref:utils.adoc#EnumerableMap-set-struct-EnumerableMap-UintToUintMap-uint256-uint256- +:xref-EnumerableMap-remove-struct-EnumerableMap-UintToUintMap-uint256-: xref:utils.adoc#EnumerableMap-remove-struct-EnumerableMap-UintToUintMap-uint256- +:xref-EnumerableMap-contains-struct-EnumerableMap-UintToUintMap-uint256-: xref:utils.adoc#EnumerableMap-contains-struct-EnumerableMap-UintToUintMap-uint256- +:xref-EnumerableMap-length-struct-EnumerableMap-UintToUintMap-: xref:utils.adoc#EnumerableMap-length-struct-EnumerableMap-UintToUintMap- +:xref-EnumerableMap-at-struct-EnumerableMap-UintToUintMap-uint256-: xref:utils.adoc#EnumerableMap-at-struct-EnumerableMap-UintToUintMap-uint256- +:xref-EnumerableMap-tryGet-struct-EnumerableMap-UintToUintMap-uint256-: xref:utils.adoc#EnumerableMap-tryGet-struct-EnumerableMap-UintToUintMap-uint256- +:xref-EnumerableMap-get-struct-EnumerableMap-UintToUintMap-uint256-: xref:utils.adoc#EnumerableMap-get-struct-EnumerableMap-UintToUintMap-uint256- +:xref-EnumerableMap-keys-struct-EnumerableMap-UintToUintMap-: xref:utils.adoc#EnumerableMap-keys-struct-EnumerableMap-UintToUintMap- +:xref-EnumerableMap-set-struct-EnumerableMap-UintToAddressMap-uint256-address-: xref:utils.adoc#EnumerableMap-set-struct-EnumerableMap-UintToAddressMap-uint256-address- +:xref-EnumerableMap-remove-struct-EnumerableMap-UintToAddressMap-uint256-: xref:utils.adoc#EnumerableMap-remove-struct-EnumerableMap-UintToAddressMap-uint256- +:xref-EnumerableMap-contains-struct-EnumerableMap-UintToAddressMap-uint256-: xref:utils.adoc#EnumerableMap-contains-struct-EnumerableMap-UintToAddressMap-uint256- +:xref-EnumerableMap-length-struct-EnumerableMap-UintToAddressMap-: xref:utils.adoc#EnumerableMap-length-struct-EnumerableMap-UintToAddressMap- +:xref-EnumerableMap-at-struct-EnumerableMap-UintToAddressMap-uint256-: xref:utils.adoc#EnumerableMap-at-struct-EnumerableMap-UintToAddressMap-uint256- +:xref-EnumerableMap-tryGet-struct-EnumerableMap-UintToAddressMap-uint256-: xref:utils.adoc#EnumerableMap-tryGet-struct-EnumerableMap-UintToAddressMap-uint256- +:xref-EnumerableMap-get-struct-EnumerableMap-UintToAddressMap-uint256-: xref:utils.adoc#EnumerableMap-get-struct-EnumerableMap-UintToAddressMap-uint256- +:xref-EnumerableMap-keys-struct-EnumerableMap-UintToAddressMap-: xref:utils.adoc#EnumerableMap-keys-struct-EnumerableMap-UintToAddressMap- +:xref-EnumerableMap-set-struct-EnumerableMap-AddressToUintMap-address-uint256-: xref:utils.adoc#EnumerableMap-set-struct-EnumerableMap-AddressToUintMap-address-uint256- +:xref-EnumerableMap-remove-struct-EnumerableMap-AddressToUintMap-address-: xref:utils.adoc#EnumerableMap-remove-struct-EnumerableMap-AddressToUintMap-address- +:xref-EnumerableMap-contains-struct-EnumerableMap-AddressToUintMap-address-: xref:utils.adoc#EnumerableMap-contains-struct-EnumerableMap-AddressToUintMap-address- +:xref-EnumerableMap-length-struct-EnumerableMap-AddressToUintMap-: xref:utils.adoc#EnumerableMap-length-struct-EnumerableMap-AddressToUintMap- +:xref-EnumerableMap-at-struct-EnumerableMap-AddressToUintMap-uint256-: xref:utils.adoc#EnumerableMap-at-struct-EnumerableMap-AddressToUintMap-uint256- +:xref-EnumerableMap-tryGet-struct-EnumerableMap-AddressToUintMap-address-: xref:utils.adoc#EnumerableMap-tryGet-struct-EnumerableMap-AddressToUintMap-address- +:xref-EnumerableMap-get-struct-EnumerableMap-AddressToUintMap-address-: xref:utils.adoc#EnumerableMap-get-struct-EnumerableMap-AddressToUintMap-address- +:xref-EnumerableMap-keys-struct-EnumerableMap-AddressToUintMap-: xref:utils.adoc#EnumerableMap-keys-struct-EnumerableMap-AddressToUintMap- +:xref-EnumerableMap-set-struct-EnumerableMap-Bytes32ToUintMap-bytes32-uint256-: xref:utils.adoc#EnumerableMap-set-struct-EnumerableMap-Bytes32ToUintMap-bytes32-uint256- +:xref-EnumerableMap-remove-struct-EnumerableMap-Bytes32ToUintMap-bytes32-: xref:utils.adoc#EnumerableMap-remove-struct-EnumerableMap-Bytes32ToUintMap-bytes32- +:xref-EnumerableMap-contains-struct-EnumerableMap-Bytes32ToUintMap-bytes32-: xref:utils.adoc#EnumerableMap-contains-struct-EnumerableMap-Bytes32ToUintMap-bytes32- +:xref-EnumerableMap-length-struct-EnumerableMap-Bytes32ToUintMap-: xref:utils.adoc#EnumerableMap-length-struct-EnumerableMap-Bytes32ToUintMap- +:xref-EnumerableMap-at-struct-EnumerableMap-Bytes32ToUintMap-uint256-: xref:utils.adoc#EnumerableMap-at-struct-EnumerableMap-Bytes32ToUintMap-uint256- +:xref-EnumerableMap-tryGet-struct-EnumerableMap-Bytes32ToUintMap-bytes32-: xref:utils.adoc#EnumerableMap-tryGet-struct-EnumerableMap-Bytes32ToUintMap-bytes32- +:xref-EnumerableMap-get-struct-EnumerableMap-Bytes32ToUintMap-bytes32-: xref:utils.adoc#EnumerableMap-get-struct-EnumerableMap-Bytes32ToUintMap-bytes32- +:xref-EnumerableMap-keys-struct-EnumerableMap-Bytes32ToUintMap-: xref:utils.adoc#EnumerableMap-keys-struct-EnumerableMap-Bytes32ToUintMap- +:xref-EnumerableMap-EnumerableMapNonexistentKey-bytes32-: xref:utils.adoc#EnumerableMap-EnumerableMapNonexistentKey-bytes32- +:xref-EnumerableSet-add-struct-EnumerableSet-Bytes32Set-bytes32-: xref:utils.adoc#EnumerableSet-add-struct-EnumerableSet-Bytes32Set-bytes32- +:xref-EnumerableSet-remove-struct-EnumerableSet-Bytes32Set-bytes32-: xref:utils.adoc#EnumerableSet-remove-struct-EnumerableSet-Bytes32Set-bytes32- +:xref-EnumerableSet-contains-struct-EnumerableSet-Bytes32Set-bytes32-: xref:utils.adoc#EnumerableSet-contains-struct-EnumerableSet-Bytes32Set-bytes32- +:xref-EnumerableSet-length-struct-EnumerableSet-Bytes32Set-: xref:utils.adoc#EnumerableSet-length-struct-EnumerableSet-Bytes32Set- +:xref-EnumerableSet-at-struct-EnumerableSet-Bytes32Set-uint256-: xref:utils.adoc#EnumerableSet-at-struct-EnumerableSet-Bytes32Set-uint256- +:xref-EnumerableSet-values-struct-EnumerableSet-Bytes32Set-: xref:utils.adoc#EnumerableSet-values-struct-EnumerableSet-Bytes32Set- +:xref-EnumerableSet-add-struct-EnumerableSet-AddressSet-address-: xref:utils.adoc#EnumerableSet-add-struct-EnumerableSet-AddressSet-address- +:xref-EnumerableSet-remove-struct-EnumerableSet-AddressSet-address-: xref:utils.adoc#EnumerableSet-remove-struct-EnumerableSet-AddressSet-address- +:xref-EnumerableSet-contains-struct-EnumerableSet-AddressSet-address-: xref:utils.adoc#EnumerableSet-contains-struct-EnumerableSet-AddressSet-address- +:xref-EnumerableSet-length-struct-EnumerableSet-AddressSet-: xref:utils.adoc#EnumerableSet-length-struct-EnumerableSet-AddressSet- +:xref-EnumerableSet-at-struct-EnumerableSet-AddressSet-uint256-: xref:utils.adoc#EnumerableSet-at-struct-EnumerableSet-AddressSet-uint256- +:xref-EnumerableSet-values-struct-EnumerableSet-AddressSet-: xref:utils.adoc#EnumerableSet-values-struct-EnumerableSet-AddressSet- +:xref-EnumerableSet-add-struct-EnumerableSet-UintSet-uint256-: xref:utils.adoc#EnumerableSet-add-struct-EnumerableSet-UintSet-uint256- +:xref-EnumerableSet-remove-struct-EnumerableSet-UintSet-uint256-: xref:utils.adoc#EnumerableSet-remove-struct-EnumerableSet-UintSet-uint256- +:xref-EnumerableSet-contains-struct-EnumerableSet-UintSet-uint256-: xref:utils.adoc#EnumerableSet-contains-struct-EnumerableSet-UintSet-uint256- +:xref-EnumerableSet-length-struct-EnumerableSet-UintSet-: xref:utils.adoc#EnumerableSet-length-struct-EnumerableSet-UintSet- +:xref-EnumerableSet-at-struct-EnumerableSet-UintSet-uint256-: xref:utils.adoc#EnumerableSet-at-struct-EnumerableSet-UintSet-uint256- +:xref-EnumerableSet-values-struct-EnumerableSet-UintSet-: xref:utils.adoc#EnumerableSet-values-struct-EnumerableSet-UintSet- +:xref-DoubleEndedQueue-pushBack-struct-DoubleEndedQueue-Bytes32Deque-bytes32-: xref:utils.adoc#DoubleEndedQueue-pushBack-struct-DoubleEndedQueue-Bytes32Deque-bytes32- +:xref-DoubleEndedQueue-popBack-struct-DoubleEndedQueue-Bytes32Deque-: xref:utils.adoc#DoubleEndedQueue-popBack-struct-DoubleEndedQueue-Bytes32Deque- +:xref-DoubleEndedQueue-pushFront-struct-DoubleEndedQueue-Bytes32Deque-bytes32-: xref:utils.adoc#DoubleEndedQueue-pushFront-struct-DoubleEndedQueue-Bytes32Deque-bytes32- +:xref-DoubleEndedQueue-popFront-struct-DoubleEndedQueue-Bytes32Deque-: xref:utils.adoc#DoubleEndedQueue-popFront-struct-DoubleEndedQueue-Bytes32Deque- +:xref-DoubleEndedQueue-front-struct-DoubleEndedQueue-Bytes32Deque-: xref:utils.adoc#DoubleEndedQueue-front-struct-DoubleEndedQueue-Bytes32Deque- +:xref-DoubleEndedQueue-back-struct-DoubleEndedQueue-Bytes32Deque-: xref:utils.adoc#DoubleEndedQueue-back-struct-DoubleEndedQueue-Bytes32Deque- +:xref-DoubleEndedQueue-at-struct-DoubleEndedQueue-Bytes32Deque-uint256-: xref:utils.adoc#DoubleEndedQueue-at-struct-DoubleEndedQueue-Bytes32Deque-uint256- +:xref-DoubleEndedQueue-clear-struct-DoubleEndedQueue-Bytes32Deque-: xref:utils.adoc#DoubleEndedQueue-clear-struct-DoubleEndedQueue-Bytes32Deque- +:xref-DoubleEndedQueue-length-struct-DoubleEndedQueue-Bytes32Deque-: xref:utils.adoc#DoubleEndedQueue-length-struct-DoubleEndedQueue-Bytes32Deque- +:xref-DoubleEndedQueue-empty-struct-DoubleEndedQueue-Bytes32Deque-: xref:utils.adoc#DoubleEndedQueue-empty-struct-DoubleEndedQueue-Bytes32Deque- +:xref-DoubleEndedQueue-QueueEmpty--: xref:utils.adoc#DoubleEndedQueue-QueueEmpty-- +:xref-DoubleEndedQueue-QueueFull--: xref:utils.adoc#DoubleEndedQueue-QueueFull-- +:xref-DoubleEndedQueue-QueueOutOfBounds--: xref:utils.adoc#DoubleEndedQueue-QueueOutOfBounds-- +:Votes: pass:normal[xref:governance.adoc#Votes[`Votes`]] +:xref-Checkpoints-push-struct-Checkpoints-Trace224-uint32-uint224-: xref:utils.adoc#Checkpoints-push-struct-Checkpoints-Trace224-uint32-uint224- +:xref-Checkpoints-lowerLookup-struct-Checkpoints-Trace224-uint32-: xref:utils.adoc#Checkpoints-lowerLookup-struct-Checkpoints-Trace224-uint32- +:xref-Checkpoints-upperLookup-struct-Checkpoints-Trace224-uint32-: xref:utils.adoc#Checkpoints-upperLookup-struct-Checkpoints-Trace224-uint32- +:xref-Checkpoints-upperLookupRecent-struct-Checkpoints-Trace224-uint32-: xref:utils.adoc#Checkpoints-upperLookupRecent-struct-Checkpoints-Trace224-uint32- +:xref-Checkpoints-latest-struct-Checkpoints-Trace224-: xref:utils.adoc#Checkpoints-latest-struct-Checkpoints-Trace224- +:xref-Checkpoints-latestCheckpoint-struct-Checkpoints-Trace224-: xref:utils.adoc#Checkpoints-latestCheckpoint-struct-Checkpoints-Trace224- +:xref-Checkpoints-length-struct-Checkpoints-Trace224-: xref:utils.adoc#Checkpoints-length-struct-Checkpoints-Trace224- +:xref-Checkpoints-at-struct-Checkpoints-Trace224-uint32-: xref:utils.adoc#Checkpoints-at-struct-Checkpoints-Trace224-uint32- +:xref-Checkpoints-push-struct-Checkpoints-Trace208-uint48-uint208-: xref:utils.adoc#Checkpoints-push-struct-Checkpoints-Trace208-uint48-uint208- +:xref-Checkpoints-lowerLookup-struct-Checkpoints-Trace208-uint48-: xref:utils.adoc#Checkpoints-lowerLookup-struct-Checkpoints-Trace208-uint48- +:xref-Checkpoints-upperLookup-struct-Checkpoints-Trace208-uint48-: xref:utils.adoc#Checkpoints-upperLookup-struct-Checkpoints-Trace208-uint48- +:xref-Checkpoints-upperLookupRecent-struct-Checkpoints-Trace208-uint48-: xref:utils.adoc#Checkpoints-upperLookupRecent-struct-Checkpoints-Trace208-uint48- +:xref-Checkpoints-latest-struct-Checkpoints-Trace208-: xref:utils.adoc#Checkpoints-latest-struct-Checkpoints-Trace208- +:xref-Checkpoints-latestCheckpoint-struct-Checkpoints-Trace208-: xref:utils.adoc#Checkpoints-latestCheckpoint-struct-Checkpoints-Trace208- +:xref-Checkpoints-length-struct-Checkpoints-Trace208-: xref:utils.adoc#Checkpoints-length-struct-Checkpoints-Trace208- +:xref-Checkpoints-at-struct-Checkpoints-Trace208-uint32-: xref:utils.adoc#Checkpoints-at-struct-Checkpoints-Trace208-uint32- +:xref-Checkpoints-push-struct-Checkpoints-Trace160-uint96-uint160-: xref:utils.adoc#Checkpoints-push-struct-Checkpoints-Trace160-uint96-uint160- +:xref-Checkpoints-lowerLookup-struct-Checkpoints-Trace160-uint96-: xref:utils.adoc#Checkpoints-lowerLookup-struct-Checkpoints-Trace160-uint96- +:xref-Checkpoints-upperLookup-struct-Checkpoints-Trace160-uint96-: xref:utils.adoc#Checkpoints-upperLookup-struct-Checkpoints-Trace160-uint96- +:xref-Checkpoints-upperLookupRecent-struct-Checkpoints-Trace160-uint96-: xref:utils.adoc#Checkpoints-upperLookupRecent-struct-Checkpoints-Trace160-uint96- +:xref-Checkpoints-latest-struct-Checkpoints-Trace160-: xref:utils.adoc#Checkpoints-latest-struct-Checkpoints-Trace160- +:xref-Checkpoints-latestCheckpoint-struct-Checkpoints-Trace160-: xref:utils.adoc#Checkpoints-latestCheckpoint-struct-Checkpoints-Trace160- +:xref-Checkpoints-length-struct-Checkpoints-Trace160-: xref:utils.adoc#Checkpoints-length-struct-Checkpoints-Trace160- +:xref-Checkpoints-at-struct-Checkpoints-Trace160-uint32-: xref:utils.adoc#Checkpoints-at-struct-Checkpoints-Trace160-uint32- +:xref-Checkpoints-CheckpointUnorderedInsertion--: xref:utils.adoc#Checkpoints-CheckpointUnorderedInsertion-- +:xref-Create2-deploy-uint256-bytes32-bytes-: xref:utils.adoc#Create2-deploy-uint256-bytes32-bytes- +:xref-Create2-computeAddress-bytes32-bytes32-: xref:utils.adoc#Create2-computeAddress-bytes32-bytes32- +:xref-Create2-computeAddress-bytes32-bytes32-address-: xref:utils.adoc#Create2-computeAddress-bytes32-bytes32-address- +:xref-Create2-Create2InsufficientBalance-uint256-uint256-: xref:utils.adoc#Create2-Create2InsufficientBalance-uint256-uint256- +:xref-Create2-Create2EmptyBytecode--: xref:utils.adoc#Create2-Create2EmptyBytecode-- +:xref-Create2-Create2FailedDeployment--: xref:utils.adoc#Create2-Create2FailedDeployment-- +:xref-Address-sendValue-address-payable-uint256-: xref:utils.adoc#Address-sendValue-address-payable-uint256- +:xref-Address-functionCall-address-bytes-: xref:utils.adoc#Address-functionCall-address-bytes- +:xref-Address-functionCallWithValue-address-bytes-uint256-: xref:utils.adoc#Address-functionCallWithValue-address-bytes-uint256- +:xref-Address-functionStaticCall-address-bytes-: xref:utils.adoc#Address-functionStaticCall-address-bytes- +:xref-Address-functionDelegateCall-address-bytes-: xref:utils.adoc#Address-functionDelegateCall-address-bytes- +:xref-Address-verifyCallResultFromTarget-address-bool-bytes-: xref:utils.adoc#Address-verifyCallResultFromTarget-address-bool-bytes- +:xref-Address-verifyCallResult-bool-bytes-: xref:utils.adoc#Address-verifyCallResult-bool-bytes- +:xref-Address-AddressInsufficientBalance-address-: xref:utils.adoc#Address-AddressInsufficientBalance-address- +:xref-Address-AddressEmptyCode-address-: xref:utils.adoc#Address-AddressEmptyCode-address- +:xref-Address-FailedInnerCall--: xref:utils.adoc#Address-FailedInnerCall-- +:ReentrancyGuard: pass:normal[xref:utils.adoc#ReentrancyGuard[`ReentrancyGuard`]] +:xref-Address-functionCall-address-bytes-: xref:utils.adoc#Address-functionCall-address-bytes- +:xref-Address-functionCall-address-bytes-: xref:utils.adoc#Address-functionCall-address-bytes- +:xref-Address-functionCall-address-bytes-: xref:utils.adoc#Address-functionCall-address-bytes- +:xref-Arrays-findUpperBound-uint256---uint256-: xref:utils.adoc#Arrays-findUpperBound-uint256---uint256- +:xref-Arrays-unsafeAccess-address---uint256-: xref:utils.adoc#Arrays-unsafeAccess-address---uint256- +:xref-Arrays-unsafeAccess-bytes32---uint256-: xref:utils.adoc#Arrays-unsafeAccess-bytes32---uint256- +:xref-Arrays-unsafeAccess-uint256---uint256-: xref:utils.adoc#Arrays-unsafeAccess-uint256---uint256- +:xref-Arrays-unsafeMemoryAccess-uint256---uint256-: xref:utils.adoc#Arrays-unsafeMemoryAccess-uint256---uint256- +:xref-Arrays-unsafeMemoryAccess-address---uint256-: xref:utils.adoc#Arrays-unsafeMemoryAccess-address---uint256- +:xref-Base64-encode-bytes-: xref:utils.adoc#Base64-encode-bytes- +:xref-Strings-toString-uint256-: xref:utils.adoc#Strings-toString-uint256- +:xref-Strings-toStringSigned-int256-: xref:utils.adoc#Strings-toStringSigned-int256- +:xref-Strings-toHexString-uint256-: xref:utils.adoc#Strings-toHexString-uint256- +:xref-Strings-toHexString-uint256-uint256-: xref:utils.adoc#Strings-toHexString-uint256-uint256- +:xref-Strings-toHexString-address-: xref:utils.adoc#Strings-toHexString-address- +:xref-Strings-equal-string-string-: xref:utils.adoc#Strings-equal-string-string- +:xref-Strings-StringsInsufficientHexLength-uint256-uint256-: xref:utils.adoc#Strings-StringsInsufficientHexLength-uint256-uint256- +:xref-ShortStrings-toShortString-string-: xref:utils.adoc#ShortStrings-toShortString-string- +:xref-ShortStrings-toString-ShortString-: xref:utils.adoc#ShortStrings-toString-ShortString- +:xref-ShortStrings-byteLength-ShortString-: xref:utils.adoc#ShortStrings-byteLength-ShortString- +:xref-ShortStrings-toShortStringWithFallback-string-string-: xref:utils.adoc#ShortStrings-toShortStringWithFallback-string-string- +:xref-ShortStrings-toStringWithFallback-ShortString-string-: xref:utils.adoc#ShortStrings-toStringWithFallback-ShortString-string- +:xref-ShortStrings-byteLengthWithFallback-ShortString-string-: xref:utils.adoc#ShortStrings-byteLengthWithFallback-ShortString-string- +:xref-ShortStrings-StringTooLong-string-: xref:utils.adoc#ShortStrings-StringTooLong-string- +:xref-ShortStrings-InvalidShortString--: xref:utils.adoc#ShortStrings-InvalidShortString-- +:xref-StorageSlot-getAddressSlot-bytes32-: xref:utils.adoc#StorageSlot-getAddressSlot-bytes32- +:xref-StorageSlot-getBooleanSlot-bytes32-: xref:utils.adoc#StorageSlot-getBooleanSlot-bytes32- +:xref-StorageSlot-getBytes32Slot-bytes32-: xref:utils.adoc#StorageSlot-getBytes32Slot-bytes32- +:xref-StorageSlot-getUint256Slot-bytes32-: xref:utils.adoc#StorageSlot-getUint256Slot-bytes32- +:xref-StorageSlot-getStringSlot-bytes32-: xref:utils.adoc#StorageSlot-getStringSlot-bytes32- +:xref-StorageSlot-getStringSlot-string-: xref:utils.adoc#StorageSlot-getStringSlot-string- +:xref-StorageSlot-getBytesSlot-bytes32-: xref:utils.adoc#StorageSlot-getBytesSlot-bytes32- +:xref-StorageSlot-getBytesSlot-bytes-: xref:utils.adoc#StorageSlot-getBytesSlot-bytes- +:xref-Multicall-multicall-bytes---: xref:utils.adoc#Multicall-multicall-bytes--- += Utilities + +[.readme-notice] +NOTE: This document is better viewed at https://docs.openzeppelin.com/contracts/api/utils + +Miscellaneous contracts and libraries containing utility functions you can use to improve security, work with new data types, or safely use low-level primitives. + + * {ReentrancyGuard}: A modifier that can prevent reentrancy during certain functions. + * {Pausable}: A common emergency response mechanism that can pause functionality while a remediation is pending. + * {SafeCast}: Checked downcasting functions to avoid silent truncation. + * {Math}, {SignedMath}: Implementation of various arithmetic functions. + * {Multicall}: Simple way to batch together multiple calls in a single external call. + * {Create2}: Wrapper around the https://blog.openzeppelin.com/getting-the-most-out-of-create2/[`CREATE2` EVM opcode] for safe use without having to deal with low-level assembly. + * {EnumerableMap}: A type like Solidity's https://solidity.readthedocs.io/en/latest/types.html#mapping-types[`mapping`], but with key-value _enumeration_: this will let you know how many entries a mapping has, and iterate over them (which is not possible with `mapping`). + * {EnumerableSet}: Like {EnumerableMap}, but for https://en.wikipedia.org/wiki/Set_(abstract_data_type)[sets]. Can be used to store privileged accounts, issued IDs, etc. + +[NOTE] +==== +Because Solidity does not support generic types, {EnumerableMap} and {EnumerableSet} are specialized to a limited number of key-value types. +==== + +== Math + +:MathOverflowedMulDiv: pass:normal[xref:#Math-MathOverflowedMulDiv--[`++MathOverflowedMulDiv++`]] +:Rounding: pass:normal[xref:#Math-Rounding[`++Rounding++`]] +:tryAdd: pass:normal[xref:#Math-tryAdd-uint256-uint256-[`++tryAdd++`]] +:trySub: pass:normal[xref:#Math-trySub-uint256-uint256-[`++trySub++`]] +:tryMul: pass:normal[xref:#Math-tryMul-uint256-uint256-[`++tryMul++`]] +:tryDiv: pass:normal[xref:#Math-tryDiv-uint256-uint256-[`++tryDiv++`]] +:tryMod: pass:normal[xref:#Math-tryMod-uint256-uint256-[`++tryMod++`]] +:max: pass:normal[xref:#Math-max-uint256-uint256-[`++max++`]] +:min: pass:normal[xref:#Math-min-uint256-uint256-[`++min++`]] +:average: pass:normal[xref:#Math-average-uint256-uint256-[`++average++`]] +:ceilDiv: pass:normal[xref:#Math-ceilDiv-uint256-uint256-[`++ceilDiv++`]] +:mulDiv: pass:normal[xref:#Math-mulDiv-uint256-uint256-uint256-[`++mulDiv++`]] +:mulDiv: pass:normal[xref:#Math-mulDiv-uint256-uint256-uint256-enum-Math-Rounding-[`++mulDiv++`]] +:sqrt: pass:normal[xref:#Math-sqrt-uint256-[`++sqrt++`]] +:sqrt: pass:normal[xref:#Math-sqrt-uint256-enum-Math-Rounding-[`++sqrt++`]] +:log2: pass:normal[xref:#Math-log2-uint256-[`++log2++`]] +:log2: pass:normal[xref:#Math-log2-uint256-enum-Math-Rounding-[`++log2++`]] +:log10: pass:normal[xref:#Math-log10-uint256-[`++log10++`]] +:log10: pass:normal[xref:#Math-log10-uint256-enum-Math-Rounding-[`++log10++`]] +:log256: pass:normal[xref:#Math-log256-uint256-[`++log256++`]] +:log256: pass:normal[xref:#Math-log256-uint256-enum-Math-Rounding-[`++log256++`]] +:unsignedRoundsUp: pass:normal[xref:#Math-unsignedRoundsUp-enum-Math-Rounding-[`++unsignedRoundsUp++`]] + +[.contract] +[[Math]] +=== `++Math++` link:https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v5.0.0-rc.0/contracts/utils/math/Math.sol[{github-icon},role=heading-link] + +[.hljs-theme-light.nopadding] +```solidity +import "@openzeppelin/contracts/utils/math/Math.sol"; +``` + +Standard math utilities missing in the Solidity language. + +[.contract-index] +.Functions +-- +* {xref-Math-tryAdd-uint256-uint256-}[`++tryAdd(a, b)++`] +* {xref-Math-trySub-uint256-uint256-}[`++trySub(a, b)++`] +* {xref-Math-tryMul-uint256-uint256-}[`++tryMul(a, b)++`] +* {xref-Math-tryDiv-uint256-uint256-}[`++tryDiv(a, b)++`] +* {xref-Math-tryMod-uint256-uint256-}[`++tryMod(a, b)++`] +* {xref-Math-max-uint256-uint256-}[`++max(a, b)++`] +* {xref-Math-min-uint256-uint256-}[`++min(a, b)++`] +* {xref-Math-average-uint256-uint256-}[`++average(a, b)++`] +* {xref-Math-ceilDiv-uint256-uint256-}[`++ceilDiv(a, b)++`] +* {xref-Math-mulDiv-uint256-uint256-uint256-}[`++mulDiv(x, y, denominator)++`] +* {xref-Math-mulDiv-uint256-uint256-uint256-enum-Math-Rounding-}[`++mulDiv(x, y, denominator, rounding)++`] +* {xref-Math-sqrt-uint256-}[`++sqrt(a)++`] +* {xref-Math-sqrt-uint256-enum-Math-Rounding-}[`++sqrt(a, rounding)++`] +* {xref-Math-log2-uint256-}[`++log2(value)++`] +* {xref-Math-log2-uint256-enum-Math-Rounding-}[`++log2(value, rounding)++`] +* {xref-Math-log10-uint256-}[`++log10(value)++`] +* {xref-Math-log10-uint256-enum-Math-Rounding-}[`++log10(value, rounding)++`] +* {xref-Math-log256-uint256-}[`++log256(value)++`] +* {xref-Math-log256-uint256-enum-Math-Rounding-}[`++log256(value, rounding)++`] +* {xref-Math-unsignedRoundsUp-enum-Math-Rounding-}[`++unsignedRoundsUp(rounding)++`] + +-- + +[.contract-index] +.Errors +-- +* {xref-Math-MathOverflowedMulDiv--}[`++MathOverflowedMulDiv()++`] + +-- + +[.contract-item] +[[Math-tryAdd-uint256-uint256-]] +==== `[.contract-item-name]#++tryAdd++#++(uint256 a, uint256 b) → bool, uint256++` [.item-kind]#internal# + +Returns the addition of two unsigned integers, with an overflow flag. + +[.contract-item] +[[Math-trySub-uint256-uint256-]] +==== `[.contract-item-name]#++trySub++#++(uint256 a, uint256 b) → bool, uint256++` [.item-kind]#internal# + +Returns the subtraction of two unsigned integers, with an overflow flag. + +[.contract-item] +[[Math-tryMul-uint256-uint256-]] +==== `[.contract-item-name]#++tryMul++#++(uint256 a, uint256 b) → bool, uint256++` [.item-kind]#internal# + +Returns the multiplication of two unsigned integers, with an overflow flag. + +[.contract-item] +[[Math-tryDiv-uint256-uint256-]] +==== `[.contract-item-name]#++tryDiv++#++(uint256 a, uint256 b) → bool, uint256++` [.item-kind]#internal# + +Returns the division of two unsigned integers, with a division by zero flag. + +[.contract-item] +[[Math-tryMod-uint256-uint256-]] +==== `[.contract-item-name]#++tryMod++#++(uint256 a, uint256 b) → bool, uint256++` [.item-kind]#internal# + +Returns the remainder of dividing two unsigned integers, with a division by zero flag. + +[.contract-item] +[[Math-max-uint256-uint256-]] +==== `[.contract-item-name]#++max++#++(uint256 a, uint256 b) → uint256++` [.item-kind]#internal# + +Returns the largest of two numbers. + +[.contract-item] +[[Math-min-uint256-uint256-]] +==== `[.contract-item-name]#++min++#++(uint256 a, uint256 b) → uint256++` [.item-kind]#internal# + +Returns the smallest of two numbers. + +[.contract-item] +[[Math-average-uint256-uint256-]] +==== `[.contract-item-name]#++average++#++(uint256 a, uint256 b) → uint256++` [.item-kind]#internal# + +Returns the average of two numbers. The result is rounded towards +zero. + +[.contract-item] +[[Math-ceilDiv-uint256-uint256-]] +==== `[.contract-item-name]#++ceilDiv++#++(uint256 a, uint256 b) → uint256++` [.item-kind]#internal# + +Returns the ceiling of the division of two numbers. + +This differs from standard division with `/` in that it rounds towards infinity instead +of rounding towards zero. + +[.contract-item] +[[Math-mulDiv-uint256-uint256-uint256-]] +==== `[.contract-item-name]#++mulDiv++#++(uint256 x, uint256 y, uint256 denominator) → uint256 result++` [.item-kind]#internal# + +Original credit to Remco Bloemen under MIT license (https://xn--2-umb.com/21/muldiv) with further edits by +Uniswap Labs also under MIT license. + +[.contract-item] +[[Math-mulDiv-uint256-uint256-uint256-enum-Math-Rounding-]] +==== `[.contract-item-name]#++mulDiv++#++(uint256 x, uint256 y, uint256 denominator, enum Math.Rounding rounding) → uint256++` [.item-kind]#internal# + +[.contract-item] +[[Math-sqrt-uint256-]] +==== `[.contract-item-name]#++sqrt++#++(uint256 a) → uint256++` [.item-kind]#internal# + +Returns the square root of a number. If the number is not a perfect square, the value is rounded +towards zero. + +Inspired by Henry S. Warren, Jr.'s "Hacker's Delight" (Chapter 11). + +[.contract-item] +[[Math-sqrt-uint256-enum-Math-Rounding-]] +==== `[.contract-item-name]#++sqrt++#++(uint256 a, enum Math.Rounding rounding) → uint256++` [.item-kind]#internal# + +[.contract-item] +[[Math-log2-uint256-]] +==== `[.contract-item-name]#++log2++#++(uint256 value) → uint256++` [.item-kind]#internal# + +Return the log in base 2 of a positive value rounded towards zero. +Returns 0 if given 0. + +[.contract-item] +[[Math-log2-uint256-enum-Math-Rounding-]] +==== `[.contract-item-name]#++log2++#++(uint256 value, enum Math.Rounding rounding) → uint256++` [.item-kind]#internal# + +Return the log in base 2, following the selected rounding direction, of a positive value. +Returns 0 if given 0. + +[.contract-item] +[[Math-log10-uint256-]] +==== `[.contract-item-name]#++log10++#++(uint256 value) → uint256++` [.item-kind]#internal# + +Return the log in base 10 of a positive value rounded towards zero. +Returns 0 if given 0. + +[.contract-item] +[[Math-log10-uint256-enum-Math-Rounding-]] +==== `[.contract-item-name]#++log10++#++(uint256 value, enum Math.Rounding rounding) → uint256++` [.item-kind]#internal# + +Return the log in base 10, following the selected rounding direction, of a positive value. +Returns 0 if given 0. + +[.contract-item] +[[Math-log256-uint256-]] +==== `[.contract-item-name]#++log256++#++(uint256 value) → uint256++` [.item-kind]#internal# + +Return the log in base 256 of a positive value rounded towards zero. +Returns 0 if given 0. + +Adding one to the result gives the number of pairs of hex symbols needed to represent `value` as a hex string. + +[.contract-item] +[[Math-log256-uint256-enum-Math-Rounding-]] +==== `[.contract-item-name]#++log256++#++(uint256 value, enum Math.Rounding rounding) → uint256++` [.item-kind]#internal# + +Return the log in base 256, following the selected rounding direction, of a positive value. +Returns 0 if given 0. + +[.contract-item] +[[Math-unsignedRoundsUp-enum-Math-Rounding-]] +==== `[.contract-item-name]#++unsignedRoundsUp++#++(enum Math.Rounding rounding) → bool++` [.item-kind]#internal# + +Returns whether a provided rounding mode is considered rounding up for unsigned integers. + +[.contract-item] +[[Math-MathOverflowedMulDiv--]] +==== `[.contract-item-name]#++MathOverflowedMulDiv++#++()++` [.item-kind]#error# + +Muldiv operation overflow. + +:max: pass:normal[xref:#SignedMath-max-int256-int256-[`++max++`]] +:min: pass:normal[xref:#SignedMath-min-int256-int256-[`++min++`]] +:average: pass:normal[xref:#SignedMath-average-int256-int256-[`++average++`]] +:abs: pass:normal[xref:#SignedMath-abs-int256-[`++abs++`]] + +[.contract] +[[SignedMath]] +=== `++SignedMath++` link:https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v5.0.0-rc.0/contracts/utils/math/SignedMath.sol[{github-icon},role=heading-link] + +[.hljs-theme-light.nopadding] +```solidity +import "@openzeppelin/contracts/utils/math/SignedMath.sol"; +``` + +Standard signed math utilities missing in the Solidity language. + +[.contract-index] +.Functions +-- +* {xref-SignedMath-max-int256-int256-}[`++max(a, b)++`] +* {xref-SignedMath-min-int256-int256-}[`++min(a, b)++`] +* {xref-SignedMath-average-int256-int256-}[`++average(a, b)++`] +* {xref-SignedMath-abs-int256-}[`++abs(n)++`] + +-- + +[.contract-item] +[[SignedMath-max-int256-int256-]] +==== `[.contract-item-name]#++max++#++(int256 a, int256 b) → int256++` [.item-kind]#internal# + +Returns the largest of two signed numbers. + +[.contract-item] +[[SignedMath-min-int256-int256-]] +==== `[.contract-item-name]#++min++#++(int256 a, int256 b) → int256++` [.item-kind]#internal# + +Returns the smallest of two signed numbers. + +[.contract-item] +[[SignedMath-average-int256-int256-]] +==== `[.contract-item-name]#++average++#++(int256 a, int256 b) → int256++` [.item-kind]#internal# + +Returns the average of two signed numbers without overflow. +The result is rounded towards zero. + +[.contract-item] +[[SignedMath-abs-int256-]] +==== `[.contract-item-name]#++abs++#++(int256 n) → uint256++` [.item-kind]#internal# + +Returns the absolute unsigned value of a signed value. + +:SafeCastOverflowedUintDowncast: pass:normal[xref:#SafeCast-SafeCastOverflowedUintDowncast-uint8-uint256-[`++SafeCastOverflowedUintDowncast++`]] +:SafeCastOverflowedIntToUint: pass:normal[xref:#SafeCast-SafeCastOverflowedIntToUint-int256-[`++SafeCastOverflowedIntToUint++`]] +:SafeCastOverflowedIntDowncast: pass:normal[xref:#SafeCast-SafeCastOverflowedIntDowncast-uint8-int256-[`++SafeCastOverflowedIntDowncast++`]] +:SafeCastOverflowedUintToInt: pass:normal[xref:#SafeCast-SafeCastOverflowedUintToInt-uint256-[`++SafeCastOverflowedUintToInt++`]] +:toUint248: pass:normal[xref:#SafeCast-toUint248-uint256-[`++toUint248++`]] +:toUint240: pass:normal[xref:#SafeCast-toUint240-uint256-[`++toUint240++`]] +:toUint232: pass:normal[xref:#SafeCast-toUint232-uint256-[`++toUint232++`]] +:toUint224: pass:normal[xref:#SafeCast-toUint224-uint256-[`++toUint224++`]] +:toUint216: pass:normal[xref:#SafeCast-toUint216-uint256-[`++toUint216++`]] +:toUint208: pass:normal[xref:#SafeCast-toUint208-uint256-[`++toUint208++`]] +:toUint200: pass:normal[xref:#SafeCast-toUint200-uint256-[`++toUint200++`]] +:toUint192: pass:normal[xref:#SafeCast-toUint192-uint256-[`++toUint192++`]] +:toUint184: pass:normal[xref:#SafeCast-toUint184-uint256-[`++toUint184++`]] +:toUint176: pass:normal[xref:#SafeCast-toUint176-uint256-[`++toUint176++`]] +:toUint168: pass:normal[xref:#SafeCast-toUint168-uint256-[`++toUint168++`]] +:toUint160: pass:normal[xref:#SafeCast-toUint160-uint256-[`++toUint160++`]] +:toUint152: pass:normal[xref:#SafeCast-toUint152-uint256-[`++toUint152++`]] +:toUint144: pass:normal[xref:#SafeCast-toUint144-uint256-[`++toUint144++`]] +:toUint136: pass:normal[xref:#SafeCast-toUint136-uint256-[`++toUint136++`]] +:toUint128: pass:normal[xref:#SafeCast-toUint128-uint256-[`++toUint128++`]] +:toUint120: pass:normal[xref:#SafeCast-toUint120-uint256-[`++toUint120++`]] +:toUint112: pass:normal[xref:#SafeCast-toUint112-uint256-[`++toUint112++`]] +:toUint104: pass:normal[xref:#SafeCast-toUint104-uint256-[`++toUint104++`]] +:toUint96: pass:normal[xref:#SafeCast-toUint96-uint256-[`++toUint96++`]] +:toUint88: pass:normal[xref:#SafeCast-toUint88-uint256-[`++toUint88++`]] +:toUint80: pass:normal[xref:#SafeCast-toUint80-uint256-[`++toUint80++`]] +:toUint72: pass:normal[xref:#SafeCast-toUint72-uint256-[`++toUint72++`]] +:toUint64: pass:normal[xref:#SafeCast-toUint64-uint256-[`++toUint64++`]] +:toUint56: pass:normal[xref:#SafeCast-toUint56-uint256-[`++toUint56++`]] +:toUint48: pass:normal[xref:#SafeCast-toUint48-uint256-[`++toUint48++`]] +:toUint40: pass:normal[xref:#SafeCast-toUint40-uint256-[`++toUint40++`]] +:toUint32: pass:normal[xref:#SafeCast-toUint32-uint256-[`++toUint32++`]] +:toUint24: pass:normal[xref:#SafeCast-toUint24-uint256-[`++toUint24++`]] +:toUint16: pass:normal[xref:#SafeCast-toUint16-uint256-[`++toUint16++`]] +:toUint8: pass:normal[xref:#SafeCast-toUint8-uint256-[`++toUint8++`]] +:toUint256: pass:normal[xref:#SafeCast-toUint256-int256-[`++toUint256++`]] +:toInt248: pass:normal[xref:#SafeCast-toInt248-int256-[`++toInt248++`]] +:toInt240: pass:normal[xref:#SafeCast-toInt240-int256-[`++toInt240++`]] +:toInt232: pass:normal[xref:#SafeCast-toInt232-int256-[`++toInt232++`]] +:toInt224: pass:normal[xref:#SafeCast-toInt224-int256-[`++toInt224++`]] +:toInt216: pass:normal[xref:#SafeCast-toInt216-int256-[`++toInt216++`]] +:toInt208: pass:normal[xref:#SafeCast-toInt208-int256-[`++toInt208++`]] +:toInt200: pass:normal[xref:#SafeCast-toInt200-int256-[`++toInt200++`]] +:toInt192: pass:normal[xref:#SafeCast-toInt192-int256-[`++toInt192++`]] +:toInt184: pass:normal[xref:#SafeCast-toInt184-int256-[`++toInt184++`]] +:toInt176: pass:normal[xref:#SafeCast-toInt176-int256-[`++toInt176++`]] +:toInt168: pass:normal[xref:#SafeCast-toInt168-int256-[`++toInt168++`]] +:toInt160: pass:normal[xref:#SafeCast-toInt160-int256-[`++toInt160++`]] +:toInt152: pass:normal[xref:#SafeCast-toInt152-int256-[`++toInt152++`]] +:toInt144: pass:normal[xref:#SafeCast-toInt144-int256-[`++toInt144++`]] +:toInt136: pass:normal[xref:#SafeCast-toInt136-int256-[`++toInt136++`]] +:toInt128: pass:normal[xref:#SafeCast-toInt128-int256-[`++toInt128++`]] +:toInt120: pass:normal[xref:#SafeCast-toInt120-int256-[`++toInt120++`]] +:toInt112: pass:normal[xref:#SafeCast-toInt112-int256-[`++toInt112++`]] +:toInt104: pass:normal[xref:#SafeCast-toInt104-int256-[`++toInt104++`]] +:toInt96: pass:normal[xref:#SafeCast-toInt96-int256-[`++toInt96++`]] +:toInt88: pass:normal[xref:#SafeCast-toInt88-int256-[`++toInt88++`]] +:toInt80: pass:normal[xref:#SafeCast-toInt80-int256-[`++toInt80++`]] +:toInt72: pass:normal[xref:#SafeCast-toInt72-int256-[`++toInt72++`]] +:toInt64: pass:normal[xref:#SafeCast-toInt64-int256-[`++toInt64++`]] +:toInt56: pass:normal[xref:#SafeCast-toInt56-int256-[`++toInt56++`]] +:toInt48: pass:normal[xref:#SafeCast-toInt48-int256-[`++toInt48++`]] +:toInt40: pass:normal[xref:#SafeCast-toInt40-int256-[`++toInt40++`]] +:toInt32: pass:normal[xref:#SafeCast-toInt32-int256-[`++toInt32++`]] +:toInt24: pass:normal[xref:#SafeCast-toInt24-int256-[`++toInt24++`]] +:toInt16: pass:normal[xref:#SafeCast-toInt16-int256-[`++toInt16++`]] +:toInt8: pass:normal[xref:#SafeCast-toInt8-int256-[`++toInt8++`]] +:toInt256: pass:normal[xref:#SafeCast-toInt256-uint256-[`++toInt256++`]] + +[.contract] +[[SafeCast]] +=== `++SafeCast++` link:https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v5.0.0-rc.0/contracts/utils/math/SafeCast.sol[{github-icon},role=heading-link] + +[.hljs-theme-light.nopadding] +```solidity +import "@openzeppelin/contracts/utils/math/SafeCast.sol"; +``` + +Wrappers over Solidity's uintXX/intXX casting operators with added overflow +checks. + +Downcasting from uint256/int256 in Solidity does not revert on overflow. This can +easily result in undesired exploitation or bugs, since developers usually +assume that overflows raise errors. `SafeCast` restores this intuition by +reverting the transaction when such an operation overflows. + +Using this library instead of the unchecked operations eliminates an entire +class of bugs, so it's recommended to use it always. + +[.contract-index] +.Functions +-- +* {xref-SafeCast-toUint248-uint256-}[`++toUint248(value)++`] +* {xref-SafeCast-toUint240-uint256-}[`++toUint240(value)++`] +* {xref-SafeCast-toUint232-uint256-}[`++toUint232(value)++`] +* {xref-SafeCast-toUint224-uint256-}[`++toUint224(value)++`] +* {xref-SafeCast-toUint216-uint256-}[`++toUint216(value)++`] +* {xref-SafeCast-toUint208-uint256-}[`++toUint208(value)++`] +* {xref-SafeCast-toUint200-uint256-}[`++toUint200(value)++`] +* {xref-SafeCast-toUint192-uint256-}[`++toUint192(value)++`] +* {xref-SafeCast-toUint184-uint256-}[`++toUint184(value)++`] +* {xref-SafeCast-toUint176-uint256-}[`++toUint176(value)++`] +* {xref-SafeCast-toUint168-uint256-}[`++toUint168(value)++`] +* {xref-SafeCast-toUint160-uint256-}[`++toUint160(value)++`] +* {xref-SafeCast-toUint152-uint256-}[`++toUint152(value)++`] +* {xref-SafeCast-toUint144-uint256-}[`++toUint144(value)++`] +* {xref-SafeCast-toUint136-uint256-}[`++toUint136(value)++`] +* {xref-SafeCast-toUint128-uint256-}[`++toUint128(value)++`] +* {xref-SafeCast-toUint120-uint256-}[`++toUint120(value)++`] +* {xref-SafeCast-toUint112-uint256-}[`++toUint112(value)++`] +* {xref-SafeCast-toUint104-uint256-}[`++toUint104(value)++`] +* {xref-SafeCast-toUint96-uint256-}[`++toUint96(value)++`] +* {xref-SafeCast-toUint88-uint256-}[`++toUint88(value)++`] +* {xref-SafeCast-toUint80-uint256-}[`++toUint80(value)++`] +* {xref-SafeCast-toUint72-uint256-}[`++toUint72(value)++`] +* {xref-SafeCast-toUint64-uint256-}[`++toUint64(value)++`] +* {xref-SafeCast-toUint56-uint256-}[`++toUint56(value)++`] +* {xref-SafeCast-toUint48-uint256-}[`++toUint48(value)++`] +* {xref-SafeCast-toUint40-uint256-}[`++toUint40(value)++`] +* {xref-SafeCast-toUint32-uint256-}[`++toUint32(value)++`] +* {xref-SafeCast-toUint24-uint256-}[`++toUint24(value)++`] +* {xref-SafeCast-toUint16-uint256-}[`++toUint16(value)++`] +* {xref-SafeCast-toUint8-uint256-}[`++toUint8(value)++`] +* {xref-SafeCast-toUint256-int256-}[`++toUint256(value)++`] +* {xref-SafeCast-toInt248-int256-}[`++toInt248(value)++`] +* {xref-SafeCast-toInt240-int256-}[`++toInt240(value)++`] +* {xref-SafeCast-toInt232-int256-}[`++toInt232(value)++`] +* {xref-SafeCast-toInt224-int256-}[`++toInt224(value)++`] +* {xref-SafeCast-toInt216-int256-}[`++toInt216(value)++`] +* {xref-SafeCast-toInt208-int256-}[`++toInt208(value)++`] +* {xref-SafeCast-toInt200-int256-}[`++toInt200(value)++`] +* {xref-SafeCast-toInt192-int256-}[`++toInt192(value)++`] +* {xref-SafeCast-toInt184-int256-}[`++toInt184(value)++`] +* {xref-SafeCast-toInt176-int256-}[`++toInt176(value)++`] +* {xref-SafeCast-toInt168-int256-}[`++toInt168(value)++`] +* {xref-SafeCast-toInt160-int256-}[`++toInt160(value)++`] +* {xref-SafeCast-toInt152-int256-}[`++toInt152(value)++`] +* {xref-SafeCast-toInt144-int256-}[`++toInt144(value)++`] +* {xref-SafeCast-toInt136-int256-}[`++toInt136(value)++`] +* {xref-SafeCast-toInt128-int256-}[`++toInt128(value)++`] +* {xref-SafeCast-toInt120-int256-}[`++toInt120(value)++`] +* {xref-SafeCast-toInt112-int256-}[`++toInt112(value)++`] +* {xref-SafeCast-toInt104-int256-}[`++toInt104(value)++`] +* {xref-SafeCast-toInt96-int256-}[`++toInt96(value)++`] +* {xref-SafeCast-toInt88-int256-}[`++toInt88(value)++`] +* {xref-SafeCast-toInt80-int256-}[`++toInt80(value)++`] +* {xref-SafeCast-toInt72-int256-}[`++toInt72(value)++`] +* {xref-SafeCast-toInt64-int256-}[`++toInt64(value)++`] +* {xref-SafeCast-toInt56-int256-}[`++toInt56(value)++`] +* {xref-SafeCast-toInt48-int256-}[`++toInt48(value)++`] +* {xref-SafeCast-toInt40-int256-}[`++toInt40(value)++`] +* {xref-SafeCast-toInt32-int256-}[`++toInt32(value)++`] +* {xref-SafeCast-toInt24-int256-}[`++toInt24(value)++`] +* {xref-SafeCast-toInt16-int256-}[`++toInt16(value)++`] +* {xref-SafeCast-toInt8-int256-}[`++toInt8(value)++`] +* {xref-SafeCast-toInt256-uint256-}[`++toInt256(value)++`] + +-- + +[.contract-index] +.Errors +-- +* {xref-SafeCast-SafeCastOverflowedUintDowncast-uint8-uint256-}[`++SafeCastOverflowedUintDowncast(bits, value)++`] +* {xref-SafeCast-SafeCastOverflowedIntToUint-int256-}[`++SafeCastOverflowedIntToUint(value)++`] +* {xref-SafeCast-SafeCastOverflowedIntDowncast-uint8-int256-}[`++SafeCastOverflowedIntDowncast(bits, value)++`] +* {xref-SafeCast-SafeCastOverflowedUintToInt-uint256-}[`++SafeCastOverflowedUintToInt(value)++`] + +-- + +[.contract-item] +[[SafeCast-toUint248-uint256-]] +==== `[.contract-item-name]#++toUint248++#++(uint256 value) → uint248++` [.item-kind]#internal# + +Returns the downcasted uint248 from uint256, reverting on +overflow (when the input is greater than largest uint248). + +Counterpart to Solidity's `uint248` operator. + +Requirements: + +- input must fit into 248 bits + +[.contract-item] +[[SafeCast-toUint240-uint256-]] +==== `[.contract-item-name]#++toUint240++#++(uint256 value) → uint240++` [.item-kind]#internal# + +Returns the downcasted uint240 from uint256, reverting on +overflow (when the input is greater than largest uint240). + +Counterpart to Solidity's `uint240` operator. + +Requirements: + +- input must fit into 240 bits + +[.contract-item] +[[SafeCast-toUint232-uint256-]] +==== `[.contract-item-name]#++toUint232++#++(uint256 value) → uint232++` [.item-kind]#internal# + +Returns the downcasted uint232 from uint256, reverting on +overflow (when the input is greater than largest uint232). + +Counterpart to Solidity's `uint232` operator. + +Requirements: + +- input must fit into 232 bits + +[.contract-item] +[[SafeCast-toUint224-uint256-]] +==== `[.contract-item-name]#++toUint224++#++(uint256 value) → uint224++` [.item-kind]#internal# + +Returns the downcasted uint224 from uint256, reverting on +overflow (when the input is greater than largest uint224). + +Counterpart to Solidity's `uint224` operator. + +Requirements: + +- input must fit into 224 bits + +[.contract-item] +[[SafeCast-toUint216-uint256-]] +==== `[.contract-item-name]#++toUint216++#++(uint256 value) → uint216++` [.item-kind]#internal# + +Returns the downcasted uint216 from uint256, reverting on +overflow (when the input is greater than largest uint216). + +Counterpart to Solidity's `uint216` operator. + +Requirements: + +- input must fit into 216 bits + +[.contract-item] +[[SafeCast-toUint208-uint256-]] +==== `[.contract-item-name]#++toUint208++#++(uint256 value) → uint208++` [.item-kind]#internal# + +Returns the downcasted uint208 from uint256, reverting on +overflow (when the input is greater than largest uint208). + +Counterpart to Solidity's `uint208` operator. + +Requirements: + +- input must fit into 208 bits + +[.contract-item] +[[SafeCast-toUint200-uint256-]] +==== `[.contract-item-name]#++toUint200++#++(uint256 value) → uint200++` [.item-kind]#internal# + +Returns the downcasted uint200 from uint256, reverting on +overflow (when the input is greater than largest uint200). + +Counterpart to Solidity's `uint200` operator. + +Requirements: + +- input must fit into 200 bits + +[.contract-item] +[[SafeCast-toUint192-uint256-]] +==== `[.contract-item-name]#++toUint192++#++(uint256 value) → uint192++` [.item-kind]#internal# + +Returns the downcasted uint192 from uint256, reverting on +overflow (when the input is greater than largest uint192). + +Counterpart to Solidity's `uint192` operator. + +Requirements: + +- input must fit into 192 bits + +[.contract-item] +[[SafeCast-toUint184-uint256-]] +==== `[.contract-item-name]#++toUint184++#++(uint256 value) → uint184++` [.item-kind]#internal# + +Returns the downcasted uint184 from uint256, reverting on +overflow (when the input is greater than largest uint184). + +Counterpart to Solidity's `uint184` operator. + +Requirements: + +- input must fit into 184 bits + +[.contract-item] +[[SafeCast-toUint176-uint256-]] +==== `[.contract-item-name]#++toUint176++#++(uint256 value) → uint176++` [.item-kind]#internal# + +Returns the downcasted uint176 from uint256, reverting on +overflow (when the input is greater than largest uint176). + +Counterpart to Solidity's `uint176` operator. + +Requirements: + +- input must fit into 176 bits + +[.contract-item] +[[SafeCast-toUint168-uint256-]] +==== `[.contract-item-name]#++toUint168++#++(uint256 value) → uint168++` [.item-kind]#internal# + +Returns the downcasted uint168 from uint256, reverting on +overflow (when the input is greater than largest uint168). + +Counterpart to Solidity's `uint168` operator. + +Requirements: + +- input must fit into 168 bits + +[.contract-item] +[[SafeCast-toUint160-uint256-]] +==== `[.contract-item-name]#++toUint160++#++(uint256 value) → uint160++` [.item-kind]#internal# + +Returns the downcasted uint160 from uint256, reverting on +overflow (when the input is greater than largest uint160). + +Counterpart to Solidity's `uint160` operator. + +Requirements: + +- input must fit into 160 bits + +[.contract-item] +[[SafeCast-toUint152-uint256-]] +==== `[.contract-item-name]#++toUint152++#++(uint256 value) → uint152++` [.item-kind]#internal# + +Returns the downcasted uint152 from uint256, reverting on +overflow (when the input is greater than largest uint152). + +Counterpart to Solidity's `uint152` operator. + +Requirements: + +- input must fit into 152 bits + +[.contract-item] +[[SafeCast-toUint144-uint256-]] +==== `[.contract-item-name]#++toUint144++#++(uint256 value) → uint144++` [.item-kind]#internal# + +Returns the downcasted uint144 from uint256, reverting on +overflow (when the input is greater than largest uint144). + +Counterpart to Solidity's `uint144` operator. + +Requirements: + +- input must fit into 144 bits + +[.contract-item] +[[SafeCast-toUint136-uint256-]] +==== `[.contract-item-name]#++toUint136++#++(uint256 value) → uint136++` [.item-kind]#internal# + +Returns the downcasted uint136 from uint256, reverting on +overflow (when the input is greater than largest uint136). + +Counterpart to Solidity's `uint136` operator. + +Requirements: + +- input must fit into 136 bits + +[.contract-item] +[[SafeCast-toUint128-uint256-]] +==== `[.contract-item-name]#++toUint128++#++(uint256 value) → uint128++` [.item-kind]#internal# + +Returns the downcasted uint128 from uint256, reverting on +overflow (when the input is greater than largest uint128). + +Counterpart to Solidity's `uint128` operator. + +Requirements: + +- input must fit into 128 bits + +[.contract-item] +[[SafeCast-toUint120-uint256-]] +==== `[.contract-item-name]#++toUint120++#++(uint256 value) → uint120++` [.item-kind]#internal# + +Returns the downcasted uint120 from uint256, reverting on +overflow (when the input is greater than largest uint120). + +Counterpart to Solidity's `uint120` operator. + +Requirements: + +- input must fit into 120 bits + +[.contract-item] +[[SafeCast-toUint112-uint256-]] +==== `[.contract-item-name]#++toUint112++#++(uint256 value) → uint112++` [.item-kind]#internal# + +Returns the downcasted uint112 from uint256, reverting on +overflow (when the input is greater than largest uint112). + +Counterpart to Solidity's `uint112` operator. + +Requirements: + +- input must fit into 112 bits + +[.contract-item] +[[SafeCast-toUint104-uint256-]] +==== `[.contract-item-name]#++toUint104++#++(uint256 value) → uint104++` [.item-kind]#internal# + +Returns the downcasted uint104 from uint256, reverting on +overflow (when the input is greater than largest uint104). + +Counterpart to Solidity's `uint104` operator. + +Requirements: + +- input must fit into 104 bits + +[.contract-item] +[[SafeCast-toUint96-uint256-]] +==== `[.contract-item-name]#++toUint96++#++(uint256 value) → uint96++` [.item-kind]#internal# + +Returns the downcasted uint96 from uint256, reverting on +overflow (when the input is greater than largest uint96). + +Counterpart to Solidity's `uint96` operator. + +Requirements: + +- input must fit into 96 bits + +[.contract-item] +[[SafeCast-toUint88-uint256-]] +==== `[.contract-item-name]#++toUint88++#++(uint256 value) → uint88++` [.item-kind]#internal# + +Returns the downcasted uint88 from uint256, reverting on +overflow (when the input is greater than largest uint88). + +Counterpart to Solidity's `uint88` operator. + +Requirements: + +- input must fit into 88 bits + +[.contract-item] +[[SafeCast-toUint80-uint256-]] +==== `[.contract-item-name]#++toUint80++#++(uint256 value) → uint80++` [.item-kind]#internal# + +Returns the downcasted uint80 from uint256, reverting on +overflow (when the input is greater than largest uint80). + +Counterpart to Solidity's `uint80` operator. + +Requirements: + +- input must fit into 80 bits + +[.contract-item] +[[SafeCast-toUint72-uint256-]] +==== `[.contract-item-name]#++toUint72++#++(uint256 value) → uint72++` [.item-kind]#internal# + +Returns the downcasted uint72 from uint256, reverting on +overflow (when the input is greater than largest uint72). + +Counterpart to Solidity's `uint72` operator. + +Requirements: + +- input must fit into 72 bits + +[.contract-item] +[[SafeCast-toUint64-uint256-]] +==== `[.contract-item-name]#++toUint64++#++(uint256 value) → uint64++` [.item-kind]#internal# + +Returns the downcasted uint64 from uint256, reverting on +overflow (when the input is greater than largest uint64). + +Counterpart to Solidity's `uint64` operator. + +Requirements: + +- input must fit into 64 bits + +[.contract-item] +[[SafeCast-toUint56-uint256-]] +==== `[.contract-item-name]#++toUint56++#++(uint256 value) → uint56++` [.item-kind]#internal# + +Returns the downcasted uint56 from uint256, reverting on +overflow (when the input is greater than largest uint56). + +Counterpart to Solidity's `uint56` operator. + +Requirements: + +- input must fit into 56 bits + +[.contract-item] +[[SafeCast-toUint48-uint256-]] +==== `[.contract-item-name]#++toUint48++#++(uint256 value) → uint48++` [.item-kind]#internal# + +Returns the downcasted uint48 from uint256, reverting on +overflow (when the input is greater than largest uint48). + +Counterpart to Solidity's `uint48` operator. + +Requirements: + +- input must fit into 48 bits + +[.contract-item] +[[SafeCast-toUint40-uint256-]] +==== `[.contract-item-name]#++toUint40++#++(uint256 value) → uint40++` [.item-kind]#internal# + +Returns the downcasted uint40 from uint256, reverting on +overflow (when the input is greater than largest uint40). + +Counterpart to Solidity's `uint40` operator. + +Requirements: + +- input must fit into 40 bits + +[.contract-item] +[[SafeCast-toUint32-uint256-]] +==== `[.contract-item-name]#++toUint32++#++(uint256 value) → uint32++` [.item-kind]#internal# + +Returns the downcasted uint32 from uint256, reverting on +overflow (when the input is greater than largest uint32). + +Counterpart to Solidity's `uint32` operator. + +Requirements: + +- input must fit into 32 bits + +[.contract-item] +[[SafeCast-toUint24-uint256-]] +==== `[.contract-item-name]#++toUint24++#++(uint256 value) → uint24++` [.item-kind]#internal# + +Returns the downcasted uint24 from uint256, reverting on +overflow (when the input is greater than largest uint24). + +Counterpart to Solidity's `uint24` operator. + +Requirements: + +- input must fit into 24 bits + +[.contract-item] +[[SafeCast-toUint16-uint256-]] +==== `[.contract-item-name]#++toUint16++#++(uint256 value) → uint16++` [.item-kind]#internal# + +Returns the downcasted uint16 from uint256, reverting on +overflow (when the input is greater than largest uint16). + +Counterpart to Solidity's `uint16` operator. + +Requirements: + +- input must fit into 16 bits + +[.contract-item] +[[SafeCast-toUint8-uint256-]] +==== `[.contract-item-name]#++toUint8++#++(uint256 value) → uint8++` [.item-kind]#internal# + +Returns the downcasted uint8 from uint256, reverting on +overflow (when the input is greater than largest uint8). + +Counterpart to Solidity's `uint8` operator. + +Requirements: + +- input must fit into 8 bits + +[.contract-item] +[[SafeCast-toUint256-int256-]] +==== `[.contract-item-name]#++toUint256++#++(int256 value) → uint256++` [.item-kind]#internal# + +Converts a signed int256 into an unsigned uint256. + +Requirements: + +- input must be greater than or equal to 0. + +[.contract-item] +[[SafeCast-toInt248-int256-]] +==== `[.contract-item-name]#++toInt248++#++(int256 value) → int248 downcasted++` [.item-kind]#internal# + +Returns the downcasted int248 from int256, reverting on +overflow (when the input is less than smallest int248 or +greater than largest int248). + +Counterpart to Solidity's `int248` operator. + +Requirements: + +- input must fit into 248 bits + +[.contract-item] +[[SafeCast-toInt240-int256-]] +==== `[.contract-item-name]#++toInt240++#++(int256 value) → int240 downcasted++` [.item-kind]#internal# + +Returns the downcasted int240 from int256, reverting on +overflow (when the input is less than smallest int240 or +greater than largest int240). + +Counterpart to Solidity's `int240` operator. + +Requirements: + +- input must fit into 240 bits + +[.contract-item] +[[SafeCast-toInt232-int256-]] +==== `[.contract-item-name]#++toInt232++#++(int256 value) → int232 downcasted++` [.item-kind]#internal# + +Returns the downcasted int232 from int256, reverting on +overflow (when the input is less than smallest int232 or +greater than largest int232). + +Counterpart to Solidity's `int232` operator. + +Requirements: + +- input must fit into 232 bits + +[.contract-item] +[[SafeCast-toInt224-int256-]] +==== `[.contract-item-name]#++toInt224++#++(int256 value) → int224 downcasted++` [.item-kind]#internal# + +Returns the downcasted int224 from int256, reverting on +overflow (when the input is less than smallest int224 or +greater than largest int224). + +Counterpart to Solidity's `int224` operator. + +Requirements: + +- input must fit into 224 bits + +[.contract-item] +[[SafeCast-toInt216-int256-]] +==== `[.contract-item-name]#++toInt216++#++(int256 value) → int216 downcasted++` [.item-kind]#internal# + +Returns the downcasted int216 from int256, reverting on +overflow (when the input is less than smallest int216 or +greater than largest int216). + +Counterpart to Solidity's `int216` operator. + +Requirements: + +- input must fit into 216 bits + +[.contract-item] +[[SafeCast-toInt208-int256-]] +==== `[.contract-item-name]#++toInt208++#++(int256 value) → int208 downcasted++` [.item-kind]#internal# + +Returns the downcasted int208 from int256, reverting on +overflow (when the input is less than smallest int208 or +greater than largest int208). + +Counterpart to Solidity's `int208` operator. + +Requirements: + +- input must fit into 208 bits + +[.contract-item] +[[SafeCast-toInt200-int256-]] +==== `[.contract-item-name]#++toInt200++#++(int256 value) → int200 downcasted++` [.item-kind]#internal# + +Returns the downcasted int200 from int256, reverting on +overflow (when the input is less than smallest int200 or +greater than largest int200). + +Counterpart to Solidity's `int200` operator. + +Requirements: + +- input must fit into 200 bits + +[.contract-item] +[[SafeCast-toInt192-int256-]] +==== `[.contract-item-name]#++toInt192++#++(int256 value) → int192 downcasted++` [.item-kind]#internal# + +Returns the downcasted int192 from int256, reverting on +overflow (when the input is less than smallest int192 or +greater than largest int192). + +Counterpart to Solidity's `int192` operator. + +Requirements: + +- input must fit into 192 bits + +[.contract-item] +[[SafeCast-toInt184-int256-]] +==== `[.contract-item-name]#++toInt184++#++(int256 value) → int184 downcasted++` [.item-kind]#internal# + +Returns the downcasted int184 from int256, reverting on +overflow (when the input is less than smallest int184 or +greater than largest int184). + +Counterpart to Solidity's `int184` operator. + +Requirements: + +- input must fit into 184 bits + +[.contract-item] +[[SafeCast-toInt176-int256-]] +==== `[.contract-item-name]#++toInt176++#++(int256 value) → int176 downcasted++` [.item-kind]#internal# + +Returns the downcasted int176 from int256, reverting on +overflow (when the input is less than smallest int176 or +greater than largest int176). + +Counterpart to Solidity's `int176` operator. + +Requirements: + +- input must fit into 176 bits + +[.contract-item] +[[SafeCast-toInt168-int256-]] +==== `[.contract-item-name]#++toInt168++#++(int256 value) → int168 downcasted++` [.item-kind]#internal# + +Returns the downcasted int168 from int256, reverting on +overflow (when the input is less than smallest int168 or +greater than largest int168). + +Counterpart to Solidity's `int168` operator. + +Requirements: + +- input must fit into 168 bits + +[.contract-item] +[[SafeCast-toInt160-int256-]] +==== `[.contract-item-name]#++toInt160++#++(int256 value) → int160 downcasted++` [.item-kind]#internal# + +Returns the downcasted int160 from int256, reverting on +overflow (when the input is less than smallest int160 or +greater than largest int160). + +Counterpart to Solidity's `int160` operator. + +Requirements: + +- input must fit into 160 bits + +[.contract-item] +[[SafeCast-toInt152-int256-]] +==== `[.contract-item-name]#++toInt152++#++(int256 value) → int152 downcasted++` [.item-kind]#internal# + +Returns the downcasted int152 from int256, reverting on +overflow (when the input is less than smallest int152 or +greater than largest int152). + +Counterpart to Solidity's `int152` operator. + +Requirements: + +- input must fit into 152 bits + +[.contract-item] +[[SafeCast-toInt144-int256-]] +==== `[.contract-item-name]#++toInt144++#++(int256 value) → int144 downcasted++` [.item-kind]#internal# + +Returns the downcasted int144 from int256, reverting on +overflow (when the input is less than smallest int144 or +greater than largest int144). + +Counterpart to Solidity's `int144` operator. + +Requirements: + +- input must fit into 144 bits + +[.contract-item] +[[SafeCast-toInt136-int256-]] +==== `[.contract-item-name]#++toInt136++#++(int256 value) → int136 downcasted++` [.item-kind]#internal# + +Returns the downcasted int136 from int256, reverting on +overflow (when the input is less than smallest int136 or +greater than largest int136). + +Counterpart to Solidity's `int136` operator. + +Requirements: + +- input must fit into 136 bits + +[.contract-item] +[[SafeCast-toInt128-int256-]] +==== `[.contract-item-name]#++toInt128++#++(int256 value) → int128 downcasted++` [.item-kind]#internal# + +Returns the downcasted int128 from int256, reverting on +overflow (when the input is less than smallest int128 or +greater than largest int128). + +Counterpart to Solidity's `int128` operator. + +Requirements: + +- input must fit into 128 bits + +[.contract-item] +[[SafeCast-toInt120-int256-]] +==== `[.contract-item-name]#++toInt120++#++(int256 value) → int120 downcasted++` [.item-kind]#internal# + +Returns the downcasted int120 from int256, reverting on +overflow (when the input is less than smallest int120 or +greater than largest int120). + +Counterpart to Solidity's `int120` operator. + +Requirements: + +- input must fit into 120 bits + +[.contract-item] +[[SafeCast-toInt112-int256-]] +==== `[.contract-item-name]#++toInt112++#++(int256 value) → int112 downcasted++` [.item-kind]#internal# + +Returns the downcasted int112 from int256, reverting on +overflow (when the input is less than smallest int112 or +greater than largest int112). + +Counterpart to Solidity's `int112` operator. + +Requirements: + +- input must fit into 112 bits + +[.contract-item] +[[SafeCast-toInt104-int256-]] +==== `[.contract-item-name]#++toInt104++#++(int256 value) → int104 downcasted++` [.item-kind]#internal# + +Returns the downcasted int104 from int256, reverting on +overflow (when the input is less than smallest int104 or +greater than largest int104). + +Counterpart to Solidity's `int104` operator. + +Requirements: + +- input must fit into 104 bits + +[.contract-item] +[[SafeCast-toInt96-int256-]] +==== `[.contract-item-name]#++toInt96++#++(int256 value) → int96 downcasted++` [.item-kind]#internal# + +Returns the downcasted int96 from int256, reverting on +overflow (when the input is less than smallest int96 or +greater than largest int96). + +Counterpart to Solidity's `int96` operator. + +Requirements: + +- input must fit into 96 bits + +[.contract-item] +[[SafeCast-toInt88-int256-]] +==== `[.contract-item-name]#++toInt88++#++(int256 value) → int88 downcasted++` [.item-kind]#internal# + +Returns the downcasted int88 from int256, reverting on +overflow (when the input is less than smallest int88 or +greater than largest int88). + +Counterpart to Solidity's `int88` operator. + +Requirements: + +- input must fit into 88 bits + +[.contract-item] +[[SafeCast-toInt80-int256-]] +==== `[.contract-item-name]#++toInt80++#++(int256 value) → int80 downcasted++` [.item-kind]#internal# + +Returns the downcasted int80 from int256, reverting on +overflow (when the input is less than smallest int80 or +greater than largest int80). + +Counterpart to Solidity's `int80` operator. + +Requirements: + +- input must fit into 80 bits + +[.contract-item] +[[SafeCast-toInt72-int256-]] +==== `[.contract-item-name]#++toInt72++#++(int256 value) → int72 downcasted++` [.item-kind]#internal# + +Returns the downcasted int72 from int256, reverting on +overflow (when the input is less than smallest int72 or +greater than largest int72). + +Counterpart to Solidity's `int72` operator. + +Requirements: + +- input must fit into 72 bits + +[.contract-item] +[[SafeCast-toInt64-int256-]] +==== `[.contract-item-name]#++toInt64++#++(int256 value) → int64 downcasted++` [.item-kind]#internal# + +Returns the downcasted int64 from int256, reverting on +overflow (when the input is less than smallest int64 or +greater than largest int64). + +Counterpart to Solidity's `int64` operator. + +Requirements: + +- input must fit into 64 bits + +[.contract-item] +[[SafeCast-toInt56-int256-]] +==== `[.contract-item-name]#++toInt56++#++(int256 value) → int56 downcasted++` [.item-kind]#internal# + +Returns the downcasted int56 from int256, reverting on +overflow (when the input is less than smallest int56 or +greater than largest int56). + +Counterpart to Solidity's `int56` operator. + +Requirements: + +- input must fit into 56 bits + +[.contract-item] +[[SafeCast-toInt48-int256-]] +==== `[.contract-item-name]#++toInt48++#++(int256 value) → int48 downcasted++` [.item-kind]#internal# + +Returns the downcasted int48 from int256, reverting on +overflow (when the input is less than smallest int48 or +greater than largest int48). + +Counterpart to Solidity's `int48` operator. + +Requirements: + +- input must fit into 48 bits + +[.contract-item] +[[SafeCast-toInt40-int256-]] +==== `[.contract-item-name]#++toInt40++#++(int256 value) → int40 downcasted++` [.item-kind]#internal# + +Returns the downcasted int40 from int256, reverting on +overflow (when the input is less than smallest int40 or +greater than largest int40). + +Counterpart to Solidity's `int40` operator. + +Requirements: + +- input must fit into 40 bits + +[.contract-item] +[[SafeCast-toInt32-int256-]] +==== `[.contract-item-name]#++toInt32++#++(int256 value) → int32 downcasted++` [.item-kind]#internal# + +Returns the downcasted int32 from int256, reverting on +overflow (when the input is less than smallest int32 or +greater than largest int32). + +Counterpart to Solidity's `int32` operator. + +Requirements: + +- input must fit into 32 bits + +[.contract-item] +[[SafeCast-toInt24-int256-]] +==== `[.contract-item-name]#++toInt24++#++(int256 value) → int24 downcasted++` [.item-kind]#internal# + +Returns the downcasted int24 from int256, reverting on +overflow (when the input is less than smallest int24 or +greater than largest int24). + +Counterpart to Solidity's `int24` operator. + +Requirements: + +- input must fit into 24 bits + +[.contract-item] +[[SafeCast-toInt16-int256-]] +==== `[.contract-item-name]#++toInt16++#++(int256 value) → int16 downcasted++` [.item-kind]#internal# + +Returns the downcasted int16 from int256, reverting on +overflow (when the input is less than smallest int16 or +greater than largest int16). + +Counterpart to Solidity's `int16` operator. + +Requirements: + +- input must fit into 16 bits + +[.contract-item] +[[SafeCast-toInt8-int256-]] +==== `[.contract-item-name]#++toInt8++#++(int256 value) → int8 downcasted++` [.item-kind]#internal# + +Returns the downcasted int8 from int256, reverting on +overflow (when the input is less than smallest int8 or +greater than largest int8). + +Counterpart to Solidity's `int8` operator. + +Requirements: + +- input must fit into 8 bits + +[.contract-item] +[[SafeCast-toInt256-uint256-]] +==== `[.contract-item-name]#++toInt256++#++(uint256 value) → int256++` [.item-kind]#internal# + +Converts an unsigned uint256 into a signed int256. + +Requirements: + +- input must be less than or equal to maxInt256. + +[.contract-item] +[[SafeCast-SafeCastOverflowedUintDowncast-uint8-uint256-]] +==== `[.contract-item-name]#++SafeCastOverflowedUintDowncast++#++(uint8 bits, uint256 value)++` [.item-kind]#error# + +Value doesn't fit in an uint of `bits` size. + +[.contract-item] +[[SafeCast-SafeCastOverflowedIntToUint-int256-]] +==== `[.contract-item-name]#++SafeCastOverflowedIntToUint++#++(int256 value)++` [.item-kind]#error# + +An int value doesn't fit in an uint of `bits` size. + +[.contract-item] +[[SafeCast-SafeCastOverflowedIntDowncast-uint8-int256-]] +==== `[.contract-item-name]#++SafeCastOverflowedIntDowncast++#++(uint8 bits, int256 value)++` [.item-kind]#error# + +Value doesn't fit in an int of `bits` size. + +[.contract-item] +[[SafeCast-SafeCastOverflowedUintToInt-uint256-]] +==== `[.contract-item-name]#++SafeCastOverflowedUintToInt++#++(uint256 value)++` [.item-kind]#error# + +An uint value doesn't fit in an int of `bits` size. + +== Cryptography + +:RecoverError: pass:normal[xref:#ECDSA-RecoverError[`++RecoverError++`]] +:ECDSAInvalidSignature: pass:normal[xref:#ECDSA-ECDSAInvalidSignature--[`++ECDSAInvalidSignature++`]] +:ECDSAInvalidSignatureLength: pass:normal[xref:#ECDSA-ECDSAInvalidSignatureLength-uint256-[`++ECDSAInvalidSignatureLength++`]] +:ECDSAInvalidSignatureS: pass:normal[xref:#ECDSA-ECDSAInvalidSignatureS-bytes32-[`++ECDSAInvalidSignatureS++`]] +:tryRecover: pass:normal[xref:#ECDSA-tryRecover-bytes32-bytes-[`++tryRecover++`]] +:recover: pass:normal[xref:#ECDSA-recover-bytes32-bytes-[`++recover++`]] +:tryRecover: pass:normal[xref:#ECDSA-tryRecover-bytes32-bytes32-bytes32-[`++tryRecover++`]] +:recover: pass:normal[xref:#ECDSA-recover-bytes32-bytes32-bytes32-[`++recover++`]] +:tryRecover: pass:normal[xref:#ECDSA-tryRecover-bytes32-uint8-bytes32-bytes32-[`++tryRecover++`]] +:recover: pass:normal[xref:#ECDSA-recover-bytes32-uint8-bytes32-bytes32-[`++recover++`]] + +[.contract] +[[ECDSA]] +=== `++ECDSA++` link:https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v5.0.0-rc.0/contracts/utils/cryptography/ECDSA.sol[{github-icon},role=heading-link] + +[.hljs-theme-light.nopadding] +```solidity +import "@openzeppelin/contracts/utils/cryptography/ECDSA.sol"; +``` + +Elliptic Curve Digital Signature Algorithm (ECDSA) operations. + +These functions can be used to verify that a message was signed by the holder +of the private keys of a given address. + +[.contract-index] +.Functions +-- +* {xref-ECDSA-tryRecover-bytes32-bytes-}[`++tryRecover(hash, signature)++`] +* {xref-ECDSA-recover-bytes32-bytes-}[`++recover(hash, signature)++`] +* {xref-ECDSA-tryRecover-bytes32-bytes32-bytes32-}[`++tryRecover(hash, r, vs)++`] +* {xref-ECDSA-recover-bytes32-bytes32-bytes32-}[`++recover(hash, r, vs)++`] +* {xref-ECDSA-tryRecover-bytes32-uint8-bytes32-bytes32-}[`++tryRecover(hash, v, r, s)++`] +* {xref-ECDSA-recover-bytes32-uint8-bytes32-bytes32-}[`++recover(hash, v, r, s)++`] + +-- + +[.contract-index] +.Errors +-- +* {xref-ECDSA-ECDSAInvalidSignature--}[`++ECDSAInvalidSignature()++`] +* {xref-ECDSA-ECDSAInvalidSignatureLength-uint256-}[`++ECDSAInvalidSignatureLength(length)++`] +* {xref-ECDSA-ECDSAInvalidSignatureS-bytes32-}[`++ECDSAInvalidSignatureS(s)++`] + +-- + +[.contract-item] +[[ECDSA-tryRecover-bytes32-bytes-]] +==== `[.contract-item-name]#++tryRecover++#++(bytes32 hash, bytes signature) → address, enum ECDSA.RecoverError, bytes32++` [.item-kind]#internal# + +Returns the address that signed a hashed message (`hash`) with `signature` or an error. This will not +return address(0) without also returning an error description. Errors are documented using an enum (error type) +and a bytes32 providing additional information about the error. + +If no error is returned, then the address can be used for verification purposes. + +The `ecrecover` EVM precompile allows for malleable (non-unique) signatures: +this function rejects them by requiring the `s` value to be in the lower +half order, and the `v` value to be either 27 or 28. + +IMPORTANT: `hash` _must_ be the result of a hash operation for the +verification to be secure: it is possible to craft signatures that +recover to arbitrary addresses for non-hashed data. A safe way to ensure +this is by receiving a hash of the original message (which may otherwise +be too long), and then calling {MessageHashUtils-toEthSignedMessageHash} on it. + +Documentation for signature generation: +- with https://web3js.readthedocs.io/en/v1.3.4/web3-eth-accounts.html#sign[Web3.js] +- with https://docs.ethers.io/v5/api/signer/#Signer-signMessage[ethers] + +[.contract-item] +[[ECDSA-recover-bytes32-bytes-]] +==== `[.contract-item-name]#++recover++#++(bytes32 hash, bytes signature) → address++` [.item-kind]#internal# + +Returns the address that signed a hashed message (`hash`) with +`signature`. This address can then be used for verification purposes. + +The `ecrecover` EVM precompile allows for malleable (non-unique) signatures: +this function rejects them by requiring the `s` value to be in the lower +half order, and the `v` value to be either 27 or 28. + +IMPORTANT: `hash` _must_ be the result of a hash operation for the +verification to be secure: it is possible to craft signatures that +recover to arbitrary addresses for non-hashed data. A safe way to ensure +this is by receiving a hash of the original message (which may otherwise +be too long), and then calling {MessageHashUtils-toEthSignedMessageHash} on it. + +[.contract-item] +[[ECDSA-tryRecover-bytes32-bytes32-bytes32-]] +==== `[.contract-item-name]#++tryRecover++#++(bytes32 hash, bytes32 r, bytes32 vs) → address, enum ECDSA.RecoverError, bytes32++` [.item-kind]#internal# + +Overload of {ECDSA-tryRecover} that receives the `r` and `vs` short-signature fields separately. + +See https://eips.ethereum.org/EIPS/eip-2098[EIP-2098 short signatures] + +[.contract-item] +[[ECDSA-recover-bytes32-bytes32-bytes32-]] +==== `[.contract-item-name]#++recover++#++(bytes32 hash, bytes32 r, bytes32 vs) → address++` [.item-kind]#internal# + +Overload of {ECDSA-recover} that receives the `r and `vs` short-signature fields separately. + +[.contract-item] +[[ECDSA-tryRecover-bytes32-uint8-bytes32-bytes32-]] +==== `[.contract-item-name]#++tryRecover++#++(bytes32 hash, uint8 v, bytes32 r, bytes32 s) → address, enum ECDSA.RecoverError, bytes32++` [.item-kind]#internal# + +Overload of {ECDSA-tryRecover} that receives the `v`, +`r` and `s` signature fields separately. + +[.contract-item] +[[ECDSA-recover-bytes32-uint8-bytes32-bytes32-]] +==== `[.contract-item-name]#++recover++#++(bytes32 hash, uint8 v, bytes32 r, bytes32 s) → address++` [.item-kind]#internal# + +Overload of {ECDSA-recover} that receives the `v`, +`r` and `s` signature fields separately. + +[.contract-item] +[[ECDSA-ECDSAInvalidSignature--]] +==== `[.contract-item-name]#++ECDSAInvalidSignature++#++()++` [.item-kind]#error# + +The signature derives the `address(0)`. + +[.contract-item] +[[ECDSA-ECDSAInvalidSignatureLength-uint256-]] +==== `[.contract-item-name]#++ECDSAInvalidSignatureLength++#++(uint256 length)++` [.item-kind]#error# + +The signature has an invalid length. + +[.contract-item] +[[ECDSA-ECDSAInvalidSignatureS-bytes32-]] +==== `[.contract-item-name]#++ECDSAInvalidSignatureS++#++(bytes32 s)++` [.item-kind]#error# + +The signature has an S value that is in the upper half order. + +:toEthSignedMessageHash: pass:normal[xref:#MessageHashUtils-toEthSignedMessageHash-bytes32-[`++toEthSignedMessageHash++`]] +:toEthSignedMessageHash: pass:normal[xref:#MessageHashUtils-toEthSignedMessageHash-bytes-[`++toEthSignedMessageHash++`]] +:toDataWithIntendedValidatorHash: pass:normal[xref:#MessageHashUtils-toDataWithIntendedValidatorHash-address-bytes-[`++toDataWithIntendedValidatorHash++`]] +:toTypedDataHash: pass:normal[xref:#MessageHashUtils-toTypedDataHash-bytes32-bytes32-[`++toTypedDataHash++`]] + +[.contract] +[[MessageHashUtils]] +=== `++MessageHashUtils++` link:https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v5.0.0-rc.0/contracts/utils/cryptography/MessageHashUtils.sol[{github-icon},role=heading-link] + +[.hljs-theme-light.nopadding] +```solidity +import "@openzeppelin/contracts/utils/cryptography/MessageHashUtils.sol"; +``` + +Signature message hash utilities for producing digests to be consumed by {ECDSA} recovery or signing. + +The library provides methods for generating a hash of a message that conforms to the +https://eips.ethereum.org/EIPS/eip-191[EIP 191] and https://eips.ethereum.org/EIPS/eip-712[EIP 712] +specifications. + +[.contract-index] +.Functions +-- +* {xref-MessageHashUtils-toEthSignedMessageHash-bytes32-}[`++toEthSignedMessageHash(messageHash)++`] +* {xref-MessageHashUtils-toEthSignedMessageHash-bytes-}[`++toEthSignedMessageHash(message)++`] +* {xref-MessageHashUtils-toDataWithIntendedValidatorHash-address-bytes-}[`++toDataWithIntendedValidatorHash(validator, data)++`] +* {xref-MessageHashUtils-toTypedDataHash-bytes32-bytes32-}[`++toTypedDataHash(domainSeparator, structHash)++`] + +-- + +[.contract-item] +[[MessageHashUtils-toEthSignedMessageHash-bytes32-]] +==== `[.contract-item-name]#++toEthSignedMessageHash++#++(bytes32 messageHash) → bytes32 digest++` [.item-kind]#internal# + +Returns the keccak256 digest of an EIP-191 signed data with version +`0x45` (`personal_sign` messages). + +The digest is calculated by prefixing a bytes32 `messageHash` with +`"\x19Ethereum Signed Message:\n32"` and hashing the result. It corresponds with the +hash signed when using the https://eth.wiki/json-rpc/API#eth_sign[`eth_sign`] JSON-RPC method. + +NOTE: The `messageHash` parameter is intended to be the result of hashing a raw message with +keccak256, although any bytes32 value can be safely used because the final digest will +be re-hashed. + +See {ECDSA-recover}. + +[.contract-item] +[[MessageHashUtils-toEthSignedMessageHash-bytes-]] +==== `[.contract-item-name]#++toEthSignedMessageHash++#++(bytes message) → bytes32++` [.item-kind]#internal# + +Returns the keccak256 digest of an EIP-191 signed data with version +`0x45` (`personal_sign` messages). + +The digest is calculated by prefixing an arbitrary `message` with +`"\x19Ethereum Signed Message:\n" + len(message)` and hashing the result. It corresponds with the +hash signed when using the https://eth.wiki/json-rpc/API#eth_sign[`eth_sign`] JSON-RPC method. + +See {ECDSA-recover}. + +[.contract-item] +[[MessageHashUtils-toDataWithIntendedValidatorHash-address-bytes-]] +==== `[.contract-item-name]#++toDataWithIntendedValidatorHash++#++(address validator, bytes data) → bytes32++` [.item-kind]#internal# + +Returns the keccak256 digest of an EIP-191 signed data with version +`0x00` (data with intended validator). + +The digest is calculated by prefixing an arbitrary `data` with `"\x19\x00"` and the intended +`validator` address. Then hashing the result. + +See {ECDSA-recover}. + +[.contract-item] +[[MessageHashUtils-toTypedDataHash-bytes32-bytes32-]] +==== `[.contract-item-name]#++toTypedDataHash++#++(bytes32 domainSeparator, bytes32 structHash) → bytes32 digest++` [.item-kind]#internal# + +Returns the keccak256 digest of an EIP-712 typed data (EIP-191 version `0x01`). + +The digest is calculated from a `domainSeparator` and a `structHash`, by prefixing them with +`\x19\x01` and hashing the result. It corresponds to the hash signed by the +https://eips.ethereum.org/EIPS/eip-712[`eth_signTypedData`] JSON-RPC method as part of EIP-712. + +See {ECDSA-recover}. + +:isValidSignatureNow: pass:normal[xref:#SignatureChecker-isValidSignatureNow-address-bytes32-bytes-[`++isValidSignatureNow++`]] +:isValidERC1271SignatureNow: pass:normal[xref:#SignatureChecker-isValidERC1271SignatureNow-address-bytes32-bytes-[`++isValidERC1271SignatureNow++`]] + +[.contract] +[[SignatureChecker]] +=== `++SignatureChecker++` link:https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v5.0.0-rc.0/contracts/utils/cryptography/SignatureChecker.sol[{github-icon},role=heading-link] + +[.hljs-theme-light.nopadding] +```solidity +import "@openzeppelin/contracts/utils/cryptography/SignatureChecker.sol"; +``` + +Signature verification helper that can be used instead of `ECDSA.recover` to seamlessly support both ECDSA +signatures from externally owned accounts (EOAs) as well as ERC1271 signatures from smart contract wallets like +Argent and Safe Wallet (previously Gnosis Safe). + +[.contract-index] +.Functions +-- +* {xref-SignatureChecker-isValidSignatureNow-address-bytes32-bytes-}[`++isValidSignatureNow(signer, hash, signature)++`] +* {xref-SignatureChecker-isValidERC1271SignatureNow-address-bytes32-bytes-}[`++isValidERC1271SignatureNow(signer, hash, signature)++`] + +-- + +[.contract-item] +[[SignatureChecker-isValidSignatureNow-address-bytes32-bytes-]] +==== `[.contract-item-name]#++isValidSignatureNow++#++(address signer, bytes32 hash, bytes signature) → bool++` [.item-kind]#internal# + +Checks if a signature is valid for a given signer and data hash. If the signer is a smart contract, the +signature is validated against that smart contract using ERC1271, otherwise it's validated using `ECDSA.recover`. + +NOTE: Unlike ECDSA signatures, contract signatures are revocable, and the outcome of this function can thus +change through time. It could return true at block N and false at block N+1 (or the opposite). + +[.contract-item] +[[SignatureChecker-isValidERC1271SignatureNow-address-bytes32-bytes-]] +==== `[.contract-item-name]#++isValidERC1271SignatureNow++#++(address signer, bytes32 hash, bytes signature) → bool++` [.item-kind]#internal# + +Checks if a signature is valid for a given signer and data hash. The signature is validated +against the signer smart contract using ERC1271. + +NOTE: Unlike ECDSA signatures, contract signatures are revocable, and the outcome of this function can thus +change through time. It could return true at block N and false at block N+1 (or the opposite). + +:MerkleProofInvalidMultiproof: pass:normal[xref:#MerkleProof-MerkleProofInvalidMultiproof--[`++MerkleProofInvalidMultiproof++`]] +:verify: pass:normal[xref:#MerkleProof-verify-bytes32---bytes32-bytes32-[`++verify++`]] +:verifyCalldata: pass:normal[xref:#MerkleProof-verifyCalldata-bytes32---bytes32-bytes32-[`++verifyCalldata++`]] +:processProof: pass:normal[xref:#MerkleProof-processProof-bytes32---bytes32-[`++processProof++`]] +:processProofCalldata: pass:normal[xref:#MerkleProof-processProofCalldata-bytes32---bytes32-[`++processProofCalldata++`]] +:multiProofVerify: pass:normal[xref:#MerkleProof-multiProofVerify-bytes32---bool---bytes32-bytes32---[`++multiProofVerify++`]] +:multiProofVerifyCalldata: pass:normal[xref:#MerkleProof-multiProofVerifyCalldata-bytes32---bool---bytes32-bytes32---[`++multiProofVerifyCalldata++`]] +:processMultiProof: pass:normal[xref:#MerkleProof-processMultiProof-bytes32---bool---bytes32---[`++processMultiProof++`]] +:processMultiProofCalldata: pass:normal[xref:#MerkleProof-processMultiProofCalldata-bytes32---bool---bytes32---[`++processMultiProofCalldata++`]] + +[.contract] +[[MerkleProof]] +=== `++MerkleProof++` link:https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v5.0.0-rc.0/contracts/utils/cryptography/MerkleProof.sol[{github-icon},role=heading-link] + +[.hljs-theme-light.nopadding] +```solidity +import "@openzeppelin/contracts/utils/cryptography/MerkleProof.sol"; +``` + +These functions deal with verification of Merkle Tree proofs. + +The tree and the proofs can be generated using our +https://github.com/OpenZeppelin/merkle-tree[JavaScript library]. +You will find a quickstart guide in the readme. + +WARNING: You should avoid using leaf values that are 64 bytes long prior to +hashing, or use a hash function other than keccak256 for hashing leaves. +This is because the concatenation of a sorted pair of internal nodes in +the Merkle tree could be reinterpreted as a leaf value. +OpenZeppelin's JavaScript library generates Merkle trees that are safe +against this attack out of the box. + +[.contract-index] +.Functions +-- +* {xref-MerkleProof-verify-bytes32---bytes32-bytes32-}[`++verify(proof, root, leaf)++`] +* {xref-MerkleProof-verifyCalldata-bytes32---bytes32-bytes32-}[`++verifyCalldata(proof, root, leaf)++`] +* {xref-MerkleProof-processProof-bytes32---bytes32-}[`++processProof(proof, leaf)++`] +* {xref-MerkleProof-processProofCalldata-bytes32---bytes32-}[`++processProofCalldata(proof, leaf)++`] +* {xref-MerkleProof-multiProofVerify-bytes32---bool---bytes32-bytes32---}[`++multiProofVerify(proof, proofFlags, root, leaves)++`] +* {xref-MerkleProof-multiProofVerifyCalldata-bytes32---bool---bytes32-bytes32---}[`++multiProofVerifyCalldata(proof, proofFlags, root, leaves)++`] +* {xref-MerkleProof-processMultiProof-bytes32---bool---bytes32---}[`++processMultiProof(proof, proofFlags, leaves)++`] +* {xref-MerkleProof-processMultiProofCalldata-bytes32---bool---bytes32---}[`++processMultiProofCalldata(proof, proofFlags, leaves)++`] + +-- + +[.contract-index] +.Errors +-- +* {xref-MerkleProof-MerkleProofInvalidMultiproof--}[`++MerkleProofInvalidMultiproof()++`] + +-- + +[.contract-item] +[[MerkleProof-verify-bytes32---bytes32-bytes32-]] +==== `[.contract-item-name]#++verify++#++(bytes32[] proof, bytes32 root, bytes32 leaf) → bool++` [.item-kind]#internal# + +Returns true if a `leaf` can be proved to be a part of a Merkle tree +defined by `root`. For this, a `proof` must be provided, containing +sibling hashes on the branch from the leaf to the root of the tree. Each +pair of leaves and each pair of pre-images are assumed to be sorted. + +[.contract-item] +[[MerkleProof-verifyCalldata-bytes32---bytes32-bytes32-]] +==== `[.contract-item-name]#++verifyCalldata++#++(bytes32[] proof, bytes32 root, bytes32 leaf) → bool++` [.item-kind]#internal# + +Calldata version of {verify} + +[.contract-item] +[[MerkleProof-processProof-bytes32---bytes32-]] +==== `[.contract-item-name]#++processProof++#++(bytes32[] proof, bytes32 leaf) → bytes32++` [.item-kind]#internal# + +Returns the rebuilt hash obtained by traversing a Merkle tree up +from `leaf` using `proof`. A `proof` is valid if and only if the rebuilt +hash matches the root of the tree. When processing the proof, the pairs +of leafs & pre-images are assumed to be sorted. + +[.contract-item] +[[MerkleProof-processProofCalldata-bytes32---bytes32-]] +==== `[.contract-item-name]#++processProofCalldata++#++(bytes32[] proof, bytes32 leaf) → bytes32++` [.item-kind]#internal# + +Calldata version of {processProof} + +[.contract-item] +[[MerkleProof-multiProofVerify-bytes32---bool---bytes32-bytes32---]] +==== `[.contract-item-name]#++multiProofVerify++#++(bytes32[] proof, bool[] proofFlags, bytes32 root, bytes32[] leaves) → bool++` [.item-kind]#internal# + +Returns true if the `leaves` can be simultaneously proven to be a part of a Merkle tree defined by +`root`, according to `proof` and `proofFlags` as described in {processMultiProof}. + +CAUTION: Not all Merkle trees admit multiproofs. See {processMultiProof} for details. + +[.contract-item] +[[MerkleProof-multiProofVerifyCalldata-bytes32---bool---bytes32-bytes32---]] +==== `[.contract-item-name]#++multiProofVerifyCalldata++#++(bytes32[] proof, bool[] proofFlags, bytes32 root, bytes32[] leaves) → bool++` [.item-kind]#internal# + +Calldata version of {multiProofVerify} + +CAUTION: Not all Merkle trees admit multiproofs. See {processMultiProof} for details. + +[.contract-item] +[[MerkleProof-processMultiProof-bytes32---bool---bytes32---]] +==== `[.contract-item-name]#++processMultiProof++#++(bytes32[] proof, bool[] proofFlags, bytes32[] leaves) → bytes32 merkleRoot++` [.item-kind]#internal# + +Returns the root of a tree reconstructed from `leaves` and sibling nodes in `proof`. The reconstruction +proceeds by incrementally reconstructing all inner nodes by combining a leaf/inner node with either another +leaf/inner node or a proof sibling node, depending on whether each `proofFlags` item is true or false +respectively. + +CAUTION: Not all Merkle trees admit multiproofs. To use multiproofs, it is sufficient to ensure that: 1) the tree +is complete (but not necessarily perfect), 2) the leaves to be proven are in the opposite order they are in the +tree (i.e., as seen from right to left starting at the deepest layer and continuing at the next layer). + +[.contract-item] +[[MerkleProof-processMultiProofCalldata-bytes32---bool---bytes32---]] +==== `[.contract-item-name]#++processMultiProofCalldata++#++(bytes32[] proof, bool[] proofFlags, bytes32[] leaves) → bytes32 merkleRoot++` [.item-kind]#internal# + +Calldata version of {processMultiProof}. + +CAUTION: Not all Merkle trees admit multiproofs. See {processMultiProof} for details. + +[.contract-item] +[[MerkleProof-MerkleProofInvalidMultiproof--]] +==== `[.contract-item-name]#++MerkleProofInvalidMultiproof++#++()++` [.item-kind]#error# + +The multiproof provided is not valid. + +:constructor: pass:normal[xref:#EIP712-constructor-string-string-[`++constructor++`]] +:_domainSeparatorV4: pass:normal[xref:#EIP712-_domainSeparatorV4--[`++_domainSeparatorV4++`]] +:_hashTypedDataV4: pass:normal[xref:#EIP712-_hashTypedDataV4-bytes32-[`++_hashTypedDataV4++`]] +:eip712Domain: pass:normal[xref:#EIP712-eip712Domain--[`++eip712Domain++`]] +:_EIP712Name: pass:normal[xref:#EIP712-_EIP712Name--[`++_EIP712Name++`]] +:_EIP712Version: pass:normal[xref:#EIP712-_EIP712Version--[`++_EIP712Version++`]] + +[.contract] +[[EIP712]] +=== `++EIP712++` link:https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v5.0.0-rc.0/contracts/utils/cryptography/EIP712.sol[{github-icon},role=heading-link] + +[.hljs-theme-light.nopadding] +```solidity +import "@openzeppelin/contracts/utils/cryptography/EIP712.sol"; +``` + +https://eips.ethereum.org/EIPS/eip-712[EIP 712] is a standard for hashing and signing of typed structured data. + +The encoding scheme specified in the EIP requires a domain separator and a hash of the typed structured data, whose +encoding is very generic and therefore its implementation in Solidity is not feasible, thus this contract +does not implement the encoding itself. Protocols need to implement the type-specific encoding they need in order to +produce the hash of their typed data using a combination of `abi.encode` and `keccak256`. + +This contract implements the EIP 712 domain separator ({_domainSeparatorV4}) that is used as part of the encoding +scheme, and the final step of the encoding to obtain the message digest that is then signed via ECDSA +({_hashTypedDataV4}). + +The implementation of the domain separator was designed to be as efficient as possible while still properly updating +the chain id to protect against replay attacks on an eventual fork of the chain. + +NOTE: This contract implements the version of the encoding known as "v4", as implemented by the JSON RPC method +https://docs.metamask.io/guide/signing-data.html[`eth_signTypedDataV4` in MetaMask]. + +NOTE: In the upgradeable version of this contract, the cached values will correspond to the address, and the domain +separator of the implementation contract. This will cause the {_domainSeparatorV4} function to always rebuild the +separator from the immutable values, which is cheaper than accessing a cached version in cold storage. + +[.contract-index] +.Functions +-- +* {xref-EIP712-constructor-string-string-}[`++constructor(name, version)++`] +* {xref-EIP712-_domainSeparatorV4--}[`++_domainSeparatorV4()++`] +* {xref-EIP712-_hashTypedDataV4-bytes32-}[`++_hashTypedDataV4(structHash)++`] +* {xref-EIP712-eip712Domain--}[`++eip712Domain()++`] +* {xref-EIP712-_EIP712Name--}[`++_EIP712Name()++`] +* {xref-EIP712-_EIP712Version--}[`++_EIP712Version()++`] + +[.contract-subindex-inherited] +.IERC5267 + +-- + +[.contract-index] +.Events +-- + +[.contract-subindex-inherited] +.IERC5267 +* {xref-IERC5267-EIP712DomainChanged--}[`++EIP712DomainChanged()++`] + +-- + +[.contract-item] +[[EIP712-constructor-string-string-]] +==== `[.contract-item-name]#++constructor++#++(string name, string version)++` [.item-kind]#internal# + +Initializes the domain separator and parameter caches. + +The meaning of `name` and `version` is specified in +https://eips.ethereum.org/EIPS/eip-712#definition-of-domainseparator[EIP 712]: + +- `name`: the user readable name of the signing domain, i.e. the name of the DApp or the protocol. +- `version`: the current major version of the signing domain. + +NOTE: These parameters cannot be changed except through a xref:learn::upgrading-smart-contracts.adoc[smart +contract upgrade]. + +[.contract-item] +[[EIP712-_domainSeparatorV4--]] +==== `[.contract-item-name]#++_domainSeparatorV4++#++() → bytes32++` [.item-kind]#internal# + +Returns the domain separator for the current chain. + +[.contract-item] +[[EIP712-_hashTypedDataV4-bytes32-]] +==== `[.contract-item-name]#++_hashTypedDataV4++#++(bytes32 structHash) → bytes32++` [.item-kind]#internal# + +Given an already https://eips.ethereum.org/EIPS/eip-712#definition-of-hashstruct[hashed struct], this +function returns the hash of the fully encoded EIP712 message for this domain. + +This hash can be used together with {ECDSA-recover} to obtain the signer of a message. For example: + +```solidity +bytes32 digest = _hashTypedDataV4(keccak256(abi.encode( + keccak256("Mail(address to,string contents)"), + mailTo, + keccak256(bytes(mailContents)) +))); +address signer = ECDSA.recover(digest, signature); +``` + +[.contract-item] +[[EIP712-eip712Domain--]] +==== `[.contract-item-name]#++eip712Domain++#++() → bytes1 fields, string name, string version, uint256 chainId, address verifyingContract, bytes32 salt, uint256[] extensions++` [.item-kind]#public# + +See {IERC-5267}. + +[.contract-item] +[[EIP712-_EIP712Name--]] +==== `[.contract-item-name]#++_EIP712Name++#++() → string++` [.item-kind]#internal# + +The name parameter for the EIP712 domain. + +NOTE: By default this function reads _name which is an immutable value. +It only reads from storage if necessary (in case the value is too large to fit in a ShortString). + +[.contract-item] +[[EIP712-_EIP712Version--]] +==== `[.contract-item-name]#++_EIP712Version++#++() → string++` [.item-kind]#internal# + +The version parameter for the EIP712 domain. + +NOTE: By default this function reads _version which is an immutable value. +It only reads from storage if necessary (in case the value is too large to fit in a ShortString). + +== Security + +:ReentrancyGuardReentrantCall: pass:normal[xref:#ReentrancyGuard-ReentrancyGuardReentrantCall--[`++ReentrancyGuardReentrantCall++`]] +:constructor: pass:normal[xref:#ReentrancyGuard-constructor--[`++constructor++`]] +:nonReentrant: pass:normal[xref:#ReentrancyGuard-nonReentrant--[`++nonReentrant++`]] +:_reentrancyGuardEntered: pass:normal[xref:#ReentrancyGuard-_reentrancyGuardEntered--[`++_reentrancyGuardEntered++`]] + +[.contract] +[[ReentrancyGuard]] +=== `++ReentrancyGuard++` link:https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v5.0.0-rc.0/contracts/utils/ReentrancyGuard.sol[{github-icon},role=heading-link] + +[.hljs-theme-light.nopadding] +```solidity +import "@openzeppelin/contracts/utils/ReentrancyGuard.sol"; +``` + +Contract module that helps prevent reentrant calls to a function. + +Inheriting from `ReentrancyGuard` will make the {nonReentrant} modifier +available, which can be applied to functions to make sure there are no nested +(reentrant) calls to them. + +Note that because there is a single `nonReentrant` guard, functions marked as +`nonReentrant` may not call one another. This can be worked around by making +those functions `private`, and then adding `external` `nonReentrant` entry +points to them. + +TIP: If you would like to learn more about reentrancy and alternative ways +to protect against it, check out our blog post +https://blog.openzeppelin.com/reentrancy-after-istanbul/[Reentrancy After Istanbul]. + +[.contract-index] +.Modifiers +-- +* {xref-ReentrancyGuard-nonReentrant--}[`++nonReentrant()++`] +-- + +[.contract-index] +.Functions +-- +* {xref-ReentrancyGuard-constructor--}[`++constructor()++`] +* {xref-ReentrancyGuard-_reentrancyGuardEntered--}[`++_reentrancyGuardEntered()++`] + +-- + +[.contract-index] +.Errors +-- +* {xref-ReentrancyGuard-ReentrancyGuardReentrantCall--}[`++ReentrancyGuardReentrantCall()++`] + +-- + +[.contract-item] +[[ReentrancyGuard-nonReentrant--]] +==== `[.contract-item-name]#++nonReentrant++#++()++` [.item-kind]#modifier# + +Prevents a contract from calling itself, directly or indirectly. +Calling a `nonReentrant` function from another `nonReentrant` +function is not supported. It is possible to prevent this from happening +by making the `nonReentrant` function external, and making it call a +`private` function that does the actual work. + +[.contract-item] +[[ReentrancyGuard-constructor--]] +==== `[.contract-item-name]#++constructor++#++()++` [.item-kind]#internal# + +[.contract-item] +[[ReentrancyGuard-_reentrancyGuardEntered--]] +==== `[.contract-item-name]#++_reentrancyGuardEntered++#++() → bool++` [.item-kind]#internal# + +Returns true if the reentrancy guard is currently set to "entered", which indicates there is a +`nonReentrant` function in the call stack. + +[.contract-item] +[[ReentrancyGuard-ReentrancyGuardReentrantCall--]] +==== `[.contract-item-name]#++ReentrancyGuardReentrantCall++#++()++` [.item-kind]#error# + +Unauthorized reentrant call. + +:Paused: pass:normal[xref:#Pausable-Paused-address-[`++Paused++`]] +:Unpaused: pass:normal[xref:#Pausable-Unpaused-address-[`++Unpaused++`]] +:EnforcedPause: pass:normal[xref:#Pausable-EnforcedPause--[`++EnforcedPause++`]] +:ExpectedPause: pass:normal[xref:#Pausable-ExpectedPause--[`++ExpectedPause++`]] +:constructor: pass:normal[xref:#Pausable-constructor--[`++constructor++`]] +:whenNotPaused: pass:normal[xref:#Pausable-whenNotPaused--[`++whenNotPaused++`]] +:whenPaused: pass:normal[xref:#Pausable-whenPaused--[`++whenPaused++`]] +:paused: pass:normal[xref:#Pausable-paused--[`++paused++`]] +:_requireNotPaused: pass:normal[xref:#Pausable-_requireNotPaused--[`++_requireNotPaused++`]] +:_requirePaused: pass:normal[xref:#Pausable-_requirePaused--[`++_requirePaused++`]] +:_pause: pass:normal[xref:#Pausable-_pause--[`++_pause++`]] +:_unpause: pass:normal[xref:#Pausable-_unpause--[`++_unpause++`]] + +[.contract] +[[Pausable]] +=== `++Pausable++` link:https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v5.0.0-rc.0/contracts/utils/Pausable.sol[{github-icon},role=heading-link] + +[.hljs-theme-light.nopadding] +```solidity +import "@openzeppelin/contracts/utils/Pausable.sol"; +``` + +Contract module which allows children to implement an emergency stop +mechanism that can be triggered by an authorized account. + +This module is used through inheritance. It will make available the +modifiers `whenNotPaused` and `whenPaused`, which can be applied to +the functions of your contract. Note that they will not be pausable by +simply including this module, only once the modifiers are put in place. + +[.contract-index] +.Modifiers +-- +* {xref-Pausable-whenNotPaused--}[`++whenNotPaused()++`] +* {xref-Pausable-whenPaused--}[`++whenPaused()++`] +-- + +[.contract-index] +.Functions +-- +* {xref-Pausable-constructor--}[`++constructor()++`] +* {xref-Pausable-paused--}[`++paused()++`] +* {xref-Pausable-_requireNotPaused--}[`++_requireNotPaused()++`] +* {xref-Pausable-_requirePaused--}[`++_requirePaused()++`] +* {xref-Pausable-_pause--}[`++_pause()++`] +* {xref-Pausable-_unpause--}[`++_unpause()++`] + +-- + +[.contract-index] +.Events +-- +* {xref-Pausable-Paused-address-}[`++Paused(account)++`] +* {xref-Pausable-Unpaused-address-}[`++Unpaused(account)++`] + +-- + +[.contract-index] +.Errors +-- +* {xref-Pausable-EnforcedPause--}[`++EnforcedPause()++`] +* {xref-Pausable-ExpectedPause--}[`++ExpectedPause()++`] + +-- + +[.contract-item] +[[Pausable-whenNotPaused--]] +==== `[.contract-item-name]#++whenNotPaused++#++()++` [.item-kind]#modifier# + +Modifier to make a function callable only when the contract is not paused. + +Requirements: + +- The contract must not be paused. + +[.contract-item] +[[Pausable-whenPaused--]] +==== `[.contract-item-name]#++whenPaused++#++()++` [.item-kind]#modifier# + +Modifier to make a function callable only when the contract is paused. + +Requirements: + +- The contract must be paused. + +[.contract-item] +[[Pausable-constructor--]] +==== `[.contract-item-name]#++constructor++#++()++` [.item-kind]#internal# + +Initializes the contract in unpaused state. + +[.contract-item] +[[Pausable-paused--]] +==== `[.contract-item-name]#++paused++#++() → bool++` [.item-kind]#public# + +Returns true if the contract is paused, and false otherwise. + +[.contract-item] +[[Pausable-_requireNotPaused--]] +==== `[.contract-item-name]#++_requireNotPaused++#++()++` [.item-kind]#internal# + +Throws if the contract is paused. + +[.contract-item] +[[Pausable-_requirePaused--]] +==== `[.contract-item-name]#++_requirePaused++#++()++` [.item-kind]#internal# + +Throws if the contract is not paused. + +[.contract-item] +[[Pausable-_pause--]] +==== `[.contract-item-name]#++_pause++#++()++` [.item-kind]#internal# + +Triggers stopped state. + +Requirements: + +- The contract must not be paused. + +[.contract-item] +[[Pausable-_unpause--]] +==== `[.contract-item-name]#++_unpause++#++()++` [.item-kind]#internal# + +Returns to normal state. + +Requirements: + +- The contract must be paused. + +[.contract-item] +[[Pausable-Paused-address-]] +==== `[.contract-item-name]#++Paused++#++(address account)++` [.item-kind]#event# + +Emitted when the pause is triggered by `account`. + +[.contract-item] +[[Pausable-Unpaused-address-]] +==== `[.contract-item-name]#++Unpaused++#++(address account)++` [.item-kind]#event# + +Emitted when the pause is lifted by `account`. + +[.contract-item] +[[Pausable-EnforcedPause--]] +==== `[.contract-item-name]#++EnforcedPause++#++()++` [.item-kind]#error# + +The operation failed because the contract is paused. + +[.contract-item] +[[Pausable-ExpectedPause--]] +==== `[.contract-item-name]#++ExpectedPause++#++()++` [.item-kind]#error# + +The operation failed because the contract is not paused. + +== Introspection + +This set of interfaces and contracts deal with https://en.wikipedia.org/wiki/Type_introspection[type introspection] of contracts, that is, examining which functions can be called on them. This is usually referred to as a contract's _interface_. + +Ethereum contracts have no native concept of an interface, so applications must usually simply trust they are not making an incorrect call. For trusted setups this is a non-issue, but often unknown and untrusted third-party addresses need to be interacted with. There may even not be any direct calls to them! (e.g. `ERC20` tokens may be sent to a contract that lacks a way to transfer them out of it, locking them forever). In these cases, a contract _declaring_ its interface can be very helpful in preventing errors. + +:supportsInterface: pass:normal[xref:#IERC165-supportsInterface-bytes4-[`++supportsInterface++`]] + +[.contract] +[[IERC165]] +=== `++IERC165++` link:https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v5.0.0-rc.0/contracts/utils/introspection/IERC165.sol[{github-icon},role=heading-link] + +[.hljs-theme-light.nopadding] +```solidity +import "@openzeppelin/contracts/utils/introspection/IERC165.sol"; +``` + +Interface of the ERC165 standard, as defined in the +https://eips.ethereum.org/EIPS/eip-165[EIP]. + +Implementers can declare support of contract interfaces, which can then be +queried by others ({ERC165Checker}). + +For an implementation, see {ERC165}. + +[.contract-index] +.Functions +-- +* {xref-IERC165-supportsInterface-bytes4-}[`++supportsInterface(interfaceId)++`] + +-- + +[.contract-item] +[[IERC165-supportsInterface-bytes4-]] +==== `[.contract-item-name]#++supportsInterface++#++(bytes4 interfaceId) → bool++` [.item-kind]#external# + +Returns true if this contract implements the interface defined by +`interfaceId`. See the corresponding +https://eips.ethereum.org/EIPS/eip-165#how-interfaces-are-identified[EIP section] +to learn more about how these ids are created. + +This function call must use less than 30 000 gas. + +:supportsInterface: pass:normal[xref:#ERC165-supportsInterface-bytes4-[`++supportsInterface++`]] + +[.contract] +[[ERC165]] +=== `++ERC165++` link:https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v5.0.0-rc.0/contracts/utils/introspection/ERC165.sol[{github-icon},role=heading-link] + +[.hljs-theme-light.nopadding] +```solidity +import "@openzeppelin/contracts/utils/introspection/ERC165.sol"; +``` + +Implementation of the {IERC165} interface. + +Contracts that want to implement ERC165 should inherit from this contract and override {supportsInterface} to check +for the additional interface id that will be supported. For example: + +```solidity +function supportsInterface(bytes4 interfaceId) public view virtual override returns (bool) { + return interfaceId == type(MyInterface).interfaceId || super.supportsInterface(interfaceId); +} +``` + +[.contract-index] +.Functions +-- +* {xref-ERC165-supportsInterface-bytes4-}[`++supportsInterface(interfaceId)++`] + +[.contract-subindex-inherited] +.IERC165 + +-- + +[.contract-item] +[[ERC165-supportsInterface-bytes4-]] +==== `[.contract-item-name]#++supportsInterface++#++(bytes4 interfaceId) → bool++` [.item-kind]#public# + +See {IERC165-supportsInterface}. + +:supportsERC165: pass:normal[xref:#ERC165Checker-supportsERC165-address-[`++supportsERC165++`]] +:supportsInterface: pass:normal[xref:#ERC165Checker-supportsInterface-address-bytes4-[`++supportsInterface++`]] +:getSupportedInterfaces: pass:normal[xref:#ERC165Checker-getSupportedInterfaces-address-bytes4---[`++getSupportedInterfaces++`]] +:supportsAllInterfaces: pass:normal[xref:#ERC165Checker-supportsAllInterfaces-address-bytes4---[`++supportsAllInterfaces++`]] +:supportsERC165InterfaceUnchecked: pass:normal[xref:#ERC165Checker-supportsERC165InterfaceUnchecked-address-bytes4-[`++supportsERC165InterfaceUnchecked++`]] + +[.contract] +[[ERC165Checker]] +=== `++ERC165Checker++` link:https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v5.0.0-rc.0/contracts/utils/introspection/ERC165Checker.sol[{github-icon},role=heading-link] + +[.hljs-theme-light.nopadding] +```solidity +import "@openzeppelin/contracts/utils/introspection/ERC165Checker.sol"; +``` + +Library used to query support of an interface declared via {IERC165}. + +Note that these functions return the actual result of the query: they do not +`revert` if an interface is not supported. It is up to the caller to decide +what to do in these cases. + +[.contract-index] +.Functions +-- +* {xref-ERC165Checker-supportsERC165-address-}[`++supportsERC165(account)++`] +* {xref-ERC165Checker-supportsInterface-address-bytes4-}[`++supportsInterface(account, interfaceId)++`] +* {xref-ERC165Checker-getSupportedInterfaces-address-bytes4---}[`++getSupportedInterfaces(account, interfaceIds)++`] +* {xref-ERC165Checker-supportsAllInterfaces-address-bytes4---}[`++supportsAllInterfaces(account, interfaceIds)++`] +* {xref-ERC165Checker-supportsERC165InterfaceUnchecked-address-bytes4-}[`++supportsERC165InterfaceUnchecked(account, interfaceId)++`] + +-- + +[.contract-item] +[[ERC165Checker-supportsERC165-address-]] +==== `[.contract-item-name]#++supportsERC165++#++(address account) → bool++` [.item-kind]#internal# + +Returns true if `account` supports the {IERC165} interface. + +[.contract-item] +[[ERC165Checker-supportsInterface-address-bytes4-]] +==== `[.contract-item-name]#++supportsInterface++#++(address account, bytes4 interfaceId) → bool++` [.item-kind]#internal# + +Returns true if `account` supports the interface defined by +`interfaceId`. Support for {IERC165} itself is queried automatically. + +See {IERC165-supportsInterface}. + +[.contract-item] +[[ERC165Checker-getSupportedInterfaces-address-bytes4---]] +==== `[.contract-item-name]#++getSupportedInterfaces++#++(address account, bytes4[] interfaceIds) → bool[]++` [.item-kind]#internal# + +Returns a boolean array where each value corresponds to the +interfaces passed in and whether they're supported or not. This allows +you to batch check interfaces for a contract where your expectation +is that some interfaces may not be supported. + +See {IERC165-supportsInterface}. + +[.contract-item] +[[ERC165Checker-supportsAllInterfaces-address-bytes4---]] +==== `[.contract-item-name]#++supportsAllInterfaces++#++(address account, bytes4[] interfaceIds) → bool++` [.item-kind]#internal# + +Returns true if `account` supports all the interfaces defined in +`interfaceIds`. Support for {IERC165} itself is queried automatically. + +Batch-querying can lead to gas savings by skipping repeated checks for +{IERC165} support. + +See {IERC165-supportsInterface}. + +[.contract-item] +[[ERC165Checker-supportsERC165InterfaceUnchecked-address-bytes4-]] +==== `[.contract-item-name]#++supportsERC165InterfaceUnchecked++#++(address account, bytes4 interfaceId) → bool++` [.item-kind]#internal# + +Assumes that account contains a contract that supports ERC165, otherwise +the behavior of this method is undefined. This precondition can be checked +with {supportsERC165}. + +Some precompiled contracts will falsely indicate support for a given interface, so caution +should be exercised when using this function. + +Interface identification is specified in ERC-165. + +== Data Structures + +:BitMap: pass:normal[xref:#BitMaps-BitMap[`++BitMap++`]] +:get: pass:normal[xref:#BitMaps-get-struct-BitMaps-BitMap-uint256-[`++get++`]] +:setTo: pass:normal[xref:#BitMaps-setTo-struct-BitMaps-BitMap-uint256-bool-[`++setTo++`]] +:set: pass:normal[xref:#BitMaps-set-struct-BitMaps-BitMap-uint256-[`++set++`]] +:unset: pass:normal[xref:#BitMaps-unset-struct-BitMaps-BitMap-uint256-[`++unset++`]] + +[.contract] +[[BitMaps]] +=== `++BitMaps++` link:https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v5.0.0-rc.0/contracts/utils/structs/BitMaps.sol[{github-icon},role=heading-link] + +[.hljs-theme-light.nopadding] +```solidity +import "@openzeppelin/contracts/utils/structs/BitMaps.sol"; +``` + +Library for managing uint256 to bool mapping in a compact and efficient way, provided the keys are sequential. +Largely inspired by Uniswap's https://github.com/Uniswap/merkle-distributor/blob/master/contracts/MerkleDistributor.sol[merkle-distributor]. + +BitMaps pack 256 booleans across each bit of a single 256-bit slot of `uint256` type. +Hence booleans corresponding to 256 _sequential_ indices would only consume a single slot, +unlike the regular `bool` which would consume an entire slot for a single value. + +This results in gas savings in two ways: + +- Setting a zero value to non-zero only once every 256 times +- Accessing the same warm slot for every 256 _sequential_ indices + +[.contract-index] +.Functions +-- +* {xref-BitMaps-get-struct-BitMaps-BitMap-uint256-}[`++get(bitmap, index)++`] +* {xref-BitMaps-setTo-struct-BitMaps-BitMap-uint256-bool-}[`++setTo(bitmap, index, value)++`] +* {xref-BitMaps-set-struct-BitMaps-BitMap-uint256-}[`++set(bitmap, index)++`] +* {xref-BitMaps-unset-struct-BitMaps-BitMap-uint256-}[`++unset(bitmap, index)++`] + +-- + +[.contract-item] +[[BitMaps-get-struct-BitMaps-BitMap-uint256-]] +==== `[.contract-item-name]#++get++#++(struct BitMaps.BitMap bitmap, uint256 index) → bool++` [.item-kind]#internal# + +Returns whether the bit at `index` is set. + +[.contract-item] +[[BitMaps-setTo-struct-BitMaps-BitMap-uint256-bool-]] +==== `[.contract-item-name]#++setTo++#++(struct BitMaps.BitMap bitmap, uint256 index, bool value)++` [.item-kind]#internal# + +Sets the bit at `index` to the boolean `value`. + +[.contract-item] +[[BitMaps-set-struct-BitMaps-BitMap-uint256-]] +==== `[.contract-item-name]#++set++#++(struct BitMaps.BitMap bitmap, uint256 index)++` [.item-kind]#internal# + +Sets the bit at `index`. + +[.contract-item] +[[BitMaps-unset-struct-BitMaps-BitMap-uint256-]] +==== `[.contract-item-name]#++unset++#++(struct BitMaps.BitMap bitmap, uint256 index)++` [.item-kind]#internal# + +Unsets the bit at `index`. + +:EnumerableMapNonexistentKey: pass:normal[xref:#EnumerableMap-EnumerableMapNonexistentKey-bytes32-[`++EnumerableMapNonexistentKey++`]] +:Bytes32ToBytes32Map: pass:normal[xref:#EnumerableMap-Bytes32ToBytes32Map[`++Bytes32ToBytes32Map++`]] +:set: pass:normal[xref:#EnumerableMap-set-struct-EnumerableMap-Bytes32ToBytes32Map-bytes32-bytes32-[`++set++`]] +:remove: pass:normal[xref:#EnumerableMap-remove-struct-EnumerableMap-Bytes32ToBytes32Map-bytes32-[`++remove++`]] +:contains: pass:normal[xref:#EnumerableMap-contains-struct-EnumerableMap-Bytes32ToBytes32Map-bytes32-[`++contains++`]] +:length: pass:normal[xref:#EnumerableMap-length-struct-EnumerableMap-Bytes32ToBytes32Map-[`++length++`]] +:at: pass:normal[xref:#EnumerableMap-at-struct-EnumerableMap-Bytes32ToBytes32Map-uint256-[`++at++`]] +:tryGet: pass:normal[xref:#EnumerableMap-tryGet-struct-EnumerableMap-Bytes32ToBytes32Map-bytes32-[`++tryGet++`]] +:get: pass:normal[xref:#EnumerableMap-get-struct-EnumerableMap-Bytes32ToBytes32Map-bytes32-[`++get++`]] +:keys: pass:normal[xref:#EnumerableMap-keys-struct-EnumerableMap-Bytes32ToBytes32Map-[`++keys++`]] +:UintToUintMap: pass:normal[xref:#EnumerableMap-UintToUintMap[`++UintToUintMap++`]] +:set: pass:normal[xref:#EnumerableMap-set-struct-EnumerableMap-UintToUintMap-uint256-uint256-[`++set++`]] +:remove: pass:normal[xref:#EnumerableMap-remove-struct-EnumerableMap-UintToUintMap-uint256-[`++remove++`]] +:contains: pass:normal[xref:#EnumerableMap-contains-struct-EnumerableMap-UintToUintMap-uint256-[`++contains++`]] +:length: pass:normal[xref:#EnumerableMap-length-struct-EnumerableMap-UintToUintMap-[`++length++`]] +:at: pass:normal[xref:#EnumerableMap-at-struct-EnumerableMap-UintToUintMap-uint256-[`++at++`]] +:tryGet: pass:normal[xref:#EnumerableMap-tryGet-struct-EnumerableMap-UintToUintMap-uint256-[`++tryGet++`]] +:get: pass:normal[xref:#EnumerableMap-get-struct-EnumerableMap-UintToUintMap-uint256-[`++get++`]] +:keys: pass:normal[xref:#EnumerableMap-keys-struct-EnumerableMap-UintToUintMap-[`++keys++`]] +:UintToAddressMap: pass:normal[xref:#EnumerableMap-UintToAddressMap[`++UintToAddressMap++`]] +:set: pass:normal[xref:#EnumerableMap-set-struct-EnumerableMap-UintToAddressMap-uint256-address-[`++set++`]] +:remove: pass:normal[xref:#EnumerableMap-remove-struct-EnumerableMap-UintToAddressMap-uint256-[`++remove++`]] +:contains: pass:normal[xref:#EnumerableMap-contains-struct-EnumerableMap-UintToAddressMap-uint256-[`++contains++`]] +:length: pass:normal[xref:#EnumerableMap-length-struct-EnumerableMap-UintToAddressMap-[`++length++`]] +:at: pass:normal[xref:#EnumerableMap-at-struct-EnumerableMap-UintToAddressMap-uint256-[`++at++`]] +:tryGet: pass:normal[xref:#EnumerableMap-tryGet-struct-EnumerableMap-UintToAddressMap-uint256-[`++tryGet++`]] +:get: pass:normal[xref:#EnumerableMap-get-struct-EnumerableMap-UintToAddressMap-uint256-[`++get++`]] +:keys: pass:normal[xref:#EnumerableMap-keys-struct-EnumerableMap-UintToAddressMap-[`++keys++`]] +:AddressToUintMap: pass:normal[xref:#EnumerableMap-AddressToUintMap[`++AddressToUintMap++`]] +:set: pass:normal[xref:#EnumerableMap-set-struct-EnumerableMap-AddressToUintMap-address-uint256-[`++set++`]] +:remove: pass:normal[xref:#EnumerableMap-remove-struct-EnumerableMap-AddressToUintMap-address-[`++remove++`]] +:contains: pass:normal[xref:#EnumerableMap-contains-struct-EnumerableMap-AddressToUintMap-address-[`++contains++`]] +:length: pass:normal[xref:#EnumerableMap-length-struct-EnumerableMap-AddressToUintMap-[`++length++`]] +:at: pass:normal[xref:#EnumerableMap-at-struct-EnumerableMap-AddressToUintMap-uint256-[`++at++`]] +:tryGet: pass:normal[xref:#EnumerableMap-tryGet-struct-EnumerableMap-AddressToUintMap-address-[`++tryGet++`]] +:get: pass:normal[xref:#EnumerableMap-get-struct-EnumerableMap-AddressToUintMap-address-[`++get++`]] +:keys: pass:normal[xref:#EnumerableMap-keys-struct-EnumerableMap-AddressToUintMap-[`++keys++`]] +:Bytes32ToUintMap: pass:normal[xref:#EnumerableMap-Bytes32ToUintMap[`++Bytes32ToUintMap++`]] +:set: pass:normal[xref:#EnumerableMap-set-struct-EnumerableMap-Bytes32ToUintMap-bytes32-uint256-[`++set++`]] +:remove: pass:normal[xref:#EnumerableMap-remove-struct-EnumerableMap-Bytes32ToUintMap-bytes32-[`++remove++`]] +:contains: pass:normal[xref:#EnumerableMap-contains-struct-EnumerableMap-Bytes32ToUintMap-bytes32-[`++contains++`]] +:length: pass:normal[xref:#EnumerableMap-length-struct-EnumerableMap-Bytes32ToUintMap-[`++length++`]] +:at: pass:normal[xref:#EnumerableMap-at-struct-EnumerableMap-Bytes32ToUintMap-uint256-[`++at++`]] +:tryGet: pass:normal[xref:#EnumerableMap-tryGet-struct-EnumerableMap-Bytes32ToUintMap-bytes32-[`++tryGet++`]] +:get: pass:normal[xref:#EnumerableMap-get-struct-EnumerableMap-Bytes32ToUintMap-bytes32-[`++get++`]] +:keys: pass:normal[xref:#EnumerableMap-keys-struct-EnumerableMap-Bytes32ToUintMap-[`++keys++`]] + +[.contract] +[[EnumerableMap]] +=== `++EnumerableMap++` link:https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v5.0.0-rc.0/contracts/utils/structs/EnumerableMap.sol[{github-icon},role=heading-link] + +[.hljs-theme-light.nopadding] +```solidity +import "@openzeppelin/contracts/utils/structs/EnumerableMap.sol"; +``` + +Library for managing an enumerable variant of Solidity's +https://solidity.readthedocs.io/en/latest/types.html#mapping-types[`mapping`] +type. + +Maps have the following properties: + +- Entries are added, removed, and checked for existence in constant time +(O(1)). +- Entries are enumerated in O(n). No guarantees are made on the ordering. + +```solidity +contract Example { + // Add the library methods + using EnumerableMap for EnumerableMap.UintToAddressMap; + + // Declare a set state variable + EnumerableMap.UintToAddressMap private myMap; +} +``` + +The following map types are supported: + +- `uint256 -> address` (`UintToAddressMap`) since v3.0.0 +- `address -> uint256` (`AddressToUintMap`) since v4.6.0 +- `bytes32 -> bytes32` (`Bytes32ToBytes32Map`) since v4.6.0 +- `uint256 -> uint256` (`UintToUintMap`) since v4.7.0 +- `bytes32 -> uint256` (`Bytes32ToUintMap`) since v4.7.0 + +[WARNING] +==== +Trying to delete such a structure from storage will likely result in data corruption, rendering the structure +unusable. +See https://github.com/ethereum/solidity/pull/11843[ethereum/solidity#11843] for more info. + +In order to clean an EnumerableMap, you can either remove all elements one by one or create a fresh instance using an +array of EnumerableMap. +==== + +[.contract-index] +.Functions +-- +* {xref-EnumerableMap-set-struct-EnumerableMap-Bytes32ToBytes32Map-bytes32-bytes32-}[`++set(map, key, value)++`] +* {xref-EnumerableMap-remove-struct-EnumerableMap-Bytes32ToBytes32Map-bytes32-}[`++remove(map, key)++`] +* {xref-EnumerableMap-contains-struct-EnumerableMap-Bytes32ToBytes32Map-bytes32-}[`++contains(map, key)++`] +* {xref-EnumerableMap-length-struct-EnumerableMap-Bytes32ToBytes32Map-}[`++length(map)++`] +* {xref-EnumerableMap-at-struct-EnumerableMap-Bytes32ToBytes32Map-uint256-}[`++at(map, index)++`] +* {xref-EnumerableMap-tryGet-struct-EnumerableMap-Bytes32ToBytes32Map-bytes32-}[`++tryGet(map, key)++`] +* {xref-EnumerableMap-get-struct-EnumerableMap-Bytes32ToBytes32Map-bytes32-}[`++get(map, key)++`] +* {xref-EnumerableMap-keys-struct-EnumerableMap-Bytes32ToBytes32Map-}[`++keys(map)++`] +* {xref-EnumerableMap-set-struct-EnumerableMap-UintToUintMap-uint256-uint256-}[`++set(map, key, value)++`] +* {xref-EnumerableMap-remove-struct-EnumerableMap-UintToUintMap-uint256-}[`++remove(map, key)++`] +* {xref-EnumerableMap-contains-struct-EnumerableMap-UintToUintMap-uint256-}[`++contains(map, key)++`] +* {xref-EnumerableMap-length-struct-EnumerableMap-UintToUintMap-}[`++length(map)++`] +* {xref-EnumerableMap-at-struct-EnumerableMap-UintToUintMap-uint256-}[`++at(map, index)++`] +* {xref-EnumerableMap-tryGet-struct-EnumerableMap-UintToUintMap-uint256-}[`++tryGet(map, key)++`] +* {xref-EnumerableMap-get-struct-EnumerableMap-UintToUintMap-uint256-}[`++get(map, key)++`] +* {xref-EnumerableMap-keys-struct-EnumerableMap-UintToUintMap-}[`++keys(map)++`] +* {xref-EnumerableMap-set-struct-EnumerableMap-UintToAddressMap-uint256-address-}[`++set(map, key, value)++`] +* {xref-EnumerableMap-remove-struct-EnumerableMap-UintToAddressMap-uint256-}[`++remove(map, key)++`] +* {xref-EnumerableMap-contains-struct-EnumerableMap-UintToAddressMap-uint256-}[`++contains(map, key)++`] +* {xref-EnumerableMap-length-struct-EnumerableMap-UintToAddressMap-}[`++length(map)++`] +* {xref-EnumerableMap-at-struct-EnumerableMap-UintToAddressMap-uint256-}[`++at(map, index)++`] +* {xref-EnumerableMap-tryGet-struct-EnumerableMap-UintToAddressMap-uint256-}[`++tryGet(map, key)++`] +* {xref-EnumerableMap-get-struct-EnumerableMap-UintToAddressMap-uint256-}[`++get(map, key)++`] +* {xref-EnumerableMap-keys-struct-EnumerableMap-UintToAddressMap-}[`++keys(map)++`] +* {xref-EnumerableMap-set-struct-EnumerableMap-AddressToUintMap-address-uint256-}[`++set(map, key, value)++`] +* {xref-EnumerableMap-remove-struct-EnumerableMap-AddressToUintMap-address-}[`++remove(map, key)++`] +* {xref-EnumerableMap-contains-struct-EnumerableMap-AddressToUintMap-address-}[`++contains(map, key)++`] +* {xref-EnumerableMap-length-struct-EnumerableMap-AddressToUintMap-}[`++length(map)++`] +* {xref-EnumerableMap-at-struct-EnumerableMap-AddressToUintMap-uint256-}[`++at(map, index)++`] +* {xref-EnumerableMap-tryGet-struct-EnumerableMap-AddressToUintMap-address-}[`++tryGet(map, key)++`] +* {xref-EnumerableMap-get-struct-EnumerableMap-AddressToUintMap-address-}[`++get(map, key)++`] +* {xref-EnumerableMap-keys-struct-EnumerableMap-AddressToUintMap-}[`++keys(map)++`] +* {xref-EnumerableMap-set-struct-EnumerableMap-Bytes32ToUintMap-bytes32-uint256-}[`++set(map, key, value)++`] +* {xref-EnumerableMap-remove-struct-EnumerableMap-Bytes32ToUintMap-bytes32-}[`++remove(map, key)++`] +* {xref-EnumerableMap-contains-struct-EnumerableMap-Bytes32ToUintMap-bytes32-}[`++contains(map, key)++`] +* {xref-EnumerableMap-length-struct-EnumerableMap-Bytes32ToUintMap-}[`++length(map)++`] +* {xref-EnumerableMap-at-struct-EnumerableMap-Bytes32ToUintMap-uint256-}[`++at(map, index)++`] +* {xref-EnumerableMap-tryGet-struct-EnumerableMap-Bytes32ToUintMap-bytes32-}[`++tryGet(map, key)++`] +* {xref-EnumerableMap-get-struct-EnumerableMap-Bytes32ToUintMap-bytes32-}[`++get(map, key)++`] +* {xref-EnumerableMap-keys-struct-EnumerableMap-Bytes32ToUintMap-}[`++keys(map)++`] + +-- + +[.contract-index] +.Errors +-- +* {xref-EnumerableMap-EnumerableMapNonexistentKey-bytes32-}[`++EnumerableMapNonexistentKey(key)++`] + +-- + +[.contract-item] +[[EnumerableMap-set-struct-EnumerableMap-Bytes32ToBytes32Map-bytes32-bytes32-]] +==== `[.contract-item-name]#++set++#++(struct EnumerableMap.Bytes32ToBytes32Map map, bytes32 key, bytes32 value) → bool++` [.item-kind]#internal# + +Adds a key-value pair to a map, or updates the value for an existing +key. O(1). + +Returns true if the key was added to the map, that is if it was not +already present. + +[.contract-item] +[[EnumerableMap-remove-struct-EnumerableMap-Bytes32ToBytes32Map-bytes32-]] +==== `[.contract-item-name]#++remove++#++(struct EnumerableMap.Bytes32ToBytes32Map map, bytes32 key) → bool++` [.item-kind]#internal# + +Removes a key-value pair from a map. O(1). + +Returns true if the key was removed from the map, that is if it was present. + +[.contract-item] +[[EnumerableMap-contains-struct-EnumerableMap-Bytes32ToBytes32Map-bytes32-]] +==== `[.contract-item-name]#++contains++#++(struct EnumerableMap.Bytes32ToBytes32Map map, bytes32 key) → bool++` [.item-kind]#internal# + +Returns true if the key is in the map. O(1). + +[.contract-item] +[[EnumerableMap-length-struct-EnumerableMap-Bytes32ToBytes32Map-]] +==== `[.contract-item-name]#++length++#++(struct EnumerableMap.Bytes32ToBytes32Map map) → uint256++` [.item-kind]#internal# + +Returns the number of key-value pairs in the map. O(1). + +[.contract-item] +[[EnumerableMap-at-struct-EnumerableMap-Bytes32ToBytes32Map-uint256-]] +==== `[.contract-item-name]#++at++#++(struct EnumerableMap.Bytes32ToBytes32Map map, uint256 index) → bytes32, bytes32++` [.item-kind]#internal# + +Returns the key-value pair stored at position `index` in the map. O(1). + +Note that there are no guarantees on the ordering of entries inside the +array, and it may change when more entries are added or removed. + +Requirements: + +- `index` must be strictly less than {length}. + +[.contract-item] +[[EnumerableMap-tryGet-struct-EnumerableMap-Bytes32ToBytes32Map-bytes32-]] +==== `[.contract-item-name]#++tryGet++#++(struct EnumerableMap.Bytes32ToBytes32Map map, bytes32 key) → bool, bytes32++` [.item-kind]#internal# + +Tries to returns the value associated with `key`. O(1). +Does not revert if `key` is not in the map. + +[.contract-item] +[[EnumerableMap-get-struct-EnumerableMap-Bytes32ToBytes32Map-bytes32-]] +==== `[.contract-item-name]#++get++#++(struct EnumerableMap.Bytes32ToBytes32Map map, bytes32 key) → bytes32++` [.item-kind]#internal# + +Returns the value associated with `key`. O(1). + +Requirements: + +- `key` must be in the map. + +[.contract-item] +[[EnumerableMap-keys-struct-EnumerableMap-Bytes32ToBytes32Map-]] +==== `[.contract-item-name]#++keys++#++(struct EnumerableMap.Bytes32ToBytes32Map map) → bytes32[]++` [.item-kind]#internal# + +Return the an array containing all the keys + +WARNING: This operation will copy the entire storage to memory, which can be quite expensive. This is designed +to mostly be used by view accessors that are queried without any gas fees. Developers should keep in mind that +this function has an unbounded cost, and using it as part of a state-changing function may render the function +uncallable if the map grows to a point where copying to memory consumes too much gas to fit in a block. + +[.contract-item] +[[EnumerableMap-set-struct-EnumerableMap-UintToUintMap-uint256-uint256-]] +==== `[.contract-item-name]#++set++#++(struct EnumerableMap.UintToUintMap map, uint256 key, uint256 value) → bool++` [.item-kind]#internal# + +Adds a key-value pair to a map, or updates the value for an existing +key. O(1). + +Returns true if the key was added to the map, that is if it was not +already present. + +[.contract-item] +[[EnumerableMap-remove-struct-EnumerableMap-UintToUintMap-uint256-]] +==== `[.contract-item-name]#++remove++#++(struct EnumerableMap.UintToUintMap map, uint256 key) → bool++` [.item-kind]#internal# + +Removes a value from a map. O(1). + +Returns true if the key was removed from the map, that is if it was present. + +[.contract-item] +[[EnumerableMap-contains-struct-EnumerableMap-UintToUintMap-uint256-]] +==== `[.contract-item-name]#++contains++#++(struct EnumerableMap.UintToUintMap map, uint256 key) → bool++` [.item-kind]#internal# + +Returns true if the key is in the map. O(1). + +[.contract-item] +[[EnumerableMap-length-struct-EnumerableMap-UintToUintMap-]] +==== `[.contract-item-name]#++length++#++(struct EnumerableMap.UintToUintMap map) → uint256++` [.item-kind]#internal# + +Returns the number of elements in the map. O(1). + +[.contract-item] +[[EnumerableMap-at-struct-EnumerableMap-UintToUintMap-uint256-]] +==== `[.contract-item-name]#++at++#++(struct EnumerableMap.UintToUintMap map, uint256 index) → uint256, uint256++` [.item-kind]#internal# + +Returns the element stored at position `index` in the map. O(1). +Note that there are no guarantees on the ordering of values inside the +array, and it may change when more values are added or removed. + +Requirements: + +- `index` must be strictly less than {length}. + +[.contract-item] +[[EnumerableMap-tryGet-struct-EnumerableMap-UintToUintMap-uint256-]] +==== `[.contract-item-name]#++tryGet++#++(struct EnumerableMap.UintToUintMap map, uint256 key) → bool, uint256++` [.item-kind]#internal# + +Tries to returns the value associated with `key`. O(1). +Does not revert if `key` is not in the map. + +[.contract-item] +[[EnumerableMap-get-struct-EnumerableMap-UintToUintMap-uint256-]] +==== `[.contract-item-name]#++get++#++(struct EnumerableMap.UintToUintMap map, uint256 key) → uint256++` [.item-kind]#internal# + +Returns the value associated with `key`. O(1). + +Requirements: + +- `key` must be in the map. + +[.contract-item] +[[EnumerableMap-keys-struct-EnumerableMap-UintToUintMap-]] +==== `[.contract-item-name]#++keys++#++(struct EnumerableMap.UintToUintMap map) → uint256[]++` [.item-kind]#internal# + +Return the an array containing all the keys + +WARNING: This operation will copy the entire storage to memory, which can be quite expensive. This is designed +to mostly be used by view accessors that are queried without any gas fees. Developers should keep in mind that +this function has an unbounded cost, and using it as part of a state-changing function may render the function +uncallable if the map grows to a point where copying to memory consumes too much gas to fit in a block. + +[.contract-item] +[[EnumerableMap-set-struct-EnumerableMap-UintToAddressMap-uint256-address-]] +==== `[.contract-item-name]#++set++#++(struct EnumerableMap.UintToAddressMap map, uint256 key, address value) → bool++` [.item-kind]#internal# + +Adds a key-value pair to a map, or updates the value for an existing +key. O(1). + +Returns true if the key was added to the map, that is if it was not +already present. + +[.contract-item] +[[EnumerableMap-remove-struct-EnumerableMap-UintToAddressMap-uint256-]] +==== `[.contract-item-name]#++remove++#++(struct EnumerableMap.UintToAddressMap map, uint256 key) → bool++` [.item-kind]#internal# + +Removes a value from a map. O(1). + +Returns true if the key was removed from the map, that is if it was present. + +[.contract-item] +[[EnumerableMap-contains-struct-EnumerableMap-UintToAddressMap-uint256-]] +==== `[.contract-item-name]#++contains++#++(struct EnumerableMap.UintToAddressMap map, uint256 key) → bool++` [.item-kind]#internal# + +Returns true if the key is in the map. O(1). + +[.contract-item] +[[EnumerableMap-length-struct-EnumerableMap-UintToAddressMap-]] +==== `[.contract-item-name]#++length++#++(struct EnumerableMap.UintToAddressMap map) → uint256++` [.item-kind]#internal# + +Returns the number of elements in the map. O(1). + +[.contract-item] +[[EnumerableMap-at-struct-EnumerableMap-UintToAddressMap-uint256-]] +==== `[.contract-item-name]#++at++#++(struct EnumerableMap.UintToAddressMap map, uint256 index) → uint256, address++` [.item-kind]#internal# + +Returns the element stored at position `index` in the map. O(1). +Note that there are no guarantees on the ordering of values inside the +array, and it may change when more values are added or removed. + +Requirements: + +- `index` must be strictly less than {length}. + +[.contract-item] +[[EnumerableMap-tryGet-struct-EnumerableMap-UintToAddressMap-uint256-]] +==== `[.contract-item-name]#++tryGet++#++(struct EnumerableMap.UintToAddressMap map, uint256 key) → bool, address++` [.item-kind]#internal# + +Tries to returns the value associated with `key`. O(1). +Does not revert if `key` is not in the map. + +[.contract-item] +[[EnumerableMap-get-struct-EnumerableMap-UintToAddressMap-uint256-]] +==== `[.contract-item-name]#++get++#++(struct EnumerableMap.UintToAddressMap map, uint256 key) → address++` [.item-kind]#internal# + +Returns the value associated with `key`. O(1). + +Requirements: + +- `key` must be in the map. + +[.contract-item] +[[EnumerableMap-keys-struct-EnumerableMap-UintToAddressMap-]] +==== `[.contract-item-name]#++keys++#++(struct EnumerableMap.UintToAddressMap map) → uint256[]++` [.item-kind]#internal# + +Return the an array containing all the keys + +WARNING: This operation will copy the entire storage to memory, which can be quite expensive. This is designed +to mostly be used by view accessors that are queried without any gas fees. Developers should keep in mind that +this function has an unbounded cost, and using it as part of a state-changing function may render the function +uncallable if the map grows to a point where copying to memory consumes too much gas to fit in a block. + +[.contract-item] +[[EnumerableMap-set-struct-EnumerableMap-AddressToUintMap-address-uint256-]] +==== `[.contract-item-name]#++set++#++(struct EnumerableMap.AddressToUintMap map, address key, uint256 value) → bool++` [.item-kind]#internal# + +Adds a key-value pair to a map, or updates the value for an existing +key. O(1). + +Returns true if the key was added to the map, that is if it was not +already present. + +[.contract-item] +[[EnumerableMap-remove-struct-EnumerableMap-AddressToUintMap-address-]] +==== `[.contract-item-name]#++remove++#++(struct EnumerableMap.AddressToUintMap map, address key) → bool++` [.item-kind]#internal# + +Removes a value from a map. O(1). + +Returns true if the key was removed from the map, that is if it was present. + +[.contract-item] +[[EnumerableMap-contains-struct-EnumerableMap-AddressToUintMap-address-]] +==== `[.contract-item-name]#++contains++#++(struct EnumerableMap.AddressToUintMap map, address key) → bool++` [.item-kind]#internal# + +Returns true if the key is in the map. O(1). + +[.contract-item] +[[EnumerableMap-length-struct-EnumerableMap-AddressToUintMap-]] +==== `[.contract-item-name]#++length++#++(struct EnumerableMap.AddressToUintMap map) → uint256++` [.item-kind]#internal# + +Returns the number of elements in the map. O(1). + +[.contract-item] +[[EnumerableMap-at-struct-EnumerableMap-AddressToUintMap-uint256-]] +==== `[.contract-item-name]#++at++#++(struct EnumerableMap.AddressToUintMap map, uint256 index) → address, uint256++` [.item-kind]#internal# + +Returns the element stored at position `index` in the map. O(1). +Note that there are no guarantees on the ordering of values inside the +array, and it may change when more values are added or removed. + +Requirements: + +- `index` must be strictly less than {length}. + +[.contract-item] +[[EnumerableMap-tryGet-struct-EnumerableMap-AddressToUintMap-address-]] +==== `[.contract-item-name]#++tryGet++#++(struct EnumerableMap.AddressToUintMap map, address key) → bool, uint256++` [.item-kind]#internal# + +Tries to returns the value associated with `key`. O(1). +Does not revert if `key` is not in the map. + +[.contract-item] +[[EnumerableMap-get-struct-EnumerableMap-AddressToUintMap-address-]] +==== `[.contract-item-name]#++get++#++(struct EnumerableMap.AddressToUintMap map, address key) → uint256++` [.item-kind]#internal# + +Returns the value associated with `key`. O(1). + +Requirements: + +- `key` must be in the map. + +[.contract-item] +[[EnumerableMap-keys-struct-EnumerableMap-AddressToUintMap-]] +==== `[.contract-item-name]#++keys++#++(struct EnumerableMap.AddressToUintMap map) → address[]++` [.item-kind]#internal# + +Return the an array containing all the keys + +WARNING: This operation will copy the entire storage to memory, which can be quite expensive. This is designed +to mostly be used by view accessors that are queried without any gas fees. Developers should keep in mind that +this function has an unbounded cost, and using it as part of a state-changing function may render the function +uncallable if the map grows to a point where copying to memory consumes too much gas to fit in a block. + +[.contract-item] +[[EnumerableMap-set-struct-EnumerableMap-Bytes32ToUintMap-bytes32-uint256-]] +==== `[.contract-item-name]#++set++#++(struct EnumerableMap.Bytes32ToUintMap map, bytes32 key, uint256 value) → bool++` [.item-kind]#internal# + +Adds a key-value pair to a map, or updates the value for an existing +key. O(1). + +Returns true if the key was added to the map, that is if it was not +already present. + +[.contract-item] +[[EnumerableMap-remove-struct-EnumerableMap-Bytes32ToUintMap-bytes32-]] +==== `[.contract-item-name]#++remove++#++(struct EnumerableMap.Bytes32ToUintMap map, bytes32 key) → bool++` [.item-kind]#internal# + +Removes a value from a map. O(1). + +Returns true if the key was removed from the map, that is if it was present. + +[.contract-item] +[[EnumerableMap-contains-struct-EnumerableMap-Bytes32ToUintMap-bytes32-]] +==== `[.contract-item-name]#++contains++#++(struct EnumerableMap.Bytes32ToUintMap map, bytes32 key) → bool++` [.item-kind]#internal# + +Returns true if the key is in the map. O(1). + +[.contract-item] +[[EnumerableMap-length-struct-EnumerableMap-Bytes32ToUintMap-]] +==== `[.contract-item-name]#++length++#++(struct EnumerableMap.Bytes32ToUintMap map) → uint256++` [.item-kind]#internal# + +Returns the number of elements in the map. O(1). + +[.contract-item] +[[EnumerableMap-at-struct-EnumerableMap-Bytes32ToUintMap-uint256-]] +==== `[.contract-item-name]#++at++#++(struct EnumerableMap.Bytes32ToUintMap map, uint256 index) → bytes32, uint256++` [.item-kind]#internal# + +Returns the element stored at position `index` in the map. O(1). +Note that there are no guarantees on the ordering of values inside the +array, and it may change when more values are added or removed. + +Requirements: + +- `index` must be strictly less than {length}. + +[.contract-item] +[[EnumerableMap-tryGet-struct-EnumerableMap-Bytes32ToUintMap-bytes32-]] +==== `[.contract-item-name]#++tryGet++#++(struct EnumerableMap.Bytes32ToUintMap map, bytes32 key) → bool, uint256++` [.item-kind]#internal# + +Tries to returns the value associated with `key`. O(1). +Does not revert if `key` is not in the map. + +[.contract-item] +[[EnumerableMap-get-struct-EnumerableMap-Bytes32ToUintMap-bytes32-]] +==== `[.contract-item-name]#++get++#++(struct EnumerableMap.Bytes32ToUintMap map, bytes32 key) → uint256++` [.item-kind]#internal# + +Returns the value associated with `key`. O(1). + +Requirements: + +- `key` must be in the map. + +[.contract-item] +[[EnumerableMap-keys-struct-EnumerableMap-Bytes32ToUintMap-]] +==== `[.contract-item-name]#++keys++#++(struct EnumerableMap.Bytes32ToUintMap map) → bytes32[]++` [.item-kind]#internal# + +Return the an array containing all the keys + +WARNING: This operation will copy the entire storage to memory, which can be quite expensive. This is designed +to mostly be used by view accessors that are queried without any gas fees. Developers should keep in mind that +this function has an unbounded cost, and using it as part of a state-changing function may render the function +uncallable if the map grows to a point where copying to memory consumes too much gas to fit in a block. + +[.contract-item] +[[EnumerableMap-EnumerableMapNonexistentKey-bytes32-]] +==== `[.contract-item-name]#++EnumerableMapNonexistentKey++#++(bytes32 key)++` [.item-kind]#error# + +Query for a nonexistent map key. + +:Set: pass:normal[xref:#EnumerableSet-Set[`++Set++`]] +:Bytes32Set: pass:normal[xref:#EnumerableSet-Bytes32Set[`++Bytes32Set++`]] +:add: pass:normal[xref:#EnumerableSet-add-struct-EnumerableSet-Bytes32Set-bytes32-[`++add++`]] +:remove: pass:normal[xref:#EnumerableSet-remove-struct-EnumerableSet-Bytes32Set-bytes32-[`++remove++`]] +:contains: pass:normal[xref:#EnumerableSet-contains-struct-EnumerableSet-Bytes32Set-bytes32-[`++contains++`]] +:length: pass:normal[xref:#EnumerableSet-length-struct-EnumerableSet-Bytes32Set-[`++length++`]] +:at: pass:normal[xref:#EnumerableSet-at-struct-EnumerableSet-Bytes32Set-uint256-[`++at++`]] +:values: pass:normal[xref:#EnumerableSet-values-struct-EnumerableSet-Bytes32Set-[`++values++`]] +:AddressSet: pass:normal[xref:#EnumerableSet-AddressSet[`++AddressSet++`]] +:add: pass:normal[xref:#EnumerableSet-add-struct-EnumerableSet-AddressSet-address-[`++add++`]] +:remove: pass:normal[xref:#EnumerableSet-remove-struct-EnumerableSet-AddressSet-address-[`++remove++`]] +:contains: pass:normal[xref:#EnumerableSet-contains-struct-EnumerableSet-AddressSet-address-[`++contains++`]] +:length: pass:normal[xref:#EnumerableSet-length-struct-EnumerableSet-AddressSet-[`++length++`]] +:at: pass:normal[xref:#EnumerableSet-at-struct-EnumerableSet-AddressSet-uint256-[`++at++`]] +:values: pass:normal[xref:#EnumerableSet-values-struct-EnumerableSet-AddressSet-[`++values++`]] +:UintSet: pass:normal[xref:#EnumerableSet-UintSet[`++UintSet++`]] +:add: pass:normal[xref:#EnumerableSet-add-struct-EnumerableSet-UintSet-uint256-[`++add++`]] +:remove: pass:normal[xref:#EnumerableSet-remove-struct-EnumerableSet-UintSet-uint256-[`++remove++`]] +:contains: pass:normal[xref:#EnumerableSet-contains-struct-EnumerableSet-UintSet-uint256-[`++contains++`]] +:length: pass:normal[xref:#EnumerableSet-length-struct-EnumerableSet-UintSet-[`++length++`]] +:at: pass:normal[xref:#EnumerableSet-at-struct-EnumerableSet-UintSet-uint256-[`++at++`]] +:values: pass:normal[xref:#EnumerableSet-values-struct-EnumerableSet-UintSet-[`++values++`]] + +[.contract] +[[EnumerableSet]] +=== `++EnumerableSet++` link:https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v5.0.0-rc.0/contracts/utils/structs/EnumerableSet.sol[{github-icon},role=heading-link] + +[.hljs-theme-light.nopadding] +```solidity +import "@openzeppelin/contracts/utils/structs/EnumerableSet.sol"; +``` + +Library for managing +https://en.wikipedia.org/wiki/Set_(abstract_data_type)[sets] of primitive +types. + +Sets have the following properties: + +- Elements are added, removed, and checked for existence in constant time +(O(1)). +- Elements are enumerated in O(n). No guarantees are made on the ordering. + +```solidity +contract Example { + // Add the library methods + using EnumerableSet for EnumerableSet.AddressSet; + + // Declare a set state variable + EnumerableSet.AddressSet private mySet; +} +``` + +As of v3.3.0, sets of type `bytes32` (`Bytes32Set`), `address` (`AddressSet`) +and `uint256` (`UintSet`) are supported. + +[WARNING] +==== +Trying to delete such a structure from storage will likely result in data corruption, rendering the structure +unusable. +See https://github.com/ethereum/solidity/pull/11843[ethereum/solidity#11843] for more info. + +In order to clean an EnumerableSet, you can either remove all elements one by one or create a fresh instance using an +array of EnumerableSet. +==== + +[.contract-index] +.Functions +-- +* {xref-EnumerableSet-add-struct-EnumerableSet-Bytes32Set-bytes32-}[`++add(set, value)++`] +* {xref-EnumerableSet-remove-struct-EnumerableSet-Bytes32Set-bytes32-}[`++remove(set, value)++`] +* {xref-EnumerableSet-contains-struct-EnumerableSet-Bytes32Set-bytes32-}[`++contains(set, value)++`] +* {xref-EnumerableSet-length-struct-EnumerableSet-Bytes32Set-}[`++length(set)++`] +* {xref-EnumerableSet-at-struct-EnumerableSet-Bytes32Set-uint256-}[`++at(set, index)++`] +* {xref-EnumerableSet-values-struct-EnumerableSet-Bytes32Set-}[`++values(set)++`] +* {xref-EnumerableSet-add-struct-EnumerableSet-AddressSet-address-}[`++add(set, value)++`] +* {xref-EnumerableSet-remove-struct-EnumerableSet-AddressSet-address-}[`++remove(set, value)++`] +* {xref-EnumerableSet-contains-struct-EnumerableSet-AddressSet-address-}[`++contains(set, value)++`] +* {xref-EnumerableSet-length-struct-EnumerableSet-AddressSet-}[`++length(set)++`] +* {xref-EnumerableSet-at-struct-EnumerableSet-AddressSet-uint256-}[`++at(set, index)++`] +* {xref-EnumerableSet-values-struct-EnumerableSet-AddressSet-}[`++values(set)++`] +* {xref-EnumerableSet-add-struct-EnumerableSet-UintSet-uint256-}[`++add(set, value)++`] +* {xref-EnumerableSet-remove-struct-EnumerableSet-UintSet-uint256-}[`++remove(set, value)++`] +* {xref-EnumerableSet-contains-struct-EnumerableSet-UintSet-uint256-}[`++contains(set, value)++`] +* {xref-EnumerableSet-length-struct-EnumerableSet-UintSet-}[`++length(set)++`] +* {xref-EnumerableSet-at-struct-EnumerableSet-UintSet-uint256-}[`++at(set, index)++`] +* {xref-EnumerableSet-values-struct-EnumerableSet-UintSet-}[`++values(set)++`] + +-- + +[.contract-item] +[[EnumerableSet-add-struct-EnumerableSet-Bytes32Set-bytes32-]] +==== `[.contract-item-name]#++add++#++(struct EnumerableSet.Bytes32Set set, bytes32 value) → bool++` [.item-kind]#internal# + +Add a value to a set. O(1). + +Returns true if the value was added to the set, that is if it was not +already present. + +[.contract-item] +[[EnumerableSet-remove-struct-EnumerableSet-Bytes32Set-bytes32-]] +==== `[.contract-item-name]#++remove++#++(struct EnumerableSet.Bytes32Set set, bytes32 value) → bool++` [.item-kind]#internal# + +Removes a value from a set. O(1). + +Returns true if the value was removed from the set, that is if it was +present. + +[.contract-item] +[[EnumerableSet-contains-struct-EnumerableSet-Bytes32Set-bytes32-]] +==== `[.contract-item-name]#++contains++#++(struct EnumerableSet.Bytes32Set set, bytes32 value) → bool++` [.item-kind]#internal# + +Returns true if the value is in the set. O(1). + +[.contract-item] +[[EnumerableSet-length-struct-EnumerableSet-Bytes32Set-]] +==== `[.contract-item-name]#++length++#++(struct EnumerableSet.Bytes32Set set) → uint256++` [.item-kind]#internal# + +Returns the number of values in the set. O(1). + +[.contract-item] +[[EnumerableSet-at-struct-EnumerableSet-Bytes32Set-uint256-]] +==== `[.contract-item-name]#++at++#++(struct EnumerableSet.Bytes32Set set, uint256 index) → bytes32++` [.item-kind]#internal# + +Returns the value stored at position `index` in the set. O(1). + +Note that there are no guarantees on the ordering of values inside the +array, and it may change when more values are added or removed. + +Requirements: + +- `index` must be strictly less than {length}. + +[.contract-item] +[[EnumerableSet-values-struct-EnumerableSet-Bytes32Set-]] +==== `[.contract-item-name]#++values++#++(struct EnumerableSet.Bytes32Set set) → bytes32[]++` [.item-kind]#internal# + +Return the entire set in an array + +WARNING: This operation will copy the entire storage to memory, which can be quite expensive. This is designed +to mostly be used by view accessors that are queried without any gas fees. Developers should keep in mind that +this function has an unbounded cost, and using it as part of a state-changing function may render the function +uncallable if the set grows to a point where copying to memory consumes too much gas to fit in a block. + +[.contract-item] +[[EnumerableSet-add-struct-EnumerableSet-AddressSet-address-]] +==== `[.contract-item-name]#++add++#++(struct EnumerableSet.AddressSet set, address value) → bool++` [.item-kind]#internal# + +Add a value to a set. O(1). + +Returns true if the value was added to the set, that is if it was not +already present. + +[.contract-item] +[[EnumerableSet-remove-struct-EnumerableSet-AddressSet-address-]] +==== `[.contract-item-name]#++remove++#++(struct EnumerableSet.AddressSet set, address value) → bool++` [.item-kind]#internal# + +Removes a value from a set. O(1). + +Returns true if the value was removed from the set, that is if it was +present. + +[.contract-item] +[[EnumerableSet-contains-struct-EnumerableSet-AddressSet-address-]] +==== `[.contract-item-name]#++contains++#++(struct EnumerableSet.AddressSet set, address value) → bool++` [.item-kind]#internal# + +Returns true if the value is in the set. O(1). + +[.contract-item] +[[EnumerableSet-length-struct-EnumerableSet-AddressSet-]] +==== `[.contract-item-name]#++length++#++(struct EnumerableSet.AddressSet set) → uint256++` [.item-kind]#internal# + +Returns the number of values in the set. O(1). + +[.contract-item] +[[EnumerableSet-at-struct-EnumerableSet-AddressSet-uint256-]] +==== `[.contract-item-name]#++at++#++(struct EnumerableSet.AddressSet set, uint256 index) → address++` [.item-kind]#internal# + +Returns the value stored at position `index` in the set. O(1). + +Note that there are no guarantees on the ordering of values inside the +array, and it may change when more values are added or removed. + +Requirements: + +- `index` must be strictly less than {length}. + +[.contract-item] +[[EnumerableSet-values-struct-EnumerableSet-AddressSet-]] +==== `[.contract-item-name]#++values++#++(struct EnumerableSet.AddressSet set) → address[]++` [.item-kind]#internal# + +Return the entire set in an array + +WARNING: This operation will copy the entire storage to memory, which can be quite expensive. This is designed +to mostly be used by view accessors that are queried without any gas fees. Developers should keep in mind that +this function has an unbounded cost, and using it as part of a state-changing function may render the function +uncallable if the set grows to a point where copying to memory consumes too much gas to fit in a block. + +[.contract-item] +[[EnumerableSet-add-struct-EnumerableSet-UintSet-uint256-]] +==== `[.contract-item-name]#++add++#++(struct EnumerableSet.UintSet set, uint256 value) → bool++` [.item-kind]#internal# + +Add a value to a set. O(1). + +Returns true if the value was added to the set, that is if it was not +already present. + +[.contract-item] +[[EnumerableSet-remove-struct-EnumerableSet-UintSet-uint256-]] +==== `[.contract-item-name]#++remove++#++(struct EnumerableSet.UintSet set, uint256 value) → bool++` [.item-kind]#internal# + +Removes a value from a set. O(1). + +Returns true if the value was removed from the set, that is if it was +present. + +[.contract-item] +[[EnumerableSet-contains-struct-EnumerableSet-UintSet-uint256-]] +==== `[.contract-item-name]#++contains++#++(struct EnumerableSet.UintSet set, uint256 value) → bool++` [.item-kind]#internal# + +Returns true if the value is in the set. O(1). + +[.contract-item] +[[EnumerableSet-length-struct-EnumerableSet-UintSet-]] +==== `[.contract-item-name]#++length++#++(struct EnumerableSet.UintSet set) → uint256++` [.item-kind]#internal# + +Returns the number of values in the set. O(1). + +[.contract-item] +[[EnumerableSet-at-struct-EnumerableSet-UintSet-uint256-]] +==== `[.contract-item-name]#++at++#++(struct EnumerableSet.UintSet set, uint256 index) → uint256++` [.item-kind]#internal# + +Returns the value stored at position `index` in the set. O(1). + +Note that there are no guarantees on the ordering of values inside the +array, and it may change when more values are added or removed. + +Requirements: + +- `index` must be strictly less than {length}. + +[.contract-item] +[[EnumerableSet-values-struct-EnumerableSet-UintSet-]] +==== `[.contract-item-name]#++values++#++(struct EnumerableSet.UintSet set) → uint256[]++` [.item-kind]#internal# + +Return the entire set in an array + +WARNING: This operation will copy the entire storage to memory, which can be quite expensive. This is designed +to mostly be used by view accessors that are queried without any gas fees. Developers should keep in mind that +this function has an unbounded cost, and using it as part of a state-changing function may render the function +uncallable if the set grows to a point where copying to memory consumes too much gas to fit in a block. + +:QueueEmpty: pass:normal[xref:#DoubleEndedQueue-QueueEmpty--[`++QueueEmpty++`]] +:QueueFull: pass:normal[xref:#DoubleEndedQueue-QueueFull--[`++QueueFull++`]] +:QueueOutOfBounds: pass:normal[xref:#DoubleEndedQueue-QueueOutOfBounds--[`++QueueOutOfBounds++`]] +:Bytes32Deque: pass:normal[xref:#DoubleEndedQueue-Bytes32Deque[`++Bytes32Deque++`]] +:pushBack: pass:normal[xref:#DoubleEndedQueue-pushBack-struct-DoubleEndedQueue-Bytes32Deque-bytes32-[`++pushBack++`]] +:popBack: pass:normal[xref:#DoubleEndedQueue-popBack-struct-DoubleEndedQueue-Bytes32Deque-[`++popBack++`]] +:pushFront: pass:normal[xref:#DoubleEndedQueue-pushFront-struct-DoubleEndedQueue-Bytes32Deque-bytes32-[`++pushFront++`]] +:popFront: pass:normal[xref:#DoubleEndedQueue-popFront-struct-DoubleEndedQueue-Bytes32Deque-[`++popFront++`]] +:front: pass:normal[xref:#DoubleEndedQueue-front-struct-DoubleEndedQueue-Bytes32Deque-[`++front++`]] +:back: pass:normal[xref:#DoubleEndedQueue-back-struct-DoubleEndedQueue-Bytes32Deque-[`++back++`]] +:at: pass:normal[xref:#DoubleEndedQueue-at-struct-DoubleEndedQueue-Bytes32Deque-uint256-[`++at++`]] +:clear: pass:normal[xref:#DoubleEndedQueue-clear-struct-DoubleEndedQueue-Bytes32Deque-[`++clear++`]] +:length: pass:normal[xref:#DoubleEndedQueue-length-struct-DoubleEndedQueue-Bytes32Deque-[`++length++`]] +:empty: pass:normal[xref:#DoubleEndedQueue-empty-struct-DoubleEndedQueue-Bytes32Deque-[`++empty++`]] + +[.contract] +[[DoubleEndedQueue]] +=== `++DoubleEndedQueue++` link:https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v5.0.0-rc.0/contracts/utils/structs/DoubleEndedQueue.sol[{github-icon},role=heading-link] + +[.hljs-theme-light.nopadding] +```solidity +import "@openzeppelin/contracts/utils/structs/DoubleEndedQueue.sol"; +``` + +A sequence of items with the ability to efficiently push and pop items (i.e. insert and remove) on both ends of +the sequence (called front and back). Among other access patterns, it can be used to implement efficient LIFO and +FIFO queues. Storage use is optimized, and all operations are O(1) constant time. This includes {clear}, given that +the existing queue contents are left in storage. + +The struct is called `Bytes32Deque`. Other types can be cast to and from `bytes32`. This data structure can only be +used in storage, and not in memory. +```solidity +DoubleEndedQueue.Bytes32Deque queue; +``` + +[.contract-index] +.Functions +-- +* {xref-DoubleEndedQueue-pushBack-struct-DoubleEndedQueue-Bytes32Deque-bytes32-}[`++pushBack(deque, value)++`] +* {xref-DoubleEndedQueue-popBack-struct-DoubleEndedQueue-Bytes32Deque-}[`++popBack(deque)++`] +* {xref-DoubleEndedQueue-pushFront-struct-DoubleEndedQueue-Bytes32Deque-bytes32-}[`++pushFront(deque, value)++`] +* {xref-DoubleEndedQueue-popFront-struct-DoubleEndedQueue-Bytes32Deque-}[`++popFront(deque)++`] +* {xref-DoubleEndedQueue-front-struct-DoubleEndedQueue-Bytes32Deque-}[`++front(deque)++`] +* {xref-DoubleEndedQueue-back-struct-DoubleEndedQueue-Bytes32Deque-}[`++back(deque)++`] +* {xref-DoubleEndedQueue-at-struct-DoubleEndedQueue-Bytes32Deque-uint256-}[`++at(deque, index)++`] +* {xref-DoubleEndedQueue-clear-struct-DoubleEndedQueue-Bytes32Deque-}[`++clear(deque)++`] +* {xref-DoubleEndedQueue-length-struct-DoubleEndedQueue-Bytes32Deque-}[`++length(deque)++`] +* {xref-DoubleEndedQueue-empty-struct-DoubleEndedQueue-Bytes32Deque-}[`++empty(deque)++`] + +-- + +[.contract-index] +.Errors +-- +* {xref-DoubleEndedQueue-QueueEmpty--}[`++QueueEmpty()++`] +* {xref-DoubleEndedQueue-QueueFull--}[`++QueueFull()++`] +* {xref-DoubleEndedQueue-QueueOutOfBounds--}[`++QueueOutOfBounds()++`] + +-- + +[.contract-item] +[[DoubleEndedQueue-pushBack-struct-DoubleEndedQueue-Bytes32Deque-bytes32-]] +==== `[.contract-item-name]#++pushBack++#++(struct DoubleEndedQueue.Bytes32Deque deque, bytes32 value)++` [.item-kind]#internal# + +Inserts an item at the end of the queue. + +Reverts with {QueueFull} if the queue is full. + +[.contract-item] +[[DoubleEndedQueue-popBack-struct-DoubleEndedQueue-Bytes32Deque-]] +==== `[.contract-item-name]#++popBack++#++(struct DoubleEndedQueue.Bytes32Deque deque) → bytes32 value++` [.item-kind]#internal# + +Removes the item at the end of the queue and returns it. + +Reverts with {QueueEmpty} if the queue is empty. + +[.contract-item] +[[DoubleEndedQueue-pushFront-struct-DoubleEndedQueue-Bytes32Deque-bytes32-]] +==== `[.contract-item-name]#++pushFront++#++(struct DoubleEndedQueue.Bytes32Deque deque, bytes32 value)++` [.item-kind]#internal# + +Inserts an item at the beginning of the queue. + +Reverts with {QueueFull} if the queue is full. + +[.contract-item] +[[DoubleEndedQueue-popFront-struct-DoubleEndedQueue-Bytes32Deque-]] +==== `[.contract-item-name]#++popFront++#++(struct DoubleEndedQueue.Bytes32Deque deque) → bytes32 value++` [.item-kind]#internal# + +Removes the item at the beginning of the queue and returns it. + +Reverts with `QueueEmpty` if the queue is empty. + +[.contract-item] +[[DoubleEndedQueue-front-struct-DoubleEndedQueue-Bytes32Deque-]] +==== `[.contract-item-name]#++front++#++(struct DoubleEndedQueue.Bytes32Deque deque) → bytes32 value++` [.item-kind]#internal# + +Returns the item at the beginning of the queue. + +Reverts with `QueueEmpty` if the queue is empty. + +[.contract-item] +[[DoubleEndedQueue-back-struct-DoubleEndedQueue-Bytes32Deque-]] +==== `[.contract-item-name]#++back++#++(struct DoubleEndedQueue.Bytes32Deque deque) → bytes32 value++` [.item-kind]#internal# + +Returns the item at the end of the queue. + +Reverts with `QueueEmpty` if the queue is empty. + +[.contract-item] +[[DoubleEndedQueue-at-struct-DoubleEndedQueue-Bytes32Deque-uint256-]] +==== `[.contract-item-name]#++at++#++(struct DoubleEndedQueue.Bytes32Deque deque, uint256 index) → bytes32 value++` [.item-kind]#internal# + +Return the item at a position in the queue given by `index`, with the first item at 0 and last item at +`length(deque) - 1`. + +Reverts with `QueueOutOfBounds` if the index is out of bounds. + +[.contract-item] +[[DoubleEndedQueue-clear-struct-DoubleEndedQueue-Bytes32Deque-]] +==== `[.contract-item-name]#++clear++#++(struct DoubleEndedQueue.Bytes32Deque deque)++` [.item-kind]#internal# + +Resets the queue back to being empty. + +NOTE: The current items are left behind in storage. This does not affect the functioning of the queue, but misses +out on potential gas refunds. + +[.contract-item] +[[DoubleEndedQueue-length-struct-DoubleEndedQueue-Bytes32Deque-]] +==== `[.contract-item-name]#++length++#++(struct DoubleEndedQueue.Bytes32Deque deque) → uint256++` [.item-kind]#internal# + +Returns the number of items in the queue. + +[.contract-item] +[[DoubleEndedQueue-empty-struct-DoubleEndedQueue-Bytes32Deque-]] +==== `[.contract-item-name]#++empty++#++(struct DoubleEndedQueue.Bytes32Deque deque) → bool++` [.item-kind]#internal# + +Returns true if the queue is empty. + +[.contract-item] +[[DoubleEndedQueue-QueueEmpty--]] +==== `[.contract-item-name]#++QueueEmpty++#++()++` [.item-kind]#error# + +An operation (e.g. {front}) couldn't be completed due to the queue being empty. + +[.contract-item] +[[DoubleEndedQueue-QueueFull--]] +==== `[.contract-item-name]#++QueueFull++#++()++` [.item-kind]#error# + +A push operation couldn't be completed due to the queue being full. + +[.contract-item] +[[DoubleEndedQueue-QueueOutOfBounds--]] +==== `[.contract-item-name]#++QueueOutOfBounds++#++()++` [.item-kind]#error# + +An operation (e.g. {at}) couldn't be completed due to an index being out of bounds. + +:CheckpointUnorderedInsertion: pass:normal[xref:#Checkpoints-CheckpointUnorderedInsertion--[`++CheckpointUnorderedInsertion++`]] +:Trace224: pass:normal[xref:#Checkpoints-Trace224[`++Trace224++`]] +:Checkpoint224: pass:normal[xref:#Checkpoints-Checkpoint224[`++Checkpoint224++`]] +:push: pass:normal[xref:#Checkpoints-push-struct-Checkpoints-Trace224-uint32-uint224-[`++push++`]] +:lowerLookup: pass:normal[xref:#Checkpoints-lowerLookup-struct-Checkpoints-Trace224-uint32-[`++lowerLookup++`]] +:upperLookup: pass:normal[xref:#Checkpoints-upperLookup-struct-Checkpoints-Trace224-uint32-[`++upperLookup++`]] +:upperLookupRecent: pass:normal[xref:#Checkpoints-upperLookupRecent-struct-Checkpoints-Trace224-uint32-[`++upperLookupRecent++`]] +:latest: pass:normal[xref:#Checkpoints-latest-struct-Checkpoints-Trace224-[`++latest++`]] +:latestCheckpoint: pass:normal[xref:#Checkpoints-latestCheckpoint-struct-Checkpoints-Trace224-[`++latestCheckpoint++`]] +:length: pass:normal[xref:#Checkpoints-length-struct-Checkpoints-Trace224-[`++length++`]] +:at: pass:normal[xref:#Checkpoints-at-struct-Checkpoints-Trace224-uint32-[`++at++`]] +:Trace208: pass:normal[xref:#Checkpoints-Trace208[`++Trace208++`]] +:Checkpoint208: pass:normal[xref:#Checkpoints-Checkpoint208[`++Checkpoint208++`]] +:push: pass:normal[xref:#Checkpoints-push-struct-Checkpoints-Trace208-uint48-uint208-[`++push++`]] +:lowerLookup: pass:normal[xref:#Checkpoints-lowerLookup-struct-Checkpoints-Trace208-uint48-[`++lowerLookup++`]] +:upperLookup: pass:normal[xref:#Checkpoints-upperLookup-struct-Checkpoints-Trace208-uint48-[`++upperLookup++`]] +:upperLookupRecent: pass:normal[xref:#Checkpoints-upperLookupRecent-struct-Checkpoints-Trace208-uint48-[`++upperLookupRecent++`]] +:latest: pass:normal[xref:#Checkpoints-latest-struct-Checkpoints-Trace208-[`++latest++`]] +:latestCheckpoint: pass:normal[xref:#Checkpoints-latestCheckpoint-struct-Checkpoints-Trace208-[`++latestCheckpoint++`]] +:length: pass:normal[xref:#Checkpoints-length-struct-Checkpoints-Trace208-[`++length++`]] +:at: pass:normal[xref:#Checkpoints-at-struct-Checkpoints-Trace208-uint32-[`++at++`]] +:Trace160: pass:normal[xref:#Checkpoints-Trace160[`++Trace160++`]] +:Checkpoint160: pass:normal[xref:#Checkpoints-Checkpoint160[`++Checkpoint160++`]] +:push: pass:normal[xref:#Checkpoints-push-struct-Checkpoints-Trace160-uint96-uint160-[`++push++`]] +:lowerLookup: pass:normal[xref:#Checkpoints-lowerLookup-struct-Checkpoints-Trace160-uint96-[`++lowerLookup++`]] +:upperLookup: pass:normal[xref:#Checkpoints-upperLookup-struct-Checkpoints-Trace160-uint96-[`++upperLookup++`]] +:upperLookupRecent: pass:normal[xref:#Checkpoints-upperLookupRecent-struct-Checkpoints-Trace160-uint96-[`++upperLookupRecent++`]] +:latest: pass:normal[xref:#Checkpoints-latest-struct-Checkpoints-Trace160-[`++latest++`]] +:latestCheckpoint: pass:normal[xref:#Checkpoints-latestCheckpoint-struct-Checkpoints-Trace160-[`++latestCheckpoint++`]] +:length: pass:normal[xref:#Checkpoints-length-struct-Checkpoints-Trace160-[`++length++`]] +:at: pass:normal[xref:#Checkpoints-at-struct-Checkpoints-Trace160-uint32-[`++at++`]] + +[.contract] +[[Checkpoints]] +=== `++Checkpoints++` link:https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v5.0.0-rc.0/contracts/utils/structs/Checkpoints.sol[{github-icon},role=heading-link] + +[.hljs-theme-light.nopadding] +```solidity +import "@openzeppelin/contracts/utils/structs/Checkpoints.sol"; +``` + +This library defines the `Trace*` struct, for checkpointing values as they change at different points in +time, and later looking up past values by block number. See {Votes} as an example. + +To create a history of checkpoints define a variable type `Checkpoints.Trace*` in your contract, and store a new +checkpoint for the current transaction block using the {push} function. + +[.contract-index] +.Functions +-- +* {xref-Checkpoints-push-struct-Checkpoints-Trace224-uint32-uint224-}[`++push(self, key, value)++`] +* {xref-Checkpoints-lowerLookup-struct-Checkpoints-Trace224-uint32-}[`++lowerLookup(self, key)++`] +* {xref-Checkpoints-upperLookup-struct-Checkpoints-Trace224-uint32-}[`++upperLookup(self, key)++`] +* {xref-Checkpoints-upperLookupRecent-struct-Checkpoints-Trace224-uint32-}[`++upperLookupRecent(self, key)++`] +* {xref-Checkpoints-latest-struct-Checkpoints-Trace224-}[`++latest(self)++`] +* {xref-Checkpoints-latestCheckpoint-struct-Checkpoints-Trace224-}[`++latestCheckpoint(self)++`] +* {xref-Checkpoints-length-struct-Checkpoints-Trace224-}[`++length(self)++`] +* {xref-Checkpoints-at-struct-Checkpoints-Trace224-uint32-}[`++at(self, pos)++`] +* {xref-Checkpoints-push-struct-Checkpoints-Trace208-uint48-uint208-}[`++push(self, key, value)++`] +* {xref-Checkpoints-lowerLookup-struct-Checkpoints-Trace208-uint48-}[`++lowerLookup(self, key)++`] +* {xref-Checkpoints-upperLookup-struct-Checkpoints-Trace208-uint48-}[`++upperLookup(self, key)++`] +* {xref-Checkpoints-upperLookupRecent-struct-Checkpoints-Trace208-uint48-}[`++upperLookupRecent(self, key)++`] +* {xref-Checkpoints-latest-struct-Checkpoints-Trace208-}[`++latest(self)++`] +* {xref-Checkpoints-latestCheckpoint-struct-Checkpoints-Trace208-}[`++latestCheckpoint(self)++`] +* {xref-Checkpoints-length-struct-Checkpoints-Trace208-}[`++length(self)++`] +* {xref-Checkpoints-at-struct-Checkpoints-Trace208-uint32-}[`++at(self, pos)++`] +* {xref-Checkpoints-push-struct-Checkpoints-Trace160-uint96-uint160-}[`++push(self, key, value)++`] +* {xref-Checkpoints-lowerLookup-struct-Checkpoints-Trace160-uint96-}[`++lowerLookup(self, key)++`] +* {xref-Checkpoints-upperLookup-struct-Checkpoints-Trace160-uint96-}[`++upperLookup(self, key)++`] +* {xref-Checkpoints-upperLookupRecent-struct-Checkpoints-Trace160-uint96-}[`++upperLookupRecent(self, key)++`] +* {xref-Checkpoints-latest-struct-Checkpoints-Trace160-}[`++latest(self)++`] +* {xref-Checkpoints-latestCheckpoint-struct-Checkpoints-Trace160-}[`++latestCheckpoint(self)++`] +* {xref-Checkpoints-length-struct-Checkpoints-Trace160-}[`++length(self)++`] +* {xref-Checkpoints-at-struct-Checkpoints-Trace160-uint32-}[`++at(self, pos)++`] + +-- + +[.contract-index] +.Errors +-- +* {xref-Checkpoints-CheckpointUnorderedInsertion--}[`++CheckpointUnorderedInsertion()++`] + +-- + +[.contract-item] +[[Checkpoints-push-struct-Checkpoints-Trace224-uint32-uint224-]] +==== `[.contract-item-name]#++push++#++(struct Checkpoints.Trace224 self, uint32 key, uint224 value) → uint224, uint224++` [.item-kind]#internal# + +Pushes a (`key`, `value`) pair into a Trace224 so that it is stored as the checkpoint. + +Returns previous value and new value. + +IMPORTANT: Never accept `key` as a user input, since an arbitrary `type(uint32).max` key set will disable the +library. + +[.contract-item] +[[Checkpoints-lowerLookup-struct-Checkpoints-Trace224-uint32-]] +==== `[.contract-item-name]#++lowerLookup++#++(struct Checkpoints.Trace224 self, uint32 key) → uint224++` [.item-kind]#internal# + +Returns the value in the first (oldest) checkpoint with key greater or equal than the search key, or zero if +there is none. + +[.contract-item] +[[Checkpoints-upperLookup-struct-Checkpoints-Trace224-uint32-]] +==== `[.contract-item-name]#++upperLookup++#++(struct Checkpoints.Trace224 self, uint32 key) → uint224++` [.item-kind]#internal# + +Returns the value in the last (most recent) checkpoint with key lower or equal than the search key, or zero +if there is none. + +[.contract-item] +[[Checkpoints-upperLookupRecent-struct-Checkpoints-Trace224-uint32-]] +==== `[.contract-item-name]#++upperLookupRecent++#++(struct Checkpoints.Trace224 self, uint32 key) → uint224++` [.item-kind]#internal# + +Returns the value in the last (most recent) checkpoint with key lower or equal than the search key, or zero +if there is none. + +NOTE: This is a variant of {upperLookup} that is optimised to find "recent" checkpoint (checkpoints with high +keys). + +[.contract-item] +[[Checkpoints-latest-struct-Checkpoints-Trace224-]] +==== `[.contract-item-name]#++latest++#++(struct Checkpoints.Trace224 self) → uint224++` [.item-kind]#internal# + +Returns the value in the most recent checkpoint, or zero if there are no checkpoints. + +[.contract-item] +[[Checkpoints-latestCheckpoint-struct-Checkpoints-Trace224-]] +==== `[.contract-item-name]#++latestCheckpoint++#++(struct Checkpoints.Trace224 self) → bool exists, uint32 _key, uint224 _value++` [.item-kind]#internal# + +Returns whether there is a checkpoint in the structure (i.e. it is not empty), and if so the key and value +in the most recent checkpoint. + +[.contract-item] +[[Checkpoints-length-struct-Checkpoints-Trace224-]] +==== `[.contract-item-name]#++length++#++(struct Checkpoints.Trace224 self) → uint256++` [.item-kind]#internal# + +Returns the number of checkpoint. + +[.contract-item] +[[Checkpoints-at-struct-Checkpoints-Trace224-uint32-]] +==== `[.contract-item-name]#++at++#++(struct Checkpoints.Trace224 self, uint32 pos) → struct Checkpoints.Checkpoint224++` [.item-kind]#internal# + +Returns checkpoint at given position. + +[.contract-item] +[[Checkpoints-push-struct-Checkpoints-Trace208-uint48-uint208-]] +==== `[.contract-item-name]#++push++#++(struct Checkpoints.Trace208 self, uint48 key, uint208 value) → uint208, uint208++` [.item-kind]#internal# + +Pushes a (`key`, `value`) pair into a Trace208 so that it is stored as the checkpoint. + +Returns previous value and new value. + +IMPORTANT: Never accept `key` as a user input, since an arbitrary `type(uint48).max` key set will disable the +library. + +[.contract-item] +[[Checkpoints-lowerLookup-struct-Checkpoints-Trace208-uint48-]] +==== `[.contract-item-name]#++lowerLookup++#++(struct Checkpoints.Trace208 self, uint48 key) → uint208++` [.item-kind]#internal# + +Returns the value in the first (oldest) checkpoint with key greater or equal than the search key, or zero if +there is none. + +[.contract-item] +[[Checkpoints-upperLookup-struct-Checkpoints-Trace208-uint48-]] +==== `[.contract-item-name]#++upperLookup++#++(struct Checkpoints.Trace208 self, uint48 key) → uint208++` [.item-kind]#internal# + +Returns the value in the last (most recent) checkpoint with key lower or equal than the search key, or zero +if there is none. + +[.contract-item] +[[Checkpoints-upperLookupRecent-struct-Checkpoints-Trace208-uint48-]] +==== `[.contract-item-name]#++upperLookupRecent++#++(struct Checkpoints.Trace208 self, uint48 key) → uint208++` [.item-kind]#internal# + +Returns the value in the last (most recent) checkpoint with key lower or equal than the search key, or zero +if there is none. + +NOTE: This is a variant of {upperLookup} that is optimised to find "recent" checkpoint (checkpoints with high +keys). + +[.contract-item] +[[Checkpoints-latest-struct-Checkpoints-Trace208-]] +==== `[.contract-item-name]#++latest++#++(struct Checkpoints.Trace208 self) → uint208++` [.item-kind]#internal# + +Returns the value in the most recent checkpoint, or zero if there are no checkpoints. + +[.contract-item] +[[Checkpoints-latestCheckpoint-struct-Checkpoints-Trace208-]] +==== `[.contract-item-name]#++latestCheckpoint++#++(struct Checkpoints.Trace208 self) → bool exists, uint48 _key, uint208 _value++` [.item-kind]#internal# + +Returns whether there is a checkpoint in the structure (i.e. it is not empty), and if so the key and value +in the most recent checkpoint. + +[.contract-item] +[[Checkpoints-length-struct-Checkpoints-Trace208-]] +==== `[.contract-item-name]#++length++#++(struct Checkpoints.Trace208 self) → uint256++` [.item-kind]#internal# + +Returns the number of checkpoint. + +[.contract-item] +[[Checkpoints-at-struct-Checkpoints-Trace208-uint32-]] +==== `[.contract-item-name]#++at++#++(struct Checkpoints.Trace208 self, uint32 pos) → struct Checkpoints.Checkpoint208++` [.item-kind]#internal# + +Returns checkpoint at given position. + +[.contract-item] +[[Checkpoints-push-struct-Checkpoints-Trace160-uint96-uint160-]] +==== `[.contract-item-name]#++push++#++(struct Checkpoints.Trace160 self, uint96 key, uint160 value) → uint160, uint160++` [.item-kind]#internal# + +Pushes a (`key`, `value`) pair into a Trace160 so that it is stored as the checkpoint. + +Returns previous value and new value. + +IMPORTANT: Never accept `key` as a user input, since an arbitrary `type(uint96).max` key set will disable the +library. + +[.contract-item] +[[Checkpoints-lowerLookup-struct-Checkpoints-Trace160-uint96-]] +==== `[.contract-item-name]#++lowerLookup++#++(struct Checkpoints.Trace160 self, uint96 key) → uint160++` [.item-kind]#internal# + +Returns the value in the first (oldest) checkpoint with key greater or equal than the search key, or zero if +there is none. + +[.contract-item] +[[Checkpoints-upperLookup-struct-Checkpoints-Trace160-uint96-]] +==== `[.contract-item-name]#++upperLookup++#++(struct Checkpoints.Trace160 self, uint96 key) → uint160++` [.item-kind]#internal# + +Returns the value in the last (most recent) checkpoint with key lower or equal than the search key, or zero +if there is none. + +[.contract-item] +[[Checkpoints-upperLookupRecent-struct-Checkpoints-Trace160-uint96-]] +==== `[.contract-item-name]#++upperLookupRecent++#++(struct Checkpoints.Trace160 self, uint96 key) → uint160++` [.item-kind]#internal# + +Returns the value in the last (most recent) checkpoint with key lower or equal than the search key, or zero +if there is none. + +NOTE: This is a variant of {upperLookup} that is optimised to find "recent" checkpoint (checkpoints with high +keys). + +[.contract-item] +[[Checkpoints-latest-struct-Checkpoints-Trace160-]] +==== `[.contract-item-name]#++latest++#++(struct Checkpoints.Trace160 self) → uint160++` [.item-kind]#internal# + +Returns the value in the most recent checkpoint, or zero if there are no checkpoints. + +[.contract-item] +[[Checkpoints-latestCheckpoint-struct-Checkpoints-Trace160-]] +==== `[.contract-item-name]#++latestCheckpoint++#++(struct Checkpoints.Trace160 self) → bool exists, uint96 _key, uint160 _value++` [.item-kind]#internal# + +Returns whether there is a checkpoint in the structure (i.e. it is not empty), and if so the key and value +in the most recent checkpoint. + +[.contract-item] +[[Checkpoints-length-struct-Checkpoints-Trace160-]] +==== `[.contract-item-name]#++length++#++(struct Checkpoints.Trace160 self) → uint256++` [.item-kind]#internal# + +Returns the number of checkpoint. + +[.contract-item] +[[Checkpoints-at-struct-Checkpoints-Trace160-uint32-]] +==== `[.contract-item-name]#++at++#++(struct Checkpoints.Trace160 self, uint32 pos) → struct Checkpoints.Checkpoint160++` [.item-kind]#internal# + +Returns checkpoint at given position. + +[.contract-item] +[[Checkpoints-CheckpointUnorderedInsertion--]] +==== `[.contract-item-name]#++CheckpointUnorderedInsertion++#++()++` [.item-kind]#error# + +A value was attempted to be inserted on a past checkpoint. + +== Libraries + +:Create2InsufficientBalance: pass:normal[xref:#Create2-Create2InsufficientBalance-uint256-uint256-[`++Create2InsufficientBalance++`]] +:Create2EmptyBytecode: pass:normal[xref:#Create2-Create2EmptyBytecode--[`++Create2EmptyBytecode++`]] +:Create2FailedDeployment: pass:normal[xref:#Create2-Create2FailedDeployment--[`++Create2FailedDeployment++`]] +:deploy: pass:normal[xref:#Create2-deploy-uint256-bytes32-bytes-[`++deploy++`]] +:computeAddress: pass:normal[xref:#Create2-computeAddress-bytes32-bytes32-[`++computeAddress++`]] +:computeAddress: pass:normal[xref:#Create2-computeAddress-bytes32-bytes32-address-[`++computeAddress++`]] + +[.contract] +[[Create2]] +=== `++Create2++` link:https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v5.0.0-rc.0/contracts/utils/Create2.sol[{github-icon},role=heading-link] + +[.hljs-theme-light.nopadding] +```solidity +import "@openzeppelin/contracts/utils/Create2.sol"; +``` + +Helper to make usage of the `CREATE2` EVM opcode easier and safer. +`CREATE2` can be used to compute in advance the address where a smart +contract will be deployed, which allows for interesting new mechanisms known +as 'counterfactual interactions'. + +See the https://eips.ethereum.org/EIPS/eip-1014#motivation[EIP] for more +information. + +[.contract-index] +.Functions +-- +* {xref-Create2-deploy-uint256-bytes32-bytes-}[`++deploy(amount, salt, bytecode)++`] +* {xref-Create2-computeAddress-bytes32-bytes32-}[`++computeAddress(salt, bytecodeHash)++`] +* {xref-Create2-computeAddress-bytes32-bytes32-address-}[`++computeAddress(salt, bytecodeHash, deployer)++`] + +-- + +[.contract-index] +.Errors +-- +* {xref-Create2-Create2InsufficientBalance-uint256-uint256-}[`++Create2InsufficientBalance(balance, needed)++`] +* {xref-Create2-Create2EmptyBytecode--}[`++Create2EmptyBytecode()++`] +* {xref-Create2-Create2FailedDeployment--}[`++Create2FailedDeployment()++`] + +-- + +[.contract-item] +[[Create2-deploy-uint256-bytes32-bytes-]] +==== `[.contract-item-name]#++deploy++#++(uint256 amount, bytes32 salt, bytes bytecode) → address addr++` [.item-kind]#internal# + +Deploys a contract using `CREATE2`. The address where the contract +will be deployed can be known in advance via {computeAddress}. + +The bytecode for a contract can be obtained from Solidity with +`type(contractName).creationCode`. + +Requirements: + +- `bytecode` must not be empty. +- `salt` must have not been used for `bytecode` already. +- the factory must have a balance of at least `amount`. +- if `amount` is non-zero, `bytecode` must have a `payable` constructor. + +[.contract-item] +[[Create2-computeAddress-bytes32-bytes32-]] +==== `[.contract-item-name]#++computeAddress++#++(bytes32 salt, bytes32 bytecodeHash) → address++` [.item-kind]#internal# + +Returns the address where a contract will be stored if deployed via {deploy}. Any change in the +`bytecodeHash` or `salt` will result in a new destination address. + +[.contract-item] +[[Create2-computeAddress-bytes32-bytes32-address-]] +==== `[.contract-item-name]#++computeAddress++#++(bytes32 salt, bytes32 bytecodeHash, address deployer) → address addr++` [.item-kind]#internal# + +Returns the address where a contract will be stored if deployed via {deploy} from a contract located at +`deployer`. If `deployer` is this contract's address, returns the same value as {computeAddress}. + +[.contract-item] +[[Create2-Create2InsufficientBalance-uint256-uint256-]] +==== `[.contract-item-name]#++Create2InsufficientBalance++#++(uint256 balance, uint256 needed)++` [.item-kind]#error# + +Not enough balance for performing a CREATE2 deploy. + +[.contract-item] +[[Create2-Create2EmptyBytecode--]] +==== `[.contract-item-name]#++Create2EmptyBytecode++#++()++` [.item-kind]#error# + +There's no code to deploy. + +[.contract-item] +[[Create2-Create2FailedDeployment--]] +==== `[.contract-item-name]#++Create2FailedDeployment++#++()++` [.item-kind]#error# + +The deployment failed. + +:AddressInsufficientBalance: pass:normal[xref:#Address-AddressInsufficientBalance-address-[`++AddressInsufficientBalance++`]] +:AddressEmptyCode: pass:normal[xref:#Address-AddressEmptyCode-address-[`++AddressEmptyCode++`]] +:FailedInnerCall: pass:normal[xref:#Address-FailedInnerCall--[`++FailedInnerCall++`]] +:sendValue: pass:normal[xref:#Address-sendValue-address-payable-uint256-[`++sendValue++`]] +:functionCall: pass:normal[xref:#Address-functionCall-address-bytes-[`++functionCall++`]] +:functionCallWithValue: pass:normal[xref:#Address-functionCallWithValue-address-bytes-uint256-[`++functionCallWithValue++`]] +:functionStaticCall: pass:normal[xref:#Address-functionStaticCall-address-bytes-[`++functionStaticCall++`]] +:functionDelegateCall: pass:normal[xref:#Address-functionDelegateCall-address-bytes-[`++functionDelegateCall++`]] +:verifyCallResultFromTarget: pass:normal[xref:#Address-verifyCallResultFromTarget-address-bool-bytes-[`++verifyCallResultFromTarget++`]] +:verifyCallResult: pass:normal[xref:#Address-verifyCallResult-bool-bytes-[`++verifyCallResult++`]] + +[.contract] +[[Address]] +=== `++Address++` link:https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v5.0.0-rc.0/contracts/utils/Address.sol[{github-icon},role=heading-link] + +[.hljs-theme-light.nopadding] +```solidity +import "@openzeppelin/contracts/utils/Address.sol"; +``` + +Collection of functions related to the address type + +[.contract-index] +.Functions +-- +* {xref-Address-sendValue-address-payable-uint256-}[`++sendValue(recipient, amount)++`] +* {xref-Address-functionCall-address-bytes-}[`++functionCall(target, data)++`] +* {xref-Address-functionCallWithValue-address-bytes-uint256-}[`++functionCallWithValue(target, data, value)++`] +* {xref-Address-functionStaticCall-address-bytes-}[`++functionStaticCall(target, data)++`] +* {xref-Address-functionDelegateCall-address-bytes-}[`++functionDelegateCall(target, data)++`] +* {xref-Address-verifyCallResultFromTarget-address-bool-bytes-}[`++verifyCallResultFromTarget(target, success, returndata)++`] +* {xref-Address-verifyCallResult-bool-bytes-}[`++verifyCallResult(success, returndata)++`] + +-- + +[.contract-index] +.Errors +-- +* {xref-Address-AddressInsufficientBalance-address-}[`++AddressInsufficientBalance(account)++`] +* {xref-Address-AddressEmptyCode-address-}[`++AddressEmptyCode(target)++`] +* {xref-Address-FailedInnerCall--}[`++FailedInnerCall()++`] + +-- + +[.contract-item] +[[Address-sendValue-address-payable-uint256-]] +==== `[.contract-item-name]#++sendValue++#++(address payable recipient, uint256 amount)++` [.item-kind]#internal# + +Replacement for Solidity's `transfer`: sends `amount` wei to +`recipient`, forwarding all available gas and reverting on errors. + +https://eips.ethereum.org/EIPS/eip-1884[EIP1884] increases the gas cost +of certain opcodes, possibly making contracts go over the 2300 gas limit +imposed by `transfer`, making them unable to receive funds via +`transfer`. {sendValue} removes this limitation. + +https://consensys.net/diligence/blog/2019/09/stop-using-soliditys-transfer-now/[Learn more]. + +IMPORTANT: because control is transferred to `recipient`, care must be +taken to not create reentrancy vulnerabilities. Consider using +{ReentrancyGuard} or the +https://solidity.readthedocs.io/en/v0.8.20/security-considerations.html#use-the-checks-effects-interactions-pattern[checks-effects-interactions pattern]. + +[.contract-item] +[[Address-functionCall-address-bytes-]] +==== `[.contract-item-name]#++functionCall++#++(address target, bytes data) → bytes++` [.item-kind]#internal# + +Performs a Solidity function call using a low level `call`. A +plain `call` is an unsafe replacement for a function call: use this +function instead. + +If `target` reverts with a revert reason or custom error, it is bubbled +up by this function (like regular Solidity function calls). However, if +the call reverted with no returned reason, this function reverts with a +{FailedInnerCall} error. + +Returns the raw returned data. To convert to the expected return value, +use https://solidity.readthedocs.io/en/latest/units-and-global-variables.html?highlight=abi.decode#abi-encoding-and-decoding-functions[`abi.decode`]. + +Requirements: + +- `target` must be a contract. +- calling `target` with `data` must not revert. + +[.contract-item] +[[Address-functionCallWithValue-address-bytes-uint256-]] +==== `[.contract-item-name]#++functionCallWithValue++#++(address target, bytes data, uint256 value) → bytes++` [.item-kind]#internal# + +Same as {xref-Address-functionCall-address-bytes-}[`functionCall`], +but also transferring `value` wei to `target`. + +Requirements: + +- the calling contract must have an ETH balance of at least `value`. +- the called Solidity function must be `payable`. + +[.contract-item] +[[Address-functionStaticCall-address-bytes-]] +==== `[.contract-item-name]#++functionStaticCall++#++(address target, bytes data) → bytes++` [.item-kind]#internal# + +Same as {xref-Address-functionCall-address-bytes-}[`functionCall`], +but performing a static call. + +[.contract-item] +[[Address-functionDelegateCall-address-bytes-]] +==== `[.contract-item-name]#++functionDelegateCall++#++(address target, bytes data) → bytes++` [.item-kind]#internal# + +Same as {xref-Address-functionCall-address-bytes-}[`functionCall`], +but performing a delegate call. + +[.contract-item] +[[Address-verifyCallResultFromTarget-address-bool-bytes-]] +==== `[.contract-item-name]#++verifyCallResultFromTarget++#++(address target, bool success, bytes returndata) → bytes++` [.item-kind]#internal# + +Tool to verify that a low level call to smart-contract was successful, and reverts if the target +was not a contract or bubbling up the revert reason (falling back to {FailedInnerCall}) in case of an +unsuccessful call. + +[.contract-item] +[[Address-verifyCallResult-bool-bytes-]] +==== `[.contract-item-name]#++verifyCallResult++#++(bool success, bytes returndata) → bytes++` [.item-kind]#internal# + +Tool to verify that a low level call was successful, and reverts if it wasn't, either by bubbling the +revert reason or with a default {FailedInnerCall} error. + +[.contract-item] +[[Address-AddressInsufficientBalance-address-]] +==== `[.contract-item-name]#++AddressInsufficientBalance++#++(address account)++` [.item-kind]#error# + +The ETH balance of the account is not enough to perform the operation. + +[.contract-item] +[[Address-AddressEmptyCode-address-]] +==== `[.contract-item-name]#++AddressEmptyCode++#++(address target)++` [.item-kind]#error# + +There's no code at `target` (it is not a contract). + +[.contract-item] +[[Address-FailedInnerCall--]] +==== `[.contract-item-name]#++FailedInnerCall++#++()++` [.item-kind]#error# + +A call to an address target failed. The target may have reverted. + +:findUpperBound: pass:normal[xref:#Arrays-findUpperBound-uint256---uint256-[`++findUpperBound++`]] +:unsafeAccess: pass:normal[xref:#Arrays-unsafeAccess-address---uint256-[`++unsafeAccess++`]] +:unsafeAccess: pass:normal[xref:#Arrays-unsafeAccess-bytes32---uint256-[`++unsafeAccess++`]] +:unsafeAccess: pass:normal[xref:#Arrays-unsafeAccess-uint256---uint256-[`++unsafeAccess++`]] +:unsafeMemoryAccess: pass:normal[xref:#Arrays-unsafeMemoryAccess-uint256---uint256-[`++unsafeMemoryAccess++`]] +:unsafeMemoryAccess: pass:normal[xref:#Arrays-unsafeMemoryAccess-address---uint256-[`++unsafeMemoryAccess++`]] + +[.contract] +[[Arrays]] +=== `++Arrays++` link:https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v5.0.0-rc.0/contracts/utils/Arrays.sol[{github-icon},role=heading-link] + +[.hljs-theme-light.nopadding] +```solidity +import "@openzeppelin/contracts/utils/Arrays.sol"; +``` + +Collection of functions related to array types. + +[.contract-index] +.Functions +-- +* {xref-Arrays-findUpperBound-uint256---uint256-}[`++findUpperBound(array, element)++`] +* {xref-Arrays-unsafeAccess-address---uint256-}[`++unsafeAccess(arr, pos)++`] +* {xref-Arrays-unsafeAccess-bytes32---uint256-}[`++unsafeAccess(arr, pos)++`] +* {xref-Arrays-unsafeAccess-uint256---uint256-}[`++unsafeAccess(arr, pos)++`] +* {xref-Arrays-unsafeMemoryAccess-uint256---uint256-}[`++unsafeMemoryAccess(arr, pos)++`] +* {xref-Arrays-unsafeMemoryAccess-address---uint256-}[`++unsafeMemoryAccess(arr, pos)++`] + +-- + +[.contract-item] +[[Arrays-findUpperBound-uint256---uint256-]] +==== `[.contract-item-name]#++findUpperBound++#++(uint256[] array, uint256 element) → uint256++` [.item-kind]#internal# + +Searches a sorted `array` and returns the first index that contains +a value greater or equal to `element`. If no such index exists (i.e. all +values in the array are strictly less than `element`), the array length is +returned. Time complexity O(log n). + +`array` is expected to be sorted in ascending order, and to contain no +repeated elements. + +[.contract-item] +[[Arrays-unsafeAccess-address---uint256-]] +==== `[.contract-item-name]#++unsafeAccess++#++(address[] arr, uint256 pos) → struct StorageSlot.AddressSlot++` [.item-kind]#internal# + +Access an array in an "unsafe" way. Skips solidity "index-out-of-range" check. + +WARNING: Only use if you are certain `pos` is lower than the array length. + +[.contract-item] +[[Arrays-unsafeAccess-bytes32---uint256-]] +==== `[.contract-item-name]#++unsafeAccess++#++(bytes32[] arr, uint256 pos) → struct StorageSlot.Bytes32Slot++` [.item-kind]#internal# + +Access an array in an "unsafe" way. Skips solidity "index-out-of-range" check. + +WARNING: Only use if you are certain `pos` is lower than the array length. + +[.contract-item] +[[Arrays-unsafeAccess-uint256---uint256-]] +==== `[.contract-item-name]#++unsafeAccess++#++(uint256[] arr, uint256 pos) → struct StorageSlot.Uint256Slot++` [.item-kind]#internal# + +Access an array in an "unsafe" way. Skips solidity "index-out-of-range" check. + +WARNING: Only use if you are certain `pos` is lower than the array length. + +[.contract-item] +[[Arrays-unsafeMemoryAccess-uint256---uint256-]] +==== `[.contract-item-name]#++unsafeMemoryAccess++#++(uint256[] arr, uint256 pos) → uint256 res++` [.item-kind]#internal# + +Access an array in an "unsafe" way. Skips solidity "index-out-of-range" check. + +WARNING: Only use if you are certain `pos` is lower than the array length. + +[.contract-item] +[[Arrays-unsafeMemoryAccess-address---uint256-]] +==== `[.contract-item-name]#++unsafeMemoryAccess++#++(address[] arr, uint256 pos) → address res++` [.item-kind]#internal# + +Access an array in an "unsafe" way. Skips solidity "index-out-of-range" check. + +WARNING: Only use if you are certain `pos` is lower than the array length. + +:_TABLE: pass:normal[xref:#Base64-_TABLE-string[`++_TABLE++`]] +:encode: pass:normal[xref:#Base64-encode-bytes-[`++encode++`]] + +[.contract] +[[Base64]] +=== `++Base64++` link:https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v5.0.0-rc.0/contracts/utils/Base64.sol[{github-icon},role=heading-link] + +[.hljs-theme-light.nopadding] +```solidity +import "@openzeppelin/contracts/utils/Base64.sol"; +``` + +Provides a set of functions to operate with Base64 strings. + +[.contract-index] +.Functions +-- +* {xref-Base64-encode-bytes-}[`++encode(data)++`] + +-- + +[.contract-item] +[[Base64-encode-bytes-]] +==== `[.contract-item-name]#++encode++#++(bytes data) → string++` [.item-kind]#internal# + +Converts a `bytes` to its Bytes64 `string` representation. + +:StringsInsufficientHexLength: pass:normal[xref:#Strings-StringsInsufficientHexLength-uint256-uint256-[`++StringsInsufficientHexLength++`]] +:toString: pass:normal[xref:#Strings-toString-uint256-[`++toString++`]] +:toStringSigned: pass:normal[xref:#Strings-toStringSigned-int256-[`++toStringSigned++`]] +:toHexString: pass:normal[xref:#Strings-toHexString-uint256-[`++toHexString++`]] +:toHexString: pass:normal[xref:#Strings-toHexString-uint256-uint256-[`++toHexString++`]] +:toHexString: pass:normal[xref:#Strings-toHexString-address-[`++toHexString++`]] +:equal: pass:normal[xref:#Strings-equal-string-string-[`++equal++`]] + +[.contract] +[[Strings]] +=== `++Strings++` link:https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v5.0.0-rc.0/contracts/utils/Strings.sol[{github-icon},role=heading-link] + +[.hljs-theme-light.nopadding] +```solidity +import "@openzeppelin/contracts/utils/Strings.sol"; +``` + +String operations. + +[.contract-index] +.Functions +-- +* {xref-Strings-toString-uint256-}[`++toString(value)++`] +* {xref-Strings-toStringSigned-int256-}[`++toStringSigned(value)++`] +* {xref-Strings-toHexString-uint256-}[`++toHexString(value)++`] +* {xref-Strings-toHexString-uint256-uint256-}[`++toHexString(value, length)++`] +* {xref-Strings-toHexString-address-}[`++toHexString(addr)++`] +* {xref-Strings-equal-string-string-}[`++equal(a, b)++`] + +-- + +[.contract-index] +.Errors +-- +* {xref-Strings-StringsInsufficientHexLength-uint256-uint256-}[`++StringsInsufficientHexLength(value, length)++`] + +-- + +[.contract-item] +[[Strings-toString-uint256-]] +==== `[.contract-item-name]#++toString++#++(uint256 value) → string++` [.item-kind]#internal# + +Converts a `uint256` to its ASCII `string` decimal representation. + +[.contract-item] +[[Strings-toStringSigned-int256-]] +==== `[.contract-item-name]#++toStringSigned++#++(int256 value) → string++` [.item-kind]#internal# + +Converts a `int256` to its ASCII `string` decimal representation. + +[.contract-item] +[[Strings-toHexString-uint256-]] +==== `[.contract-item-name]#++toHexString++#++(uint256 value) → string++` [.item-kind]#internal# + +Converts a `uint256` to its ASCII `string` hexadecimal representation. + +[.contract-item] +[[Strings-toHexString-uint256-uint256-]] +==== `[.contract-item-name]#++toHexString++#++(uint256 value, uint256 length) → string++` [.item-kind]#internal# + +Converts a `uint256` to its ASCII `string` hexadecimal representation with fixed length. + +[.contract-item] +[[Strings-toHexString-address-]] +==== `[.contract-item-name]#++toHexString++#++(address addr) → string++` [.item-kind]#internal# + +Converts an `address` with fixed length of 20 bytes to its not checksummed ASCII `string` hexadecimal +representation. + +[.contract-item] +[[Strings-equal-string-string-]] +==== `[.contract-item-name]#++equal++#++(string a, string b) → bool++` [.item-kind]#internal# + +Returns true if the two strings are equal. + +[.contract-item] +[[Strings-StringsInsufficientHexLength-uint256-uint256-]] +==== `[.contract-item-name]#++StringsInsufficientHexLength++#++(uint256 value, uint256 length)++` [.item-kind]#error# + +The `value` string doesn't fit in the specified `length`. + +:StringTooLong: pass:normal[xref:#ShortStrings-StringTooLong-string-[`++StringTooLong++`]] +:InvalidShortString: pass:normal[xref:#ShortStrings-InvalidShortString--[`++InvalidShortString++`]] +:toShortString: pass:normal[xref:#ShortStrings-toShortString-string-[`++toShortString++`]] +:toString: pass:normal[xref:#ShortStrings-toString-ShortString-[`++toString++`]] +:byteLength: pass:normal[xref:#ShortStrings-byteLength-ShortString-[`++byteLength++`]] +:toShortStringWithFallback: pass:normal[xref:#ShortStrings-toShortStringWithFallback-string-string-[`++toShortStringWithFallback++`]] +:toStringWithFallback: pass:normal[xref:#ShortStrings-toStringWithFallback-ShortString-string-[`++toStringWithFallback++`]] +:byteLengthWithFallback: pass:normal[xref:#ShortStrings-byteLengthWithFallback-ShortString-string-[`++byteLengthWithFallback++`]] + +[.contract] +[[ShortStrings]] +=== `++ShortStrings++` link:https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v5.0.0-rc.0/contracts/utils/ShortStrings.sol[{github-icon},role=heading-link] + +[.hljs-theme-light.nopadding] +```solidity +import "@openzeppelin/contracts/utils/ShortStrings.sol"; +``` + +This library provides functions to convert short memory strings +into a `ShortString` type that can be used as an immutable variable. + +Strings of arbitrary length can be optimized using this library if +they are short enough (up to 31 bytes) by packing them with their +length (1 byte) in a single EVM word (32 bytes). Additionally, a +fallback mechanism can be used for every other case. + +Usage example: + +```solidity +contract Named { + using ShortStrings for *; + + ShortString private immutable _name; + string private _nameFallback; + + constructor(string memory contractName) { + _name = contractName.toShortStringWithFallback(_nameFallback); + } + + function name() external view returns (string memory) { + return _name.toStringWithFallback(_nameFallback); + } +} +``` + +[.contract-index] +.Functions +-- +* {xref-ShortStrings-toShortString-string-}[`++toShortString(str)++`] +* {xref-ShortStrings-toString-ShortString-}[`++toString(sstr)++`] +* {xref-ShortStrings-byteLength-ShortString-}[`++byteLength(sstr)++`] +* {xref-ShortStrings-toShortStringWithFallback-string-string-}[`++toShortStringWithFallback(value, store)++`] +* {xref-ShortStrings-toStringWithFallback-ShortString-string-}[`++toStringWithFallback(value, store)++`] +* {xref-ShortStrings-byteLengthWithFallback-ShortString-string-}[`++byteLengthWithFallback(value, store)++`] + +-- + +[.contract-index] +.Errors +-- +* {xref-ShortStrings-StringTooLong-string-}[`++StringTooLong(str)++`] +* {xref-ShortStrings-InvalidShortString--}[`++InvalidShortString()++`] + +-- + +[.contract-item] +[[ShortStrings-toShortString-string-]] +==== `[.contract-item-name]#++toShortString++#++(string str) → ShortString++` [.item-kind]#internal# + +Encode a string of at most 31 chars into a `ShortString`. + +This will trigger a `StringTooLong` error is the input string is too long. + +[.contract-item] +[[ShortStrings-toString-ShortString-]] +==== `[.contract-item-name]#++toString++#++(ShortString sstr) → string++` [.item-kind]#internal# + +Decode a `ShortString` back to a "normal" string. + +[.contract-item] +[[ShortStrings-byteLength-ShortString-]] +==== `[.contract-item-name]#++byteLength++#++(ShortString sstr) → uint256++` [.item-kind]#internal# + +Return the length of a `ShortString`. + +[.contract-item] +[[ShortStrings-toShortStringWithFallback-string-string-]] +==== `[.contract-item-name]#++toShortStringWithFallback++#++(string value, string store) → ShortString++` [.item-kind]#internal# + +Encode a string into a `ShortString`, or write it to storage if it is too long. + +[.contract-item] +[[ShortStrings-toStringWithFallback-ShortString-string-]] +==== `[.contract-item-name]#++toStringWithFallback++#++(ShortString value, string store) → string++` [.item-kind]#internal# + +Decode a string that was encoded to `ShortString` or written to storage using {setWithFallback}. + +[.contract-item] +[[ShortStrings-byteLengthWithFallback-ShortString-string-]] +==== `[.contract-item-name]#++byteLengthWithFallback++#++(ShortString value, string store) → uint256++` [.item-kind]#internal# + +Return the length of a string that was encoded to `ShortString` or written to storage using +{setWithFallback}. + +WARNING: This will return the "byte length" of the string. This may not reflect the actual length in terms of +actual characters as the UTF-8 encoding of a single character can span over multiple bytes. + +[.contract-item] +[[ShortStrings-StringTooLong-string-]] +==== `[.contract-item-name]#++StringTooLong++#++(string str)++` [.item-kind]#error# + +[.contract-item] +[[ShortStrings-InvalidShortString--]] +==== `[.contract-item-name]#++InvalidShortString++#++()++` [.item-kind]#error# + +:AddressSlot: pass:normal[xref:#StorageSlot-AddressSlot[`++AddressSlot++`]] +:BooleanSlot: pass:normal[xref:#StorageSlot-BooleanSlot[`++BooleanSlot++`]] +:Bytes32Slot: pass:normal[xref:#StorageSlot-Bytes32Slot[`++Bytes32Slot++`]] +:Uint256Slot: pass:normal[xref:#StorageSlot-Uint256Slot[`++Uint256Slot++`]] +:StringSlot: pass:normal[xref:#StorageSlot-StringSlot[`++StringSlot++`]] +:BytesSlot: pass:normal[xref:#StorageSlot-BytesSlot[`++BytesSlot++`]] +:getAddressSlot: pass:normal[xref:#StorageSlot-getAddressSlot-bytes32-[`++getAddressSlot++`]] +:getBooleanSlot: pass:normal[xref:#StorageSlot-getBooleanSlot-bytes32-[`++getBooleanSlot++`]] +:getBytes32Slot: pass:normal[xref:#StorageSlot-getBytes32Slot-bytes32-[`++getBytes32Slot++`]] +:getUint256Slot: pass:normal[xref:#StorageSlot-getUint256Slot-bytes32-[`++getUint256Slot++`]] +:getStringSlot: pass:normal[xref:#StorageSlot-getStringSlot-bytes32-[`++getStringSlot++`]] +:getStringSlot: pass:normal[xref:#StorageSlot-getStringSlot-string-[`++getStringSlot++`]] +:getBytesSlot: pass:normal[xref:#StorageSlot-getBytesSlot-bytes32-[`++getBytesSlot++`]] +:getBytesSlot: pass:normal[xref:#StorageSlot-getBytesSlot-bytes-[`++getBytesSlot++`]] + +[.contract] +[[StorageSlot]] +=== `++StorageSlot++` link:https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v5.0.0-rc.0/contracts/utils/StorageSlot.sol[{github-icon},role=heading-link] + +[.hljs-theme-light.nopadding] +```solidity +import "@openzeppelin/contracts/utils/StorageSlot.sol"; +``` + +Library for reading and writing primitive types to specific storage slots. + +Storage slots are often used to avoid storage conflict when dealing with upgradeable contracts. +This library helps with reading and writing to such slots without the need for inline assembly. + +The functions in this library return Slot structs that contain a `value` member that can be used to read or write. + +Example usage to set ERC1967 implementation slot: +```solidity +contract ERC1967 { + bytes32 internal constant _IMPLEMENTATION_SLOT = 0x360894a13ba1a3210667c828492db98dca3e2076cc3735a920a3ca505d382bbc; + + function _getImplementation() internal view returns (address) { + return StorageSlot.getAddressSlot(_IMPLEMENTATION_SLOT).value; + } + + function _setImplementation(address newImplementation) internal { + require(newImplementation.code.length > 0); + StorageSlot.getAddressSlot(_IMPLEMENTATION_SLOT).value = newImplementation; + } +} +``` + +[.contract-index] +.Functions +-- +* {xref-StorageSlot-getAddressSlot-bytes32-}[`++getAddressSlot(slot)++`] +* {xref-StorageSlot-getBooleanSlot-bytes32-}[`++getBooleanSlot(slot)++`] +* {xref-StorageSlot-getBytes32Slot-bytes32-}[`++getBytes32Slot(slot)++`] +* {xref-StorageSlot-getUint256Slot-bytes32-}[`++getUint256Slot(slot)++`] +* {xref-StorageSlot-getStringSlot-bytes32-}[`++getStringSlot(slot)++`] +* {xref-StorageSlot-getStringSlot-string-}[`++getStringSlot(store)++`] +* {xref-StorageSlot-getBytesSlot-bytes32-}[`++getBytesSlot(slot)++`] +* {xref-StorageSlot-getBytesSlot-bytes-}[`++getBytesSlot(store)++`] + +-- + +[.contract-item] +[[StorageSlot-getAddressSlot-bytes32-]] +==== `[.contract-item-name]#++getAddressSlot++#++(bytes32 slot) → struct StorageSlot.AddressSlot r++` [.item-kind]#internal# + +Returns an `AddressSlot` with member `value` located at `slot`. + +[.contract-item] +[[StorageSlot-getBooleanSlot-bytes32-]] +==== `[.contract-item-name]#++getBooleanSlot++#++(bytes32 slot) → struct StorageSlot.BooleanSlot r++` [.item-kind]#internal# + +Returns an `BooleanSlot` with member `value` located at `slot`. + +[.contract-item] +[[StorageSlot-getBytes32Slot-bytes32-]] +==== `[.contract-item-name]#++getBytes32Slot++#++(bytes32 slot) → struct StorageSlot.Bytes32Slot r++` [.item-kind]#internal# + +Returns an `Bytes32Slot` with member `value` located at `slot`. + +[.contract-item] +[[StorageSlot-getUint256Slot-bytes32-]] +==== `[.contract-item-name]#++getUint256Slot++#++(bytes32 slot) → struct StorageSlot.Uint256Slot r++` [.item-kind]#internal# + +Returns an `Uint256Slot` with member `value` located at `slot`. + +[.contract-item] +[[StorageSlot-getStringSlot-bytes32-]] +==== `[.contract-item-name]#++getStringSlot++#++(bytes32 slot) → struct StorageSlot.StringSlot r++` [.item-kind]#internal# + +Returns an `StringSlot` with member `value` located at `slot`. + +[.contract-item] +[[StorageSlot-getStringSlot-string-]] +==== `[.contract-item-name]#++getStringSlot++#++(string store) → struct StorageSlot.StringSlot r++` [.item-kind]#internal# + +Returns an `StringSlot` representation of the string storage pointer `store`. + +[.contract-item] +[[StorageSlot-getBytesSlot-bytes32-]] +==== `[.contract-item-name]#++getBytesSlot++#++(bytes32 slot) → struct StorageSlot.BytesSlot r++` [.item-kind]#internal# + +Returns an `BytesSlot` with member `value` located at `slot`. + +[.contract-item] +[[StorageSlot-getBytesSlot-bytes-]] +==== `[.contract-item-name]#++getBytesSlot++#++(bytes store) → struct StorageSlot.BytesSlot r++` [.item-kind]#internal# + +Returns an `BytesSlot` representation of the bytes storage pointer `store`. + +:multicall: pass:normal[xref:#Multicall-multicall-bytes---[`++multicall++`]] + +[.contract] +[[Multicall]] +=== `++Multicall++` link:https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v5.0.0-rc.0/contracts/utils/Multicall.sol[{github-icon},role=heading-link] + +[.hljs-theme-light.nopadding] +```solidity +import "@openzeppelin/contracts/utils/Multicall.sol"; +``` + +Provides a function to batch together multiple calls in a single external call. + +[.contract-index] +.Functions +-- +* {xref-Multicall-multicall-bytes---}[`++multicall(data)++`] + +-- + +[.contract-item] +[[Multicall-multicall-bytes---]] +==== `[.contract-item-name]#++multicall++#++(bytes[] data) → bytes[] results++` [.item-kind]#external# + +Receives and executes a batch of function calls on this contract. + diff --git a/docs/templates/contract.hbs b/docs/templates/contract.hbs new file mode 100644 index 000000000..a4716825a --- /dev/null +++ b/docs/templates/contract.hbs @@ -0,0 +1,111 @@ +{{#each items}} +:{{name}}: pass:normal[xref:#{{anchor}}[`++{{name}}++`]] +{{/each}} + +[.contract] +[[{{anchor}}]] +=== `++{{name}}++` link:https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v{{oz-version}}/{{__item_context.file.absolutePath}}[{github-icon},role=heading-link] + +[.hljs-theme-light.nopadding] +```solidity +import "@openzeppelin/{{__item_context.file.absolutePath}}"; +``` + +{{{natspec.dev}}} + +{{#if modifiers}} +[.contract-index] +.Modifiers +-- +{{#each modifiers}} +* {xref-{{anchor~}} }[`++{{name}}({{names params}})++`] +{{/each}} +-- +{{/if}} + +{{#if has-functions}} +[.contract-index] +.Functions +-- +{{#each inherited-functions}} +{{#unless @first}} +[.contract-subindex-inherited] +.{{contract.name}} +{{/unless}} +{{#each functions}} +* {xref-{{anchor~}} }[`++{{name}}({{names params}})++`] +{{/each}} + +{{/each}} +-- +{{/if}} + +{{#if has-events}} +[.contract-index] +.Events +-- +{{#each inheritance}} +{{#unless @first}} +[.contract-subindex-inherited] +.{{name}} +{{/unless}} +{{#each events}} +* {xref-{{anchor~}} }[`++{{name}}({{names params}})++`] +{{/each}} + +{{/each}} +-- +{{/if}} + +{{#if has-errors}} +[.contract-index] +.Errors +-- +{{#each inheritance}} +{{#unless @first}} +[.contract-subindex-inherited] +.{{name}} +{{/unless}} +{{#each errors}} +* {xref-{{anchor~}} }[`++{{name}}({{names params}})++`] +{{/each}} + +{{/each}} +-- +{{/if}} + +{{#each modifiers}} +[.contract-item] +[[{{anchor}}]] +==== `[.contract-item-name]#++{{name}}++#++({{typed-params params}})++` [.item-kind]#modifier# + +{{{natspec.dev}}} + +{{/each}} + +{{#each functions}} +[.contract-item] +[[{{anchor}}]] +==== `[.contract-item-name]#++{{name}}++#++({{typed-params params}}){{#if returns}} → {{typed-params returns}}{{/if}}++` [.item-kind]#{{visibility}}# + +{{{natspec.dev}}} + +{{/each}} + +{{#each events}} +[.contract-item] +[[{{anchor}}]] +==== `[.contract-item-name]#++{{name}}++#++({{typed-params params}})++` [.item-kind]#event# + +{{{natspec.dev}}} + +{{/each}} + +{{#each errors}} +[.contract-item] +[[{{anchor}}]] +==== `[.contract-item-name]#++{{name}}++#++({{typed-params params}})++` [.item-kind]#error# + +{{{natspec.dev}}} + +{{/each}} diff --git a/docs/templates/helpers.js b/docs/templates/helpers.js new file mode 100644 index 000000000..65f168eba --- /dev/null +++ b/docs/templates/helpers.js @@ -0,0 +1,46 @@ +const { version } = require('../../package.json'); + +module.exports['oz-version'] = () => version; + +module.exports['readme-path'] = opts => { + return 'contracts/' + opts.data.root.id.replace(/\.adoc$/, '') + '/README.adoc'; +}; + +module.exports.names = params => params.map(p => p.name).join(', '); + +module.exports['typed-params'] = params => { + return params?.map(p => `${p.type}${p.indexed ? ' indexed' : ''}${p.name ? ' ' + p.name : ''}`).join(', '); +}; + +const slug = (module.exports.slug = str => { + if (str === undefined) { + throw new Error('Missing argument'); + } + return str.replace(/\W/g, '-'); +}); + +const linksCache = new WeakMap(); + +function getAllLinks(items) { + if (linksCache.has(items)) { + return linksCache.get(items); + } + const res = {}; + linksCache.set(items, res); + for (const item of items) { + res[`xref-${item.anchor}`] = `xref:${item.__item_context.page}#${item.anchor}`; + res[slug(item.fullName)] = `pass:normal[xref:${item.__item_context.page}#${item.anchor}[\`${item.fullName}\`]]`; + } + return res; +} + +module.exports['with-prelude'] = opts => { + const links = getAllLinks(opts.data.site.items); + const contents = opts.fn(); + const neededLinks = contents + .match(/\{[-._a-z0-9]+\}/gi) + .map(m => m.replace(/^\{(.+)\}$/, '$1')) + .filter(k => k in links); + const prelude = neededLinks.map(k => `:${k}: ${links[k]}`).join('\n'); + return prelude + '\n' + contents; +}; diff --git a/docs/templates/page.hbs b/docs/templates/page.hbs new file mode 100644 index 000000000..cab050acb --- /dev/null +++ b/docs/templates/page.hbs @@ -0,0 +1,4 @@ +:github-icon: pass:[] +{{#with-prelude}} +{{readme (readme-path)}} +{{/with-prelude}} diff --git a/docs/templates/properties.js b/docs/templates/properties.js new file mode 100644 index 000000000..584c0abca --- /dev/null +++ b/docs/templates/properties.js @@ -0,0 +1,49 @@ +const { isNodeType } = require('solidity-ast/utils'); +const { slug } = require('./helpers'); + +module.exports.anchor = function anchor({ item, contract }) { + let res = ''; + if (contract) { + res += contract.name + '-'; + } + res += item.name; + if ('parameters' in item) { + const signature = item.parameters.parameters.map(v => v.typeName.typeDescriptions.typeString).join(','); + res += slug('(' + signature + ')'); + } + if (isNodeType('VariableDeclaration', item)) { + res += '-' + slug(item.typeName.typeDescriptions.typeString); + } + return res; +}; + +module.exports.inheritance = function ({ item, build }) { + if (!isNodeType('ContractDefinition', item)) { + throw new Error('used inherited-items on non-contract'); + } + + return item.linearizedBaseContracts + .map(id => build.deref('ContractDefinition', id)) + .filter((c, i) => c.name !== 'Context' || i === 0); +}; + +module.exports['has-functions'] = function ({ item }) { + return item.inheritance.some(c => c.functions.length > 0); +}; + +module.exports['has-events'] = function ({ item }) { + return item.inheritance.some(c => c.events.length > 0); +}; + +module.exports['has-errors'] = function ({ item }) { + return item.inheritance.some(c => c.errors.length > 0); +}; + +module.exports['inherited-functions'] = function ({ item }) { + const { inheritance } = item; + const baseFunctions = new Set(inheritance.flatMap(c => c.functions.flatMap(f => f.baseFunctions ?? []))); + return inheritance.map((contract, i) => ({ + contract, + functions: contract.functions.filter(f => !baseFunctions.has(f.id) && (f.name !== 'constructor' || i === 0)), + })); +}; diff --git a/foundry.toml b/foundry.toml new file mode 100644 index 000000000..d0aa4ea39 --- /dev/null +++ b/foundry.toml @@ -0,0 +1,3 @@ +[fuzz] +runs = 10000 +max_test_rejects = 150000 diff --git a/hardhat.config.js b/hardhat.config.js new file mode 100644 index 000000000..1c87aac94 --- /dev/null +++ b/hardhat.config.js @@ -0,0 +1,115 @@ +/// ENVVAR +// - CI: output gas report to file instead of stdout +// - COVERAGE: enable coverage report +// - ENABLE_GAS_REPORT: enable gas report +// - COMPILE_MODE: production modes enables optimizations (default: development) +// - COMPILE_VERSION: compiler version (default: 0.8.20) +// - COINMARKETCAP: coinmarkercat api key for USD value in gas report + +const fs = require('fs'); +const path = require('path'); +const argv = require('yargs/yargs')() + .env('') + .options({ + coverage: { + type: 'boolean', + default: false, + }, + gas: { + alias: 'enableGasReport', + type: 'boolean', + default: false, + }, + gasReport: { + alias: 'enableGasReportPath', + type: 'string', + implies: 'gas', + default: undefined, + }, + mode: { + alias: 'compileMode', + type: 'string', + choices: ['production', 'development'], + default: 'development', + }, + ir: { + alias: 'enableIR', + type: 'boolean', + default: false, + }, + compiler: { + alias: 'compileVersion', + type: 'string', + default: '0.8.20', + }, + coinmarketcap: { + alias: 'coinmarketcapApiKey', + type: 'string', + }, + }).argv; + +require('@nomiclabs/hardhat-truffle5'); +require('hardhat-ignore-warnings'); +require('hardhat-exposed'); + +require('solidity-docgen'); + +for (const f of fs.readdirSync(path.join(__dirname, 'hardhat'))) { + require(path.join(__dirname, 'hardhat', f)); +} + +const withOptimizations = argv.gas || argv.compileMode === 'production'; + +/** + * @type import('hardhat/config').HardhatUserConfig + */ +module.exports = { + solidity: { + version: argv.compiler, + settings: { + optimizer: { + enabled: withOptimizations, + runs: 200, + }, + viaIR: withOptimizations && argv.ir, + outputSelection: { '*': { '*': ['storageLayout'] } }, + }, + }, + warnings: { + 'contracts-exposed/**/*': { + 'code-size': 'off', + 'initcode-size': 'off', + }, + '*': { + 'code-size': withOptimizations, + 'unused-param': !argv.coverage, // coverage causes unused-param warnings + default: 'error', + }, + }, + networks: { + hardhat: { + blockGasLimit: 10000000, + allowUnlimitedContractSize: !withOptimizations, + }, + }, + exposed: { + initializers: true, + exclude: ['vendor/**/*'], + }, + docgen: require('./docs/config'), +}; + +if (argv.gas) { + require('hardhat-gas-reporter'); + module.exports.gasReporter = { + showMethodSig: true, + currency: 'USD', + outputFile: argv.gasReport, + coinmarketcap: argv.coinmarketcap, + }; +} + +if (argv.coverage) { + require('solidity-coverage'); + module.exports.networks.hardhat.initialBaseFeePerGas = 0; +} diff --git a/hardhat/env-artifacts.js b/hardhat/env-artifacts.js new file mode 100644 index 000000000..fbbea2e2d --- /dev/null +++ b/hardhat/env-artifacts.js @@ -0,0 +1,24 @@ +const { HardhatError } = require('hardhat/internal/core/errors'); + +// Modifies `artifacts.require(X)` so that instead of X it loads the XUpgradeable contract. +// This allows us to run the same test suite on both the original and the transpiled and renamed Upgradeable contracts. + +extendEnvironment(env => { + const artifactsRequire = env.artifacts.require; + + env.artifacts.require = name => { + for (const suffix of ['UpgradeableWithInit', 'Upgradeable', '']) { + try { + return artifactsRequire(name + suffix); + } catch (e) { + // HH700: Artifact not found - from https://hardhat.org/hardhat-runner/docs/errors#HH700 + if (HardhatError.isHardhatError(e) && e.number === 700 && suffix !== '') { + continue; + } else { + throw e; + } + } + } + throw new Error('Unreachable'); + }; +}); diff --git a/hardhat/env-contract.js b/hardhat/env-contract.js new file mode 100644 index 000000000..74d54cfbb --- /dev/null +++ b/hardhat/env-contract.js @@ -0,0 +1,10 @@ +extendEnvironment(env => { + const { contract } = env; + + env.contract = function (name, body) { + // remove the default account from the accounts list used in tests, in order + // to protect tests against accidentally passing due to the contract + // deployer being used subsequently as function caller + contract(name, accounts => body(accounts.slice(1))); + }; +}); diff --git a/hardhat/ignore-unreachable-warnings.js b/hardhat/ignore-unreachable-warnings.js new file mode 100644 index 000000000..8e3e34340 --- /dev/null +++ b/hardhat/ignore-unreachable-warnings.js @@ -0,0 +1,45 @@ +// Warnings about unreachable code are emitted with a source location that corresponds to the unreachable code. +// We have some testing contracts that purposely cause unreachable code, but said code is in the library contracts, and +// with hardhat-ignore-warnings we are not able to selectively ignore them without potentially ignoring relevant +// warnings that we don't want to miss. +// Thus, we need to handle these warnings separately. We force Hardhat to compile them in a separate compilation job and +// then ignore the warnings about unreachable code that come from that compilation job. + +const { task } = require('hardhat/config'); +const { + TASK_COMPILE_SOLIDITY_GET_COMPILATION_JOB_FOR_FILE, + TASK_COMPILE_SOLIDITY_COMPILE, +} = require('hardhat/builtin-tasks/task-names'); + +const marker = Symbol('unreachable'); +const markedCache = new WeakMap(); + +task(TASK_COMPILE_SOLIDITY_GET_COMPILATION_JOB_FOR_FILE, async (params, _, runSuper) => { + const job = await runSuper(params); + // If the file is in the unreachable directory, we make a copy of the config and mark it, which will cause it to get + // compiled separately (along with the other marked files). + if (params.file.sourceName.startsWith('contracts/mocks/') && /\bunreachable\b/.test(params.file.sourceName)) { + const originalConfig = job.solidityConfig; + let markedConfig = markedCache.get(originalConfig); + if (markedConfig === undefined) { + markedConfig = { ...originalConfig, [marker]: true }; + markedCache.set(originalConfig, markedConfig); + } + job.solidityConfig = markedConfig; + } + return job; +}); + +const W_UNREACHABLE_CODE = '5740'; + +task(TASK_COMPILE_SOLIDITY_COMPILE, async (params, _, runSuper) => { + const marked = params.compilationJob.solidityConfig[marker]; + const result = await runSuper(params); + if (marked) { + result.output = { + ...result.output, + errors: result.output.errors?.filter(e => e.severity !== 'warning' || e.errorCode !== W_UNREACHABLE_CODE), + }; + } + return result; +}); diff --git a/hardhat/skip-foundry-tests.js b/hardhat/skip-foundry-tests.js new file mode 100644 index 000000000..965ba37c3 --- /dev/null +++ b/hardhat/skip-foundry-tests.js @@ -0,0 +1,6 @@ +const { subtask } = require('hardhat/config'); +const { TASK_COMPILE_SOLIDITY_GET_SOURCE_PATHS } = require('hardhat/builtin-tasks/task-names'); + +subtask(TASK_COMPILE_SOLIDITY_GET_SOURCE_PATHS).setAction(async (_, __, runSuper) => + (await runSuper()).filter(path => !path.endsWith('.t.sol')), +); diff --git a/hardhat/task-test-get-files.js b/hardhat/task-test-get-files.js new file mode 100644 index 000000000..108f40a42 --- /dev/null +++ b/hardhat/task-test-get-files.js @@ -0,0 +1,25 @@ +const { internalTask } = require('hardhat/config'); +const { TASK_TEST_GET_TEST_FILES } = require('hardhat/builtin-tasks/task-names'); + +// Modifies `hardhat test` to skip the proxy tests after proxies are removed by the transpiler for upgradeability. + +internalTask(TASK_TEST_GET_TEST_FILES).setAction(async (args, hre, runSuper) => { + const path = require('path'); + const { promises: fs } = require('fs'); + + const hasProxies = await fs + .access(path.join(hre.config.paths.sources, 'proxy/Proxy.sol')) + .then(() => true) + .catch(() => false); + + const ignoredIfProxy = [ + 'proxy/beacon/BeaconProxy.test.js', + 'proxy/beacon/UpgradeableBeacon.test.js', + 'proxy/ERC1967/ERC1967Proxy.test.js', + 'proxy/transparent/ProxyAdmin.test.js', + 'proxy/transparent/TransparentUpgradeableProxy.test.js', + 'proxy/utils/UUPSUpgradeable.test.js', + ].map(p => path.join(hre.config.paths.tests, p)); + + return (await runSuper(args)).filter(file => hasProxies || !ignoredIfProxy.includes(file)); +}); diff --git a/lib/erc4626-tests b/lib/erc4626-tests new file mode 160000 index 000000000..8b1d7c2ac --- /dev/null +++ b/lib/erc4626-tests @@ -0,0 +1 @@ +Subproject commit 8b1d7c2ac248c33c3506b1bff8321758943c5e11 diff --git a/lib/forge-std b/lib/forge-std new file mode 160000 index 000000000..eb980e1d4 --- /dev/null +++ b/lib/forge-std @@ -0,0 +1 @@ +Subproject commit eb980e1d4f0e8173ec27da77297ae411840c8ccb diff --git a/logo.svg b/logo.svg new file mode 100644 index 000000000..f1e14c2bb --- /dev/null +++ b/logo.svg @@ -0,0 +1,15 @@ + + + + + + + + + + + + + + + diff --git a/netlify.toml b/netlify.toml new file mode 100644 index 000000000..0447f41ad --- /dev/null +++ b/netlify.toml @@ -0,0 +1,3 @@ +[build] +command = "npm run docs" +publish = "build/site" diff --git a/package-lock.json b/package-lock.json new file mode 100644 index 000000000..ea4c6db0d --- /dev/null +++ b/package-lock.json @@ -0,0 +1,27465 @@ +{ + "name": "openzeppelin-solidity", + "version": "4.9.2", + "lockfileVersion": 2, + "requires": true, + "packages": { + "": { + "name": "openzeppelin-solidity", + "version": "4.9.2", + "license": "MIT", + "devDependencies": { + "@changesets/changelog-github": "^0.4.8", + "@changesets/cli": "^2.26.0", + "@changesets/pre": "^1.0.14", + "@changesets/read": "^0.5.9", + "@nomicfoundation/hardhat-network-helpers": "^1.0.3", + "@nomiclabs/hardhat-truffle5": "^2.0.5", + "@nomiclabs/hardhat-web3": "^2.0.0", + "@openzeppelin/docs-utils": "^0.1.4", + "@openzeppelin/test-helpers": "^0.5.13", + "@openzeppelin/upgrades-core": "^1.20.6", + "array.prototype.at": "^1.1.1", + "chai": "^4.2.0", + "eslint": "^8.30.0", + "eslint-config-prettier": "^9.0.0", + "eth-sig-util": "^3.0.0", + "ethereumjs-util": "^7.0.7", + "ethereumjs-wallet": "^1.0.1", + "glob": "^8.0.3", + "graphlib": "^2.1.8", + "hardhat": "^2.9.1", + "hardhat-exposed": "^0.3.11", + "hardhat-gas-reporter": "^1.0.4", + "hardhat-ignore-warnings": "^0.2.0", + "keccak256": "^1.0.2", + "lodash.startcase": "^4.4.0", + "lodash.zip": "^4.2.0", + "merkletreejs": "^0.2.13", + "micromatch": "^4.0.2", + "p-limit": "^3.1.0", + "prettier": "^3.0.0", + "prettier-plugin-solidity": "^1.1.0", + "rimraf": "^3.0.2", + "semver": "^7.3.5", + "solhint": "^3.3.6", + "solhint-plugin-openzeppelin": "file:scripts/solhint-custom", + "solidity-ast": "^0.4.50", + "solidity-coverage": "^0.8.0", + "solidity-docgen": "^0.6.0-beta.29", + "undici": "^5.22.1", + "web3": "^1.3.0", + "yargs": "^17.0.0" + } + }, + "node_modules/@aashutoshrathi/word-wrap": { + "version": "1.2.6", + "resolved": "https://registry.npmjs.org/@aashutoshrathi/word-wrap/-/word-wrap-1.2.6.tgz", + "integrity": "sha512-1Yjs2SvM8TflER/OD3cOjhWWOZb58A2t7wpE2S9XfBYTiIl+XFhQG2bjy4Pu1I+EAlCNUzRDYDdFwFYUKvXcIA==", + "dev": true, + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/@babel/code-frame": { + "version": "7.22.5", + "resolved": "https://registry.npmjs.org/@babel/code-frame/-/code-frame-7.22.5.tgz", + "integrity": "sha512-Xmwn266vad+6DAqEB2A6V/CcZVp62BbwVmcOJc2RPuwih1kw02TjQvWVWlcKGbBPd+8/0V5DEkOcizRGYsspYQ==", + "dev": true, + "dependencies": { + "@babel/highlight": "^7.22.5" + }, + "engines": { + "node": ">=6.9.0" + } + }, + "node_modules/@babel/helper-validator-identifier": { + "version": "7.22.5", + "resolved": "https://registry.npmjs.org/@babel/helper-validator-identifier/-/helper-validator-identifier-7.22.5.tgz", + "integrity": "sha512-aJXu+6lErq8ltp+JhkJUfk1MTGyuA4v7f3pA+BJ5HLfNC6nAQ0Cpi9uOquUj8Hehg0aUiHzWQbOVJGao6ztBAQ==", + "dev": true, + "engines": { + "node": ">=6.9.0" + } + }, + "node_modules/@babel/highlight": { + "version": "7.22.5", + "resolved": "https://registry.npmjs.org/@babel/highlight/-/highlight-7.22.5.tgz", + "integrity": "sha512-BSKlD1hgnedS5XRnGOljZawtag7H1yPfQp0tdNJCHoH6AZ+Pcm9VvkrK59/Yy593Ypg0zMxH2BxD1VPYUQ7UIw==", + "dev": true, + "dependencies": { + "@babel/helper-validator-identifier": "^7.22.5", + "chalk": "^2.0.0", + "js-tokens": "^4.0.0" + }, + "engines": { + "node": ">=6.9.0" + } + }, + "node_modules/@babel/runtime": { + "version": "7.22.6", + "resolved": "https://registry.npmjs.org/@babel/runtime/-/runtime-7.22.6.tgz", + "integrity": "sha512-wDb5pWm4WDdF6LFUde3Jl8WzPA+3ZbxYqkC6xAXuD3irdEHN1k0NfTRrJD8ZD378SJ61miMLCqIOXYhd8x+AJQ==", + "dev": true, + "dependencies": { + "regenerator-runtime": "^0.13.11" + }, + "engines": { + "node": ">=6.9.0" + } + }, + "node_modules/@chainsafe/as-sha256": { + "version": "0.3.1", + "resolved": "https://registry.npmjs.org/@chainsafe/as-sha256/-/as-sha256-0.3.1.tgz", + "integrity": "sha512-hldFFYuf49ed7DAakWVXSJODuq3pzJEguD8tQ7h+sGkM18vja+OFoJI9krnGmgzyuZC2ETX0NOIcCTy31v2Mtg==", + "dev": true + }, + "node_modules/@chainsafe/persistent-merkle-tree": { + "version": "0.4.2", + "resolved": "https://registry.npmjs.org/@chainsafe/persistent-merkle-tree/-/persistent-merkle-tree-0.4.2.tgz", + "integrity": "sha512-lLO3ihKPngXLTus/L7WHKaw9PnNJWizlOF1H9NNzHP6Xvh82vzg9F2bzkXhYIFshMZ2gTCEz8tq6STe7r5NDfQ==", + "dev": true, + "dependencies": { + "@chainsafe/as-sha256": "^0.3.1" + } + }, + "node_modules/@chainsafe/ssz": { + "version": "0.9.4", + "resolved": "https://registry.npmjs.org/@chainsafe/ssz/-/ssz-0.9.4.tgz", + "integrity": "sha512-77Qtg2N1ayqs4Bg/wvnWfg5Bta7iy7IRh8XqXh7oNMeP2HBbBwx8m6yTpA8p0EHItWPEBkgZd5S5/LSlp3GXuQ==", + "dev": true, + "dependencies": { + "@chainsafe/as-sha256": "^0.3.1", + "@chainsafe/persistent-merkle-tree": "^0.4.2", + "case": "^1.6.3" + } + }, + "node_modules/@changesets/apply-release-plan": { + "version": "6.1.4", + "resolved": "https://registry.npmjs.org/@changesets/apply-release-plan/-/apply-release-plan-6.1.4.tgz", + "integrity": "sha512-FMpKF1fRlJyCZVYHr3CbinpZZ+6MwvOtWUuO8uo+svcATEoc1zRDcj23pAurJ2TZ/uVz1wFHH6K3NlACy0PLew==", + "dev": true, + "dependencies": { + "@babel/runtime": "^7.20.1", + "@changesets/config": "^2.3.1", + "@changesets/get-version-range-type": "^0.3.2", + "@changesets/git": "^2.0.0", + "@changesets/types": "^5.2.1", + "@manypkg/get-packages": "^1.1.3", + "detect-indent": "^6.0.0", + "fs-extra": "^7.0.1", + "lodash.startcase": "^4.4.0", + "outdent": "^0.5.0", + "prettier": "^2.7.1", + "resolve-from": "^5.0.0", + "semver": "^7.5.3" + } + }, + "node_modules/@changesets/apply-release-plan/node_modules/prettier": { + "version": "2.8.8", + "resolved": "https://registry.npmjs.org/prettier/-/prettier-2.8.8.tgz", + "integrity": "sha512-tdN8qQGvNjw4CHbY+XXk0JgCXn9QiF21a55rBe5LJAU+kDyC4WQn4+awm2Xfk2lQMk5fKup9XgzTZtGkjBdP9Q==", + "dev": true, + "bin": { + "prettier": "bin-prettier.js" + }, + "engines": { + "node": ">=10.13.0" + }, + "funding": { + "url": "https://github.com/prettier/prettier?sponsor=1" + } + }, + "node_modules/@changesets/assemble-release-plan": { + "version": "5.2.4", + "resolved": "https://registry.npmjs.org/@changesets/assemble-release-plan/-/assemble-release-plan-5.2.4.tgz", + "integrity": "sha512-xJkWX+1/CUaOUWTguXEbCDTyWJFECEhmdtbkjhn5GVBGxdP/JwaHBIU9sW3FR6gD07UwZ7ovpiPclQZs+j+mvg==", + "dev": true, + "dependencies": { + "@babel/runtime": "^7.20.1", + "@changesets/errors": "^0.1.4", + "@changesets/get-dependents-graph": "^1.3.6", + "@changesets/types": "^5.2.1", + "@manypkg/get-packages": "^1.1.3", + "semver": "^7.5.3" + } + }, + "node_modules/@changesets/changelog-git": { + "version": "0.1.14", + "resolved": "https://registry.npmjs.org/@changesets/changelog-git/-/changelog-git-0.1.14.tgz", + "integrity": "sha512-+vRfnKtXVWsDDxGctOfzJsPhaCdXRYoe+KyWYoq5X/GqoISREiat0l3L8B0a453B2B4dfHGcZaGyowHbp9BSaA==", + "dev": true, + "dependencies": { + "@changesets/types": "^5.2.1" + } + }, + "node_modules/@changesets/changelog-github": { + "version": "0.4.8", + "resolved": "https://registry.npmjs.org/@changesets/changelog-github/-/changelog-github-0.4.8.tgz", + "integrity": "sha512-jR1DHibkMAb5v/8ym77E4AMNWZKB5NPzw5a5Wtqm1JepAuIF+hrKp2u04NKM14oBZhHglkCfrla9uq8ORnK/dw==", + "dev": true, + "dependencies": { + "@changesets/get-github-info": "^0.5.2", + "@changesets/types": "^5.2.1", + "dotenv": "^8.1.0" + } + }, + "node_modules/@changesets/cli": { + "version": "2.26.2", + "resolved": "https://registry.npmjs.org/@changesets/cli/-/cli-2.26.2.tgz", + "integrity": "sha512-dnWrJTmRR8bCHikJHl9b9HW3gXACCehz4OasrXpMp7sx97ECuBGGNjJhjPhdZNCvMy9mn4BWdplI323IbqsRig==", + "dev": true, + "dependencies": { + "@babel/runtime": "^7.20.1", + "@changesets/apply-release-plan": "^6.1.4", + "@changesets/assemble-release-plan": "^5.2.4", + "@changesets/changelog-git": "^0.1.14", + "@changesets/config": "^2.3.1", + "@changesets/errors": "^0.1.4", + "@changesets/get-dependents-graph": "^1.3.6", + "@changesets/get-release-plan": "^3.0.17", + "@changesets/git": "^2.0.0", + "@changesets/logger": "^0.0.5", + "@changesets/pre": "^1.0.14", + "@changesets/read": "^0.5.9", + "@changesets/types": "^5.2.1", + "@changesets/write": "^0.2.3", + "@manypkg/get-packages": "^1.1.3", + "@types/is-ci": "^3.0.0", + "@types/semver": "^7.5.0", + "ansi-colors": "^4.1.3", + "chalk": "^2.1.0", + "enquirer": "^2.3.0", + "external-editor": "^3.1.0", + "fs-extra": "^7.0.1", + "human-id": "^1.0.2", + "is-ci": "^3.0.1", + "meow": "^6.0.0", + "outdent": "^0.5.0", + "p-limit": "^2.2.0", + "preferred-pm": "^3.0.0", + "resolve-from": "^5.0.0", + "semver": "^7.5.3", + "spawndamnit": "^2.0.0", + "term-size": "^2.1.0", + "tty-table": "^4.1.5" + }, + "bin": { + "changeset": "bin.js" + } + }, + "node_modules/@changesets/cli/node_modules/p-limit": { + "version": "2.3.0", + "resolved": "https://registry.npmjs.org/p-limit/-/p-limit-2.3.0.tgz", + "integrity": "sha512-//88mFWSJx8lxCzwdAABTJL2MyWB12+eIY7MDL2SqLmAkeKU9qxRvWuSyTjm3FUmpBEMuFfckAIqEaVGUDxb6w==", + "dev": true, + "dependencies": { + "p-try": "^2.0.0" + }, + "engines": { + "node": ">=6" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/@changesets/config": { + "version": "2.3.1", + "resolved": "https://registry.npmjs.org/@changesets/config/-/config-2.3.1.tgz", + "integrity": "sha512-PQXaJl82CfIXddUOppj4zWu+987GCw2M+eQcOepxN5s+kvnsZOwjEJO3DH9eVy+OP6Pg/KFEWdsECFEYTtbg6w==", + "dev": true, + "dependencies": { + "@changesets/errors": "^0.1.4", + "@changesets/get-dependents-graph": "^1.3.6", + "@changesets/logger": "^0.0.5", + "@changesets/types": "^5.2.1", + "@manypkg/get-packages": "^1.1.3", + "fs-extra": "^7.0.1", + "micromatch": "^4.0.2" + } + }, + "node_modules/@changesets/errors": { + "version": "0.1.4", + "resolved": "https://registry.npmjs.org/@changesets/errors/-/errors-0.1.4.tgz", + "integrity": "sha512-HAcqPF7snsUJ/QzkWoKfRfXushHTu+K5KZLJWPb34s4eCZShIf8BFO3fwq6KU8+G7L5KdtN2BzQAXOSXEyiY9Q==", + "dev": true, + "dependencies": { + "extendable-error": "^0.1.5" + } + }, + "node_modules/@changesets/get-dependents-graph": { + "version": "1.3.6", + "resolved": "https://registry.npmjs.org/@changesets/get-dependents-graph/-/get-dependents-graph-1.3.6.tgz", + "integrity": "sha512-Q/sLgBANmkvUm09GgRsAvEtY3p1/5OCzgBE5vX3vgb5CvW0j7CEljocx5oPXeQSNph6FXulJlXV3Re/v3K3P3Q==", + "dev": true, + "dependencies": { + "@changesets/types": "^5.2.1", + "@manypkg/get-packages": "^1.1.3", + "chalk": "^2.1.0", + "fs-extra": "^7.0.1", + "semver": "^7.5.3" + } + }, + "node_modules/@changesets/get-github-info": { + "version": "0.5.2", + "resolved": "https://registry.npmjs.org/@changesets/get-github-info/-/get-github-info-0.5.2.tgz", + "integrity": "sha512-JppheLu7S114aEs157fOZDjFqUDpm7eHdq5E8SSR0gUBTEK0cNSHsrSR5a66xs0z3RWuo46QvA3vawp8BxDHvg==", + "dev": true, + "dependencies": { + "dataloader": "^1.4.0", + "node-fetch": "^2.5.0" + } + }, + "node_modules/@changesets/get-release-plan": { + "version": "3.0.17", + "resolved": "https://registry.npmjs.org/@changesets/get-release-plan/-/get-release-plan-3.0.17.tgz", + "integrity": "sha512-6IwKTubNEgoOZwDontYc2x2cWXfr6IKxP3IhKeK+WjyD6y3M4Gl/jdQvBw+m/5zWILSOCAaGLu2ZF6Q+WiPniw==", + "dev": true, + "dependencies": { + "@babel/runtime": "^7.20.1", + "@changesets/assemble-release-plan": "^5.2.4", + "@changesets/config": "^2.3.1", + "@changesets/pre": "^1.0.14", + "@changesets/read": "^0.5.9", + "@changesets/types": "^5.2.1", + "@manypkg/get-packages": "^1.1.3" + } + }, + "node_modules/@changesets/get-version-range-type": { + "version": "0.3.2", + "resolved": "https://registry.npmjs.org/@changesets/get-version-range-type/-/get-version-range-type-0.3.2.tgz", + "integrity": "sha512-SVqwYs5pULYjYT4op21F2pVbcrca4qA/bAA3FmFXKMN7Y+HcO8sbZUTx3TAy2VXulP2FACd1aC7f2nTuqSPbqg==", + "dev": true + }, + "node_modules/@changesets/git": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/@changesets/git/-/git-2.0.0.tgz", + "integrity": "sha512-enUVEWbiqUTxqSnmesyJGWfzd51PY4H7mH9yUw0hPVpZBJ6tQZFMU3F3mT/t9OJ/GjyiM4770i+sehAn6ymx6A==", + "dev": true, + "dependencies": { + "@babel/runtime": "^7.20.1", + "@changesets/errors": "^0.1.4", + "@changesets/types": "^5.2.1", + "@manypkg/get-packages": "^1.1.3", + "is-subdir": "^1.1.1", + "micromatch": "^4.0.2", + "spawndamnit": "^2.0.0" + } + }, + "node_modules/@changesets/logger": { + "version": "0.0.5", + "resolved": "https://registry.npmjs.org/@changesets/logger/-/logger-0.0.5.tgz", + "integrity": "sha512-gJyZHomu8nASHpaANzc6bkQMO9gU/ib20lqew1rVx753FOxffnCrJlGIeQVxNWCqM+o6OOleCo/ivL8UAO5iFw==", + "dev": true, + "dependencies": { + "chalk": "^2.1.0" + } + }, + "node_modules/@changesets/parse": { + "version": "0.3.16", + "resolved": "https://registry.npmjs.org/@changesets/parse/-/parse-0.3.16.tgz", + "integrity": "sha512-127JKNd167ayAuBjUggZBkmDS5fIKsthnr9jr6bdnuUljroiERW7FBTDNnNVyJ4l69PzR57pk6mXQdtJyBCJKg==", + "dev": true, + "dependencies": { + "@changesets/types": "^5.2.1", + "js-yaml": "^3.13.1" + } + }, + "node_modules/@changesets/pre": { + "version": "1.0.14", + "resolved": "https://registry.npmjs.org/@changesets/pre/-/pre-1.0.14.tgz", + "integrity": "sha512-dTsHmxQWEQekHYHbg+M1mDVYFvegDh9j/kySNuDKdylwfMEevTeDouR7IfHNyVodxZXu17sXoJuf2D0vi55FHQ==", + "dev": true, + "dependencies": { + "@babel/runtime": "^7.20.1", + "@changesets/errors": "^0.1.4", + "@changesets/types": "^5.2.1", + "@manypkg/get-packages": "^1.1.3", + "fs-extra": "^7.0.1" + } + }, + "node_modules/@changesets/read": { + "version": "0.5.9", + "resolved": "https://registry.npmjs.org/@changesets/read/-/read-0.5.9.tgz", + "integrity": "sha512-T8BJ6JS6j1gfO1HFq50kU3qawYxa4NTbI/ASNVVCBTsKquy2HYwM9r7ZnzkiMe8IEObAJtUVGSrePCOxAK2haQ==", + "dev": true, + "dependencies": { + "@babel/runtime": "^7.20.1", + "@changesets/git": "^2.0.0", + "@changesets/logger": "^0.0.5", + "@changesets/parse": "^0.3.16", + "@changesets/types": "^5.2.1", + "chalk": "^2.1.0", + "fs-extra": "^7.0.1", + "p-filter": "^2.1.0" + } + }, + "node_modules/@changesets/types": { + "version": "5.2.1", + "resolved": "https://registry.npmjs.org/@changesets/types/-/types-5.2.1.tgz", + "integrity": "sha512-myLfHbVOqaq9UtUKqR/nZA/OY7xFjQMdfgfqeZIBK4d0hA6pgxArvdv8M+6NUzzBsjWLOtvApv8YHr4qM+Kpfg==", + "dev": true + }, + "node_modules/@changesets/write": { + "version": "0.2.3", + "resolved": "https://registry.npmjs.org/@changesets/write/-/write-0.2.3.tgz", + "integrity": "sha512-Dbamr7AIMvslKnNYsLFafaVORx4H0pvCA2MHqgtNCySMe1blImEyAEOzDmcgKAkgz4+uwoLz7demIrX+JBr/Xw==", + "dev": true, + "dependencies": { + "@babel/runtime": "^7.20.1", + "@changesets/types": "^5.2.1", + "fs-extra": "^7.0.1", + "human-id": "^1.0.2", + "prettier": "^2.7.1" + } + }, + "node_modules/@changesets/write/node_modules/prettier": { + "version": "2.8.8", + "resolved": "https://registry.npmjs.org/prettier/-/prettier-2.8.8.tgz", + "integrity": "sha512-tdN8qQGvNjw4CHbY+XXk0JgCXn9QiF21a55rBe5LJAU+kDyC4WQn4+awm2Xfk2lQMk5fKup9XgzTZtGkjBdP9Q==", + "dev": true, + "bin": { + "prettier": "bin-prettier.js" + }, + "engines": { + "node": ">=10.13.0" + }, + "funding": { + "url": "https://github.com/prettier/prettier?sponsor=1" + } + }, + "node_modules/@ensdomains/address-encoder": { + "version": "0.1.9", + "resolved": "https://registry.npmjs.org/@ensdomains/address-encoder/-/address-encoder-0.1.9.tgz", + "integrity": "sha512-E2d2gP4uxJQnDu2Kfg1tHNspefzbLT8Tyjrm5sEuim32UkU2sm5xL4VXtgc2X33fmPEw9+jUMpGs4veMbf+PYg==", + "dev": true, + "dependencies": { + "bech32": "^1.1.3", + "blakejs": "^1.1.0", + "bn.js": "^4.11.8", + "bs58": "^4.0.1", + "crypto-addr-codec": "^0.1.7", + "nano-base32": "^1.0.1", + "ripemd160": "^2.0.2" + } + }, + "node_modules/@ensdomains/ens": { + "version": "0.4.5", + "resolved": "https://registry.npmjs.org/@ensdomains/ens/-/ens-0.4.5.tgz", + "integrity": "sha512-JSvpj1iNMFjK6K+uVl4unqMoa9rf5jopb8cya5UGBWz23Nw8hSNT7efgUx4BTlAPAgpNlEioUfeTyQ6J9ZvTVw==", + "deprecated": "Please use @ensdomains/ens-contracts", + "dev": true, + "dependencies": { + "bluebird": "^3.5.2", + "eth-ens-namehash": "^2.0.8", + "solc": "^0.4.20", + "testrpc": "0.0.1", + "web3-utils": "^1.0.0-beta.31" + } + }, + "node_modules/@ensdomains/ensjs": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/@ensdomains/ensjs/-/ensjs-2.1.0.tgz", + "integrity": "sha512-GRbGPT8Z/OJMDuxs75U/jUNEC0tbL0aj7/L/QQznGYKm/tiasp+ndLOaoULy9kKJFC0TBByqfFliEHDgoLhyog==", + "dev": true, + "dependencies": { + "@babel/runtime": "^7.4.4", + "@ensdomains/address-encoder": "^0.1.7", + "@ensdomains/ens": "0.4.5", + "@ensdomains/resolver": "0.2.4", + "content-hash": "^2.5.2", + "eth-ens-namehash": "^2.0.8", + "ethers": "^5.0.13", + "js-sha3": "^0.8.0" + } + }, + "node_modules/@ensdomains/ensjs/node_modules/ethers": { + "version": "5.7.2", + "resolved": "https://registry.npmjs.org/ethers/-/ethers-5.7.2.tgz", + "integrity": "sha512-wswUsmWo1aOK8rR7DIKiWSw9DbLWe6x98Jrn8wcTflTVvaXhAMaB5zGAXy0GYQEQp9iO1iSHWVyARQm11zUtyg==", + "dev": true, + "funding": [ + { + "type": "individual", + "url": "https://gitcoin.co/grants/13/ethersjs-complete-simple-and-tiny-2" + }, + { + "type": "individual", + "url": "https://www.buymeacoffee.com/ricmoo" + } + ], + "dependencies": { + "@ethersproject/abi": "5.7.0", + "@ethersproject/abstract-provider": "5.7.0", + "@ethersproject/abstract-signer": "5.7.0", + "@ethersproject/address": "5.7.0", + "@ethersproject/base64": "5.7.0", + "@ethersproject/basex": "5.7.0", + "@ethersproject/bignumber": "5.7.0", + "@ethersproject/bytes": "5.7.0", + "@ethersproject/constants": "5.7.0", + "@ethersproject/contracts": "5.7.0", + "@ethersproject/hash": "5.7.0", + "@ethersproject/hdnode": "5.7.0", + "@ethersproject/json-wallets": "5.7.0", + "@ethersproject/keccak256": "5.7.0", + "@ethersproject/logger": "5.7.0", + "@ethersproject/networks": "5.7.1", + "@ethersproject/pbkdf2": "5.7.0", + "@ethersproject/properties": "5.7.0", + "@ethersproject/providers": "5.7.2", + "@ethersproject/random": "5.7.0", + "@ethersproject/rlp": "5.7.0", + "@ethersproject/sha2": "5.7.0", + "@ethersproject/signing-key": "5.7.0", + "@ethersproject/solidity": "5.7.0", + "@ethersproject/strings": "5.7.0", + "@ethersproject/transactions": "5.7.0", + "@ethersproject/units": "5.7.0", + "@ethersproject/wallet": "5.7.0", + "@ethersproject/web": "5.7.1", + "@ethersproject/wordlists": "5.7.0" + } + }, + "node_modules/@ensdomains/resolver": { + "version": "0.2.4", + "resolved": "https://registry.npmjs.org/@ensdomains/resolver/-/resolver-0.2.4.tgz", + "integrity": "sha512-bvaTH34PMCbv6anRa9I/0zjLJgY4EuznbEMgbV77JBCQ9KNC46rzi0avuxpOfu+xDjPEtSFGqVEOr5GlUSGudA==", + "deprecated": "Please use @ensdomains/ens-contracts", + "dev": true + }, + "node_modules/@eslint-community/eslint-utils": { + "version": "4.4.0", + "resolved": "https://registry.npmjs.org/@eslint-community/eslint-utils/-/eslint-utils-4.4.0.tgz", + "integrity": "sha512-1/sA4dwrzBAyeUoQ6oxahHKmrZvsnLCg4RfxW3ZFGGmQkSNQPFNLV9CUEFQP1x9EYXHTo5p6xdhZM1Ne9p/AfA==", + "dev": true, + "dependencies": { + "eslint-visitor-keys": "^3.3.0" + }, + "engines": { + "node": "^12.22.0 || ^14.17.0 || >=16.0.0" + }, + "peerDependencies": { + "eslint": "^6.0.0 || ^7.0.0 || >=8.0.0" + } + }, + "node_modules/@eslint-community/regexpp": { + "version": "4.5.1", + "resolved": "https://registry.npmjs.org/@eslint-community/regexpp/-/regexpp-4.5.1.tgz", + "integrity": "sha512-Z5ba73P98O1KUYCCJTUeVpja9RcGoMdncZ6T49FCUl2lN38JtCJ+3WgIDBv0AuY4WChU5PmtJmOCTlN6FZTFKQ==", + "dev": true, + "engines": { + "node": "^12.0.0 || ^14.0.0 || >=16.0.0" + } + }, + "node_modules/@eslint/eslintrc": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/@eslint/eslintrc/-/eslintrc-2.1.0.tgz", + "integrity": "sha512-Lj7DECXqIVCqnqjjHMPna4vn6GJcMgul/wuS0je9OZ9gsL0zzDpKPVtcG1HaDVc+9y+qgXneTeUMbCqXJNpH1A==", + "dev": true, + "dependencies": { + "ajv": "^6.12.4", + "debug": "^4.3.2", + "espree": "^9.6.0", + "globals": "^13.19.0", + "ignore": "^5.2.0", + "import-fresh": "^3.2.1", + "js-yaml": "^4.1.0", + "minimatch": "^3.1.2", + "strip-json-comments": "^3.1.1" + }, + "engines": { + "node": "^12.22.0 || ^14.17.0 || >=16.0.0" + }, + "funding": { + "url": "https://opencollective.com/eslint" + } + }, + "node_modules/@eslint/eslintrc/node_modules/argparse": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/argparse/-/argparse-2.0.1.tgz", + "integrity": "sha512-8+9WqebbFzpX9OR+Wa6O29asIogeRMzcGtAINdpMHHyAg10f05aSFVBbcEqGf/PXw1EjAZ+q2/bEBg3DvurK3Q==", + "dev": true + }, + "node_modules/@eslint/eslintrc/node_modules/js-yaml": { + "version": "4.1.0", + "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-4.1.0.tgz", + "integrity": "sha512-wpxZs9NoxZaJESJGIZTyDEaYpl0FKSA+FB9aJiyemKhMwkxQg63h4T1KJgUGHpTqPDNRcmmYLugrRjJlBtWvRA==", + "dev": true, + "dependencies": { + "argparse": "^2.0.1" + }, + "bin": { + "js-yaml": "bin/js-yaml.js" + } + }, + "node_modules/@eslint/js": { + "version": "8.44.0", + "resolved": "https://registry.npmjs.org/@eslint/js/-/js-8.44.0.tgz", + "integrity": "sha512-Ag+9YM4ocKQx9AarydN0KY2j0ErMHNIocPDrVo8zAE44xLTjEtz81OdR68/cydGtk6m6jDb5Za3r2useMzYmSw==", + "dev": true, + "engines": { + "node": "^12.22.0 || ^14.17.0 || >=16.0.0" + } + }, + "node_modules/@ethereumjs/common": { + "version": "2.5.0", + "resolved": "https://registry.npmjs.org/@ethereumjs/common/-/common-2.5.0.tgz", + "integrity": "sha512-DEHjW6e38o+JmB/NO3GZBpW4lpaiBpkFgXF6jLcJ6gETBYpEyaA5nTimsWBUJR3Vmtm/didUEbNjajskugZORg==", + "dev": true, + "dependencies": { + "crc-32": "^1.2.0", + "ethereumjs-util": "^7.1.1" + } + }, + "node_modules/@ethereumjs/tx": { + "version": "3.3.2", + "resolved": "https://registry.npmjs.org/@ethereumjs/tx/-/tx-3.3.2.tgz", + "integrity": "sha512-6AaJhwg4ucmwTvw/1qLaZUX5miWrwZ4nLOUsKyb/HtzS3BMw/CasKhdi1ims9mBKeK9sOJCH4qGKOBGyJCeeog==", + "dev": true, + "dependencies": { + "@ethereumjs/common": "^2.5.0", + "ethereumjs-util": "^7.1.2" + } + }, + "node_modules/@ethersproject/abi": { + "version": "5.7.0", + "resolved": "https://registry.npmjs.org/@ethersproject/abi/-/abi-5.7.0.tgz", + "integrity": "sha512-351ktp42TiRcYB3H1OP8yajPeAQstMW/yCFokj/AthP9bLHzQFPlOrxOcwYEDkUAICmOHljvN4K39OMTMUa9RA==", + "dev": true, + "funding": [ + { + "type": "individual", + "url": "https://gitcoin.co/grants/13/ethersjs-complete-simple-and-tiny-2" + }, + { + "type": "individual", + "url": "https://www.buymeacoffee.com/ricmoo" + } + ], + "dependencies": { + "@ethersproject/address": "^5.7.0", + "@ethersproject/bignumber": "^5.7.0", + "@ethersproject/bytes": "^5.7.0", + "@ethersproject/constants": "^5.7.0", + "@ethersproject/hash": "^5.7.0", + "@ethersproject/keccak256": "^5.7.0", + "@ethersproject/logger": "^5.7.0", + "@ethersproject/properties": "^5.7.0", + "@ethersproject/strings": "^5.7.0" + } + }, + "node_modules/@ethersproject/abstract-provider": { + "version": "5.7.0", + "resolved": "https://registry.npmjs.org/@ethersproject/abstract-provider/-/abstract-provider-5.7.0.tgz", + "integrity": "sha512-R41c9UkchKCpAqStMYUpdunjo3pkEvZC3FAwZn5S5MGbXoMQOHIdHItezTETxAO5bevtMApSyEhn9+CHcDsWBw==", + "dev": true, + "funding": [ + { + "type": "individual", + "url": "https://gitcoin.co/grants/13/ethersjs-complete-simple-and-tiny-2" + }, + { + "type": "individual", + "url": "https://www.buymeacoffee.com/ricmoo" + } + ], + "dependencies": { + "@ethersproject/bignumber": "^5.7.0", + "@ethersproject/bytes": "^5.7.0", + "@ethersproject/logger": "^5.7.0", + "@ethersproject/networks": "^5.7.0", + "@ethersproject/properties": "^5.7.0", + "@ethersproject/transactions": "^5.7.0", + "@ethersproject/web": "^5.7.0" + } + }, + "node_modules/@ethersproject/abstract-signer": { + "version": "5.7.0", + "resolved": "https://registry.npmjs.org/@ethersproject/abstract-signer/-/abstract-signer-5.7.0.tgz", + "integrity": "sha512-a16V8bq1/Cz+TGCkE2OPMTOUDLS3grCpdjoJCYNnVBbdYEMSgKrU0+B90s8b6H+ByYTBZN7a3g76jdIJi7UfKQ==", + "dev": true, + "funding": [ + { + "type": "individual", + "url": "https://gitcoin.co/grants/13/ethersjs-complete-simple-and-tiny-2" + }, + { + "type": "individual", + "url": "https://www.buymeacoffee.com/ricmoo" + } + ], + "dependencies": { + "@ethersproject/abstract-provider": "^5.7.0", + "@ethersproject/bignumber": "^5.7.0", + "@ethersproject/bytes": "^5.7.0", + "@ethersproject/logger": "^5.7.0", + "@ethersproject/properties": "^5.7.0" + } + }, + "node_modules/@ethersproject/address": { + "version": "5.7.0", + "resolved": "https://registry.npmjs.org/@ethersproject/address/-/address-5.7.0.tgz", + "integrity": "sha512-9wYhYt7aghVGo758POM5nqcOMaE168Q6aRLJZwUmiqSrAungkG74gSSeKEIR7ukixesdRZGPgVqme6vmxs1fkA==", + "dev": true, + "funding": [ + { + "type": "individual", + "url": "https://gitcoin.co/grants/13/ethersjs-complete-simple-and-tiny-2" + }, + { + "type": "individual", + "url": "https://www.buymeacoffee.com/ricmoo" + } + ], + "dependencies": { + "@ethersproject/bignumber": "^5.7.0", + "@ethersproject/bytes": "^5.7.0", + "@ethersproject/keccak256": "^5.7.0", + "@ethersproject/logger": "^5.7.0", + "@ethersproject/rlp": "^5.7.0" + } + }, + "node_modules/@ethersproject/base64": { + "version": "5.7.0", + "resolved": "https://registry.npmjs.org/@ethersproject/base64/-/base64-5.7.0.tgz", + "integrity": "sha512-Dr8tcHt2mEbsZr/mwTPIQAf3Ai0Bks/7gTw9dSqk1mQvhW3XvRlmDJr/4n+wg1JmCl16NZue17CDh8xb/vZ0sQ==", + "dev": true, + "funding": [ + { + "type": "individual", + "url": "https://gitcoin.co/grants/13/ethersjs-complete-simple-and-tiny-2" + }, + { + "type": "individual", + "url": "https://www.buymeacoffee.com/ricmoo" + } + ], + "dependencies": { + "@ethersproject/bytes": "^5.7.0" + } + }, + "node_modules/@ethersproject/basex": { + "version": "5.7.0", + "resolved": "https://registry.npmjs.org/@ethersproject/basex/-/basex-5.7.0.tgz", + "integrity": "sha512-ywlh43GwZLv2Voc2gQVTKBoVQ1mti3d8HK5aMxsfu/nRDnMmNqaSJ3r3n85HBByT8OpoY96SXM1FogC533T4zw==", + "dev": true, + "funding": [ + { + "type": "individual", + "url": "https://gitcoin.co/grants/13/ethersjs-complete-simple-and-tiny-2" + }, + { + "type": "individual", + "url": "https://www.buymeacoffee.com/ricmoo" + } + ], + "dependencies": { + "@ethersproject/bytes": "^5.7.0", + "@ethersproject/properties": "^5.7.0" + } + }, + "node_modules/@ethersproject/bignumber": { + "version": "5.7.0", + "resolved": "https://registry.npmjs.org/@ethersproject/bignumber/-/bignumber-5.7.0.tgz", + "integrity": "sha512-n1CAdIHRWjSucQO3MC1zPSVgV/6dy/fjL9pMrPP9peL+QxEg9wOsVqwD4+818B6LUEtaXzVHQiuivzRoxPxUGw==", + "dev": true, + "funding": [ + { + "type": "individual", + "url": "https://gitcoin.co/grants/13/ethersjs-complete-simple-and-tiny-2" + }, + { + "type": "individual", + "url": "https://www.buymeacoffee.com/ricmoo" + } + ], + "dependencies": { + "@ethersproject/bytes": "^5.7.0", + "@ethersproject/logger": "^5.7.0", + "bn.js": "^5.2.1" + } + }, + "node_modules/@ethersproject/bignumber/node_modules/bn.js": { + "version": "5.2.1", + "resolved": "https://registry.npmjs.org/bn.js/-/bn.js-5.2.1.tgz", + "integrity": "sha512-eXRvHzWyYPBuB4NBy0cmYQjGitUrtqwbvlzP3G6VFnNRbsZQIxQ10PbKKHt8gZ/HW/D/747aDl+QkDqg3KQLMQ==", + "dev": true + }, + "node_modules/@ethersproject/bytes": { + "version": "5.7.0", + "resolved": "https://registry.npmjs.org/@ethersproject/bytes/-/bytes-5.7.0.tgz", + "integrity": "sha512-nsbxwgFXWh9NyYWo+U8atvmMsSdKJprTcICAkvbBffT75qDocbuggBU0SJiVK2MuTrp0q+xvLkTnGMPK1+uA9A==", + "dev": true, + "funding": [ + { + "type": "individual", + "url": "https://gitcoin.co/grants/13/ethersjs-complete-simple-and-tiny-2" + }, + { + "type": "individual", + "url": "https://www.buymeacoffee.com/ricmoo" + } + ], + "dependencies": { + "@ethersproject/logger": "^5.7.0" + } + }, + "node_modules/@ethersproject/constants": { + "version": "5.7.0", + "resolved": "https://registry.npmjs.org/@ethersproject/constants/-/constants-5.7.0.tgz", + "integrity": "sha512-DHI+y5dBNvkpYUMiRQyxRBYBefZkJfo70VUkUAsRjcPs47muV9evftfZ0PJVCXYbAiCgght0DtcF9srFQmIgWA==", + "dev": true, + "funding": [ + { + "type": "individual", + "url": "https://gitcoin.co/grants/13/ethersjs-complete-simple-and-tiny-2" + }, + { + "type": "individual", + "url": "https://www.buymeacoffee.com/ricmoo" + } + ], + "dependencies": { + "@ethersproject/bignumber": "^5.7.0" + } + }, + "node_modules/@ethersproject/contracts": { + "version": "5.7.0", + "resolved": "https://registry.npmjs.org/@ethersproject/contracts/-/contracts-5.7.0.tgz", + "integrity": "sha512-5GJbzEU3X+d33CdfPhcyS+z8MzsTrBGk/sc+G+59+tPa9yFkl6HQ9D6L0QMgNTA9q8dT0XKxxkyp883XsQvbbg==", + "dev": true, + "funding": [ + { + "type": "individual", + "url": "https://gitcoin.co/grants/13/ethersjs-complete-simple-and-tiny-2" + }, + { + "type": "individual", + "url": "https://www.buymeacoffee.com/ricmoo" + } + ], + "dependencies": { + "@ethersproject/abi": "^5.7.0", + "@ethersproject/abstract-provider": "^5.7.0", + "@ethersproject/abstract-signer": "^5.7.0", + "@ethersproject/address": "^5.7.0", + "@ethersproject/bignumber": "^5.7.0", + "@ethersproject/bytes": "^5.7.0", + "@ethersproject/constants": "^5.7.0", + "@ethersproject/logger": "^5.7.0", + "@ethersproject/properties": "^5.7.0", + "@ethersproject/transactions": "^5.7.0" + } + }, + "node_modules/@ethersproject/hash": { + "version": "5.7.0", + "resolved": "https://registry.npmjs.org/@ethersproject/hash/-/hash-5.7.0.tgz", + "integrity": "sha512-qX5WrQfnah1EFnO5zJv1v46a8HW0+E5xuBBDTwMFZLuVTx0tbU2kkx15NqdjxecrLGatQN9FGQKpb1FKdHCt+g==", + "dev": true, + "funding": [ + { + "type": "individual", + "url": "https://gitcoin.co/grants/13/ethersjs-complete-simple-and-tiny-2" + }, + { + "type": "individual", + "url": "https://www.buymeacoffee.com/ricmoo" + } + ], + "dependencies": { + "@ethersproject/abstract-signer": "^5.7.0", + "@ethersproject/address": "^5.7.0", + "@ethersproject/base64": "^5.7.0", + "@ethersproject/bignumber": "^5.7.0", + "@ethersproject/bytes": "^5.7.0", + "@ethersproject/keccak256": "^5.7.0", + "@ethersproject/logger": "^5.7.0", + "@ethersproject/properties": "^5.7.0", + "@ethersproject/strings": "^5.7.0" + } + }, + "node_modules/@ethersproject/hdnode": { + "version": "5.7.0", + "resolved": "https://registry.npmjs.org/@ethersproject/hdnode/-/hdnode-5.7.0.tgz", + "integrity": "sha512-OmyYo9EENBPPf4ERhR7oj6uAtUAhYGqOnIS+jE5pTXvdKBS99ikzq1E7Iv0ZQZ5V36Lqx1qZLeak0Ra16qpeOg==", + "dev": true, + "funding": [ + { + "type": "individual", + "url": "https://gitcoin.co/grants/13/ethersjs-complete-simple-and-tiny-2" + }, + { + "type": "individual", + "url": "https://www.buymeacoffee.com/ricmoo" + } + ], + "dependencies": { + "@ethersproject/abstract-signer": "^5.7.0", + "@ethersproject/basex": "^5.7.0", + "@ethersproject/bignumber": "^5.7.0", + "@ethersproject/bytes": "^5.7.0", + "@ethersproject/logger": "^5.7.0", + "@ethersproject/pbkdf2": "^5.7.0", + "@ethersproject/properties": "^5.7.0", + "@ethersproject/sha2": "^5.7.0", + "@ethersproject/signing-key": "^5.7.0", + "@ethersproject/strings": "^5.7.0", + "@ethersproject/transactions": "^5.7.0", + "@ethersproject/wordlists": "^5.7.0" + } + }, + "node_modules/@ethersproject/json-wallets": { + "version": "5.7.0", + "resolved": "https://registry.npmjs.org/@ethersproject/json-wallets/-/json-wallets-5.7.0.tgz", + "integrity": "sha512-8oee5Xgu6+RKgJTkvEMl2wDgSPSAQ9MB/3JYjFV9jlKvcYHUXZC+cQp0njgmxdHkYWn8s6/IqIZYm0YWCjO/0g==", + "dev": true, + "funding": [ + { + "type": "individual", + "url": "https://gitcoin.co/grants/13/ethersjs-complete-simple-and-tiny-2" + }, + { + "type": "individual", + "url": "https://www.buymeacoffee.com/ricmoo" + } + ], + "dependencies": { + "@ethersproject/abstract-signer": "^5.7.0", + "@ethersproject/address": "^5.7.0", + "@ethersproject/bytes": "^5.7.0", + "@ethersproject/hdnode": "^5.7.0", + "@ethersproject/keccak256": "^5.7.0", + "@ethersproject/logger": "^5.7.0", + "@ethersproject/pbkdf2": "^5.7.0", + "@ethersproject/properties": "^5.7.0", + "@ethersproject/random": "^5.7.0", + "@ethersproject/strings": "^5.7.0", + "@ethersproject/transactions": "^5.7.0", + "aes-js": "3.0.0", + "scrypt-js": "3.0.1" + } + }, + "node_modules/@ethersproject/json-wallets/node_modules/aes-js": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/aes-js/-/aes-js-3.0.0.tgz", + "integrity": "sha512-H7wUZRn8WpTq9jocdxQ2c8x2sKo9ZVmzfRE13GiNJXfp7NcKYEdvl3vspKjXox6RIG2VtaRe4JFvxG4rqp2Zuw==", + "dev": true + }, + "node_modules/@ethersproject/keccak256": { + "version": "5.7.0", + "resolved": "https://registry.npmjs.org/@ethersproject/keccak256/-/keccak256-5.7.0.tgz", + "integrity": "sha512-2UcPboeL/iW+pSg6vZ6ydF8tCnv3Iu/8tUmLLzWWGzxWKFFqOBQFLo6uLUv6BDrLgCDfN28RJ/wtByx+jZ4KBg==", + "dev": true, + "funding": [ + { + "type": "individual", + "url": "https://gitcoin.co/grants/13/ethersjs-complete-simple-and-tiny-2" + }, + { + "type": "individual", + "url": "https://www.buymeacoffee.com/ricmoo" + } + ], + "dependencies": { + "@ethersproject/bytes": "^5.7.0", + "js-sha3": "0.8.0" + } + }, + "node_modules/@ethersproject/logger": { + "version": "5.7.0", + "resolved": "https://registry.npmjs.org/@ethersproject/logger/-/logger-5.7.0.tgz", + "integrity": "sha512-0odtFdXu/XHtjQXJYA3u9G0G8btm0ND5Cu8M7i5vhEcE8/HmF4Lbdqanwyv4uQTr2tx6b7fQRmgLrsnpQlmnig==", + "dev": true, + "funding": [ + { + "type": "individual", + "url": "https://gitcoin.co/grants/13/ethersjs-complete-simple-and-tiny-2" + }, + { + "type": "individual", + "url": "https://www.buymeacoffee.com/ricmoo" + } + ] + }, + "node_modules/@ethersproject/networks": { + "version": "5.7.1", + "resolved": "https://registry.npmjs.org/@ethersproject/networks/-/networks-5.7.1.tgz", + "integrity": "sha512-n/MufjFYv3yFcUyfhnXotyDlNdFb7onmkSy8aQERi2PjNcnWQ66xXxa3XlS8nCcA8aJKJjIIMNJTC7tu80GwpQ==", + "dev": true, + "funding": [ + { + "type": "individual", + "url": "https://gitcoin.co/grants/13/ethersjs-complete-simple-and-tiny-2" + }, + { + "type": "individual", + "url": "https://www.buymeacoffee.com/ricmoo" + } + ], + "dependencies": { + "@ethersproject/logger": "^5.7.0" + } + }, + "node_modules/@ethersproject/pbkdf2": { + "version": "5.7.0", + "resolved": "https://registry.npmjs.org/@ethersproject/pbkdf2/-/pbkdf2-5.7.0.tgz", + "integrity": "sha512-oR/dBRZR6GTyaofd86DehG72hY6NpAjhabkhxgr3X2FpJtJuodEl2auADWBZfhDHgVCbu3/H/Ocq2uC6dpNjjw==", + "dev": true, + "funding": [ + { + "type": "individual", + "url": "https://gitcoin.co/grants/13/ethersjs-complete-simple-and-tiny-2" + }, + { + "type": "individual", + "url": "https://www.buymeacoffee.com/ricmoo" + } + ], + "dependencies": { + "@ethersproject/bytes": "^5.7.0", + "@ethersproject/sha2": "^5.7.0" + } + }, + "node_modules/@ethersproject/properties": { + "version": "5.7.0", + "resolved": "https://registry.npmjs.org/@ethersproject/properties/-/properties-5.7.0.tgz", + "integrity": "sha512-J87jy8suntrAkIZtecpxEPxY//szqr1mlBaYlQ0r4RCaiD2hjheqF9s1LVE8vVuJCXisjIP+JgtK/Do54ej4Sw==", + "dev": true, + "funding": [ + { + "type": "individual", + "url": "https://gitcoin.co/grants/13/ethersjs-complete-simple-and-tiny-2" + }, + { + "type": "individual", + "url": "https://www.buymeacoffee.com/ricmoo" + } + ], + "dependencies": { + "@ethersproject/logger": "^5.7.0" + } + }, + "node_modules/@ethersproject/providers": { + "version": "5.7.2", + "resolved": "https://registry.npmjs.org/@ethersproject/providers/-/providers-5.7.2.tgz", + "integrity": "sha512-g34EWZ1WWAVgr4aptGlVBF8mhl3VWjv+8hoAnzStu8Ah22VHBsuGzP17eb6xDVRzw895G4W7vvx60lFFur/1Rg==", + "dev": true, + "funding": [ + { + "type": "individual", + "url": "https://gitcoin.co/grants/13/ethersjs-complete-simple-and-tiny-2" + }, + { + "type": "individual", + "url": "https://www.buymeacoffee.com/ricmoo" + } + ], + "dependencies": { + "@ethersproject/abstract-provider": "^5.7.0", + "@ethersproject/abstract-signer": "^5.7.0", + "@ethersproject/address": "^5.7.0", + "@ethersproject/base64": "^5.7.0", + "@ethersproject/basex": "^5.7.0", + "@ethersproject/bignumber": "^5.7.0", + "@ethersproject/bytes": "^5.7.0", + "@ethersproject/constants": "^5.7.0", + "@ethersproject/hash": "^5.7.0", + "@ethersproject/logger": "^5.7.0", + "@ethersproject/networks": "^5.7.0", + "@ethersproject/properties": "^5.7.0", + "@ethersproject/random": "^5.7.0", + "@ethersproject/rlp": "^5.7.0", + "@ethersproject/sha2": "^5.7.0", + "@ethersproject/strings": "^5.7.0", + "@ethersproject/transactions": "^5.7.0", + "@ethersproject/web": "^5.7.0", + "bech32": "1.1.4", + "ws": "7.4.6" + } + }, + "node_modules/@ethersproject/providers/node_modules/ws": { + "version": "7.4.6", + "resolved": "https://registry.npmjs.org/ws/-/ws-7.4.6.tgz", + "integrity": "sha512-YmhHDO4MzaDLB+M9ym/mDA5z0naX8j7SIlT8f8z+I0VtzsRbekxEutHSme7NPS2qE8StCYQNUnfWdXta/Yu85A==", + "dev": true, + "engines": { + "node": ">=8.3.0" + }, + "peerDependencies": { + "bufferutil": "^4.0.1", + "utf-8-validate": "^5.0.2" + }, + "peerDependenciesMeta": { + "bufferutil": { + "optional": true + }, + "utf-8-validate": { + "optional": true + } + } + }, + "node_modules/@ethersproject/random": { + "version": "5.7.0", + "resolved": "https://registry.npmjs.org/@ethersproject/random/-/random-5.7.0.tgz", + "integrity": "sha512-19WjScqRA8IIeWclFme75VMXSBvi4e6InrUNuaR4s5pTF2qNhcGdCUwdxUVGtDDqC00sDLCO93jPQoDUH4HVmQ==", + "dev": true, + "funding": [ + { + "type": "individual", + "url": "https://gitcoin.co/grants/13/ethersjs-complete-simple-and-tiny-2" + }, + { + "type": "individual", + "url": "https://www.buymeacoffee.com/ricmoo" + } + ], + "dependencies": { + "@ethersproject/bytes": "^5.7.0", + "@ethersproject/logger": "^5.7.0" + } + }, + "node_modules/@ethersproject/rlp": { + "version": "5.7.0", + "resolved": "https://registry.npmjs.org/@ethersproject/rlp/-/rlp-5.7.0.tgz", + "integrity": "sha512-rBxzX2vK8mVF7b0Tol44t5Tb8gomOHkj5guL+HhzQ1yBh/ydjGnpw6at+X6Iw0Kp3OzzzkcKp8N9r0W4kYSs9w==", + "dev": true, + "funding": [ + { + "type": "individual", + "url": "https://gitcoin.co/grants/13/ethersjs-complete-simple-and-tiny-2" + }, + { + "type": "individual", + "url": "https://www.buymeacoffee.com/ricmoo" + } + ], + "dependencies": { + "@ethersproject/bytes": "^5.7.0", + "@ethersproject/logger": "^5.7.0" + } + }, + "node_modules/@ethersproject/sha2": { + "version": "5.7.0", + "resolved": "https://registry.npmjs.org/@ethersproject/sha2/-/sha2-5.7.0.tgz", + "integrity": "sha512-gKlH42riwb3KYp0reLsFTokByAKoJdgFCwI+CCiX/k+Jm2mbNs6oOaCjYQSlI1+XBVejwH2KrmCbMAT/GnRDQw==", + "dev": true, + "funding": [ + { + "type": "individual", + "url": "https://gitcoin.co/grants/13/ethersjs-complete-simple-and-tiny-2" + }, + { + "type": "individual", + "url": "https://www.buymeacoffee.com/ricmoo" + } + ], + "dependencies": { + "@ethersproject/bytes": "^5.7.0", + "@ethersproject/logger": "^5.7.0", + "hash.js": "1.1.7" + } + }, + "node_modules/@ethersproject/signing-key": { + "version": "5.7.0", + "resolved": "https://registry.npmjs.org/@ethersproject/signing-key/-/signing-key-5.7.0.tgz", + "integrity": "sha512-MZdy2nL3wO0u7gkB4nA/pEf8lu1TlFswPNmy8AiYkfKTdO6eXBJyUdmHO/ehm/htHw9K/qF8ujnTyUAD+Ry54Q==", + "dev": true, + "funding": [ + { + "type": "individual", + "url": "https://gitcoin.co/grants/13/ethersjs-complete-simple-and-tiny-2" + }, + { + "type": "individual", + "url": "https://www.buymeacoffee.com/ricmoo" + } + ], + "dependencies": { + "@ethersproject/bytes": "^5.7.0", + "@ethersproject/logger": "^5.7.0", + "@ethersproject/properties": "^5.7.0", + "bn.js": "^5.2.1", + "elliptic": "6.5.4", + "hash.js": "1.1.7" + } + }, + "node_modules/@ethersproject/signing-key/node_modules/bn.js": { + "version": "5.2.1", + "resolved": "https://registry.npmjs.org/bn.js/-/bn.js-5.2.1.tgz", + "integrity": "sha512-eXRvHzWyYPBuB4NBy0cmYQjGitUrtqwbvlzP3G6VFnNRbsZQIxQ10PbKKHt8gZ/HW/D/747aDl+QkDqg3KQLMQ==", + "dev": true + }, + "node_modules/@ethersproject/solidity": { + "version": "5.7.0", + "resolved": "https://registry.npmjs.org/@ethersproject/solidity/-/solidity-5.7.0.tgz", + "integrity": "sha512-HmabMd2Dt/raavyaGukF4XxizWKhKQ24DoLtdNbBmNKUOPqwjsKQSdV9GQtj9CBEea9DlzETlVER1gYeXXBGaA==", + "dev": true, + "funding": [ + { + "type": "individual", + "url": "https://gitcoin.co/grants/13/ethersjs-complete-simple-and-tiny-2" + }, + { + "type": "individual", + "url": "https://www.buymeacoffee.com/ricmoo" + } + ], + "dependencies": { + "@ethersproject/bignumber": "^5.7.0", + "@ethersproject/bytes": "^5.7.0", + "@ethersproject/keccak256": "^5.7.0", + "@ethersproject/logger": "^5.7.0", + "@ethersproject/sha2": "^5.7.0", + "@ethersproject/strings": "^5.7.0" + } + }, + "node_modules/@ethersproject/strings": { + "version": "5.7.0", + "resolved": "https://registry.npmjs.org/@ethersproject/strings/-/strings-5.7.0.tgz", + "integrity": "sha512-/9nu+lj0YswRNSH0NXYqrh8775XNyEdUQAuf3f+SmOrnVewcJ5SBNAjF7lpgehKi4abvNNXyf+HX86czCdJ8Mg==", + "dev": true, + "funding": [ + { + "type": "individual", + "url": "https://gitcoin.co/grants/13/ethersjs-complete-simple-and-tiny-2" + }, + { + "type": "individual", + "url": "https://www.buymeacoffee.com/ricmoo" + } + ], + "dependencies": { + "@ethersproject/bytes": "^5.7.0", + "@ethersproject/constants": "^5.7.0", + "@ethersproject/logger": "^5.7.0" + } + }, + "node_modules/@ethersproject/transactions": { + "version": "5.7.0", + "resolved": "https://registry.npmjs.org/@ethersproject/transactions/-/transactions-5.7.0.tgz", + "integrity": "sha512-kmcNicCp1lp8qanMTC3RIikGgoJ80ztTyvtsFvCYpSCfkjhD0jZ2LOrnbcuxuToLIUYYf+4XwD1rP+B/erDIhQ==", + "dev": true, + "funding": [ + { + "type": "individual", + "url": "https://gitcoin.co/grants/13/ethersjs-complete-simple-and-tiny-2" + }, + { + "type": "individual", + "url": "https://www.buymeacoffee.com/ricmoo" + } + ], + "dependencies": { + "@ethersproject/address": "^5.7.0", + "@ethersproject/bignumber": "^5.7.0", + "@ethersproject/bytes": "^5.7.0", + "@ethersproject/constants": "^5.7.0", + "@ethersproject/keccak256": "^5.7.0", + "@ethersproject/logger": "^5.7.0", + "@ethersproject/properties": "^5.7.0", + "@ethersproject/rlp": "^5.7.0", + "@ethersproject/signing-key": "^5.7.0" + } + }, + "node_modules/@ethersproject/units": { + "version": "5.7.0", + "resolved": "https://registry.npmjs.org/@ethersproject/units/-/units-5.7.0.tgz", + "integrity": "sha512-pD3xLMy3SJu9kG5xDGI7+xhTEmGXlEqXU4OfNapmfnxLVY4EMSSRp7j1k7eezutBPH7RBN/7QPnwR7hzNlEFeg==", + "dev": true, + "funding": [ + { + "type": "individual", + "url": "https://gitcoin.co/grants/13/ethersjs-complete-simple-and-tiny-2" + }, + { + "type": "individual", + "url": "https://www.buymeacoffee.com/ricmoo" + } + ], + "dependencies": { + "@ethersproject/bignumber": "^5.7.0", + "@ethersproject/constants": "^5.7.0", + "@ethersproject/logger": "^5.7.0" + } + }, + "node_modules/@ethersproject/wallet": { + "version": "5.7.0", + "resolved": "https://registry.npmjs.org/@ethersproject/wallet/-/wallet-5.7.0.tgz", + "integrity": "sha512-MhmXlJXEJFBFVKrDLB4ZdDzxcBxQ3rLyCkhNqVu3CDYvR97E+8r01UgrI+TI99Le+aYm/in/0vp86guJuM7FCA==", + "dev": true, + "funding": [ + { + "type": "individual", + "url": "https://gitcoin.co/grants/13/ethersjs-complete-simple-and-tiny-2" + }, + { + "type": "individual", + "url": "https://www.buymeacoffee.com/ricmoo" + } + ], + "dependencies": { + "@ethersproject/abstract-provider": "^5.7.0", + "@ethersproject/abstract-signer": "^5.7.0", + "@ethersproject/address": "^5.7.0", + "@ethersproject/bignumber": "^5.7.0", + "@ethersproject/bytes": "^5.7.0", + "@ethersproject/hash": "^5.7.0", + "@ethersproject/hdnode": "^5.7.0", + "@ethersproject/json-wallets": "^5.7.0", + "@ethersproject/keccak256": "^5.7.0", + "@ethersproject/logger": "^5.7.0", + "@ethersproject/properties": "^5.7.0", + "@ethersproject/random": "^5.7.0", + "@ethersproject/signing-key": "^5.7.0", + "@ethersproject/transactions": "^5.7.0", + "@ethersproject/wordlists": "^5.7.0" + } + }, + "node_modules/@ethersproject/web": { + "version": "5.7.1", + "resolved": "https://registry.npmjs.org/@ethersproject/web/-/web-5.7.1.tgz", + "integrity": "sha512-Gueu8lSvyjBWL4cYsWsjh6MtMwM0+H4HvqFPZfB6dV8ctbP9zFAO73VG1cMWae0FLPCtz0peKPpZY8/ugJJX2w==", + "dev": true, + "funding": [ + { + "type": "individual", + "url": "https://gitcoin.co/grants/13/ethersjs-complete-simple-and-tiny-2" + }, + { + "type": "individual", + "url": "https://www.buymeacoffee.com/ricmoo" + } + ], + "dependencies": { + "@ethersproject/base64": "^5.7.0", + "@ethersproject/bytes": "^5.7.0", + "@ethersproject/logger": "^5.7.0", + "@ethersproject/properties": "^5.7.0", + "@ethersproject/strings": "^5.7.0" + } + }, + "node_modules/@ethersproject/wordlists": { + "version": "5.7.0", + "resolved": "https://registry.npmjs.org/@ethersproject/wordlists/-/wordlists-5.7.0.tgz", + "integrity": "sha512-S2TFNJNfHWVHNE6cNDjbVlZ6MgE17MIxMbMg2zv3wn+3XSJGosL1m9ZVv3GXCf/2ymSsQ+hRI5IzoMJTG6aoVA==", + "dev": true, + "funding": [ + { + "type": "individual", + "url": "https://gitcoin.co/grants/13/ethersjs-complete-simple-and-tiny-2" + }, + { + "type": "individual", + "url": "https://www.buymeacoffee.com/ricmoo" + } + ], + "dependencies": { + "@ethersproject/bytes": "^5.7.0", + "@ethersproject/hash": "^5.7.0", + "@ethersproject/logger": "^5.7.0", + "@ethersproject/properties": "^5.7.0", + "@ethersproject/strings": "^5.7.0" + } + }, + "node_modules/@frangio/servbot": { + "version": "0.2.5", + "resolved": "https://registry.npmjs.org/@frangio/servbot/-/servbot-0.2.5.tgz", + "integrity": "sha512-ogja4iAPZ1VwM5MU3C1ZhB88358F0PGbmSTGOkIZwOyLaDoMHIqOVCnavHjR7DV5h+oAI4Z4KDqlam3myQUrmg==", + "dev": true, + "engines": { + "node": ">=12.x", + "pnpm": "7.5.1" + } + }, + "node_modules/@humanwhocodes/config-array": { + "version": "0.11.10", + "resolved": "https://registry.npmjs.org/@humanwhocodes/config-array/-/config-array-0.11.10.tgz", + "integrity": "sha512-KVVjQmNUepDVGXNuoRRdmmEjruj0KfiGSbS8LVc12LMsWDQzRXJ0qdhN8L8uUigKpfEHRhlaQFY0ib1tnUbNeQ==", + "dev": true, + "dependencies": { + "@humanwhocodes/object-schema": "^1.2.1", + "debug": "^4.1.1", + "minimatch": "^3.0.5" + }, + "engines": { + "node": ">=10.10.0" + } + }, + "node_modules/@humanwhocodes/module-importer": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/@humanwhocodes/module-importer/-/module-importer-1.0.1.tgz", + "integrity": "sha512-bxveV4V8v5Yb4ncFTT3rPSgZBOpCkjfK0y4oVVVJwIuDVBRMDXrPyXRL988i5ap9m9bnyEEjWfm5WkBmtffLfA==", + "dev": true, + "engines": { + "node": ">=12.22" + }, + "funding": { + "type": "github", + "url": "https://github.com/sponsors/nzakas" + } + }, + "node_modules/@humanwhocodes/object-schema": { + "version": "1.2.1", + "resolved": "https://registry.npmjs.org/@humanwhocodes/object-schema/-/object-schema-1.2.1.tgz", + "integrity": "sha512-ZnQMnLV4e7hDlUvw8H+U8ASL02SS2Gn6+9Ac3wGGLIe7+je2AeAOxPY+izIPJDfFDb7eDjev0Us8MO1iFRN8hA==", + "dev": true + }, + "node_modules/@manypkg/find-root": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/@manypkg/find-root/-/find-root-1.1.0.tgz", + "integrity": "sha512-mki5uBvhHzO8kYYix/WRy2WX8S3B5wdVSc9D6KcU5lQNglP2yt58/VfLuAK49glRXChosY8ap2oJ1qgma3GUVA==", + "dev": true, + "dependencies": { + "@babel/runtime": "^7.5.5", + "@types/node": "^12.7.1", + "find-up": "^4.1.0", + "fs-extra": "^8.1.0" + } + }, + "node_modules/@manypkg/find-root/node_modules/fs-extra": { + "version": "8.1.0", + "resolved": "https://registry.npmjs.org/fs-extra/-/fs-extra-8.1.0.tgz", + "integrity": "sha512-yhlQgA6mnOJUKOsRUFsgJdQCvkKhcz8tlZG5HBQfReYZy46OwLcY+Zia0mtdHsOo9y/hP+CxMN0TU9QxoOtG4g==", + "dev": true, + "dependencies": { + "graceful-fs": "^4.2.0", + "jsonfile": "^4.0.0", + "universalify": "^0.1.0" + }, + "engines": { + "node": ">=6 <7 || >=8" + } + }, + "node_modules/@manypkg/get-packages": { + "version": "1.1.3", + "resolved": "https://registry.npmjs.org/@manypkg/get-packages/-/get-packages-1.1.3.tgz", + "integrity": "sha512-fo+QhuU3qE/2TQMQmbVMqaQ6EWbMhi4ABWP+O4AM1NqPBuy0OrApV5LO6BrrgnhtAHS2NH6RrVk9OL181tTi8A==", + "dev": true, + "dependencies": { + "@babel/runtime": "^7.5.5", + "@changesets/types": "^4.0.1", + "@manypkg/find-root": "^1.1.0", + "fs-extra": "^8.1.0", + "globby": "^11.0.0", + "read-yaml-file": "^1.1.0" + } + }, + "node_modules/@manypkg/get-packages/node_modules/@changesets/types": { + "version": "4.1.0", + "resolved": "https://registry.npmjs.org/@changesets/types/-/types-4.1.0.tgz", + "integrity": "sha512-LDQvVDv5Kb50ny2s25Fhm3d9QSZimsoUGBsUioj6MC3qbMUCuC8GPIvk/M6IvXx3lYhAs0lwWUQLb+VIEUCECw==", + "dev": true + }, + "node_modules/@manypkg/get-packages/node_modules/fs-extra": { + "version": "8.1.0", + "resolved": "https://registry.npmjs.org/fs-extra/-/fs-extra-8.1.0.tgz", + "integrity": "sha512-yhlQgA6mnOJUKOsRUFsgJdQCvkKhcz8tlZG5HBQfReYZy46OwLcY+Zia0mtdHsOo9y/hP+CxMN0TU9QxoOtG4g==", + "dev": true, + "dependencies": { + "graceful-fs": "^4.2.0", + "jsonfile": "^4.0.0", + "universalify": "^0.1.0" + }, + "engines": { + "node": ">=6 <7 || >=8" + } + }, + "node_modules/@metamask/eth-sig-util": { + "version": "4.0.1", + "resolved": "https://registry.npmjs.org/@metamask/eth-sig-util/-/eth-sig-util-4.0.1.tgz", + "integrity": "sha512-tghyZKLHZjcdlDqCA3gNZmLeR0XvOE9U1qoQO9ohyAZT6Pya+H9vkBPcsyXytmYLNgVoin7CKCmweo/R43V+tQ==", + "dev": true, + "dependencies": { + "ethereumjs-abi": "^0.6.8", + "ethereumjs-util": "^6.2.1", + "ethjs-util": "^0.1.6", + "tweetnacl": "^1.0.3", + "tweetnacl-util": "^0.15.1" + }, + "engines": { + "node": ">=12.0.0" + } + }, + "node_modules/@metamask/eth-sig-util/node_modules/@types/bn.js": { + "version": "4.11.6", + "resolved": "https://registry.npmjs.org/@types/bn.js/-/bn.js-4.11.6.tgz", + "integrity": "sha512-pqr857jrp2kPuO9uRjZ3PwnJTjoQy+fcdxvBTvHm6dkmEL9q+hDD/2j/0ELOBPtPnS8LjCX0gI9nbl8lVkadpg==", + "dev": true, + "dependencies": { + "@types/node": "*" + } + }, + "node_modules/@metamask/eth-sig-util/node_modules/ethereumjs-util": { + "version": "6.2.1", + "resolved": "https://registry.npmjs.org/ethereumjs-util/-/ethereumjs-util-6.2.1.tgz", + "integrity": "sha512-W2Ktez4L01Vexijrm5EB6w7dg4n/TgpoYU4avuT5T3Vmnw/eCRtiBrJfQYS/DCSvDIOLn2k57GcHdeBcgVxAqw==", + "dev": true, + "dependencies": { + "@types/bn.js": "^4.11.3", + "bn.js": "^4.11.0", + "create-hash": "^1.1.2", + "elliptic": "^6.5.2", + "ethereum-cryptography": "^0.1.3", + "ethjs-util": "0.1.6", + "rlp": "^2.2.3" + } + }, + "node_modules/@noble/hashes": { + "version": "1.2.0", + "resolved": "https://registry.npmjs.org/@noble/hashes/-/hashes-1.2.0.tgz", + "integrity": "sha512-FZfhjEDbT5GRswV3C6uvLPHMiVD6lQBmpoX5+eSiPaMTXte/IKqI5dykDxzZB/WBeK/CDuQRBWarPdi3FNY2zQ==", + "dev": true, + "funding": [ + { + "type": "individual", + "url": "https://paulmillr.com/funding/" + } + ] + }, + "node_modules/@noble/secp256k1": { + "version": "1.7.1", + "resolved": "https://registry.npmjs.org/@noble/secp256k1/-/secp256k1-1.7.1.tgz", + "integrity": "sha512-hOUk6AyBFmqVrv7k5WAw/LpszxVbj9gGN4JRkIX52fdFAj1UA61KXmZDvqVEm+pOyec3+fIeZB02LYa/pWOArw==", + "dev": true, + "funding": [ + { + "type": "individual", + "url": "https://paulmillr.com/funding/" + } + ] + }, + "node_modules/@nodelib/fs.scandir": { + "version": "2.1.5", + "resolved": "https://registry.npmjs.org/@nodelib/fs.scandir/-/fs.scandir-2.1.5.tgz", + "integrity": "sha512-vq24Bq3ym5HEQm2NKCr3yXDwjc7vTsEThRDnkp2DK9p1uqLR+DHurm/NOTo0KG7HYHU7eppKZj3MyqYuMBf62g==", + "dev": true, + "dependencies": { + "@nodelib/fs.stat": "2.0.5", + "run-parallel": "^1.1.9" + }, + "engines": { + "node": ">= 8" + } + }, + "node_modules/@nodelib/fs.stat": { + "version": "2.0.5", + "resolved": "https://registry.npmjs.org/@nodelib/fs.stat/-/fs.stat-2.0.5.tgz", + "integrity": "sha512-RkhPPp2zrqDAQA/2jNhnztcPAlv64XdhIp7a7454A5ovI7Bukxgt7MX7udwAu3zg1DcpPU0rz3VV1SeaqvY4+A==", + "dev": true, + "engines": { + "node": ">= 8" + } + }, + "node_modules/@nodelib/fs.walk": { + "version": "1.2.8", + "resolved": "https://registry.npmjs.org/@nodelib/fs.walk/-/fs.walk-1.2.8.tgz", + "integrity": "sha512-oGB+UxlgWcgQkgwo8GcEGwemoTFt3FIO9ababBmaGwXIoBKZ+GTy0pP185beGg7Llih/NSHSV2XAs1lnznocSg==", + "dev": true, + "dependencies": { + "@nodelib/fs.scandir": "2.1.5", + "fastq": "^1.6.0" + }, + "engines": { + "node": ">= 8" + } + }, + "node_modules/@nomicfoundation/ethereumjs-block": { + "version": "5.0.1", + "resolved": "https://registry.npmjs.org/@nomicfoundation/ethereumjs-block/-/ethereumjs-block-5.0.1.tgz", + "integrity": "sha512-u1Yioemi6Ckj3xspygu/SfFvm8vZEO8/Yx5a1QLzi6nVU0jz3Pg2OmHKJ5w+D9Ogk1vhwRiqEBAqcb0GVhCyHw==", + "dev": true, + "dependencies": { + "@nomicfoundation/ethereumjs-common": "4.0.1", + "@nomicfoundation/ethereumjs-rlp": "5.0.1", + "@nomicfoundation/ethereumjs-trie": "6.0.1", + "@nomicfoundation/ethereumjs-tx": "5.0.1", + "@nomicfoundation/ethereumjs-util": "9.0.1", + "ethereum-cryptography": "0.1.3", + "ethers": "^5.7.1" + }, + "engines": { + "node": ">=14" + } + }, + "node_modules/@nomicfoundation/ethereumjs-block/node_modules/ethers": { + "version": "5.7.2", + "resolved": "https://registry.npmjs.org/ethers/-/ethers-5.7.2.tgz", + "integrity": "sha512-wswUsmWo1aOK8rR7DIKiWSw9DbLWe6x98Jrn8wcTflTVvaXhAMaB5zGAXy0GYQEQp9iO1iSHWVyARQm11zUtyg==", + "dev": true, + "funding": [ + { + "type": "individual", + "url": "https://gitcoin.co/grants/13/ethersjs-complete-simple-and-tiny-2" + }, + { + "type": "individual", + "url": "https://www.buymeacoffee.com/ricmoo" + } + ], + "dependencies": { + "@ethersproject/abi": "5.7.0", + "@ethersproject/abstract-provider": "5.7.0", + "@ethersproject/abstract-signer": "5.7.0", + "@ethersproject/address": "5.7.0", + "@ethersproject/base64": "5.7.0", + "@ethersproject/basex": "5.7.0", + "@ethersproject/bignumber": "5.7.0", + "@ethersproject/bytes": "5.7.0", + "@ethersproject/constants": "5.7.0", + "@ethersproject/contracts": "5.7.0", + "@ethersproject/hash": "5.7.0", + "@ethersproject/hdnode": "5.7.0", + "@ethersproject/json-wallets": "5.7.0", + "@ethersproject/keccak256": "5.7.0", + "@ethersproject/logger": "5.7.0", + "@ethersproject/networks": "5.7.1", + "@ethersproject/pbkdf2": "5.7.0", + "@ethersproject/properties": "5.7.0", + "@ethersproject/providers": "5.7.2", + "@ethersproject/random": "5.7.0", + "@ethersproject/rlp": "5.7.0", + "@ethersproject/sha2": "5.7.0", + "@ethersproject/signing-key": "5.7.0", + "@ethersproject/solidity": "5.7.0", + "@ethersproject/strings": "5.7.0", + "@ethersproject/transactions": "5.7.0", + "@ethersproject/units": "5.7.0", + "@ethersproject/wallet": "5.7.0", + "@ethersproject/web": "5.7.1", + "@ethersproject/wordlists": "5.7.0" + } + }, + "node_modules/@nomicfoundation/ethereumjs-blockchain": { + "version": "7.0.1", + "resolved": "https://registry.npmjs.org/@nomicfoundation/ethereumjs-blockchain/-/ethereumjs-blockchain-7.0.1.tgz", + "integrity": "sha512-NhzndlGg829XXbqJEYrF1VeZhAwSPgsK/OB7TVrdzft3y918hW5KNd7gIZ85sn6peDZOdjBsAXIpXZ38oBYE5A==", + "dev": true, + "dependencies": { + "@nomicfoundation/ethereumjs-block": "5.0.1", + "@nomicfoundation/ethereumjs-common": "4.0.1", + "@nomicfoundation/ethereumjs-ethash": "3.0.1", + "@nomicfoundation/ethereumjs-rlp": "5.0.1", + "@nomicfoundation/ethereumjs-trie": "6.0.1", + "@nomicfoundation/ethereumjs-tx": "5.0.1", + "@nomicfoundation/ethereumjs-util": "9.0.1", + "abstract-level": "^1.0.3", + "debug": "^4.3.3", + "ethereum-cryptography": "0.1.3", + "level": "^8.0.0", + "lru-cache": "^5.1.1", + "memory-level": "^1.0.0" + }, + "engines": { + "node": ">=14" + } + }, + "node_modules/@nomicfoundation/ethereumjs-common": { + "version": "4.0.1", + "resolved": "https://registry.npmjs.org/@nomicfoundation/ethereumjs-common/-/ethereumjs-common-4.0.1.tgz", + "integrity": "sha512-OBErlkfp54GpeiE06brBW/TTbtbuBJV5YI5Nz/aB2evTDo+KawyEzPjBlSr84z/8MFfj8wS2wxzQX1o32cev5g==", + "dev": true, + "dependencies": { + "@nomicfoundation/ethereumjs-util": "9.0.1", + "crc-32": "^1.2.0" + } + }, + "node_modules/@nomicfoundation/ethereumjs-ethash": { + "version": "3.0.1", + "resolved": "https://registry.npmjs.org/@nomicfoundation/ethereumjs-ethash/-/ethereumjs-ethash-3.0.1.tgz", + "integrity": "sha512-KDjGIB5igzWOp8Ik5I6QiRH5DH+XgILlplsHR7TEuWANZA759G6krQ6o8bvj+tRUz08YygMQu/sGd9mJ1DYT8w==", + "dev": true, + "dependencies": { + "@nomicfoundation/ethereumjs-block": "5.0.1", + "@nomicfoundation/ethereumjs-rlp": "5.0.1", + "@nomicfoundation/ethereumjs-util": "9.0.1", + "abstract-level": "^1.0.3", + "bigint-crypto-utils": "^3.0.23", + "ethereum-cryptography": "0.1.3" + }, + "engines": { + "node": ">=14" + } + }, + "node_modules/@nomicfoundation/ethereumjs-evm": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/@nomicfoundation/ethereumjs-evm/-/ethereumjs-evm-2.0.1.tgz", + "integrity": "sha512-oL8vJcnk0Bx/onl+TgQOQ1t/534GKFaEG17fZmwtPFeH8S5soiBYPCLUrvANOl4sCp9elYxIMzIiTtMtNNN8EQ==", + "dev": true, + "dependencies": { + "@ethersproject/providers": "^5.7.1", + "@nomicfoundation/ethereumjs-common": "4.0.1", + "@nomicfoundation/ethereumjs-tx": "5.0.1", + "@nomicfoundation/ethereumjs-util": "9.0.1", + "debug": "^4.3.3", + "ethereum-cryptography": "0.1.3", + "mcl-wasm": "^0.7.1", + "rustbn.js": "~0.2.0" + }, + "engines": { + "node": ">=14" + } + }, + "node_modules/@nomicfoundation/ethereumjs-rlp": { + "version": "5.0.1", + "resolved": "https://registry.npmjs.org/@nomicfoundation/ethereumjs-rlp/-/ethereumjs-rlp-5.0.1.tgz", + "integrity": "sha512-xtxrMGa8kP4zF5ApBQBtjlSbN5E2HI8m8FYgVSYAnO6ssUoY5pVPGy2H8+xdf/bmMa22Ce8nWMH3aEW8CcqMeQ==", + "dev": true, + "bin": { + "rlp": "bin/rlp" + }, + "engines": { + "node": ">=14" + } + }, + "node_modules/@nomicfoundation/ethereumjs-statemanager": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/@nomicfoundation/ethereumjs-statemanager/-/ethereumjs-statemanager-2.0.1.tgz", + "integrity": "sha512-B5ApMOnlruVOR7gisBaYwFX+L/AP7i/2oAahatssjPIBVDF6wTX1K7Qpa39E/nzsH8iYuL3krkYeUFIdO3EMUQ==", + "dev": true, + "dependencies": { + "@nomicfoundation/ethereumjs-common": "4.0.1", + "@nomicfoundation/ethereumjs-rlp": "5.0.1", + "debug": "^4.3.3", + "ethereum-cryptography": "0.1.3", + "ethers": "^5.7.1", + "js-sdsl": "^4.1.4" + } + }, + "node_modules/@nomicfoundation/ethereumjs-statemanager/node_modules/ethers": { + "version": "5.7.2", + "resolved": "https://registry.npmjs.org/ethers/-/ethers-5.7.2.tgz", + "integrity": "sha512-wswUsmWo1aOK8rR7DIKiWSw9DbLWe6x98Jrn8wcTflTVvaXhAMaB5zGAXy0GYQEQp9iO1iSHWVyARQm11zUtyg==", + "dev": true, + "funding": [ + { + "type": "individual", + "url": "https://gitcoin.co/grants/13/ethersjs-complete-simple-and-tiny-2" + }, + { + "type": "individual", + "url": "https://www.buymeacoffee.com/ricmoo" + } + ], + "dependencies": { + "@ethersproject/abi": "5.7.0", + "@ethersproject/abstract-provider": "5.7.0", + "@ethersproject/abstract-signer": "5.7.0", + "@ethersproject/address": "5.7.0", + "@ethersproject/base64": "5.7.0", + "@ethersproject/basex": "5.7.0", + "@ethersproject/bignumber": "5.7.0", + "@ethersproject/bytes": "5.7.0", + "@ethersproject/constants": "5.7.0", + "@ethersproject/contracts": "5.7.0", + "@ethersproject/hash": "5.7.0", + "@ethersproject/hdnode": "5.7.0", + "@ethersproject/json-wallets": "5.7.0", + "@ethersproject/keccak256": "5.7.0", + "@ethersproject/logger": "5.7.0", + "@ethersproject/networks": "5.7.1", + "@ethersproject/pbkdf2": "5.7.0", + "@ethersproject/properties": "5.7.0", + "@ethersproject/providers": "5.7.2", + "@ethersproject/random": "5.7.0", + "@ethersproject/rlp": "5.7.0", + "@ethersproject/sha2": "5.7.0", + "@ethersproject/signing-key": "5.7.0", + "@ethersproject/solidity": "5.7.0", + "@ethersproject/strings": "5.7.0", + "@ethersproject/transactions": "5.7.0", + "@ethersproject/units": "5.7.0", + "@ethersproject/wallet": "5.7.0", + "@ethersproject/web": "5.7.1", + "@ethersproject/wordlists": "5.7.0" + } + }, + "node_modules/@nomicfoundation/ethereumjs-trie": { + "version": "6.0.1", + "resolved": "https://registry.npmjs.org/@nomicfoundation/ethereumjs-trie/-/ethereumjs-trie-6.0.1.tgz", + "integrity": "sha512-A64It/IMpDVODzCgxDgAAla8jNjNtsoQZIzZUfIV5AY6Coi4nvn7+VReBn5itlxMiL2yaTlQr9TRWp3CSI6VoA==", + "dev": true, + "dependencies": { + "@nomicfoundation/ethereumjs-rlp": "5.0.1", + "@nomicfoundation/ethereumjs-util": "9.0.1", + "@types/readable-stream": "^2.3.13", + "ethereum-cryptography": "0.1.3", + "readable-stream": "^3.6.0" + }, + "engines": { + "node": ">=14" + } + }, + "node_modules/@nomicfoundation/ethereumjs-tx": { + "version": "5.0.1", + "resolved": "https://registry.npmjs.org/@nomicfoundation/ethereumjs-tx/-/ethereumjs-tx-5.0.1.tgz", + "integrity": "sha512-0HwxUF2u2hrsIM1fsasjXvlbDOq1ZHFV2dd1yGq8CA+MEYhaxZr8OTScpVkkxqMwBcc5y83FyPl0J9MZn3kY0w==", + "dev": true, + "dependencies": { + "@chainsafe/ssz": "^0.9.2", + "@ethersproject/providers": "^5.7.2", + "@nomicfoundation/ethereumjs-common": "4.0.1", + "@nomicfoundation/ethereumjs-rlp": "5.0.1", + "@nomicfoundation/ethereumjs-util": "9.0.1", + "ethereum-cryptography": "0.1.3" + }, + "engines": { + "node": ">=14" + } + }, + "node_modules/@nomicfoundation/ethereumjs-util": { + "version": "9.0.1", + "resolved": "https://registry.npmjs.org/@nomicfoundation/ethereumjs-util/-/ethereumjs-util-9.0.1.tgz", + "integrity": "sha512-TwbhOWQ8QoSCFhV/DDfSmyfFIHjPjFBj957219+V3jTZYZ2rf9PmDtNOeZWAE3p3vlp8xb02XGpd0v6nTUPbsA==", + "dev": true, + "dependencies": { + "@chainsafe/ssz": "^0.10.0", + "@nomicfoundation/ethereumjs-rlp": "5.0.1", + "ethereum-cryptography": "0.1.3" + }, + "engines": { + "node": ">=14" + } + }, + "node_modules/@nomicfoundation/ethereumjs-util/node_modules/@chainsafe/persistent-merkle-tree": { + "version": "0.5.0", + "resolved": "https://registry.npmjs.org/@chainsafe/persistent-merkle-tree/-/persistent-merkle-tree-0.5.0.tgz", + "integrity": "sha512-l0V1b5clxA3iwQLXP40zYjyZYospQLZXzBVIhhr9kDg/1qHZfzzHw0jj4VPBijfYCArZDlPkRi1wZaV2POKeuw==", + "dev": true, + "dependencies": { + "@chainsafe/as-sha256": "^0.3.1" + } + }, + "node_modules/@nomicfoundation/ethereumjs-util/node_modules/@chainsafe/ssz": { + "version": "0.10.2", + "resolved": "https://registry.npmjs.org/@chainsafe/ssz/-/ssz-0.10.2.tgz", + "integrity": "sha512-/NL3Lh8K+0q7A3LsiFq09YXS9fPE+ead2rr7vM2QK8PLzrNsw3uqrif9bpRX5UxgeRjM+vYi+boCM3+GM4ovXg==", + "dev": true, + "dependencies": { + "@chainsafe/as-sha256": "^0.3.1", + "@chainsafe/persistent-merkle-tree": "^0.5.0" + } + }, + "node_modules/@nomicfoundation/ethereumjs-vm": { + "version": "7.0.1", + "resolved": "https://registry.npmjs.org/@nomicfoundation/ethereumjs-vm/-/ethereumjs-vm-7.0.1.tgz", + "integrity": "sha512-rArhyn0jPsS/D+ApFsz3yVJMQ29+pVzNZ0VJgkzAZ+7FqXSRtThl1C1prhmlVr3YNUlfpZ69Ak+RUT4g7VoOuQ==", + "dev": true, + "dependencies": { + "@nomicfoundation/ethereumjs-block": "5.0.1", + "@nomicfoundation/ethereumjs-blockchain": "7.0.1", + "@nomicfoundation/ethereumjs-common": "4.0.1", + "@nomicfoundation/ethereumjs-evm": "2.0.1", + "@nomicfoundation/ethereumjs-rlp": "5.0.1", + "@nomicfoundation/ethereumjs-statemanager": "2.0.1", + "@nomicfoundation/ethereumjs-trie": "6.0.1", + "@nomicfoundation/ethereumjs-tx": "5.0.1", + "@nomicfoundation/ethereumjs-util": "9.0.1", + "debug": "^4.3.3", + "ethereum-cryptography": "0.1.3", + "mcl-wasm": "^0.7.1", + "rustbn.js": "~0.2.0" + }, + "engines": { + "node": ">=14" + } + }, + "node_modules/@nomicfoundation/hardhat-network-helpers": { + "version": "1.0.8", + "resolved": "https://registry.npmjs.org/@nomicfoundation/hardhat-network-helpers/-/hardhat-network-helpers-1.0.8.tgz", + "integrity": "sha512-MNqQbzUJZnCMIYvlniC3U+kcavz/PhhQSsY90tbEtUyMj/IQqsLwIRZa4ctjABh3Bz0KCh9OXUZ7Yk/d9hr45Q==", + "dev": true, + "dependencies": { + "ethereumjs-util": "^7.1.4" + }, + "peerDependencies": { + "hardhat": "^2.9.5" + } + }, + "node_modules/@nomicfoundation/solidity-analyzer": { + "version": "0.1.1", + "resolved": "https://registry.npmjs.org/@nomicfoundation/solidity-analyzer/-/solidity-analyzer-0.1.1.tgz", + "integrity": "sha512-1LMtXj1puAxyFusBgUIy5pZk3073cNXYnXUpuNKFghHbIit/xZgbk0AokpUADbNm3gyD6bFWl3LRFh3dhVdREg==", + "dev": true, + "engines": { + "node": ">= 12" + }, + "optionalDependencies": { + "@nomicfoundation/solidity-analyzer-darwin-arm64": "0.1.1", + "@nomicfoundation/solidity-analyzer-darwin-x64": "0.1.1", + "@nomicfoundation/solidity-analyzer-freebsd-x64": "0.1.1", + "@nomicfoundation/solidity-analyzer-linux-arm64-gnu": "0.1.1", + "@nomicfoundation/solidity-analyzer-linux-arm64-musl": "0.1.1", + "@nomicfoundation/solidity-analyzer-linux-x64-gnu": "0.1.1", + "@nomicfoundation/solidity-analyzer-linux-x64-musl": "0.1.1", + "@nomicfoundation/solidity-analyzer-win32-arm64-msvc": "0.1.1", + "@nomicfoundation/solidity-analyzer-win32-ia32-msvc": "0.1.1", + "@nomicfoundation/solidity-analyzer-win32-x64-msvc": "0.1.1" + } + }, + "node_modules/@nomicfoundation/solidity-analyzer-darwin-arm64": { + "version": "0.1.1", + "resolved": "https://registry.npmjs.org/@nomicfoundation/solidity-analyzer-darwin-arm64/-/solidity-analyzer-darwin-arm64-0.1.1.tgz", + "integrity": "sha512-KcTodaQw8ivDZyF+D76FokN/HdpgGpfjc/gFCImdLUyqB6eSWVaZPazMbeAjmfhx3R0zm/NYVzxwAokFKgrc0w==", + "cpu": [ + "arm64" + ], + "dev": true, + "optional": true, + "os": [ + "darwin" + ], + "engines": { + "node": ">= 10" + } + }, + "node_modules/@nomicfoundation/solidity-analyzer-darwin-x64": { + "version": "0.1.1", + "resolved": "https://registry.npmjs.org/@nomicfoundation/solidity-analyzer-darwin-x64/-/solidity-analyzer-darwin-x64-0.1.1.tgz", + "integrity": "sha512-XhQG4BaJE6cIbjAVtzGOGbK3sn1BO9W29uhk9J8y8fZF1DYz0Doj8QDMfpMu+A6TjPDs61lbsmeYodIDnfveSA==", + "cpu": [ + "x64" + ], + "dev": true, + "optional": true, + "os": [ + "darwin" + ], + "engines": { + "node": ">= 10" + } + }, + "node_modules/@nomicfoundation/solidity-analyzer-freebsd-x64": { + "version": "0.1.1", + "resolved": "https://registry.npmjs.org/@nomicfoundation/solidity-analyzer-freebsd-x64/-/solidity-analyzer-freebsd-x64-0.1.1.tgz", + "integrity": "sha512-GHF1VKRdHW3G8CndkwdaeLkVBi5A9u2jwtlS7SLhBc8b5U/GcoL39Q+1CSO3hYqePNP+eV5YI7Zgm0ea6kMHoA==", + "cpu": [ + "x64" + ], + "dev": true, + "optional": true, + "os": [ + "freebsd" + ], + "engines": { + "node": ">= 10" + } + }, + "node_modules/@nomicfoundation/solidity-analyzer-linux-arm64-gnu": { + "version": "0.1.1", + "resolved": "https://registry.npmjs.org/@nomicfoundation/solidity-analyzer-linux-arm64-gnu/-/solidity-analyzer-linux-arm64-gnu-0.1.1.tgz", + "integrity": "sha512-g4Cv2fO37ZsUENQ2vwPnZc2zRenHyAxHcyBjKcjaSmmkKrFr64yvzeNO8S3GBFCo90rfochLs99wFVGT/0owpg==", + "cpu": [ + "arm64" + ], + "dev": true, + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">= 10" + } + }, + "node_modules/@nomicfoundation/solidity-analyzer-linux-arm64-musl": { + "version": "0.1.1", + "resolved": "https://registry.npmjs.org/@nomicfoundation/solidity-analyzer-linux-arm64-musl/-/solidity-analyzer-linux-arm64-musl-0.1.1.tgz", + "integrity": "sha512-WJ3CE5Oek25OGE3WwzK7oaopY8xMw9Lhb0mlYuJl/maZVo+WtP36XoQTb7bW/i8aAdHW5Z+BqrHMux23pvxG3w==", + "cpu": [ + "arm64" + ], + "dev": true, + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">= 10" + } + }, + "node_modules/@nomicfoundation/solidity-analyzer-linux-x64-gnu": { + "version": "0.1.1", + "resolved": "https://registry.npmjs.org/@nomicfoundation/solidity-analyzer-linux-x64-gnu/-/solidity-analyzer-linux-x64-gnu-0.1.1.tgz", + "integrity": "sha512-5WN7leSr5fkUBBjE4f3wKENUy9HQStu7HmWqbtknfXkkil+eNWiBV275IOlpXku7v3uLsXTOKpnnGHJYI2qsdA==", + "cpu": [ + "x64" + ], + "dev": true, + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">= 10" + } + }, + "node_modules/@nomicfoundation/solidity-analyzer-linux-x64-musl": { + "version": "0.1.1", + "resolved": "https://registry.npmjs.org/@nomicfoundation/solidity-analyzer-linux-x64-musl/-/solidity-analyzer-linux-x64-musl-0.1.1.tgz", + "integrity": "sha512-KdYMkJOq0SYPQMmErv/63CwGwMm5XHenEna9X9aB8mQmhDBrYrlAOSsIPgFCUSL0hjxE3xHP65/EPXR/InD2+w==", + "cpu": [ + "x64" + ], + "dev": true, + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">= 10" + } + }, + "node_modules/@nomicfoundation/solidity-analyzer-win32-arm64-msvc": { + "version": "0.1.1", + "resolved": "https://registry.npmjs.org/@nomicfoundation/solidity-analyzer-win32-arm64-msvc/-/solidity-analyzer-win32-arm64-msvc-0.1.1.tgz", + "integrity": "sha512-VFZASBfl4qiBYwW5xeY20exWhmv6ww9sWu/krWSesv3q5hA0o1JuzmPHR4LPN6SUZj5vcqci0O6JOL8BPw+APg==", + "cpu": [ + "arm64" + ], + "dev": true, + "optional": true, + "os": [ + "win32" + ], + "engines": { + "node": ">= 10" + } + }, + "node_modules/@nomicfoundation/solidity-analyzer-win32-ia32-msvc": { + "version": "0.1.1", + "resolved": "https://registry.npmjs.org/@nomicfoundation/solidity-analyzer-win32-ia32-msvc/-/solidity-analyzer-win32-ia32-msvc-0.1.1.tgz", + "integrity": "sha512-JnFkYuyCSA70j6Si6cS1A9Gh1aHTEb8kOTBApp/c7NRTFGNMH8eaInKlyuuiIbvYFhlXW4LicqyYuWNNq9hkpQ==", + "cpu": [ + "ia32" + ], + "dev": true, + "optional": true, + "os": [ + "win32" + ], + "engines": { + "node": ">= 10" + } + }, + "node_modules/@nomicfoundation/solidity-analyzer-win32-x64-msvc": { + "version": "0.1.1", + "resolved": "https://registry.npmjs.org/@nomicfoundation/solidity-analyzer-win32-x64-msvc/-/solidity-analyzer-win32-x64-msvc-0.1.1.tgz", + "integrity": "sha512-HrVJr6+WjIXGnw3Q9u6KQcbZCtk0caVWhCdFADySvRyUxJ8PnzlaP+MhwNE8oyT8OZ6ejHBRrrgjSqDCFXGirw==", + "cpu": [ + "x64" + ], + "dev": true, + "optional": true, + "os": [ + "win32" + ], + "engines": { + "node": ">= 10" + } + }, + "node_modules/@nomiclabs/hardhat-truffle5": { + "version": "2.0.7", + "resolved": "https://registry.npmjs.org/@nomiclabs/hardhat-truffle5/-/hardhat-truffle5-2.0.7.tgz", + "integrity": "sha512-Pw8451IUZp1bTp0QqCHCYfCHs66sCnyxPcaorapu9mfOV9xnZsVaFdtutnhNEiXdiZwbed7LFKpRsde4BjFwig==", + "dev": true, + "dependencies": { + "@nomiclabs/truffle-contract": "^4.2.23", + "@types/chai": "^4.2.0", + "chai": "^4.2.0", + "ethereumjs-util": "^7.1.4", + "fs-extra": "^7.0.1" + }, + "peerDependencies": { + "@nomiclabs/hardhat-web3": "^2.0.0", + "hardhat": "^2.6.4", + "web3": "^1.0.0-beta.36" + } + }, + "node_modules/@nomiclabs/hardhat-web3": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/@nomiclabs/hardhat-web3/-/hardhat-web3-2.0.0.tgz", + "integrity": "sha512-zt4xN+D+fKl3wW2YlTX3k9APR3XZgPkxJYf36AcliJn3oujnKEVRZaHu0PhgLjO+gR+F/kiYayo9fgd2L8970Q==", + "dev": true, + "dependencies": { + "@types/bignumber.js": "^5.0.0" + }, + "peerDependencies": { + "hardhat": "^2.0.0", + "web3": "^1.0.0-beta.36" + } + }, + "node_modules/@nomiclabs/truffle-contract": { + "version": "4.5.10", + "resolved": "https://registry.npmjs.org/@nomiclabs/truffle-contract/-/truffle-contract-4.5.10.tgz", + "integrity": "sha512-nF/6InFV+0hUvutyFgsdOMCoYlr//2fJbRER4itxYtQtc4/O1biTwZIKRu+5l2J5Sq6LU2WX7vZHtDgQdhWxIQ==", + "dev": true, + "dependencies": { + "@ensdomains/ensjs": "^2.0.1", + "@truffle/blockchain-utils": "^0.1.3", + "@truffle/contract-schema": "^3.4.7", + "@truffle/debug-utils": "^6.0.22", + "@truffle/error": "^0.1.0", + "@truffle/interface-adapter": "^0.5.16", + "bignumber.js": "^7.2.1", + "ethereum-ens": "^0.8.0", + "ethers": "^4.0.0-beta.1", + "source-map-support": "^0.5.19" + }, + "peerDependencies": { + "web3": "^1.2.1", + "web3-core-helpers": "^1.2.1", + "web3-core-promievent": "^1.2.1", + "web3-eth-abi": "^1.2.1", + "web3-utils": "^1.2.1" + } + }, + "node_modules/@openzeppelin/contract-loader": { + "version": "0.6.3", + "resolved": "https://registry.npmjs.org/@openzeppelin/contract-loader/-/contract-loader-0.6.3.tgz", + "integrity": "sha512-cOFIjBjwbGgZhDZsitNgJl0Ye1rd5yu/Yx5LMgeq3u0ZYzldm4uObzHDFq4gjDdoypvyORjjJa3BlFA7eAnVIg==", + "dev": true, + "dependencies": { + "find-up": "^4.1.0", + "fs-extra": "^8.1.0" + } + }, + "node_modules/@openzeppelin/contract-loader/node_modules/fs-extra": { + "version": "8.1.0", + "resolved": "https://registry.npmjs.org/fs-extra/-/fs-extra-8.1.0.tgz", + "integrity": "sha512-yhlQgA6mnOJUKOsRUFsgJdQCvkKhcz8tlZG5HBQfReYZy46OwLcY+Zia0mtdHsOo9y/hP+CxMN0TU9QxoOtG4g==", + "dev": true, + "dependencies": { + "graceful-fs": "^4.2.0", + "jsonfile": "^4.0.0", + "universalify": "^0.1.0" + }, + "engines": { + "node": ">=6 <7 || >=8" + } + }, + "node_modules/@openzeppelin/docs-utils": { + "version": "0.1.4", + "resolved": "https://registry.npmjs.org/@openzeppelin/docs-utils/-/docs-utils-0.1.4.tgz", + "integrity": "sha512-2I56U1GhnNlymz0gGmJbyZKhnErGIaJ+rqtKTGyNf7YX3jgeS9/Twv8H0T+OgLV4dimtCHPz/27w6CYhWQ/TGg==", + "dev": true, + "dependencies": { + "@frangio/servbot": "^0.2.5", + "chalk": "^3.0.0", + "chokidar": "^3.5.3", + "env-paths": "^2.2.0", + "find-up": "^4.1.0", + "is-port-reachable": "^3.0.0", + "js-yaml": "^3.13.1", + "lodash.startcase": "^4.4.0", + "minimist": "^1.2.0" + }, + "bin": { + "oz-docs": "oz-docs.js" + } + }, + "node_modules/@openzeppelin/docs-utils/node_modules/ansi-styles": { + "version": "4.3.0", + "resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-4.3.0.tgz", + "integrity": "sha512-zbB9rCJAT1rbjiVDb2hqKFHNYLxgtk8NURxZ3IZwD3F6NtxbXZQCnnSi1Lkx+IDohdPlFp222wVALIheZJQSEg==", + "dev": true, + "dependencies": { + "color-convert": "^2.0.1" + }, + "engines": { + "node": ">=8" + }, + "funding": { + "url": "https://github.com/chalk/ansi-styles?sponsor=1" + } + }, + "node_modules/@openzeppelin/docs-utils/node_modules/chalk": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/chalk/-/chalk-3.0.0.tgz", + "integrity": "sha512-4D3B6Wf41KOYRFdszmDqMCGq5VV/uMAB273JILmO+3jAlh8X4qDtdtgCR3fxtbLEMzSx22QdhnDcJvu2u1fVwg==", + "dev": true, + "dependencies": { + "ansi-styles": "^4.1.0", + "supports-color": "^7.1.0" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/@openzeppelin/docs-utils/node_modules/color-convert": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/color-convert/-/color-convert-2.0.1.tgz", + "integrity": "sha512-RRECPsj7iu/xb5oKYcsFHSppFNnsj/52OVTRKb4zP5onXwVF3zVmmToNcOfGC+CRDpfK/U584fMg38ZHCaElKQ==", + "dev": true, + "dependencies": { + "color-name": "~1.1.4" + }, + "engines": { + "node": ">=7.0.0" + } + }, + "node_modules/@openzeppelin/docs-utils/node_modules/color-name": { + "version": "1.1.4", + "resolved": "https://registry.npmjs.org/color-name/-/color-name-1.1.4.tgz", + "integrity": "sha512-dOy+3AuW3a2wNbZHIuMZpTcgjGuLU/uBL/ubcZF9OXbDo8ff4O8yVp5Bf0efS8uEoYo5q4Fx7dY9OgQGXgAsQA==", + "dev": true + }, + "node_modules/@openzeppelin/docs-utils/node_modules/has-flag": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/has-flag/-/has-flag-4.0.0.tgz", + "integrity": "sha512-EykJT/Q1KjTWctppgIAgfSO0tKVuZUjhgMr17kqTumMl6Afv3EISleU7qZUzoXDFTAHTDC4NOoG/ZxU3EvlMPQ==", + "dev": true, + "engines": { + "node": ">=8" + } + }, + "node_modules/@openzeppelin/docs-utils/node_modules/supports-color": { + "version": "7.2.0", + "resolved": "https://registry.npmjs.org/supports-color/-/supports-color-7.2.0.tgz", + "integrity": "sha512-qpCAvRl9stuOHveKsn7HncJRvv501qIacKzQlO/+Lwxc9+0q2wLyv4Dfvt80/DPn2pqOBsJdDiogXGR9+OvwRw==", + "dev": true, + "dependencies": { + "has-flag": "^4.0.0" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/@openzeppelin/test-helpers": { + "version": "0.5.16", + "resolved": "https://registry.npmjs.org/@openzeppelin/test-helpers/-/test-helpers-0.5.16.tgz", + "integrity": "sha512-T1EvspSfH1qQO/sgGlskLfYVBbqzJR23SZzYl/6B2JnT4EhThcI85UpvDk0BkLWKaDScQTabGHt4GzHW+3SfZg==", + "dev": true, + "dependencies": { + "@openzeppelin/contract-loader": "^0.6.2", + "@truffle/contract": "^4.0.35", + "ansi-colors": "^3.2.3", + "chai": "^4.2.0", + "chai-bn": "^0.2.1", + "ethjs-abi": "^0.2.1", + "lodash.flatten": "^4.4.0", + "semver": "^5.6.0", + "web3": "^1.2.5", + "web3-utils": "^1.2.5" + } + }, + "node_modules/@openzeppelin/test-helpers/node_modules/ansi-colors": { + "version": "3.2.4", + "resolved": "https://registry.npmjs.org/ansi-colors/-/ansi-colors-3.2.4.tgz", + "integrity": "sha512-hHUXGagefjN2iRrID63xckIvotOXOojhQKWIPUZ4mNUZ9nLZW+7FMNoE1lOkEhNWYsx/7ysGIuJYCiMAA9FnrA==", + "dev": true, + "engines": { + "node": ">=6" + } + }, + "node_modules/@openzeppelin/test-helpers/node_modules/semver": { + "version": "5.7.1", + "resolved": "https://registry.npmjs.org/semver/-/semver-5.7.1.tgz", + "integrity": "sha512-sauaDf/PZdVgrLTNYHRtpXa1iRiKcaebiKQ1BJdpQlWH2lCvexQdX55snPFyK7QzpudqbCI0qXFfOasHdyNDGQ==", + "dev": true, + "bin": { + "semver": "bin/semver" + } + }, + "node_modules/@openzeppelin/upgrades-core": { + "version": "1.27.1", + "resolved": "https://registry.npmjs.org/@openzeppelin/upgrades-core/-/upgrades-core-1.27.1.tgz", + "integrity": "sha512-6tLcu6jt0nYdJNr+LRicBgP3jp+//B+dixgB3KsvycSglCHNfmBNDf0ZQ3ZquDdLL0QQmKzIs1EBRVp6lNvPnQ==", + "dev": true, + "dependencies": { + "cbor": "^8.0.0", + "chalk": "^4.1.0", + "compare-versions": "^5.0.0", + "debug": "^4.1.1", + "ethereumjs-util": "^7.0.3", + "minimist": "^1.2.7", + "proper-lockfile": "^4.1.1", + "solidity-ast": "^0.4.15" + }, + "bin": { + "openzeppelin-upgrades-core": "dist/cli/cli.js" + } + }, + "node_modules/@openzeppelin/upgrades-core/node_modules/ansi-styles": { + "version": "4.3.0", + "resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-4.3.0.tgz", + "integrity": "sha512-zbB9rCJAT1rbjiVDb2hqKFHNYLxgtk8NURxZ3IZwD3F6NtxbXZQCnnSi1Lkx+IDohdPlFp222wVALIheZJQSEg==", + "dev": true, + "dependencies": { + "color-convert": "^2.0.1" + }, + "engines": { + "node": ">=8" + }, + "funding": { + "url": "https://github.com/chalk/ansi-styles?sponsor=1" + } + }, + "node_modules/@openzeppelin/upgrades-core/node_modules/chalk": { + "version": "4.1.2", + "resolved": "https://registry.npmjs.org/chalk/-/chalk-4.1.2.tgz", + "integrity": "sha512-oKnbhFyRIXpUuez8iBMmyEa4nbj4IOQyuhc/wy9kY7/WVPcwIO9VA668Pu8RkO7+0G76SLROeyw9CpQ061i4mA==", + "dev": true, + "dependencies": { + "ansi-styles": "^4.1.0", + "supports-color": "^7.1.0" + }, + "engines": { + "node": ">=10" + }, + "funding": { + "url": "https://github.com/chalk/chalk?sponsor=1" + } + }, + "node_modules/@openzeppelin/upgrades-core/node_modules/color-convert": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/color-convert/-/color-convert-2.0.1.tgz", + "integrity": "sha512-RRECPsj7iu/xb5oKYcsFHSppFNnsj/52OVTRKb4zP5onXwVF3zVmmToNcOfGC+CRDpfK/U584fMg38ZHCaElKQ==", + "dev": true, + "dependencies": { + "color-name": "~1.1.4" + }, + "engines": { + "node": ">=7.0.0" + } + }, + "node_modules/@openzeppelin/upgrades-core/node_modules/color-name": { + "version": "1.1.4", + "resolved": "https://registry.npmjs.org/color-name/-/color-name-1.1.4.tgz", + "integrity": "sha512-dOy+3AuW3a2wNbZHIuMZpTcgjGuLU/uBL/ubcZF9OXbDo8ff4O8yVp5Bf0efS8uEoYo5q4Fx7dY9OgQGXgAsQA==", + "dev": true + }, + "node_modules/@openzeppelin/upgrades-core/node_modules/has-flag": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/has-flag/-/has-flag-4.0.0.tgz", + "integrity": "sha512-EykJT/Q1KjTWctppgIAgfSO0tKVuZUjhgMr17kqTumMl6Afv3EISleU7qZUzoXDFTAHTDC4NOoG/ZxU3EvlMPQ==", + "dev": true, + "engines": { + "node": ">=8" + } + }, + "node_modules/@openzeppelin/upgrades-core/node_modules/supports-color": { + "version": "7.2.0", + "resolved": "https://registry.npmjs.org/supports-color/-/supports-color-7.2.0.tgz", + "integrity": "sha512-qpCAvRl9stuOHveKsn7HncJRvv501qIacKzQlO/+Lwxc9+0q2wLyv4Dfvt80/DPn2pqOBsJdDiogXGR9+OvwRw==", + "dev": true, + "dependencies": { + "has-flag": "^4.0.0" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/@scure/base": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/@scure/base/-/base-1.1.1.tgz", + "integrity": "sha512-ZxOhsSyxYwLJj3pLZCefNitxsj093tb2vq90mp2txoYeBqbcjDjqFhyM8eUjq/uFm6zJ+mUuqxlS2FkuSY1MTA==", + "dev": true, + "funding": [ + { + "type": "individual", + "url": "https://paulmillr.com/funding/" + } + ] + }, + "node_modules/@scure/bip32": { + "version": "1.1.5", + "resolved": "https://registry.npmjs.org/@scure/bip32/-/bip32-1.1.5.tgz", + "integrity": "sha512-XyNh1rB0SkEqd3tXcXMi+Xe1fvg+kUIcoRIEujP1Jgv7DqW2r9lg3Ah0NkFaCs9sTkQAQA8kw7xiRXzENi9Rtw==", + "dev": true, + "funding": [ + { + "type": "individual", + "url": "https://paulmillr.com/funding/" + } + ], + "dependencies": { + "@noble/hashes": "~1.2.0", + "@noble/secp256k1": "~1.7.0", + "@scure/base": "~1.1.0" + } + }, + "node_modules/@scure/bip39": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/@scure/bip39/-/bip39-1.1.1.tgz", + "integrity": "sha512-t+wDck2rVkh65Hmv280fYdVdY25J9YeEUIgn2LG1WM6gxFkGzcksoDiUkWVpVp3Oex9xGC68JU2dSbUfwZ2jPg==", + "dev": true, + "funding": [ + { + "type": "individual", + "url": "https://paulmillr.com/funding/" + } + ], + "dependencies": { + "@noble/hashes": "~1.2.0", + "@scure/base": "~1.1.0" + } + }, + "node_modules/@sentry/core": { + "version": "5.30.0", + "resolved": "https://registry.npmjs.org/@sentry/core/-/core-5.30.0.tgz", + "integrity": "sha512-TmfrII8w1PQZSZgPpUESqjB+jC6MvZJZdLtE/0hZ+SrnKhW3x5WlYLvTXZpcWePYBku7rl2wn1RZu6uT0qCTeg==", + "dev": true, + "dependencies": { + "@sentry/hub": "5.30.0", + "@sentry/minimal": "5.30.0", + "@sentry/types": "5.30.0", + "@sentry/utils": "5.30.0", + "tslib": "^1.9.3" + }, + "engines": { + "node": ">=6" + } + }, + "node_modules/@sentry/hub": { + "version": "5.30.0", + "resolved": "https://registry.npmjs.org/@sentry/hub/-/hub-5.30.0.tgz", + "integrity": "sha512-2tYrGnzb1gKz2EkMDQcfLrDTvmGcQPuWxLnJKXJvYTQDGLlEvi2tWz1VIHjunmOvJrB5aIQLhm+dcMRwFZDCqQ==", + "dev": true, + "dependencies": { + "@sentry/types": "5.30.0", + "@sentry/utils": "5.30.0", + "tslib": "^1.9.3" + }, + "engines": { + "node": ">=6" + } + }, + "node_modules/@sentry/minimal": { + "version": "5.30.0", + "resolved": "https://registry.npmjs.org/@sentry/minimal/-/minimal-5.30.0.tgz", + "integrity": "sha512-BwWb/owZKtkDX+Sc4zCSTNcvZUq7YcH3uAVlmh/gtR9rmUvbzAA3ewLuB3myi4wWRAMEtny6+J/FN/x+2wn9Xw==", + "dev": true, + "dependencies": { + "@sentry/hub": "5.30.0", + "@sentry/types": "5.30.0", + "tslib": "^1.9.3" + }, + "engines": { + "node": ">=6" + } + }, + "node_modules/@sentry/node": { + "version": "5.30.0", + "resolved": "https://registry.npmjs.org/@sentry/node/-/node-5.30.0.tgz", + "integrity": "sha512-Br5oyVBF0fZo6ZS9bxbJZG4ApAjRqAnqFFurMVJJdunNb80brh7a5Qva2kjhm+U6r9NJAB5OmDyPkA1Qnt+QVg==", + "dev": true, + "dependencies": { + "@sentry/core": "5.30.0", + "@sentry/hub": "5.30.0", + "@sentry/tracing": "5.30.0", + "@sentry/types": "5.30.0", + "@sentry/utils": "5.30.0", + "cookie": "^0.4.1", + "https-proxy-agent": "^5.0.0", + "lru_map": "^0.3.3", + "tslib": "^1.9.3" + }, + "engines": { + "node": ">=6" + } + }, + "node_modules/@sentry/tracing": { + "version": "5.30.0", + "resolved": "https://registry.npmjs.org/@sentry/tracing/-/tracing-5.30.0.tgz", + "integrity": "sha512-dUFowCr0AIMwiLD7Fs314Mdzcug+gBVo/+NCMyDw8tFxJkwWAKl7Qa2OZxLQ0ZHjakcj1hNKfCQJ9rhyfOl4Aw==", + "dev": true, + "dependencies": { + "@sentry/hub": "5.30.0", + "@sentry/minimal": "5.30.0", + "@sentry/types": "5.30.0", + "@sentry/utils": "5.30.0", + "tslib": "^1.9.3" + }, + "engines": { + "node": ">=6" + } + }, + "node_modules/@sentry/types": { + "version": "5.30.0", + "resolved": "https://registry.npmjs.org/@sentry/types/-/types-5.30.0.tgz", + "integrity": "sha512-R8xOqlSTZ+htqrfteCWU5Nk0CDN5ApUTvrlvBuiH1DyP6czDZ4ktbZB0hAgBlVcK0U+qpD3ag3Tqqpa5Q67rPw==", + "dev": true, + "engines": { + "node": ">=6" + } + }, + "node_modules/@sentry/utils": { + "version": "5.30.0", + "resolved": "https://registry.npmjs.org/@sentry/utils/-/utils-5.30.0.tgz", + "integrity": "sha512-zaYmoH0NWWtvnJjC9/CBseXMtKHm/tm40sz3YfJRxeQjyzRqNQPgivpd9R/oDJCYj999mzdW382p/qi2ypjLww==", + "dev": true, + "dependencies": { + "@sentry/types": "5.30.0", + "tslib": "^1.9.3" + }, + "engines": { + "node": ">=6" + } + }, + "node_modules/@sindresorhus/is": { + "version": "4.6.0", + "resolved": "https://registry.npmjs.org/@sindresorhus/is/-/is-4.6.0.tgz", + "integrity": "sha512-t09vSN3MdfsyCHoFcTRCH/iUtG7OJ0CsjzB8cjAmKc/va/kIgeDI/TxsigdncE/4be734m0cvIYwNaV4i2XqAw==", + "dev": true, + "engines": { + "node": ">=10" + }, + "funding": { + "url": "https://github.com/sindresorhus/is?sponsor=1" + } + }, + "node_modules/@solidity-parser/parser": { + "version": "0.14.5", + "resolved": "https://registry.npmjs.org/@solidity-parser/parser/-/parser-0.14.5.tgz", + "integrity": "sha512-6dKnHZn7fg/iQATVEzqyUOyEidbn05q7YA2mQ9hC0MMXhhV3/JrsxmFSYZAcr7j1yUP700LLhTruvJ3MiQmjJg==", + "dev": true, + "dependencies": { + "antlr4ts": "^0.5.0-alpha.4" + } + }, + "node_modules/@szmarczak/http-timer": { + "version": "5.0.1", + "resolved": "https://registry.npmjs.org/@szmarczak/http-timer/-/http-timer-5.0.1.tgz", + "integrity": "sha512-+PmQX0PiAYPMeVYe237LJAYvOMYW1j2rH5YROyS3b4CTVJum34HfRvKvAzozHAQG0TnHNdUfY9nCeUyRAs//cw==", + "dev": true, + "dependencies": { + "defer-to-connect": "^2.0.1" + }, + "engines": { + "node": ">=14.16" + } + }, + "node_modules/@truffle/abi-utils": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/@truffle/abi-utils/-/abi-utils-1.0.1.tgz", + "integrity": "sha512-ZQUY3XUxEPdqxNaoXsOqF0spTtb6f5RNlnN4MUrVsJ64sOh0FJsY7rxZiUI3khfePmNh4i2qcJrQlKT36YcWUA==", + "dev": true, + "dependencies": { + "change-case": "3.0.2", + "fast-check": "3.1.1", + "web3-utils": "1.10.0" + } + }, + "node_modules/@truffle/blockchain-utils": { + "version": "0.1.8", + "resolved": "https://registry.npmjs.org/@truffle/blockchain-utils/-/blockchain-utils-0.1.8.tgz", + "integrity": "sha512-ZskpYDNHkXD3ota4iU3pZz6kLth87RC+wDn66Rp2Or+DqqJCKdnmS9GDctBi1EcMPDEi0BqpkdrfBuzA9uIkGg==", + "dev": true + }, + "node_modules/@truffle/codec": { + "version": "0.17.0", + "resolved": "https://registry.npmjs.org/@truffle/codec/-/codec-0.17.0.tgz", + "integrity": "sha512-0Z7DQNCnvW++JuvNj35v/CuJoaFSAp7/+lXWwe+Zoe++E27V+hzRI88ZYxRJa0/q1HE81epd1r0ipqc7WBotig==", + "dev": true, + "dependencies": { + "@truffle/abi-utils": "^1.0.1", + "@truffle/compile-common": "^0.9.6", + "big.js": "^6.0.3", + "bn.js": "^5.1.3", + "cbor": "^5.2.0", + "debug": "^4.3.1", + "lodash": "^4.17.21", + "semver": "7.5.2", + "utf8": "^3.0.0", + "web3-utils": "1.10.0" + } + }, + "node_modules/@truffle/codec/node_modules/bignumber.js": { + "version": "9.1.1", + "resolved": "https://registry.npmjs.org/bignumber.js/-/bignumber.js-9.1.1.tgz", + "integrity": "sha512-pHm4LsMJ6lzgNGVfZHjMoO8sdoRhOzOH4MLmY65Jg70bpxCKu5iOHNJyfF6OyvYw7t8Fpf35RuzUyqnQsj8Vig==", + "dev": true, + "engines": { + "node": "*" + } + }, + "node_modules/@truffle/codec/node_modules/bn.js": { + "version": "5.2.1", + "resolved": "https://registry.npmjs.org/bn.js/-/bn.js-5.2.1.tgz", + "integrity": "sha512-eXRvHzWyYPBuB4NBy0cmYQjGitUrtqwbvlzP3G6VFnNRbsZQIxQ10PbKKHt8gZ/HW/D/747aDl+QkDqg3KQLMQ==", + "dev": true + }, + "node_modules/@truffle/codec/node_modules/cbor": { + "version": "5.2.0", + "resolved": "https://registry.npmjs.org/cbor/-/cbor-5.2.0.tgz", + "integrity": "sha512-5IMhi9e1QU76ppa5/ajP1BmMWZ2FHkhAhjeVKQ/EFCgYSEaeVaoGtL7cxJskf9oCCk+XjzaIdc3IuU/dbA/o2A==", + "dev": true, + "dependencies": { + "bignumber.js": "^9.0.1", + "nofilter": "^1.0.4" + }, + "engines": { + "node": ">=6.0.0" + } + }, + "node_modules/@truffle/codec/node_modules/lru-cache": { + "version": "6.0.0", + "resolved": "https://registry.npmjs.org/lru-cache/-/lru-cache-6.0.0.tgz", + "integrity": "sha512-Jo6dJ04CmSjuznwJSS3pUeWmd/H0ffTlkXXgwZi+eq1UCmqQwCh+eLsYOYCwY991i2Fah4h1BEMCx4qThGbsiA==", + "dev": true, + "dependencies": { + "yallist": "^4.0.0" + }, + "engines": { + "node": ">=10" + } + }, + "node_modules/@truffle/codec/node_modules/nofilter": { + "version": "1.0.4", + "resolved": "https://registry.npmjs.org/nofilter/-/nofilter-1.0.4.tgz", + "integrity": "sha512-N8lidFp+fCz+TD51+haYdbDGrcBWwuHX40F5+z0qkUjMJ5Tp+rdSuAkMJ9N9eoolDlEVTf6u5icM+cNKkKW2mA==", + "dev": true, + "engines": { + "node": ">=8" + } + }, + "node_modules/@truffle/codec/node_modules/semver": { + "version": "7.5.2", + "resolved": "https://registry.npmjs.org/semver/-/semver-7.5.2.tgz", + "integrity": "sha512-SoftuTROv/cRjCze/scjGyiDtcUyxw1rgYQSZY7XTmtR5hX+dm76iDbTH8TkLPHCQmlbQVSSbNZCPM2hb0knnQ==", + "dev": true, + "dependencies": { + "lru-cache": "^6.0.0" + }, + "bin": { + "semver": "bin/semver.js" + }, + "engines": { + "node": ">=10" + } + }, + "node_modules/@truffle/codec/node_modules/yallist": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/yallist/-/yallist-4.0.0.tgz", + "integrity": "sha512-3wdGidZyq5PB084XLES5TpOSRA3wjXAlIWMhum2kRcv/41Sn2emQ0dycQW4uZXLejwKvg6EsvbdlVL+FYEct7A==", + "dev": true + }, + "node_modules/@truffle/compile-common": { + "version": "0.9.6", + "resolved": "https://registry.npmjs.org/@truffle/compile-common/-/compile-common-0.9.6.tgz", + "integrity": "sha512-TCcmr1E0GqMZJ2tOaCRNEllxTBJ/g7TuD6jDJpw5Gt9Bw0YO3Cmp6yPQRynRSO4xMJbHUgiEsSfRgIhswut5UA==", + "dev": true, + "dependencies": { + "@truffle/error": "^0.2.1", + "colors": "1.4.0" + } + }, + "node_modules/@truffle/compile-common/node_modules/@truffle/error": { + "version": "0.2.1", + "resolved": "https://registry.npmjs.org/@truffle/error/-/error-0.2.1.tgz", + "integrity": "sha512-5Qy+z9dg9hP37WNdLnXH4b9MzemWrjTufRq7/DTKqimjyxCP/1zlL8gQEMdiSx1BBtAZz0xypkID/jb7AF/Osg==", + "dev": true + }, + "node_modules/@truffle/contract": { + "version": "4.6.26", + "resolved": "https://registry.npmjs.org/@truffle/contract/-/contract-4.6.26.tgz", + "integrity": "sha512-B3KM8fW9dKJCzMRD40r+u+iqQtBGFbcMr2GML31iUkjC77Wn/KlM9cCGZiuXcOquWmBlKrpD4nJCoGirPhyPTQ==", + "dev": true, + "dependencies": { + "@ensdomains/ensjs": "^2.1.0", + "@truffle/blockchain-utils": "^0.1.8", + "@truffle/contract-schema": "^3.4.14", + "@truffle/debug-utils": "^6.0.54", + "@truffle/error": "^0.2.1", + "@truffle/interface-adapter": "^0.5.34", + "bignumber.js": "^7.2.1", + "debug": "^4.3.1", + "ethers": "^4.0.32", + "web3": "1.10.0", + "web3-core-helpers": "1.10.0", + "web3-core-promievent": "1.10.0", + "web3-eth-abi": "1.10.0", + "web3-utils": "1.10.0" + } + }, + "node_modules/@truffle/contract-schema": { + "version": "3.4.14", + "resolved": "https://registry.npmjs.org/@truffle/contract-schema/-/contract-schema-3.4.14.tgz", + "integrity": "sha512-IwVQZG9RVNwTdn321+jbFIcky3/kZLkCtq8tqil4jZwivvmZQg8rIVC8GJ7Lkrmixl9/yTyQNL6GtIUUvkZxyA==", + "dev": true, + "dependencies": { + "ajv": "^6.10.0", + "debug": "^4.3.1" + } + }, + "node_modules/@truffle/contract/node_modules/@truffle/error": { + "version": "0.2.1", + "resolved": "https://registry.npmjs.org/@truffle/error/-/error-0.2.1.tgz", + "integrity": "sha512-5Qy+z9dg9hP37WNdLnXH4b9MzemWrjTufRq7/DTKqimjyxCP/1zlL8gQEMdiSx1BBtAZz0xypkID/jb7AF/Osg==", + "dev": true + }, + "node_modules/@truffle/debug-utils": { + "version": "6.0.54", + "resolved": "https://registry.npmjs.org/@truffle/debug-utils/-/debug-utils-6.0.54.tgz", + "integrity": "sha512-ENv5TQQv+CJrwSX9AdXXTDHVNHpPfH+yCpRSnM3Sg0dx7IeWJAjGA66/BiucNBUiAgLhV2EcvkMo+4tEPoR+YQ==", + "dev": true, + "dependencies": { + "@truffle/codec": "^0.17.0", + "@trufflesuite/chromafi": "^3.0.0", + "bn.js": "^5.1.3", + "chalk": "^2.4.2", + "debug": "^4.3.1", + "highlightjs-solidity": "^2.0.6" + } + }, + "node_modules/@truffle/debug-utils/node_modules/bn.js": { + "version": "5.2.1", + "resolved": "https://registry.npmjs.org/bn.js/-/bn.js-5.2.1.tgz", + "integrity": "sha512-eXRvHzWyYPBuB4NBy0cmYQjGitUrtqwbvlzP3G6VFnNRbsZQIxQ10PbKKHt8gZ/HW/D/747aDl+QkDqg3KQLMQ==", + "dev": true + }, + "node_modules/@truffle/error": { + "version": "0.1.1", + "resolved": "https://registry.npmjs.org/@truffle/error/-/error-0.1.1.tgz", + "integrity": "sha512-sE7c9IHIGdbK4YayH4BC8i8qMjoAOeg6nUXUDZZp8wlU21/EMpaG+CLx+KqcIPyR+GSWIW3Dm0PXkr2nlggFDA==", + "dev": true + }, + "node_modules/@truffle/interface-adapter": { + "version": "0.5.34", + "resolved": "https://registry.npmjs.org/@truffle/interface-adapter/-/interface-adapter-0.5.34.tgz", + "integrity": "sha512-gPxabfMi2TueE4VxnNuyeudOfvGJQ1ofVC02PFw14cnRQhzH327JikjjQbZ1bT6S7kWl9H6P3hQPFeYFMHdm1g==", + "dev": true, + "dependencies": { + "bn.js": "^5.1.3", + "ethers": "^4.0.32", + "web3": "1.10.0" + } + }, + "node_modules/@truffle/interface-adapter/node_modules/bn.js": { + "version": "5.2.1", + "resolved": "https://registry.npmjs.org/bn.js/-/bn.js-5.2.1.tgz", + "integrity": "sha512-eXRvHzWyYPBuB4NBy0cmYQjGitUrtqwbvlzP3G6VFnNRbsZQIxQ10PbKKHt8gZ/HW/D/747aDl+QkDqg3KQLMQ==", + "dev": true + }, + "node_modules/@trufflesuite/chromafi": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/@trufflesuite/chromafi/-/chromafi-3.0.0.tgz", + "integrity": "sha512-oqWcOqn8nT1bwlPPfidfzS55vqcIDdpfzo3HbU9EnUmcSTX+I8z0UyUFI3tZQjByVJulbzxHxUGS3ZJPwK/GPQ==", + "dev": true, + "dependencies": { + "camelcase": "^4.1.0", + "chalk": "^2.3.2", + "cheerio": "^1.0.0-rc.2", + "detect-indent": "^5.0.0", + "highlight.js": "^10.4.1", + "lodash.merge": "^4.6.2", + "strip-ansi": "^4.0.0", + "strip-indent": "^2.0.0" + } + }, + "node_modules/@trufflesuite/chromafi/node_modules/detect-indent": { + "version": "5.0.0", + "resolved": "https://registry.npmjs.org/detect-indent/-/detect-indent-5.0.0.tgz", + "integrity": "sha512-rlpvsxUtM0PQvy9iZe640/IWwWYyBsTApREbA1pHOpmOUIl9MkP/U4z7vTtg4Oaojvqhxt7sdufnT0EzGaR31g==", + "dev": true, + "engines": { + "node": ">=4" + } + }, + "node_modules/@types/bignumber.js": { + "version": "5.0.0", + "resolved": "https://registry.npmjs.org/@types/bignumber.js/-/bignumber.js-5.0.0.tgz", + "integrity": "sha512-0DH7aPGCClywOFaxxjE6UwpN2kQYe9LwuDQMv+zYA97j5GkOMo8e66LYT+a8JYU7jfmUFRZLa9KycxHDsKXJCA==", + "deprecated": "This is a stub types definition for bignumber.js (https://github.com/MikeMcl/bignumber.js/). bignumber.js provides its own type definitions, so you don't need @types/bignumber.js installed!", + "dev": true, + "dependencies": { + "bignumber.js": "*" + } + }, + "node_modules/@types/bn.js": { + "version": "5.1.1", + "resolved": "https://registry.npmjs.org/@types/bn.js/-/bn.js-5.1.1.tgz", + "integrity": "sha512-qNrYbZqMx0uJAfKnKclPh+dTwK33KfLHYqtyODwd5HnXOjnkhc4qgn3BrK6RWyGZm5+sIFE7Q7Vz6QQtJB7w7g==", + "dev": true, + "dependencies": { + "@types/node": "*" + } + }, + "node_modules/@types/cacheable-request": { + "version": "6.0.3", + "resolved": "https://registry.npmjs.org/@types/cacheable-request/-/cacheable-request-6.0.3.tgz", + "integrity": "sha512-IQ3EbTzGxIigb1I3qPZc1rWJnH0BmSKv5QYTalEwweFvyBDLSAe24zP0le/hyi7ecGfZVlIVAg4BZqb8WBwKqw==", + "dev": true, + "dependencies": { + "@types/http-cache-semantics": "*", + "@types/keyv": "^3.1.4", + "@types/node": "*", + "@types/responselike": "^1.0.0" + } + }, + "node_modules/@types/chai": { + "version": "4.3.5", + "resolved": "https://registry.npmjs.org/@types/chai/-/chai-4.3.5.tgz", + "integrity": "sha512-mEo1sAde+UCE6b2hxn332f1g1E8WfYRu6p5SvTKr2ZKC1f7gFJXk4h5PyGP9Dt6gCaG8y8XhwnXWC6Iy2cmBng==", + "dev": true + }, + "node_modules/@types/concat-stream": { + "version": "1.6.1", + "resolved": "https://registry.npmjs.org/@types/concat-stream/-/concat-stream-1.6.1.tgz", + "integrity": "sha512-eHE4cQPoj6ngxBZMvVf6Hw7Mh4jMW4U9lpGmS5GBPB9RYxlFg+CHaVN7ErNY4W9XfLIEn20b4VDYaIrbq0q4uA==", + "dev": true, + "dependencies": { + "@types/node": "*" + } + }, + "node_modules/@types/form-data": { + "version": "0.0.33", + "resolved": "https://registry.npmjs.org/@types/form-data/-/form-data-0.0.33.tgz", + "integrity": "sha512-8BSvG1kGm83cyJITQMZSulnl6QV8jqAGreJsc5tPu1Jq0vTSOiY/k24Wx82JRpWwZSqrala6sd5rWi6aNXvqcw==", + "dev": true, + "dependencies": { + "@types/node": "*" + } + }, + "node_modules/@types/glob": { + "version": "7.2.0", + "resolved": "https://registry.npmjs.org/@types/glob/-/glob-7.2.0.tgz", + "integrity": "sha512-ZUxbzKl0IfJILTS6t7ip5fQQM/J3TJYubDm3nMbgubNNYS62eXeUpoLUC8/7fJNiFYHTrGPQn7hspDUzIHX3UA==", + "dev": true, + "dependencies": { + "@types/minimatch": "*", + "@types/node": "*" + } + }, + "node_modules/@types/http-cache-semantics": { + "version": "4.0.1", + "resolved": "https://registry.npmjs.org/@types/http-cache-semantics/-/http-cache-semantics-4.0.1.tgz", + "integrity": "sha512-SZs7ekbP8CN0txVG2xVRH6EgKmEm31BOxA07vkFaETzZz1xh+cbt8BcI0slpymvwhx5dlFnQG2rTlPVQn+iRPQ==", + "dev": true + }, + "node_modules/@types/is-ci": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/@types/is-ci/-/is-ci-3.0.0.tgz", + "integrity": "sha512-Q0Op0hdWbYd1iahB+IFNQcWXFq4O0Q5MwQP7uN0souuQ4rPg1vEYcnIOfr1gY+M+6rc8FGoRaBO1mOOvL29sEQ==", + "dev": true, + "dependencies": { + "ci-info": "^3.1.0" + } + }, + "node_modules/@types/keyv": { + "version": "3.1.4", + "resolved": "https://registry.npmjs.org/@types/keyv/-/keyv-3.1.4.tgz", + "integrity": "sha512-BQ5aZNSCpj7D6K2ksrRCTmKRLEpnPvWDiLPfoGyhZ++8YtiK9d/3DBKPJgry359X/P1PfruyYwvnvwFjuEiEIg==", + "dev": true, + "dependencies": { + "@types/node": "*" + } + }, + "node_modules/@types/lru-cache": { + "version": "5.1.1", + "resolved": "https://registry.npmjs.org/@types/lru-cache/-/lru-cache-5.1.1.tgz", + "integrity": "sha512-ssE3Vlrys7sdIzs5LOxCzTVMsU7i9oa/IaW92wF32JFb3CVczqOkru2xspuKczHEbG3nvmPY7IFqVmGGHdNbYw==", + "dev": true + }, + "node_modules/@types/minimatch": { + "version": "5.1.2", + "resolved": "https://registry.npmjs.org/@types/minimatch/-/minimatch-5.1.2.tgz", + "integrity": "sha512-K0VQKziLUWkVKiRVrx4a40iPaxTUefQmjtkQofBkYRcoaaL/8rhwDWww9qWbrgicNOgnpIsMxyNIUM4+n6dUIA==", + "dev": true + }, + "node_modules/@types/minimist": { + "version": "1.2.2", + "resolved": "https://registry.npmjs.org/@types/minimist/-/minimist-1.2.2.tgz", + "integrity": "sha512-jhuKLIRrhvCPLqwPcx6INqmKeiA5EWrsCOPhrlFSrbrmU4ZMPjj5Ul/oLCMDO98XRUIwVm78xICz4EPCektzeQ==", + "dev": true + }, + "node_modules/@types/node": { + "version": "12.20.55", + "resolved": "https://registry.npmjs.org/@types/node/-/node-12.20.55.tgz", + "integrity": "sha512-J8xLz7q2OFulZ2cyGTLE1TbbZcjpno7FaN6zdJNrgAdrJ+DZzh/uFR6YrTb4C+nXakvud8Q4+rbhoIWlYQbUFQ==", + "dev": true + }, + "node_modules/@types/normalize-package-data": { + "version": "2.4.1", + "resolved": "https://registry.npmjs.org/@types/normalize-package-data/-/normalize-package-data-2.4.1.tgz", + "integrity": "sha512-Gj7cI7z+98M282Tqmp2K5EIsoouUEzbBJhQQzDE3jSIRk6r9gsz0oUokqIUR4u1R3dMHo0pDHM7sNOHyhulypw==", + "dev": true + }, + "node_modules/@types/pbkdf2": { + "version": "3.1.0", + "resolved": "https://registry.npmjs.org/@types/pbkdf2/-/pbkdf2-3.1.0.tgz", + "integrity": "sha512-Cf63Rv7jCQ0LaL8tNXmEyqTHuIJxRdlS5vMh1mj5voN4+QFhVZnlZruezqpWYDiJ8UTzhP0VmeLXCmBk66YrMQ==", + "dev": true, + "dependencies": { + "@types/node": "*" + } + }, + "node_modules/@types/qs": { + "version": "6.9.7", + "resolved": "https://registry.npmjs.org/@types/qs/-/qs-6.9.7.tgz", + "integrity": "sha512-FGa1F62FT09qcrueBA6qYTrJPVDzah9a+493+o2PCXsesWHIn27G98TsSMs3WPNbZIEj4+VJf6saSFpvD+3Zsw==", + "dev": true + }, + "node_modules/@types/readable-stream": { + "version": "2.3.15", + "resolved": "https://registry.npmjs.org/@types/readable-stream/-/readable-stream-2.3.15.tgz", + "integrity": "sha512-oM5JSKQCcICF1wvGgmecmHldZ48OZamtMxcGGVICOJA8o8cahXC1zEVAif8iwoc5j8etxFaRFnf095+CDsuoFQ==", + "dev": true, + "dependencies": { + "@types/node": "*", + "safe-buffer": "~5.1.1" + } + }, + "node_modules/@types/readable-stream/node_modules/safe-buffer": { + "version": "5.1.2", + "resolved": "https://registry.npmjs.org/safe-buffer/-/safe-buffer-5.1.2.tgz", + "integrity": "sha512-Gd2UZBJDkXlY7GbJxfsE8/nvKkUEU1G38c1siN6QP6a9PT9MmHB8GnpscSmMJSoF8LOIrt8ud/wPtojys4G6+g==", + "dev": true + }, + "node_modules/@types/responselike": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/@types/responselike/-/responselike-1.0.0.tgz", + "integrity": "sha512-85Y2BjiufFzaMIlvJDvTTB8Fxl2xfLo4HgmHzVBz08w4wDePCTjYw66PdrolO0kzli3yam/YCgRufyo1DdQVTA==", + "dev": true, + "dependencies": { + "@types/node": "*" + } + }, + "node_modules/@types/secp256k1": { + "version": "4.0.3", + "resolved": "https://registry.npmjs.org/@types/secp256k1/-/secp256k1-4.0.3.tgz", + "integrity": "sha512-Da66lEIFeIz9ltsdMZcpQvmrmmoqrfju8pm1BH8WbYjZSwUgCwXLb9C+9XYogwBITnbsSaMdVPb2ekf7TV+03w==", + "dev": true, + "dependencies": { + "@types/node": "*" + } + }, + "node_modules/@types/semver": { + "version": "7.5.0", + "resolved": "https://registry.npmjs.org/@types/semver/-/semver-7.5.0.tgz", + "integrity": "sha512-G8hZ6XJiHnuhQKR7ZmysCeJWE08o8T0AXtk5darsCaTVsYZhhgUrq53jizaR2FvsoeCwJhlmwTjkXBY5Pn/ZHw==", + "dev": true + }, + "node_modules/abbrev": { + "version": "1.0.9", + "resolved": "https://registry.npmjs.org/abbrev/-/abbrev-1.0.9.tgz", + "integrity": "sha512-LEyx4aLEC3x6T0UguF6YILf+ntvmOaWsVfENmIW0E9H09vKlLDGelMjjSm0jkDHALj8A8quZ/HapKNigzwge+Q==", + "dev": true + }, + "node_modules/abort-controller": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/abort-controller/-/abort-controller-3.0.0.tgz", + "integrity": "sha512-h8lQ8tacZYnR3vNQTgibj+tODHI5/+l06Au2Pcriv/Gmet0eaj4TwWH41sO9wnHDiQsEj19q0drzdWdeAHtweg==", + "dev": true, + "dependencies": { + "event-target-shim": "^5.0.0" + }, + "engines": { + "node": ">=6.5" + } + }, + "node_modules/abortcontroller-polyfill": { + "version": "1.7.5", + "resolved": "https://registry.npmjs.org/abortcontroller-polyfill/-/abortcontroller-polyfill-1.7.5.tgz", + "integrity": "sha512-JMJ5soJWP18htbbxJjG7bG6yuI6pRhgJ0scHHTfkUjf6wjP912xZWvM+A4sJK3gqd9E8fcPbDnOefbA9Th/FIQ==", + "dev": true + }, + "node_modules/abstract-level": { + "version": "1.0.3", + "resolved": "https://registry.npmjs.org/abstract-level/-/abstract-level-1.0.3.tgz", + "integrity": "sha512-t6jv+xHy+VYwc4xqZMn2Pa9DjcdzvzZmQGRjTFc8spIbRGHgBrEKbPq+rYXc7CCo0lxgYvSgKVg9qZAhpVQSjA==", + "dev": true, + "dependencies": { + "buffer": "^6.0.3", + "catering": "^2.1.0", + "is-buffer": "^2.0.5", + "level-supports": "^4.0.0", + "level-transcoder": "^1.0.1", + "module-error": "^1.0.1", + "queue-microtask": "^1.2.3" + }, + "engines": { + "node": ">=12" + } + }, + "node_modules/abstract-level/node_modules/buffer": { + "version": "6.0.3", + "resolved": "https://registry.npmjs.org/buffer/-/buffer-6.0.3.tgz", + "integrity": "sha512-FTiCpNxtwiZZHEZbcbTIcZjERVICn9yq/pDFkTl95/AxzD1naBctN7YO68riM/gLSDY7sdrMby8hofADYuuqOA==", + "dev": true, + "funding": [ + { + "type": "github", + "url": "https://github.com/sponsors/feross" + }, + { + "type": "patreon", + "url": "https://www.patreon.com/feross" + }, + { + "type": "consulting", + "url": "https://feross.org/support" + } + ], + "dependencies": { + "base64-js": "^1.3.1", + "ieee754": "^1.2.1" + } + }, + "node_modules/accepts": { + "version": "1.3.8", + "resolved": "https://registry.npmjs.org/accepts/-/accepts-1.3.8.tgz", + "integrity": "sha512-PYAthTa2m2VKxuvSD3DPC/Gy+U+sOA1LAuT8mkmRuvw+NACSaeXEQ+NHcVF7rONl6qcaxV3Uuemwawk+7+SJLw==", + "dev": true, + "dependencies": { + "mime-types": "~2.1.34", + "negotiator": "0.6.3" + }, + "engines": { + "node": ">= 0.6" + } + }, + "node_modules/acorn": { + "version": "8.10.0", + "resolved": "https://registry.npmjs.org/acorn/-/acorn-8.10.0.tgz", + "integrity": "sha512-F0SAmZ8iUtS//m8DmCTA0jlh6TDKkHQyK6xc6V4KDTyZKA9dnvX9/3sRTVQrWm79glUAZbnmmNcdYwUIHWVybw==", + "dev": true, + "bin": { + "acorn": "bin/acorn" + }, + "engines": { + "node": ">=0.4.0" + } + }, + "node_modules/acorn-jsx": { + "version": "5.3.2", + "resolved": "https://registry.npmjs.org/acorn-jsx/-/acorn-jsx-5.3.2.tgz", + "integrity": "sha512-rq9s+JNhf0IChjtDXxllJ7g41oZk5SlXtp0LHwyA5cejwn7vKmKp4pPri6YEePv2PU65sAsegbXtIinmDFDXgQ==", + "dev": true, + "peerDependencies": { + "acorn": "^6.0.0 || ^7.0.0 || ^8.0.0" + } + }, + "node_modules/address": { + "version": "1.2.2", + "resolved": "https://registry.npmjs.org/address/-/address-1.2.2.tgz", + "integrity": "sha512-4B/qKCfeE/ODUaAUpSwfzazo5x29WD4r3vXiWsB7I2mSDAihwEqKO+g8GELZUQSSAo5e1XTYh3ZVfLyxBc12nA==", + "dev": true, + "engines": { + "node": ">= 10.0.0" + } + }, + "node_modules/adm-zip": { + "version": "0.4.16", + "resolved": "https://registry.npmjs.org/adm-zip/-/adm-zip-0.4.16.tgz", + "integrity": "sha512-TFi4HBKSGfIKsK5YCkKaaFG2m4PEDyViZmEwof3MTIgzimHLto6muaHVpbrljdIvIrFZzEq/p4nafOeLcYegrg==", + "dev": true, + "engines": { + "node": ">=0.3.0" + } + }, + "node_modules/aes-js": { + "version": "3.1.2", + "resolved": "https://registry.npmjs.org/aes-js/-/aes-js-3.1.2.tgz", + "integrity": "sha512-e5pEa2kBnBOgR4Y/p20pskXI74UEz7de8ZGVo58asOtvSVG5YAbJeELPZxOmt+Bnz3rX753YKhfIn4X4l1PPRQ==", + "dev": true + }, + "node_modules/agent-base": { + "version": "6.0.2", + "resolved": "https://registry.npmjs.org/agent-base/-/agent-base-6.0.2.tgz", + "integrity": "sha512-RZNwNclF7+MS/8bDg70amg32dyeZGZxiDuQmZxKLAlQjr3jGyLx+4Kkk58UO7D2QdgFIQCovuSuZESne6RG6XQ==", + "dev": true, + "dependencies": { + "debug": "4" + }, + "engines": { + "node": ">= 6.0.0" + } + }, + "node_modules/aggregate-error": { + "version": "3.1.0", + "resolved": "https://registry.npmjs.org/aggregate-error/-/aggregate-error-3.1.0.tgz", + "integrity": "sha512-4I7Td01quW/RpocfNayFdFVk1qSuoh0E7JrbRJ16nH01HhKFQ88INq9Sd+nd72zqRySlr9BmDA8xlEJ6vJMrYA==", + "dev": true, + "dependencies": { + "clean-stack": "^2.0.0", + "indent-string": "^4.0.0" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/ajv": { + "version": "6.12.6", + "resolved": "https://registry.npmjs.org/ajv/-/ajv-6.12.6.tgz", + "integrity": "sha512-j3fVLgvTo527anyYyJOGTYJbG+vnnQYvE0m5mmkc1TK+nxAppkCLMIL0aZ4dblVCNoGShhm+kzE4ZUykBoMg4g==", + "dev": true, + "dependencies": { + "fast-deep-equal": "^3.1.1", + "fast-json-stable-stringify": "^2.0.0", + "json-schema-traverse": "^0.4.1", + "uri-js": "^4.2.2" + }, + "funding": { + "type": "github", + "url": "https://github.com/sponsors/epoberezkin" + } + }, + "node_modules/amdefine": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/amdefine/-/amdefine-1.0.1.tgz", + "integrity": "sha512-S2Hw0TtNkMJhIabBwIojKL9YHO5T0n5eNqWJ7Lrlel/zDbftQpxpapi8tZs3X1HWa+u+QeydGmzzNU0m09+Rcg==", + "dev": true, + "optional": true, + "engines": { + "node": ">=0.4.2" + } + }, + "node_modules/ansi-colors": { + "version": "4.1.3", + "resolved": "https://registry.npmjs.org/ansi-colors/-/ansi-colors-4.1.3.tgz", + "integrity": "sha512-/6w/C21Pm1A7aZitlI5Ni/2J6FFQN8i1Cvz3kHABAAbw93v/NlvKdVOqz7CCWz/3iv/JplRSEEZ83XION15ovw==", + "dev": true, + "engines": { + "node": ">=6" + } + }, + "node_modules/ansi-escapes": { + "version": "4.3.2", + "resolved": "https://registry.npmjs.org/ansi-escapes/-/ansi-escapes-4.3.2.tgz", + "integrity": "sha512-gKXj5ALrKWQLsYG9jlTRmR/xKluxHV+Z9QEwNIgCfM1/uwPMCuzVVnh5mwTd+OuBZcwSIMbqssNWRm1lE51QaQ==", + "dev": true, + "dependencies": { + "type-fest": "^0.21.3" + }, + "engines": { + "node": ">=8" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/ansi-escapes/node_modules/type-fest": { + "version": "0.21.3", + "resolved": "https://registry.npmjs.org/type-fest/-/type-fest-0.21.3.tgz", + "integrity": "sha512-t0rzBq87m3fVcduHDUFhKmyyX+9eo6WQjZvf51Ea/M0Q7+T374Jp1aUiyUl0GKxp8M/OETVHSDvmkyPgvX+X2w==", + "dev": true, + "engines": { + "node": ">=10" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/ansi-regex": { + "version": "3.0.1", + "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-3.0.1.tgz", + "integrity": "sha512-+O9Jct8wf++lXxxFc4hc8LsjaSq0HFzzL7cVsw8pRDIPdjKD2mT4ytDZlLuSBZ4cLKZFXIrMGO7DbQCtMJJMKw==", + "dev": true, + "engines": { + "node": ">=4" + } + }, + "node_modules/ansi-styles": { + "version": "3.2.1", + "resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-3.2.1.tgz", + "integrity": "sha512-VT0ZI6kZRdTh8YyJw3SMbYm/u+NqfsAxEpWO0Pf9sq8/e94WxxOpPKx9FR1FlyCtOVDNOQ+8ntlqFxiRc+r5qA==", + "dev": true, + "dependencies": { + "color-convert": "^1.9.0" + }, + "engines": { + "node": ">=4" + } + }, + "node_modules/antlr4": { + "version": "4.13.0", + "resolved": "https://registry.npmjs.org/antlr4/-/antlr4-4.13.0.tgz", + "integrity": "sha512-zooUbt+UscjnWyOrsuY/tVFL4rwrAGwOivpQmvmUDE22hy/lUA467Rc1rcixyRwcRUIXFYBwv7+dClDSHdmmew==", + "dev": true, + "engines": { + "node": ">=16" + } + }, + "node_modules/antlr4ts": { + "version": "0.5.0-alpha.4", + "resolved": "https://registry.npmjs.org/antlr4ts/-/antlr4ts-0.5.0-alpha.4.tgz", + "integrity": "sha512-WPQDt1B74OfPv/IMS2ekXAKkTZIHl88uMetg6q3OTqgFxZ/dxDXI0EWLyZid/1Pe6hTftyg5N7gel5wNAGxXyQ==", + "dev": true + }, + "node_modules/anymatch": { + "version": "3.1.3", + "resolved": "https://registry.npmjs.org/anymatch/-/anymatch-3.1.3.tgz", + "integrity": "sha512-KMReFUr0B4t+D+OBkjR3KYqvocp2XaSzO55UcB6mgQMd3KbcE+mWTyvVV7D/zsdEbNnV6acZUutkiHQXvTr1Rw==", + "dev": true, + "dependencies": { + "normalize-path": "^3.0.0", + "picomatch": "^2.0.4" + }, + "engines": { + "node": ">= 8" + } + }, + "node_modules/argparse": { + "version": "1.0.10", + "resolved": "https://registry.npmjs.org/argparse/-/argparse-1.0.10.tgz", + "integrity": "sha512-o5Roy6tNG4SL/FOkCAN6RzjiakZS25RLYFrcMttJqbdd8BWrnA+fGz57iN5Pb06pvBGvl5gQ0B48dJlslXvoTg==", + "dev": true, + "dependencies": { + "sprintf-js": "~1.0.2" + } + }, + "node_modules/array-buffer-byte-length": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/array-buffer-byte-length/-/array-buffer-byte-length-1.0.0.tgz", + "integrity": "sha512-LPuwb2P+NrQw3XhxGc36+XSvuBPopovXYTR9Ew++Du9Yb/bx5AzBfrIsBoj0EZUifjQU+sHL21sseZ3jerWO/A==", + "dev": true, + "dependencies": { + "call-bind": "^1.0.2", + "is-array-buffer": "^3.0.1" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/array-flatten": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/array-flatten/-/array-flatten-1.1.1.tgz", + "integrity": "sha512-PCVAQswWemu6UdxsDFFX/+gVeYqKAod3D3UVm91jHwynguOwAvYPhx8nNlM++NqRcK6CxxpUafjmhIdKiHibqg==", + "dev": true + }, + "node_modules/array-union": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/array-union/-/array-union-2.1.0.tgz", + "integrity": "sha512-HGyxoOTYUyCM6stUe6EJgnd4EoewAI7zMdfqO+kGjnlZmBDz/cR5pf8r/cR4Wq60sL/p0IkcjUEEPwS3GFrIyw==", + "dev": true, + "engines": { + "node": ">=8" + } + }, + "node_modules/array-uniq": { + "version": "1.0.3", + "resolved": "https://registry.npmjs.org/array-uniq/-/array-uniq-1.0.3.tgz", + "integrity": "sha512-MNha4BWQ6JbwhFhj03YK552f7cb3AzoE8SzeljgChvL1dl3IcvggXVz1DilzySZkCja+CXuZbdW7yATchWn8/Q==", + "dev": true, + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/array.prototype.at": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/array.prototype.at/-/array.prototype.at-1.1.1.tgz", + "integrity": "sha512-n/wYNLJy/fVEU9EGPt2ww920hy1XX3XB2yTREFy1QsxctBgQV/tZIwg1G8jVxELna4pLCzg/xvvS/DDXtI4NNg==", + "dev": true, + "dependencies": { + "call-bind": "^1.0.2", + "define-properties": "^1.1.4", + "es-abstract": "^1.20.4", + "es-shim-unscopables": "^1.0.0" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/array.prototype.findlast": { + "version": "1.2.2", + "resolved": "https://registry.npmjs.org/array.prototype.findlast/-/array.prototype.findlast-1.2.2.tgz", + "integrity": "sha512-p1YDNPNqA+P6cPX9ATsxg7DKir7gOmJ+jh5dEP3LlumMNYVC1F2Jgnyh6oI3n/qD9FeIkqR2jXfd73G68ImYUQ==", + "dev": true, + "dependencies": { + "call-bind": "^1.0.2", + "define-properties": "^1.1.4", + "es-abstract": "^1.20.4", + "es-shim-unscopables": "^1.0.0", + "get-intrinsic": "^1.1.3" + }, + "engines": { + "node": ">= 0.4" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/array.prototype.flat": { + "version": "1.3.1", + "resolved": "https://registry.npmjs.org/array.prototype.flat/-/array.prototype.flat-1.3.1.tgz", + "integrity": "sha512-roTU0KWIOmJ4DRLmwKd19Otg0/mT3qPNt0Qb3GWW8iObuZXxrjB/pzn0R3hqpRSWg4HCwqx+0vwOnWnvlOyeIA==", + "dev": true, + "dependencies": { + "call-bind": "^1.0.2", + "define-properties": "^1.1.4", + "es-abstract": "^1.20.4", + "es-shim-unscopables": "^1.0.0" + }, + "engines": { + "node": ">= 0.4" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/array.prototype.reduce": { + "version": "1.0.5", + "resolved": "https://registry.npmjs.org/array.prototype.reduce/-/array.prototype.reduce-1.0.5.tgz", + "integrity": "sha512-kDdugMl7id9COE8R7MHF5jWk7Dqt/fs4Pv+JXoICnYwqpjjjbUurz6w5fT5IG6brLdJhv6/VoHB0H7oyIBXd+Q==", + "dev": true, + "dependencies": { + "call-bind": "^1.0.2", + "define-properties": "^1.1.4", + "es-abstract": "^1.20.4", + "es-array-method-boxes-properly": "^1.0.0", + "is-string": "^1.0.7" + }, + "engines": { + "node": ">= 0.4" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/arrify": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/arrify/-/arrify-1.0.1.tgz", + "integrity": "sha512-3CYzex9M9FGQjCGMGyi6/31c8GJbgb0qGyrx5HWxPd0aCwh4cB2YjMb2Xf9UuoogrMrlO9cTqnB5rI5GHZTcUA==", + "dev": true, + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/asap": { + "version": "2.0.6", + "resolved": "https://registry.npmjs.org/asap/-/asap-2.0.6.tgz", + "integrity": "sha512-BSHWgDSAiKs50o2Re8ppvp3seVHXSRM44cdSsT9FfNEUUZLOGWVCsiWaRPWM1Znn+mqZ1OfVZ3z3DWEzSp7hRA==", + "dev": true + }, + "node_modules/asn1": { + "version": "0.2.6", + "resolved": "https://registry.npmjs.org/asn1/-/asn1-0.2.6.tgz", + "integrity": "sha512-ix/FxPn0MDjeyJ7i/yoHGFt/EX6LyNbxSEhPPXODPL+KB0VPk86UYfL0lMdy+KCnv+fmvIzySwaK5COwqVbWTQ==", + "dev": true, + "dependencies": { + "safer-buffer": "~2.1.0" + } + }, + "node_modules/assert-plus": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/assert-plus/-/assert-plus-1.0.0.tgz", + "integrity": "sha512-NfJ4UzBCcQGLDlQq7nHxH+tv3kyZ0hHQqF5BO6J7tNJeP5do1llPr8dZ8zHonfhAu0PHAdMkSo+8o0wxg9lZWw==", + "dev": true, + "engines": { + "node": ">=0.8" + } + }, + "node_modules/assertion-error": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/assertion-error/-/assertion-error-1.1.0.tgz", + "integrity": "sha512-jgsaNduz+ndvGyFt3uSuWqvy4lCnIJiovtouQN5JZHOKCS2QuhEdbcQHFhVksz2N2U9hXJo8odG7ETyWlEeuDw==", + "dev": true, + "engines": { + "node": "*" + } + }, + "node_modules/ast-parents": { + "version": "0.0.1", + "resolved": "https://registry.npmjs.org/ast-parents/-/ast-parents-0.0.1.tgz", + "integrity": "sha512-XHusKxKz3zoYk1ic8Un640joHbFMhbqneyoZfoKnEGtf2ey9Uh/IdpcQplODdO/kENaMIWsD0nJm4+wX3UNLHA==", + "dev": true + }, + "node_modules/astral-regex": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/astral-regex/-/astral-regex-2.0.0.tgz", + "integrity": "sha512-Z7tMw1ytTXt5jqMcOP+OQteU1VuNK9Y02uuJtKQ1Sv69jXQKKg5cibLwGJow8yzZP+eAc18EmLGPal0bp36rvQ==", + "dev": true, + "engines": { + "node": ">=8" + } + }, + "node_modules/async": { + "version": "1.5.2", + "resolved": "https://registry.npmjs.org/async/-/async-1.5.2.tgz", + "integrity": "sha512-nSVgobk4rv61R9PUSDtYt7mPVB2olxNR5RWJcAsH676/ef11bUZwvu7+RGYrYauVdDPcO519v68wRhXQtxsV9w==", + "dev": true + }, + "node_modules/async-limiter": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/async-limiter/-/async-limiter-1.0.1.tgz", + "integrity": "sha512-csOlWGAcRFJaI6m+F2WKdnMKr4HhdhFVBk0H/QbJFMCr+uO2kwohwXQPxw/9OCxp05r5ghVBFSyioixx3gfkNQ==", + "dev": true + }, + "node_modules/asynckit": { + "version": "0.4.0", + "resolved": "https://registry.npmjs.org/asynckit/-/asynckit-0.4.0.tgz", + "integrity": "sha512-Oei9OH4tRh0YqU3GxhX79dM/mwVgvbZJaSNaRk+bshkj0S5cfHcgYakreBjrHwatXKbz+IoIdYLxrKim2MjW0Q==", + "dev": true + }, + "node_modules/available-typed-arrays": { + "version": "1.0.5", + "resolved": "https://registry.npmjs.org/available-typed-arrays/-/available-typed-arrays-1.0.5.tgz", + "integrity": "sha512-DMD0KiN46eipeziST1LPP/STfDU0sufISXmjSgvVsoU2tqxctQeASejWcfNtxYKqETM1UxQ8sp2OrSBWpHY6sw==", + "dev": true, + "engines": { + "node": ">= 0.4" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/aws-sign2": { + "version": "0.7.0", + "resolved": "https://registry.npmjs.org/aws-sign2/-/aws-sign2-0.7.0.tgz", + "integrity": "sha512-08kcGqnYf/YmjoRhfxyu+CLxBjUtHLXLXX/vUfx9l2LYzG3c1m61nrpyFUZI6zeS+Li/wWMMidD9KgrqtGq3mA==", + "dev": true, + "engines": { + "node": "*" + } + }, + "node_modules/aws4": { + "version": "1.12.0", + "resolved": "https://registry.npmjs.org/aws4/-/aws4-1.12.0.tgz", + "integrity": "sha512-NmWvPnx0F1SfrQbYwOi7OeaNGokp9XhzNioJ/CSBs8Qa4vxug81mhJEAVZwxXuBmYB5KDRfMq/F3RR0BIU7sWg==", + "dev": true + }, + "node_modules/balanced-match": { + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/balanced-match/-/balanced-match-1.0.2.tgz", + "integrity": "sha512-3oSeUO0TMV67hN1AmbXsK4yaqU7tjiHlbxRDZOpH0KW9+CeX4bRAaX0Anxt0tx2MrpRpWwQaPwIlISEJhYU5Pw==", + "dev": true + }, + "node_modules/base-x": { + "version": "3.0.9", + "resolved": "https://registry.npmjs.org/base-x/-/base-x-3.0.9.tgz", + "integrity": "sha512-H7JU6iBHTal1gp56aKoaa//YUxEaAOUiydvrV/pILqIHXTtqxSkATOnDA2u+jZ/61sD+L/412+7kzXRtWukhpQ==", + "dev": true, + "dependencies": { + "safe-buffer": "^5.0.1" + } + }, + "node_modules/base64-js": { + "version": "1.5.1", + "resolved": "https://registry.npmjs.org/base64-js/-/base64-js-1.5.1.tgz", + "integrity": "sha512-AKpaYlHn8t4SVbOHCy+b5+KKgvR4vrsD8vbvrbiQJps7fKDTkjkDry6ji0rUJjC0kzbNePLwzxq8iypo41qeWA==", + "dev": true, + "funding": [ + { + "type": "github", + "url": "https://github.com/sponsors/feross" + }, + { + "type": "patreon", + "url": "https://www.patreon.com/feross" + }, + { + "type": "consulting", + "url": "https://feross.org/support" + } + ] + }, + "node_modules/bcrypt-pbkdf": { + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/bcrypt-pbkdf/-/bcrypt-pbkdf-1.0.2.tgz", + "integrity": "sha512-qeFIXtP4MSoi6NLqO12WfqARWWuCKi2Rn/9hJLEmtB5yTNr9DqFWkJRCf2qShWzPeAMRnOgCrq0sg/KLv5ES9w==", + "dev": true, + "dependencies": { + "tweetnacl": "^0.14.3" + } + }, + "node_modules/bcrypt-pbkdf/node_modules/tweetnacl": { + "version": "0.14.5", + "resolved": "https://registry.npmjs.org/tweetnacl/-/tweetnacl-0.14.5.tgz", + "integrity": "sha512-KXXFFdAbFXY4geFIwoyNK+f5Z1b7swfXABfL7HXCmoIWMKU3dmS26672A4EeQtDzLKy7SXmfBu51JolvEKwtGA==", + "dev": true + }, + "node_modules/bech32": { + "version": "1.1.4", + "resolved": "https://registry.npmjs.org/bech32/-/bech32-1.1.4.tgz", + "integrity": "sha512-s0IrSOzLlbvX7yp4WBfPITzpAU8sqQcpsmwXDiKwrG4r491vwCO/XpejasRNl0piBMe/DvP4Tz0mIS/X1DPJBQ==", + "dev": true + }, + "node_modules/better-path-resolve": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/better-path-resolve/-/better-path-resolve-1.0.0.tgz", + "integrity": "sha512-pbnl5XzGBdrFU/wT4jqmJVPn2B6UHPBOhzMQkY/SPUPB6QtUXtmBHBIwCbXJol93mOpGMnQyP/+BB19q04xj7g==", + "dev": true, + "dependencies": { + "is-windows": "^1.0.0" + }, + "engines": { + "node": ">=4" + } + }, + "node_modules/big-integer": { + "version": "1.6.36", + "resolved": "https://registry.npmjs.org/big-integer/-/big-integer-1.6.36.tgz", + "integrity": "sha512-t70bfa7HYEA1D9idDbmuv7YbsbVkQ+Hp+8KFSul4aE5e/i1bjCNIRYJZlA8Q8p0r9T8cF/RVvwUgRA//FydEyg==", + "dev": true, + "engines": { + "node": ">=0.6" + } + }, + "node_modules/big.js": { + "version": "6.2.1", + "resolved": "https://registry.npmjs.org/big.js/-/big.js-6.2.1.tgz", + "integrity": "sha512-bCtHMwL9LeDIozFn+oNhhFoq+yQ3BNdnsLSASUxLciOb1vgvpHsIO1dsENiGMgbb4SkP5TrzWzRiLddn8ahVOQ==", + "dev": true, + "engines": { + "node": "*" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/bigjs" + } + }, + "node_modules/bigint-crypto-utils": { + "version": "3.3.0", + "resolved": "https://registry.npmjs.org/bigint-crypto-utils/-/bigint-crypto-utils-3.3.0.tgz", + "integrity": "sha512-jOTSb+drvEDxEq6OuUybOAv/xxoh3cuYRUIPyu8sSHQNKM303UQ2R1DAo45o1AkcIXw6fzbaFI1+xGGdaXs2lg==", + "dev": true, + "engines": { + "node": ">=14.0.0" + } + }, + "node_modules/bignumber.js": { + "version": "7.2.1", + "resolved": "https://registry.npmjs.org/bignumber.js/-/bignumber.js-7.2.1.tgz", + "integrity": "sha512-S4XzBk5sMB+Rcb/LNcpzXr57VRTxgAvaAEDAl1AwRx27j00hT84O6OkteE7u8UB3NuaaygCRrEpqox4uDOrbdQ==", + "dev": true, + "engines": { + "node": "*" + } + }, + "node_modules/binary-extensions": { + "version": "2.2.0", + "resolved": "https://registry.npmjs.org/binary-extensions/-/binary-extensions-2.2.0.tgz", + "integrity": "sha512-jDctJ/IVQbZoJykoeHbhXpOlNBqGNcwXJKJog42E5HDPUwQTSdjCHdihjj0DlnheQ7blbT6dHOafNAiS8ooQKA==", + "dev": true, + "engines": { + "node": ">=8" + } + }, + "node_modules/blakejs": { + "version": "1.2.1", + "resolved": "https://registry.npmjs.org/blakejs/-/blakejs-1.2.1.tgz", + "integrity": "sha512-QXUSXI3QVc/gJME0dBpXrag1kbzOqCjCX8/b54ntNyW6sjtoqxqRk3LTmXzaJoh71zMsDCjM+47jS7XiwN/+fQ==", + "dev": true + }, + "node_modules/bluebird": { + "version": "3.7.2", + "resolved": "https://registry.npmjs.org/bluebird/-/bluebird-3.7.2.tgz", + "integrity": "sha512-XpNj6GDQzdfW+r2Wnn7xiSAd7TM3jzkxGXBGTtWKuSXv1xUV+azxAm8jdWZN06QTQk+2N2XB9jRDkvbmQmcRtg==", + "dev": true + }, + "node_modules/bn.js": { + "version": "4.12.0", + "resolved": "https://registry.npmjs.org/bn.js/-/bn.js-4.12.0.tgz", + "integrity": "sha512-c98Bf3tPniI+scsdk237ku1Dc3ujXQTSgyiPUDEOe7tRkhrqridvh8klBv0HCEso1OLOYcHuCv/cS6DNxKH+ZA==", + "dev": true + }, + "node_modules/body-parser": { + "version": "1.20.2", + "resolved": "https://registry.npmjs.org/body-parser/-/body-parser-1.20.2.tgz", + "integrity": "sha512-ml9pReCu3M61kGlqoTm2umSXTlRTuGTx0bfYj+uIUKKYycG5NtSbeetV3faSU6R7ajOPw0g/J1PvK4qNy7s5bA==", + "dev": true, + "dependencies": { + "bytes": "3.1.2", + "content-type": "~1.0.5", + "debug": "2.6.9", + "depd": "2.0.0", + "destroy": "1.2.0", + "http-errors": "2.0.0", + "iconv-lite": "0.4.24", + "on-finished": "2.4.1", + "qs": "6.11.0", + "raw-body": "2.5.2", + "type-is": "~1.6.18", + "unpipe": "1.0.0" + }, + "engines": { + "node": ">= 0.8", + "npm": "1.2.8000 || >= 1.4.16" + } + }, + "node_modules/body-parser/node_modules/debug": { + "version": "2.6.9", + "resolved": "https://registry.npmjs.org/debug/-/debug-2.6.9.tgz", + "integrity": "sha512-bC7ElrdJaJnPbAP+1EotYvqZsb3ecl5wi6Bfi6BJTUcNowp6cvspg0jXznRTKDjm/E7AdgFBVeAPVMNcKGsHMA==", + "dev": true, + "dependencies": { + "ms": "2.0.0" + } + }, + "node_modules/body-parser/node_modules/ms": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/ms/-/ms-2.0.0.tgz", + "integrity": "sha512-Tpp60P6IUJDTuOq/5Z8cdskzJujfwqfOTkrwIwj7IRISpnkJnT6SyJ4PCPnGMoFjC9ddhal5KVIYtAt97ix05A==", + "dev": true + }, + "node_modules/body-parser/node_modules/qs": { + "version": "6.11.0", + "resolved": "https://registry.npmjs.org/qs/-/qs-6.11.0.tgz", + "integrity": "sha512-MvjoMCJwEarSbUYk5O+nmoSzSutSsTwF85zcHPQ9OrlFoZOYIjaqBAJIqIXjptyD5vThxGq52Xu/MaJzRkIk4Q==", + "dev": true, + "dependencies": { + "side-channel": "^1.0.4" + }, + "engines": { + "node": ">=0.6" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/boolbase": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/boolbase/-/boolbase-1.0.0.tgz", + "integrity": "sha512-JZOSA7Mo9sNGB8+UjSgzdLtokWAky1zbztM3WRLCbZ70/3cTANmQmOdR7y2g+J0e2WXywy1yS468tY+IruqEww==", + "dev": true + }, + "node_modules/brace-expansion": { + "version": "1.1.11", + "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.11.tgz", + "integrity": "sha512-iCuPHDFgrHX7H2vEI/5xpz07zSHB00TpugqhmYtVmMO6518mCuRMoOYFldEBl0g187ufozdaHgWKcYFb61qGiA==", + "dev": true, + "dependencies": { + "balanced-match": "^1.0.0", + "concat-map": "0.0.1" + } + }, + "node_modules/braces": { + "version": "3.0.2", + "resolved": "https://registry.npmjs.org/braces/-/braces-3.0.2.tgz", + "integrity": "sha512-b8um+L1RzM3WDSzvhm6gIz1yfTbBt6YTlcEKAvsmqCZZFw46z626lVj9j1yEPW33H5H+lBQpZMP1k8l+78Ha0A==", + "dev": true, + "dependencies": { + "fill-range": "^7.0.1" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/breakword": { + "version": "1.0.6", + "resolved": "https://registry.npmjs.org/breakword/-/breakword-1.0.6.tgz", + "integrity": "sha512-yjxDAYyK/pBvws9H4xKYpLDpYKEH6CzrBPAuXq3x18I+c/2MkVtT3qAr7Oloi6Dss9qNhPVueAAVU1CSeNDIXw==", + "dev": true, + "dependencies": { + "wcwidth": "^1.0.1" + } + }, + "node_modules/brorand": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/brorand/-/brorand-1.1.0.tgz", + "integrity": "sha512-cKV8tMCEpQs4hK/ik71d6LrPOnpkpGBR0wzxqr68g2m/LB2GxVYQroAjMJZRVM1Y4BCjCKc3vAamxSzOY2RP+w==", + "dev": true + }, + "node_modules/browser-level": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/browser-level/-/browser-level-1.0.1.tgz", + "integrity": "sha512-XECYKJ+Dbzw0lbydyQuJzwNXtOpbMSq737qxJN11sIRTErOMShvDpbzTlgju7orJKvx4epULolZAuJGLzCmWRQ==", + "dev": true, + "dependencies": { + "abstract-level": "^1.0.2", + "catering": "^2.1.1", + "module-error": "^1.0.2", + "run-parallel-limit": "^1.1.0" + } + }, + "node_modules/browser-stdout": { + "version": "1.3.1", + "resolved": "https://registry.npmjs.org/browser-stdout/-/browser-stdout-1.3.1.tgz", + "integrity": "sha512-qhAVI1+Av2X7qelOfAIYwXONood6XlZE/fXaBSmW/T5SzLAmCgzi+eiWE7fUvbHaeNBQH13UftjpXxsfLkMpgw==", + "dev": true + }, + "node_modules/browserify-aes": { + "version": "1.2.0", + "resolved": "https://registry.npmjs.org/browserify-aes/-/browserify-aes-1.2.0.tgz", + "integrity": "sha512-+7CHXqGuspUn/Sl5aO7Ea0xWGAtETPXNSAjHo48JfLdPWcMng33Xe4znFvQweqc/uzk5zSOI3H52CYnjCfb5hA==", + "dev": true, + "dependencies": { + "buffer-xor": "^1.0.3", + "cipher-base": "^1.0.0", + "create-hash": "^1.1.0", + "evp_bytestokey": "^1.0.3", + "inherits": "^2.0.1", + "safe-buffer": "^5.0.1" + } + }, + "node_modules/bs58": { + "version": "4.0.1", + "resolved": "https://registry.npmjs.org/bs58/-/bs58-4.0.1.tgz", + "integrity": "sha512-Ok3Wdf5vOIlBrgCvTq96gBkJw+JUEzdBgyaza5HLtPm7yTHkjRy8+JzNyHF7BHa0bNWOQIp3m5YF0nnFcOIKLw==", + "dev": true, + "dependencies": { + "base-x": "^3.0.2" + } + }, + "node_modules/bs58check": { + "version": "2.1.2", + "resolved": "https://registry.npmjs.org/bs58check/-/bs58check-2.1.2.tgz", + "integrity": "sha512-0TS1jicxdU09dwJMNZtVAfzPi6Q6QeN0pM1Fkzrjn+XYHvzMKPU3pHVpva+769iNVSfIYWf7LJ6WR+BuuMf8cA==", + "dev": true, + "dependencies": { + "bs58": "^4.0.0", + "create-hash": "^1.1.0", + "safe-buffer": "^5.1.2" + } + }, + "node_modules/buffer": { + "version": "5.7.1", + "resolved": "https://registry.npmjs.org/buffer/-/buffer-5.7.1.tgz", + "integrity": "sha512-EHcyIPBQ4BSGlvjB16k5KgAJ27CIsHY/2JBmCRReo48y9rQ3MaUzWX3KVlBa4U7MyX02HdVj0K7C3WaB3ju7FQ==", + "dev": true, + "funding": [ + { + "type": "github", + "url": "https://github.com/sponsors/feross" + }, + { + "type": "patreon", + "url": "https://www.patreon.com/feross" + }, + { + "type": "consulting", + "url": "https://feross.org/support" + } + ], + "dependencies": { + "base64-js": "^1.3.1", + "ieee754": "^1.1.13" + } + }, + "node_modules/buffer-from": { + "version": "1.1.2", + "resolved": "https://registry.npmjs.org/buffer-from/-/buffer-from-1.1.2.tgz", + "integrity": "sha512-E+XQCRwSbaaiChtv6k6Dwgc+bx+Bs6vuKJHHl5kox/BaKbhiXzqQOwK4cO22yElGp2OCmjwVhT3HmxgyPGnJfQ==", + "dev": true + }, + "node_modules/buffer-reverse": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/buffer-reverse/-/buffer-reverse-1.0.1.tgz", + "integrity": "sha512-M87YIUBsZ6N924W57vDwT/aOu8hw7ZgdByz6ijksLjmHJELBASmYTTlNHRgjE+pTsT9oJXGaDSgqqwfdHotDUg==", + "dev": true + }, + "node_modules/buffer-to-arraybuffer": { + "version": "0.0.5", + "resolved": "https://registry.npmjs.org/buffer-to-arraybuffer/-/buffer-to-arraybuffer-0.0.5.tgz", + "integrity": "sha512-3dthu5CYiVB1DEJp61FtApNnNndTckcqe4pFcLdvHtrpG+kcyekCJKg4MRiDcFW7A6AODnXB9U4dwQiCW5kzJQ==", + "dev": true + }, + "node_modules/buffer-xor": { + "version": "1.0.3", + "resolved": "https://registry.npmjs.org/buffer-xor/-/buffer-xor-1.0.3.tgz", + "integrity": "sha512-571s0T7nZWK6vB67HI5dyUF7wXiNcfaPPPTl6zYCNApANjIvYJTg7hlud/+cJpdAhS7dVzqMLmfhfHR3rAcOjQ==", + "dev": true + }, + "node_modules/bufferutil": { + "version": "4.0.7", + "resolved": "https://registry.npmjs.org/bufferutil/-/bufferutil-4.0.7.tgz", + "integrity": "sha512-kukuqc39WOHtdxtw4UScxF/WVnMFVSQVKhtx3AjZJzhd0RGZZldcrfSEbVsWWe6KNH253574cq5F+wpv0G9pJw==", + "dev": true, + "hasInstallScript": true, + "dependencies": { + "node-gyp-build": "^4.3.0" + }, + "engines": { + "node": ">=6.14.2" + } + }, + "node_modules/busboy": { + "version": "1.6.0", + "resolved": "https://registry.npmjs.org/busboy/-/busboy-1.6.0.tgz", + "integrity": "sha512-8SFQbg/0hQ9xy3UNTB0YEnsNBbWfhf7RtnzpL7TkBiTBRfrQ9Fxcnz7VJsleJpyp6rVLvXiuORqjlHi5q+PYuA==", + "dev": true, + "dependencies": { + "streamsearch": "^1.1.0" + }, + "engines": { + "node": ">=10.16.0" + } + }, + "node_modules/bytes": { + "version": "3.1.2", + "resolved": "https://registry.npmjs.org/bytes/-/bytes-3.1.2.tgz", + "integrity": "sha512-/Nf7TyzTx6S3yRJObOAV7956r8cr2+Oj8AC5dt8wSP3BQAoeX58NoHyCU8P8zGkNXStjTSi6fzO6F0pBdcYbEg==", + "dev": true, + "engines": { + "node": ">= 0.8" + } + }, + "node_modules/cacheable-lookup": { + "version": "6.1.0", + "resolved": "https://registry.npmjs.org/cacheable-lookup/-/cacheable-lookup-6.1.0.tgz", + "integrity": "sha512-KJ/Dmo1lDDhmW2XDPMo+9oiy/CeqosPguPCrgcVzKyZrL6pM1gU2GmPY/xo6OQPTUaA/c0kwHuywB4E6nmT9ww==", + "dev": true, + "engines": { + "node": ">=10.6.0" + } + }, + "node_modules/cacheable-request": { + "version": "7.0.4", + "resolved": "https://registry.npmjs.org/cacheable-request/-/cacheable-request-7.0.4.tgz", + "integrity": "sha512-v+p6ongsrp0yTGbJXjgxPow2+DL93DASP4kXCDKb8/bwRtt9OEF3whggkkDkGNzgcWy2XaF4a8nZglC7uElscg==", + "dev": true, + "dependencies": { + "clone-response": "^1.0.2", + "get-stream": "^5.1.0", + "http-cache-semantics": "^4.0.0", + "keyv": "^4.0.0", + "lowercase-keys": "^2.0.0", + "normalize-url": "^6.0.1", + "responselike": "^2.0.0" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/cacheable-request/node_modules/get-stream": { + "version": "5.2.0", + "resolved": "https://registry.npmjs.org/get-stream/-/get-stream-5.2.0.tgz", + "integrity": "sha512-nBF+F1rAZVCu/p7rjzgA+Yb4lfYXrpl7a6VmJrU8wF9I1CKvP/QwPNZHnOlwbTkY6dvtFIzFMSyQXbLoTQPRpA==", + "dev": true, + "dependencies": { + "pump": "^3.0.0" + }, + "engines": { + "node": ">=8" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/cacheable-request/node_modules/lowercase-keys": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/lowercase-keys/-/lowercase-keys-2.0.0.tgz", + "integrity": "sha512-tqNXrS78oMOE73NMxK4EMLQsQowWf8jKooH9g7xPavRT706R6bkQJ6DY2Te7QukaZsulxa30wQ7bk0pm4XiHmA==", + "dev": true, + "engines": { + "node": ">=8" + } + }, + "node_modules/call-bind": { + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/call-bind/-/call-bind-1.0.2.tgz", + "integrity": "sha512-7O+FbCihrB5WGbFYesctwmTKae6rOiIzmz1icreWJ+0aA7LJfuqhEso2T9ncpcFtzMQtzXf2QGGueWJGTYsqrA==", + "dev": true, + "dependencies": { + "function-bind": "^1.1.1", + "get-intrinsic": "^1.0.2" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/callsites": { + "version": "3.1.0", + "resolved": "https://registry.npmjs.org/callsites/-/callsites-3.1.0.tgz", + "integrity": "sha512-P8BjAsXvZS+VIDUI11hHCQEv74YT67YUi5JJFNWIqL235sBmjX4+qx9Muvls5ivyNENctx46xQLQ3aTuE7ssaQ==", + "dev": true, + "engines": { + "node": ">=6" + } + }, + "node_modules/camel-case": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/camel-case/-/camel-case-3.0.0.tgz", + "integrity": "sha512-+MbKztAYHXPr1jNTSKQF52VpcFjwY5RkR7fxksV8Doo4KAYc5Fl4UJRgthBbTmEx8C54DqahhbLJkDwjI3PI/w==", + "dev": true, + "dependencies": { + "no-case": "^2.2.0", + "upper-case": "^1.1.1" + } + }, + "node_modules/camelcase": { + "version": "4.1.0", + "resolved": "https://registry.npmjs.org/camelcase/-/camelcase-4.1.0.tgz", + "integrity": "sha512-FxAv7HpHrXbh3aPo4o2qxHay2lkLY3x5Mw3KeE4KQE8ysVfziWeRZDwcjauvwBSGEC/nXUPzZy8zeh4HokqOnw==", + "dev": true, + "engines": { + "node": ">=4" + } + }, + "node_modules/camelcase-keys": { + "version": "6.2.2", + "resolved": "https://registry.npmjs.org/camelcase-keys/-/camelcase-keys-6.2.2.tgz", + "integrity": "sha512-YrwaA0vEKazPBkn0ipTiMpSajYDSe+KjQfrjhcBMxJt/znbvlHd8Pw/Vamaz5EB4Wfhs3SUR3Z9mwRu/P3s3Yg==", + "dev": true, + "dependencies": { + "camelcase": "^5.3.1", + "map-obj": "^4.0.0", + "quick-lru": "^4.0.1" + }, + "engines": { + "node": ">=8" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/camelcase-keys/node_modules/camelcase": { + "version": "5.3.1", + "resolved": "https://registry.npmjs.org/camelcase/-/camelcase-5.3.1.tgz", + "integrity": "sha512-L28STB170nwWS63UjtlEOE3dldQApaJXZkOI1uMFfzf3rRuPegHaHesyee+YxQ+W6SvRDQV6UrdOdRiR153wJg==", + "dev": true, + "engines": { + "node": ">=6" + } + }, + "node_modules/case": { + "version": "1.6.3", + "resolved": "https://registry.npmjs.org/case/-/case-1.6.3.tgz", + "integrity": "sha512-mzDSXIPaFwVDvZAHqZ9VlbyF4yyXRuX6IvB06WvPYkqJVO24kX1PPhv9bfpKNFZyxYFmmgo03HUiD8iklmJYRQ==", + "dev": true, + "engines": { + "node": ">= 0.8.0" + } + }, + "node_modules/caseless": { + "version": "0.12.0", + "resolved": "https://registry.npmjs.org/caseless/-/caseless-0.12.0.tgz", + "integrity": "sha512-4tYFyifaFfGacoiObjJegolkwSU4xQNGbVgUiNYVUxbQ2x2lUsFvY4hVgVzGiIe6WLOPqycWXA40l+PWsxthUw==", + "dev": true + }, + "node_modules/catering": { + "version": "2.1.1", + "resolved": "https://registry.npmjs.org/catering/-/catering-2.1.1.tgz", + "integrity": "sha512-K7Qy8O9p76sL3/3m7/zLKbRkyOlSZAgzEaLhyj2mXS8PsCud2Eo4hAb8aLtZqHh0QGqLcb9dlJSu6lHRVENm1w==", + "dev": true, + "engines": { + "node": ">=6" + } + }, + "node_modules/cbor": { + "version": "8.1.0", + "resolved": "https://registry.npmjs.org/cbor/-/cbor-8.1.0.tgz", + "integrity": "sha512-DwGjNW9omn6EwP70aXsn7FQJx5kO12tX0bZkaTjzdVFM6/7nhA4t0EENocKGx6D2Bch9PE2KzCUf5SceBdeijg==", + "dev": true, + "dependencies": { + "nofilter": "^3.1.0" + }, + "engines": { + "node": ">=12.19" + } + }, + "node_modules/chai": { + "version": "4.3.7", + "resolved": "https://registry.npmjs.org/chai/-/chai-4.3.7.tgz", + "integrity": "sha512-HLnAzZ2iupm25PlN0xFreAlBA5zaBSv3og0DdeGA4Ar6h6rJ3A0rolRUKJhSF2V10GZKDgWF/VmAEsNWjCRB+A==", + "dev": true, + "dependencies": { + "assertion-error": "^1.1.0", + "check-error": "^1.0.2", + "deep-eql": "^4.1.2", + "get-func-name": "^2.0.0", + "loupe": "^2.3.1", + "pathval": "^1.1.1", + "type-detect": "^4.0.5" + }, + "engines": { + "node": ">=4" + } + }, + "node_modules/chai-bn": { + "version": "0.2.2", + "resolved": "https://registry.npmjs.org/chai-bn/-/chai-bn-0.2.2.tgz", + "integrity": "sha512-MzjelH0p8vWn65QKmEq/DLBG1Hle4WeyqT79ANhXZhn/UxRWO0OogkAxi5oGGtfzwU9bZR8mvbvYdoqNVWQwFg==", + "dev": true, + "peerDependencies": { + "bn.js": "^4.11.0", + "chai": "^4.0.0" + } + }, + "node_modules/chalk": { + "version": "2.4.2", + "resolved": "https://registry.npmjs.org/chalk/-/chalk-2.4.2.tgz", + "integrity": "sha512-Mti+f9lpJNcwF4tWV8/OrTTtF1gZi+f8FqlyAdouralcFWFQWF2+NgCHShjkCb+IFBLq9buZwE1xckQU4peSuQ==", + "dev": true, + "dependencies": { + "ansi-styles": "^3.2.1", + "escape-string-regexp": "^1.0.5", + "supports-color": "^5.3.0" + }, + "engines": { + "node": ">=4" + } + }, + "node_modules/change-case": { + "version": "3.0.2", + "resolved": "https://registry.npmjs.org/change-case/-/change-case-3.0.2.tgz", + "integrity": "sha512-Mww+SLF6MZ0U6kdg11algyKd5BARbyM4TbFBepwowYSR5ClfQGCGtxNXgykpN0uF/bstWeaGDT4JWaDh8zWAHA==", + "dev": true, + "dependencies": { + "camel-case": "^3.0.0", + "constant-case": "^2.0.0", + "dot-case": "^2.1.0", + "header-case": "^1.0.0", + "is-lower-case": "^1.1.0", + "is-upper-case": "^1.1.0", + "lower-case": "^1.1.1", + "lower-case-first": "^1.0.0", + "no-case": "^2.3.2", + "param-case": "^2.1.0", + "pascal-case": "^2.0.0", + "path-case": "^2.1.0", + "sentence-case": "^2.1.0", + "snake-case": "^2.1.0", + "swap-case": "^1.1.0", + "title-case": "^2.1.0", + "upper-case": "^1.1.1", + "upper-case-first": "^1.1.0" + } + }, + "node_modules/chardet": { + "version": "0.7.0", + "resolved": "https://registry.npmjs.org/chardet/-/chardet-0.7.0.tgz", + "integrity": "sha512-mT8iDcrh03qDGRRmoA2hmBJnxpllMR+0/0qlzjqZES6NdiWDcZkCNAk4rPFZ9Q85r27unkiNNg8ZOiwZXBHwcA==", + "dev": true + }, + "node_modules/charenc": { + "version": "0.0.2", + "resolved": "https://registry.npmjs.org/charenc/-/charenc-0.0.2.tgz", + "integrity": "sha512-yrLQ/yVUFXkzg7EDQsPieE/53+0RlaWTs+wBrvW36cyilJ2SaDWfl4Yj7MtLTXleV9uEKefbAGUPv2/iWSooRA==", + "dev": true, + "engines": { + "node": "*" + } + }, + "node_modules/check-error": { + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/check-error/-/check-error-1.0.2.tgz", + "integrity": "sha512-BrgHpW9NURQgzoNyjfq0Wu6VFO6D7IZEmJNdtgNqpzGG8RuNFHt2jQxWlAs4HMe119chBnv+34syEZtc6IhLtA==", + "dev": true, + "engines": { + "node": "*" + } + }, + "node_modules/cheerio": { + "version": "1.0.0-rc.12", + "resolved": "https://registry.npmjs.org/cheerio/-/cheerio-1.0.0-rc.12.tgz", + "integrity": "sha512-VqR8m68vM46BNnuZ5NtnGBKIE/DfN0cRIzg9n40EIq9NOv90ayxLBXA8fXC5gquFRGJSTRqBq25Jt2ECLR431Q==", + "dev": true, + "dependencies": { + "cheerio-select": "^2.1.0", + "dom-serializer": "^2.0.0", + "domhandler": "^5.0.3", + "domutils": "^3.0.1", + "htmlparser2": "^8.0.1", + "parse5": "^7.0.0", + "parse5-htmlparser2-tree-adapter": "^7.0.0" + }, + "engines": { + "node": ">= 6" + }, + "funding": { + "url": "https://github.com/cheeriojs/cheerio?sponsor=1" + } + }, + "node_modules/cheerio-select": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/cheerio-select/-/cheerio-select-2.1.0.tgz", + "integrity": "sha512-9v9kG0LvzrlcungtnJtpGNxY+fzECQKhK4EGJX2vByejiMX84MFNQw4UxPJl3bFbTMw+Dfs37XaIkCwTZfLh4g==", + "dev": true, + "dependencies": { + "boolbase": "^1.0.0", + "css-select": "^5.1.0", + "css-what": "^6.1.0", + "domelementtype": "^2.3.0", + "domhandler": "^5.0.3", + "domutils": "^3.0.1" + }, + "funding": { + "url": "https://github.com/sponsors/fb55" + } + }, + "node_modules/chokidar": { + "version": "3.5.3", + "resolved": "https://registry.npmjs.org/chokidar/-/chokidar-3.5.3.tgz", + "integrity": "sha512-Dr3sfKRP6oTcjf2JmUmFJfeVMvXBdegxB0iVQ5eb2V10uFJUCAS8OByZdVAyVb8xXNz3GjjTgj9kLWsZTqE6kw==", + "dev": true, + "funding": [ + { + "type": "individual", + "url": "https://paulmillr.com/funding/" + } + ], + "dependencies": { + "anymatch": "~3.1.2", + "braces": "~3.0.2", + "glob-parent": "~5.1.2", + "is-binary-path": "~2.1.0", + "is-glob": "~4.0.1", + "normalize-path": "~3.0.0", + "readdirp": "~3.6.0" + }, + "engines": { + "node": ">= 8.10.0" + }, + "optionalDependencies": { + "fsevents": "~2.3.2" + } + }, + "node_modules/chownr": { + "version": "1.1.4", + "resolved": "https://registry.npmjs.org/chownr/-/chownr-1.1.4.tgz", + "integrity": "sha512-jJ0bqzaylmJtVnNgzTeSOs8DPavpbYgEr/b0YL8/2GO3xJEhInFmhKMUnEJQjZumK7KXGFhUy89PrsJWlakBVg==", + "dev": true + }, + "node_modules/ci-info": { + "version": "3.8.0", + "resolved": "https://registry.npmjs.org/ci-info/-/ci-info-3.8.0.tgz", + "integrity": "sha512-eXTggHWSooYhq49F2opQhuHWgzucfF2YgODK4e1566GQs5BIfP30B0oenwBJHfWxAs2fyPB1s7Mg949zLf61Yw==", + "dev": true, + "funding": [ + { + "type": "github", + "url": "https://github.com/sponsors/sibiraj-s" + } + ], + "engines": { + "node": ">=8" + } + }, + "node_modules/cids": { + "version": "0.7.5", + "resolved": "https://registry.npmjs.org/cids/-/cids-0.7.5.tgz", + "integrity": "sha512-zT7mPeghoWAu+ppn8+BS1tQ5qGmbMfB4AregnQjA/qHY3GC1m1ptI9GkWNlgeu38r7CuRdXB47uY2XgAYt6QVA==", + "deprecated": "This module has been superseded by the multiformats module", + "dev": true, + "dependencies": { + "buffer": "^5.5.0", + "class-is": "^1.1.0", + "multibase": "~0.6.0", + "multicodec": "^1.0.0", + "multihashes": "~0.4.15" + }, + "engines": { + "node": ">=4.0.0", + "npm": ">=3.0.0" + } + }, + "node_modules/cids/node_modules/multicodec": { + "version": "1.0.4", + "resolved": "https://registry.npmjs.org/multicodec/-/multicodec-1.0.4.tgz", + "integrity": "sha512-NDd7FeS3QamVtbgfvu5h7fd1IlbaC4EQ0/pgU4zqE2vdHCmBGsUa0TiM8/TdSeG6BMPC92OOCf8F1ocE/Wkrrg==", + "deprecated": "This module has been superseded by the multiformats module", + "dev": true, + "dependencies": { + "buffer": "^5.6.0", + "varint": "^5.0.0" + } + }, + "node_modules/cipher-base": { + "version": "1.0.4", + "resolved": "https://registry.npmjs.org/cipher-base/-/cipher-base-1.0.4.tgz", + "integrity": "sha512-Kkht5ye6ZGmwv40uUDZztayT2ThLQGfnj/T71N/XzeZeo3nf8foyW7zGTsPYkEya3m5f3cAypH+qe7YOrM1U2Q==", + "dev": true, + "dependencies": { + "inherits": "^2.0.1", + "safe-buffer": "^5.0.1" + } + }, + "node_modules/class-is": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/class-is/-/class-is-1.1.0.tgz", + "integrity": "sha512-rhjH9AG1fvabIDoGRVH587413LPjTZgmDF9fOFCbFJQV4yuocX1mHxxvXI4g3cGwbVY9wAYIoKlg1N79frJKQw==", + "dev": true + }, + "node_modules/classic-level": { + "version": "1.3.0", + "resolved": "https://registry.npmjs.org/classic-level/-/classic-level-1.3.0.tgz", + "integrity": "sha512-iwFAJQYtqRTRM0F6L8h4JCt00ZSGdOyqh7yVrhhjrOpFhmBjNlRUey64MCiyo6UmQHMJ+No3c81nujPv+n9yrg==", + "dev": true, + "hasInstallScript": true, + "dependencies": { + "abstract-level": "^1.0.2", + "catering": "^2.1.0", + "module-error": "^1.0.1", + "napi-macros": "^2.2.2", + "node-gyp-build": "^4.3.0" + }, + "engines": { + "node": ">=12" + } + }, + "node_modules/clean-stack": { + "version": "2.2.0", + "resolved": "https://registry.npmjs.org/clean-stack/-/clean-stack-2.2.0.tgz", + "integrity": "sha512-4diC9HaTE+KRAMWhDhrGOECgWZxoevMc5TlkObMqNSsVU62PYzXZ/SMTjzyGAFF1YusgxGcSWTEXBhp0CPwQ1A==", + "dev": true, + "engines": { + "node": ">=6" + } + }, + "node_modules/cli-table3": { + "version": "0.5.1", + "resolved": "https://registry.npmjs.org/cli-table3/-/cli-table3-0.5.1.tgz", + "integrity": "sha512-7Qg2Jrep1S/+Q3EceiZtQcDPWxhAvBw+ERf1162v4sikJrvojMHFqXt8QIVha8UlH9rgU0BeWPytZ9/TzYqlUw==", + "dev": true, + "dependencies": { + "object-assign": "^4.1.0", + "string-width": "^2.1.1" + }, + "engines": { + "node": ">=6" + }, + "optionalDependencies": { + "colors": "^1.1.2" + } + }, + "node_modules/cliui": { + "version": "8.0.1", + "resolved": "https://registry.npmjs.org/cliui/-/cliui-8.0.1.tgz", + "integrity": "sha512-BSeNnyus75C4//NQ9gQt1/csTXyo/8Sb+afLAkzAptFuMsod9HFokGNudZpi/oQV73hnVK+sR+5PVRMd+Dr7YQ==", + "dev": true, + "dependencies": { + "string-width": "^4.2.0", + "strip-ansi": "^6.0.1", + "wrap-ansi": "^7.0.0" + }, + "engines": { + "node": ">=12" + } + }, + "node_modules/cliui/node_modules/ansi-regex": { + "version": "5.0.1", + "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-5.0.1.tgz", + "integrity": "sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ==", + "dev": true, + "engines": { + "node": ">=8" + } + }, + "node_modules/cliui/node_modules/is-fullwidth-code-point": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/is-fullwidth-code-point/-/is-fullwidth-code-point-3.0.0.tgz", + "integrity": "sha512-zymm5+u+sCsSWyD9qNaejV3DFvhCKclKdizYaJUuHA83RLjb7nSuGnddCHGv0hk+KY7BMAlsWeK4Ueg6EV6XQg==", + "dev": true, + "engines": { + "node": ">=8" + } + }, + "node_modules/cliui/node_modules/string-width": { + "version": "4.2.3", + "resolved": "https://registry.npmjs.org/string-width/-/string-width-4.2.3.tgz", + "integrity": "sha512-wKyQRQpjJ0sIp62ErSZdGsjMJWsap5oRNihHhu6G7JVO/9jIB6UyevL+tXuOqrng8j/cxKTWyWUwvSTriiZz/g==", + "dev": true, + "dependencies": { + "emoji-regex": "^8.0.0", + "is-fullwidth-code-point": "^3.0.0", + "strip-ansi": "^6.0.1" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/cliui/node_modules/strip-ansi": { + "version": "6.0.1", + "resolved": "https://registry.npmjs.org/strip-ansi/-/strip-ansi-6.0.1.tgz", + "integrity": "sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A==", + "dev": true, + "dependencies": { + "ansi-regex": "^5.0.1" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/clone": { + "version": "1.0.4", + "resolved": "https://registry.npmjs.org/clone/-/clone-1.0.4.tgz", + "integrity": "sha512-JQHZ2QMW6l3aH/j6xCqQThY/9OH4D/9ls34cgkUBiEeocRTU04tHfKPBsUK1PqZCUQM7GiA0IIXJSuXHI64Kbg==", + "dev": true, + "engines": { + "node": ">=0.8" + } + }, + "node_modules/clone-response": { + "version": "1.0.3", + "resolved": "https://registry.npmjs.org/clone-response/-/clone-response-1.0.3.tgz", + "integrity": "sha512-ROoL94jJH2dUVML2Y/5PEDNaSHgeOdSDicUyS7izcF63G6sTc/FTjLub4b8Il9S8S0beOfYt0TaA5qvFK+w0wA==", + "dev": true, + "dependencies": { + "mimic-response": "^1.0.0" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/code-point-at": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/code-point-at/-/code-point-at-1.1.0.tgz", + "integrity": "sha512-RpAVKQA5T63xEj6/giIbUEtZwJ4UFIc3ZtvEkiaUERylqe8xb5IvqcgOurZLahv93CLKfxcw5YI+DZcUBRyLXA==", + "dev": true, + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/color-convert": { + "version": "1.9.3", + "resolved": "https://registry.npmjs.org/color-convert/-/color-convert-1.9.3.tgz", + "integrity": "sha512-QfAUtd+vFdAtFQcC8CCyYt1fYWxSqAiK2cSD6zDB8N3cpsEBAvRxp9zOGg6G/SHHJYAT88/az/IuDGALsNVbGg==", + "dev": true, + "dependencies": { + "color-name": "1.1.3" + } + }, + "node_modules/color-name": { + "version": "1.1.3", + "resolved": "https://registry.npmjs.org/color-name/-/color-name-1.1.3.tgz", + "integrity": "sha512-72fSenhMw2HZMTVHeCA9KCmpEIbzWiQsjN+BHcBbS9vr1mtt+vJjPdksIBNUmKAW8TFUDPJK5SUU3QhE9NEXDw==", + "dev": true + }, + "node_modules/colors": { + "version": "1.4.0", + "resolved": "https://registry.npmjs.org/colors/-/colors-1.4.0.tgz", + "integrity": "sha512-a+UqTh4kgZg/SlGvfbzDHpgRu7AAQOmmqRHJnxhRZICKFUT91brVhNNt58CMWU9PsBbv3PDCZUHbVxuDiH2mtA==", + "dev": true, + "engines": { + "node": ">=0.1.90" + } + }, + "node_modules/combined-stream": { + "version": "1.0.8", + "resolved": "https://registry.npmjs.org/combined-stream/-/combined-stream-1.0.8.tgz", + "integrity": "sha512-FQN4MRfuJeHf7cBbBMJFXhKSDq+2kAArBlmRBvcvFE5BB1HZKXtSFASDhdlz9zOYwxh8lDdnvmMOe/+5cdoEdg==", + "dev": true, + "dependencies": { + "delayed-stream": "~1.0.0" + }, + "engines": { + "node": ">= 0.8" + } + }, + "node_modules/command-exists": { + "version": "1.2.9", + "resolved": "https://registry.npmjs.org/command-exists/-/command-exists-1.2.9.tgz", + "integrity": "sha512-LTQ/SGc+s0Xc0Fu5WaKnR0YiygZkm9eKFvyS+fRsU7/ZWFF8ykFM6Pc9aCVf1+xasOOZpO3BAVgVrKvsqKHV7w==", + "dev": true + }, + "node_modules/commander": { + "version": "10.0.1", + "resolved": "https://registry.npmjs.org/commander/-/commander-10.0.1.tgz", + "integrity": "sha512-y4Mg2tXshplEbSGzx7amzPwKKOCGuoSRP/CjEdwwk0FOGlUbq6lKuoyDZTNZkmxHdJtp54hdfY/JUrdL7Xfdug==", + "dev": true, + "engines": { + "node": ">=14" + } + }, + "node_modules/compare-versions": { + "version": "5.0.3", + "resolved": "https://registry.npmjs.org/compare-versions/-/compare-versions-5.0.3.tgz", + "integrity": "sha512-4UZlZP8Z99MGEY+Ovg/uJxJuvoXuN4M6B3hKaiackiHrgzQFEe3diJi1mf1PNHbFujM7FvLrK2bpgIaImbtZ1A==", + "dev": true + }, + "node_modules/concat-map": { + "version": "0.0.1", + "resolved": "https://registry.npmjs.org/concat-map/-/concat-map-0.0.1.tgz", + "integrity": "sha512-/Srv4dswyQNBfohGpz9o6Yb3Gz3SrUDqBH5rTuhGR7ahtlbYKnVxw2bCFMRljaA7EXHaXZ8wsHdodFvbkhKmqg==", + "dev": true + }, + "node_modules/concat-stream": { + "version": "1.6.2", + "resolved": "https://registry.npmjs.org/concat-stream/-/concat-stream-1.6.2.tgz", + "integrity": "sha512-27HBghJxjiZtIk3Ycvn/4kbJk/1uZuJFfuPEns6LaEvpvG1f0hTea8lilrouyo9mVc2GWdcEZ8OLoGmSADlrCw==", + "dev": true, + "engines": [ + "node >= 0.8" + ], + "dependencies": { + "buffer-from": "^1.0.0", + "inherits": "^2.0.3", + "readable-stream": "^2.2.2", + "typedarray": "^0.0.6" + } + }, + "node_modules/concat-stream/node_modules/readable-stream": { + "version": "2.3.8", + "resolved": "https://registry.npmjs.org/readable-stream/-/readable-stream-2.3.8.tgz", + "integrity": "sha512-8p0AUk4XODgIewSi0l8Epjs+EVnWiK7NoDIEGU0HhE7+ZyY8D1IMY7odu5lRrFXGg71L15KG8QrPmum45RTtdA==", + "dev": true, + "dependencies": { + "core-util-is": "~1.0.0", + "inherits": "~2.0.3", + "isarray": "~1.0.0", + "process-nextick-args": "~2.0.0", + "safe-buffer": "~5.1.1", + "string_decoder": "~1.1.1", + "util-deprecate": "~1.0.1" + } + }, + "node_modules/concat-stream/node_modules/safe-buffer": { + "version": "5.1.2", + "resolved": "https://registry.npmjs.org/safe-buffer/-/safe-buffer-5.1.2.tgz", + "integrity": "sha512-Gd2UZBJDkXlY7GbJxfsE8/nvKkUEU1G38c1siN6QP6a9PT9MmHB8GnpscSmMJSoF8LOIrt8ud/wPtojys4G6+g==", + "dev": true + }, + "node_modules/concat-stream/node_modules/string_decoder": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/string_decoder/-/string_decoder-1.1.1.tgz", + "integrity": "sha512-n/ShnvDi6FHbbVfviro+WojiFzv+s8MPMHBczVePfUpDJLwoLT0ht1l4YwBCbi8pJAveEEdnkHyPyTP/mzRfwg==", + "dev": true, + "dependencies": { + "safe-buffer": "~5.1.0" + } + }, + "node_modules/constant-case": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/constant-case/-/constant-case-2.0.0.tgz", + "integrity": "sha512-eS0N9WwmjTqrOmR3o83F5vW8Z+9R1HnVz3xmzT2PMFug9ly+Au/fxRWlEBSb6LcZwspSsEn9Xs1uw9YgzAg1EQ==", + "dev": true, + "dependencies": { + "snake-case": "^2.1.0", + "upper-case": "^1.1.1" + } + }, + "node_modules/content-disposition": { + "version": "0.5.4", + "resolved": "https://registry.npmjs.org/content-disposition/-/content-disposition-0.5.4.tgz", + "integrity": "sha512-FveZTNuGw04cxlAiWbzi6zTAL/lhehaWbTtgluJh4/E95DqMwTmha3KZN1aAWA8cFIhHzMZUvLevkw5Rqk+tSQ==", + "dev": true, + "dependencies": { + "safe-buffer": "5.2.1" + }, + "engines": { + "node": ">= 0.6" + } + }, + "node_modules/content-hash": { + "version": "2.5.2", + "resolved": "https://registry.npmjs.org/content-hash/-/content-hash-2.5.2.tgz", + "integrity": "sha512-FvIQKy0S1JaWV10sMsA7TRx8bpU+pqPkhbsfvOJAdjRXvYxEckAwQWGwtRjiaJfh+E0DvcWUGqcdjwMGFjsSdw==", + "dev": true, + "dependencies": { + "cids": "^0.7.1", + "multicodec": "^0.5.5", + "multihashes": "^0.4.15" + } + }, + "node_modules/content-type": { + "version": "1.0.5", + "resolved": "https://registry.npmjs.org/content-type/-/content-type-1.0.5.tgz", + "integrity": "sha512-nTjqfcBFEipKdXCv4YDQWCfmcLZKm81ldF0pAopTvyrFGVbcR6P/VAAd5G7N+0tTr8QqiU0tFadD6FK4NtJwOA==", + "dev": true, + "engines": { + "node": ">= 0.6" + } + }, + "node_modules/cookie": { + "version": "0.4.2", + "resolved": "https://registry.npmjs.org/cookie/-/cookie-0.4.2.tgz", + "integrity": "sha512-aSWTXFzaKWkvHO1Ny/s+ePFpvKsPnjc551iI41v3ny/ow6tBG5Vd+FuqGNhh1LxOmVzOlGUriIlOaokOvhaStA==", + "dev": true, + "engines": { + "node": ">= 0.6" + } + }, + "node_modules/cookie-signature": { + "version": "1.0.6", + "resolved": "https://registry.npmjs.org/cookie-signature/-/cookie-signature-1.0.6.tgz", + "integrity": "sha512-QADzlaHc8icV8I7vbaJXJwod9HWYp8uCqf1xa4OfNu1T7JVxQIrUgOWtHdNDtPiywmFbiS12VjotIXLrKM3orQ==", + "dev": true + }, + "node_modules/core-util-is": { + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/core-util-is/-/core-util-is-1.0.2.tgz", + "integrity": "sha512-3lqz5YjWTYnW6dlDa5TLaTCcShfar1e40rmcJVwCBJC6mWlFuj0eCHIElmG1g5kyuJ/GD+8Wn4FFCcz4gJPfaQ==", + "dev": true + }, + "node_modules/cors": { + "version": "2.8.5", + "resolved": "https://registry.npmjs.org/cors/-/cors-2.8.5.tgz", + "integrity": "sha512-KIHbLJqu73RGr/hnbrO9uBeixNGuvSQjul/jdFvS/KFSIH1hWVd1ng7zOHx+YrEfInLG7q4n6GHQ9cDtxv/P6g==", + "dev": true, + "dependencies": { + "object-assign": "^4", + "vary": "^1" + }, + "engines": { + "node": ">= 0.10" + } + }, + "node_modules/cosmiconfig": { + "version": "8.2.0", + "resolved": "https://registry.npmjs.org/cosmiconfig/-/cosmiconfig-8.2.0.tgz", + "integrity": "sha512-3rTMnFJA1tCOPwRxtgF4wd7Ab2qvDbL8jX+3smjIbS4HlZBagTlpERbdN7iAbWlrfxE3M8c27kTwTawQ7st+OQ==", + "dev": true, + "dependencies": { + "import-fresh": "^3.2.1", + "js-yaml": "^4.1.0", + "parse-json": "^5.0.0", + "path-type": "^4.0.0" + }, + "engines": { + "node": ">=14" + }, + "funding": { + "url": "https://github.com/sponsors/d-fischer" + } + }, + "node_modules/cosmiconfig/node_modules/argparse": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/argparse/-/argparse-2.0.1.tgz", + "integrity": "sha512-8+9WqebbFzpX9OR+Wa6O29asIogeRMzcGtAINdpMHHyAg10f05aSFVBbcEqGf/PXw1EjAZ+q2/bEBg3DvurK3Q==", + "dev": true + }, + "node_modules/cosmiconfig/node_modules/js-yaml": { + "version": "4.1.0", + "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-4.1.0.tgz", + "integrity": "sha512-wpxZs9NoxZaJESJGIZTyDEaYpl0FKSA+FB9aJiyemKhMwkxQg63h4T1KJgUGHpTqPDNRcmmYLugrRjJlBtWvRA==", + "dev": true, + "dependencies": { + "argparse": "^2.0.1" + }, + "bin": { + "js-yaml": "bin/js-yaml.js" + } + }, + "node_modules/crc-32": { + "version": "1.2.2", + "resolved": "https://registry.npmjs.org/crc-32/-/crc-32-1.2.2.tgz", + "integrity": "sha512-ROmzCKrTnOwybPcJApAA6WBWij23HVfGVNKqqrZpuyZOHqK2CwHSvpGuyt/UNNvaIjEd8X5IFGp4Mh+Ie1IHJQ==", + "dev": true, + "bin": { + "crc32": "bin/crc32.njs" + }, + "engines": { + "node": ">=0.8" + } + }, + "node_modules/create-hash": { + "version": "1.2.0", + "resolved": "https://registry.npmjs.org/create-hash/-/create-hash-1.2.0.tgz", + "integrity": "sha512-z00bCGNHDG8mHAkP7CtT1qVu+bFQUPjYq/4Iv3C3kWjTFV10zIjfSoeqXo9Asws8gwSHDGj/hl2u4OGIjapeCg==", + "dev": true, + "dependencies": { + "cipher-base": "^1.0.1", + "inherits": "^2.0.1", + "md5.js": "^1.3.4", + "ripemd160": "^2.0.1", + "sha.js": "^2.4.0" + } + }, + "node_modules/create-hmac": { + "version": "1.1.7", + "resolved": "https://registry.npmjs.org/create-hmac/-/create-hmac-1.1.7.tgz", + "integrity": "sha512-MJG9liiZ+ogc4TzUwuvbER1JRdgvUFSB5+VR/g5h82fGaIRWMWddtKBHi7/sVhfjQZ6SehlyhvQYrcYkaUIpLg==", + "dev": true, + "dependencies": { + "cipher-base": "^1.0.3", + "create-hash": "^1.1.0", + "inherits": "^2.0.1", + "ripemd160": "^2.0.0", + "safe-buffer": "^5.0.1", + "sha.js": "^2.4.8" + } + }, + "node_modules/cross-fetch": { + "version": "3.1.8", + "resolved": "https://registry.npmjs.org/cross-fetch/-/cross-fetch-3.1.8.tgz", + "integrity": "sha512-cvA+JwZoU0Xq+h6WkMvAUqPEYy92Obet6UdKLfW60qn99ftItKjB5T+BkyWOFWe2pUyfQ+IJHmpOTznqk1M6Kg==", + "dev": true, + "dependencies": { + "node-fetch": "^2.6.12" + } + }, + "node_modules/cross-spawn": { + "version": "7.0.3", + "resolved": "https://registry.npmjs.org/cross-spawn/-/cross-spawn-7.0.3.tgz", + "integrity": "sha512-iRDPJKUPVEND7dHPO8rkbOnPpyDygcDFtWjpeWNCgy8WP2rXcxXL8TskReQl6OrB2G7+UJrags1q15Fudc7G6w==", + "dev": true, + "dependencies": { + "path-key": "^3.1.0", + "shebang-command": "^2.0.0", + "which": "^2.0.1" + }, + "engines": { + "node": ">= 8" + } + }, + "node_modules/crypt": { + "version": "0.0.2", + "resolved": "https://registry.npmjs.org/crypt/-/crypt-0.0.2.tgz", + "integrity": "sha512-mCxBlsHFYh9C+HVpiEacem8FEBnMXgU9gy4zmNC+SXAZNB/1idgp/aulFJ4FgCi7GPEVbfyng092GqL2k2rmow==", + "dev": true, + "engines": { + "node": "*" + } + }, + "node_modules/crypto-addr-codec": { + "version": "0.1.7", + "resolved": "https://registry.npmjs.org/crypto-addr-codec/-/crypto-addr-codec-0.1.7.tgz", + "integrity": "sha512-X4hzfBzNhy4mAc3UpiXEC/L0jo5E8wAa9unsnA8nNXYzXjCcGk83hfC5avJWCSGT8V91xMnAS9AKMHmjw5+XCg==", + "dev": true, + "dependencies": { + "base-x": "^3.0.8", + "big-integer": "1.6.36", + "blakejs": "^1.1.0", + "bs58": "^4.0.1", + "ripemd160-min": "0.0.6", + "safe-buffer": "^5.2.0", + "sha3": "^2.1.1" + } + }, + "node_modules/crypto-js": { + "version": "3.3.0", + "resolved": "https://registry.npmjs.org/crypto-js/-/crypto-js-3.3.0.tgz", + "integrity": "sha512-DIT51nX0dCfKltpRiXV+/TVZq+Qq2NgF4644+K7Ttnla7zEzqc+kjJyiB96BHNyUTBxyjzRcZYpUdZa+QAqi6Q==", + "dev": true + }, + "node_modules/css-select": { + "version": "5.1.0", + "resolved": "https://registry.npmjs.org/css-select/-/css-select-5.1.0.tgz", + "integrity": "sha512-nwoRF1rvRRnnCqqY7updORDsuqKzqYJ28+oSMaJMMgOauh3fvwHqMS7EZpIPqK8GL+g9mKxF1vP/ZjSeNjEVHg==", + "dev": true, + "dependencies": { + "boolbase": "^1.0.0", + "css-what": "^6.1.0", + "domhandler": "^5.0.2", + "domutils": "^3.0.1", + "nth-check": "^2.0.1" + }, + "funding": { + "url": "https://github.com/sponsors/fb55" + } + }, + "node_modules/css-what": { + "version": "6.1.0", + "resolved": "https://registry.npmjs.org/css-what/-/css-what-6.1.0.tgz", + "integrity": "sha512-HTUrgRJ7r4dsZKU6GjmpfRK1O76h97Z8MfS1G0FozR+oF2kG6Vfe8JE6zwrkbxigziPHinCJ+gCPjA9EaBDtRw==", + "dev": true, + "engines": { + "node": ">= 6" + }, + "funding": { + "url": "https://github.com/sponsors/fb55" + } + }, + "node_modules/csv": { + "version": "5.5.3", + "resolved": "https://registry.npmjs.org/csv/-/csv-5.5.3.tgz", + "integrity": "sha512-QTaY0XjjhTQOdguARF0lGKm5/mEq9PD9/VhZZegHDIBq2tQwgNpHc3dneD4mGo2iJs+fTKv5Bp0fZ+BRuY3Z0g==", + "dev": true, + "dependencies": { + "csv-generate": "^3.4.3", + "csv-parse": "^4.16.3", + "csv-stringify": "^5.6.5", + "stream-transform": "^2.1.3" + }, + "engines": { + "node": ">= 0.1.90" + } + }, + "node_modules/csv-generate": { + "version": "3.4.3", + "resolved": "https://registry.npmjs.org/csv-generate/-/csv-generate-3.4.3.tgz", + "integrity": "sha512-w/T+rqR0vwvHqWs/1ZyMDWtHHSJaN06klRqJXBEpDJaM/+dZkso0OKh1VcuuYvK3XM53KysVNq8Ko/epCK8wOw==", + "dev": true + }, + "node_modules/csv-parse": { + "version": "4.16.3", + "resolved": "https://registry.npmjs.org/csv-parse/-/csv-parse-4.16.3.tgz", + "integrity": "sha512-cO1I/zmz4w2dcKHVvpCr7JVRu8/FymG5OEpmvsZYlccYolPBLoVGKUHgNoc4ZGkFeFlWGEDmMyBM+TTqRdW/wg==", + "dev": true + }, + "node_modules/csv-stringify": { + "version": "5.6.5", + "resolved": "https://registry.npmjs.org/csv-stringify/-/csv-stringify-5.6.5.tgz", + "integrity": "sha512-PjiQ659aQ+fUTQqSrd1XEDnOr52jh30RBurfzkscaE2tPaFsDH5wOAHJiw8XAHphRknCwMUE9KRayc4K/NbO8A==", + "dev": true + }, + "node_modules/d": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/d/-/d-1.0.1.tgz", + "integrity": "sha512-m62ShEObQ39CfralilEQRjH6oAMtNCV1xJyEx5LpRYUVN+EviphDgUc/F3hnYbADmkiNs67Y+3ylmlG7Lnu+FA==", + "dev": true, + "dependencies": { + "es5-ext": "^0.10.50", + "type": "^1.0.1" + } + }, + "node_modules/dashdash": { + "version": "1.14.1", + "resolved": "https://registry.npmjs.org/dashdash/-/dashdash-1.14.1.tgz", + "integrity": "sha512-jRFi8UDGo6j+odZiEpjazZaWqEal3w/basFjQHQEwVtZJGDpxbH1MeYluwCS8Xq5wmLJooDlMgvVarmWfGM44g==", + "dev": true, + "dependencies": { + "assert-plus": "^1.0.0" + }, + "engines": { + "node": ">=0.10" + } + }, + "node_modules/dataloader": { + "version": "1.4.0", + "resolved": "https://registry.npmjs.org/dataloader/-/dataloader-1.4.0.tgz", + "integrity": "sha512-68s5jYdlvasItOJnCuI2Q9s4q98g0pCyL3HrcKJu8KNugUl8ahgmZYg38ysLTgQjjXX3H8CJLkAvWrclWfcalw==", + "dev": true + }, + "node_modules/death": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/death/-/death-1.1.0.tgz", + "integrity": "sha512-vsV6S4KVHvTGxbEcij7hkWRv0It+sGGWVOM67dQde/o5Xjnr+KmLjxWJii2uEObIrt1CcM9w0Yaovx+iOlIL+w==", + "dev": true + }, + "node_modules/debug": { + "version": "4.3.4", + "resolved": "https://registry.npmjs.org/debug/-/debug-4.3.4.tgz", + "integrity": "sha512-PRWFHuSU3eDtQJPvnNY7Jcket1j0t5OuOsFzPPzsekD52Zl8qUfFIPEiswXqIvHWGVHOgX+7G/vCNNhehwxfkQ==", + "dev": true, + "dependencies": { + "ms": "2.1.2" + }, + "engines": { + "node": ">=6.0" + }, + "peerDependenciesMeta": { + "supports-color": { + "optional": true + } + } + }, + "node_modules/decamelize": { + "version": "1.2.0", + "resolved": "https://registry.npmjs.org/decamelize/-/decamelize-1.2.0.tgz", + "integrity": "sha512-z2S+W9X73hAUUki+N+9Za2lBlun89zigOyGrsax+KUQ6wKW4ZoWpEYBkGhQjwAjjDCkWxhY0VKEhk8wzY7F5cA==", + "dev": true, + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/decamelize-keys": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/decamelize-keys/-/decamelize-keys-1.1.1.tgz", + "integrity": "sha512-WiPxgEirIV0/eIOMcnFBA3/IJZAZqKnwAwWyvvdi4lsr1WCN22nhdf/3db3DoZcUjTV2SqfzIwNyp6y2xs3nmg==", + "dev": true, + "dependencies": { + "decamelize": "^1.1.0", + "map-obj": "^1.0.0" + }, + "engines": { + "node": ">=0.10.0" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/decamelize-keys/node_modules/map-obj": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/map-obj/-/map-obj-1.0.1.tgz", + "integrity": "sha512-7N/q3lyZ+LVCp7PzuxrJr4KMbBE2hW7BT7YNia330OFxIf4d3r5zVpicP2650l7CPN6RM9zOJRl3NGpqSiw3Eg==", + "dev": true, + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/decode-uri-component": { + "version": "0.2.2", + "resolved": "https://registry.npmjs.org/decode-uri-component/-/decode-uri-component-0.2.2.tgz", + "integrity": "sha512-FqUYQ+8o158GyGTrMFJms9qh3CqTKvAqgqsTnkLI8sKu0028orqBhxNMFkFen0zGyg6epACD32pjVk58ngIErQ==", + "dev": true, + "engines": { + "node": ">=0.10" + } + }, + "node_modules/decompress-response": { + "version": "6.0.0", + "resolved": "https://registry.npmjs.org/decompress-response/-/decompress-response-6.0.0.tgz", + "integrity": "sha512-aW35yZM6Bb/4oJlZncMH2LCoZtJXTRxES17vE3hoRiowU2kWHaJKFkSBDnDR+cm9J+9QhXmREyIfv0pji9ejCQ==", + "dev": true, + "dependencies": { + "mimic-response": "^3.1.0" + }, + "engines": { + "node": ">=10" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/decompress-response/node_modules/mimic-response": { + "version": "3.1.0", + "resolved": "https://registry.npmjs.org/mimic-response/-/mimic-response-3.1.0.tgz", + "integrity": "sha512-z0yWI+4FDrrweS8Zmt4Ej5HdJmky15+L2e6Wgn3+iK5fWzb6T3fhNFq2+MeTRb064c6Wr4N/wv0DzQTjNzHNGQ==", + "dev": true, + "engines": { + "node": ">=10" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/deep-eql": { + "version": "4.1.3", + "resolved": "https://registry.npmjs.org/deep-eql/-/deep-eql-4.1.3.tgz", + "integrity": "sha512-WaEtAOpRA1MQ0eohqZjpGD8zdI0Ovsm8mmFhaDN8dvDZzyoUMcYDnf5Y6iu7HTXxf8JDS23qWa4a+hKCDyOPzw==", + "dev": true, + "dependencies": { + "type-detect": "^4.0.0" + }, + "engines": { + "node": ">=6" + } + }, + "node_modules/deep-is": { + "version": "0.1.4", + "resolved": "https://registry.npmjs.org/deep-is/-/deep-is-0.1.4.tgz", + "integrity": "sha512-oIPzksmTg4/MriiaYGO+okXDT7ztn/w3Eptv/+gSIdMdKsJo0u4CfYNFJPy+4SKMuCqGw2wxnA+URMg3t8a/bQ==", + "dev": true + }, + "node_modules/defaults": { + "version": "1.0.4", + "resolved": "https://registry.npmjs.org/defaults/-/defaults-1.0.4.tgz", + "integrity": "sha512-eFuaLoy/Rxalv2kr+lqMlUnrDWV+3j4pljOIJgLIhI058IQfWJ7vXhyEIHu+HtC738klGALYxOKDO0bQP3tg8A==", + "dev": true, + "dependencies": { + "clone": "^1.0.2" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/defer-to-connect": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/defer-to-connect/-/defer-to-connect-2.0.1.tgz", + "integrity": "sha512-4tvttepXG1VaYGrRibk5EwJd1t4udunSOVMdLSAL6mId1ix438oPwPZMALY41FCijukO1L0twNcGsdzS7dHgDg==", + "dev": true, + "engines": { + "node": ">=10" + } + }, + "node_modules/define-properties": { + "version": "1.2.0", + "resolved": "https://registry.npmjs.org/define-properties/-/define-properties-1.2.0.tgz", + "integrity": "sha512-xvqAVKGfT1+UAvPwKTVw/njhdQ8ZhXK4lI0bCIuCMrp2up9nPnaDftrLtmpTazqd1o+UY4zgzU+avtMbDP+ldA==", + "dev": true, + "dependencies": { + "has-property-descriptors": "^1.0.0", + "object-keys": "^1.1.1" + }, + "engines": { + "node": ">= 0.4" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/delayed-stream": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/delayed-stream/-/delayed-stream-1.0.0.tgz", + "integrity": "sha512-ZySD7Nf91aLB0RxL4KGrKHBXl7Eds1DAmEdcoVawXnLD7SDhpNgtuII2aAkg7a7QS41jxPSZ17p4VdGnMHk3MQ==", + "dev": true, + "engines": { + "node": ">=0.4.0" + } + }, + "node_modules/depd": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/depd/-/depd-2.0.0.tgz", + "integrity": "sha512-g7nH6P6dyDioJogAAGprGpCtVImJhpPk/roCzdb3fIh61/s/nPsfR6onyMwkCAR/OlC3yBC0lESvUoQEAssIrw==", + "dev": true, + "engines": { + "node": ">= 0.8" + } + }, + "node_modules/destroy": { + "version": "1.2.0", + "resolved": "https://registry.npmjs.org/destroy/-/destroy-1.2.0.tgz", + "integrity": "sha512-2sJGJTaXIIaR1w4iJSNoN0hnMY7Gpc/n8D4qSCJw8QqFWXf7cuAgnEHxBpweaVcPevC2l3KpjYCx3NypQQgaJg==", + "dev": true, + "engines": { + "node": ">= 0.8", + "npm": "1.2.8000 || >= 1.4.16" + } + }, + "node_modules/detect-indent": { + "version": "6.1.0", + "resolved": "https://registry.npmjs.org/detect-indent/-/detect-indent-6.1.0.tgz", + "integrity": "sha512-reYkTUJAZb9gUuZ2RvVCNhVHdg62RHnJ7WJl8ftMi4diZ6NWlciOzQN88pUhSELEwflJht4oQDv0F0BMlwaYtA==", + "dev": true, + "engines": { + "node": ">=8" + } + }, + "node_modules/detect-port": { + "version": "1.5.1", + "resolved": "https://registry.npmjs.org/detect-port/-/detect-port-1.5.1.tgz", + "integrity": "sha512-aBzdj76lueB6uUst5iAs7+0H/oOjqI5D16XUWxlWMIMROhcM0rfsNVk93zTngq1dDNpoXRr++Sus7ETAExppAQ==", + "dev": true, + "dependencies": { + "address": "^1.0.1", + "debug": "4" + }, + "bin": { + "detect": "bin/detect-port.js", + "detect-port": "bin/detect-port.js" + } + }, + "node_modules/diff": { + "version": "5.0.0", + "resolved": "https://registry.npmjs.org/diff/-/diff-5.0.0.tgz", + "integrity": "sha512-/VTCrvm5Z0JGty/BWHljh+BAiw3IK+2j87NGMu8Nwc/f48WoDAC395uomO9ZD117ZOBaHmkX1oyLvkVM/aIT3w==", + "dev": true, + "engines": { + "node": ">=0.3.1" + } + }, + "node_modules/difflib": { + "version": "0.2.4", + "resolved": "https://registry.npmjs.org/difflib/-/difflib-0.2.4.tgz", + "integrity": "sha512-9YVwmMb0wQHQNr5J9m6BSj6fk4pfGITGQOOs+D9Fl+INODWFOfvhIU1hNv6GgR1RBoC/9NJcwu77zShxV0kT7w==", + "dev": true, + "dependencies": { + "heap": ">= 0.2.0" + }, + "engines": { + "node": "*" + } + }, + "node_modules/dir-glob": { + "version": "3.0.1", + "resolved": "https://registry.npmjs.org/dir-glob/-/dir-glob-3.0.1.tgz", + "integrity": "sha512-WkrWp9GR4KXfKGYzOLmTuGVi1UWFfws377n9cc55/tb6DuqyF6pcQ5AbiHEshaDpY9v6oaSr2XCDidGmMwdzIA==", + "dev": true, + "dependencies": { + "path-type": "^4.0.0" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/doctrine": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/doctrine/-/doctrine-3.0.0.tgz", + "integrity": "sha512-yS+Q5i3hBf7GBkd4KG8a7eBNNWNGLTaEwwYWUijIYM7zrlYDM0BFXHjjPWlWZ1Rg7UaddZeIDmi9jF3HmqiQ2w==", + "dev": true, + "dependencies": { + "esutils": "^2.0.2" + }, + "engines": { + "node": ">=6.0.0" + } + }, + "node_modules/dom-serializer": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/dom-serializer/-/dom-serializer-2.0.0.tgz", + "integrity": "sha512-wIkAryiqt/nV5EQKqQpo3SToSOV9J0DnbJqwK7Wv/Trc92zIAYZ4FlMu+JPFW1DfGFt81ZTCGgDEabffXeLyJg==", + "dev": true, + "dependencies": { + "domelementtype": "^2.3.0", + "domhandler": "^5.0.2", + "entities": "^4.2.0" + }, + "funding": { + "url": "https://github.com/cheeriojs/dom-serializer?sponsor=1" + } + }, + "node_modules/dom-walk": { + "version": "0.1.2", + "resolved": "https://registry.npmjs.org/dom-walk/-/dom-walk-0.1.2.tgz", + "integrity": "sha512-6QvTW9mrGeIegrFXdtQi9pk7O/nSK6lSdXW2eqUspN5LWD7UTji2Fqw5V2YLjBpHEoU9Xl/eUWNpDeZvoyOv2w==", + "dev": true + }, + "node_modules/domelementtype": { + "version": "2.3.0", + "resolved": "https://registry.npmjs.org/domelementtype/-/domelementtype-2.3.0.tgz", + "integrity": "sha512-OLETBj6w0OsagBwdXnPdN0cnMfF9opN69co+7ZrbfPGrdpPVNBUj02spi6B1N7wChLQiPn4CSH/zJvXw56gmHw==", + "dev": true, + "funding": [ + { + "type": "github", + "url": "https://github.com/sponsors/fb55" + } + ] + }, + "node_modules/domhandler": { + "version": "5.0.3", + "resolved": "https://registry.npmjs.org/domhandler/-/domhandler-5.0.3.tgz", + "integrity": "sha512-cgwlv/1iFQiFnU96XXgROh8xTeetsnJiDsTc7TYCLFd9+/WNkIqPTxiM/8pSd8VIrhXGTf1Ny1q1hquVqDJB5w==", + "dev": true, + "dependencies": { + "domelementtype": "^2.3.0" + }, + "engines": { + "node": ">= 4" + }, + "funding": { + "url": "https://github.com/fb55/domhandler?sponsor=1" + } + }, + "node_modules/domutils": { + "version": "3.1.0", + "resolved": "https://registry.npmjs.org/domutils/-/domutils-3.1.0.tgz", + "integrity": "sha512-H78uMmQtI2AhgDJjWeQmHwJJ2bLPD3GMmO7Zja/ZZh84wkm+4ut+IUnUdRa8uCGX88DiVx1j6FRe1XfxEgjEZA==", + "dev": true, + "dependencies": { + "dom-serializer": "^2.0.0", + "domelementtype": "^2.3.0", + "domhandler": "^5.0.3" + }, + "funding": { + "url": "https://github.com/fb55/domutils?sponsor=1" + } + }, + "node_modules/dot-case": { + "version": "2.1.1", + "resolved": "https://registry.npmjs.org/dot-case/-/dot-case-2.1.1.tgz", + "integrity": "sha512-HnM6ZlFqcajLsyudHq7LeeLDr2rFAVYtDv/hV5qchQEidSck8j9OPUsXY9KwJv/lHMtYlX4DjRQqwFYa+0r8Ug==", + "dev": true, + "dependencies": { + "no-case": "^2.2.0" + } + }, + "node_modules/dotenv": { + "version": "8.6.0", + "resolved": "https://registry.npmjs.org/dotenv/-/dotenv-8.6.0.tgz", + "integrity": "sha512-IrPdXQsk2BbzvCBGBOTmmSH5SodmqZNt4ERAZDmW4CT+tL8VtvinqywuANaFu4bOMWki16nqf0e4oC0QIaDr/g==", + "dev": true, + "engines": { + "node": ">=10" + } + }, + "node_modules/ecc-jsbn": { + "version": "0.1.2", + "resolved": "https://registry.npmjs.org/ecc-jsbn/-/ecc-jsbn-0.1.2.tgz", + "integrity": "sha512-eh9O+hwRHNbG4BLTjEl3nw044CkGm5X6LoaCf7LPp7UU8Qrt47JYNi6nPX8xjW97TKGKm1ouctg0QSpZe9qrnw==", + "dev": true, + "dependencies": { + "jsbn": "~0.1.0", + "safer-buffer": "^2.1.0" + } + }, + "node_modules/ee-first": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/ee-first/-/ee-first-1.1.1.tgz", + "integrity": "sha512-WMwm9LhRUo+WUaRN+vRuETqG89IgZphVSNkdFgeb6sS/E4OrDIN7t48CAewSHXc6C8lefD8KKfr5vY61brQlow==", + "dev": true + }, + "node_modules/elliptic": { + "version": "6.5.4", + "resolved": "https://registry.npmjs.org/elliptic/-/elliptic-6.5.4.tgz", + "integrity": "sha512-iLhC6ULemrljPZb+QutR5TQGB+pdW6KGD5RSegS+8sorOZT+rdQFbsQFJgvN3eRqNALqJer4oQ16YvJHlU8hzQ==", + "dev": true, + "dependencies": { + "bn.js": "^4.11.9", + "brorand": "^1.1.0", + "hash.js": "^1.0.0", + "hmac-drbg": "^1.0.1", + "inherits": "^2.0.4", + "minimalistic-assert": "^1.0.1", + "minimalistic-crypto-utils": "^1.0.1" + } + }, + "node_modules/emoji-regex": { + "version": "8.0.0", + "resolved": "https://registry.npmjs.org/emoji-regex/-/emoji-regex-8.0.0.tgz", + "integrity": "sha512-MSjYzcWNOA0ewAHpz0MxpYFvwg6yjy1NG3xteoqz644VCo/RPgnr1/GGt+ic3iJTzQ8Eu3TdM14SawnVUmGE6A==", + "dev": true + }, + "node_modules/encodeurl": { + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/encodeurl/-/encodeurl-1.0.2.tgz", + "integrity": "sha512-TPJXq8JqFaVYm2CWmPvnP2Iyo4ZSM7/QKcSmuMLDObfpH5fi7RUGmd/rTDf+rut/saiDiQEeVTNgAmJEdAOx0w==", + "dev": true, + "engines": { + "node": ">= 0.8" + } + }, + "node_modules/end-of-stream": { + "version": "1.4.4", + "resolved": "https://registry.npmjs.org/end-of-stream/-/end-of-stream-1.4.4.tgz", + "integrity": "sha512-+uw1inIHVPQoaVuHzRyXd21icM+cnt4CzD5rW+NC1wjOUSTOs+Te7FOv7AhN7vS9x/oIyhLP5PR1H+phQAHu5Q==", + "dev": true, + "dependencies": { + "once": "^1.4.0" + } + }, + "node_modules/enquirer": { + "version": "2.3.6", + "resolved": "https://registry.npmjs.org/enquirer/-/enquirer-2.3.6.tgz", + "integrity": "sha512-yjNnPr315/FjS4zIsUxYguYUPP2e1NK4d7E7ZOLiyYCcbFBiTMyID+2wvm2w6+pZ/odMA7cRkjhsPbltwBOrLg==", + "dev": true, + "dependencies": { + "ansi-colors": "^4.1.1" + }, + "engines": { + "node": ">=8.6" + } + }, + "node_modules/entities": { + "version": "4.5.0", + "resolved": "https://registry.npmjs.org/entities/-/entities-4.5.0.tgz", + "integrity": "sha512-V0hjH4dGPh9Ao5p0MoRY6BVqtwCjhz6vI5LT8AJ55H+4g9/4vbHx1I54fS0XuclLhDHArPQCiMjDxjaL8fPxhw==", + "dev": true, + "engines": { + "node": ">=0.12" + }, + "funding": { + "url": "https://github.com/fb55/entities?sponsor=1" + } + }, + "node_modules/env-paths": { + "version": "2.2.1", + "resolved": "https://registry.npmjs.org/env-paths/-/env-paths-2.2.1.tgz", + "integrity": "sha512-+h1lkLKhZMTYjog1VEpJNG7NZJWcuc2DDk/qsqSTRRCOXiLjeQ1d1/udrUGhqMxUgAlwKNZ0cf2uqan5GLuS2A==", + "dev": true, + "engines": { + "node": ">=6" + } + }, + "node_modules/error-ex": { + "version": "1.3.2", + "resolved": "https://registry.npmjs.org/error-ex/-/error-ex-1.3.2.tgz", + "integrity": "sha512-7dFHNmqeFSEt2ZBsCriorKnn3Z2pj+fd9kmI6QoWw4//DL+icEBfc0U7qJCisqrTsKTjw4fNFy2pW9OqStD84g==", + "dev": true, + "dependencies": { + "is-arrayish": "^0.2.1" + } + }, + "node_modules/es-abstract": { + "version": "1.21.2", + "resolved": "https://registry.npmjs.org/es-abstract/-/es-abstract-1.21.2.tgz", + "integrity": "sha512-y/B5POM2iBnIxCiernH1G7rC9qQoM77lLIMQLuob0zhp8C56Po81+2Nj0WFKnd0pNReDTnkYryc+zhOzpEIROg==", + "dev": true, + "dependencies": { + "array-buffer-byte-length": "^1.0.0", + "available-typed-arrays": "^1.0.5", + "call-bind": "^1.0.2", + "es-set-tostringtag": "^2.0.1", + "es-to-primitive": "^1.2.1", + "function.prototype.name": "^1.1.5", + "get-intrinsic": "^1.2.0", + "get-symbol-description": "^1.0.0", + "globalthis": "^1.0.3", + "gopd": "^1.0.1", + "has": "^1.0.3", + "has-property-descriptors": "^1.0.0", + "has-proto": "^1.0.1", + "has-symbols": "^1.0.3", + "internal-slot": "^1.0.5", + "is-array-buffer": "^3.0.2", + "is-callable": "^1.2.7", + "is-negative-zero": "^2.0.2", + "is-regex": "^1.1.4", + "is-shared-array-buffer": "^1.0.2", + "is-string": "^1.0.7", + "is-typed-array": "^1.1.10", + "is-weakref": "^1.0.2", + "object-inspect": "^1.12.3", + "object-keys": "^1.1.1", + "object.assign": "^4.1.4", + "regexp.prototype.flags": "^1.4.3", + "safe-regex-test": "^1.0.0", + "string.prototype.trim": "^1.2.7", + "string.prototype.trimend": "^1.0.6", + "string.prototype.trimstart": "^1.0.6", + "typed-array-length": "^1.0.4", + "unbox-primitive": "^1.0.2", + "which-typed-array": "^1.1.9" + }, + "engines": { + "node": ">= 0.4" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/es-array-method-boxes-properly": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/es-array-method-boxes-properly/-/es-array-method-boxes-properly-1.0.0.tgz", + "integrity": "sha512-wd6JXUmyHmt8T5a2xreUwKcGPq6f1f+WwIJkijUqiGcJz1qqnZgP6XIK+QyIWU5lT7imeNxUll48bziG+TSYcA==", + "dev": true + }, + "node_modules/es-set-tostringtag": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/es-set-tostringtag/-/es-set-tostringtag-2.0.1.tgz", + "integrity": "sha512-g3OMbtlwY3QewlqAiMLI47KywjWZoEytKr8pf6iTC8uJq5bIAH52Z9pnQ8pVL6whrCto53JZDuUIsifGeLorTg==", + "dev": true, + "dependencies": { + "get-intrinsic": "^1.1.3", + "has": "^1.0.3", + "has-tostringtag": "^1.0.0" + }, + "engines": { + "node": ">= 0.4" + } + }, + "node_modules/es-shim-unscopables": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/es-shim-unscopables/-/es-shim-unscopables-1.0.0.tgz", + "integrity": "sha512-Jm6GPcCdC30eMLbZ2x8z2WuRwAws3zTBBKuusffYVUrNj/GVSUAZ+xKMaUpfNDR5IbyNA5LJbaecoUVbmUcB1w==", + "dev": true, + "dependencies": { + "has": "^1.0.3" + } + }, + "node_modules/es-to-primitive": { + "version": "1.2.1", + "resolved": "https://registry.npmjs.org/es-to-primitive/-/es-to-primitive-1.2.1.tgz", + "integrity": "sha512-QCOllgZJtaUo9miYBcLChTUaHNjJF3PYs1VidD7AwiEj1kYxKeQTctLAezAOH5ZKRH0g2IgPn6KwB4IT8iRpvA==", + "dev": true, + "dependencies": { + "is-callable": "^1.1.4", + "is-date-object": "^1.0.1", + "is-symbol": "^1.0.2" + }, + "engines": { + "node": ">= 0.4" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/es5-ext": { + "version": "0.10.62", + "resolved": "https://registry.npmjs.org/es5-ext/-/es5-ext-0.10.62.tgz", + "integrity": "sha512-BHLqn0klhEpnOKSrzn/Xsz2UIW8j+cGmo9JLzr8BiUapV8hPL9+FliFqjwr9ngW7jWdnxv6eO+/LqyhJVqgrjA==", + "dev": true, + "hasInstallScript": true, + "dependencies": { + "es6-iterator": "^2.0.3", + "es6-symbol": "^3.1.3", + "next-tick": "^1.1.0" + }, + "engines": { + "node": ">=0.10" + } + }, + "node_modules/es6-iterator": { + "version": "2.0.3", + "resolved": "https://registry.npmjs.org/es6-iterator/-/es6-iterator-2.0.3.tgz", + "integrity": "sha512-zw4SRzoUkd+cl+ZoE15A9o1oQd920Bb0iOJMQkQhl3jNc03YqVjAhG7scf9C5KWRU/R13Orf588uCC6525o02g==", + "dev": true, + "dependencies": { + "d": "1", + "es5-ext": "^0.10.35", + "es6-symbol": "^3.1.1" + } + }, + "node_modules/es6-promise": { + "version": "4.2.8", + "resolved": "https://registry.npmjs.org/es6-promise/-/es6-promise-4.2.8.tgz", + "integrity": "sha512-HJDGx5daxeIvxdBxvG2cb9g4tEvwIk3i8+nhX0yGrYmZUzbkdg8QbDevheDB8gd0//uPj4c1EQua8Q+MViT0/w==", + "dev": true + }, + "node_modules/es6-symbol": { + "version": "3.1.3", + "resolved": "https://registry.npmjs.org/es6-symbol/-/es6-symbol-3.1.3.tgz", + "integrity": "sha512-NJ6Yn3FuDinBaBRWl/q5X/s4koRHBrgKAu+yGI6JCBeiu3qrcbJhwT2GeR/EXVfylRk8dpQVJoLEFhK+Mu31NA==", + "dev": true, + "dependencies": { + "d": "^1.0.1", + "ext": "^1.1.2" + } + }, + "node_modules/escalade": { + "version": "3.1.1", + "resolved": "https://registry.npmjs.org/escalade/-/escalade-3.1.1.tgz", + "integrity": "sha512-k0er2gUkLf8O0zKJiAhmkTnJlTvINGv7ygDNPbeIsX/TJjGJZHuh9B2UxbsaEkmlEo9MfhrSzmhIlhRlI2GXnw==", + "dev": true, + "engines": { + "node": ">=6" + } + }, + "node_modules/escape-html": { + "version": "1.0.3", + "resolved": "https://registry.npmjs.org/escape-html/-/escape-html-1.0.3.tgz", + "integrity": "sha512-NiSupZ4OeuGwr68lGIeym/ksIZMJodUGOSCZ/FSnTxcrekbvqrgdUxlJOMpijaKZVjAJrWrGs/6Jy8OMuyj9ow==", + "dev": true + }, + "node_modules/escape-string-regexp": { + "version": "1.0.5", + "resolved": "https://registry.npmjs.org/escape-string-regexp/-/escape-string-regexp-1.0.5.tgz", + "integrity": "sha512-vbRorB5FUQWvla16U8R/qgaFIya2qGzwDrNmCZuYKrbdSUMG6I1ZCGQRefkRVhuOkIGVne7BQ35DSfo1qvJqFg==", + "dev": true, + "engines": { + "node": ">=0.8.0" + } + }, + "node_modules/escodegen": { + "version": "1.8.1", + "resolved": "https://registry.npmjs.org/escodegen/-/escodegen-1.8.1.tgz", + "integrity": "sha512-yhi5S+mNTOuRvyW4gWlg5W1byMaQGWWSYHXsuFZ7GBo7tpyOwi2EdzMP/QWxh9hwkD2m+wDVHJsxhRIj+v/b/A==", + "dev": true, + "dependencies": { + "esprima": "^2.7.1", + "estraverse": "^1.9.1", + "esutils": "^2.0.2", + "optionator": "^0.8.1" + }, + "bin": { + "escodegen": "bin/escodegen.js", + "esgenerate": "bin/esgenerate.js" + }, + "engines": { + "node": ">=0.12.0" + }, + "optionalDependencies": { + "source-map": "~0.2.0" + } + }, + "node_modules/escodegen/node_modules/esprima": { + "version": "2.7.3", + "resolved": "https://registry.npmjs.org/esprima/-/esprima-2.7.3.tgz", + "integrity": "sha512-OarPfz0lFCiW4/AV2Oy1Rp9qu0iusTKqykwTspGCZtPxmF81JR4MmIebvF1F9+UOKth2ZubLQ4XGGaU+hSn99A==", + "dev": true, + "bin": { + "esparse": "bin/esparse.js", + "esvalidate": "bin/esvalidate.js" + }, + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/escodegen/node_modules/estraverse": { + "version": "1.9.3", + "resolved": "https://registry.npmjs.org/estraverse/-/estraverse-1.9.3.tgz", + "integrity": "sha512-25w1fMXQrGdoquWnScXZGckOv+Wes+JDnuN/+7ex3SauFRS72r2lFDec0EKPt2YD1wUJ/IrfEex+9yp4hfSOJA==", + "dev": true, + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/escodegen/node_modules/levn": { + "version": "0.3.0", + "resolved": "https://registry.npmjs.org/levn/-/levn-0.3.0.tgz", + "integrity": "sha512-0OO4y2iOHix2W6ujICbKIaEQXvFQHue65vUG3pb5EUomzPI90z9hsA1VsO/dbIIpC53J8gxM9Q4Oho0jrCM/yA==", + "dev": true, + "dependencies": { + "prelude-ls": "~1.1.2", + "type-check": "~0.3.2" + }, + "engines": { + "node": ">= 0.8.0" + } + }, + "node_modules/escodegen/node_modules/optionator": { + "version": "0.8.3", + "resolved": "https://registry.npmjs.org/optionator/-/optionator-0.8.3.tgz", + "integrity": "sha512-+IW9pACdk3XWmmTXG8m3upGUJst5XRGzxMRjXzAuJ1XnIFNvfhjjIuYkDvysnPQ7qzqVzLt78BCruntqRhWQbA==", + "dev": true, + "dependencies": { + "deep-is": "~0.1.3", + "fast-levenshtein": "~2.0.6", + "levn": "~0.3.0", + "prelude-ls": "~1.1.2", + "type-check": "~0.3.2", + "word-wrap": "~1.2.3" + }, + "engines": { + "node": ">= 0.8.0" + } + }, + "node_modules/escodegen/node_modules/prelude-ls": { + "version": "1.1.2", + "resolved": "https://registry.npmjs.org/prelude-ls/-/prelude-ls-1.1.2.tgz", + "integrity": "sha512-ESF23V4SKG6lVSGZgYNpbsiaAkdab6ZgOxe52p7+Kid3W3u3bxR4Vfd/o21dmN7jSt0IwgZ4v5MUd26FEtXE9w==", + "dev": true, + "engines": { + "node": ">= 0.8.0" + } + }, + "node_modules/escodegen/node_modules/type-check": { + "version": "0.3.2", + "resolved": "https://registry.npmjs.org/type-check/-/type-check-0.3.2.tgz", + "integrity": "sha512-ZCmOJdvOWDBYJlzAoFkC+Q0+bUyEOS1ltgp1MGU03fqHG+dbi9tBFU2Rd9QKiDZFAYrhPh2JUf7rZRIuHRKtOg==", + "dev": true, + "dependencies": { + "prelude-ls": "~1.1.2" + }, + "engines": { + "node": ">= 0.8.0" + } + }, + "node_modules/eslint": { + "version": "8.44.0", + "resolved": "https://registry.npmjs.org/eslint/-/eslint-8.44.0.tgz", + "integrity": "sha512-0wpHoUbDUHgNCyvFB5aXLiQVfK9B0at6gUvzy83k4kAsQ/u769TQDX6iKC+aO4upIHO9WSaA3QoXYQDHbNwf1A==", + "dev": true, + "dependencies": { + "@eslint-community/eslint-utils": "^4.2.0", + "@eslint-community/regexpp": "^4.4.0", + "@eslint/eslintrc": "^2.1.0", + "@eslint/js": "8.44.0", + "@humanwhocodes/config-array": "^0.11.10", + "@humanwhocodes/module-importer": "^1.0.1", + "@nodelib/fs.walk": "^1.2.8", + "ajv": "^6.10.0", + "chalk": "^4.0.0", + "cross-spawn": "^7.0.2", + "debug": "^4.3.2", + "doctrine": "^3.0.0", + "escape-string-regexp": "^4.0.0", + "eslint-scope": "^7.2.0", + "eslint-visitor-keys": "^3.4.1", + "espree": "^9.6.0", + "esquery": "^1.4.2", + "esutils": "^2.0.2", + "fast-deep-equal": "^3.1.3", + "file-entry-cache": "^6.0.1", + "find-up": "^5.0.0", + "glob-parent": "^6.0.2", + "globals": "^13.19.0", + "graphemer": "^1.4.0", + "ignore": "^5.2.0", + "import-fresh": "^3.0.0", + "imurmurhash": "^0.1.4", + "is-glob": "^4.0.0", + "is-path-inside": "^3.0.3", + "js-yaml": "^4.1.0", + "json-stable-stringify-without-jsonify": "^1.0.1", + "levn": "^0.4.1", + "lodash.merge": "^4.6.2", + "minimatch": "^3.1.2", + "natural-compare": "^1.4.0", + "optionator": "^0.9.3", + "strip-ansi": "^6.0.1", + "strip-json-comments": "^3.1.0", + "text-table": "^0.2.0" + }, + "bin": { + "eslint": "bin/eslint.js" + }, + "engines": { + "node": "^12.22.0 || ^14.17.0 || >=16.0.0" + }, + "funding": { + "url": "https://opencollective.com/eslint" + } + }, + "node_modules/eslint-config-prettier": { + "version": "9.0.0", + "resolved": "https://registry.npmjs.org/eslint-config-prettier/-/eslint-config-prettier-9.0.0.tgz", + "integrity": "sha512-IcJsTkJae2S35pRsRAwoCE+925rJJStOdkKnLVgtE+tEpqU0EVVM7OqrwxqgptKdX29NUwC82I5pXsGFIgSevw==", + "dev": true, + "bin": { + "eslint-config-prettier": "bin/cli.js" + }, + "peerDependencies": { + "eslint": ">=7.0.0" + } + }, + "node_modules/eslint-scope": { + "version": "7.2.0", + "resolved": "https://registry.npmjs.org/eslint-scope/-/eslint-scope-7.2.0.tgz", + "integrity": "sha512-DYj5deGlHBfMt15J7rdtyKNq/Nqlv5KfU4iodrQ019XESsRnwXH9KAE0y3cwtUHDo2ob7CypAnCqefh6vioWRw==", + "dev": true, + "dependencies": { + "esrecurse": "^4.3.0", + "estraverse": "^5.2.0" + }, + "engines": { + "node": "^12.22.0 || ^14.17.0 || >=16.0.0" + }, + "funding": { + "url": "https://opencollective.com/eslint" + } + }, + "node_modules/eslint-visitor-keys": { + "version": "3.4.1", + "resolved": "https://registry.npmjs.org/eslint-visitor-keys/-/eslint-visitor-keys-3.4.1.tgz", + "integrity": "sha512-pZnmmLwYzf+kWaM/Qgrvpen51upAktaaiI01nsJD/Yr3lMOdNtq0cxkrrg16w64VtisN6okbs7Q8AfGqj4c9fA==", + "dev": true, + "engines": { + "node": "^12.22.0 || ^14.17.0 || >=16.0.0" + }, + "funding": { + "url": "https://opencollective.com/eslint" + } + }, + "node_modules/eslint/node_modules/ansi-regex": { + "version": "5.0.1", + "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-5.0.1.tgz", + "integrity": "sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ==", + "dev": true, + "engines": { + "node": ">=8" + } + }, + "node_modules/eslint/node_modules/ansi-styles": { + "version": "4.3.0", + "resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-4.3.0.tgz", + "integrity": "sha512-zbB9rCJAT1rbjiVDb2hqKFHNYLxgtk8NURxZ3IZwD3F6NtxbXZQCnnSi1Lkx+IDohdPlFp222wVALIheZJQSEg==", + "dev": true, + "dependencies": { + "color-convert": "^2.0.1" + }, + "engines": { + "node": ">=8" + }, + "funding": { + "url": "https://github.com/chalk/ansi-styles?sponsor=1" + } + }, + "node_modules/eslint/node_modules/argparse": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/argparse/-/argparse-2.0.1.tgz", + "integrity": "sha512-8+9WqebbFzpX9OR+Wa6O29asIogeRMzcGtAINdpMHHyAg10f05aSFVBbcEqGf/PXw1EjAZ+q2/bEBg3DvurK3Q==", + "dev": true + }, + "node_modules/eslint/node_modules/chalk": { + "version": "4.1.2", + "resolved": "https://registry.npmjs.org/chalk/-/chalk-4.1.2.tgz", + "integrity": "sha512-oKnbhFyRIXpUuez8iBMmyEa4nbj4IOQyuhc/wy9kY7/WVPcwIO9VA668Pu8RkO7+0G76SLROeyw9CpQ061i4mA==", + "dev": true, + "dependencies": { + "ansi-styles": "^4.1.0", + "supports-color": "^7.1.0" + }, + "engines": { + "node": ">=10" + }, + "funding": { + "url": "https://github.com/chalk/chalk?sponsor=1" + } + }, + "node_modules/eslint/node_modules/color-convert": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/color-convert/-/color-convert-2.0.1.tgz", + "integrity": "sha512-RRECPsj7iu/xb5oKYcsFHSppFNnsj/52OVTRKb4zP5onXwVF3zVmmToNcOfGC+CRDpfK/U584fMg38ZHCaElKQ==", + "dev": true, + "dependencies": { + "color-name": "~1.1.4" + }, + "engines": { + "node": ">=7.0.0" + } + }, + "node_modules/eslint/node_modules/color-name": { + "version": "1.1.4", + "resolved": "https://registry.npmjs.org/color-name/-/color-name-1.1.4.tgz", + "integrity": "sha512-dOy+3AuW3a2wNbZHIuMZpTcgjGuLU/uBL/ubcZF9OXbDo8ff4O8yVp5Bf0efS8uEoYo5q4Fx7dY9OgQGXgAsQA==", + "dev": true + }, + "node_modules/eslint/node_modules/escape-string-regexp": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/escape-string-regexp/-/escape-string-regexp-4.0.0.tgz", + "integrity": "sha512-TtpcNJ3XAzx3Gq8sWRzJaVajRs0uVxA2YAkdb1jm2YkPz4G6egUFAyA3n5vtEIZefPk5Wa4UXbKuS5fKkJWdgA==", + "dev": true, + "engines": { + "node": ">=10" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/eslint/node_modules/find-up": { + "version": "5.0.0", + "resolved": "https://registry.npmjs.org/find-up/-/find-up-5.0.0.tgz", + "integrity": "sha512-78/PXT1wlLLDgTzDs7sjq9hzz0vXD+zn+7wypEe4fXQxCmdmqfGsEPQxmiCSQI3ajFV91bVSsvNtrJRiW6nGng==", + "dev": true, + "dependencies": { + "locate-path": "^6.0.0", + "path-exists": "^4.0.0" + }, + "engines": { + "node": ">=10" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/eslint/node_modules/glob-parent": { + "version": "6.0.2", + "resolved": "https://registry.npmjs.org/glob-parent/-/glob-parent-6.0.2.tgz", + "integrity": "sha512-XxwI8EOhVQgWp6iDL+3b0r86f4d6AX6zSU55HfB4ydCEuXLXc5FcYeOu+nnGftS4TEju/11rt4KJPTMgbfmv4A==", + "dev": true, + "dependencies": { + "is-glob": "^4.0.3" + }, + "engines": { + "node": ">=10.13.0" + } + }, + "node_modules/eslint/node_modules/has-flag": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/has-flag/-/has-flag-4.0.0.tgz", + "integrity": "sha512-EykJT/Q1KjTWctppgIAgfSO0tKVuZUjhgMr17kqTumMl6Afv3EISleU7qZUzoXDFTAHTDC4NOoG/ZxU3EvlMPQ==", + "dev": true, + "engines": { + "node": ">=8" + } + }, + "node_modules/eslint/node_modules/js-yaml": { + "version": "4.1.0", + "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-4.1.0.tgz", + "integrity": "sha512-wpxZs9NoxZaJESJGIZTyDEaYpl0FKSA+FB9aJiyemKhMwkxQg63h4T1KJgUGHpTqPDNRcmmYLugrRjJlBtWvRA==", + "dev": true, + "dependencies": { + "argparse": "^2.0.1" + }, + "bin": { + "js-yaml": "bin/js-yaml.js" + } + }, + "node_modules/eslint/node_modules/locate-path": { + "version": "6.0.0", + "resolved": "https://registry.npmjs.org/locate-path/-/locate-path-6.0.0.tgz", + "integrity": "sha512-iPZK6eYjbxRu3uB4/WZ3EsEIMJFMqAoopl3R+zuq0UjcAm/MO6KCweDgPfP3elTztoKP3KtnVHxTn2NHBSDVUw==", + "dev": true, + "dependencies": { + "p-locate": "^5.0.0" + }, + "engines": { + "node": ">=10" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/eslint/node_modules/p-locate": { + "version": "5.0.0", + "resolved": "https://registry.npmjs.org/p-locate/-/p-locate-5.0.0.tgz", + "integrity": "sha512-LaNjtRWUBY++zB5nE/NwcaoMylSPk+S+ZHNB1TzdbMJMny6dynpAGt7X/tl/QYq3TIeE6nxHppbo2LGymrG5Pw==", + "dev": true, + "dependencies": { + "p-limit": "^3.0.2" + }, + "engines": { + "node": ">=10" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/eslint/node_modules/strip-ansi": { + "version": "6.0.1", + "resolved": "https://registry.npmjs.org/strip-ansi/-/strip-ansi-6.0.1.tgz", + "integrity": "sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A==", + "dev": true, + "dependencies": { + "ansi-regex": "^5.0.1" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/eslint/node_modules/supports-color": { + "version": "7.2.0", + "resolved": "https://registry.npmjs.org/supports-color/-/supports-color-7.2.0.tgz", + "integrity": "sha512-qpCAvRl9stuOHveKsn7HncJRvv501qIacKzQlO/+Lwxc9+0q2wLyv4Dfvt80/DPn2pqOBsJdDiogXGR9+OvwRw==", + "dev": true, + "dependencies": { + "has-flag": "^4.0.0" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/espree": { + "version": "9.6.0", + "resolved": "https://registry.npmjs.org/espree/-/espree-9.6.0.tgz", + "integrity": "sha512-1FH/IiruXZ84tpUlm0aCUEwMl2Ho5ilqVh0VvQXw+byAz/4SAciyHLlfmL5WYqsvD38oymdUwBss0LtK8m4s/A==", + "dev": true, + "dependencies": { + "acorn": "^8.9.0", + "acorn-jsx": "^5.3.2", + "eslint-visitor-keys": "^3.4.1" + }, + "engines": { + "node": "^12.22.0 || ^14.17.0 || >=16.0.0" + }, + "funding": { + "url": "https://opencollective.com/eslint" + } + }, + "node_modules/esprima": { + "version": "4.0.1", + "resolved": "https://registry.npmjs.org/esprima/-/esprima-4.0.1.tgz", + "integrity": "sha512-eGuFFw7Upda+g4p+QHvnW0RyTX/SVeJBDM/gCtMARO0cLuT2HcEKnTPvhjV6aGeqrCB/sbNop0Kszm0jsaWU4A==", + "dev": true, + "bin": { + "esparse": "bin/esparse.js", + "esvalidate": "bin/esvalidate.js" + }, + "engines": { + "node": ">=4" + } + }, + "node_modules/esquery": { + "version": "1.5.0", + "resolved": "https://registry.npmjs.org/esquery/-/esquery-1.5.0.tgz", + "integrity": "sha512-YQLXUplAwJgCydQ78IMJywZCceoqk1oH01OERdSAJc/7U2AylwjhSCLDEtqwg811idIS/9fIU5GjG73IgjKMVg==", + "dev": true, + "dependencies": { + "estraverse": "^5.1.0" + }, + "engines": { + "node": ">=0.10" + } + }, + "node_modules/esrecurse": { + "version": "4.3.0", + "resolved": "https://registry.npmjs.org/esrecurse/-/esrecurse-4.3.0.tgz", + "integrity": "sha512-KmfKL3b6G+RXvP8N1vr3Tq1kL/oCFgn2NYXEtqP8/L3pKapUA4G8cFVaoF3SU323CD4XypR/ffioHmkti6/Tag==", + "dev": true, + "dependencies": { + "estraverse": "^5.2.0" + }, + "engines": { + "node": ">=4.0" + } + }, + "node_modules/estraverse": { + "version": "5.3.0", + "resolved": "https://registry.npmjs.org/estraverse/-/estraverse-5.3.0.tgz", + "integrity": "sha512-MMdARuVEQziNTeJD8DgMqmhwR11BRQ/cBP+pLtYdSTnf3MIO8fFeiINEbX36ZdNlfU/7A9f3gUw49B3oQsvwBA==", + "dev": true, + "engines": { + "node": ">=4.0" + } + }, + "node_modules/esutils": { + "version": "2.0.3", + "resolved": "https://registry.npmjs.org/esutils/-/esutils-2.0.3.tgz", + "integrity": "sha512-kVscqXk4OCp68SZ0dkgEKVi6/8ij300KBWTJq32P/dYeWTSwK41WyTxalN1eRmA5Z9UU/LX9D7FWSmV9SAYx6g==", + "dev": true, + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/etag": { + "version": "1.8.1", + "resolved": "https://registry.npmjs.org/etag/-/etag-1.8.1.tgz", + "integrity": "sha512-aIL5Fx7mawVa300al2BnEE4iNvo1qETxLrPI/o05L7z6go7fCw1J6EQmbK4FmJ2AS7kgVF/KEZWufBfdClMcPg==", + "dev": true, + "engines": { + "node": ">= 0.6" + } + }, + "node_modules/eth-ens-namehash": { + "version": "2.0.8", + "resolved": "https://registry.npmjs.org/eth-ens-namehash/-/eth-ens-namehash-2.0.8.tgz", + "integrity": "sha512-VWEI1+KJfz4Km//dadyvBBoBeSQ0MHTXPvr8UIXiLW6IanxvAV+DmlZAijZwAyggqGUfwQBeHf7tc9wzc1piSw==", + "dev": true, + "dependencies": { + "idna-uts46-hx": "^2.3.1", + "js-sha3": "^0.5.7" + } + }, + "node_modules/eth-ens-namehash/node_modules/js-sha3": { + "version": "0.5.7", + "resolved": "https://registry.npmjs.org/js-sha3/-/js-sha3-0.5.7.tgz", + "integrity": "sha512-GII20kjaPX0zJ8wzkTbNDYMY7msuZcTWk8S5UOh6806Jq/wz1J8/bnr8uGU0DAUmYDjj2Mr4X1cW8v/GLYnR+g==", + "dev": true + }, + "node_modules/eth-gas-reporter": { + "version": "0.2.25", + "resolved": "https://registry.npmjs.org/eth-gas-reporter/-/eth-gas-reporter-0.2.25.tgz", + "integrity": "sha512-1fRgyE4xUB8SoqLgN3eDfpDfwEfRxh2Sz1b7wzFbyQA+9TekMmvSjjoRu9SKcSVyK+vLkLIsVbJDsTWjw195OQ==", + "dev": true, + "dependencies": { + "@ethersproject/abi": "^5.0.0-beta.146", + "@solidity-parser/parser": "^0.14.0", + "cli-table3": "^0.5.0", + "colors": "1.4.0", + "ethereum-cryptography": "^1.0.3", + "ethers": "^4.0.40", + "fs-readdir-recursive": "^1.1.0", + "lodash": "^4.17.14", + "markdown-table": "^1.1.3", + "mocha": "^7.1.1", + "req-cwd": "^2.0.0", + "request": "^2.88.0", + "request-promise-native": "^1.0.5", + "sha1": "^1.1.1", + "sync-request": "^6.0.0" + }, + "peerDependencies": { + "@codechecks/client": "^0.1.0" + }, + "peerDependenciesMeta": { + "@codechecks/client": { + "optional": true + } + } + }, + "node_modules/eth-gas-reporter/node_modules/ansi-colors": { + "version": "3.2.3", + "resolved": "https://registry.npmjs.org/ansi-colors/-/ansi-colors-3.2.3.tgz", + "integrity": "sha512-LEHHyuhlPY3TmuUYMh2oz89lTShfvgbmzaBcxve9t/9Wuy7Dwf4yoAKcND7KFT1HAQfqZ12qtc+DUrBMeKF9nw==", + "dev": true, + "engines": { + "node": ">=6" + } + }, + "node_modules/eth-gas-reporter/node_modules/ansi-regex": { + "version": "4.1.1", + "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-4.1.1.tgz", + "integrity": "sha512-ILlv4k/3f6vfQ4OoP2AGvirOktlQ98ZEL1k9FaQjxa3L1abBgbuTDAdPOpvbGncC0BTVQrl+OM8xZGK6tWXt7g==", + "dev": true, + "engines": { + "node": ">=6" + } + }, + "node_modules/eth-gas-reporter/node_modules/camelcase": { + "version": "5.3.1", + "resolved": "https://registry.npmjs.org/camelcase/-/camelcase-5.3.1.tgz", + "integrity": "sha512-L28STB170nwWS63UjtlEOE3dldQApaJXZkOI1uMFfzf3rRuPegHaHesyee+YxQ+W6SvRDQV6UrdOdRiR153wJg==", + "dev": true, + "engines": { + "node": ">=6" + } + }, + "node_modules/eth-gas-reporter/node_modules/chokidar": { + "version": "3.3.0", + "resolved": "https://registry.npmjs.org/chokidar/-/chokidar-3.3.0.tgz", + "integrity": "sha512-dGmKLDdT3Gdl7fBUe8XK+gAtGmzy5Fn0XkkWQuYxGIgWVPPse2CxFA5mtrlD0TOHaHjEUqkWNyP1XdHoJES/4A==", + "dev": true, + "dependencies": { + "anymatch": "~3.1.1", + "braces": "~3.0.2", + "glob-parent": "~5.1.0", + "is-binary-path": "~2.1.0", + "is-glob": "~4.0.1", + "normalize-path": "~3.0.0", + "readdirp": "~3.2.0" + }, + "engines": { + "node": ">= 8.10.0" + }, + "optionalDependencies": { + "fsevents": "~2.1.1" + } + }, + "node_modules/eth-gas-reporter/node_modules/cliui": { + "version": "5.0.0", + "resolved": "https://registry.npmjs.org/cliui/-/cliui-5.0.0.tgz", + "integrity": "sha512-PYeGSEmmHM6zvoef2w8TPzlrnNpXIjTipYK780YswmIP9vjxmd6Y2a3CB2Ks6/AU8NHjZugXvo8w3oWM2qnwXA==", + "dev": true, + "dependencies": { + "string-width": "^3.1.0", + "strip-ansi": "^5.2.0", + "wrap-ansi": "^5.1.0" + } + }, + "node_modules/eth-gas-reporter/node_modules/debug": { + "version": "3.2.6", + "resolved": "https://registry.npmjs.org/debug/-/debug-3.2.6.tgz", + "integrity": "sha512-mel+jf7nrtEl5Pn1Qx46zARXKDpBbvzezse7p7LqINmdoIk8PYP5SySaxEmYv6TZ0JyEKA1hsCId6DIhgITtWQ==", + "deprecated": "Debug versions >=3.2.0 <3.2.7 || >=4 <4.3.1 have a low-severity ReDos regression when used in a Node.js environment. It is recommended you upgrade to 3.2.7 or 4.3.1. (https://github.com/visionmedia/debug/issues/797)", + "dev": true, + "dependencies": { + "ms": "^2.1.1" + } + }, + "node_modules/eth-gas-reporter/node_modules/diff": { + "version": "3.5.0", + "resolved": "https://registry.npmjs.org/diff/-/diff-3.5.0.tgz", + "integrity": "sha512-A46qtFgd+g7pDZinpnwiRJtxbC1hpgf0uzP3iG89scHk0AUC7A1TGxf5OiiOUv/JMZR8GOt8hL900hV0bOy5xA==", + "dev": true, + "engines": { + "node": ">=0.3.1" + } + }, + "node_modules/eth-gas-reporter/node_modules/emoji-regex": { + "version": "7.0.3", + "resolved": "https://registry.npmjs.org/emoji-regex/-/emoji-regex-7.0.3.tgz", + "integrity": "sha512-CwBLREIQ7LvYFB0WyRvwhq5N5qPhc6PMjD6bYggFlI5YyDgl+0vxq5VHbMOFqLg7hfWzmu8T5Z1QofhmTIhItA==", + "dev": true + }, + "node_modules/eth-gas-reporter/node_modules/ethereum-cryptography": { + "version": "1.2.0", + "resolved": "https://registry.npmjs.org/ethereum-cryptography/-/ethereum-cryptography-1.2.0.tgz", + "integrity": "sha512-6yFQC9b5ug6/17CQpCyE3k9eKBMdhyVjzUy1WkiuY/E4vj/SXDBbCw8QEIaXqf0Mf2SnY6RmpDcwlUmBSS0EJw==", + "dev": true, + "dependencies": { + "@noble/hashes": "1.2.0", + "@noble/secp256k1": "1.7.1", + "@scure/bip32": "1.1.5", + "@scure/bip39": "1.1.1" + } + }, + "node_modules/eth-gas-reporter/node_modules/find-up": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/find-up/-/find-up-3.0.0.tgz", + "integrity": "sha512-1yD6RmLI1XBfxugvORwlck6f75tYL+iR0jqwsOrOxMZyGYqUuDhJ0l4AXdO1iX/FTs9cBAMEk1gWSEx1kSbylg==", + "dev": true, + "dependencies": { + "locate-path": "^3.0.0" + }, + "engines": { + "node": ">=6" + } + }, + "node_modules/eth-gas-reporter/node_modules/flat": { + "version": "4.1.1", + "resolved": "https://registry.npmjs.org/flat/-/flat-4.1.1.tgz", + "integrity": "sha512-FmTtBsHskrU6FJ2VxCnsDb84wu9zhmO3cUX2kGFb5tuwhfXxGciiT0oRY+cck35QmG+NmGh5eLz6lLCpWTqwpA==", + "dev": true, + "dependencies": { + "is-buffer": "~2.0.3" + }, + "bin": { + "flat": "cli.js" + } + }, + "node_modules/eth-gas-reporter/node_modules/fsevents": { + "version": "2.1.3", + "resolved": "https://registry.npmjs.org/fsevents/-/fsevents-2.1.3.tgz", + "integrity": "sha512-Auw9a4AxqWpa9GUfj370BMPzzyncfBABW8Mab7BGWBYDj4Isgq+cDKtx0i6u9jcX9pQDnswsaaOTgTmA5pEjuQ==", + "deprecated": "\"Please update to latest v2.3 or v2.2\"", + "dev": true, + "hasInstallScript": true, + "optional": true, + "os": [ + "darwin" + ], + "engines": { + "node": "^8.16.0 || ^10.6.0 || >=11.0.0" + } + }, + "node_modules/eth-gas-reporter/node_modules/glob": { + "version": "7.1.3", + "resolved": "https://registry.npmjs.org/glob/-/glob-7.1.3.tgz", + "integrity": "sha512-vcfuiIxogLV4DlGBHIUOwI0IbrJ8HWPc4MU7HzviGeNho/UJDfi6B5p3sHeWIQ0KGIU0Jpxi5ZHxemQfLkkAwQ==", + "dev": true, + "dependencies": { + "fs.realpath": "^1.0.0", + "inflight": "^1.0.4", + "inherits": "2", + "minimatch": "^3.0.4", + "once": "^1.3.0", + "path-is-absolute": "^1.0.0" + }, + "engines": { + "node": "*" + } + }, + "node_modules/eth-gas-reporter/node_modules/js-yaml": { + "version": "3.13.1", + "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-3.13.1.tgz", + "integrity": "sha512-YfbcO7jXDdyj0DGxYVSlSeQNHbD7XPWvrVWeVUujrQEoZzWJIRrCPoyk6kL6IAjAG2IolMK4T0hNUe0HOUs5Jw==", + "dev": true, + "dependencies": { + "argparse": "^1.0.7", + "esprima": "^4.0.0" + }, + "bin": { + "js-yaml": "bin/js-yaml.js" + } + }, + "node_modules/eth-gas-reporter/node_modules/locate-path": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/locate-path/-/locate-path-3.0.0.tgz", + "integrity": "sha512-7AO748wWnIhNqAuaty2ZWHkQHRSNfPVIsPIfwEOWO22AmaoVrWavlOcMR5nzTLNYvp36X220/maaRsrec1G65A==", + "dev": true, + "dependencies": { + "p-locate": "^3.0.0", + "path-exists": "^3.0.0" + }, + "engines": { + "node": ">=6" + } + }, + "node_modules/eth-gas-reporter/node_modules/log-symbols": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/log-symbols/-/log-symbols-3.0.0.tgz", + "integrity": "sha512-dSkNGuI7iG3mfvDzUuYZyvk5dD9ocYCYzNU6CYDE6+Xqd+gwme6Z00NS3dUh8mq/73HaEtT7m6W+yUPtU6BZnQ==", + "dev": true, + "dependencies": { + "chalk": "^2.4.2" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/eth-gas-reporter/node_modules/minimatch": { + "version": "3.0.4", + "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-3.0.4.tgz", + "integrity": "sha512-yJHVQEhyqPLUTgt9B83PXu6W3rx4MvvHvSUvToogpwoGDOUQ+yDrR0HRot+yOCdCO7u4hX3pWft6kWBBcqh0UA==", + "dev": true, + "dependencies": { + "brace-expansion": "^1.1.7" + }, + "engines": { + "node": "*" + } + }, + "node_modules/eth-gas-reporter/node_modules/mkdirp": { + "version": "0.5.5", + "resolved": "https://registry.npmjs.org/mkdirp/-/mkdirp-0.5.5.tgz", + "integrity": "sha512-NKmAlESf6jMGym1++R0Ra7wvhV+wFW63FaSOFPwRahvea0gMUcGUhVeAg/0BC0wiv9ih5NYPB1Wn1UEI1/L+xQ==", + "dev": true, + "dependencies": { + "minimist": "^1.2.5" + }, + "bin": { + "mkdirp": "bin/cmd.js" + } + }, + "node_modules/eth-gas-reporter/node_modules/mocha": { + "version": "7.2.0", + "resolved": "https://registry.npmjs.org/mocha/-/mocha-7.2.0.tgz", + "integrity": "sha512-O9CIypScywTVpNaRrCAgoUnJgozpIofjKUYmJhiCIJMiuYnLI6otcb1/kpW9/n/tJODHGZ7i8aLQoDVsMtOKQQ==", + "dev": true, + "dependencies": { + "ansi-colors": "3.2.3", + "browser-stdout": "1.3.1", + "chokidar": "3.3.0", + "debug": "3.2.6", + "diff": "3.5.0", + "escape-string-regexp": "1.0.5", + "find-up": "3.0.0", + "glob": "7.1.3", + "growl": "1.10.5", + "he": "1.2.0", + "js-yaml": "3.13.1", + "log-symbols": "3.0.0", + "minimatch": "3.0.4", + "mkdirp": "0.5.5", + "ms": "2.1.1", + "node-environment-flags": "1.0.6", + "object.assign": "4.1.0", + "strip-json-comments": "2.0.1", + "supports-color": "6.0.0", + "which": "1.3.1", + "wide-align": "1.1.3", + "yargs": "13.3.2", + "yargs-parser": "13.1.2", + "yargs-unparser": "1.6.0" + }, + "bin": { + "_mocha": "bin/_mocha", + "mocha": "bin/mocha" + }, + "engines": { + "node": ">= 8.10.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/mochajs" + } + }, + "node_modules/eth-gas-reporter/node_modules/ms": { + "version": "2.1.1", + "resolved": "https://registry.npmjs.org/ms/-/ms-2.1.1.tgz", + "integrity": "sha512-tgp+dl5cGk28utYktBsrFqA7HKgrhgPsg6Z/EfhWI4gl1Hwq8B/GmY/0oXZ6nF8hDVesS/FpnYaD/kOWhYQvyg==", + "dev": true + }, + "node_modules/eth-gas-reporter/node_modules/object.assign": { + "version": "4.1.0", + "resolved": "https://registry.npmjs.org/object.assign/-/object.assign-4.1.0.tgz", + "integrity": "sha512-exHJeq6kBKj58mqGyTQ9DFvrZC/eR6OwxzoM9YRoGBqrXYonaFyGiFMuc9VZrXf7DarreEwMpurG3dd+CNyW5w==", + "dev": true, + "dependencies": { + "define-properties": "^1.1.2", + "function-bind": "^1.1.1", + "has-symbols": "^1.0.0", + "object-keys": "^1.0.11" + }, + "engines": { + "node": ">= 0.4" + } + }, + "node_modules/eth-gas-reporter/node_modules/p-limit": { + "version": "2.3.0", + "resolved": "https://registry.npmjs.org/p-limit/-/p-limit-2.3.0.tgz", + "integrity": "sha512-//88mFWSJx8lxCzwdAABTJL2MyWB12+eIY7MDL2SqLmAkeKU9qxRvWuSyTjm3FUmpBEMuFfckAIqEaVGUDxb6w==", + "dev": true, + "dependencies": { + "p-try": "^2.0.0" + }, + "engines": { + "node": ">=6" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/eth-gas-reporter/node_modules/p-locate": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/p-locate/-/p-locate-3.0.0.tgz", + "integrity": "sha512-x+12w/To+4GFfgJhBEpiDcLozRJGegY+Ei7/z0tSLkMmxGZNybVMSfWj9aJn8Z5Fc7dBUNJOOVgPv2H7IwulSQ==", + "dev": true, + "dependencies": { + "p-limit": "^2.0.0" + }, + "engines": { + "node": ">=6" + } + }, + "node_modules/eth-gas-reporter/node_modules/path-exists": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/path-exists/-/path-exists-3.0.0.tgz", + "integrity": "sha512-bpC7GYwiDYQ4wYLe+FA8lhRjhQCMcQGuSgGGqDkg/QerRWw9CmGRT0iSOVRSZJ29NMLZgIzqaljJ63oaL4NIJQ==", + "dev": true, + "engines": { + "node": ">=4" + } + }, + "node_modules/eth-gas-reporter/node_modules/readdirp": { + "version": "3.2.0", + "resolved": "https://registry.npmjs.org/readdirp/-/readdirp-3.2.0.tgz", + "integrity": "sha512-crk4Qu3pmXwgxdSgGhgA/eXiJAPQiX4GMOZZMXnqKxHX7TaoL+3gQVo/WeuAiogr07DpnfjIMpXXa+PAIvwPGQ==", + "dev": true, + "dependencies": { + "picomatch": "^2.0.4" + }, + "engines": { + "node": ">= 8" + } + }, + "node_modules/eth-gas-reporter/node_modules/string-width": { + "version": "3.1.0", + "resolved": "https://registry.npmjs.org/string-width/-/string-width-3.1.0.tgz", + "integrity": "sha512-vafcv6KjVZKSgz06oM/H6GDBrAtz8vdhQakGjFIvNrHA6y3HCF1CInLy+QLq8dTJPQ1b+KDUqDFctkdRW44e1w==", + "dev": true, + "dependencies": { + "emoji-regex": "^7.0.1", + "is-fullwidth-code-point": "^2.0.0", + "strip-ansi": "^5.1.0" + }, + "engines": { + "node": ">=6" + } + }, + "node_modules/eth-gas-reporter/node_modules/strip-ansi": { + "version": "5.2.0", + "resolved": "https://registry.npmjs.org/strip-ansi/-/strip-ansi-5.2.0.tgz", + "integrity": "sha512-DuRs1gKbBqsMKIZlrffwlug8MHkcnpjs5VPmL1PAh+mA30U0DTotfDZ0d2UUsXpPmPmMMJ6W773MaA3J+lbiWA==", + "dev": true, + "dependencies": { + "ansi-regex": "^4.1.0" + }, + "engines": { + "node": ">=6" + } + }, + "node_modules/eth-gas-reporter/node_modules/strip-json-comments": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/strip-json-comments/-/strip-json-comments-2.0.1.tgz", + "integrity": "sha512-4gB8na07fecVVkOI6Rs4e7T6NOTki5EmL7TUduTs6bu3EdnSycntVJ4re8kgZA+wx9IueI2Y11bfbgwtzuE0KQ==", + "dev": true, + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/eth-gas-reporter/node_modules/supports-color": { + "version": "6.0.0", + "resolved": "https://registry.npmjs.org/supports-color/-/supports-color-6.0.0.tgz", + "integrity": "sha512-on9Kwidc1IUQo+bQdhi8+Tijpo0e1SS6RoGo2guUwn5vdaxw8RXOF9Vb2ws+ihWOmh4JnCJOvaziZWP1VABaLg==", + "dev": true, + "dependencies": { + "has-flag": "^3.0.0" + }, + "engines": { + "node": ">=6" + } + }, + "node_modules/eth-gas-reporter/node_modules/which": { + "version": "1.3.1", + "resolved": "https://registry.npmjs.org/which/-/which-1.3.1.tgz", + "integrity": "sha512-HxJdYWq1MTIQbJ3nw0cqssHoTNU267KlrDuGZ1WYlxDStUtKUhOaJmh112/TZmHxxUfuJqPXSOm7tDyas0OSIQ==", + "dev": true, + "dependencies": { + "isexe": "^2.0.0" + }, + "bin": { + "which": "bin/which" + } + }, + "node_modules/eth-gas-reporter/node_modules/wrap-ansi": { + "version": "5.1.0", + "resolved": "https://registry.npmjs.org/wrap-ansi/-/wrap-ansi-5.1.0.tgz", + "integrity": "sha512-QC1/iN/2/RPVJ5jYK8BGttj5z83LmSKmvbvrXPNCLZSEb32KKVDJDl/MOt2N01qU2H/FkzEa9PKto1BqDjtd7Q==", + "dev": true, + "dependencies": { + "ansi-styles": "^3.2.0", + "string-width": "^3.0.0", + "strip-ansi": "^5.0.0" + }, + "engines": { + "node": ">=6" + } + }, + "node_modules/eth-gas-reporter/node_modules/y18n": { + "version": "4.0.3", + "resolved": "https://registry.npmjs.org/y18n/-/y18n-4.0.3.tgz", + "integrity": "sha512-JKhqTOwSrqNA1NY5lSztJ1GrBiUodLMmIZuLiDaMRJ+itFd+ABVE8XBjOvIWL+rSqNDC74LCSFmlb/U4UZ4hJQ==", + "dev": true + }, + "node_modules/eth-gas-reporter/node_modules/yargs": { + "version": "13.3.2", + "resolved": "https://registry.npmjs.org/yargs/-/yargs-13.3.2.tgz", + "integrity": "sha512-AX3Zw5iPruN5ie6xGRIDgqkT+ZhnRlZMLMHAs8tg7nRruy2Nb+i5o9bwghAogtM08q1dpr2LVoS8KSTMYpWXUw==", + "dev": true, + "dependencies": { + "cliui": "^5.0.0", + "find-up": "^3.0.0", + "get-caller-file": "^2.0.1", + "require-directory": "^2.1.1", + "require-main-filename": "^2.0.0", + "set-blocking": "^2.0.0", + "string-width": "^3.0.0", + "which-module": "^2.0.0", + "y18n": "^4.0.0", + "yargs-parser": "^13.1.2" + } + }, + "node_modules/eth-gas-reporter/node_modules/yargs-parser": { + "version": "13.1.2", + "resolved": "https://registry.npmjs.org/yargs-parser/-/yargs-parser-13.1.2.tgz", + "integrity": "sha512-3lbsNRf/j+A4QuSZfDRA7HRSfWrzO0YjqTJd5kjAq37Zep1CEgaYmrH9Q3GwPiB9cHyd1Y1UwggGhJGoxipbzg==", + "dev": true, + "dependencies": { + "camelcase": "^5.0.0", + "decamelize": "^1.2.0" + } + }, + "node_modules/eth-gas-reporter/node_modules/yargs-unparser": { + "version": "1.6.0", + "resolved": "https://registry.npmjs.org/yargs-unparser/-/yargs-unparser-1.6.0.tgz", + "integrity": "sha512-W9tKgmSn0DpSatfri0nx52Joq5hVXgeLiqR/5G0sZNDoLZFOr/xjBUDcShCOGNsBnEMNo1KAMBkTej1Hm62HTw==", + "dev": true, + "dependencies": { + "flat": "^4.1.0", + "lodash": "^4.17.15", + "yargs": "^13.3.0" + }, + "engines": { + "node": ">=6" + } + }, + "node_modules/eth-lib": { + "version": "0.1.29", + "resolved": "https://registry.npmjs.org/eth-lib/-/eth-lib-0.1.29.tgz", + "integrity": "sha512-bfttrr3/7gG4E02HoWTDUcDDslN003OlOoBxk9virpAZQ1ja/jDgwkWB8QfJF7ojuEowrqy+lzp9VcJG7/k5bQ==", + "dev": true, + "dependencies": { + "bn.js": "^4.11.6", + "elliptic": "^6.4.0", + "nano-json-stream-parser": "^0.1.2", + "servify": "^0.1.12", + "ws": "^3.0.0", + "xhr-request-promise": "^0.1.2" + } + }, + "node_modules/eth-lib/node_modules/safe-buffer": { + "version": "5.1.2", + "resolved": "https://registry.npmjs.org/safe-buffer/-/safe-buffer-5.1.2.tgz", + "integrity": "sha512-Gd2UZBJDkXlY7GbJxfsE8/nvKkUEU1G38c1siN6QP6a9PT9MmHB8GnpscSmMJSoF8LOIrt8ud/wPtojys4G6+g==", + "dev": true + }, + "node_modules/eth-lib/node_modules/ws": { + "version": "3.3.3", + "resolved": "https://registry.npmjs.org/ws/-/ws-3.3.3.tgz", + "integrity": "sha512-nnWLa/NwZSt4KQJu51MYlCcSQ5g7INpOrOMt4XV8j4dqTXdmlUmSHQ8/oLC069ckre0fRsgfvsKwbTdtKLCDkA==", + "dev": true, + "dependencies": { + "async-limiter": "~1.0.0", + "safe-buffer": "~5.1.0", + "ultron": "~1.1.0" + } + }, + "node_modules/eth-sig-util": { + "version": "3.0.1", + "resolved": "https://registry.npmjs.org/eth-sig-util/-/eth-sig-util-3.0.1.tgz", + "integrity": "sha512-0Us50HiGGvZgjtWTyAI/+qTzYPMLy5Q451D0Xy68bxq1QMWdoOddDwGvsqcFT27uohKgalM9z/yxplyt+mY2iQ==", + "deprecated": "Deprecated in favor of '@metamask/eth-sig-util'", + "dev": true, + "dependencies": { + "ethereumjs-abi": "^0.6.8", + "ethereumjs-util": "^5.1.1", + "tweetnacl": "^1.0.3", + "tweetnacl-util": "^0.15.0" + } + }, + "node_modules/eth-sig-util/node_modules/ethereumjs-util": { + "version": "5.2.1", + "resolved": "https://registry.npmjs.org/ethereumjs-util/-/ethereumjs-util-5.2.1.tgz", + "integrity": "sha512-v3kT+7zdyCm1HIqWlLNrHGqHGLpGYIhjeHxQjnDXjLT2FyGJDsd3LWMYUo7pAFRrk86CR3nUJfhC81CCoJNNGQ==", + "dev": true, + "dependencies": { + "bn.js": "^4.11.0", + "create-hash": "^1.1.2", + "elliptic": "^6.5.2", + "ethereum-cryptography": "^0.1.3", + "ethjs-util": "^0.1.3", + "rlp": "^2.0.0", + "safe-buffer": "^5.1.1" + } + }, + "node_modules/ethereum-bloom-filters": { + "version": "1.0.10", + "resolved": "https://registry.npmjs.org/ethereum-bloom-filters/-/ethereum-bloom-filters-1.0.10.tgz", + "integrity": "sha512-rxJ5OFN3RwjQxDcFP2Z5+Q9ho4eIdEmSc2ht0fCu8Se9nbXjZ7/031uXoUYJ87KHCOdVeiUuwSnoS7hmYAGVHA==", + "dev": true, + "dependencies": { + "js-sha3": "^0.8.0" + } + }, + "node_modules/ethereum-cryptography": { + "version": "0.1.3", + "resolved": "https://registry.npmjs.org/ethereum-cryptography/-/ethereum-cryptography-0.1.3.tgz", + "integrity": "sha512-w8/4x1SGGzc+tO97TASLja6SLd3fRIK2tLVcV2Gx4IB21hE19atll5Cq9o3d0ZmAYC/8aw0ipieTSiekAea4SQ==", + "dev": true, + "dependencies": { + "@types/pbkdf2": "^3.0.0", + "@types/secp256k1": "^4.0.1", + "blakejs": "^1.1.0", + "browserify-aes": "^1.2.0", + "bs58check": "^2.1.2", + "create-hash": "^1.2.0", + "create-hmac": "^1.1.7", + "hash.js": "^1.1.7", + "keccak": "^3.0.0", + "pbkdf2": "^3.0.17", + "randombytes": "^2.1.0", + "safe-buffer": "^5.1.2", + "scrypt-js": "^3.0.0", + "secp256k1": "^4.0.1", + "setimmediate": "^1.0.5" + } + }, + "node_modules/ethereum-ens": { + "version": "0.8.0", + "resolved": "https://registry.npmjs.org/ethereum-ens/-/ethereum-ens-0.8.0.tgz", + "integrity": "sha512-a8cBTF4AWw1Q1Y37V1LSCS9pRY4Mh3f8vCg5cbXCCEJ3eno1hbI/+Ccv9SZLISYpqQhaglP3Bxb/34lS4Qf7Bg==", + "dev": true, + "dependencies": { + "bluebird": "^3.4.7", + "eth-ens-namehash": "^2.0.0", + "js-sha3": "^0.5.7", + "pako": "^1.0.4", + "underscore": "^1.8.3", + "web3": "^1.0.0-beta.34" + } + }, + "node_modules/ethereum-ens/node_modules/js-sha3": { + "version": "0.5.7", + "resolved": "https://registry.npmjs.org/js-sha3/-/js-sha3-0.5.7.tgz", + "integrity": "sha512-GII20kjaPX0zJ8wzkTbNDYMY7msuZcTWk8S5UOh6806Jq/wz1J8/bnr8uGU0DAUmYDjj2Mr4X1cW8v/GLYnR+g==", + "dev": true + }, + "node_modules/ethereumjs-abi": { + "version": "0.6.8", + "resolved": "https://registry.npmjs.org/ethereumjs-abi/-/ethereumjs-abi-0.6.8.tgz", + "integrity": "sha512-Tx0r/iXI6r+lRsdvkFDlut0N08jWMnKRZ6Gkq+Nmw75lZe4e6o3EkSnkaBP5NF6+m5PTGAr9JP43N3LyeoglsA==", + "dev": true, + "dependencies": { + "bn.js": "^4.11.8", + "ethereumjs-util": "^6.0.0" + } + }, + "node_modules/ethereumjs-abi/node_modules/@types/bn.js": { + "version": "4.11.6", + "resolved": "https://registry.npmjs.org/@types/bn.js/-/bn.js-4.11.6.tgz", + "integrity": "sha512-pqr857jrp2kPuO9uRjZ3PwnJTjoQy+fcdxvBTvHm6dkmEL9q+hDD/2j/0ELOBPtPnS8LjCX0gI9nbl8lVkadpg==", + "dev": true, + "dependencies": { + "@types/node": "*" + } + }, + "node_modules/ethereumjs-abi/node_modules/ethereumjs-util": { + "version": "6.2.1", + "resolved": "https://registry.npmjs.org/ethereumjs-util/-/ethereumjs-util-6.2.1.tgz", + "integrity": "sha512-W2Ktez4L01Vexijrm5EB6w7dg4n/TgpoYU4avuT5T3Vmnw/eCRtiBrJfQYS/DCSvDIOLn2k57GcHdeBcgVxAqw==", + "dev": true, + "dependencies": { + "@types/bn.js": "^4.11.3", + "bn.js": "^4.11.0", + "create-hash": "^1.1.2", + "elliptic": "^6.5.2", + "ethereum-cryptography": "^0.1.3", + "ethjs-util": "0.1.6", + "rlp": "^2.2.3" + } + }, + "node_modules/ethereumjs-util": { + "version": "7.1.5", + "resolved": "https://registry.npmjs.org/ethereumjs-util/-/ethereumjs-util-7.1.5.tgz", + "integrity": "sha512-SDl5kKrQAudFBUe5OJM9Ac6WmMyYmXX/6sTmLZ3ffG2eY6ZIGBes3pEDxNN6V72WyOw4CPD5RomKdsa8DAAwLg==", + "dev": true, + "dependencies": { + "@types/bn.js": "^5.1.0", + "bn.js": "^5.1.2", + "create-hash": "^1.1.2", + "ethereum-cryptography": "^0.1.3", + "rlp": "^2.2.4" + }, + "engines": { + "node": ">=10.0.0" + } + }, + "node_modules/ethereumjs-util/node_modules/bn.js": { + "version": "5.2.1", + "resolved": "https://registry.npmjs.org/bn.js/-/bn.js-5.2.1.tgz", + "integrity": "sha512-eXRvHzWyYPBuB4NBy0cmYQjGitUrtqwbvlzP3G6VFnNRbsZQIxQ10PbKKHt8gZ/HW/D/747aDl+QkDqg3KQLMQ==", + "dev": true + }, + "node_modules/ethereumjs-wallet": { + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/ethereumjs-wallet/-/ethereumjs-wallet-1.0.2.tgz", + "integrity": "sha512-CCWV4RESJgRdHIvFciVQFnCHfqyhXWchTPlkfp28Qc53ufs+doi5I/cV2+xeK9+qEo25XCWfP9MiL+WEPAZfdA==", + "dev": true, + "dependencies": { + "aes-js": "^3.1.2", + "bs58check": "^2.1.2", + "ethereum-cryptography": "^0.1.3", + "ethereumjs-util": "^7.1.2", + "randombytes": "^2.1.0", + "scrypt-js": "^3.0.1", + "utf8": "^3.0.0", + "uuid": "^8.3.2" + } + }, + "node_modules/ethers": { + "version": "4.0.49", + "resolved": "https://registry.npmjs.org/ethers/-/ethers-4.0.49.tgz", + "integrity": "sha512-kPltTvWiyu+OktYy1IStSO16i2e7cS9D9OxZ81q2UUaiNPVrm/RTcbxamCXF9VUSKzJIdJV68EAIhTEVBalRWg==", + "dev": true, + "dependencies": { + "aes-js": "3.0.0", + "bn.js": "^4.11.9", + "elliptic": "6.5.4", + "hash.js": "1.1.3", + "js-sha3": "0.5.7", + "scrypt-js": "2.0.4", + "setimmediate": "1.0.4", + "uuid": "2.0.1", + "xmlhttprequest": "1.8.0" + } + }, + "node_modules/ethers/node_modules/aes-js": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/aes-js/-/aes-js-3.0.0.tgz", + "integrity": "sha512-H7wUZRn8WpTq9jocdxQ2c8x2sKo9ZVmzfRE13GiNJXfp7NcKYEdvl3vspKjXox6RIG2VtaRe4JFvxG4rqp2Zuw==", + "dev": true + }, + "node_modules/ethers/node_modules/hash.js": { + "version": "1.1.3", + "resolved": "https://registry.npmjs.org/hash.js/-/hash.js-1.1.3.tgz", + "integrity": "sha512-/UETyP0W22QILqS+6HowevwhEFJ3MBJnwTf75Qob9Wz9t0DPuisL8kW8YZMK62dHAKE1c1p+gY1TtOLY+USEHA==", + "dev": true, + "dependencies": { + "inherits": "^2.0.3", + "minimalistic-assert": "^1.0.0" + } + }, + "node_modules/ethers/node_modules/js-sha3": { + "version": "0.5.7", + "resolved": "https://registry.npmjs.org/js-sha3/-/js-sha3-0.5.7.tgz", + "integrity": "sha512-GII20kjaPX0zJ8wzkTbNDYMY7msuZcTWk8S5UOh6806Jq/wz1J8/bnr8uGU0DAUmYDjj2Mr4X1cW8v/GLYnR+g==", + "dev": true + }, + "node_modules/ethers/node_modules/scrypt-js": { + "version": "2.0.4", + "resolved": "https://registry.npmjs.org/scrypt-js/-/scrypt-js-2.0.4.tgz", + "integrity": "sha512-4KsaGcPnuhtCZQCxFxN3GVYIhKFPTdLd8PLC552XwbMndtD0cjRFAhDuuydXQ0h08ZfPgzqe6EKHozpuH74iDw==", + "dev": true + }, + "node_modules/ethers/node_modules/setimmediate": { + "version": "1.0.4", + "resolved": "https://registry.npmjs.org/setimmediate/-/setimmediate-1.0.4.tgz", + "integrity": "sha512-/TjEmXQVEzdod/FFskf3o7oOAsGhHf2j1dZqRFbDzq4F3mvvxflIIi4Hd3bLQE9y/CpwqfSQam5JakI/mi3Pog==", + "dev": true + }, + "node_modules/ethers/node_modules/uuid": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/uuid/-/uuid-2.0.1.tgz", + "integrity": "sha512-nWg9+Oa3qD2CQzHIP4qKUqwNfzKn8P0LtFhotaCTFchsV7ZfDhAybeip/HZVeMIpZi9JgY1E3nUlwaCmZT1sEg==", + "deprecated": "Please upgrade to version 7 or higher. Older versions may use Math.random() in certain circumstances, which is known to be problematic. See https://v8.dev/blog/math-random for details.", + "dev": true + }, + "node_modules/ethjs-abi": { + "version": "0.2.1", + "resolved": "https://registry.npmjs.org/ethjs-abi/-/ethjs-abi-0.2.1.tgz", + "integrity": "sha512-g2AULSDYI6nEJyJaEVEXtTimRY2aPC2fi7ddSy0W+LXvEVL8Fe1y76o43ecbgdUKwZD+xsmEgX1yJr1Ia3r1IA==", + "dev": true, + "dependencies": { + "bn.js": "4.11.6", + "js-sha3": "0.5.5", + "number-to-bn": "1.7.0" + }, + "engines": { + "node": ">=6.5.0", + "npm": ">=3" + } + }, + "node_modules/ethjs-abi/node_modules/bn.js": { + "version": "4.11.6", + "resolved": "https://registry.npmjs.org/bn.js/-/bn.js-4.11.6.tgz", + "integrity": "sha512-XWwnNNFCuuSQ0m3r3C4LE3EiORltHd9M05pq6FOlVeiophzRbMo50Sbz1ehl8K3Z+jw9+vmgnXefY1hz8X+2wA==", + "dev": true + }, + "node_modules/ethjs-abi/node_modules/js-sha3": { + "version": "0.5.5", + "resolved": "https://registry.npmjs.org/js-sha3/-/js-sha3-0.5.5.tgz", + "integrity": "sha512-yLLwn44IVeunwjpDVTDZmQeVbB0h+dZpY2eO68B/Zik8hu6dH+rKeLxwua79GGIvW6xr8NBAcrtiUbYrTjEFTA==", + "dev": true + }, + "node_modules/ethjs-unit": { + "version": "0.1.6", + "resolved": "https://registry.npmjs.org/ethjs-unit/-/ethjs-unit-0.1.6.tgz", + "integrity": "sha512-/Sn9Y0oKl0uqQuvgFk/zQgR7aw1g36qX/jzSQ5lSwlO0GigPymk4eGQfeNTD03w1dPOqfz8V77Cy43jH56pagw==", + "dev": true, + "dependencies": { + "bn.js": "4.11.6", + "number-to-bn": "1.7.0" + }, + "engines": { + "node": ">=6.5.0", + "npm": ">=3" + } + }, + "node_modules/ethjs-unit/node_modules/bn.js": { + "version": "4.11.6", + "resolved": "https://registry.npmjs.org/bn.js/-/bn.js-4.11.6.tgz", + "integrity": "sha512-XWwnNNFCuuSQ0m3r3C4LE3EiORltHd9M05pq6FOlVeiophzRbMo50Sbz1ehl8K3Z+jw9+vmgnXefY1hz8X+2wA==", + "dev": true + }, + "node_modules/ethjs-util": { + "version": "0.1.6", + "resolved": "https://registry.npmjs.org/ethjs-util/-/ethjs-util-0.1.6.tgz", + "integrity": "sha512-CUnVOQq7gSpDHZVVrQW8ExxUETWrnrvXYvYz55wOU8Uj4VCgw56XC2B/fVqQN+f7gmrnRHSLVnFAwsCuNwji8w==", + "dev": true, + "dependencies": { + "is-hex-prefixed": "1.0.0", + "strip-hex-prefix": "1.0.0" + }, + "engines": { + "node": ">=6.5.0", + "npm": ">=3" + } + }, + "node_modules/event-target-shim": { + "version": "5.0.1", + "resolved": "https://registry.npmjs.org/event-target-shim/-/event-target-shim-5.0.1.tgz", + "integrity": "sha512-i/2XbnSz/uxRCU6+NdVJgKWDTM427+MqYbkQzD321DuCQJUqOuJKIA0IM2+W2xtYHdKOmZ4dR6fExsd4SXL+WQ==", + "dev": true, + "engines": { + "node": ">=6" + } + }, + "node_modules/eventemitter3": { + "version": "4.0.4", + "resolved": "https://registry.npmjs.org/eventemitter3/-/eventemitter3-4.0.4.tgz", + "integrity": "sha512-rlaVLnVxtxvoyLsQQFBx53YmXHDxRIzzTLbdfxqi4yocpSjAxXwkU0cScM5JgSKMqEhrZpnvQ2D9gjylR0AimQ==", + "dev": true + }, + "node_modules/evp_bytestokey": { + "version": "1.0.3", + "resolved": "https://registry.npmjs.org/evp_bytestokey/-/evp_bytestokey-1.0.3.tgz", + "integrity": "sha512-/f2Go4TognH/KvCISP7OUsHn85hT9nUkxxA9BEWxFn+Oj9o8ZNLm/40hdlgSLyuOimsrTKLUMEorQexp/aPQeA==", + "dev": true, + "dependencies": { + "md5.js": "^1.3.4", + "safe-buffer": "^5.1.1" + } + }, + "node_modules/express": { + "version": "4.18.2", + "resolved": "https://registry.npmjs.org/express/-/express-4.18.2.tgz", + "integrity": "sha512-5/PsL6iGPdfQ/lKM1UuielYgv3BUoJfz1aUwU9vHZ+J7gyvwdQXFEBIEIaxeGf0GIcreATNyBExtalisDbuMqQ==", + "dev": true, + "dependencies": { + "accepts": "~1.3.8", + "array-flatten": "1.1.1", + "body-parser": "1.20.1", + "content-disposition": "0.5.4", + "content-type": "~1.0.4", + "cookie": "0.5.0", + "cookie-signature": "1.0.6", + "debug": "2.6.9", + "depd": "2.0.0", + "encodeurl": "~1.0.2", + "escape-html": "~1.0.3", + "etag": "~1.8.1", + "finalhandler": "1.2.0", + "fresh": "0.5.2", + "http-errors": "2.0.0", + "merge-descriptors": "1.0.1", + "methods": "~1.1.2", + "on-finished": "2.4.1", + "parseurl": "~1.3.3", + "path-to-regexp": "0.1.7", + "proxy-addr": "~2.0.7", + "qs": "6.11.0", + "range-parser": "~1.2.1", + "safe-buffer": "5.2.1", + "send": "0.18.0", + "serve-static": "1.15.0", + "setprototypeof": "1.2.0", + "statuses": "2.0.1", + "type-is": "~1.6.18", + "utils-merge": "1.0.1", + "vary": "~1.1.2" + }, + "engines": { + "node": ">= 0.10.0" + } + }, + "node_modules/express/node_modules/body-parser": { + "version": "1.20.1", + "resolved": "https://registry.npmjs.org/body-parser/-/body-parser-1.20.1.tgz", + "integrity": "sha512-jWi7abTbYwajOytWCQc37VulmWiRae5RyTpaCyDcS5/lMdtwSz5lOpDE67srw/HYe35f1z3fDQw+3txg7gNtWw==", + "dev": true, + "dependencies": { + "bytes": "3.1.2", + "content-type": "~1.0.4", + "debug": "2.6.9", + "depd": "2.0.0", + "destroy": "1.2.0", + "http-errors": "2.0.0", + "iconv-lite": "0.4.24", + "on-finished": "2.4.1", + "qs": "6.11.0", + "raw-body": "2.5.1", + "type-is": "~1.6.18", + "unpipe": "1.0.0" + }, + "engines": { + "node": ">= 0.8", + "npm": "1.2.8000 || >= 1.4.16" + } + }, + "node_modules/express/node_modules/cookie": { + "version": "0.5.0", + "resolved": "https://registry.npmjs.org/cookie/-/cookie-0.5.0.tgz", + "integrity": "sha512-YZ3GUyn/o8gfKJlnlX7g7xq4gyO6OSuhGPKaaGssGB2qgDUS0gPgtTvoyZLTt9Ab6dC4hfc9dV5arkvc/OCmrw==", + "dev": true, + "engines": { + "node": ">= 0.6" + } + }, + "node_modules/express/node_modules/debug": { + "version": "2.6.9", + "resolved": "https://registry.npmjs.org/debug/-/debug-2.6.9.tgz", + "integrity": "sha512-bC7ElrdJaJnPbAP+1EotYvqZsb3ecl5wi6Bfi6BJTUcNowp6cvspg0jXznRTKDjm/E7AdgFBVeAPVMNcKGsHMA==", + "dev": true, + "dependencies": { + "ms": "2.0.0" + } + }, + "node_modules/express/node_modules/ms": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/ms/-/ms-2.0.0.tgz", + "integrity": "sha512-Tpp60P6IUJDTuOq/5Z8cdskzJujfwqfOTkrwIwj7IRISpnkJnT6SyJ4PCPnGMoFjC9ddhal5KVIYtAt97ix05A==", + "dev": true + }, + "node_modules/express/node_modules/qs": { + "version": "6.11.0", + "resolved": "https://registry.npmjs.org/qs/-/qs-6.11.0.tgz", + "integrity": "sha512-MvjoMCJwEarSbUYk5O+nmoSzSutSsTwF85zcHPQ9OrlFoZOYIjaqBAJIqIXjptyD5vThxGq52Xu/MaJzRkIk4Q==", + "dev": true, + "dependencies": { + "side-channel": "^1.0.4" + }, + "engines": { + "node": ">=0.6" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/express/node_modules/raw-body": { + "version": "2.5.1", + "resolved": "https://registry.npmjs.org/raw-body/-/raw-body-2.5.1.tgz", + "integrity": "sha512-qqJBtEyVgS0ZmPGdCFPWJ3FreoqvG4MVQln/kCgF7Olq95IbOp0/BWyMwbdtn4VTvkM8Y7khCQ2Xgk/tcrCXig==", + "dev": true, + "dependencies": { + "bytes": "3.1.2", + "http-errors": "2.0.0", + "iconv-lite": "0.4.24", + "unpipe": "1.0.0" + }, + "engines": { + "node": ">= 0.8" + } + }, + "node_modules/ext": { + "version": "1.7.0", + "resolved": "https://registry.npmjs.org/ext/-/ext-1.7.0.tgz", + "integrity": "sha512-6hxeJYaL110a9b5TEJSj0gojyHQAmA2ch5Os+ySCiA1QGdS697XWY1pzsrSjqA9LDEEgdB/KypIlR59RcLuHYw==", + "dev": true, + "dependencies": { + "type": "^2.7.2" + } + }, + "node_modules/ext/node_modules/type": { + "version": "2.7.2", + "resolved": "https://registry.npmjs.org/type/-/type-2.7.2.tgz", + "integrity": "sha512-dzlvlNlt6AXU7EBSfpAscydQ7gXB+pPGsPnfJnZpiNJBDj7IaJzQlBZYGdEi4R9HmPdBv2XmWJ6YUtoTa7lmCw==", + "dev": true + }, + "node_modules/extend": { + "version": "3.0.2", + "resolved": "https://registry.npmjs.org/extend/-/extend-3.0.2.tgz", + "integrity": "sha512-fjquC59cD7CyW6urNXK0FBufkZcoiGG80wTuPujX590cB5Ttln20E2UB4S/WARVqhXffZl2LNgS+gQdPIIim/g==", + "dev": true + }, + "node_modules/extendable-error": { + "version": "0.1.7", + "resolved": "https://registry.npmjs.org/extendable-error/-/extendable-error-0.1.7.tgz", + "integrity": "sha512-UOiS2in6/Q0FK0R0q6UY9vYpQ21mr/Qn1KOnte7vsACuNJf514WvCCUHSRCPcgjPT2bAhNIJdlE6bVap1GKmeg==", + "dev": true + }, + "node_modules/external-editor": { + "version": "3.1.0", + "resolved": "https://registry.npmjs.org/external-editor/-/external-editor-3.1.0.tgz", + "integrity": "sha512-hMQ4CX1p1izmuLYyZqLMO/qGNw10wSv9QDCPfzXfyFrOaCSSoRfqE1Kf1s5an66J5JZC62NewG+mK49jOCtQew==", + "dev": true, + "dependencies": { + "chardet": "^0.7.0", + "iconv-lite": "^0.4.24", + "tmp": "^0.0.33" + }, + "engines": { + "node": ">=4" + } + }, + "node_modules/extsprintf": { + "version": "1.3.0", + "resolved": "https://registry.npmjs.org/extsprintf/-/extsprintf-1.3.0.tgz", + "integrity": "sha512-11Ndz7Nv+mvAC1j0ktTa7fAb0vLyGGX+rMHNBYQviQDGU0Hw7lhctJANqbPhu9nV9/izT/IntTgZ7Im/9LJs9g==", + "dev": true, + "engines": [ + "node >=0.6.0" + ] + }, + "node_modules/fast-check": { + "version": "3.1.1", + "resolved": "https://registry.npmjs.org/fast-check/-/fast-check-3.1.1.tgz", + "integrity": "sha512-3vtXinVyuUKCKFKYcwXhGE6NtGWkqF8Yh3rvMZNzmwz8EPrgoc/v4pDdLHyLnCyCI5MZpZZkDEwFyXyEONOxpA==", + "dev": true, + "dependencies": { + "pure-rand": "^5.0.1" + }, + "engines": { + "node": ">=8.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/fast-check" + } + }, + "node_modules/fast-deep-equal": { + "version": "3.1.3", + "resolved": "https://registry.npmjs.org/fast-deep-equal/-/fast-deep-equal-3.1.3.tgz", + "integrity": "sha512-f3qQ9oQy9j2AhBe/H9VC91wLmKBCCU/gDOnKNAYG5hswO7BLKj09Hc5HYNz9cGI++xlpDCIgDaitVs03ATR84Q==", + "dev": true + }, + "node_modules/fast-diff": { + "version": "1.3.0", + "resolved": "https://registry.npmjs.org/fast-diff/-/fast-diff-1.3.0.tgz", + "integrity": "sha512-VxPP4NqbUjj6MaAOafWeUn2cXWLcCtljklUtZf0Ind4XQ+QPtmA0b18zZy0jIQx+ExRVCR/ZQpBmik5lXshNsw==", + "dev": true + }, + "node_modules/fast-glob": { + "version": "3.3.0", + "resolved": "https://registry.npmjs.org/fast-glob/-/fast-glob-3.3.0.tgz", + "integrity": "sha512-ChDuvbOypPuNjO8yIDf36x7BlZX1smcUMTTcyoIjycexOxd6DFsKsg21qVBzEmr3G7fUKIRy2/psii+CIUt7FA==", + "dev": true, + "dependencies": { + "@nodelib/fs.stat": "^2.0.2", + "@nodelib/fs.walk": "^1.2.3", + "glob-parent": "^5.1.2", + "merge2": "^1.3.0", + "micromatch": "^4.0.4" + }, + "engines": { + "node": ">=8.6.0" + } + }, + "node_modules/fast-json-stable-stringify": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/fast-json-stable-stringify/-/fast-json-stable-stringify-2.1.0.tgz", + "integrity": "sha512-lhd/wF+Lk98HZoTCtlVraHtfh5XYijIjalXck7saUtuanSDyLMxnHhSXEDJqHxD7msR8D0uCmqlkwjCV8xvwHw==", + "dev": true + }, + "node_modules/fast-levenshtein": { + "version": "2.0.6", + "resolved": "https://registry.npmjs.org/fast-levenshtein/-/fast-levenshtein-2.0.6.tgz", + "integrity": "sha512-DCXu6Ifhqcks7TZKY3Hxp3y6qphY5SJZmrWMDrKcERSOXWQdMhU9Ig/PYrzyw/ul9jOIyh0N4M0tbC5hodg8dw==", + "dev": true + }, + "node_modules/fastq": { + "version": "1.15.0", + "resolved": "https://registry.npmjs.org/fastq/-/fastq-1.15.0.tgz", + "integrity": "sha512-wBrocU2LCXXa+lWBt8RoIRD89Fi8OdABODa/kEnyeyjS5aZO5/GNvI5sEINADqP/h8M29UHTHUb53sUu5Ihqdw==", + "dev": true, + "dependencies": { + "reusify": "^1.0.4" + } + }, + "node_modules/file-entry-cache": { + "version": "6.0.1", + "resolved": "https://registry.npmjs.org/file-entry-cache/-/file-entry-cache-6.0.1.tgz", + "integrity": "sha512-7Gps/XWymbLk2QLYK4NzpMOrYjMhdIxXuIvy2QBsLE6ljuodKvdkWs/cpyJJ3CVIVpH0Oi1Hvg1ovbMzLdFBBg==", + "dev": true, + "dependencies": { + "flat-cache": "^3.0.4" + }, + "engines": { + "node": "^10.12.0 || >=12.0.0" + } + }, + "node_modules/fill-range": { + "version": "7.0.1", + "resolved": "https://registry.npmjs.org/fill-range/-/fill-range-7.0.1.tgz", + "integrity": "sha512-qOo9F+dMUmC2Lcb4BbVvnKJxTPjCm+RRpe4gDuGrzkL7mEVl/djYSu2OdQ2Pa302N4oqkSg9ir6jaLWJ2USVpQ==", + "dev": true, + "dependencies": { + "to-regex-range": "^5.0.1" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/finalhandler": { + "version": "1.2.0", + "resolved": "https://registry.npmjs.org/finalhandler/-/finalhandler-1.2.0.tgz", + "integrity": "sha512-5uXcUVftlQMFnWC9qu/svkWv3GTd2PfUhK/3PLkYNAe7FbqJMt3515HaxE6eRL74GdsriiwujiawdaB1BpEISg==", + "dev": true, + "dependencies": { + "debug": "2.6.9", + "encodeurl": "~1.0.2", + "escape-html": "~1.0.3", + "on-finished": "2.4.1", + "parseurl": "~1.3.3", + "statuses": "2.0.1", + "unpipe": "~1.0.0" + }, + "engines": { + "node": ">= 0.8" + } + }, + "node_modules/finalhandler/node_modules/debug": { + "version": "2.6.9", + "resolved": "https://registry.npmjs.org/debug/-/debug-2.6.9.tgz", + "integrity": "sha512-bC7ElrdJaJnPbAP+1EotYvqZsb3ecl5wi6Bfi6BJTUcNowp6cvspg0jXznRTKDjm/E7AdgFBVeAPVMNcKGsHMA==", + "dev": true, + "dependencies": { + "ms": "2.0.0" + } + }, + "node_modules/finalhandler/node_modules/ms": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/ms/-/ms-2.0.0.tgz", + "integrity": "sha512-Tpp60P6IUJDTuOq/5Z8cdskzJujfwqfOTkrwIwj7IRISpnkJnT6SyJ4PCPnGMoFjC9ddhal5KVIYtAt97ix05A==", + "dev": true + }, + "node_modules/find-up": { + "version": "4.1.0", + "resolved": "https://registry.npmjs.org/find-up/-/find-up-4.1.0.tgz", + "integrity": "sha512-PpOwAdQ/YlXQ2vj8a3h8IipDuYRi3wceVQQGYWxNINccq40Anw7BlsEXCMbt1Zt+OLA6Fq9suIpIWD0OsnISlw==", + "dev": true, + "dependencies": { + "locate-path": "^5.0.0", + "path-exists": "^4.0.0" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/find-yarn-workspace-root2": { + "version": "1.2.16", + "resolved": "https://registry.npmjs.org/find-yarn-workspace-root2/-/find-yarn-workspace-root2-1.2.16.tgz", + "integrity": "sha512-hr6hb1w8ePMpPVUK39S4RlwJzi+xPLuVuG8XlwXU3KD5Yn3qgBWVfy3AzNlDhWvE1EORCE65/Qm26rFQt3VLVA==", + "dev": true, + "dependencies": { + "micromatch": "^4.0.2", + "pkg-dir": "^4.2.0" + } + }, + "node_modules/flat": { + "version": "5.0.2", + "resolved": "https://registry.npmjs.org/flat/-/flat-5.0.2.tgz", + "integrity": "sha512-b6suED+5/3rTpUBdG1gupIl8MPFCAMA0QXwmljLhvCUKcUvdE4gWky9zpuGCcXHOsz4J9wPGNWq6OKpmIzz3hQ==", + "dev": true, + "bin": { + "flat": "cli.js" + } + }, + "node_modules/flat-cache": { + "version": "3.0.4", + "resolved": "https://registry.npmjs.org/flat-cache/-/flat-cache-3.0.4.tgz", + "integrity": "sha512-dm9s5Pw7Jc0GvMYbshN6zchCA9RgQlzzEZX3vylR9IqFfS8XciblUXOKfW6SiuJ0e13eDYZoZV5wdrev7P3Nwg==", + "dev": true, + "dependencies": { + "flatted": "^3.1.0", + "rimraf": "^3.0.2" + }, + "engines": { + "node": "^10.12.0 || >=12.0.0" + } + }, + "node_modules/flatted": { + "version": "3.2.7", + "resolved": "https://registry.npmjs.org/flatted/-/flatted-3.2.7.tgz", + "integrity": "sha512-5nqDSxl8nn5BSNxyR3n4I6eDmbolI6WT+QqR547RwxQapgjQBmtktdP+HTBb/a/zLsbzERTONyUB5pefh5TtjQ==", + "dev": true + }, + "node_modules/follow-redirects": { + "version": "1.15.2", + "resolved": "https://registry.npmjs.org/follow-redirects/-/follow-redirects-1.15.2.tgz", + "integrity": "sha512-VQLG33o04KaQ8uYi2tVNbdrWp1QWxNNea+nmIB4EVM28v0hmP17z7aG1+wAkNzVq4KeXTq3221ye5qTJP91JwA==", + "dev": true, + "funding": [ + { + "type": "individual", + "url": "https://github.com/sponsors/RubenVerborgh" + } + ], + "engines": { + "node": ">=4.0" + }, + "peerDependenciesMeta": { + "debug": { + "optional": true + } + } + }, + "node_modules/for-each": { + "version": "0.3.3", + "resolved": "https://registry.npmjs.org/for-each/-/for-each-0.3.3.tgz", + "integrity": "sha512-jqYfLp7mo9vIyQf8ykW2v7A+2N4QjeCeI5+Dz9XraiO1ign81wjiH7Fb9vSOWvQfNtmSa4H2RoQTrrXivdUZmw==", + "dev": true, + "dependencies": { + "is-callable": "^1.1.3" + } + }, + "node_modules/forever-agent": { + "version": "0.6.1", + "resolved": "https://registry.npmjs.org/forever-agent/-/forever-agent-0.6.1.tgz", + "integrity": "sha512-j0KLYPhm6zeac4lz3oJ3o65qvgQCcPubiyotZrXqEaG4hNagNYO8qdlUrX5vwqv9ohqeT/Z3j6+yW067yWWdUw==", + "dev": true, + "engines": { + "node": "*" + } + }, + "node_modules/form-data": { + "version": "2.3.3", + "resolved": "https://registry.npmjs.org/form-data/-/form-data-2.3.3.tgz", + "integrity": "sha512-1lLKB2Mu3aGP1Q/2eCOx0fNbRMe7XdwktwOruhfqqd0rIJWwN4Dh+E3hrPSlDCXnSR7UtZ1N38rVXm+6+MEhJQ==", + "dev": true, + "dependencies": { + "asynckit": "^0.4.0", + "combined-stream": "^1.0.6", + "mime-types": "^2.1.12" + }, + "engines": { + "node": ">= 0.12" + } + }, + "node_modules/form-data-encoder": { + "version": "1.7.1", + "resolved": "https://registry.npmjs.org/form-data-encoder/-/form-data-encoder-1.7.1.tgz", + "integrity": "sha512-EFRDrsMm/kyqbTQocNvRXMLjc7Es2Vk+IQFx/YW7hkUH1eBl4J1fqiP34l74Yt0pFLCNpc06fkbVk00008mzjg==", + "dev": true + }, + "node_modules/forwarded": { + "version": "0.2.0", + "resolved": "https://registry.npmjs.org/forwarded/-/forwarded-0.2.0.tgz", + "integrity": "sha512-buRG0fpBtRHSTCOASe6hD258tEubFoRLb4ZNA6NxMVHNw2gOcwHo9wyablzMzOA5z9xA9L1KNjk/Nt6MT9aYow==", + "dev": true, + "engines": { + "node": ">= 0.6" + } + }, + "node_modules/fp-ts": { + "version": "1.19.3", + "resolved": "https://registry.npmjs.org/fp-ts/-/fp-ts-1.19.3.tgz", + "integrity": "sha512-H5KQDspykdHuztLTg+ajGN0Z2qUjcEf3Ybxc6hLt0k7/zPkn29XnKnxlBPyW2XIddWrGaJBzBl4VLYOtk39yZg==", + "dev": true + }, + "node_modules/fresh": { + "version": "0.5.2", + "resolved": "https://registry.npmjs.org/fresh/-/fresh-0.5.2.tgz", + "integrity": "sha512-zJ2mQYM18rEFOudeV4GShTGIQ7RbzA7ozbU9I/XBpm7kqgMywgmylMwXHxZJmkVoYkna9d2pVXVXPdYTP9ej8Q==", + "dev": true, + "engines": { + "node": ">= 0.6" + } + }, + "node_modules/fs-extra": { + "version": "7.0.1", + "resolved": "https://registry.npmjs.org/fs-extra/-/fs-extra-7.0.1.tgz", + "integrity": "sha512-YJDaCJZEnBmcbw13fvdAM9AwNOJwOzrE4pqMqBq5nFiEqXUqHwlK4B+3pUw6JNvfSPtX05xFHtYy/1ni01eGCw==", + "dev": true, + "dependencies": { + "graceful-fs": "^4.1.2", + "jsonfile": "^4.0.0", + "universalify": "^0.1.0" + }, + "engines": { + "node": ">=6 <7 || >=8" + } + }, + "node_modules/fs-minipass": { + "version": "1.2.7", + "resolved": "https://registry.npmjs.org/fs-minipass/-/fs-minipass-1.2.7.tgz", + "integrity": "sha512-GWSSJGFy4e9GUeCcbIkED+bgAoFyj7XF1mV8rma3QW4NIqX9Kyx79N/PF61H5udOV3aY1IaMLs6pGbH71nlCTA==", + "dev": true, + "dependencies": { + "minipass": "^2.6.0" + } + }, + "node_modules/fs-readdir-recursive": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/fs-readdir-recursive/-/fs-readdir-recursive-1.1.0.tgz", + "integrity": "sha512-GNanXlVr2pf02+sPN40XN8HG+ePaNcvM0q5mZBd668Obwb0yD5GiUbZOFgwn8kGMY6I3mdyDJzieUy3PTYyTRA==", + "dev": true + }, + "node_modules/fs.realpath": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/fs.realpath/-/fs.realpath-1.0.0.tgz", + "integrity": "sha512-OO0pH2lK6a0hZnAdau5ItzHPI6pUlvI7jMVnxUQRtw4owF2wk8lOSabtGDCTP4Ggrg2MbGnWO9X8K1t4+fGMDw==", + "dev": true + }, + "node_modules/fsevents": { + "version": "2.3.2", + "resolved": "https://registry.npmjs.org/fsevents/-/fsevents-2.3.2.tgz", + "integrity": "sha512-xiqMQR4xAeHTuB9uWm+fFRcIOgKBMiOBP+eXiyT7jsgVCq1bkVygt00oASowB7EdtpOHaaPgKt812P9ab+DDKA==", + "dev": true, + "hasInstallScript": true, + "optional": true, + "os": [ + "darwin" + ], + "engines": { + "node": "^8.16.0 || ^10.6.0 || >=11.0.0" + } + }, + "node_modules/function-bind": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/function-bind/-/function-bind-1.1.1.tgz", + "integrity": "sha512-yIovAzMX49sF8Yl58fSCWJ5svSLuaibPxXQJFLmBObTuCr0Mf1KiPopGM9NiFjiYBCbfaa2Fh6breQ6ANVTI0A==", + "dev": true + }, + "node_modules/function.prototype.name": { + "version": "1.1.5", + "resolved": "https://registry.npmjs.org/function.prototype.name/-/function.prototype.name-1.1.5.tgz", + "integrity": "sha512-uN7m/BzVKQnCUF/iW8jYea67v++2u7m5UgENbHRtdDVclOUP+FMPlCNdmk0h/ysGyo2tavMJEDqJAkJdRa1vMA==", + "dev": true, + "dependencies": { + "call-bind": "^1.0.2", + "define-properties": "^1.1.3", + "es-abstract": "^1.19.0", + "functions-have-names": "^1.2.2" + }, + "engines": { + "node": ">= 0.4" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/functional-red-black-tree": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/functional-red-black-tree/-/functional-red-black-tree-1.0.1.tgz", + "integrity": "sha512-dsKNQNdj6xA3T+QlADDA7mOSlX0qiMINjn0cgr+eGHGsbSHzTabcIogz2+p/iqP1Xs6EP/sS2SbqH+brGTbq0g==", + "dev": true + }, + "node_modules/functions-have-names": { + "version": "1.2.3", + "resolved": "https://registry.npmjs.org/functions-have-names/-/functions-have-names-1.2.3.tgz", + "integrity": "sha512-xckBUXyTIqT97tq2x2AMb+g163b5JFysYk0x4qxNFwbfQkmNZoiRHb6sPzI9/QV33WeuvVYBUIiD4NzNIyqaRQ==", + "dev": true, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/get-caller-file": { + "version": "2.0.5", + "resolved": "https://registry.npmjs.org/get-caller-file/-/get-caller-file-2.0.5.tgz", + "integrity": "sha512-DyFP3BM/3YHTQOCUL/w0OZHR0lpKeGrxotcHWcqNEdnltqFwXVfhEBQ94eIo34AfQpo0rGki4cyIiftY06h2Fg==", + "dev": true, + "engines": { + "node": "6.* || 8.* || >= 10.*" + } + }, + "node_modules/get-func-name": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/get-func-name/-/get-func-name-2.0.0.tgz", + "integrity": "sha512-Hm0ixYtaSZ/V7C8FJrtZIuBBI+iSgL+1Aq82zSu8VQNB4S3Gk8e7Qs3VwBDJAhmRZcFqkl3tQu36g/Foh5I5ig==", + "dev": true, + "engines": { + "node": "*" + } + }, + "node_modules/get-intrinsic": { + "version": "1.2.1", + "resolved": "https://registry.npmjs.org/get-intrinsic/-/get-intrinsic-1.2.1.tgz", + "integrity": "sha512-2DcsyfABl+gVHEfCOaTrWgyt+tb6MSEGmKq+kI5HwLbIYgjgmMcV8KQ41uaKz1xxUcn9tJtgFbQUEVcEbd0FYw==", + "dev": true, + "dependencies": { + "function-bind": "^1.1.1", + "has": "^1.0.3", + "has-proto": "^1.0.1", + "has-symbols": "^1.0.3" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/get-port": { + "version": "3.2.0", + "resolved": "https://registry.npmjs.org/get-port/-/get-port-3.2.0.tgz", + "integrity": "sha512-x5UJKlgeUiNT8nyo/AcnwLnZuZNcSjSw0kogRB+Whd1fjjFq4B1hySFxSFWWSn4mIBzg3sRNUDFYc4g5gjPoLg==", + "dev": true, + "engines": { + "node": ">=4" + } + }, + "node_modules/get-stream": { + "version": "6.0.1", + "resolved": "https://registry.npmjs.org/get-stream/-/get-stream-6.0.1.tgz", + "integrity": "sha512-ts6Wi+2j3jQjqi70w5AlN8DFnkSwC+MqmxEzdEALB2qXZYV3X/b1CTfgPLGJNMeAWxdPfU8FO1ms3NUfaHCPYg==", + "dev": true, + "engines": { + "node": ">=10" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/get-symbol-description": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/get-symbol-description/-/get-symbol-description-1.0.0.tgz", + "integrity": "sha512-2EmdH1YvIQiZpltCNgkuiUnyukzxM/R6NDJX31Ke3BG1Nq5b0S2PhX59UKi9vZpPDQVdqn+1IcaAwnzTT5vCjw==", + "dev": true, + "dependencies": { + "call-bind": "^1.0.2", + "get-intrinsic": "^1.1.1" + }, + "engines": { + "node": ">= 0.4" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/getpass": { + "version": "0.1.7", + "resolved": "https://registry.npmjs.org/getpass/-/getpass-0.1.7.tgz", + "integrity": "sha512-0fzj9JxOLfJ+XGLhR8ze3unN0KZCgZwiSSDz168VERjK8Wl8kVSdcu2kspd4s4wtAa1y/qrVRiAA0WclVsu0ng==", + "dev": true, + "dependencies": { + "assert-plus": "^1.0.0" + } + }, + "node_modules/ghost-testrpc": { + "version": "0.0.2", + "resolved": "https://registry.npmjs.org/ghost-testrpc/-/ghost-testrpc-0.0.2.tgz", + "integrity": "sha512-i08dAEgJ2g8z5buJIrCTduwPIhih3DP+hOCTyyryikfV8T0bNvHnGXO67i0DD1H4GBDETTclPy9njZbfluQYrQ==", + "dev": true, + "dependencies": { + "chalk": "^2.4.2", + "node-emoji": "^1.10.0" + }, + "bin": { + "testrpc-sc": "index.js" + } + }, + "node_modules/glob": { + "version": "8.1.0", + "resolved": "https://registry.npmjs.org/glob/-/glob-8.1.0.tgz", + "integrity": "sha512-r8hpEjiQEYlF2QU0df3dS+nxxSIreXQS1qRhMJM0Q5NDdR386C7jb7Hwwod8Fgiuex+k0GFjgft18yvxm5XoCQ==", + "dev": true, + "dependencies": { + "fs.realpath": "^1.0.0", + "inflight": "^1.0.4", + "inherits": "2", + "minimatch": "^5.0.1", + "once": "^1.3.0" + }, + "engines": { + "node": ">=12" + }, + "funding": { + "url": "https://github.com/sponsors/isaacs" + } + }, + "node_modules/glob-parent": { + "version": "5.1.2", + "resolved": "https://registry.npmjs.org/glob-parent/-/glob-parent-5.1.2.tgz", + "integrity": "sha512-AOIgSQCepiJYwP3ARnGx+5VnTu2HBYdzbGP45eLw1vr3zB3vZLeyed1sC9hnbcOc9/SrMyM5RPQrkGz4aS9Zow==", + "dev": true, + "dependencies": { + "is-glob": "^4.0.1" + }, + "engines": { + "node": ">= 6" + } + }, + "node_modules/glob/node_modules/brace-expansion": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-2.0.1.tgz", + "integrity": "sha512-XnAIvQ8eM+kC6aULx6wuQiwVsnzsi9d3WxzV3FpWTGA19F621kwdbsAcFKXgKUHZWsy+mY6iL1sHTxWEFCytDA==", + "dev": true, + "dependencies": { + "balanced-match": "^1.0.0" + } + }, + "node_modules/glob/node_modules/minimatch": { + "version": "5.1.6", + "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-5.1.6.tgz", + "integrity": "sha512-lKwV/1brpG6mBUFHtb7NUmtABCb2WZZmm2wNiOA5hAb8VdCS4B3dtMWyvcoViccwAW/COERjXLt0zP1zXUN26g==", + "dev": true, + "dependencies": { + "brace-expansion": "^2.0.1" + }, + "engines": { + "node": ">=10" + } + }, + "node_modules/global": { + "version": "4.4.0", + "resolved": "https://registry.npmjs.org/global/-/global-4.4.0.tgz", + "integrity": "sha512-wv/LAoHdRE3BeTGz53FAamhGlPLhlssK45usmGFThIi4XqnBmjKQ16u+RNbP7WvigRZDxUsM0J3gcQ5yicaL0w==", + "dev": true, + "dependencies": { + "min-document": "^2.19.0", + "process": "^0.11.10" + } + }, + "node_modules/global-modules": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/global-modules/-/global-modules-2.0.0.tgz", + "integrity": "sha512-NGbfmJBp9x8IxyJSd1P+otYK8vonoJactOogrVfFRIAEY1ukil8RSKDz2Yo7wh1oihl51l/r6W4epkeKJHqL8A==", + "dev": true, + "dependencies": { + "global-prefix": "^3.0.0" + }, + "engines": { + "node": ">=6" + } + }, + "node_modules/global-prefix": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/global-prefix/-/global-prefix-3.0.0.tgz", + "integrity": "sha512-awConJSVCHVGND6x3tmMaKcQvwXLhjdkmomy2W+Goaui8YPgYgXJZewhg3fWC+DlfqqQuWg8AwqjGTD2nAPVWg==", + "dev": true, + "dependencies": { + "ini": "^1.3.5", + "kind-of": "^6.0.2", + "which": "^1.3.1" + }, + "engines": { + "node": ">=6" + } + }, + "node_modules/global-prefix/node_modules/which": { + "version": "1.3.1", + "resolved": "https://registry.npmjs.org/which/-/which-1.3.1.tgz", + "integrity": "sha512-HxJdYWq1MTIQbJ3nw0cqssHoTNU267KlrDuGZ1WYlxDStUtKUhOaJmh112/TZmHxxUfuJqPXSOm7tDyas0OSIQ==", + "dev": true, + "dependencies": { + "isexe": "^2.0.0" + }, + "bin": { + "which": "bin/which" + } + }, + "node_modules/globals": { + "version": "13.20.0", + "resolved": "https://registry.npmjs.org/globals/-/globals-13.20.0.tgz", + "integrity": "sha512-Qg5QtVkCy/kv3FUSlu4ukeZDVf9ee0iXLAUYX13gbR17bnejFTzr4iS9bY7kwCf1NztRNm1t91fjOiyx4CSwPQ==", + "dev": true, + "dependencies": { + "type-fest": "^0.20.2" + }, + "engines": { + "node": ">=8" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/globalthis": { + "version": "1.0.3", + "resolved": "https://registry.npmjs.org/globalthis/-/globalthis-1.0.3.tgz", + "integrity": "sha512-sFdI5LyBiNTHjRd7cGPWapiHWMOXKyuBNX/cWJ3NfzrZQVa8GI/8cofCl74AOVqq9W5kNmguTIzJ/1s2gyI9wA==", + "dev": true, + "dependencies": { + "define-properties": "^1.1.3" + }, + "engines": { + "node": ">= 0.4" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/globby": { + "version": "11.1.0", + "resolved": "https://registry.npmjs.org/globby/-/globby-11.1.0.tgz", + "integrity": "sha512-jhIXaOzy1sb8IyocaruWSn1TjmnBVs8Ayhcy83rmxNJ8q2uWKCAj3CnJY+KpGSXCueAPc0i05kVvVKtP1t9S3g==", + "dev": true, + "dependencies": { + "array-union": "^2.1.0", + "dir-glob": "^3.0.1", + "fast-glob": "^3.2.9", + "ignore": "^5.2.0", + "merge2": "^1.4.1", + "slash": "^3.0.0" + }, + "engines": { + "node": ">=10" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/gopd": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/gopd/-/gopd-1.0.1.tgz", + "integrity": "sha512-d65bNlIadxvpb/A2abVdlqKqV563juRnZ1Wtk6s1sIR8uNsXR70xqIzVqxVf1eTqDunwT2MkczEeaezCKTZhwA==", + "dev": true, + "dependencies": { + "get-intrinsic": "^1.1.3" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/got": { + "version": "12.1.0", + "resolved": "https://registry.npmjs.org/got/-/got-12.1.0.tgz", + "integrity": "sha512-hBv2ty9QN2RdbJJMK3hesmSkFTjVIHyIDDbssCKnSmq62edGgImJWD10Eb1k77TiV1bxloxqcFAVK8+9pkhOig==", + "dev": true, + "dependencies": { + "@sindresorhus/is": "^4.6.0", + "@szmarczak/http-timer": "^5.0.1", + "@types/cacheable-request": "^6.0.2", + "@types/responselike": "^1.0.0", + "cacheable-lookup": "^6.0.4", + "cacheable-request": "^7.0.2", + "decompress-response": "^6.0.0", + "form-data-encoder": "1.7.1", + "get-stream": "^6.0.1", + "http2-wrapper": "^2.1.10", + "lowercase-keys": "^3.0.0", + "p-cancelable": "^3.0.0", + "responselike": "^2.0.0" + }, + "engines": { + "node": ">=14.16" + }, + "funding": { + "url": "https://github.com/sindresorhus/got?sponsor=1" + } + }, + "node_modules/graceful-fs": { + "version": "4.2.11", + "resolved": "https://registry.npmjs.org/graceful-fs/-/graceful-fs-4.2.11.tgz", + "integrity": "sha512-RbJ5/jmFcNNCcDV5o9eTnBLJ/HszWV0P73bc+Ff4nS/rJj+YaS6IGyiOL0VoBYX+l1Wrl3k63h/KrH+nhJ0XvQ==", + "dev": true + }, + "node_modules/grapheme-splitter": { + "version": "1.0.4", + "resolved": "https://registry.npmjs.org/grapheme-splitter/-/grapheme-splitter-1.0.4.tgz", + "integrity": "sha512-bzh50DW9kTPM00T8y4o8vQg89Di9oLJVLW/KaOGIXJWP/iqCN6WKYkbNOF04vFLJhwcpYUh9ydh/+5vpOqV4YQ==", + "dev": true + }, + "node_modules/graphemer": { + "version": "1.4.0", + "resolved": "https://registry.npmjs.org/graphemer/-/graphemer-1.4.0.tgz", + "integrity": "sha512-EtKwoO6kxCL9WO5xipiHTZlSzBm7WLT627TqC/uVRd0HKmq8NXyebnNYxDoBi7wt8eTWrUrKXCOVaFq9x1kgag==", + "dev": true + }, + "node_modules/graphlib": { + "version": "2.1.8", + "resolved": "https://registry.npmjs.org/graphlib/-/graphlib-2.1.8.tgz", + "integrity": "sha512-jcLLfkpoVGmH7/InMC/1hIvOPSUh38oJtGhvrOFGzioE1DZ+0YW16RgmOJhHiuWTvGiJQ9Z1Ik43JvkRPRvE+A==", + "dev": true, + "dependencies": { + "lodash": "^4.17.15" + } + }, + "node_modules/growl": { + "version": "1.10.5", + "resolved": "https://registry.npmjs.org/growl/-/growl-1.10.5.tgz", + "integrity": "sha512-qBr4OuELkhPenW6goKVXiv47US3clb3/IbuWF9KNKEijAy9oeHxU9IgzjvJhHkUzhaj7rOUD7+YGWqUjLp5oSA==", + "dev": true, + "engines": { + "node": ">=4.x" + } + }, + "node_modules/handlebars": { + "version": "4.7.7", + "resolved": "https://registry.npmjs.org/handlebars/-/handlebars-4.7.7.tgz", + "integrity": "sha512-aAcXm5OAfE/8IXkcZvCepKU3VzW1/39Fb5ZuqMtgI/hT8X2YgoMvBY5dLhq/cpOvw7Lk1nK/UF71aLG/ZnVYRA==", + "dev": true, + "dependencies": { + "minimist": "^1.2.5", + "neo-async": "^2.6.0", + "source-map": "^0.6.1", + "wordwrap": "^1.0.0" + }, + "bin": { + "handlebars": "bin/handlebars" + }, + "engines": { + "node": ">=0.4.7" + }, + "optionalDependencies": { + "uglify-js": "^3.1.4" + } + }, + "node_modules/handlebars/node_modules/source-map": { + "version": "0.6.1", + "resolved": "https://registry.npmjs.org/source-map/-/source-map-0.6.1.tgz", + "integrity": "sha512-UjgapumWlbMhkBgzT7Ykc5YXUT46F0iKu8SGXq0bcwP5dz/h0Plj6enJqjz1Zbq2l5WaqYnrVbwWOWMyF3F47g==", + "dev": true, + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/har-schema": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/har-schema/-/har-schema-2.0.0.tgz", + "integrity": "sha512-Oqluz6zhGX8cyRaTQlFMPw80bSJVG2x/cFb8ZPhUILGgHka9SsokCCOQgpveePerqidZOrT14ipqfJb7ILcW5Q==", + "dev": true, + "engines": { + "node": ">=4" + } + }, + "node_modules/har-validator": { + "version": "5.1.5", + "resolved": "https://registry.npmjs.org/har-validator/-/har-validator-5.1.5.tgz", + "integrity": "sha512-nmT2T0lljbxdQZfspsno9hgrG3Uir6Ks5afism62poxqBM6sDnMEuPmzTq8XN0OEwqKLLdh1jQI3qyE66Nzb3w==", + "deprecated": "this library is no longer supported", + "dev": true, + "dependencies": { + "ajv": "^6.12.3", + "har-schema": "^2.0.0" + }, + "engines": { + "node": ">=6" + } + }, + "node_modules/hard-rejection": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/hard-rejection/-/hard-rejection-2.1.0.tgz", + "integrity": "sha512-VIZB+ibDhx7ObhAe7OVtoEbuP4h/MuOTHJ+J8h/eBXotJYl0fBgR72xDFCKgIh22OJZIOVNxBMWuhAr10r8HdA==", + "dev": true, + "engines": { + "node": ">=6" + } + }, + "node_modules/hardhat": { + "version": "2.16.1", + "resolved": "https://registry.npmjs.org/hardhat/-/hardhat-2.16.1.tgz", + "integrity": "sha512-QpBjGXFhhSYoYBGEHyoau/A63crZOP+i3GbNxzLGkL6IklzT+piN14+wGnINNCg5BLSKisQI/RAySPzaWRcx/g==", + "dev": true, + "dependencies": { + "@ethersproject/abi": "^5.1.2", + "@metamask/eth-sig-util": "^4.0.0", + "@nomicfoundation/ethereumjs-block": "5.0.1", + "@nomicfoundation/ethereumjs-blockchain": "7.0.1", + "@nomicfoundation/ethereumjs-common": "4.0.1", + "@nomicfoundation/ethereumjs-evm": "2.0.1", + "@nomicfoundation/ethereumjs-rlp": "5.0.1", + "@nomicfoundation/ethereumjs-statemanager": "2.0.1", + "@nomicfoundation/ethereumjs-trie": "6.0.1", + "@nomicfoundation/ethereumjs-tx": "5.0.1", + "@nomicfoundation/ethereumjs-util": "9.0.1", + "@nomicfoundation/ethereumjs-vm": "7.0.1", + "@nomicfoundation/solidity-analyzer": "^0.1.0", + "@sentry/node": "^5.18.1", + "@types/bn.js": "^5.1.0", + "@types/lru-cache": "^5.1.0", + "abort-controller": "^3.0.0", + "adm-zip": "^0.4.16", + "aggregate-error": "^3.0.0", + "ansi-escapes": "^4.3.0", + "chalk": "^2.4.2", + "chokidar": "^3.4.0", + "ci-info": "^2.0.0", + "debug": "^4.1.1", + "enquirer": "^2.3.0", + "env-paths": "^2.2.0", + "ethereum-cryptography": "^1.0.3", + "ethereumjs-abi": "^0.6.8", + "find-up": "^2.1.0", + "fp-ts": "1.19.3", + "fs-extra": "^7.0.1", + "glob": "7.2.0", + "immutable": "^4.0.0-rc.12", + "io-ts": "1.10.4", + "keccak": "^3.0.2", + "lodash": "^4.17.11", + "mnemonist": "^0.38.0", + "mocha": "^10.0.0", + "p-map": "^4.0.0", + "raw-body": "^2.4.1", + "resolve": "1.17.0", + "semver": "^6.3.0", + "solc": "0.7.3", + "source-map-support": "^0.5.13", + "stacktrace-parser": "^0.1.10", + "tsort": "0.0.1", + "undici": "^5.14.0", + "uuid": "^8.3.2", + "ws": "^7.4.6" + }, + "bin": { + "hardhat": "internal/cli/bootstrap.js" + }, + "engines": { + "node": ">=14.0.0" + }, + "peerDependencies": { + "ts-node": "*", + "typescript": "*" + }, + "peerDependenciesMeta": { + "ts-node": { + "optional": true + }, + "typescript": { + "optional": true + } + } + }, + "node_modules/hardhat-exposed": { + "version": "0.3.11", + "resolved": "https://registry.npmjs.org/hardhat-exposed/-/hardhat-exposed-0.3.11.tgz", + "integrity": "sha512-2Gwdfx1YpSWUX80kuq0zM1tNqDJoTBCd5Q5oXKPxz6STSy1TiDyDb1miUr4Dwc/Dp2lzWzM+fZjpUrMe5O08Hw==", + "dev": true, + "dependencies": { + "micromatch": "^4.0.4", + "solidity-ast": "^0.4.25" + }, + "peerDependencies": { + "hardhat": "^2.3.0" + } + }, + "node_modules/hardhat-gas-reporter": { + "version": "1.0.9", + "resolved": "https://registry.npmjs.org/hardhat-gas-reporter/-/hardhat-gas-reporter-1.0.9.tgz", + "integrity": "sha512-INN26G3EW43adGKBNzYWOlI3+rlLnasXTwW79YNnUhXPDa+yHESgt639dJEs37gCjhkbNKcRRJnomXEuMFBXJg==", + "dev": true, + "dependencies": { + "array-uniq": "1.0.3", + "eth-gas-reporter": "^0.2.25", + "sha1": "^1.1.1" + }, + "peerDependencies": { + "hardhat": "^2.0.2" + } + }, + "node_modules/hardhat-ignore-warnings": { + "version": "0.2.9", + "resolved": "https://registry.npmjs.org/hardhat-ignore-warnings/-/hardhat-ignore-warnings-0.2.9.tgz", + "integrity": "sha512-q1oj6/ixiAx+lgIyGLBajVCSC7qUtAoK7LS9Nr8UVHYo8Iuh5naBiVGo4RDJ6wxbDGYBkeSukUGZrMqzC2DWwA==", + "dev": true, + "dependencies": { + "minimatch": "^5.1.0", + "node-interval-tree": "^2.0.1", + "solidity-comments": "^0.0.2" + } + }, + "node_modules/hardhat-ignore-warnings/node_modules/brace-expansion": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-2.0.1.tgz", + "integrity": "sha512-XnAIvQ8eM+kC6aULx6wuQiwVsnzsi9d3WxzV3FpWTGA19F621kwdbsAcFKXgKUHZWsy+mY6iL1sHTxWEFCytDA==", + "dev": true, + "dependencies": { + "balanced-match": "^1.0.0" + } + }, + "node_modules/hardhat-ignore-warnings/node_modules/minimatch": { + "version": "5.1.6", + "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-5.1.6.tgz", + "integrity": "sha512-lKwV/1brpG6mBUFHtb7NUmtABCb2WZZmm2wNiOA5hAb8VdCS4B3dtMWyvcoViccwAW/COERjXLt0zP1zXUN26g==", + "dev": true, + "dependencies": { + "brace-expansion": "^2.0.1" + }, + "engines": { + "node": ">=10" + } + }, + "node_modules/hardhat/node_modules/ci-info": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/ci-info/-/ci-info-2.0.0.tgz", + "integrity": "sha512-5tK7EtrZ0N+OLFMthtqOj4fI2Jeb88C4CAZPu25LDVUgXJ0A3Js4PMGqrn0JU1W0Mh1/Z8wZzYPxqUrXeBboCQ==", + "dev": true + }, + "node_modules/hardhat/node_modules/commander": { + "version": "3.0.2", + "resolved": "https://registry.npmjs.org/commander/-/commander-3.0.2.tgz", + "integrity": "sha512-Gar0ASD4BDyKC4hl4DwHqDrmvjoxWKZigVnAbn5H1owvm4CxCPdb0HQDehwNYMJpla5+M2tPmPARzhtYuwpHow==", + "dev": true + }, + "node_modules/hardhat/node_modules/ethereum-cryptography": { + "version": "1.2.0", + "resolved": "https://registry.npmjs.org/ethereum-cryptography/-/ethereum-cryptography-1.2.0.tgz", + "integrity": "sha512-6yFQC9b5ug6/17CQpCyE3k9eKBMdhyVjzUy1WkiuY/E4vj/SXDBbCw8QEIaXqf0Mf2SnY6RmpDcwlUmBSS0EJw==", + "dev": true, + "dependencies": { + "@noble/hashes": "1.2.0", + "@noble/secp256k1": "1.7.1", + "@scure/bip32": "1.1.5", + "@scure/bip39": "1.1.1" + } + }, + "node_modules/hardhat/node_modules/find-up": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/find-up/-/find-up-2.1.0.tgz", + "integrity": "sha512-NWzkk0jSJtTt08+FBFMvXoeZnOJD+jTtsRmBYbAIzJdX6l7dLgR7CTubCM5/eDdPUBvLCeVasP1brfVR/9/EZQ==", + "dev": true, + "dependencies": { + "locate-path": "^2.0.0" + }, + "engines": { + "node": ">=4" + } + }, + "node_modules/hardhat/node_modules/glob": { + "version": "7.2.0", + "resolved": "https://registry.npmjs.org/glob/-/glob-7.2.0.tgz", + "integrity": "sha512-lmLf6gtyrPq8tTjSmrO94wBeQbFR3HbLHbuyD69wuyQkImp2hWqMGB47OX65FBkPffO641IP9jWa1z4ivqG26Q==", + "dev": true, + "dependencies": { + "fs.realpath": "^1.0.0", + "inflight": "^1.0.4", + "inherits": "2", + "minimatch": "^3.0.4", + "once": "^1.3.0", + "path-is-absolute": "^1.0.0" + }, + "engines": { + "node": "*" + }, + "funding": { + "url": "https://github.com/sponsors/isaacs" + } + }, + "node_modules/hardhat/node_modules/jsonfile": { + "version": "2.4.0", + "resolved": "https://registry.npmjs.org/jsonfile/-/jsonfile-2.4.0.tgz", + "integrity": "sha512-PKllAqbgLgxHaj8TElYymKCAgrASebJrWpTnEkOaTowt23VKXXN0sUeriJ+eh7y6ufb/CC5ap11pz71/cM0hUw==", + "dev": true, + "optionalDependencies": { + "graceful-fs": "^4.1.6" + } + }, + "node_modules/hardhat/node_modules/locate-path": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/locate-path/-/locate-path-2.0.0.tgz", + "integrity": "sha512-NCI2kiDkyR7VeEKm27Kda/iQHyKJe1Bu0FlTbYp3CqJu+9IFe9bLyAjMxf5ZDDbEg+iMPzB5zYyUTSm8wVTKmA==", + "dev": true, + "dependencies": { + "p-locate": "^2.0.0", + "path-exists": "^3.0.0" + }, + "engines": { + "node": ">=4" + } + }, + "node_modules/hardhat/node_modules/p-limit": { + "version": "1.3.0", + "resolved": "https://registry.npmjs.org/p-limit/-/p-limit-1.3.0.tgz", + "integrity": "sha512-vvcXsLAJ9Dr5rQOPk7toZQZJApBl2K4J6dANSsEuh6QI41JYcsS/qhTGa9ErIUUgK3WNQoJYvylxvjqmiqEA9Q==", + "dev": true, + "dependencies": { + "p-try": "^1.0.0" + }, + "engines": { + "node": ">=4" + } + }, + "node_modules/hardhat/node_modules/p-locate": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/p-locate/-/p-locate-2.0.0.tgz", + "integrity": "sha512-nQja7m7gSKuewoVRen45CtVfODR3crN3goVQ0DDZ9N3yHxgpkuBhZqsaiotSQRrADUrne346peY7kT3TSACykg==", + "dev": true, + "dependencies": { + "p-limit": "^1.1.0" + }, + "engines": { + "node": ">=4" + } + }, + "node_modules/hardhat/node_modules/p-try": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/p-try/-/p-try-1.0.0.tgz", + "integrity": "sha512-U1etNYuMJoIz3ZXSrrySFjsXQTWOx2/jdi86L+2pRvph/qMKL6sbcCYdH23fqsbm8TH2Gn0OybpT4eSFlCVHww==", + "dev": true, + "engines": { + "node": ">=4" + } + }, + "node_modules/hardhat/node_modules/path-exists": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/path-exists/-/path-exists-3.0.0.tgz", + "integrity": "sha512-bpC7GYwiDYQ4wYLe+FA8lhRjhQCMcQGuSgGGqDkg/QerRWw9CmGRT0iSOVRSZJ29NMLZgIzqaljJ63oaL4NIJQ==", + "dev": true, + "engines": { + "node": ">=4" + } + }, + "node_modules/hardhat/node_modules/require-from-string": { + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/require-from-string/-/require-from-string-2.0.2.tgz", + "integrity": "sha512-Xf0nWe6RseziFMu+Ap9biiUbmplq6S9/p+7w7YXP/JBHhrUDDUhwa+vANyubuqfZWTveU//DYVGsDG7RKL/vEw==", + "dev": true, + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/hardhat/node_modules/rimraf": { + "version": "2.7.1", + "resolved": "https://registry.npmjs.org/rimraf/-/rimraf-2.7.1.tgz", + "integrity": "sha512-uWjbaKIK3T1OSVptzX7Nl6PvQ3qAGtKEtVRjRuazjfL3Bx5eI409VZSqgND+4UNnmzLVdPj9FqFJNPqBZFve4w==", + "dev": true, + "dependencies": { + "glob": "^7.1.3" + }, + "bin": { + "rimraf": "bin.js" + } + }, + "node_modules/hardhat/node_modules/semver": { + "version": "6.3.0", + "resolved": "https://registry.npmjs.org/semver/-/semver-6.3.0.tgz", + "integrity": "sha512-b39TBaTSfV6yBrapU89p5fKekE2m/NwnDocOVruQFS1/veMgdzuPcnOM34M6CwxW8jH/lxEa5rBoDeUwu5HHTw==", + "dev": true, + "bin": { + "semver": "bin/semver.js" + } + }, + "node_modules/hardhat/node_modules/solc": { + "version": "0.7.3", + "resolved": "https://registry.npmjs.org/solc/-/solc-0.7.3.tgz", + "integrity": "sha512-GAsWNAjGzIDg7VxzP6mPjdurby3IkGCjQcM8GFYZT6RyaoUZKmMU6Y7YwG+tFGhv7dwZ8rmR4iwFDrrD99JwqA==", + "dev": true, + "dependencies": { + "command-exists": "^1.2.8", + "commander": "3.0.2", + "follow-redirects": "^1.12.1", + "fs-extra": "^0.30.0", + "js-sha3": "0.8.0", + "memorystream": "^0.3.1", + "require-from-string": "^2.0.0", + "semver": "^5.5.0", + "tmp": "0.0.33" + }, + "bin": { + "solcjs": "solcjs" + }, + "engines": { + "node": ">=8.0.0" + } + }, + "node_modules/hardhat/node_modules/solc/node_modules/fs-extra": { + "version": "0.30.0", + "resolved": "https://registry.npmjs.org/fs-extra/-/fs-extra-0.30.0.tgz", + "integrity": "sha512-UvSPKyhMn6LEd/WpUaV9C9t3zATuqoqfWc3QdPhPLb58prN9tqYPlPWi8Krxi44loBoUzlobqZ3+8tGpxxSzwA==", + "dev": true, + "dependencies": { + "graceful-fs": "^4.1.2", + "jsonfile": "^2.1.0", + "klaw": "^1.0.0", + "path-is-absolute": "^1.0.0", + "rimraf": "^2.2.8" + } + }, + "node_modules/hardhat/node_modules/solc/node_modules/semver": { + "version": "5.7.1", + "resolved": "https://registry.npmjs.org/semver/-/semver-5.7.1.tgz", + "integrity": "sha512-sauaDf/PZdVgrLTNYHRtpXa1iRiKcaebiKQ1BJdpQlWH2lCvexQdX55snPFyK7QzpudqbCI0qXFfOasHdyNDGQ==", + "dev": true, + "bin": { + "semver": "bin/semver" + } + }, + "node_modules/has": { + "version": "1.0.3", + "resolved": "https://registry.npmjs.org/has/-/has-1.0.3.tgz", + "integrity": "sha512-f2dvO0VU6Oej7RkWJGrehjbzMAjFp5/VKPp5tTpWIV4JHHZK1/BxbFRtf/siA2SWTe09caDmVtYYzWEIbBS4zw==", + "dev": true, + "dependencies": { + "function-bind": "^1.1.1" + }, + "engines": { + "node": ">= 0.4.0" + } + }, + "node_modules/has-bigints": { + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/has-bigints/-/has-bigints-1.0.2.tgz", + "integrity": "sha512-tSvCKtBr9lkF0Ex0aQiP9N+OpV4zi2r/Nee5VkRDbaqv35RLYMzbwQfFSZZH0kR+Rd6302UJZ2p/bJCEoR3VoQ==", + "dev": true, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/has-flag": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/has-flag/-/has-flag-3.0.0.tgz", + "integrity": "sha512-sKJf1+ceQBr4SMkvQnBDNDtf4TXpVhVGateu0t918bl30FnbE2m4vNLX+VWe/dpjlb+HugGYzW7uQXH98HPEYw==", + "dev": true, + "engines": { + "node": ">=4" + } + }, + "node_modules/has-property-descriptors": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/has-property-descriptors/-/has-property-descriptors-1.0.0.tgz", + "integrity": "sha512-62DVLZGoiEBDHQyqG4w9xCuZ7eJEwNmJRWw2VY84Oedb7WFcA27fiEVe8oUQx9hAUJ4ekurquucTGwsyO1XGdQ==", + "dev": true, + "dependencies": { + "get-intrinsic": "^1.1.1" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/has-proto": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/has-proto/-/has-proto-1.0.1.tgz", + "integrity": "sha512-7qE+iP+O+bgF9clE5+UoBFzE65mlBiVj3tKCrlNQ0Ogwm0BjpT/gK4SlLYDMybDh5I3TCTKnPPa0oMG7JDYrhg==", + "dev": true, + "engines": { + "node": ">= 0.4" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/has-symbols": { + "version": "1.0.3", + "resolved": "https://registry.npmjs.org/has-symbols/-/has-symbols-1.0.3.tgz", + "integrity": "sha512-l3LCuF6MgDNwTDKkdYGEihYjt5pRPbEg46rtlmnSPlUbgmB8LOIrKJbYYFBSbnPaJexMKtiPO8hmeRjRz2Td+A==", + "dev": true, + "engines": { + "node": ">= 0.4" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/has-tostringtag": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/has-tostringtag/-/has-tostringtag-1.0.0.tgz", + "integrity": "sha512-kFjcSNhnlGV1kyoGk7OXKSawH5JOb/LzUc5w9B02hOTO0dfFRjbHQKvg1d6cf3HbeUmtU9VbbV3qzZ2Teh97WQ==", + "dev": true, + "dependencies": { + "has-symbols": "^1.0.2" + }, + "engines": { + "node": ">= 0.4" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/hash-base": { + "version": "3.1.0", + "resolved": "https://registry.npmjs.org/hash-base/-/hash-base-3.1.0.tgz", + "integrity": "sha512-1nmYp/rhMDiE7AYkDw+lLwlAzz0AntGIe51F3RfFfEqyQ3feY2eI/NcwC6umIQVOASPMsWJLJScWKSSvzL9IVA==", + "dev": true, + "dependencies": { + "inherits": "^2.0.4", + "readable-stream": "^3.6.0", + "safe-buffer": "^5.2.0" + }, + "engines": { + "node": ">=4" + } + }, + "node_modules/hash.js": { + "version": "1.1.7", + "resolved": "https://registry.npmjs.org/hash.js/-/hash.js-1.1.7.tgz", + "integrity": "sha512-taOaskGt4z4SOANNseOviYDvjEJinIkRgmp7LbKP2YTTmVxWBl87s/uzK9r+44BclBSp2X7K1hqeNfz9JbBeXA==", + "dev": true, + "dependencies": { + "inherits": "^2.0.3", + "minimalistic-assert": "^1.0.1" + } + }, + "node_modules/he": { + "version": "1.2.0", + "resolved": "https://registry.npmjs.org/he/-/he-1.2.0.tgz", + "integrity": "sha512-F/1DnUGPopORZi0ni+CvrCgHQ5FyEAHRLSApuYWMmrbSwoN2Mn/7k+Gl38gJnR7yyDZk6WLXwiGod1JOWNDKGw==", + "dev": true, + "bin": { + "he": "bin/he" + } + }, + "node_modules/header-case": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/header-case/-/header-case-1.0.1.tgz", + "integrity": "sha512-i0q9mkOeSuhXw6bGgiQCCBgY/jlZuV/7dZXyZ9c6LcBrqwvT8eT719E9uxE5LiZftdl+z81Ugbg/VvXV4OJOeQ==", + "dev": true, + "dependencies": { + "no-case": "^2.2.0", + "upper-case": "^1.1.3" + } + }, + "node_modules/heap": { + "version": "0.2.7", + "resolved": "https://registry.npmjs.org/heap/-/heap-0.2.7.tgz", + "integrity": "sha512-2bsegYkkHO+h/9MGbn6KWcE45cHZgPANo5LXF7EvWdT0yT2EguSVO1nDgU5c8+ZOPwp2vMNa7YFsJhVcDR9Sdg==", + "dev": true + }, + "node_modules/highlight.js": { + "version": "10.7.3", + "resolved": "https://registry.npmjs.org/highlight.js/-/highlight.js-10.7.3.tgz", + "integrity": "sha512-tzcUFauisWKNHaRkN4Wjl/ZA07gENAjFl3J/c480dprkGTg5EQstgaNFqBfUqCq54kZRIEcreTsAgF/m2quD7A==", + "dev": true, + "engines": { + "node": "*" + } + }, + "node_modules/highlightjs-solidity": { + "version": "2.0.6", + "resolved": "https://registry.npmjs.org/highlightjs-solidity/-/highlightjs-solidity-2.0.6.tgz", + "integrity": "sha512-DySXWfQghjm2l6a/flF+cteroJqD4gI8GSdL4PtvxZSsAHie8m3yVe2JFoRg03ROKT6hp2Lc/BxXkqerNmtQYg==", + "dev": true + }, + "node_modules/hmac-drbg": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/hmac-drbg/-/hmac-drbg-1.0.1.tgz", + "integrity": "sha512-Tti3gMqLdZfhOQY1Mzf/AanLiqh1WTiJgEj26ZuYQ9fbkLomzGchCws4FyrSd4VkpBfiNhaE1On+lOz894jvXg==", + "dev": true, + "dependencies": { + "hash.js": "^1.0.3", + "minimalistic-assert": "^1.0.0", + "minimalistic-crypto-utils": "^1.0.1" + } + }, + "node_modules/hosted-git-info": { + "version": "2.8.9", + "resolved": "https://registry.npmjs.org/hosted-git-info/-/hosted-git-info-2.8.9.tgz", + "integrity": "sha512-mxIDAb9Lsm6DoOJ7xH+5+X4y1LU/4Hi50L9C5sIswK3JzULS4bwk1FvjdBgvYR4bzT4tuUQiC15FE2f5HbLvYw==", + "dev": true + }, + "node_modules/htmlparser2": { + "version": "8.0.2", + "resolved": "https://registry.npmjs.org/htmlparser2/-/htmlparser2-8.0.2.tgz", + "integrity": "sha512-GYdjWKDkbRLkZ5geuHs5NY1puJ+PXwP7+fHPRz06Eirsb9ugf6d8kkXav6ADhcODhFFPMIXyxkxSuMf3D6NCFA==", + "dev": true, + "funding": [ + "https://github.com/fb55/htmlparser2?sponsor=1", + { + "type": "github", + "url": "https://github.com/sponsors/fb55" + } + ], + "dependencies": { + "domelementtype": "^2.3.0", + "domhandler": "^5.0.3", + "domutils": "^3.0.1", + "entities": "^4.4.0" + } + }, + "node_modules/http-basic": { + "version": "8.1.3", + "resolved": "https://registry.npmjs.org/http-basic/-/http-basic-8.1.3.tgz", + "integrity": "sha512-/EcDMwJZh3mABI2NhGfHOGOeOZITqfkEO4p/xK+l3NpyncIHUQBoMvCSF/b5GqvKtySC2srL/GGG3+EtlqlmCw==", + "dev": true, + "dependencies": { + "caseless": "^0.12.0", + "concat-stream": "^1.6.2", + "http-response-object": "^3.0.1", + "parse-cache-control": "^1.0.1" + }, + "engines": { + "node": ">=6.0.0" + } + }, + "node_modules/http-cache-semantics": { + "version": "4.1.1", + "resolved": "https://registry.npmjs.org/http-cache-semantics/-/http-cache-semantics-4.1.1.tgz", + "integrity": "sha512-er295DKPVsV82j5kw1Gjt+ADA/XYHsajl82cGNQG2eyoPkvgUhX+nDIyelzhIWbbsXP39EHcI6l5tYs2FYqYXQ==", + "dev": true + }, + "node_modules/http-errors": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/http-errors/-/http-errors-2.0.0.tgz", + "integrity": "sha512-FtwrG/euBzaEjYeRqOgly7G0qviiXoJWnvEH2Z1plBdXgbyjv34pHTSb9zoeHMyDy33+DWy5Wt9Wo+TURtOYSQ==", + "dev": true, + "dependencies": { + "depd": "2.0.0", + "inherits": "2.0.4", + "setprototypeof": "1.2.0", + "statuses": "2.0.1", + "toidentifier": "1.0.1" + }, + "engines": { + "node": ">= 0.8" + } + }, + "node_modules/http-https": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/http-https/-/http-https-1.0.0.tgz", + "integrity": "sha512-o0PWwVCSp3O0wS6FvNr6xfBCHgt0m1tvPLFOCc2iFDKTRAXhB7m8klDf7ErowFH8POa6dVdGatKU5I1YYwzUyg==", + "dev": true + }, + "node_modules/http-response-object": { + "version": "3.0.2", + "resolved": "https://registry.npmjs.org/http-response-object/-/http-response-object-3.0.2.tgz", + "integrity": "sha512-bqX0XTF6fnXSQcEJ2Iuyr75yVakyjIDCqroJQ/aHfSdlM743Cwqoi2nDYMzLGWUcuTWGWy8AAvOKXTfiv6q9RA==", + "dev": true, + "dependencies": { + "@types/node": "^10.0.3" + } + }, + "node_modules/http-response-object/node_modules/@types/node": { + "version": "10.17.60", + "resolved": "https://registry.npmjs.org/@types/node/-/node-10.17.60.tgz", + "integrity": "sha512-F0KIgDJfy2nA3zMLmWGKxcH2ZVEtCZXHHdOQs2gSaQ27+lNeEfGxzkIw90aXswATX7AZ33tahPbzy6KAfUreVw==", + "dev": true + }, + "node_modules/http-signature": { + "version": "1.2.0", + "resolved": "https://registry.npmjs.org/http-signature/-/http-signature-1.2.0.tgz", + "integrity": "sha512-CAbnr6Rz4CYQkLYUtSNXxQPUH2gK8f3iWexVlsnMeD+GjlsQ0Xsy1cOX+mN3dtxYomRy21CiOzU8Uhw6OwncEQ==", + "dev": true, + "dependencies": { + "assert-plus": "^1.0.0", + "jsprim": "^1.2.2", + "sshpk": "^1.7.0" + }, + "engines": { + "node": ">=0.8", + "npm": ">=1.3.7" + } + }, + "node_modules/http2-wrapper": { + "version": "2.2.0", + "resolved": "https://registry.npmjs.org/http2-wrapper/-/http2-wrapper-2.2.0.tgz", + "integrity": "sha512-kZB0wxMo0sh1PehyjJUWRFEd99KC5TLjZ2cULC4f9iqJBAmKQQXEICjxl5iPJRwP40dpeHFqqhm7tYCvODpqpQ==", + "dev": true, + "dependencies": { + "quick-lru": "^5.1.1", + "resolve-alpn": "^1.2.0" + }, + "engines": { + "node": ">=10.19.0" + } + }, + "node_modules/http2-wrapper/node_modules/quick-lru": { + "version": "5.1.1", + "resolved": "https://registry.npmjs.org/quick-lru/-/quick-lru-5.1.1.tgz", + "integrity": "sha512-WuyALRjWPDGtt/wzJiadO5AXY+8hZ80hVpe6MyivgraREW751X3SbhRvG3eLKOYN+8VEvqLcf3wdnt44Z4S4SA==", + "dev": true, + "engines": { + "node": ">=10" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/https-proxy-agent": { + "version": "5.0.1", + "resolved": "https://registry.npmjs.org/https-proxy-agent/-/https-proxy-agent-5.0.1.tgz", + "integrity": "sha512-dFcAjpTQFgoLMzC2VwU+C/CbS7uRL0lWmxDITmqm7C+7F0Odmj6s9l6alZc6AELXhrnggM2CeWSXHGOdX2YtwA==", + "dev": true, + "dependencies": { + "agent-base": "6", + "debug": "4" + }, + "engines": { + "node": ">= 6" + } + }, + "node_modules/human-id": { + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/human-id/-/human-id-1.0.2.tgz", + "integrity": "sha512-UNopramDEhHJD+VR+ehk8rOslwSfByxPIZyJRfV739NDhN5LF1fa1MqnzKm2lGTQRjNrjK19Q5fhkgIfjlVUKw==", + "dev": true + }, + "node_modules/iconv-lite": { + "version": "0.4.24", + "resolved": "https://registry.npmjs.org/iconv-lite/-/iconv-lite-0.4.24.tgz", + "integrity": "sha512-v3MXnZAcvnywkTUEZomIActle7RXXeedOR31wwl7VlyoXO4Qi9arvSenNQWne1TcRwhCL1HwLI21bEqdpj8/rA==", + "dev": true, + "dependencies": { + "safer-buffer": ">= 2.1.2 < 3" + }, + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/idna-uts46-hx": { + "version": "2.3.1", + "resolved": "https://registry.npmjs.org/idna-uts46-hx/-/idna-uts46-hx-2.3.1.tgz", + "integrity": "sha512-PWoF9Keq6laYdIRwwCdhTPl60xRqAloYNMQLiyUnG42VjT53oW07BXIRM+NK7eQjzXjAk2gUvX9caRxlnF9TAA==", + "dev": true, + "dependencies": { + "punycode": "2.1.0" + }, + "engines": { + "node": ">=4.0.0" + } + }, + "node_modules/ieee754": { + "version": "1.2.1", + "resolved": "https://registry.npmjs.org/ieee754/-/ieee754-1.2.1.tgz", + "integrity": "sha512-dcyqhDvX1C46lXZcVqCpK+FtMRQVdIMN6/Df5js2zouUsqG7I6sFxitIC+7KYK29KdXOLHdu9zL4sFnoVQnqaA==", + "dev": true, + "funding": [ + { + "type": "github", + "url": "https://github.com/sponsors/feross" + }, + { + "type": "patreon", + "url": "https://www.patreon.com/feross" + }, + { + "type": "consulting", + "url": "https://feross.org/support" + } + ] + }, + "node_modules/ignore": { + "version": "5.2.4", + "resolved": "https://registry.npmjs.org/ignore/-/ignore-5.2.4.tgz", + "integrity": "sha512-MAb38BcSbH0eHNBxn7ql2NH/kX33OkB3lZ1BNdh7ENeRChHTYsTvWrMubiIAMNS2llXEEgZ1MUOBtXChP3kaFQ==", + "dev": true, + "engines": { + "node": ">= 4" + } + }, + "node_modules/immutable": { + "version": "4.3.0", + "resolved": "https://registry.npmjs.org/immutable/-/immutable-4.3.0.tgz", + "integrity": "sha512-0AOCmOip+xgJwEVTQj1EfiDDOkPmuyllDuTuEX+DDXUgapLAsBIfkg3sxCYyCEA8mQqZrrxPUGjcOQ2JS3WLkg==", + "dev": true + }, + "node_modules/import-fresh": { + "version": "3.3.0", + "resolved": "https://registry.npmjs.org/import-fresh/-/import-fresh-3.3.0.tgz", + "integrity": "sha512-veYYhQa+D1QBKznvhUHxb8faxlrwUnxseDAbAp457E0wLNio2bOSKnjYDhMj+YiAq61xrMGhQk9iXVk5FzgQMw==", + "dev": true, + "dependencies": { + "parent-module": "^1.0.0", + "resolve-from": "^4.0.0" + }, + "engines": { + "node": ">=6" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/import-fresh/node_modules/resolve-from": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/resolve-from/-/resolve-from-4.0.0.tgz", + "integrity": "sha512-pb/MYmXstAkysRFx8piNI1tGFNQIFA3vkE3Gq4EuA1dF6gHp/+vgZqsCGJapvy8N3Q+4o7FwvquPJcnZ7RYy4g==", + "dev": true, + "engines": { + "node": ">=4" + } + }, + "node_modules/imurmurhash": { + "version": "0.1.4", + "resolved": "https://registry.npmjs.org/imurmurhash/-/imurmurhash-0.1.4.tgz", + "integrity": "sha512-JmXMZ6wuvDmLiHEml9ykzqO6lwFbof0GG4IkcGaENdCRDDmMVnny7s5HsIgHCbaq0w2MyPhDqkhTUgS2LU2PHA==", + "dev": true, + "engines": { + "node": ">=0.8.19" + } + }, + "node_modules/indent-string": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/indent-string/-/indent-string-4.0.0.tgz", + "integrity": "sha512-EdDDZu4A2OyIK7Lr/2zG+w5jmbuk1DVBnEwREQvBzspBJkCEbRa8GxU1lghYcaGJCnRWibjDXlq779X1/y5xwg==", + "dev": true, + "engines": { + "node": ">=8" + } + }, + "node_modules/inflight": { + "version": "1.0.6", + "resolved": "https://registry.npmjs.org/inflight/-/inflight-1.0.6.tgz", + "integrity": "sha512-k92I/b08q4wvFscXCLvqfsHCrjrF7yiXsQuIVvVE7N82W3+aqpzuUdBbfhWcy/FZR3/4IgflMgKLOsvPDrGCJA==", + "dev": true, + "dependencies": { + "once": "^1.3.0", + "wrappy": "1" + } + }, + "node_modules/inherits": { + "version": "2.0.4", + "resolved": "https://registry.npmjs.org/inherits/-/inherits-2.0.4.tgz", + "integrity": "sha512-k/vGaX4/Yla3WzyMCvTQOXYeIHvqOKtnqBduzTHpzpQZzAskKMhZ2K+EnBiSM9zGSoIFeMpXKxa4dYeZIQqewQ==", + "dev": true + }, + "node_modules/ini": { + "version": "1.3.8", + "resolved": "https://registry.npmjs.org/ini/-/ini-1.3.8.tgz", + "integrity": "sha512-JV/yugV2uzW5iMRSiZAyDtQd+nxtUnjeLt0acNdw98kKLrvuRVyB80tsREOE7yvGVgalhZ6RNXCmEHkUKBKxew==", + "dev": true + }, + "node_modules/internal-slot": { + "version": "1.0.5", + "resolved": "https://registry.npmjs.org/internal-slot/-/internal-slot-1.0.5.tgz", + "integrity": "sha512-Y+R5hJrzs52QCG2laLn4udYVnxsfny9CpOhNhUvk/SSSVyF6T27FzRbF0sroPidSu3X8oEAkOn2K804mjpt6UQ==", + "dev": true, + "dependencies": { + "get-intrinsic": "^1.2.0", + "has": "^1.0.3", + "side-channel": "^1.0.4" + }, + "engines": { + "node": ">= 0.4" + } + }, + "node_modules/interpret": { + "version": "1.4.0", + "resolved": "https://registry.npmjs.org/interpret/-/interpret-1.4.0.tgz", + "integrity": "sha512-agE4QfB2Lkp9uICn7BAqoscw4SZP9kTE2hxiFI3jBPmXJfdqiahTbUuKGsMoN2GtqL9AxhYioAcVvgsb1HvRbA==", + "dev": true, + "engines": { + "node": ">= 0.10" + } + }, + "node_modules/invert-kv": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/invert-kv/-/invert-kv-1.0.0.tgz", + "integrity": "sha512-xgs2NH9AE66ucSq4cNG1nhSFghr5l6tdL15Pk+jl46bmmBapgoaY/AacXyaDznAqmGL99TiLSQgO/XazFSKYeQ==", + "dev": true, + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/io-ts": { + "version": "1.10.4", + "resolved": "https://registry.npmjs.org/io-ts/-/io-ts-1.10.4.tgz", + "integrity": "sha512-b23PteSnYXSONJ6JQXRAlvJhuw8KOtkqa87W4wDtvMrud/DTJd5X+NpOOI+O/zZwVq6v0VLAaJ+1EDViKEuN9g==", + "dev": true, + "dependencies": { + "fp-ts": "^1.0.0" + } + }, + "node_modules/ipaddr.js": { + "version": "1.9.1", + "resolved": "https://registry.npmjs.org/ipaddr.js/-/ipaddr.js-1.9.1.tgz", + "integrity": "sha512-0KI/607xoxSToH7GjN1FfSbLoU0+btTicjsQSWQlh/hZykN8KpmMf7uYwPW3R+akZ6R/w18ZlXSHBYXiYUPO3g==", + "dev": true, + "engines": { + "node": ">= 0.10" + } + }, + "node_modules/is-arguments": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/is-arguments/-/is-arguments-1.1.1.tgz", + "integrity": "sha512-8Q7EARjzEnKpt/PCD7e1cgUS0a6X8u5tdSiMqXhojOdoV9TsMsiO+9VLC5vAmO8N7/GmXn7yjR8qnA6bVAEzfA==", + "dev": true, + "dependencies": { + "call-bind": "^1.0.2", + "has-tostringtag": "^1.0.0" + }, + "engines": { + "node": ">= 0.4" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/is-array-buffer": { + "version": "3.0.2", + "resolved": "https://registry.npmjs.org/is-array-buffer/-/is-array-buffer-3.0.2.tgz", + "integrity": "sha512-y+FyyR/w8vfIRq4eQcM1EYgSTnmHXPqaF+IgzgraytCFq5Xh8lllDVmAZolPJiZttZLeFSINPYMaEJ7/vWUa1w==", + "dev": true, + "dependencies": { + "call-bind": "^1.0.2", + "get-intrinsic": "^1.2.0", + "is-typed-array": "^1.1.10" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/is-arrayish": { + "version": "0.2.1", + "resolved": "https://registry.npmjs.org/is-arrayish/-/is-arrayish-0.2.1.tgz", + "integrity": "sha512-zz06S8t0ozoDXMG+ube26zeCTNXcKIPJZJi8hBrF4idCLms4CG9QtK7qBl1boi5ODzFpjswb5JPmHCbMpjaYzg==", + "dev": true + }, + "node_modules/is-bigint": { + "version": "1.0.4", + "resolved": "https://registry.npmjs.org/is-bigint/-/is-bigint-1.0.4.tgz", + "integrity": "sha512-zB9CruMamjym81i2JZ3UMn54PKGsQzsJeo6xvN3HJJ4CAsQNB6iRutp2To77OfCNuoxspsIhzaPoO1zyCEhFOg==", + "dev": true, + "dependencies": { + "has-bigints": "^1.0.1" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/is-binary-path": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/is-binary-path/-/is-binary-path-2.1.0.tgz", + "integrity": "sha512-ZMERYes6pDydyuGidse7OsHxtbI7WVeUEozgR/g7rd0xUimYNlvZRE/K2MgZTjWy725IfelLeVcEM97mmtRGXw==", + "dev": true, + "dependencies": { + "binary-extensions": "^2.0.0" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/is-boolean-object": { + "version": "1.1.2", + "resolved": "https://registry.npmjs.org/is-boolean-object/-/is-boolean-object-1.1.2.tgz", + "integrity": "sha512-gDYaKHJmnj4aWxyj6YHyXVpdQawtVLHU5cb+eztPGczf6cjuTdwve5ZIEfgXqH4e57An1D1AKf8CZ3kYrQRqYA==", + "dev": true, + "dependencies": { + "call-bind": "^1.0.2", + "has-tostringtag": "^1.0.0" + }, + "engines": { + "node": ">= 0.4" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/is-buffer": { + "version": "2.0.5", + "resolved": "https://registry.npmjs.org/is-buffer/-/is-buffer-2.0.5.tgz", + "integrity": "sha512-i2R6zNFDwgEHJyQUtJEk0XFi1i0dPFn/oqjK3/vPCcDeJvW5NQ83V8QbicfF1SupOaB0h8ntgBC2YiE7dfyctQ==", + "dev": true, + "funding": [ + { + "type": "github", + "url": "https://github.com/sponsors/feross" + }, + { + "type": "patreon", + "url": "https://www.patreon.com/feross" + }, + { + "type": "consulting", + "url": "https://feross.org/support" + } + ], + "engines": { + "node": ">=4" + } + }, + "node_modules/is-callable": { + "version": "1.2.7", + "resolved": "https://registry.npmjs.org/is-callable/-/is-callable-1.2.7.tgz", + "integrity": "sha512-1BC0BVFhS/p0qtw6enp8e+8OD0UrK0oFLztSjNzhcKA3WDuJxxAPXzPuPtKkjEY9UUoEWlX/8fgKeu2S8i9JTA==", + "dev": true, + "engines": { + "node": ">= 0.4" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/is-ci": { + "version": "3.0.1", + "resolved": "https://registry.npmjs.org/is-ci/-/is-ci-3.0.1.tgz", + "integrity": "sha512-ZYvCgrefwqoQ6yTyYUbQu64HsITZ3NfKX1lzaEYdkTDcfKzzCI/wthRRYKkdjHKFVgNiXKAKm65Zo1pk2as/QQ==", + "dev": true, + "dependencies": { + "ci-info": "^3.2.0" + }, + "bin": { + "is-ci": "bin.js" + } + }, + "node_modules/is-date-object": { + "version": "1.0.5", + "resolved": "https://registry.npmjs.org/is-date-object/-/is-date-object-1.0.5.tgz", + "integrity": "sha512-9YQaSxsAiSwcvS33MBk3wTCVnWK+HhF8VZR2jRxehM16QcVOdHqPn4VPHmRK4lSr38n9JriurInLcP90xsYNfQ==", + "dev": true, + "dependencies": { + "has-tostringtag": "^1.0.0" + }, + "engines": { + "node": ">= 0.4" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/is-extglob": { + "version": "2.1.1", + "resolved": "https://registry.npmjs.org/is-extglob/-/is-extglob-2.1.1.tgz", + "integrity": "sha512-SbKbANkN603Vi4jEZv49LeVJMn4yGwsbzZworEoyEiutsN3nJYdbO36zfhGJ6QEDpOZIFkDtnq5JRxmvl3jsoQ==", + "dev": true, + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/is-fullwidth-code-point": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/is-fullwidth-code-point/-/is-fullwidth-code-point-2.0.0.tgz", + "integrity": "sha512-VHskAKYM8RfSFXwee5t5cbN5PZeq1Wrh6qd5bkyiXIf6UQcN6w/A0eXM9r6t8d+GYOh+o6ZhiEnb88LN/Y8m2w==", + "dev": true, + "engines": { + "node": ">=4" + } + }, + "node_modules/is-function": { + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/is-function/-/is-function-1.0.2.tgz", + "integrity": "sha512-lw7DUp0aWXYg+CBCN+JKkcE0Q2RayZnSvnZBlwgxHBQhqt5pZNVy4Ri7H9GmmXkdu7LUthszM+Tor1u/2iBcpQ==", + "dev": true + }, + "node_modules/is-generator-function": { + "version": "1.0.10", + "resolved": "https://registry.npmjs.org/is-generator-function/-/is-generator-function-1.0.10.tgz", + "integrity": "sha512-jsEjy9l3yiXEQ+PsXdmBwEPcOxaXWLspKdplFUVI9vq1iZgIekeC0L167qeu86czQaxed3q/Uzuw0swL0irL8A==", + "dev": true, + "dependencies": { + "has-tostringtag": "^1.0.0" + }, + "engines": { + "node": ">= 0.4" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/is-glob": { + "version": "4.0.3", + "resolved": "https://registry.npmjs.org/is-glob/-/is-glob-4.0.3.tgz", + "integrity": "sha512-xelSayHH36ZgE7ZWhli7pW34hNbNl8Ojv5KVmkJD4hBdD3th8Tfk9vYasLM+mXWOZhFkgZfxhLSnrwRr4elSSg==", + "dev": true, + "dependencies": { + "is-extglob": "^2.1.1" + }, + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/is-hex-prefixed": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/is-hex-prefixed/-/is-hex-prefixed-1.0.0.tgz", + "integrity": "sha512-WvtOiug1VFrE9v1Cydwm+FnXd3+w9GaeVUss5W4v/SLy3UW00vP+6iNF2SdnfiBoLy4bTqVdkftNGTUeOFVsbA==", + "dev": true, + "engines": { + "node": ">=6.5.0", + "npm": ">=3" + } + }, + "node_modules/is-lower-case": { + "version": "1.1.3", + "resolved": "https://registry.npmjs.org/is-lower-case/-/is-lower-case-1.1.3.tgz", + "integrity": "sha512-+5A1e/WJpLLXZEDlgz4G//WYSHyQBD32qa4Jd3Lw06qQlv3fJHnp3YIHjTQSGzHMgzmVKz2ZP3rBxTHkPw/lxA==", + "dev": true, + "dependencies": { + "lower-case": "^1.1.0" + } + }, + "node_modules/is-negative-zero": { + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/is-negative-zero/-/is-negative-zero-2.0.2.tgz", + "integrity": "sha512-dqJvarLawXsFbNDeJW7zAz8ItJ9cd28YufuuFzh0G8pNHjJMnY08Dv7sYX2uF5UpQOwieAeOExEYAWWfu7ZZUA==", + "dev": true, + "engines": { + "node": ">= 0.4" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/is-number": { + "version": "7.0.0", + "resolved": "https://registry.npmjs.org/is-number/-/is-number-7.0.0.tgz", + "integrity": "sha512-41Cifkg6e8TylSpdtTpeLVMqvSBEVzTttHvERD741+pnZ8ANv0004MRL43QKPDlK9cGvNp6NZWZUBlbGXYxxng==", + "dev": true, + "engines": { + "node": ">=0.12.0" + } + }, + "node_modules/is-number-object": { + "version": "1.0.7", + "resolved": "https://registry.npmjs.org/is-number-object/-/is-number-object-1.0.7.tgz", + "integrity": "sha512-k1U0IRzLMo7ZlYIfzRu23Oh6MiIFasgpb9X76eqfFZAqwH44UI4KTBvBYIZ1dSL9ZzChTB9ShHfLkR4pdW5krQ==", + "dev": true, + "dependencies": { + "has-tostringtag": "^1.0.0" + }, + "engines": { + "node": ">= 0.4" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/is-path-inside": { + "version": "3.0.3", + "resolved": "https://registry.npmjs.org/is-path-inside/-/is-path-inside-3.0.3.tgz", + "integrity": "sha512-Fd4gABb+ycGAmKou8eMftCupSir5lRxqf4aD/vd0cD2qc4HL07OjCeuHMr8Ro4CoMaeCKDB0/ECBOVWjTwUvPQ==", + "dev": true, + "engines": { + "node": ">=8" + } + }, + "node_modules/is-plain-obj": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/is-plain-obj/-/is-plain-obj-1.1.0.tgz", + "integrity": "sha512-yvkRyxmFKEOQ4pNXCmJG5AEQNlXJS5LaONXo5/cLdTZdWvsZ1ioJEonLGAosKlMWE8lwUy/bJzMjcw8az73+Fg==", + "dev": true, + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/is-port-reachable": { + "version": "3.1.0", + "resolved": "https://registry.npmjs.org/is-port-reachable/-/is-port-reachable-3.1.0.tgz", + "integrity": "sha512-vjc0SSRNZ32s9SbZBzGaiP6YVB+xglLShhgZD/FHMZUXBvQWaV9CtzgeVhjccFJrI6RAMV+LX7NYxueW/A8W5A==", + "dev": true, + "engines": { + "node": ">=8" + } + }, + "node_modules/is-regex": { + "version": "1.1.4", + "resolved": "https://registry.npmjs.org/is-regex/-/is-regex-1.1.4.tgz", + "integrity": "sha512-kvRdxDsxZjhzUX07ZnLydzS1TU/TJlTUHHY4YLL87e37oUA49DfkLqgy+VjFocowy29cKvcSiu+kIv728jTTVg==", + "dev": true, + "dependencies": { + "call-bind": "^1.0.2", + "has-tostringtag": "^1.0.0" + }, + "engines": { + "node": ">= 0.4" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/is-shared-array-buffer": { + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/is-shared-array-buffer/-/is-shared-array-buffer-1.0.2.tgz", + "integrity": "sha512-sqN2UDu1/0y6uvXyStCOzyhAjCSlHceFoMKJW8W9EU9cvic/QdsZ0kEU93HEy3IUEFZIiH/3w+AH/UQbPHNdhA==", + "dev": true, + "dependencies": { + "call-bind": "^1.0.2" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/is-string": { + "version": "1.0.7", + "resolved": "https://registry.npmjs.org/is-string/-/is-string-1.0.7.tgz", + "integrity": "sha512-tE2UXzivje6ofPW7l23cjDOMa09gb7xlAqG6jG5ej6uPV32TlWP3NKPigtaGeHNu9fohccRYvIiZMfOOnOYUtg==", + "dev": true, + "dependencies": { + "has-tostringtag": "^1.0.0" + }, + "engines": { + "node": ">= 0.4" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/is-subdir": { + "version": "1.2.0", + "resolved": "https://registry.npmjs.org/is-subdir/-/is-subdir-1.2.0.tgz", + "integrity": "sha512-2AT6j+gXe/1ueqbW6fLZJiIw3F8iXGJtt0yDrZaBhAZEG1raiTxKWU+IPqMCzQAXOUCKdA4UDMgacKH25XG2Cw==", + "dev": true, + "dependencies": { + "better-path-resolve": "1.0.0" + }, + "engines": { + "node": ">=4" + } + }, + "node_modules/is-symbol": { + "version": "1.0.4", + "resolved": "https://registry.npmjs.org/is-symbol/-/is-symbol-1.0.4.tgz", + "integrity": "sha512-C/CPBqKWnvdcxqIARxyOh4v1UUEOCHpgDa0WYgpKDFMszcrPcffg5uhwSgPCLD2WWxmq6isisz87tzT01tuGhg==", + "dev": true, + "dependencies": { + "has-symbols": "^1.0.2" + }, + "engines": { + "node": ">= 0.4" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/is-typed-array": { + "version": "1.1.10", + "resolved": "https://registry.npmjs.org/is-typed-array/-/is-typed-array-1.1.10.tgz", + "integrity": "sha512-PJqgEHiWZvMpaFZ3uTc8kHPM4+4ADTlDniuQL7cU/UDA0Ql7F70yGfHph3cLNe+c9toaigv+DFzTJKhc2CtO6A==", + "dev": true, + "dependencies": { + "available-typed-arrays": "^1.0.5", + "call-bind": "^1.0.2", + "for-each": "^0.3.3", + "gopd": "^1.0.1", + "has-tostringtag": "^1.0.0" + }, + "engines": { + "node": ">= 0.4" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/is-typedarray": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/is-typedarray/-/is-typedarray-1.0.0.tgz", + "integrity": "sha512-cyA56iCMHAh5CdzjJIa4aohJyeO1YbwLi3Jc35MmRU6poroFjIGZzUzupGiRPOjgHg9TLu43xbpwXk523fMxKA==", + "dev": true + }, + "node_modules/is-unicode-supported": { + "version": "0.1.0", + "resolved": "https://registry.npmjs.org/is-unicode-supported/-/is-unicode-supported-0.1.0.tgz", + "integrity": "sha512-knxG2q4UC3u8stRGyAVJCOdxFmv5DZiRcdlIaAQXAbSfJya+OhopNotLQrstBhququ4ZpuKbDc/8S6mgXgPFPw==", + "dev": true, + "engines": { + "node": ">=10" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/is-upper-case": { + "version": "1.1.2", + "resolved": "https://registry.npmjs.org/is-upper-case/-/is-upper-case-1.1.2.tgz", + "integrity": "sha512-GQYSJMgfeAmVwh9ixyk888l7OIhNAGKtY6QA+IrWlu9MDTCaXmeozOZ2S9Knj7bQwBO/H6J2kb+pbyTUiMNbsw==", + "dev": true, + "dependencies": { + "upper-case": "^1.1.0" + } + }, + "node_modules/is-utf8": { + "version": "0.2.1", + "resolved": "https://registry.npmjs.org/is-utf8/-/is-utf8-0.2.1.tgz", + "integrity": "sha512-rMYPYvCzsXywIsldgLaSoPlw5PfoB/ssr7hY4pLfcodrA5M/eArza1a9VmTiNIBNMjOGr1Ow9mTyU2o69U6U9Q==", + "dev": true + }, + "node_modules/is-weakref": { + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/is-weakref/-/is-weakref-1.0.2.tgz", + "integrity": "sha512-qctsuLZmIQ0+vSSMfoVvyFe2+GSEvnmZ2ezTup1SBse9+twCCeial6EEi3Nc2KFcf6+qz2FBPnjXsk8xhKSaPQ==", + "dev": true, + "dependencies": { + "call-bind": "^1.0.2" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/is-windows": { + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/is-windows/-/is-windows-1.0.2.tgz", + "integrity": "sha512-eXK1UInq2bPmjyX6e3VHIzMLobc4J94i4AWn+Hpq3OU5KkrRC96OAcR3PRJ/pGu6m8TRnBHP9dkXQVsT/COVIA==", + "dev": true, + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/isarray": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/isarray/-/isarray-1.0.0.tgz", + "integrity": "sha512-VLghIWNM6ELQzo7zwmcg0NmTVyWKYjvIeM83yjp0wRDTmUnrM678fQbcKBo6n2CJEF0szoG//ytg+TKla89ALQ==", + "dev": true + }, + "node_modules/isexe": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/isexe/-/isexe-2.0.0.tgz", + "integrity": "sha512-RHxMLp9lnKHGHRng9QFhRCMbYAcVpn69smSGcq3f36xjgVVWThj4qqLbTLlq7Ssj8B+fIQ1EuCEGI2lKsyQeIw==", + "dev": true + }, + "node_modules/isstream": { + "version": "0.1.2", + "resolved": "https://registry.npmjs.org/isstream/-/isstream-0.1.2.tgz", + "integrity": "sha512-Yljz7ffyPbrLpLngrMtZ7NduUgVvi6wG9RJ9IUcyCd59YQ911PBJphODUcbOVbqYfxe1wuYf/LJ8PauMRwsM/g==", + "dev": true + }, + "node_modules/js-sdsl": { + "version": "4.4.1", + "resolved": "https://registry.npmjs.org/js-sdsl/-/js-sdsl-4.4.1.tgz", + "integrity": "sha512-6Gsx8R0RucyePbWqPssR8DyfuXmLBooYN5cZFZKjHGnQuaf7pEzhtpceagJxVu4LqhYY5EYA7nko3FmeHZ1KbA==", + "dev": true, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/js-sdsl" + } + }, + "node_modules/js-sha3": { + "version": "0.8.0", + "resolved": "https://registry.npmjs.org/js-sha3/-/js-sha3-0.8.0.tgz", + "integrity": "sha512-gF1cRrHhIzNfToc802P800N8PpXS+evLLXfsVpowqmAFR9uwbi89WvXg2QspOmXL8QL86J4T1EpFu+yUkwJY3Q==", + "dev": true + }, + "node_modules/js-tokens": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/js-tokens/-/js-tokens-4.0.0.tgz", + "integrity": "sha512-RdJUflcE3cUzKiMqQgsCu06FPu9UdIJO0beYbPhHN4k6apgJtifcoCtT9bcxOpYBtpD2kCM6Sbzg4CausW/PKQ==", + "dev": true + }, + "node_modules/js-yaml": { + "version": "3.14.1", + "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-3.14.1.tgz", + "integrity": "sha512-okMH7OXXJ7YrN9Ok3/SXrnu4iX9yOk+25nqX4imS2npuvTYDmo/QEZoqwZkYaIDk3jVvBOTOIEgEhaLOynBS9g==", + "dev": true, + "dependencies": { + "argparse": "^1.0.7", + "esprima": "^4.0.0" + }, + "bin": { + "js-yaml": "bin/js-yaml.js" + } + }, + "node_modules/jsbn": { + "version": "0.1.1", + "resolved": "https://registry.npmjs.org/jsbn/-/jsbn-0.1.1.tgz", + "integrity": "sha512-UVU9dibq2JcFWxQPA6KCqj5O42VOmAY3zQUfEKxU0KpTGXwNoCjkX1e13eHNvw/xPynt6pU0rZ1htjWTNTSXsg==", + "dev": true + }, + "node_modules/json-buffer": { + "version": "3.0.1", + "resolved": "https://registry.npmjs.org/json-buffer/-/json-buffer-3.0.1.tgz", + "integrity": "sha512-4bV5BfR2mqfQTJm+V5tPPdf+ZpuhiIvTuAB5g8kcrXOZpTT/QwwVRWBywX1ozr6lEuPdbHxwaJlm9G6mI2sfSQ==", + "dev": true + }, + "node_modules/json-parse-even-better-errors": { + "version": "2.3.1", + "resolved": "https://registry.npmjs.org/json-parse-even-better-errors/-/json-parse-even-better-errors-2.3.1.tgz", + "integrity": "sha512-xyFwyhro/JEof6Ghe2iz2NcXoj2sloNsWr/XsERDK/oiPCfaNhl5ONfp+jQdAZRQQ0IJWNzH9zIZF7li91kh2w==", + "dev": true + }, + "node_modules/json-schema": { + "version": "0.4.0", + "resolved": "https://registry.npmjs.org/json-schema/-/json-schema-0.4.0.tgz", + "integrity": "sha512-es94M3nTIfsEPisRafak+HDLfHXnKBhV3vU5eqPcS3flIWqcxJWgXHXiey3YrpaNsanY5ei1VoYEbOzijuq9BA==", + "dev": true + }, + "node_modules/json-schema-traverse": { + "version": "0.4.1", + "resolved": "https://registry.npmjs.org/json-schema-traverse/-/json-schema-traverse-0.4.1.tgz", + "integrity": "sha512-xbbCH5dCYU5T8LcEhhuh7HJ88HXuW3qsI3Y0zOZFKfZEHcpWiHU/Jxzk629Brsab/mMiHQti9wMP+845RPe3Vg==", + "dev": true + }, + "node_modules/json-stable-stringify-without-jsonify": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/json-stable-stringify-without-jsonify/-/json-stable-stringify-without-jsonify-1.0.1.tgz", + "integrity": "sha512-Bdboy+l7tA3OGW6FjyFHWkP5LuByj1Tk33Ljyq0axyzdk9//JSi2u3fP1QSmd1KNwq6VOKYGlAu87CisVir6Pw==", + "dev": true + }, + "node_modules/json-stringify-safe": { + "version": "5.0.1", + "resolved": "https://registry.npmjs.org/json-stringify-safe/-/json-stringify-safe-5.0.1.tgz", + "integrity": "sha512-ZClg6AaYvamvYEE82d3Iyd3vSSIjQ+odgjaTzRuO3s7toCdFKczob2i0zCh7JE8kWn17yvAWhUVxvqGwUalsRA==", + "dev": true + }, + "node_modules/jsonfile": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/jsonfile/-/jsonfile-4.0.0.tgz", + "integrity": "sha512-m6F1R3z8jjlf2imQHS2Qez5sjKWQzbuuhuJ/FKYFRZvPE3PuHcSMVZzfsLhGVOkfd20obL5SWEBew5ShlquNxg==", + "dev": true, + "optionalDependencies": { + "graceful-fs": "^4.1.6" + } + }, + "node_modules/jsonschema": { + "version": "1.4.1", + "resolved": "https://registry.npmjs.org/jsonschema/-/jsonschema-1.4.1.tgz", + "integrity": "sha512-S6cATIPVv1z0IlxdN+zUk5EPjkGCdnhN4wVSBlvoUO1tOLJootbo9CquNJmbIh4yikWHiUedhRYrNPn1arpEmQ==", + "dev": true, + "engines": { + "node": "*" + } + }, + "node_modules/jsprim": { + "version": "1.4.2", + "resolved": "https://registry.npmjs.org/jsprim/-/jsprim-1.4.2.tgz", + "integrity": "sha512-P2bSOMAc/ciLz6DzgjVlGJP9+BrJWu5UDGK70C2iweC5QBIeFf0ZXRvGjEj2uYgrY2MkAAhsSWHDWlFtEroZWw==", + "dev": true, + "dependencies": { + "assert-plus": "1.0.0", + "extsprintf": "1.3.0", + "json-schema": "0.4.0", + "verror": "1.10.0" + }, + "engines": { + "node": ">=0.6.0" + } + }, + "node_modules/keccak": { + "version": "3.0.3", + "resolved": "https://registry.npmjs.org/keccak/-/keccak-3.0.3.tgz", + "integrity": "sha512-JZrLIAJWuZxKbCilMpNz5Vj7Vtb4scDG3dMXLOsbzBmQGyjwE61BbW7bJkfKKCShXiQZt3T6sBgALRtmd+nZaQ==", + "dev": true, + "hasInstallScript": true, + "dependencies": { + "node-addon-api": "^2.0.0", + "node-gyp-build": "^4.2.0", + "readable-stream": "^3.6.0" + }, + "engines": { + "node": ">=10.0.0" + } + }, + "node_modules/keccak256": { + "version": "1.0.6", + "resolved": "https://registry.npmjs.org/keccak256/-/keccak256-1.0.6.tgz", + "integrity": "sha512-8GLiM01PkdJVGUhR1e6M/AvWnSqYS0HaERI+K/QtStGDGlSTx2B1zTqZk4Zlqu5TxHJNTxWAdP9Y+WI50OApUw==", + "dev": true, + "dependencies": { + "bn.js": "^5.2.0", + "buffer": "^6.0.3", + "keccak": "^3.0.2" + } + }, + "node_modules/keccak256/node_modules/bn.js": { + "version": "5.2.1", + "resolved": "https://registry.npmjs.org/bn.js/-/bn.js-5.2.1.tgz", + "integrity": "sha512-eXRvHzWyYPBuB4NBy0cmYQjGitUrtqwbvlzP3G6VFnNRbsZQIxQ10PbKKHt8gZ/HW/D/747aDl+QkDqg3KQLMQ==", + "dev": true + }, + "node_modules/keccak256/node_modules/buffer": { + "version": "6.0.3", + "resolved": "https://registry.npmjs.org/buffer/-/buffer-6.0.3.tgz", + "integrity": "sha512-FTiCpNxtwiZZHEZbcbTIcZjERVICn9yq/pDFkTl95/AxzD1naBctN7YO68riM/gLSDY7sdrMby8hofADYuuqOA==", + "dev": true, + "funding": [ + { + "type": "github", + "url": "https://github.com/sponsors/feross" + }, + { + "type": "patreon", + "url": "https://www.patreon.com/feross" + }, + { + "type": "consulting", + "url": "https://feross.org/support" + } + ], + "dependencies": { + "base64-js": "^1.3.1", + "ieee754": "^1.2.1" + } + }, + "node_modules/keyv": { + "version": "4.5.2", + "resolved": "https://registry.npmjs.org/keyv/-/keyv-4.5.2.tgz", + "integrity": "sha512-5MHbFaKn8cNSmVW7BYnijeAVlE4cYA/SVkifVgrh7yotnfhKmjuXpDKjrABLnT0SfHWV21P8ow07OGfRrNDg8g==", + "dev": true, + "dependencies": { + "json-buffer": "3.0.1" + } + }, + "node_modules/kind-of": { + "version": "6.0.3", + "resolved": "https://registry.npmjs.org/kind-of/-/kind-of-6.0.3.tgz", + "integrity": "sha512-dcS1ul+9tmeD95T+x28/ehLgd9mENa3LsvDTtzm3vyBEO7RPptvAD+t44WVXaUjTBRcrpFeFlC8WCruUR456hw==", + "dev": true, + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/klaw": { + "version": "1.3.1", + "resolved": "https://registry.npmjs.org/klaw/-/klaw-1.3.1.tgz", + "integrity": "sha512-TED5xi9gGQjGpNnvRWknrwAB1eL5GciPfVFOt3Vk1OJCVDQbzuSfrF3hkUQKlsgKrG1F+0t5W0m+Fje1jIt8rw==", + "dev": true, + "optionalDependencies": { + "graceful-fs": "^4.1.9" + } + }, + "node_modules/kleur": { + "version": "4.1.5", + "resolved": "https://registry.npmjs.org/kleur/-/kleur-4.1.5.tgz", + "integrity": "sha512-o+NO+8WrRiQEE4/7nwRJhN1HWpVmJm511pBHUxPLtp0BUISzlBplORYSmTclCnJvQq2tKu/sgl3xVpkc7ZWuQQ==", + "dev": true, + "engines": { + "node": ">=6" + } + }, + "node_modules/lcid": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/lcid/-/lcid-1.0.0.tgz", + "integrity": "sha512-YiGkH6EnGrDGqLMITnGjXtGmNtjoXw9SVUzcaos8RBi7Ps0VBylkq+vOcY9QE5poLasPCR849ucFUkl0UzUyOw==", + "dev": true, + "dependencies": { + "invert-kv": "^1.0.0" + }, + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/level": { + "version": "8.0.0", + "resolved": "https://registry.npmjs.org/level/-/level-8.0.0.tgz", + "integrity": "sha512-ypf0jjAk2BWI33yzEaaotpq7fkOPALKAgDBxggO6Q9HGX2MRXn0wbP1Jn/tJv1gtL867+YOjOB49WaUF3UoJNQ==", + "dev": true, + "dependencies": { + "browser-level": "^1.0.1", + "classic-level": "^1.2.0" + }, + "engines": { + "node": ">=12" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/level" + } + }, + "node_modules/level-supports": { + "version": "4.0.1", + "resolved": "https://registry.npmjs.org/level-supports/-/level-supports-4.0.1.tgz", + "integrity": "sha512-PbXpve8rKeNcZ9C1mUicC9auIYFyGpkV9/i6g76tLgANwWhtG2v7I4xNBUlkn3lE2/dZF3Pi0ygYGtLc4RXXdA==", + "dev": true, + "engines": { + "node": ">=12" + } + }, + "node_modules/level-transcoder": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/level-transcoder/-/level-transcoder-1.0.1.tgz", + "integrity": "sha512-t7bFwFtsQeD8cl8NIoQ2iwxA0CL/9IFw7/9gAjOonH0PWTTiRfY7Hq+Ejbsxh86tXobDQ6IOiddjNYIfOBs06w==", + "dev": true, + "dependencies": { + "buffer": "^6.0.3", + "module-error": "^1.0.1" + }, + "engines": { + "node": ">=12" + } + }, + "node_modules/level-transcoder/node_modules/buffer": { + "version": "6.0.3", + "resolved": "https://registry.npmjs.org/buffer/-/buffer-6.0.3.tgz", + "integrity": "sha512-FTiCpNxtwiZZHEZbcbTIcZjERVICn9yq/pDFkTl95/AxzD1naBctN7YO68riM/gLSDY7sdrMby8hofADYuuqOA==", + "dev": true, + "funding": [ + { + "type": "github", + "url": "https://github.com/sponsors/feross" + }, + { + "type": "patreon", + "url": "https://www.patreon.com/feross" + }, + { + "type": "consulting", + "url": "https://feross.org/support" + } + ], + "dependencies": { + "base64-js": "^1.3.1", + "ieee754": "^1.2.1" + } + }, + "node_modules/levn": { + "version": "0.4.1", + "resolved": "https://registry.npmjs.org/levn/-/levn-0.4.1.tgz", + "integrity": "sha512-+bT2uH4E5LGE7h/n3evcS/sQlJXCpIp6ym8OWJ5eV6+67Dsql/LaaT7qJBAt2rzfoa/5QBGBhxDix1dMt2kQKQ==", + "dev": true, + "dependencies": { + "prelude-ls": "^1.2.1", + "type-check": "~0.4.0" + }, + "engines": { + "node": ">= 0.8.0" + } + }, + "node_modules/lines-and-columns": { + "version": "1.2.4", + "resolved": "https://registry.npmjs.org/lines-and-columns/-/lines-and-columns-1.2.4.tgz", + "integrity": "sha512-7ylylesZQ/PV29jhEDl3Ufjo6ZX7gCqJr5F7PKrqc93v7fzSymt1BpwEU8nAUXs8qzzvqhbjhK5QZg6Mt/HkBg==", + "dev": true + }, + "node_modules/load-json-file": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/load-json-file/-/load-json-file-1.1.0.tgz", + "integrity": "sha512-cy7ZdNRXdablkXYNI049pthVeXFurRyb9+hA/dZzerZ0pGTx42z+y+ssxBaVV2l70t1muq5IdKhn4UtcoGUY9A==", + "dev": true, + "dependencies": { + "graceful-fs": "^4.1.2", + "parse-json": "^2.2.0", + "pify": "^2.0.0", + "pinkie-promise": "^2.0.0", + "strip-bom": "^2.0.0" + }, + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/load-json-file/node_modules/parse-json": { + "version": "2.2.0", + "resolved": "https://registry.npmjs.org/parse-json/-/parse-json-2.2.0.tgz", + "integrity": "sha512-QR/GGaKCkhwk1ePQNYDRKYZ3mwU9ypsKhB0XyFnLQdomyEqk3e8wpW3V5Jp88zbxK4n5ST1nqo+g9juTpownhQ==", + "dev": true, + "dependencies": { + "error-ex": "^1.2.0" + }, + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/load-json-file/node_modules/pify": { + "version": "2.3.0", + "resolved": "https://registry.npmjs.org/pify/-/pify-2.3.0.tgz", + "integrity": "sha512-udgsAY+fTnvv7kI7aaxbqwWNb0AHiB0qBO89PZKPkoTmGOgdbrHDKD+0B2X4uTfJ/FT1R09r9gTsjUjNJotuog==", + "dev": true, + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/load-json-file/node_modules/strip-bom": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/strip-bom/-/strip-bom-2.0.0.tgz", + "integrity": "sha512-kwrX1y7czp1E69n2ajbG65mIo9dqvJ+8aBQXOGVxqwvNbsXdFM6Lq37dLAY3mknUwru8CfcCbfOLL/gMo+fi3g==", + "dev": true, + "dependencies": { + "is-utf8": "^0.2.0" + }, + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/load-yaml-file": { + "version": "0.2.0", + "resolved": "https://registry.npmjs.org/load-yaml-file/-/load-yaml-file-0.2.0.tgz", + "integrity": "sha512-OfCBkGEw4nN6JLtgRidPX6QxjBQGQf72q3si2uvqyFEMbycSFFHwAZeXx6cJgFM9wmLrf9zBwCP3Ivqa+LLZPw==", + "dev": true, + "dependencies": { + "graceful-fs": "^4.1.5", + "js-yaml": "^3.13.0", + "pify": "^4.0.1", + "strip-bom": "^3.0.0" + }, + "engines": { + "node": ">=6" + } + }, + "node_modules/locate-path": { + "version": "5.0.0", + "resolved": "https://registry.npmjs.org/locate-path/-/locate-path-5.0.0.tgz", + "integrity": "sha512-t7hw9pI+WvuwNJXwk5zVHpyhIqzg2qTlklJOf0mVxGSbe3Fp2VieZcduNYjaLDoy6p9uGpQEGWG87WpMKlNq8g==", + "dev": true, + "dependencies": { + "p-locate": "^4.1.0" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/lodash": { + "version": "4.17.21", + "resolved": "https://registry.npmjs.org/lodash/-/lodash-4.17.21.tgz", + "integrity": "sha512-v2kDEe57lecTulaDIuNTPy3Ry4gLGJ6Z1O3vE1krgXZNrsQ+LFTGHVxVjcXPs17LhbZVGedAJv8XZ1tvj5FvSg==", + "dev": true + }, + "node_modules/lodash.assign": { + "version": "4.2.0", + "resolved": "https://registry.npmjs.org/lodash.assign/-/lodash.assign-4.2.0.tgz", + "integrity": "sha512-hFuH8TY+Yji7Eja3mGiuAxBqLagejScbG8GbG0j6o9vzn0YL14My+ktnqtZgFTosKymC9/44wP6s7xyuLfnClw==", + "dev": true + }, + "node_modules/lodash.flatten": { + "version": "4.4.0", + "resolved": "https://registry.npmjs.org/lodash.flatten/-/lodash.flatten-4.4.0.tgz", + "integrity": "sha512-C5N2Z3DgnnKr0LOpv/hKCgKdb7ZZwafIrsesve6lmzvZIRZRGaZ/l6Q8+2W7NaT+ZwO3fFlSCzCzrDCFdJfZ4g==", + "dev": true + }, + "node_modules/lodash.merge": { + "version": "4.6.2", + "resolved": "https://registry.npmjs.org/lodash.merge/-/lodash.merge-4.6.2.tgz", + "integrity": "sha512-0KpjqXRVvrYyCsX1swR/XTK0va6VQkQM6MNo7PqW77ByjAhoARA8EfrP1N4+KlKj8YS0ZUCtRT/YUuhyYDujIQ==", + "dev": true + }, + "node_modules/lodash.startcase": { + "version": "4.4.0", + "resolved": "https://registry.npmjs.org/lodash.startcase/-/lodash.startcase-4.4.0.tgz", + "integrity": "sha512-+WKqsK294HMSc2jEbNgpHpd0JfIBhp7rEV4aqXWqFr6AlXov+SlcgB1Fv01y2kGe3Gc8nMW7VA0SrGuSkRfIEg==", + "dev": true + }, + "node_modules/lodash.truncate": { + "version": "4.4.2", + "resolved": "https://registry.npmjs.org/lodash.truncate/-/lodash.truncate-4.4.2.tgz", + "integrity": "sha512-jttmRe7bRse52OsWIMDLaXxWqRAmtIUccAQ3garviCqJjafXOfNMO0yMfNpdD6zbGaTU0P5Nz7e7gAT6cKmJRw==", + "dev": true + }, + "node_modules/lodash.zip": { + "version": "4.2.0", + "resolved": "https://registry.npmjs.org/lodash.zip/-/lodash.zip-4.2.0.tgz", + "integrity": "sha512-C7IOaBBK/0gMORRBd8OETNx3kmOkgIWIPvyDpZSCTwUrpYmgZwJkjZeOD8ww4xbOUOs4/attY+pciKvadNfFbg==", + "dev": true + }, + "node_modules/log-symbols": { + "version": "4.1.0", + "resolved": "https://registry.npmjs.org/log-symbols/-/log-symbols-4.1.0.tgz", + "integrity": "sha512-8XPvpAA8uyhfteu8pIvQxpJZ7SYYdpUivZpGy6sFsBuKRY/7rQGavedeB8aK+Zkyq6upMFVL/9AW6vOYzfRyLg==", + "dev": true, + "dependencies": { + "chalk": "^4.1.0", + "is-unicode-supported": "^0.1.0" + }, + "engines": { + "node": ">=10" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/log-symbols/node_modules/ansi-styles": { + "version": "4.3.0", + "resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-4.3.0.tgz", + "integrity": "sha512-zbB9rCJAT1rbjiVDb2hqKFHNYLxgtk8NURxZ3IZwD3F6NtxbXZQCnnSi1Lkx+IDohdPlFp222wVALIheZJQSEg==", + "dev": true, + "dependencies": { + "color-convert": "^2.0.1" + }, + "engines": { + "node": ">=8" + }, + "funding": { + "url": "https://github.com/chalk/ansi-styles?sponsor=1" + } + }, + "node_modules/log-symbols/node_modules/chalk": { + "version": "4.1.2", + "resolved": "https://registry.npmjs.org/chalk/-/chalk-4.1.2.tgz", + "integrity": "sha512-oKnbhFyRIXpUuez8iBMmyEa4nbj4IOQyuhc/wy9kY7/WVPcwIO9VA668Pu8RkO7+0G76SLROeyw9CpQ061i4mA==", + "dev": true, + "dependencies": { + "ansi-styles": "^4.1.0", + "supports-color": "^7.1.0" + }, + "engines": { + "node": ">=10" + }, + "funding": { + "url": "https://github.com/chalk/chalk?sponsor=1" + } + }, + "node_modules/log-symbols/node_modules/color-convert": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/color-convert/-/color-convert-2.0.1.tgz", + "integrity": "sha512-RRECPsj7iu/xb5oKYcsFHSppFNnsj/52OVTRKb4zP5onXwVF3zVmmToNcOfGC+CRDpfK/U584fMg38ZHCaElKQ==", + "dev": true, + "dependencies": { + "color-name": "~1.1.4" + }, + "engines": { + "node": ">=7.0.0" + } + }, + "node_modules/log-symbols/node_modules/color-name": { + "version": "1.1.4", + "resolved": "https://registry.npmjs.org/color-name/-/color-name-1.1.4.tgz", + "integrity": "sha512-dOy+3AuW3a2wNbZHIuMZpTcgjGuLU/uBL/ubcZF9OXbDo8ff4O8yVp5Bf0efS8uEoYo5q4Fx7dY9OgQGXgAsQA==", + "dev": true + }, + "node_modules/log-symbols/node_modules/has-flag": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/has-flag/-/has-flag-4.0.0.tgz", + "integrity": "sha512-EykJT/Q1KjTWctppgIAgfSO0tKVuZUjhgMr17kqTumMl6Afv3EISleU7qZUzoXDFTAHTDC4NOoG/ZxU3EvlMPQ==", + "dev": true, + "engines": { + "node": ">=8" + } + }, + "node_modules/log-symbols/node_modules/supports-color": { + "version": "7.2.0", + "resolved": "https://registry.npmjs.org/supports-color/-/supports-color-7.2.0.tgz", + "integrity": "sha512-qpCAvRl9stuOHveKsn7HncJRvv501qIacKzQlO/+Lwxc9+0q2wLyv4Dfvt80/DPn2pqOBsJdDiogXGR9+OvwRw==", + "dev": true, + "dependencies": { + "has-flag": "^4.0.0" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/loupe": { + "version": "2.3.6", + "resolved": "https://registry.npmjs.org/loupe/-/loupe-2.3.6.tgz", + "integrity": "sha512-RaPMZKiMy8/JruncMU5Bt6na1eftNoo++R4Y+N2FrxkDVTrGvcyzFTsaGif4QTeKESheMGegbhw6iUAq+5A8zA==", + "dev": true, + "dependencies": { + "get-func-name": "^2.0.0" + } + }, + "node_modules/lower-case": { + "version": "1.1.4", + "resolved": "https://registry.npmjs.org/lower-case/-/lower-case-1.1.4.tgz", + "integrity": "sha512-2Fgx1Ycm599x+WGpIYwJOvsjmXFzTSc34IwDWALRA/8AopUKAVPwfJ+h5+f85BCp0PWmmJcWzEpxOpoXycMpdA==", + "dev": true + }, + "node_modules/lower-case-first": { + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/lower-case-first/-/lower-case-first-1.0.2.tgz", + "integrity": "sha512-UuxaYakO7XeONbKrZf5FEgkantPf5DUqDayzP5VXZrtRPdH86s4kN47I8B3TW10S4QKiE3ziHNf3kRN//okHjA==", + "dev": true, + "dependencies": { + "lower-case": "^1.1.2" + } + }, + "node_modules/lowercase-keys": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/lowercase-keys/-/lowercase-keys-3.0.0.tgz", + "integrity": "sha512-ozCC6gdQ+glXOQsveKD0YsDy8DSQFjDTz4zyzEHNV5+JP5D62LmfDZ6o1cycFx9ouG940M5dE8C8CTewdj2YWQ==", + "dev": true, + "engines": { + "node": "^12.20.0 || ^14.13.1 || >=16.0.0" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/lru_map": { + "version": "0.3.3", + "resolved": "https://registry.npmjs.org/lru_map/-/lru_map-0.3.3.tgz", + "integrity": "sha512-Pn9cox5CsMYngeDbmChANltQl+5pi6XmTrraMSzhPmMBbmgcxmqWry0U3PGapCU1yB4/LqCcom7qhHZiF/jGfQ==", + "dev": true + }, + "node_modules/lru-cache": { + "version": "5.1.1", + "resolved": "https://registry.npmjs.org/lru-cache/-/lru-cache-5.1.1.tgz", + "integrity": "sha512-KpNARQA3Iwv+jTA0utUVVbrh+Jlrr1Fv0e56GGzAFOXN7dk/FviaDW8LHmK52DlcH4WP2n6gI8vN1aesBFgo9w==", + "dev": true, + "dependencies": { + "yallist": "^3.0.2" + } + }, + "node_modules/map-obj": { + "version": "4.3.0", + "resolved": "https://registry.npmjs.org/map-obj/-/map-obj-4.3.0.tgz", + "integrity": "sha512-hdN1wVrZbb29eBGiGjJbeP8JbKjq1urkHJ/LIP/NY48MZ1QVXUsQBV1G1zvYFHn1XE06cwjBsOI2K3Ulnj1YXQ==", + "dev": true, + "engines": { + "node": ">=8" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/markdown-table": { + "version": "1.1.3", + "resolved": "https://registry.npmjs.org/markdown-table/-/markdown-table-1.1.3.tgz", + "integrity": "sha512-1RUZVgQlpJSPWYbFSpmudq5nHY1doEIv89gBtF0s4gW1GF2XorxcA/70M5vq7rLv0a6mhOUccRsqkwhwLCIQ2Q==", + "dev": true + }, + "node_modules/mcl-wasm": { + "version": "0.7.9", + "resolved": "https://registry.npmjs.org/mcl-wasm/-/mcl-wasm-0.7.9.tgz", + "integrity": "sha512-iJIUcQWA88IJB/5L15GnJVnSQJmf/YaxxV6zRavv83HILHaJQb6y0iFyDMdDO0gN8X37tdxmAOrH/P8B6RB8sQ==", + "dev": true, + "engines": { + "node": ">=8.9.0" + } + }, + "node_modules/md5.js": { + "version": "1.3.5", + "resolved": "https://registry.npmjs.org/md5.js/-/md5.js-1.3.5.tgz", + "integrity": "sha512-xitP+WxNPcTTOgnTJcrhM0xvdPepipPSf3I8EIpGKeFLjt3PlJLIDG3u8EX53ZIubkb+5U2+3rELYpEhHhzdkg==", + "dev": true, + "dependencies": { + "hash-base": "^3.0.0", + "inherits": "^2.0.1", + "safe-buffer": "^5.1.2" + } + }, + "node_modules/media-typer": { + "version": "0.3.0", + "resolved": "https://registry.npmjs.org/media-typer/-/media-typer-0.3.0.tgz", + "integrity": "sha512-dq+qelQ9akHpcOl/gUVRTxVIOkAJ1wR3QAvb4RsVjS8oVoFjDGTc679wJYmUmknUF5HwMLOgb5O+a3KxfWapPQ==", + "dev": true, + "engines": { + "node": ">= 0.6" + } + }, + "node_modules/memory-level": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/memory-level/-/memory-level-1.0.0.tgz", + "integrity": "sha512-UXzwewuWeHBz5krr7EvehKcmLFNoXxGcvuYhC41tRnkrTbJohtS7kVn9akmgirtRygg+f7Yjsfi8Uu5SGSQ4Og==", + "dev": true, + "dependencies": { + "abstract-level": "^1.0.0", + "functional-red-black-tree": "^1.0.1", + "module-error": "^1.0.1" + }, + "engines": { + "node": ">=12" + } + }, + "node_modules/memorystream": { + "version": "0.3.1", + "resolved": "https://registry.npmjs.org/memorystream/-/memorystream-0.3.1.tgz", + "integrity": "sha512-S3UwM3yj5mtUSEfP41UZmt/0SCoVYUcU1rkXv+BQ5Ig8ndL4sPoJNBUJERafdPb5jjHJGuMgytgKvKIf58XNBw==", + "dev": true, + "engines": { + "node": ">= 0.10.0" + } + }, + "node_modules/meow": { + "version": "6.1.1", + "resolved": "https://registry.npmjs.org/meow/-/meow-6.1.1.tgz", + "integrity": "sha512-3YffViIt2QWgTy6Pale5QpopX/IvU3LPL03jOTqp6pGj3VjesdO/U8CuHMKpnQr4shCNCM5fd5XFFvIIl6JBHg==", + "dev": true, + "dependencies": { + "@types/minimist": "^1.2.0", + "camelcase-keys": "^6.2.2", + "decamelize-keys": "^1.1.0", + "hard-rejection": "^2.1.0", + "minimist-options": "^4.0.2", + "normalize-package-data": "^2.5.0", + "read-pkg-up": "^7.0.1", + "redent": "^3.0.0", + "trim-newlines": "^3.0.0", + "type-fest": "^0.13.1", + "yargs-parser": "^18.1.3" + }, + "engines": { + "node": ">=8" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/meow/node_modules/type-fest": { + "version": "0.13.1", + "resolved": "https://registry.npmjs.org/type-fest/-/type-fest-0.13.1.tgz", + "integrity": "sha512-34R7HTnG0XIJcBSn5XhDd7nNFPRcXYRZrBB2O2jdKqYODldSzBAqzsWoZYYvduky73toYS/ESqxPvkDf/F0XMg==", + "dev": true, + "engines": { + "node": ">=10" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/merge-descriptors": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/merge-descriptors/-/merge-descriptors-1.0.1.tgz", + "integrity": "sha512-cCi6g3/Zr1iqQi6ySbseM1Xvooa98N0w31jzUYrXPX2xqObmFGHJ0tQ5u74H3mVh7wLouTseZyYIq39g8cNp1w==", + "dev": true + }, + "node_modules/merge2": { + "version": "1.4.1", + "resolved": "https://registry.npmjs.org/merge2/-/merge2-1.4.1.tgz", + "integrity": "sha512-8q7VEgMJW4J8tcfVPy8g09NcQwZdbwFEqhe/WZkoIzjn/3TGDwtOCYtXGxA3O8tPzpczCCDgv+P2P5y00ZJOOg==", + "dev": true, + "engines": { + "node": ">= 8" + } + }, + "node_modules/merkletreejs": { + "version": "0.2.32", + "resolved": "https://registry.npmjs.org/merkletreejs/-/merkletreejs-0.2.32.tgz", + "integrity": "sha512-TostQBiwYRIwSE5++jGmacu3ODcKAgqb0Y/pnIohXS7sWxh1gCkSptbmF1a43faehRDpcHf7J/kv0Ml2D/zblQ==", + "dev": true, + "dependencies": { + "bignumber.js": "^9.0.1", + "buffer-reverse": "^1.0.1", + "crypto-js": "^3.1.9-1", + "treeify": "^1.1.0", + "web3-utils": "^1.3.4" + }, + "engines": { + "node": ">= 7.6.0" + } + }, + "node_modules/merkletreejs/node_modules/bignumber.js": { + "version": "9.1.1", + "resolved": "https://registry.npmjs.org/bignumber.js/-/bignumber.js-9.1.1.tgz", + "integrity": "sha512-pHm4LsMJ6lzgNGVfZHjMoO8sdoRhOzOH4MLmY65Jg70bpxCKu5iOHNJyfF6OyvYw7t8Fpf35RuzUyqnQsj8Vig==", + "dev": true, + "engines": { + "node": "*" + } + }, + "node_modules/methods": { + "version": "1.1.2", + "resolved": "https://registry.npmjs.org/methods/-/methods-1.1.2.tgz", + "integrity": "sha512-iclAHeNqNm68zFtnZ0e+1L2yUIdvzNoauKU4WBA3VvH/vPFieF7qfRlwUZU+DA9P9bPXIS90ulxoUoCH23sV2w==", + "dev": true, + "engines": { + "node": ">= 0.6" + } + }, + "node_modules/micromatch": { + "version": "4.0.5", + "resolved": "https://registry.npmjs.org/micromatch/-/micromatch-4.0.5.tgz", + "integrity": "sha512-DMy+ERcEW2q8Z2Po+WNXuw3c5YaUSFjAO5GsJqfEl7UjvtIuFKO6ZrKvcItdy98dwFI2N1tg3zNIdKaQT+aNdA==", + "dev": true, + "dependencies": { + "braces": "^3.0.2", + "picomatch": "^2.3.1" + }, + "engines": { + "node": ">=8.6" + } + }, + "node_modules/mime": { + "version": "1.6.0", + "resolved": "https://registry.npmjs.org/mime/-/mime-1.6.0.tgz", + "integrity": "sha512-x0Vn8spI+wuJ1O6S7gnbaQg8Pxh4NNHb7KSINmEWKiPE4RKOplvijn+NkmYmmRgP68mc70j2EbeTFRsrswaQeg==", + "dev": true, + "bin": { + "mime": "cli.js" + }, + "engines": { + "node": ">=4" + } + }, + "node_modules/mime-db": { + "version": "1.52.0", + "resolved": "https://registry.npmjs.org/mime-db/-/mime-db-1.52.0.tgz", + "integrity": "sha512-sPU4uV7dYlvtWJxwwxHD0PuihVNiE7TyAbQ5SWxDCB9mUYvOgroQOwYQQOKPJ8CIbE+1ETVlOoK1UC2nU3gYvg==", + "dev": true, + "engines": { + "node": ">= 0.6" + } + }, + "node_modules/mime-types": { + "version": "2.1.35", + "resolved": "https://registry.npmjs.org/mime-types/-/mime-types-2.1.35.tgz", + "integrity": "sha512-ZDY+bPm5zTTF+YpCrAU9nK0UgICYPT0QtT1NZWFv4s++TNkcgVaT0g6+4R2uI4MjQjzysHB1zxuWL50hzaeXiw==", + "dev": true, + "dependencies": { + "mime-db": "1.52.0" + }, + "engines": { + "node": ">= 0.6" + } + }, + "node_modules/mimic-response": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/mimic-response/-/mimic-response-1.0.1.tgz", + "integrity": "sha512-j5EctnkH7amfV/q5Hgmoal1g2QHFJRraOtmx0JpIqkxhBhI/lJSl1nMpQ45hVarwNETOoWEimndZ4QK0RHxuxQ==", + "dev": true, + "engines": { + "node": ">=4" + } + }, + "node_modules/min-document": { + "version": "2.19.0", + "resolved": "https://registry.npmjs.org/min-document/-/min-document-2.19.0.tgz", + "integrity": "sha512-9Wy1B3m3f66bPPmU5hdA4DR4PB2OfDU/+GS3yAB7IQozE3tqXaVv2zOjgla7MEGSRv95+ILmOuvhLkOK6wJtCQ==", + "dev": true, + "dependencies": { + "dom-walk": "^0.1.0" + } + }, + "node_modules/min-indent": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/min-indent/-/min-indent-1.0.1.tgz", + "integrity": "sha512-I9jwMn07Sy/IwOj3zVkVik2JTvgpaykDZEigL6Rx6N9LbMywwUSMtxET+7lVoDLLd3O3IXwJwvuuns8UB/HeAg==", + "dev": true, + "engines": { + "node": ">=4" + } + }, + "node_modules/minimalistic-assert": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/minimalistic-assert/-/minimalistic-assert-1.0.1.tgz", + "integrity": "sha512-UtJcAD4yEaGtjPezWuO9wC4nwUnVH/8/Im3yEHQP4b67cXlD/Qr9hdITCU1xDbSEXg2XKNaP8jsReV7vQd00/A==", + "dev": true + }, + "node_modules/minimalistic-crypto-utils": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/minimalistic-crypto-utils/-/minimalistic-crypto-utils-1.0.1.tgz", + "integrity": "sha512-JIYlbt6g8i5jKfJ3xz7rF0LXmv2TkDxBLUkiBeZ7bAx4GnnNMr8xFpGnOxn6GhTEHx3SjRrZEoU+j04prX1ktg==", + "dev": true + }, + "node_modules/minimatch": { + "version": "3.1.2", + "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-3.1.2.tgz", + "integrity": "sha512-J7p63hRiAjw1NDEww1W7i37+ByIrOWO5XQQAzZ3VOcL0PNybwpfmV/N05zFAzwQ9USyEcX6t3UO+K5aqBQOIHw==", + "dev": true, + "dependencies": { + "brace-expansion": "^1.1.7" + }, + "engines": { + "node": "*" + } + }, + "node_modules/minimist": { + "version": "1.2.8", + "resolved": "https://registry.npmjs.org/minimist/-/minimist-1.2.8.tgz", + "integrity": "sha512-2yyAR8qBkN3YuheJanUpWC5U3bb5osDywNB8RzDVlDwDHbocAJveqqj1u8+SVD7jkWT4yvsHCpWqqWqAxb0zCA==", + "dev": true, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/minimist-options": { + "version": "4.1.0", + "resolved": "https://registry.npmjs.org/minimist-options/-/minimist-options-4.1.0.tgz", + "integrity": "sha512-Q4r8ghd80yhO/0j1O3B2BjweX3fiHg9cdOwjJd2J76Q135c+NDxGCqdYKQ1SKBuFfgWbAUzBfvYjPUEeNgqN1A==", + "dev": true, + "dependencies": { + "arrify": "^1.0.1", + "is-plain-obj": "^1.1.0", + "kind-of": "^6.0.3" + }, + "engines": { + "node": ">= 6" + } + }, + "node_modules/minipass": { + "version": "2.9.0", + "resolved": "https://registry.npmjs.org/minipass/-/minipass-2.9.0.tgz", + "integrity": "sha512-wxfUjg9WebH+CUDX/CdbRlh5SmfZiy/hpkxaRI16Y9W56Pa75sWgd/rvFilSgrauD9NyFymP/+JFV3KwzIsJeg==", + "dev": true, + "dependencies": { + "safe-buffer": "^5.1.2", + "yallist": "^3.0.0" + } + }, + "node_modules/minizlib": { + "version": "1.3.3", + "resolved": "https://registry.npmjs.org/minizlib/-/minizlib-1.3.3.tgz", + "integrity": "sha512-6ZYMOEnmVsdCeTJVE0W9ZD+pVnE8h9Hma/iOwwRDsdQoePpoX56/8B6z3P9VNwppJuBKNRuFDRNRqRWexT9G9Q==", + "dev": true, + "dependencies": { + "minipass": "^2.9.0" + } + }, + "node_modules/mixme": { + "version": "0.5.9", + "resolved": "https://registry.npmjs.org/mixme/-/mixme-0.5.9.tgz", + "integrity": "sha512-VC5fg6ySUscaWUpI4gxCBTQMH2RdUpNrk+MsbpCYtIvf9SBJdiUey4qE7BXviJsJR4nDQxCZ+3yaYNW3guz/Pw==", + "dev": true, + "engines": { + "node": ">= 8.0.0" + } + }, + "node_modules/mkdirp": { + "version": "0.5.6", + "resolved": "https://registry.npmjs.org/mkdirp/-/mkdirp-0.5.6.tgz", + "integrity": "sha512-FP+p8RB8OWpF3YZBCrP5gtADmtXApB5AMLn+vdyA+PyxCjrCs00mjyUozssO33cwDeT3wNGdLxJ5M//YqtHAJw==", + "dev": true, + "dependencies": { + "minimist": "^1.2.6" + }, + "bin": { + "mkdirp": "bin/cmd.js" + } + }, + "node_modules/mkdirp-promise": { + "version": "5.0.1", + "resolved": "https://registry.npmjs.org/mkdirp-promise/-/mkdirp-promise-5.0.1.tgz", + "integrity": "sha512-Hepn5kb1lJPtVW84RFT40YG1OddBNTOVUZR2bzQUHc+Z03en8/3uX0+060JDhcEzyO08HmipsN9DcnFMxhIL9w==", + "deprecated": "This package is broken and no longer maintained. 'mkdirp' itself supports promises now, please switch to that.", + "dev": true, + "dependencies": { + "mkdirp": "*" + }, + "engines": { + "node": ">=4" + } + }, + "node_modules/mnemonist": { + "version": "0.38.5", + "resolved": "https://registry.npmjs.org/mnemonist/-/mnemonist-0.38.5.tgz", + "integrity": "sha512-bZTFT5rrPKtPJxj8KSV0WkPyNxl72vQepqqVUAW2ARUpUSF2qXMB6jZj7hW5/k7C1rtpzqbD/IIbJwLXUjCHeg==", + "dev": true, + "dependencies": { + "obliterator": "^2.0.0" + } + }, + "node_modules/mocha": { + "version": "10.2.0", + "resolved": "https://registry.npmjs.org/mocha/-/mocha-10.2.0.tgz", + "integrity": "sha512-IDY7fl/BecMwFHzoqF2sg/SHHANeBoMMXFlS9r0OXKDssYE1M5O43wUY/9BVPeIvfH2zmEbBfseqN9gBQZzXkg==", + "dev": true, + "dependencies": { + "ansi-colors": "4.1.1", + "browser-stdout": "1.3.1", + "chokidar": "3.5.3", + "debug": "4.3.4", + "diff": "5.0.0", + "escape-string-regexp": "4.0.0", + "find-up": "5.0.0", + "glob": "7.2.0", + "he": "1.2.0", + "js-yaml": "4.1.0", + "log-symbols": "4.1.0", + "minimatch": "5.0.1", + "ms": "2.1.3", + "nanoid": "3.3.3", + "serialize-javascript": "6.0.0", + "strip-json-comments": "3.1.1", + "supports-color": "8.1.1", + "workerpool": "6.2.1", + "yargs": "16.2.0", + "yargs-parser": "20.2.4", + "yargs-unparser": "2.0.0" + }, + "bin": { + "_mocha": "bin/_mocha", + "mocha": "bin/mocha.js" + }, + "engines": { + "node": ">= 14.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/mochajs" + } + }, + "node_modules/mocha/node_modules/ansi-colors": { + "version": "4.1.1", + "resolved": "https://registry.npmjs.org/ansi-colors/-/ansi-colors-4.1.1.tgz", + "integrity": "sha512-JoX0apGbHaUJBNl6yF+p6JAFYZ666/hhCGKN5t9QFjbJQKUU/g8MNbFDbvfrgKXvI1QpZplPOnwIo99lX/AAmA==", + "dev": true, + "engines": { + "node": ">=6" + } + }, + "node_modules/mocha/node_modules/ansi-regex": { + "version": "5.0.1", + "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-5.0.1.tgz", + "integrity": "sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ==", + "dev": true, + "engines": { + "node": ">=8" + } + }, + "node_modules/mocha/node_modules/argparse": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/argparse/-/argparse-2.0.1.tgz", + "integrity": "sha512-8+9WqebbFzpX9OR+Wa6O29asIogeRMzcGtAINdpMHHyAg10f05aSFVBbcEqGf/PXw1EjAZ+q2/bEBg3DvurK3Q==", + "dev": true + }, + "node_modules/mocha/node_modules/cliui": { + "version": "7.0.4", + "resolved": "https://registry.npmjs.org/cliui/-/cliui-7.0.4.tgz", + "integrity": "sha512-OcRE68cOsVMXp1Yvonl/fzkQOyjLSu/8bhPDfQt0e0/Eb283TKP20Fs2MqoPsr9SwA595rRCA+QMzYc9nBP+JQ==", + "dev": true, + "dependencies": { + "string-width": "^4.2.0", + "strip-ansi": "^6.0.0", + "wrap-ansi": "^7.0.0" + } + }, + "node_modules/mocha/node_modules/escape-string-regexp": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/escape-string-regexp/-/escape-string-regexp-4.0.0.tgz", + "integrity": "sha512-TtpcNJ3XAzx3Gq8sWRzJaVajRs0uVxA2YAkdb1jm2YkPz4G6egUFAyA3n5vtEIZefPk5Wa4UXbKuS5fKkJWdgA==", + "dev": true, + "engines": { + "node": ">=10" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/mocha/node_modules/find-up": { + "version": "5.0.0", + "resolved": "https://registry.npmjs.org/find-up/-/find-up-5.0.0.tgz", + "integrity": "sha512-78/PXT1wlLLDgTzDs7sjq9hzz0vXD+zn+7wypEe4fXQxCmdmqfGsEPQxmiCSQI3ajFV91bVSsvNtrJRiW6nGng==", + "dev": true, + "dependencies": { + "locate-path": "^6.0.0", + "path-exists": "^4.0.0" + }, + "engines": { + "node": ">=10" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/mocha/node_modules/glob": { + "version": "7.2.0", + "resolved": "https://registry.npmjs.org/glob/-/glob-7.2.0.tgz", + "integrity": "sha512-lmLf6gtyrPq8tTjSmrO94wBeQbFR3HbLHbuyD69wuyQkImp2hWqMGB47OX65FBkPffO641IP9jWa1z4ivqG26Q==", + "dev": true, + "dependencies": { + "fs.realpath": "^1.0.0", + "inflight": "^1.0.4", + "inherits": "2", + "minimatch": "^3.0.4", + "once": "^1.3.0", + "path-is-absolute": "^1.0.0" + }, + "engines": { + "node": "*" + }, + "funding": { + "url": "https://github.com/sponsors/isaacs" + } + }, + "node_modules/mocha/node_modules/glob/node_modules/minimatch": { + "version": "3.1.2", + "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-3.1.2.tgz", + "integrity": "sha512-J7p63hRiAjw1NDEww1W7i37+ByIrOWO5XQQAzZ3VOcL0PNybwpfmV/N05zFAzwQ9USyEcX6t3UO+K5aqBQOIHw==", + "dev": true, + "dependencies": { + "brace-expansion": "^1.1.7" + }, + "engines": { + "node": "*" + } + }, + "node_modules/mocha/node_modules/has-flag": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/has-flag/-/has-flag-4.0.0.tgz", + "integrity": "sha512-EykJT/Q1KjTWctppgIAgfSO0tKVuZUjhgMr17kqTumMl6Afv3EISleU7qZUzoXDFTAHTDC4NOoG/ZxU3EvlMPQ==", + "dev": true, + "engines": { + "node": ">=8" + } + }, + "node_modules/mocha/node_modules/is-fullwidth-code-point": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/is-fullwidth-code-point/-/is-fullwidth-code-point-3.0.0.tgz", + "integrity": "sha512-zymm5+u+sCsSWyD9qNaejV3DFvhCKclKdizYaJUuHA83RLjb7nSuGnddCHGv0hk+KY7BMAlsWeK4Ueg6EV6XQg==", + "dev": true, + "engines": { + "node": ">=8" + } + }, + "node_modules/mocha/node_modules/js-yaml": { + "version": "4.1.0", + "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-4.1.0.tgz", + "integrity": "sha512-wpxZs9NoxZaJESJGIZTyDEaYpl0FKSA+FB9aJiyemKhMwkxQg63h4T1KJgUGHpTqPDNRcmmYLugrRjJlBtWvRA==", + "dev": true, + "dependencies": { + "argparse": "^2.0.1" + }, + "bin": { + "js-yaml": "bin/js-yaml.js" + } + }, + "node_modules/mocha/node_modules/locate-path": { + "version": "6.0.0", + "resolved": "https://registry.npmjs.org/locate-path/-/locate-path-6.0.0.tgz", + "integrity": "sha512-iPZK6eYjbxRu3uB4/WZ3EsEIMJFMqAoopl3R+zuq0UjcAm/MO6KCweDgPfP3elTztoKP3KtnVHxTn2NHBSDVUw==", + "dev": true, + "dependencies": { + "p-locate": "^5.0.0" + }, + "engines": { + "node": ">=10" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/mocha/node_modules/minimatch": { + "version": "5.0.1", + "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-5.0.1.tgz", + "integrity": "sha512-nLDxIFRyhDblz3qMuq+SoRZED4+miJ/G+tdDrjkkkRnjAsBexeGpgjLEQ0blJy7rHhR2b93rhQY4SvyWu9v03g==", + "dev": true, + "dependencies": { + "brace-expansion": "^2.0.1" + }, + "engines": { + "node": ">=10" + } + }, + "node_modules/mocha/node_modules/minimatch/node_modules/brace-expansion": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-2.0.1.tgz", + "integrity": "sha512-XnAIvQ8eM+kC6aULx6wuQiwVsnzsi9d3WxzV3FpWTGA19F621kwdbsAcFKXgKUHZWsy+mY6iL1sHTxWEFCytDA==", + "dev": true, + "dependencies": { + "balanced-match": "^1.0.0" + } + }, + "node_modules/mocha/node_modules/ms": { + "version": "2.1.3", + "resolved": "https://registry.npmjs.org/ms/-/ms-2.1.3.tgz", + "integrity": "sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==", + "dev": true + }, + "node_modules/mocha/node_modules/p-locate": { + "version": "5.0.0", + "resolved": "https://registry.npmjs.org/p-locate/-/p-locate-5.0.0.tgz", + "integrity": "sha512-LaNjtRWUBY++zB5nE/NwcaoMylSPk+S+ZHNB1TzdbMJMny6dynpAGt7X/tl/QYq3TIeE6nxHppbo2LGymrG5Pw==", + "dev": true, + "dependencies": { + "p-limit": "^3.0.2" + }, + "engines": { + "node": ">=10" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/mocha/node_modules/string-width": { + "version": "4.2.3", + "resolved": "https://registry.npmjs.org/string-width/-/string-width-4.2.3.tgz", + "integrity": "sha512-wKyQRQpjJ0sIp62ErSZdGsjMJWsap5oRNihHhu6G7JVO/9jIB6UyevL+tXuOqrng8j/cxKTWyWUwvSTriiZz/g==", + "dev": true, + "dependencies": { + "emoji-regex": "^8.0.0", + "is-fullwidth-code-point": "^3.0.0", + "strip-ansi": "^6.0.1" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/mocha/node_modules/strip-ansi": { + "version": "6.0.1", + "resolved": "https://registry.npmjs.org/strip-ansi/-/strip-ansi-6.0.1.tgz", + "integrity": "sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A==", + "dev": true, + "dependencies": { + "ansi-regex": "^5.0.1" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/mocha/node_modules/supports-color": { + "version": "8.1.1", + "resolved": "https://registry.npmjs.org/supports-color/-/supports-color-8.1.1.tgz", + "integrity": "sha512-MpUEN2OodtUzxvKQl72cUF7RQ5EiHsGvSsVG0ia9c5RbWGL2CI4C7EpPS8UTBIplnlzZiNuV56w+FuNxy3ty2Q==", + "dev": true, + "dependencies": { + "has-flag": "^4.0.0" + }, + "engines": { + "node": ">=10" + }, + "funding": { + "url": "https://github.com/chalk/supports-color?sponsor=1" + } + }, + "node_modules/mocha/node_modules/yargs": { + "version": "16.2.0", + "resolved": "https://registry.npmjs.org/yargs/-/yargs-16.2.0.tgz", + "integrity": "sha512-D1mvvtDG0L5ft/jGWkLpG1+m0eQxOfaBvTNELraWj22wSVUMWxZUvYgJYcKh6jGGIkJFhH4IZPQhR4TKpc8mBw==", + "dev": true, + "dependencies": { + "cliui": "^7.0.2", + "escalade": "^3.1.1", + "get-caller-file": "^2.0.5", + "require-directory": "^2.1.1", + "string-width": "^4.2.0", + "y18n": "^5.0.5", + "yargs-parser": "^20.2.2" + }, + "engines": { + "node": ">=10" + } + }, + "node_modules/mocha/node_modules/yargs-parser": { + "version": "20.2.4", + "resolved": "https://registry.npmjs.org/yargs-parser/-/yargs-parser-20.2.4.tgz", + "integrity": "sha512-WOkpgNhPTlE73h4VFAFsOnomJVaovO8VqLDzy5saChRBFQFBoMYirowyW+Q9HB4HFF4Z7VZTiG3iSzJJA29yRA==", + "dev": true, + "engines": { + "node": ">=10" + } + }, + "node_modules/mock-fs": { + "version": "4.14.0", + "resolved": "https://registry.npmjs.org/mock-fs/-/mock-fs-4.14.0.tgz", + "integrity": "sha512-qYvlv/exQ4+svI3UOvPUpLDF0OMX5euvUH0Ny4N5QyRyhNdgAgUrVH3iUINSzEPLvx0kbo/Bp28GJKIqvE7URw==", + "dev": true + }, + "node_modules/module-error": { + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/module-error/-/module-error-1.0.2.tgz", + "integrity": "sha512-0yuvsqSCv8LbaOKhnsQ/T5JhyFlCYLPXK3U2sgV10zoKQwzs/MyfuQUOZQ1V/6OCOJsK/TRgNVrPuPDqtdMFtA==", + "dev": true, + "engines": { + "node": ">=10" + } + }, + "node_modules/ms": { + "version": "2.1.2", + "resolved": "https://registry.npmjs.org/ms/-/ms-2.1.2.tgz", + "integrity": "sha512-sGkPx+VjMtmA6MX27oA4FBFELFCZZ4S4XqeGOXCv68tT+jb3vk/RyaKWP0PTKyWtmLSM0b+adUTEvbs1PEaH2w==", + "dev": true + }, + "node_modules/multibase": { + "version": "0.6.1", + "resolved": "https://registry.npmjs.org/multibase/-/multibase-0.6.1.tgz", + "integrity": "sha512-pFfAwyTjbbQgNc3G7D48JkJxWtoJoBMaR4xQUOuB8RnCgRqaYmWNFeJTTvrJ2w51bjLq2zTby6Rqj9TQ9elSUw==", + "deprecated": "This module has been superseded by the multiformats module", + "dev": true, + "dependencies": { + "base-x": "^3.0.8", + "buffer": "^5.5.0" + } + }, + "node_modules/multicodec": { + "version": "0.5.7", + "resolved": "https://registry.npmjs.org/multicodec/-/multicodec-0.5.7.tgz", + "integrity": "sha512-PscoRxm3f+88fAtELwUnZxGDkduE2HD9Q6GHUOywQLjOGT/HAdhjLDYNZ1e7VR0s0TP0EwZ16LNUTFpoBGivOA==", + "deprecated": "This module has been superseded by the multiformats module", + "dev": true, + "dependencies": { + "varint": "^5.0.0" + } + }, + "node_modules/multihashes": { + "version": "0.4.21", + "resolved": "https://registry.npmjs.org/multihashes/-/multihashes-0.4.21.tgz", + "integrity": "sha512-uVSvmeCWf36pU2nB4/1kzYZjsXD9vofZKpgudqkceYY5g2aZZXJ5r9lxuzoRLl1OAp28XljXsEJ/X/85ZsKmKw==", + "dev": true, + "dependencies": { + "buffer": "^5.5.0", + "multibase": "^0.7.0", + "varint": "^5.0.0" + } + }, + "node_modules/multihashes/node_modules/multibase": { + "version": "0.7.0", + "resolved": "https://registry.npmjs.org/multibase/-/multibase-0.7.0.tgz", + "integrity": "sha512-TW8q03O0f6PNFTQDvh3xxH03c8CjGaaYrjkl9UQPG6rz53TQzzxJVCIWVjzcbN/Q5Y53Zd0IBQBMVktVgNx4Fg==", + "deprecated": "This module has been superseded by the multiformats module", + "dev": true, + "dependencies": { + "base-x": "^3.0.8", + "buffer": "^5.5.0" + } + }, + "node_modules/nano-base32": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/nano-base32/-/nano-base32-1.0.1.tgz", + "integrity": "sha512-sxEtoTqAPdjWVGv71Q17koMFGsOMSiHsIFEvzOM7cNp8BXB4AnEwmDabm5dorusJf/v1z7QxaZYxUorU9RKaAw==", + "dev": true + }, + "node_modules/nano-json-stream-parser": { + "version": "0.1.2", + "resolved": "https://registry.npmjs.org/nano-json-stream-parser/-/nano-json-stream-parser-0.1.2.tgz", + "integrity": "sha512-9MqxMH/BSJC7dnLsEMPyfN5Dvoo49IsPFYMcHw3Bcfc2kN0lpHRBSzlMSVx4HGyJ7s9B31CyBTVehWJoQ8Ctew==", + "dev": true + }, + "node_modules/nanoid": { + "version": "3.3.3", + "resolved": "https://registry.npmjs.org/nanoid/-/nanoid-3.3.3.tgz", + "integrity": "sha512-p1sjXuopFs0xg+fPASzQ28agW1oHD7xDsd9Xkf3T15H3c/cifrFHVwrh74PdoklAPi+i7MdRsE47vm2r6JoB+w==", + "dev": true, + "bin": { + "nanoid": "bin/nanoid.cjs" + }, + "engines": { + "node": "^10 || ^12 || ^13.7 || ^14 || >=15.0.1" + } + }, + "node_modules/napi-macros": { + "version": "2.2.2", + "resolved": "https://registry.npmjs.org/napi-macros/-/napi-macros-2.2.2.tgz", + "integrity": "sha512-hmEVtAGYzVQpCKdbQea4skABsdXW4RUh5t5mJ2zzqowJS2OyXZTU1KhDVFhx+NlWZ4ap9mqR9TcDO3LTTttd+g==", + "dev": true + }, + "node_modules/natural-compare": { + "version": "1.4.0", + "resolved": "https://registry.npmjs.org/natural-compare/-/natural-compare-1.4.0.tgz", + "integrity": "sha512-OWND8ei3VtNC9h7V60qff3SVobHr996CTwgxubgyQYEpg290h9J0buyECNNJexkFm5sOajh5G116RYA1c8ZMSw==", + "dev": true + }, + "node_modules/negotiator": { + "version": "0.6.3", + "resolved": "https://registry.npmjs.org/negotiator/-/negotiator-0.6.3.tgz", + "integrity": "sha512-+EUsqGPLsM+j/zdChZjsnX51g4XrHFOIXwfnCVPGlQk/k5giakcKsuxCObBRu6DSm9opw/O6slWbJdghQM4bBg==", + "dev": true, + "engines": { + "node": ">= 0.6" + } + }, + "node_modules/neo-async": { + "version": "2.6.2", + "resolved": "https://registry.npmjs.org/neo-async/-/neo-async-2.6.2.tgz", + "integrity": "sha512-Yd3UES5mWCSqR+qNT93S3UoYUkqAZ9lLg8a7g9rimsWmYGK8cVToA4/sF3RrshdyV3sAGMXVUmpMYOw+dLpOuw==", + "dev": true + }, + "node_modules/next-tick": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/next-tick/-/next-tick-1.1.0.tgz", + "integrity": "sha512-CXdUiJembsNjuToQvxayPZF9Vqht7hewsvy2sOWafLvi2awflj9mOC6bHIg50orX8IJvWKY9wYQ/zB2kogPslQ==", + "dev": true + }, + "node_modules/no-case": { + "version": "2.3.2", + "resolved": "https://registry.npmjs.org/no-case/-/no-case-2.3.2.tgz", + "integrity": "sha512-rmTZ9kz+f3rCvK2TD1Ue/oZlns7OGoIWP4fc3llxxRXlOkHKoWPPWJOfFYpITabSow43QJbRIoHQXtt10VldyQ==", + "dev": true, + "dependencies": { + "lower-case": "^1.1.1" + } + }, + "node_modules/node-addon-api": { + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/node-addon-api/-/node-addon-api-2.0.2.tgz", + "integrity": "sha512-Ntyt4AIXyaLIuMHF6IOoTakB3K+RWxwtsHNRxllEoA6vPwP9o4866g6YWDLUdnucilZhmkxiHwHr11gAENw+QA==", + "dev": true + }, + "node_modules/node-emoji": { + "version": "1.11.0", + "resolved": "https://registry.npmjs.org/node-emoji/-/node-emoji-1.11.0.tgz", + "integrity": "sha512-wo2DpQkQp7Sjm2A0cq+sN7EHKO6Sl0ctXeBdFZrL9T9+UywORbufTcTZxom8YqpLQt/FqNMUkOpkZrJVYSKD3A==", + "dev": true, + "dependencies": { + "lodash": "^4.17.21" + } + }, + "node_modules/node-environment-flags": { + "version": "1.0.6", + "resolved": "https://registry.npmjs.org/node-environment-flags/-/node-environment-flags-1.0.6.tgz", + "integrity": "sha512-5Evy2epuL+6TM0lCQGpFIj6KwiEsGh1SrHUhTbNX+sLbBtjidPZFAnVK9y5yU1+h//RitLbRHTIMyxQPtxMdHw==", + "dev": true, + "dependencies": { + "object.getownpropertydescriptors": "^2.0.3", + "semver": "^5.7.0" + } + }, + "node_modules/node-environment-flags/node_modules/semver": { + "version": "5.7.1", + "resolved": "https://registry.npmjs.org/semver/-/semver-5.7.1.tgz", + "integrity": "sha512-sauaDf/PZdVgrLTNYHRtpXa1iRiKcaebiKQ1BJdpQlWH2lCvexQdX55snPFyK7QzpudqbCI0qXFfOasHdyNDGQ==", + "dev": true, + "bin": { + "semver": "bin/semver" + } + }, + "node_modules/node-fetch": { + "version": "2.6.12", + "resolved": "https://registry.npmjs.org/node-fetch/-/node-fetch-2.6.12.tgz", + "integrity": "sha512-C/fGU2E8ToujUivIO0H+tpQ6HWo4eEmchoPIoXtxCrVghxdKq+QOHqEZW7tuP3KlV3bC8FRMO5nMCC7Zm1VP6g==", + "dev": true, + "dependencies": { + "whatwg-url": "^5.0.0" + }, + "engines": { + "node": "4.x || >=6.0.0" + }, + "peerDependencies": { + "encoding": "^0.1.0" + }, + "peerDependenciesMeta": { + "encoding": { + "optional": true + } + } + }, + "node_modules/node-gyp-build": { + "version": "4.6.0", + "resolved": "https://registry.npmjs.org/node-gyp-build/-/node-gyp-build-4.6.0.tgz", + "integrity": "sha512-NTZVKn9IylLwUzaKjkas1e4u2DLNcV4rdYagA4PWdPwW87Bi7z+BznyKSRwS/761tV/lzCGXplWsiaMjLqP2zQ==", + "dev": true, + "bin": { + "node-gyp-build": "bin.js", + "node-gyp-build-optional": "optional.js", + "node-gyp-build-test": "build-test.js" + } + }, + "node_modules/node-interval-tree": { + "version": "2.1.2", + "resolved": "https://registry.npmjs.org/node-interval-tree/-/node-interval-tree-2.1.2.tgz", + "integrity": "sha512-bJ9zMDuNGzVQg1xv0bCPzyEDxHgbrx7/xGj6CDokvizZZmastPsOh0JJLuY8wA5q2SfX1TLNMk7XNV8WxbGxzA==", + "dev": true, + "dependencies": { + "shallowequal": "^1.1.0" + }, + "engines": { + "node": ">= 14.0.0" + } + }, + "node_modules/nofilter": { + "version": "3.1.0", + "resolved": "https://registry.npmjs.org/nofilter/-/nofilter-3.1.0.tgz", + "integrity": "sha512-l2NNj07e9afPnhAhvgVrCD/oy2Ai1yfLpuo3EpiO1jFTsB4sFz6oIfAfSZyQzVpkZQ9xS8ZS5g1jCBgq4Hwo0g==", + "dev": true, + "engines": { + "node": ">=12.19" + } + }, + "node_modules/nopt": { + "version": "3.0.6", + "resolved": "https://registry.npmjs.org/nopt/-/nopt-3.0.6.tgz", + "integrity": "sha512-4GUt3kSEYmk4ITxzB/b9vaIDfUVWN/Ml1Fwl11IlnIG2iaJ9O6WXZ9SrYM9NLI8OCBieN2Y8SWC2oJV0RQ7qYg==", + "dev": true, + "dependencies": { + "abbrev": "1" + }, + "bin": { + "nopt": "bin/nopt.js" + } + }, + "node_modules/normalize-package-data": { + "version": "2.5.0", + "resolved": "https://registry.npmjs.org/normalize-package-data/-/normalize-package-data-2.5.0.tgz", + "integrity": "sha512-/5CMN3T0R4XTj4DcGaexo+roZSdSFW/0AOOTROrjxzCG1wrWXEsGbRKevjlIL+ZDE4sZlJr5ED4YW0yqmkK+eA==", + "dev": true, + "dependencies": { + "hosted-git-info": "^2.1.4", + "resolve": "^1.10.0", + "semver": "2 || 3 || 4 || 5", + "validate-npm-package-license": "^3.0.1" + } + }, + "node_modules/normalize-package-data/node_modules/semver": { + "version": "5.7.1", + "resolved": "https://registry.npmjs.org/semver/-/semver-5.7.1.tgz", + "integrity": "sha512-sauaDf/PZdVgrLTNYHRtpXa1iRiKcaebiKQ1BJdpQlWH2lCvexQdX55snPFyK7QzpudqbCI0qXFfOasHdyNDGQ==", + "dev": true, + "bin": { + "semver": "bin/semver" + } + }, + "node_modules/normalize-path": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/normalize-path/-/normalize-path-3.0.0.tgz", + "integrity": "sha512-6eZs5Ls3WtCisHWp9S2GUy8dqkpGi4BVSz3GaqiE6ezub0512ESztXUwUB6C6IKbQkY2Pnb/mD4WYojCRwcwLA==", + "dev": true, + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/normalize-url": { + "version": "6.1.0", + "resolved": "https://registry.npmjs.org/normalize-url/-/normalize-url-6.1.0.tgz", + "integrity": "sha512-DlL+XwOy3NxAQ8xuC0okPgK46iuVNAK01YN7RueYBqqFeGsBjV9XmCAzAdgt+667bCl5kPh9EqKKDwnaPG1I7A==", + "dev": true, + "engines": { + "node": ">=10" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/nth-check": { + "version": "2.1.1", + "resolved": "https://registry.npmjs.org/nth-check/-/nth-check-2.1.1.tgz", + "integrity": "sha512-lqjrjmaOoAnWfMmBPL+XNnynZh2+swxiX3WUE0s4yEHI6m+AwrK2UZOimIRl3X/4QctVqS8AiZjFqyOGrMXb/w==", + "dev": true, + "dependencies": { + "boolbase": "^1.0.0" + }, + "funding": { + "url": "https://github.com/fb55/nth-check?sponsor=1" + } + }, + "node_modules/number-is-nan": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/number-is-nan/-/number-is-nan-1.0.1.tgz", + "integrity": "sha512-4jbtZXNAsfZbAHiiqjLPBiCl16dES1zI4Hpzzxw61Tk+loF+sBDBKx1ICKKKwIqQ7M0mFn1TmkN7euSncWgHiQ==", + "dev": true, + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/number-to-bn": { + "version": "1.7.0", + "resolved": "https://registry.npmjs.org/number-to-bn/-/number-to-bn-1.7.0.tgz", + "integrity": "sha512-wsJ9gfSz1/s4ZsJN01lyonwuxA1tml6X1yBDnfpMglypcBRFZZkus26EdPSlqS5GJfYddVZa22p3VNb3z5m5Ig==", + "dev": true, + "dependencies": { + "bn.js": "4.11.6", + "strip-hex-prefix": "1.0.0" + }, + "engines": { + "node": ">=6.5.0", + "npm": ">=3" + } + }, + "node_modules/number-to-bn/node_modules/bn.js": { + "version": "4.11.6", + "resolved": "https://registry.npmjs.org/bn.js/-/bn.js-4.11.6.tgz", + "integrity": "sha512-XWwnNNFCuuSQ0m3r3C4LE3EiORltHd9M05pq6FOlVeiophzRbMo50Sbz1ehl8K3Z+jw9+vmgnXefY1hz8X+2wA==", + "dev": true + }, + "node_modules/oauth-sign": { + "version": "0.9.0", + "resolved": "https://registry.npmjs.org/oauth-sign/-/oauth-sign-0.9.0.tgz", + "integrity": "sha512-fexhUFFPTGV8ybAtSIGbV6gOkSv8UtRbDBnAyLQw4QPKkgNlsH2ByPGtMUqdWkos6YCRmAqViwgZrJc/mRDzZQ==", + "dev": true, + "engines": { + "node": "*" + } + }, + "node_modules/object-assign": { + "version": "4.1.1", + "resolved": "https://registry.npmjs.org/object-assign/-/object-assign-4.1.1.tgz", + "integrity": "sha512-rJgTQnkUnH1sFw8yT6VSU3zD3sWmu6sZhIseY8VX+GRu3P6F7Fu+JNDoXfklElbLJSnc3FUQHVe4cU5hj+BcUg==", + "dev": true, + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/object-inspect": { + "version": "1.12.3", + "resolved": "https://registry.npmjs.org/object-inspect/-/object-inspect-1.12.3.tgz", + "integrity": "sha512-geUvdk7c+eizMNUDkRpW1wJwgfOiOeHbxBR/hLXK1aT6zmVSO0jsQcs7fj6MGw89jC/cjGfLcNOrtMYtGqm81g==", + "dev": true, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/object-keys": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/object-keys/-/object-keys-1.1.1.tgz", + "integrity": "sha512-NuAESUOUMrlIXOfHKzD6bpPu3tYt3xvjNdRIQ+FeT0lNb4K8WR70CaDxhuNguS2XG+GjkyMwOzsN5ZktImfhLA==", + "dev": true, + "engines": { + "node": ">= 0.4" + } + }, + "node_modules/object.assign": { + "version": "4.1.4", + "resolved": "https://registry.npmjs.org/object.assign/-/object.assign-4.1.4.tgz", + "integrity": "sha512-1mxKf0e58bvyjSCtKYY4sRe9itRk3PJpquJOjeIkz885CczcI4IvJJDLPS72oowuSh+pBxUFROpX+TU++hxhZQ==", + "dev": true, + "dependencies": { + "call-bind": "^1.0.2", + "define-properties": "^1.1.4", + "has-symbols": "^1.0.3", + "object-keys": "^1.1.1" + }, + "engines": { + "node": ">= 0.4" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/object.getownpropertydescriptors": { + "version": "2.1.6", + "resolved": "https://registry.npmjs.org/object.getownpropertydescriptors/-/object.getownpropertydescriptors-2.1.6.tgz", + "integrity": "sha512-lq+61g26E/BgHv0ZTFgRvi7NMEPuAxLkFU7rukXjc/AlwH4Am5xXVnIXy3un1bg/JPbXHrixRkK1itUzzPiIjQ==", + "dev": true, + "dependencies": { + "array.prototype.reduce": "^1.0.5", + "call-bind": "^1.0.2", + "define-properties": "^1.2.0", + "es-abstract": "^1.21.2", + "safe-array-concat": "^1.0.0" + }, + "engines": { + "node": ">= 0.8" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/obliterator": { + "version": "2.0.4", + "resolved": "https://registry.npmjs.org/obliterator/-/obliterator-2.0.4.tgz", + "integrity": "sha512-lgHwxlxV1qIg1Eap7LgIeoBWIMFibOjbrYPIPJZcI1mmGAI2m3lNYpK12Y+GBdPQ0U1hRwSord7GIaawz962qQ==", + "dev": true + }, + "node_modules/oboe": { + "version": "2.1.5", + "resolved": "https://registry.npmjs.org/oboe/-/oboe-2.1.5.tgz", + "integrity": "sha512-zRFWiF+FoicxEs3jNI/WYUrVEgA7DeET/InK0XQuudGHRg8iIob3cNPrJTKaz4004uaA9Pbe+Dwa8iluhjLZWA==", + "dev": true, + "dependencies": { + "http-https": "^1.0.0" + } + }, + "node_modules/on-finished": { + "version": "2.4.1", + "resolved": "https://registry.npmjs.org/on-finished/-/on-finished-2.4.1.tgz", + "integrity": "sha512-oVlzkg3ENAhCk2zdv7IJwd/QUD4z2RxRwpkcGY8psCVcCYZNq4wYnVWALHM+brtuJjePWiYF/ClmuDr8Ch5+kg==", + "dev": true, + "dependencies": { + "ee-first": "1.1.1" + }, + "engines": { + "node": ">= 0.8" + } + }, + "node_modules/once": { + "version": "1.4.0", + "resolved": "https://registry.npmjs.org/once/-/once-1.4.0.tgz", + "integrity": "sha512-lNaJgI+2Q5URQBkccEKHTQOPaXdUxnZZElQTZY0MFUAuaEqe1E+Nyvgdz/aIyNi6Z9MzO5dv1H8n58/GELp3+w==", + "dev": true, + "dependencies": { + "wrappy": "1" + } + }, + "node_modules/optionator": { + "version": "0.9.3", + "resolved": "https://registry.npmjs.org/optionator/-/optionator-0.9.3.tgz", + "integrity": "sha512-JjCoypp+jKn1ttEFExxhetCKeJt9zhAgAve5FXHixTvFDW/5aEktX9bufBKLRRMdU7bNtpLfcGu94B3cdEJgjg==", + "dev": true, + "dependencies": { + "@aashutoshrathi/word-wrap": "^1.2.3", + "deep-is": "^0.1.3", + "fast-levenshtein": "^2.0.6", + "levn": "^0.4.1", + "prelude-ls": "^1.2.1", + "type-check": "^0.4.0" + }, + "engines": { + "node": ">= 0.8.0" + } + }, + "node_modules/os-locale": { + "version": "1.4.0", + "resolved": "https://registry.npmjs.org/os-locale/-/os-locale-1.4.0.tgz", + "integrity": "sha512-PRT7ZORmwu2MEFt4/fv3Q+mEfN4zetKxufQrkShY2oGvUms9r8otu5HfdyIFHkYXjO7laNsoVGmM2MANfuTA8g==", + "dev": true, + "dependencies": { + "lcid": "^1.0.0" + }, + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/os-tmpdir": { + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/os-tmpdir/-/os-tmpdir-1.0.2.tgz", + "integrity": "sha512-D2FR03Vir7FIu45XBY20mTb+/ZSWB00sjU9jdQXt83gDrI4Ztz5Fs7/yy74g2N5SVQY4xY1qDr4rNddwYRVX0g==", + "dev": true, + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/outdent": { + "version": "0.5.0", + "resolved": "https://registry.npmjs.org/outdent/-/outdent-0.5.0.tgz", + "integrity": "sha512-/jHxFIzoMXdqPzTaCpFzAAWhpkSjZPF4Vsn6jAfNpmbH/ymsmd7Qc6VE9BGn0L6YMj6uwpQLxCECpus4ukKS9Q==", + "dev": true + }, + "node_modules/p-cancelable": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/p-cancelable/-/p-cancelable-3.0.0.tgz", + "integrity": "sha512-mlVgR3PGuzlo0MmTdk4cXqXWlwQDLnONTAg6sm62XkMJEiRxN3GL3SffkYvqwonbkJBcrI7Uvv5Zh9yjvn2iUw==", + "dev": true, + "engines": { + "node": ">=12.20" + } + }, + "node_modules/p-filter": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/p-filter/-/p-filter-2.1.0.tgz", + "integrity": "sha512-ZBxxZ5sL2HghephhpGAQdoskxplTwr7ICaehZwLIlfL6acuVgZPm8yBNuRAFBGEqtD/hmUeq9eqLg2ys9Xr/yw==", + "dev": true, + "dependencies": { + "p-map": "^2.0.0" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/p-filter/node_modules/p-map": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/p-map/-/p-map-2.1.0.tgz", + "integrity": "sha512-y3b8Kpd8OAN444hxfBbFfj1FY/RjtTd8tzYwhUqNYXx0fXx2iX4maP4Qr6qhIKbQXI02wTLAda4fYUbDagTUFw==", + "dev": true, + "engines": { + "node": ">=6" + } + }, + "node_modules/p-limit": { + "version": "3.1.0", + "resolved": "https://registry.npmjs.org/p-limit/-/p-limit-3.1.0.tgz", + "integrity": "sha512-TYOanM3wGwNGsZN2cVTYPArw454xnXj5qmWF1bEoAc4+cU/ol7GVh7odevjp1FNHduHc3KZMcFduxU5Xc6uJRQ==", + "dev": true, + "dependencies": { + "yocto-queue": "^0.1.0" + }, + "engines": { + "node": ">=10" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/p-locate": { + "version": "4.1.0", + "resolved": "https://registry.npmjs.org/p-locate/-/p-locate-4.1.0.tgz", + "integrity": "sha512-R79ZZ/0wAxKGu3oYMlz8jy/kbhsNrS7SKZ7PxEHBgJ5+F2mtFW2fK2cOtBh1cHYkQsbzFV7I+EoRKe6Yt0oK7A==", + "dev": true, + "dependencies": { + "p-limit": "^2.2.0" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/p-locate/node_modules/p-limit": { + "version": "2.3.0", + "resolved": "https://registry.npmjs.org/p-limit/-/p-limit-2.3.0.tgz", + "integrity": "sha512-//88mFWSJx8lxCzwdAABTJL2MyWB12+eIY7MDL2SqLmAkeKU9qxRvWuSyTjm3FUmpBEMuFfckAIqEaVGUDxb6w==", + "dev": true, + "dependencies": { + "p-try": "^2.0.0" + }, + "engines": { + "node": ">=6" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/p-map": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/p-map/-/p-map-4.0.0.tgz", + "integrity": "sha512-/bjOqmgETBYB5BoEeGVea8dmvHb2m9GLy1E9W43yeyfP6QQCZGFNa+XRceJEuDB6zqr+gKpIAmlLebMpykw/MQ==", + "dev": true, + "dependencies": { + "aggregate-error": "^3.0.0" + }, + "engines": { + "node": ">=10" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/p-try": { + "version": "2.2.0", + "resolved": "https://registry.npmjs.org/p-try/-/p-try-2.2.0.tgz", + "integrity": "sha512-R4nPAVTAU0B9D35/Gk3uJf/7XYbQcyohSKdvAxIRSNghFl4e71hVoGnBNQz9cWaXxO2I10KTC+3jMdvvoKw6dQ==", + "dev": true, + "engines": { + "node": ">=6" + } + }, + "node_modules/pako": { + "version": "1.0.11", + "resolved": "https://registry.npmjs.org/pako/-/pako-1.0.11.tgz", + "integrity": "sha512-4hLB8Py4zZce5s4yd9XzopqwVv/yGNhV1Bl8NTmCq1763HeK2+EwVTv+leGeL13Dnh2wfbqowVPXCIO0z4taYw==", + "dev": true + }, + "node_modules/param-case": { + "version": "2.1.1", + "resolved": "https://registry.npmjs.org/param-case/-/param-case-2.1.1.tgz", + "integrity": "sha512-eQE845L6ot89sk2N8liD8HAuH4ca6Vvr7VWAWwt7+kvvG5aBcPmmphQ68JsEG2qa9n1TykS2DLeMt363AAH8/w==", + "dev": true, + "dependencies": { + "no-case": "^2.2.0" + } + }, + "node_modules/parent-module": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/parent-module/-/parent-module-1.0.1.tgz", + "integrity": "sha512-GQ2EWRpQV8/o+Aw8YqtfZZPfNRWZYkbidE9k5rpl/hC3vtHHBfGm2Ifi6qWV+coDGkrUKZAxE3Lot5kcsRlh+g==", + "dev": true, + "dependencies": { + "callsites": "^3.0.0" + }, + "engines": { + "node": ">=6" + } + }, + "node_modules/parse-cache-control": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/parse-cache-control/-/parse-cache-control-1.0.1.tgz", + "integrity": "sha512-60zvsJReQPX5/QP0Kzfd/VrpjScIQ7SHBW6bFCYfEP+fp0Eppr1SHhIO5nd1PjZtvclzSzES9D/p5nFJurwfWg==", + "dev": true + }, + "node_modules/parse-headers": { + "version": "2.0.5", + "resolved": "https://registry.npmjs.org/parse-headers/-/parse-headers-2.0.5.tgz", + "integrity": "sha512-ft3iAoLOB/MlwbNXgzy43SWGP6sQki2jQvAyBg/zDFAgr9bfNWZIUj42Kw2eJIl8kEi4PbgE6U1Zau/HwI75HA==", + "dev": true + }, + "node_modules/parse-json": { + "version": "5.2.0", + "resolved": "https://registry.npmjs.org/parse-json/-/parse-json-5.2.0.tgz", + "integrity": "sha512-ayCKvm/phCGxOkYRSCM82iDwct8/EonSEgCSxWxD7ve6jHggsFl4fZVQBPRNgQoKiuV/odhFrGzQXZwbifC8Rg==", + "dev": true, + "dependencies": { + "@babel/code-frame": "^7.0.0", + "error-ex": "^1.3.1", + "json-parse-even-better-errors": "^2.3.0", + "lines-and-columns": "^1.1.6" + }, + "engines": { + "node": ">=8" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/parse5": { + "version": "7.1.2", + "resolved": "https://registry.npmjs.org/parse5/-/parse5-7.1.2.tgz", + "integrity": "sha512-Czj1WaSVpaoj0wbhMzLmWD69anp2WH7FXMB9n1Sy8/ZFF9jolSQVMu1Ij5WIyGmcBmhk7EOndpO4mIpihVqAXw==", + "dev": true, + "dependencies": { + "entities": "^4.4.0" + }, + "funding": { + "url": "https://github.com/inikulin/parse5?sponsor=1" + } + }, + "node_modules/parse5-htmlparser2-tree-adapter": { + "version": "7.0.0", + "resolved": "https://registry.npmjs.org/parse5-htmlparser2-tree-adapter/-/parse5-htmlparser2-tree-adapter-7.0.0.tgz", + "integrity": "sha512-B77tOZrqqfUfnVcOrUvfdLbz4pu4RopLD/4vmu3HUPswwTA8OH0EMW9BlWR2B0RCoiZRAHEUu7IxeP1Pd1UU+g==", + "dev": true, + "dependencies": { + "domhandler": "^5.0.2", + "parse5": "^7.0.0" + }, + "funding": { + "url": "https://github.com/inikulin/parse5?sponsor=1" + } + }, + "node_modules/parseurl": { + "version": "1.3.3", + "resolved": "https://registry.npmjs.org/parseurl/-/parseurl-1.3.3.tgz", + "integrity": "sha512-CiyeOxFT/JZyN5m0z9PfXw4SCBJ6Sygz1Dpl0wqjlhDEGGBP1GnsUVEL0p63hoG1fcj3fHynXi9NYO4nWOL+qQ==", + "dev": true, + "engines": { + "node": ">= 0.8" + } + }, + "node_modules/pascal-case": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/pascal-case/-/pascal-case-2.0.1.tgz", + "integrity": "sha512-qjS4s8rBOJa2Xm0jmxXiyh1+OFf6ekCWOvUaRgAQSktzlTbMotS0nmG9gyYAybCWBcuP4fsBeRCKNwGBnMe2OQ==", + "dev": true, + "dependencies": { + "camel-case": "^3.0.0", + "upper-case-first": "^1.1.0" + } + }, + "node_modules/path-case": { + "version": "2.1.1", + "resolved": "https://registry.npmjs.org/path-case/-/path-case-2.1.1.tgz", + "integrity": "sha512-Ou0N05MioItesaLr9q8TtHVWmJ6fxWdqKB2RohFmNWVyJ+2zeKIeDNWAN6B/Pe7wpzWChhZX6nONYmOnMeJQ/Q==", + "dev": true, + "dependencies": { + "no-case": "^2.2.0" + } + }, + "node_modules/path-exists": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/path-exists/-/path-exists-4.0.0.tgz", + "integrity": "sha512-ak9Qy5Q7jYb2Wwcey5Fpvg2KoAc/ZIhLSLOSBmRmygPsGwkVVt0fZa0qrtMz+m6tJTAHfZQ8FnmB4MG4LWy7/w==", + "dev": true, + "engines": { + "node": ">=8" + } + }, + "node_modules/path-is-absolute": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/path-is-absolute/-/path-is-absolute-1.0.1.tgz", + "integrity": "sha512-AVbw3UJ2e9bq64vSaS9Am0fje1Pa8pbGqTTsmXfaIiMpnr5DlDhfJOuLj9Sf95ZPVDAUerDfEk88MPmPe7UCQg==", + "dev": true, + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/path-key": { + "version": "3.1.1", + "resolved": "https://registry.npmjs.org/path-key/-/path-key-3.1.1.tgz", + "integrity": "sha512-ojmeN0qd+y0jszEtoY48r0Peq5dwMEkIlCOu6Q5f41lfkswXuKtYrhgoTpLnyIcHm24Uhqx+5Tqm2InSwLhE6Q==", + "dev": true, + "engines": { + "node": ">=8" + } + }, + "node_modules/path-parse": { + "version": "1.0.7", + "resolved": "https://registry.npmjs.org/path-parse/-/path-parse-1.0.7.tgz", + "integrity": "sha512-LDJzPVEEEPR+y48z93A0Ed0yXb8pAByGWo/k5YYdYgpY2/2EsOsksJrq7lOHxryrVOn1ejG6oAp8ahvOIQD8sw==", + "dev": true + }, + "node_modules/path-to-regexp": { + "version": "0.1.7", + "resolved": "https://registry.npmjs.org/path-to-regexp/-/path-to-regexp-0.1.7.tgz", + "integrity": "sha512-5DFkuoqlv1uYQKxy8omFBeJPQcdoE07Kv2sferDCrAq1ohOU+MSDswDIbnx3YAM60qIOnYa53wBhXW0EbMonrQ==", + "dev": true + }, + "node_modules/path-type": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/path-type/-/path-type-4.0.0.tgz", + "integrity": "sha512-gDKb8aZMDeD/tZWs9P6+q0J9Mwkdl6xMV8TjnGP3qJVJ06bdMgkbBlLU8IdfOsIsFz2BW1rNVT3XuNEl8zPAvw==", + "dev": true, + "engines": { + "node": ">=8" + } + }, + "node_modules/pathval": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/pathval/-/pathval-1.1.1.tgz", + "integrity": "sha512-Dp6zGqpTdETdR63lehJYPeIOqpiNBNtc7BpWSLrOje7UaIsE5aY92r/AunQA7rsXvet3lrJ3JnZX29UPTKXyKQ==", + "dev": true, + "engines": { + "node": "*" + } + }, + "node_modules/pbkdf2": { + "version": "3.1.2", + "resolved": "https://registry.npmjs.org/pbkdf2/-/pbkdf2-3.1.2.tgz", + "integrity": "sha512-iuh7L6jA7JEGu2WxDwtQP1ddOpaJNC4KlDEFfdQajSGgGPNi4OyDc2R7QnbY2bR9QjBVGwgvTdNJZoE7RaxUMA==", + "dev": true, + "dependencies": { + "create-hash": "^1.1.2", + "create-hmac": "^1.1.4", + "ripemd160": "^2.0.1", + "safe-buffer": "^5.0.1", + "sha.js": "^2.4.8" + }, + "engines": { + "node": ">=0.12" + } + }, + "node_modules/performance-now": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/performance-now/-/performance-now-2.1.0.tgz", + "integrity": "sha512-7EAHlyLHI56VEIdK57uwHdHKIaAGbnXPiw0yWbarQZOKaKpvUIgW0jWRVLiatnM+XXlSwsanIBH/hzGMJulMow==", + "dev": true + }, + "node_modules/picomatch": { + "version": "2.3.1", + "resolved": "https://registry.npmjs.org/picomatch/-/picomatch-2.3.1.tgz", + "integrity": "sha512-JU3teHTNjmE2VCGFzuY8EXzCDVwEqB2a8fsIvwaStHhAWJEeVd1o1QD80CU6+ZdEXXSLbSsuLwJjkCBWqRQUVA==", + "dev": true, + "engines": { + "node": ">=8.6" + }, + "funding": { + "url": "https://github.com/sponsors/jonschlinkert" + } + }, + "node_modules/pify": { + "version": "4.0.1", + "resolved": "https://registry.npmjs.org/pify/-/pify-4.0.1.tgz", + "integrity": "sha512-uB80kBFb/tfd68bVleG9T5GGsGPjJrLAUpR5PZIrhBnIaRTQRjqdJSsIKkOP6OAIFbj7GOrcudc5pNjZ+geV2g==", + "dev": true, + "engines": { + "node": ">=6" + } + }, + "node_modules/pinkie": { + "version": "2.0.4", + "resolved": "https://registry.npmjs.org/pinkie/-/pinkie-2.0.4.tgz", + "integrity": "sha512-MnUuEycAemtSaeFSjXKW/aroV7akBbY+Sv+RkyqFjgAe73F+MR0TBWKBRDkmfWq/HiFmdavfZ1G7h4SPZXaCSg==", + "dev": true, + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/pinkie-promise": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/pinkie-promise/-/pinkie-promise-2.0.1.tgz", + "integrity": "sha512-0Gni6D4UcLTbv9c57DfxDGdr41XfgUjqWZu492f0cIGr16zDU06BWP/RAEvOuo7CQ0CNjHaLlM59YJJFm3NWlw==", + "dev": true, + "dependencies": { + "pinkie": "^2.0.0" + }, + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/pkg-dir": { + "version": "4.2.0", + "resolved": "https://registry.npmjs.org/pkg-dir/-/pkg-dir-4.2.0.tgz", + "integrity": "sha512-HRDzbaKjC+AOWVXxAU/x54COGeIv9eb+6CkDSQoNTt4XyWoIJvuPsXizxu/Fr23EiekbtZwmh1IcIG/l/a10GQ==", + "dev": true, + "dependencies": { + "find-up": "^4.0.0" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/pluralize": { + "version": "8.0.0", + "resolved": "https://registry.npmjs.org/pluralize/-/pluralize-8.0.0.tgz", + "integrity": "sha512-Nc3IT5yHzflTfbjgqWcCPpo7DaKy4FnpB0l/zCAW0Tc7jxAiuqSxHasntB3D7887LSrA93kDJ9IXovxJYxyLCA==", + "dev": true, + "engines": { + "node": ">=4" + } + }, + "node_modules/preferred-pm": { + "version": "3.0.3", + "resolved": "https://registry.npmjs.org/preferred-pm/-/preferred-pm-3.0.3.tgz", + "integrity": "sha512-+wZgbxNES/KlJs9q40F/1sfOd/j7f1O9JaHcW5Dsn3aUUOZg3L2bjpVUcKV2jvtElYfoTuQiNeMfQJ4kwUAhCQ==", + "dev": true, + "dependencies": { + "find-up": "^5.0.0", + "find-yarn-workspace-root2": "1.2.16", + "path-exists": "^4.0.0", + "which-pm": "2.0.0" + }, + "engines": { + "node": ">=10" + } + }, + "node_modules/preferred-pm/node_modules/find-up": { + "version": "5.0.0", + "resolved": "https://registry.npmjs.org/find-up/-/find-up-5.0.0.tgz", + "integrity": "sha512-78/PXT1wlLLDgTzDs7sjq9hzz0vXD+zn+7wypEe4fXQxCmdmqfGsEPQxmiCSQI3ajFV91bVSsvNtrJRiW6nGng==", + "dev": true, + "dependencies": { + "locate-path": "^6.0.0", + "path-exists": "^4.0.0" + }, + "engines": { + "node": ">=10" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/preferred-pm/node_modules/locate-path": { + "version": "6.0.0", + "resolved": "https://registry.npmjs.org/locate-path/-/locate-path-6.0.0.tgz", + "integrity": "sha512-iPZK6eYjbxRu3uB4/WZ3EsEIMJFMqAoopl3R+zuq0UjcAm/MO6KCweDgPfP3elTztoKP3KtnVHxTn2NHBSDVUw==", + "dev": true, + "dependencies": { + "p-locate": "^5.0.0" + }, + "engines": { + "node": ">=10" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/preferred-pm/node_modules/p-locate": { + "version": "5.0.0", + "resolved": "https://registry.npmjs.org/p-locate/-/p-locate-5.0.0.tgz", + "integrity": "sha512-LaNjtRWUBY++zB5nE/NwcaoMylSPk+S+ZHNB1TzdbMJMny6dynpAGt7X/tl/QYq3TIeE6nxHppbo2LGymrG5Pw==", + "dev": true, + "dependencies": { + "p-limit": "^3.0.2" + }, + "engines": { + "node": ">=10" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/prelude-ls": { + "version": "1.2.1", + "resolved": "https://registry.npmjs.org/prelude-ls/-/prelude-ls-1.2.1.tgz", + "integrity": "sha512-vkcDPrRZo1QZLbn5RLGPpg/WmIQ65qoWWhcGKf/b5eplkkarX0m9z8ppCat4mlOqUsWpyNuYgO3VRyrYHSzX5g==", + "dev": true, + "engines": { + "node": ">= 0.8.0" + } + }, + "node_modules/prettier": { + "version": "3.0.3", + "resolved": "https://registry.npmjs.org/prettier/-/prettier-3.0.3.tgz", + "integrity": "sha512-L/4pUDMxcNa8R/EthV08Zt42WBO4h1rarVtK0K+QJG0X187OLo7l699jWw0GKuwzkPQ//jMFA/8Xm6Fh3J/DAg==", + "dev": true, + "bin": { + "prettier": "bin/prettier.cjs" + }, + "engines": { + "node": ">=14" + }, + "funding": { + "url": "https://github.com/prettier/prettier?sponsor=1" + } + }, + "node_modules/prettier-plugin-solidity": { + "version": "1.1.3", + "resolved": "https://registry.npmjs.org/prettier-plugin-solidity/-/prettier-plugin-solidity-1.1.3.tgz", + "integrity": "sha512-fQ9yucPi2sBbA2U2Xjh6m4isUTJ7S7QLc/XDDsktqqxYfTwdYKJ0EnnywXHwCGAaYbQNK+HIYPL1OemxuMsgeg==", + "dev": true, + "dependencies": { + "@solidity-parser/parser": "^0.16.0", + "semver": "^7.3.8", + "solidity-comments-extractor": "^0.0.7" + }, + "engines": { + "node": ">=12" + }, + "peerDependencies": { + "prettier": ">=2.3.0 || >=3.0.0-alpha.0" + } + }, + "node_modules/prettier-plugin-solidity/node_modules/@solidity-parser/parser": { + "version": "0.16.0", + "resolved": "https://registry.npmjs.org/@solidity-parser/parser/-/parser-0.16.0.tgz", + "integrity": "sha512-ESipEcHyRHg4Np4SqBCfcXwyxxna1DgFVz69bgpLV8vzl/NP1DtcKsJ4dJZXWQhY/Z4J2LeKBiOkOVZn9ct33Q==", + "dev": true, + "dependencies": { + "antlr4ts": "^0.5.0-alpha.4" + } + }, + "node_modules/process": { + "version": "0.11.10", + "resolved": "https://registry.npmjs.org/process/-/process-0.11.10.tgz", + "integrity": "sha512-cdGef/drWFoydD1JsMzuFf8100nZl+GT+yacc2bEced5f9Rjk4z+WtFUTBu9PhOi9j/jfmBPu0mMEY4wIdAF8A==", + "dev": true, + "engines": { + "node": ">= 0.6.0" + } + }, + "node_modules/process-nextick-args": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/process-nextick-args/-/process-nextick-args-2.0.1.tgz", + "integrity": "sha512-3ouUOpQhtgrbOa17J7+uxOTpITYWaGP7/AhoR3+A+/1e9skrzelGi/dXzEYyvbxubEF6Wn2ypscTKiKJFFn1ag==", + "dev": true + }, + "node_modules/promise": { + "version": "8.3.0", + "resolved": "https://registry.npmjs.org/promise/-/promise-8.3.0.tgz", + "integrity": "sha512-rZPNPKTOYVNEEKFaq1HqTgOwZD+4/YHS5ukLzQCypkj+OkYx7iv0mA91lJlpPPZ8vMau3IIGj5Qlwrx+8iiSmg==", + "dev": true, + "dependencies": { + "asap": "~2.0.6" + } + }, + "node_modules/proper-lockfile": { + "version": "4.1.2", + "resolved": "https://registry.npmjs.org/proper-lockfile/-/proper-lockfile-4.1.2.tgz", + "integrity": "sha512-TjNPblN4BwAWMXU8s9AEz4JmQxnD1NNL7bNOY/AKUzyamc379FWASUhc/K1pL2noVb+XmZKLL68cjzLsiOAMaA==", + "dev": true, + "dependencies": { + "graceful-fs": "^4.2.4", + "retry": "^0.12.0", + "signal-exit": "^3.0.2" + } + }, + "node_modules/proxy-addr": { + "version": "2.0.7", + "resolved": "https://registry.npmjs.org/proxy-addr/-/proxy-addr-2.0.7.tgz", + "integrity": "sha512-llQsMLSUDUPT44jdrU/O37qlnifitDP+ZwrmmZcoSKyLKvtZxpyV0n2/bD/N4tBAAZ/gJEdZU7KMraoK1+XYAg==", + "dev": true, + "dependencies": { + "forwarded": "0.2.0", + "ipaddr.js": "1.9.1" + }, + "engines": { + "node": ">= 0.10" + } + }, + "node_modules/pseudomap": { + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/pseudomap/-/pseudomap-1.0.2.tgz", + "integrity": "sha512-b/YwNhb8lk1Zz2+bXXpS/LK9OisiZZ1SNsSLxN1x2OXVEhW2Ckr/7mWE5vrC1ZTiJlD9g19jWszTmJsB+oEpFQ==", + "dev": true + }, + "node_modules/psl": { + "version": "1.9.0", + "resolved": "https://registry.npmjs.org/psl/-/psl-1.9.0.tgz", + "integrity": "sha512-E/ZsdU4HLs/68gYzgGTkMicWTLPdAftJLfJFlLUAAKZGkStNU72sZjT66SnMDVOfOWY/YAoiD7Jxa9iHvngcag==", + "dev": true + }, + "node_modules/pump": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/pump/-/pump-3.0.0.tgz", + "integrity": "sha512-LwZy+p3SFs1Pytd/jYct4wpv49HiYCqd9Rlc5ZVdk0V+8Yzv6jR5Blk3TRmPL1ft69TxP0IMZGJ+WPFU2BFhww==", + "dev": true, + "dependencies": { + "end-of-stream": "^1.1.0", + "once": "^1.3.1" + } + }, + "node_modules/punycode": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/punycode/-/punycode-2.1.0.tgz", + "integrity": "sha512-Yxz2kRwT90aPiWEMHVYnEf4+rhwF1tBmmZ4KepCP+Wkium9JxtWnUm1nqGwpiAHr/tnTSeHqr3wb++jgSkXjhA==", + "dev": true, + "engines": { + "node": ">=6" + } + }, + "node_modules/pure-rand": { + "version": "5.0.5", + "resolved": "https://registry.npmjs.org/pure-rand/-/pure-rand-5.0.5.tgz", + "integrity": "sha512-BwQpbqxSCBJVpamI6ydzcKqyFmnd5msMWUGvzXLm1aXvusbbgkbOto/EUPM00hjveJEaJtdbhUjKSzWRhQVkaw==", + "dev": true, + "funding": [ + { + "type": "individual", + "url": "https://github.com/sponsors/dubzzz" + }, + { + "type": "opencollective", + "url": "https://opencollective.com/fast-check" + } + ] + }, + "node_modules/qs": { + "version": "6.5.3", + "resolved": "https://registry.npmjs.org/qs/-/qs-6.5.3.tgz", + "integrity": "sha512-qxXIEh4pCGfHICj1mAJQ2/2XVZkjCDTcEgfoSQxc/fYivUZxTkk7L3bDBJSoNrEzXI17oUO5Dp07ktqE5KzczA==", + "dev": true, + "engines": { + "node": ">=0.6" + } + }, + "node_modules/query-string": { + "version": "5.1.1", + "resolved": "https://registry.npmjs.org/query-string/-/query-string-5.1.1.tgz", + "integrity": "sha512-gjWOsm2SoGlgLEdAGt7a6slVOk9mGiXmPFMqrEhLQ68rhQuBnpfs3+EmlvqKyxnCo9/PPlF+9MtY02S1aFg+Jw==", + "dev": true, + "dependencies": { + "decode-uri-component": "^0.2.0", + "object-assign": "^4.1.0", + "strict-uri-encode": "^1.0.0" + }, + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/queue-microtask": { + "version": "1.2.3", + "resolved": "https://registry.npmjs.org/queue-microtask/-/queue-microtask-1.2.3.tgz", + "integrity": "sha512-NuaNSa6flKT5JaSYQzJok04JzTL1CA6aGhv5rfLW3PgqA+M2ChpZQnAC8h8i4ZFkBS8X5RqkDBHA7r4hej3K9A==", + "dev": true, + "funding": [ + { + "type": "github", + "url": "https://github.com/sponsors/feross" + }, + { + "type": "patreon", + "url": "https://www.patreon.com/feross" + }, + { + "type": "consulting", + "url": "https://feross.org/support" + } + ] + }, + "node_modules/quick-lru": { + "version": "4.0.1", + "resolved": "https://registry.npmjs.org/quick-lru/-/quick-lru-4.0.1.tgz", + "integrity": "sha512-ARhCpm70fzdcvNQfPoy49IaanKkTlRWF2JMzqhcJbhSFRZv7nPTvZJdcY7301IPmvW+/p0RgIWnQDLJxifsQ7g==", + "dev": true, + "engines": { + "node": ">=8" + } + }, + "node_modules/randombytes": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/randombytes/-/randombytes-2.1.0.tgz", + "integrity": "sha512-vYl3iOX+4CKUWuxGi9Ukhie6fsqXqS9FE2Zaic4tNFD2N2QQaXOMFbuKK4QmDHC0JO6B1Zp41J0LpT0oR68amQ==", + "dev": true, + "dependencies": { + "safe-buffer": "^5.1.0" + } + }, + "node_modules/range-parser": { + "version": "1.2.1", + "resolved": "https://registry.npmjs.org/range-parser/-/range-parser-1.2.1.tgz", + "integrity": "sha512-Hrgsx+orqoygnmhFbKaHE6c296J+HTAQXoxEF6gNupROmmGJRoyzfG3ccAveqCBrwr/2yxQ5BVd/GTl5agOwSg==", + "dev": true, + "engines": { + "node": ">= 0.6" + } + }, + "node_modules/raw-body": { + "version": "2.5.2", + "resolved": "https://registry.npmjs.org/raw-body/-/raw-body-2.5.2.tgz", + "integrity": "sha512-8zGqypfENjCIqGhgXToC8aB2r7YrBX+AQAfIPs/Mlk+BtPTztOvTS01NRW/3Eh60J+a48lt8qsCzirQ6loCVfA==", + "dev": true, + "dependencies": { + "bytes": "3.1.2", + "http-errors": "2.0.0", + "iconv-lite": "0.4.24", + "unpipe": "1.0.0" + }, + "engines": { + "node": ">= 0.8" + } + }, + "node_modules/read-pkg": { + "version": "5.2.0", + "resolved": "https://registry.npmjs.org/read-pkg/-/read-pkg-5.2.0.tgz", + "integrity": "sha512-Ug69mNOpfvKDAc2Q8DRpMjjzdtrnv9HcSMX+4VsZxD1aZ6ZzrIE7rlzXBtWTyhULSMKg076AW6WR5iZpD0JiOg==", + "dev": true, + "dependencies": { + "@types/normalize-package-data": "^2.4.0", + "normalize-package-data": "^2.5.0", + "parse-json": "^5.0.0", + "type-fest": "^0.6.0" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/read-pkg-up": { + "version": "7.0.1", + "resolved": "https://registry.npmjs.org/read-pkg-up/-/read-pkg-up-7.0.1.tgz", + "integrity": "sha512-zK0TB7Xd6JpCLmlLmufqykGE+/TlOePD6qKClNW7hHDKFh/J7/7gCWGR7joEQEW1bKq3a3yUZSObOoWLFQ4ohg==", + "dev": true, + "dependencies": { + "find-up": "^4.1.0", + "read-pkg": "^5.2.0", + "type-fest": "^0.8.1" + }, + "engines": { + "node": ">=8" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/read-pkg-up/node_modules/type-fest": { + "version": "0.8.1", + "resolved": "https://registry.npmjs.org/type-fest/-/type-fest-0.8.1.tgz", + "integrity": "sha512-4dbzIzqvjtgiM5rw1k5rEHtBANKmdudhGyBEajN01fEyhaAIhsoKNy6y7+IN93IfpFtwY9iqi7kD+xwKhQsNJA==", + "dev": true, + "engines": { + "node": ">=8" + } + }, + "node_modules/read-pkg/node_modules/type-fest": { + "version": "0.6.0", + "resolved": "https://registry.npmjs.org/type-fest/-/type-fest-0.6.0.tgz", + "integrity": "sha512-q+MB8nYR1KDLrgr4G5yemftpMC7/QLqVndBmEEdqzmNj5dcFOO4Oo8qlwZE3ULT3+Zim1F8Kq4cBnikNhlCMlg==", + "dev": true, + "engines": { + "node": ">=8" + } + }, + "node_modules/read-yaml-file": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/read-yaml-file/-/read-yaml-file-1.1.0.tgz", + "integrity": "sha512-VIMnQi/Z4HT2Fxuwg5KrY174U1VdUIASQVWXXyqtNRtxSr9IYkn1rsI6Tb6HsrHCmB7gVpNwX6JxPTHcH6IoTA==", + "dev": true, + "dependencies": { + "graceful-fs": "^4.1.5", + "js-yaml": "^3.6.1", + "pify": "^4.0.1", + "strip-bom": "^3.0.0" + }, + "engines": { + "node": ">=6" + } + }, + "node_modules/readable-stream": { + "version": "3.6.2", + "resolved": "https://registry.npmjs.org/readable-stream/-/readable-stream-3.6.2.tgz", + "integrity": "sha512-9u/sniCrY3D5WdsERHzHE4G2YCXqoG5FTHUiCC4SIbr6XcLZBY05ya9EKjYek9O5xOAwjGq+1JdGBAS7Q9ScoA==", + "dev": true, + "dependencies": { + "inherits": "^2.0.3", + "string_decoder": "^1.1.1", + "util-deprecate": "^1.0.1" + }, + "engines": { + "node": ">= 6" + } + }, + "node_modules/readdirp": { + "version": "3.6.0", + "resolved": "https://registry.npmjs.org/readdirp/-/readdirp-3.6.0.tgz", + "integrity": "sha512-hOS089on8RduqdbhvQ5Z37A0ESjsqz6qnRcffsMU3495FuTdqSm+7bhJ29JvIOsBDEEnan5DPu9t3To9VRlMzA==", + "dev": true, + "dependencies": { + "picomatch": "^2.2.1" + }, + "engines": { + "node": ">=8.10.0" + } + }, + "node_modules/rechoir": { + "version": "0.6.2", + "resolved": "https://registry.npmjs.org/rechoir/-/rechoir-0.6.2.tgz", + "integrity": "sha512-HFM8rkZ+i3zrV+4LQjwQ0W+ez98pApMGM3HUrN04j3CqzPOzl9nmP15Y8YXNm8QHGv/eacOVEjqhmWpkRV0NAw==", + "dev": true, + "dependencies": { + "resolve": "^1.1.6" + }, + "engines": { + "node": ">= 0.10" + } + }, + "node_modules/recursive-readdir": { + "version": "2.2.3", + "resolved": "https://registry.npmjs.org/recursive-readdir/-/recursive-readdir-2.2.3.tgz", + "integrity": "sha512-8HrF5ZsXk5FAH9dgsx3BlUer73nIhuj+9OrQwEbLTPOBzGkL1lsFCR01am+v+0m2Cmbs1nP12hLDl5FA7EszKA==", + "dev": true, + "dependencies": { + "minimatch": "^3.0.5" + }, + "engines": { + "node": ">=6.0.0" + } + }, + "node_modules/redent": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/redent/-/redent-3.0.0.tgz", + "integrity": "sha512-6tDA8g98We0zd0GvVeMT9arEOnTw9qM03L9cJXaCjrip1OO764RDBLBfrB4cwzNGDj5OA5ioymC9GkizgWJDUg==", + "dev": true, + "dependencies": { + "indent-string": "^4.0.0", + "strip-indent": "^3.0.0" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/redent/node_modules/strip-indent": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/strip-indent/-/strip-indent-3.0.0.tgz", + "integrity": "sha512-laJTa3Jb+VQpaC6DseHhF7dXVqHTfJPCRDaEbid/drOhgitgYku/letMUqOXFoWV0zIIUbjpdH2t+tYj4bQMRQ==", + "dev": true, + "dependencies": { + "min-indent": "^1.0.0" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/regenerator-runtime": { + "version": "0.13.11", + "resolved": "https://registry.npmjs.org/regenerator-runtime/-/regenerator-runtime-0.13.11.tgz", + "integrity": "sha512-kY1AZVr2Ra+t+piVaJ4gxaFaReZVH40AKNo7UCX6W+dEwBo/2oZJzqfuN1qLq1oL45o56cPaTXELwrTh8Fpggg==", + "dev": true + }, + "node_modules/regexp.prototype.flags": { + "version": "1.5.0", + "resolved": "https://registry.npmjs.org/regexp.prototype.flags/-/regexp.prototype.flags-1.5.0.tgz", + "integrity": "sha512-0SutC3pNudRKgquxGoRGIz946MZVHqbNfPjBdxeOhBrdgDKlRoXmYLQN9xRbrR09ZXWeGAdPuif7egofn6v5LA==", + "dev": true, + "dependencies": { + "call-bind": "^1.0.2", + "define-properties": "^1.2.0", + "functions-have-names": "^1.2.3" + }, + "engines": { + "node": ">= 0.4" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/req-cwd": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/req-cwd/-/req-cwd-2.0.0.tgz", + "integrity": "sha512-ueoIoLo1OfB6b05COxAA9UpeoscNpYyM+BqYlA7H6LVF4hKGPXQQSSaD2YmvDVJMkk4UDpAHIeU1zG53IqjvlQ==", + "dev": true, + "dependencies": { + "req-from": "^2.0.0" + }, + "engines": { + "node": ">=4" + } + }, + "node_modules/req-from": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/req-from/-/req-from-2.0.0.tgz", + "integrity": "sha512-LzTfEVDVQHBRfjOUMgNBA+V6DWsSnoeKzf42J7l0xa/B4jyPOuuF5MlNSmomLNGemWTnV2TIdjSSLnEn95fOQA==", + "dev": true, + "dependencies": { + "resolve-from": "^3.0.0" + }, + "engines": { + "node": ">=4" + } + }, + "node_modules/req-from/node_modules/resolve-from": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/resolve-from/-/resolve-from-3.0.0.tgz", + "integrity": "sha512-GnlH6vxLymXJNMBo7XP1fJIzBFbdYt49CuTwmB/6N53t+kMPRMFKz783LlQ4tv28XoQfMWinAJX6WCGf2IlaIw==", + "dev": true, + "engines": { + "node": ">=4" + } + }, + "node_modules/request": { + "version": "2.88.2", + "resolved": "https://registry.npmjs.org/request/-/request-2.88.2.tgz", + "integrity": "sha512-MsvtOrfG9ZcrOwAW+Qi+F6HbD0CWXEh9ou77uOb7FM2WPhwT7smM833PzanhJLsgXjN89Ir6V2PczXNnMpwKhw==", + "deprecated": "request has been deprecated, see https://github.com/request/request/issues/3142", + "dev": true, + "dependencies": { + "aws-sign2": "~0.7.0", + "aws4": "^1.8.0", + "caseless": "~0.12.0", + "combined-stream": "~1.0.6", + "extend": "~3.0.2", + "forever-agent": "~0.6.1", + "form-data": "~2.3.2", + "har-validator": "~5.1.3", + "http-signature": "~1.2.0", + "is-typedarray": "~1.0.0", + "isstream": "~0.1.2", + "json-stringify-safe": "~5.0.1", + "mime-types": "~2.1.19", + "oauth-sign": "~0.9.0", + "performance-now": "^2.1.0", + "qs": "~6.5.2", + "safe-buffer": "^5.1.2", + "tough-cookie": "~2.5.0", + "tunnel-agent": "^0.6.0", + "uuid": "^3.3.2" + }, + "engines": { + "node": ">= 6" + } + }, + "node_modules/request-promise-core": { + "version": "1.1.4", + "resolved": "https://registry.npmjs.org/request-promise-core/-/request-promise-core-1.1.4.tgz", + "integrity": "sha512-TTbAfBBRdWD7aNNOoVOBH4pN/KigV6LyapYNNlAPA8JwbovRti1E88m3sYAwsLi5ryhPKsE9APwnjFTgdUjTpw==", + "dev": true, + "dependencies": { + "lodash": "^4.17.19" + }, + "engines": { + "node": ">=0.10.0" + }, + "peerDependencies": { + "request": "^2.34" + } + }, + "node_modules/request-promise-native": { + "version": "1.0.9", + "resolved": "https://registry.npmjs.org/request-promise-native/-/request-promise-native-1.0.9.tgz", + "integrity": "sha512-wcW+sIUiWnKgNY0dqCpOZkUbF/I+YPi+f09JZIDa39Ec+q82CpSYniDp+ISgTTbKmnpJWASeJBPZmoxH84wt3g==", + "deprecated": "request-promise-native has been deprecated because it extends the now deprecated request package, see https://github.com/request/request/issues/3142", + "dev": true, + "dependencies": { + "request-promise-core": "1.1.4", + "stealthy-require": "^1.1.1", + "tough-cookie": "^2.3.3" + }, + "engines": { + "node": ">=0.12.0" + }, + "peerDependencies": { + "request": "^2.34" + } + }, + "node_modules/request/node_modules/uuid": { + "version": "3.4.0", + "resolved": "https://registry.npmjs.org/uuid/-/uuid-3.4.0.tgz", + "integrity": "sha512-HjSDRw6gZE5JMggctHBcjVak08+KEVhSIiDzFnT9S9aegmp85S/bReBVTb4QTFaRNptJ9kuYaNhnbNEOkbKb/A==", + "deprecated": "Please upgrade to version 7 or higher. Older versions may use Math.random() in certain circumstances, which is known to be problematic. See https://v8.dev/blog/math-random for details.", + "dev": true, + "bin": { + "uuid": "bin/uuid" + } + }, + "node_modules/require-directory": { + "version": "2.1.1", + "resolved": "https://registry.npmjs.org/require-directory/-/require-directory-2.1.1.tgz", + "integrity": "sha512-fGxEI7+wsG9xrvdjsrlmL22OMTTiHRwAMroiEeMgq8gzoLC/PQr7RsRDSTLUg/bZAZtF+TVIkHc6/4RIKrui+Q==", + "dev": true, + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/require-from-string": { + "version": "1.2.1", + "resolved": "https://registry.npmjs.org/require-from-string/-/require-from-string-1.2.1.tgz", + "integrity": "sha512-H7AkJWMobeskkttHyhTVtS0fxpFLjxhbfMa6Bk3wimP7sdPRGL3EyCg3sAQenFfAe+xQ+oAc85Nmtvq0ROM83Q==", + "dev": true, + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/require-main-filename": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/require-main-filename/-/require-main-filename-2.0.0.tgz", + "integrity": "sha512-NKN5kMDylKuldxYLSUfrbo5Tuzh4hd+2E8NPPX02mZtn1VuREQToYe/ZdlJy+J3uCpfaiGF05e7B8W0iXbQHmg==", + "dev": true + }, + "node_modules/resolve": { + "version": "1.17.0", + "resolved": "https://registry.npmjs.org/resolve/-/resolve-1.17.0.tgz", + "integrity": "sha512-ic+7JYiV8Vi2yzQGFWOkiZD5Z9z7O2Zhm9XMaTxdJExKasieFCr+yXZ/WmXsckHiKl12ar0y6XiXDx3m4RHn1w==", + "dev": true, + "dependencies": { + "path-parse": "^1.0.6" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/resolve-alpn": { + "version": "1.2.1", + "resolved": "https://registry.npmjs.org/resolve-alpn/-/resolve-alpn-1.2.1.tgz", + "integrity": "sha512-0a1F4l73/ZFZOakJnQ3FvkJ2+gSTQWz/r2KE5OdDY0TxPm5h4GkqkWWfM47T7HsbnOtcJVEF4epCVy6u7Q3K+g==", + "dev": true + }, + "node_modules/resolve-from": { + "version": "5.0.0", + "resolved": "https://registry.npmjs.org/resolve-from/-/resolve-from-5.0.0.tgz", + "integrity": "sha512-qYg9KP24dD5qka9J47d0aVky0N+b4fTU89LN9iDnjB5waksiC49rvMB0PrUJQGoTmH50XPiqOvAjDfaijGxYZw==", + "dev": true, + "engines": { + "node": ">=8" + } + }, + "node_modules/responselike": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/responselike/-/responselike-2.0.1.tgz", + "integrity": "sha512-4gl03wn3hj1HP3yzgdI7d3lCkF95F21Pz4BPGvKHinyQzALR5CapwC8yIi0Rh58DEMQ/SguC03wFj2k0M/mHhw==", + "dev": true, + "dependencies": { + "lowercase-keys": "^2.0.0" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/responselike/node_modules/lowercase-keys": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/lowercase-keys/-/lowercase-keys-2.0.0.tgz", + "integrity": "sha512-tqNXrS78oMOE73NMxK4EMLQsQowWf8jKooH9g7xPavRT706R6bkQJ6DY2Te7QukaZsulxa30wQ7bk0pm4XiHmA==", + "dev": true, + "engines": { + "node": ">=8" + } + }, + "node_modules/retry": { + "version": "0.12.0", + "resolved": "https://registry.npmjs.org/retry/-/retry-0.12.0.tgz", + "integrity": "sha512-9LkiTwjUh6rT555DtE9rTX+BKByPfrMzEAtnlEtdEwr3Nkffwiihqe2bWADg+OQRjt9gl6ICdmB/ZFDCGAtSow==", + "dev": true, + "engines": { + "node": ">= 4" + } + }, + "node_modules/reusify": { + "version": "1.0.4", + "resolved": "https://registry.npmjs.org/reusify/-/reusify-1.0.4.tgz", + "integrity": "sha512-U9nH88a3fc/ekCF1l0/UP1IosiuIjyTh7hBvXVMHYgVcfGvt897Xguj2UOLDeI5BG2m7/uwyaLVT6fbtCwTyzw==", + "dev": true, + "engines": { + "iojs": ">=1.0.0", + "node": ">=0.10.0" + } + }, + "node_modules/rimraf": { + "version": "3.0.2", + "resolved": "https://registry.npmjs.org/rimraf/-/rimraf-3.0.2.tgz", + "integrity": "sha512-JZkJMZkAGFFPP2YqXZXPbMlMBgsxzE8ILs4lMIX/2o0L9UBw9O/Y3o6wFw/i9YLapcUJWwqbi3kdxIPdC62TIA==", + "dev": true, + "dependencies": { + "glob": "^7.1.3" + }, + "bin": { + "rimraf": "bin.js" + }, + "funding": { + "url": "https://github.com/sponsors/isaacs" + } + }, + "node_modules/rimraf/node_modules/glob": { + "version": "7.2.3", + "resolved": "https://registry.npmjs.org/glob/-/glob-7.2.3.tgz", + "integrity": "sha512-nFR0zLpU2YCaRxwoCJvL6UvCH2JFyFVIvwTLsIf21AuHlMskA1hhTdk+LlYJtOlYt9v6dvszD2BGRqBL+iQK9Q==", + "dev": true, + "dependencies": { + "fs.realpath": "^1.0.0", + "inflight": "^1.0.4", + "inherits": "2", + "minimatch": "^3.1.1", + "once": "^1.3.0", + "path-is-absolute": "^1.0.0" + }, + "engines": { + "node": "*" + }, + "funding": { + "url": "https://github.com/sponsors/isaacs" + } + }, + "node_modules/ripemd160": { + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/ripemd160/-/ripemd160-2.0.2.tgz", + "integrity": "sha512-ii4iagi25WusVoiC4B4lq7pbXfAp3D9v5CwfkY33vffw2+pkDjY1D8GaN7spsxvCSx8dkPqOZCEZyfxcmJG2IA==", + "dev": true, + "dependencies": { + "hash-base": "^3.0.0", + "inherits": "^2.0.1" + } + }, + "node_modules/ripemd160-min": { + "version": "0.0.6", + "resolved": "https://registry.npmjs.org/ripemd160-min/-/ripemd160-min-0.0.6.tgz", + "integrity": "sha512-+GcJgQivhs6S9qvLogusiTcS9kQUfgR75whKuy5jIhuiOfQuJ8fjqxV6EGD5duH1Y/FawFUMtMhyeq3Fbnib8A==", + "dev": true, + "engines": { + "node": ">=8" + } + }, + "node_modules/rlp": { + "version": "2.2.7", + "resolved": "https://registry.npmjs.org/rlp/-/rlp-2.2.7.tgz", + "integrity": "sha512-d5gdPmgQ0Z+AklL2NVXr/IoSjNZFfTVvQWzL/AM2AOcSzYP2xjlb0AC8YyCLc41MSNf6P6QVtjgPdmVtzb+4lQ==", + "dev": true, + "dependencies": { + "bn.js": "^5.2.0" + }, + "bin": { + "rlp": "bin/rlp" + } + }, + "node_modules/rlp/node_modules/bn.js": { + "version": "5.2.1", + "resolved": "https://registry.npmjs.org/bn.js/-/bn.js-5.2.1.tgz", + "integrity": "sha512-eXRvHzWyYPBuB4NBy0cmYQjGitUrtqwbvlzP3G6VFnNRbsZQIxQ10PbKKHt8gZ/HW/D/747aDl+QkDqg3KQLMQ==", + "dev": true + }, + "node_modules/run-parallel": { + "version": "1.2.0", + "resolved": "https://registry.npmjs.org/run-parallel/-/run-parallel-1.2.0.tgz", + "integrity": "sha512-5l4VyZR86LZ/lDxZTR6jqL8AFE2S0IFLMP26AbjsLVADxHdhB/c0GUsH+y39UfCi3dzz8OlQuPmnaJOMoDHQBA==", + "dev": true, + "funding": [ + { + "type": "github", + "url": "https://github.com/sponsors/feross" + }, + { + "type": "patreon", + "url": "https://www.patreon.com/feross" + }, + { + "type": "consulting", + "url": "https://feross.org/support" + } + ], + "dependencies": { + "queue-microtask": "^1.2.2" + } + }, + "node_modules/run-parallel-limit": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/run-parallel-limit/-/run-parallel-limit-1.1.0.tgz", + "integrity": "sha512-jJA7irRNM91jaKc3Hcl1npHsFLOXOoTkPCUL1JEa1R82O2miplXXRaGdjW/KM/98YQWDhJLiSs793CnXfblJUw==", + "dev": true, + "funding": [ + { + "type": "github", + "url": "https://github.com/sponsors/feross" + }, + { + "type": "patreon", + "url": "https://www.patreon.com/feross" + }, + { + "type": "consulting", + "url": "https://feross.org/support" + } + ], + "dependencies": { + "queue-microtask": "^1.2.2" + } + }, + "node_modules/rustbn.js": { + "version": "0.2.0", + "resolved": "https://registry.npmjs.org/rustbn.js/-/rustbn.js-0.2.0.tgz", + "integrity": "sha512-4VlvkRUuCJvr2J6Y0ImW7NvTCriMi7ErOAqWk1y69vAdoNIzCF3yPmgeNzx+RQTLEDFq5sHfscn1MwHxP9hNfA==", + "dev": true + }, + "node_modules/safe-array-concat": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/safe-array-concat/-/safe-array-concat-1.0.0.tgz", + "integrity": "sha512-9dVEFruWIsnie89yym+xWTAYASdpw3CJV7Li/6zBewGf9z2i1j31rP6jnY0pHEO4QZh6N0K11bFjWmdR8UGdPQ==", + "dev": true, + "dependencies": { + "call-bind": "^1.0.2", + "get-intrinsic": "^1.2.0", + "has-symbols": "^1.0.3", + "isarray": "^2.0.5" + }, + "engines": { + "node": ">=0.4" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/safe-array-concat/node_modules/isarray": { + "version": "2.0.5", + "resolved": "https://registry.npmjs.org/isarray/-/isarray-2.0.5.tgz", + "integrity": "sha512-xHjhDr3cNBK0BzdUJSPXZntQUx/mwMS5Rw4A7lPJ90XGAO6ISP/ePDNuo0vhqOZU+UD5JoodwCAAoZQd3FeAKw==", + "dev": true + }, + "node_modules/safe-buffer": { + "version": "5.2.1", + "resolved": "https://registry.npmjs.org/safe-buffer/-/safe-buffer-5.2.1.tgz", + "integrity": "sha512-rp3So07KcdmmKbGvgaNxQSJr7bGVSVk5S9Eq1F+ppbRo70+YeaDxkw5Dd8NPN+GD6bjnYm2VuPuCXmpuYvmCXQ==", + "dev": true, + "funding": [ + { + "type": "github", + "url": "https://github.com/sponsors/feross" + }, + { + "type": "patreon", + "url": "https://www.patreon.com/feross" + }, + { + "type": "consulting", + "url": "https://feross.org/support" + } + ] + }, + "node_modules/safe-regex-test": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/safe-regex-test/-/safe-regex-test-1.0.0.tgz", + "integrity": "sha512-JBUUzyOgEwXQY1NuPtvcj/qcBDbDmEvWufhlnXZIm75DEHp+afM1r1ujJpJsV/gSM4t59tpDyPi1sd6ZaPFfsA==", + "dev": true, + "dependencies": { + "call-bind": "^1.0.2", + "get-intrinsic": "^1.1.3", + "is-regex": "^1.1.4" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/safer-buffer": { + "version": "2.1.2", + "resolved": "https://registry.npmjs.org/safer-buffer/-/safer-buffer-2.1.2.tgz", + "integrity": "sha512-YZo3K82SD7Riyi0E1EQPojLz7kpepnSQI9IyPbHHg1XXXevb5dJI7tpyN2ADxGcQbHG7vcyRHk0cbwqcQriUtg==", + "dev": true + }, + "node_modules/sc-istanbul": { + "version": "0.4.6", + "resolved": "https://registry.npmjs.org/sc-istanbul/-/sc-istanbul-0.4.6.tgz", + "integrity": "sha512-qJFF/8tW/zJsbyfh/iT/ZM5QNHE3CXxtLJbZsL+CzdJLBsPD7SedJZoUA4d8iAcN2IoMp/Dx80shOOd2x96X/g==", + "dev": true, + "dependencies": { + "abbrev": "1.0.x", + "async": "1.x", + "escodegen": "1.8.x", + "esprima": "2.7.x", + "glob": "^5.0.15", + "handlebars": "^4.0.1", + "js-yaml": "3.x", + "mkdirp": "0.5.x", + "nopt": "3.x", + "once": "1.x", + "resolve": "1.1.x", + "supports-color": "^3.1.0", + "which": "^1.1.1", + "wordwrap": "^1.0.0" + }, + "bin": { + "istanbul": "lib/cli.js" + } + }, + "node_modules/sc-istanbul/node_modules/esprima": { + "version": "2.7.3", + "resolved": "https://registry.npmjs.org/esprima/-/esprima-2.7.3.tgz", + "integrity": "sha512-OarPfz0lFCiW4/AV2Oy1Rp9qu0iusTKqykwTspGCZtPxmF81JR4MmIebvF1F9+UOKth2ZubLQ4XGGaU+hSn99A==", + "dev": true, + "bin": { + "esparse": "bin/esparse.js", + "esvalidate": "bin/esvalidate.js" + }, + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/sc-istanbul/node_modules/glob": { + "version": "5.0.15", + "resolved": "https://registry.npmjs.org/glob/-/glob-5.0.15.tgz", + "integrity": "sha512-c9IPMazfRITpmAAKi22dK1VKxGDX9ehhqfABDriL/lzO92xcUKEJPQHrVA/2YHSNFB4iFlykVmWvwo48nr3OxA==", + "dev": true, + "dependencies": { + "inflight": "^1.0.4", + "inherits": "2", + "minimatch": "2 || 3", + "once": "^1.3.0", + "path-is-absolute": "^1.0.0" + }, + "engines": { + "node": "*" + } + }, + "node_modules/sc-istanbul/node_modules/has-flag": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/has-flag/-/has-flag-1.0.0.tgz", + "integrity": "sha512-DyYHfIYwAJmjAjSSPKANxI8bFY9YtFrgkAfinBojQ8YJTOuOuav64tMUJv584SES4xl74PmuaevIyaLESHdTAA==", + "dev": true, + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/sc-istanbul/node_modules/resolve": { + "version": "1.1.7", + "resolved": "https://registry.npmjs.org/resolve/-/resolve-1.1.7.tgz", + "integrity": "sha512-9znBF0vBcaSN3W2j7wKvdERPwqTxSpCq+if5C0WoTCyV9n24rua28jeuQ2pL/HOf+yUe/Mef+H/5p60K0Id3bg==", + "dev": true + }, + "node_modules/sc-istanbul/node_modules/supports-color": { + "version": "3.2.3", + "resolved": "https://registry.npmjs.org/supports-color/-/supports-color-3.2.3.tgz", + "integrity": "sha512-Jds2VIYDrlp5ui7t8abHN2bjAu4LV/q4N2KivFPpGH0lrka0BMq/33AmECUXlKPcHigkNaqfXRENFju+rlcy+A==", + "dev": true, + "dependencies": { + "has-flag": "^1.0.0" + }, + "engines": { + "node": ">=0.8.0" + } + }, + "node_modules/sc-istanbul/node_modules/which": { + "version": "1.3.1", + "resolved": "https://registry.npmjs.org/which/-/which-1.3.1.tgz", + "integrity": "sha512-HxJdYWq1MTIQbJ3nw0cqssHoTNU267KlrDuGZ1WYlxDStUtKUhOaJmh112/TZmHxxUfuJqPXSOm7tDyas0OSIQ==", + "dev": true, + "dependencies": { + "isexe": "^2.0.0" + }, + "bin": { + "which": "bin/which" + } + }, + "node_modules/scrypt-js": { + "version": "3.0.1", + "resolved": "https://registry.npmjs.org/scrypt-js/-/scrypt-js-3.0.1.tgz", + "integrity": "sha512-cdwTTnqPu0Hyvf5in5asVdZocVDTNRmR7XEcJuIzMjJeSHybHl7vpB66AzwTaIg6CLSbtjcxc8fqcySfnTkccA==", + "dev": true + }, + "node_modules/secp256k1": { + "version": "4.0.3", + "resolved": "https://registry.npmjs.org/secp256k1/-/secp256k1-4.0.3.tgz", + "integrity": "sha512-NLZVf+ROMxwtEj3Xa562qgv2BK5e2WNmXPiOdVIPLgs6lyTzMvBq0aWTYMI5XCP9jZMVKOcqZLw/Wc4vDkuxhA==", + "dev": true, + "hasInstallScript": true, + "dependencies": { + "elliptic": "^6.5.4", + "node-addon-api": "^2.0.0", + "node-gyp-build": "^4.2.0" + }, + "engines": { + "node": ">=10.0.0" + } + }, + "node_modules/semver": { + "version": "7.5.3", + "resolved": "https://registry.npmjs.org/semver/-/semver-7.5.3.tgz", + "integrity": "sha512-QBlUtyVk/5EeHbi7X0fw6liDZc7BBmEaSYn01fMU1OUYbf6GPsbTtd8WmnqbI20SeycoHSeiybkE/q1Q+qlThQ==", + "dev": true, + "dependencies": { + "lru-cache": "^6.0.0" + }, + "bin": { + "semver": "bin/semver.js" + }, + "engines": { + "node": ">=10" + } + }, + "node_modules/semver/node_modules/lru-cache": { + "version": "6.0.0", + "resolved": "https://registry.npmjs.org/lru-cache/-/lru-cache-6.0.0.tgz", + "integrity": "sha512-Jo6dJ04CmSjuznwJSS3pUeWmd/H0ffTlkXXgwZi+eq1UCmqQwCh+eLsYOYCwY991i2Fah4h1BEMCx4qThGbsiA==", + "dev": true, + "dependencies": { + "yallist": "^4.0.0" + }, + "engines": { + "node": ">=10" + } + }, + "node_modules/semver/node_modules/yallist": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/yallist/-/yallist-4.0.0.tgz", + "integrity": "sha512-3wdGidZyq5PB084XLES5TpOSRA3wjXAlIWMhum2kRcv/41Sn2emQ0dycQW4uZXLejwKvg6EsvbdlVL+FYEct7A==", + "dev": true + }, + "node_modules/send": { + "version": "0.18.0", + "resolved": "https://registry.npmjs.org/send/-/send-0.18.0.tgz", + "integrity": "sha512-qqWzuOjSFOuqPjFe4NOsMLafToQQwBSOEpS+FwEt3A2V3vKubTquT3vmLTQpFgMXp8AlFWFuP1qKaJZOtPpVXg==", + "dev": true, + "dependencies": { + "debug": "2.6.9", + "depd": "2.0.0", + "destroy": "1.2.0", + "encodeurl": "~1.0.2", + "escape-html": "~1.0.3", + "etag": "~1.8.1", + "fresh": "0.5.2", + "http-errors": "2.0.0", + "mime": "1.6.0", + "ms": "2.1.3", + "on-finished": "2.4.1", + "range-parser": "~1.2.1", + "statuses": "2.0.1" + }, + "engines": { + "node": ">= 0.8.0" + } + }, + "node_modules/send/node_modules/debug": { + "version": "2.6.9", + "resolved": "https://registry.npmjs.org/debug/-/debug-2.6.9.tgz", + "integrity": "sha512-bC7ElrdJaJnPbAP+1EotYvqZsb3ecl5wi6Bfi6BJTUcNowp6cvspg0jXznRTKDjm/E7AdgFBVeAPVMNcKGsHMA==", + "dev": true, + "dependencies": { + "ms": "2.0.0" + } + }, + "node_modules/send/node_modules/debug/node_modules/ms": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/ms/-/ms-2.0.0.tgz", + "integrity": "sha512-Tpp60P6IUJDTuOq/5Z8cdskzJujfwqfOTkrwIwj7IRISpnkJnT6SyJ4PCPnGMoFjC9ddhal5KVIYtAt97ix05A==", + "dev": true + }, + "node_modules/send/node_modules/ms": { + "version": "2.1.3", + "resolved": "https://registry.npmjs.org/ms/-/ms-2.1.3.tgz", + "integrity": "sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==", + "dev": true + }, + "node_modules/sentence-case": { + "version": "2.1.1", + "resolved": "https://registry.npmjs.org/sentence-case/-/sentence-case-2.1.1.tgz", + "integrity": "sha512-ENl7cYHaK/Ktwk5OTD+aDbQ3uC8IByu/6Bkg+HDv8Mm+XnBnppVNalcfJTNsp1ibstKh030/JKQQWglDvtKwEQ==", + "dev": true, + "dependencies": { + "no-case": "^2.2.0", + "upper-case-first": "^1.1.2" + } + }, + "node_modules/serialize-javascript": { + "version": "6.0.0", + "resolved": "https://registry.npmjs.org/serialize-javascript/-/serialize-javascript-6.0.0.tgz", + "integrity": "sha512-Qr3TosvguFt8ePWqsvRfrKyQXIiW+nGbYpy8XK24NQHE83caxWt+mIymTT19DGFbNWNLfEwsrkSmN64lVWB9ag==", + "dev": true, + "dependencies": { + "randombytes": "^2.1.0" + } + }, + "node_modules/serve-static": { + "version": "1.15.0", + "resolved": "https://registry.npmjs.org/serve-static/-/serve-static-1.15.0.tgz", + "integrity": "sha512-XGuRDNjXUijsUL0vl6nSD7cwURuzEgglbOaFuZM9g3kwDXOWVTck0jLzjPzGD+TazWbboZYu52/9/XPdUgne9g==", + "dev": true, + "dependencies": { + "encodeurl": "~1.0.2", + "escape-html": "~1.0.3", + "parseurl": "~1.3.3", + "send": "0.18.0" + }, + "engines": { + "node": ">= 0.8.0" + } + }, + "node_modules/servify": { + "version": "0.1.12", + "resolved": "https://registry.npmjs.org/servify/-/servify-0.1.12.tgz", + "integrity": "sha512-/xE6GvsKKqyo1BAY+KxOWXcLpPsUUyji7Qg3bVD7hh1eRze5bR1uYiuDA/k3Gof1s9BTzQZEJK8sNcNGFIzeWw==", + "dev": true, + "dependencies": { + "body-parser": "^1.16.0", + "cors": "^2.8.1", + "express": "^4.14.0", + "request": "^2.79.0", + "xhr": "^2.3.3" + }, + "engines": { + "node": ">=6" + } + }, + "node_modules/set-blocking": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/set-blocking/-/set-blocking-2.0.0.tgz", + "integrity": "sha512-KiKBS8AnWGEyLzofFfmvKwpdPzqiy16LvQfK3yv/fVH7Bj13/wl3JSR1J+rfgRE9q7xUJK4qvgS8raSOeLUehw==", + "dev": true + }, + "node_modules/setimmediate": { + "version": "1.0.5", + "resolved": "https://registry.npmjs.org/setimmediate/-/setimmediate-1.0.5.tgz", + "integrity": "sha512-MATJdZp8sLqDl/68LfQmbP8zKPLQNV6BIZoIgrscFDQ+RsvK/BxeDQOgyxKKoh0y/8h3BqVFnCqQ/gd+reiIXA==", + "dev": true + }, + "node_modules/setprototypeof": { + "version": "1.2.0", + "resolved": "https://registry.npmjs.org/setprototypeof/-/setprototypeof-1.2.0.tgz", + "integrity": "sha512-E5LDX7Wrp85Kil5bhZv46j8jOeboKq5JMmYM3gVGdGH8xFpPWXUMsNrlODCrkoxMEeNi/XZIwuRvY4XNwYMJpw==", + "dev": true + }, + "node_modules/sha.js": { + "version": "2.4.11", + "resolved": "https://registry.npmjs.org/sha.js/-/sha.js-2.4.11.tgz", + "integrity": "sha512-QMEp5B7cftE7APOjk5Y6xgrbWu+WkLVQwk8JNjZ8nKRciZaByEW6MubieAiToS7+dwvrjGhH8jRXz3MVd0AYqQ==", + "dev": true, + "dependencies": { + "inherits": "^2.0.1", + "safe-buffer": "^5.0.1" + }, + "bin": { + "sha.js": "bin.js" + } + }, + "node_modules/sha1": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/sha1/-/sha1-1.1.1.tgz", + "integrity": "sha512-dZBS6OrMjtgVkopB1Gmo4RQCDKiZsqcpAQpkV/aaj+FCrCg8r4I4qMkDPQjBgLIxlmu9k4nUbWq6ohXahOneYA==", + "dev": true, + "dependencies": { + "charenc": ">= 0.0.1", + "crypt": ">= 0.0.1" + }, + "engines": { + "node": "*" + } + }, + "node_modules/sha3": { + "version": "2.1.4", + "resolved": "https://registry.npmjs.org/sha3/-/sha3-2.1.4.tgz", + "integrity": "sha512-S8cNxbyb0UGUM2VhRD4Poe5N58gJnJsLJ5vC7FYWGUmGhcsj4++WaIOBFVDxlG0W3To6xBuiRh+i0Qp2oNCOtg==", + "dev": true, + "dependencies": { + "buffer": "6.0.3" + } + }, + "node_modules/sha3/node_modules/buffer": { + "version": "6.0.3", + "resolved": "https://registry.npmjs.org/buffer/-/buffer-6.0.3.tgz", + "integrity": "sha512-FTiCpNxtwiZZHEZbcbTIcZjERVICn9yq/pDFkTl95/AxzD1naBctN7YO68riM/gLSDY7sdrMby8hofADYuuqOA==", + "dev": true, + "funding": [ + { + "type": "github", + "url": "https://github.com/sponsors/feross" + }, + { + "type": "patreon", + "url": "https://www.patreon.com/feross" + }, + { + "type": "consulting", + "url": "https://feross.org/support" + } + ], + "dependencies": { + "base64-js": "^1.3.1", + "ieee754": "^1.2.1" + } + }, + "node_modules/shallowequal": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/shallowequal/-/shallowequal-1.1.0.tgz", + "integrity": "sha512-y0m1JoUZSlPAjXVtPPW70aZWfIL/dSP7AFkRnniLCrK/8MDKog3TySTBmckD+RObVxH0v4Tox67+F14PdED2oQ==", + "dev": true + }, + "node_modules/shebang-command": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/shebang-command/-/shebang-command-2.0.0.tgz", + "integrity": "sha512-kHxr2zZpYtdmrN1qDjrrX/Z1rR1kG8Dx+gkpK1G4eXmvXswmcE1hTWBWYUzlraYw1/yZp6YuDY77YtvbN0dmDA==", + "dev": true, + "dependencies": { + "shebang-regex": "^3.0.0" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/shebang-regex": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/shebang-regex/-/shebang-regex-3.0.0.tgz", + "integrity": "sha512-7++dFhtcx3353uBaq8DDR4NuxBetBzC7ZQOhmTQInHEd6bSrXdiEyzCvG07Z44UYdLShWUyXt5M/yhz8ekcb1A==", + "dev": true, + "engines": { + "node": ">=8" + } + }, + "node_modules/shelljs": { + "version": "0.8.5", + "resolved": "https://registry.npmjs.org/shelljs/-/shelljs-0.8.5.tgz", + "integrity": "sha512-TiwcRcrkhHvbrZbnRcFYMLl30Dfov3HKqzp5tO5b4pt6G/SezKcYhmDg15zXVBswHmctSAQKznqNW2LO5tTDow==", + "dev": true, + "dependencies": { + "glob": "^7.0.0", + "interpret": "^1.0.0", + "rechoir": "^0.6.2" + }, + "bin": { + "shjs": "bin/shjs" + }, + "engines": { + "node": ">=4" + } + }, + "node_modules/shelljs/node_modules/glob": { + "version": "7.2.3", + "resolved": "https://registry.npmjs.org/glob/-/glob-7.2.3.tgz", + "integrity": "sha512-nFR0zLpU2YCaRxwoCJvL6UvCH2JFyFVIvwTLsIf21AuHlMskA1hhTdk+LlYJtOlYt9v6dvszD2BGRqBL+iQK9Q==", + "dev": true, + "dependencies": { + "fs.realpath": "^1.0.0", + "inflight": "^1.0.4", + "inherits": "2", + "minimatch": "^3.1.1", + "once": "^1.3.0", + "path-is-absolute": "^1.0.0" + }, + "engines": { + "node": "*" + }, + "funding": { + "url": "https://github.com/sponsors/isaacs" + } + }, + "node_modules/side-channel": { + "version": "1.0.4", + "resolved": "https://registry.npmjs.org/side-channel/-/side-channel-1.0.4.tgz", + "integrity": "sha512-q5XPytqFEIKHkGdiMIrY10mvLRvnQh42/+GoBlFW3b2LXLE2xxJpZFdm94we0BaoV3RwJyGqg5wS7epxTv0Zvw==", + "dev": true, + "dependencies": { + "call-bind": "^1.0.0", + "get-intrinsic": "^1.0.2", + "object-inspect": "^1.9.0" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/signal-exit": { + "version": "3.0.7", + "resolved": "https://registry.npmjs.org/signal-exit/-/signal-exit-3.0.7.tgz", + "integrity": "sha512-wnD2ZE+l+SPC/uoS0vXeE9L1+0wuaMqKlfz9AMUo38JsyLSBWSFcHR1Rri62LZc12vLr1gb3jl7iwQhgwpAbGQ==", + "dev": true + }, + "node_modules/simple-concat": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/simple-concat/-/simple-concat-1.0.1.tgz", + "integrity": "sha512-cSFtAPtRhljv69IK0hTVZQ+OfE9nePi/rtJmw5UjHeVyVroEqJXP1sFztKUy1qU+xvz3u/sfYJLa947b7nAN2Q==", + "dev": true, + "funding": [ + { + "type": "github", + "url": "https://github.com/sponsors/feross" + }, + { + "type": "patreon", + "url": "https://www.patreon.com/feross" + }, + { + "type": "consulting", + "url": "https://feross.org/support" + } + ] + }, + "node_modules/simple-get": { + "version": "2.8.2", + "resolved": "https://registry.npmjs.org/simple-get/-/simple-get-2.8.2.tgz", + "integrity": "sha512-Ijd/rV5o+mSBBs4F/x9oDPtTx9Zb6X9brmnXvMW4J7IR15ngi9q5xxqWBKU744jTZiaXtxaPL7uHG6vtN8kUkw==", + "dev": true, + "dependencies": { + "decompress-response": "^3.3.0", + "once": "^1.3.1", + "simple-concat": "^1.0.0" + } + }, + "node_modules/simple-get/node_modules/decompress-response": { + "version": "3.3.0", + "resolved": "https://registry.npmjs.org/decompress-response/-/decompress-response-3.3.0.tgz", + "integrity": "sha512-BzRPQuY1ip+qDonAOz42gRm/pg9F768C+npV/4JOsxRC2sq+Rlk+Q4ZCAsOhnIaMrgarILY+RMUIvMmmX1qAEA==", + "dev": true, + "dependencies": { + "mimic-response": "^1.0.0" + }, + "engines": { + "node": ">=4" + } + }, + "node_modules/slash": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/slash/-/slash-3.0.0.tgz", + "integrity": "sha512-g9Q1haeby36OSStwb4ntCGGGaKsaVSjQ68fBxoQcutl5fS1vuY18H3wSt3jFyFtrkx+Kz0V1G85A4MyAdDMi2Q==", + "dev": true, + "engines": { + "node": ">=8" + } + }, + "node_modules/slice-ansi": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/slice-ansi/-/slice-ansi-4.0.0.tgz", + "integrity": "sha512-qMCMfhY040cVHT43K9BFygqYbUPFZKHOg7K73mtTWJRb8pyP3fzf4Ixd5SzdEJQ6MRUg/WBnOLxghZtKKurENQ==", + "dev": true, + "dependencies": { + "ansi-styles": "^4.0.0", + "astral-regex": "^2.0.0", + "is-fullwidth-code-point": "^3.0.0" + }, + "engines": { + "node": ">=10" + }, + "funding": { + "url": "https://github.com/chalk/slice-ansi?sponsor=1" + } + }, + "node_modules/slice-ansi/node_modules/ansi-styles": { + "version": "4.3.0", + "resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-4.3.0.tgz", + "integrity": "sha512-zbB9rCJAT1rbjiVDb2hqKFHNYLxgtk8NURxZ3IZwD3F6NtxbXZQCnnSi1Lkx+IDohdPlFp222wVALIheZJQSEg==", + "dev": true, + "dependencies": { + "color-convert": "^2.0.1" + }, + "engines": { + "node": ">=8" + }, + "funding": { + "url": "https://github.com/chalk/ansi-styles?sponsor=1" + } + }, + "node_modules/slice-ansi/node_modules/color-convert": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/color-convert/-/color-convert-2.0.1.tgz", + "integrity": "sha512-RRECPsj7iu/xb5oKYcsFHSppFNnsj/52OVTRKb4zP5onXwVF3zVmmToNcOfGC+CRDpfK/U584fMg38ZHCaElKQ==", + "dev": true, + "dependencies": { + "color-name": "~1.1.4" + }, + "engines": { + "node": ">=7.0.0" + } + }, + "node_modules/slice-ansi/node_modules/color-name": { + "version": "1.1.4", + "resolved": "https://registry.npmjs.org/color-name/-/color-name-1.1.4.tgz", + "integrity": "sha512-dOy+3AuW3a2wNbZHIuMZpTcgjGuLU/uBL/ubcZF9OXbDo8ff4O8yVp5Bf0efS8uEoYo5q4Fx7dY9OgQGXgAsQA==", + "dev": true + }, + "node_modules/slice-ansi/node_modules/is-fullwidth-code-point": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/is-fullwidth-code-point/-/is-fullwidth-code-point-3.0.0.tgz", + "integrity": "sha512-zymm5+u+sCsSWyD9qNaejV3DFvhCKclKdizYaJUuHA83RLjb7nSuGnddCHGv0hk+KY7BMAlsWeK4Ueg6EV6XQg==", + "dev": true, + "engines": { + "node": ">=8" + } + }, + "node_modules/smartwrap": { + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/smartwrap/-/smartwrap-2.0.2.tgz", + "integrity": "sha512-vCsKNQxb7PnCNd2wY1WClWifAc2lwqsG8OaswpJkVJsvMGcnEntdTCDajZCkk93Ay1U3t/9puJmb525Rg5MZBA==", + "dev": true, + "dependencies": { + "array.prototype.flat": "^1.2.3", + "breakword": "^1.0.5", + "grapheme-splitter": "^1.0.4", + "strip-ansi": "^6.0.0", + "wcwidth": "^1.0.1", + "yargs": "^15.1.0" + }, + "bin": { + "smartwrap": "src/terminal-adapter.js" + }, + "engines": { + "node": ">=6" + } + }, + "node_modules/smartwrap/node_modules/ansi-regex": { + "version": "5.0.1", + "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-5.0.1.tgz", + "integrity": "sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ==", + "dev": true, + "engines": { + "node": ">=8" + } + }, + "node_modules/smartwrap/node_modules/ansi-styles": { + "version": "4.3.0", + "resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-4.3.0.tgz", + "integrity": "sha512-zbB9rCJAT1rbjiVDb2hqKFHNYLxgtk8NURxZ3IZwD3F6NtxbXZQCnnSi1Lkx+IDohdPlFp222wVALIheZJQSEg==", + "dev": true, + "dependencies": { + "color-convert": "^2.0.1" + }, + "engines": { + "node": ">=8" + }, + "funding": { + "url": "https://github.com/chalk/ansi-styles?sponsor=1" + } + }, + "node_modules/smartwrap/node_modules/cliui": { + "version": "6.0.0", + "resolved": "https://registry.npmjs.org/cliui/-/cliui-6.0.0.tgz", + "integrity": "sha512-t6wbgtoCXvAzst7QgXxJYqPt0usEfbgQdftEPbLL/cvv6HPE5VgvqCuAIDR0NgU52ds6rFwqrgakNLrHEjCbrQ==", + "dev": true, + "dependencies": { + "string-width": "^4.2.0", + "strip-ansi": "^6.0.0", + "wrap-ansi": "^6.2.0" + } + }, + "node_modules/smartwrap/node_modules/color-convert": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/color-convert/-/color-convert-2.0.1.tgz", + "integrity": "sha512-RRECPsj7iu/xb5oKYcsFHSppFNnsj/52OVTRKb4zP5onXwVF3zVmmToNcOfGC+CRDpfK/U584fMg38ZHCaElKQ==", + "dev": true, + "dependencies": { + "color-name": "~1.1.4" + }, + "engines": { + "node": ">=7.0.0" + } + }, + "node_modules/smartwrap/node_modules/color-name": { + "version": "1.1.4", + "resolved": "https://registry.npmjs.org/color-name/-/color-name-1.1.4.tgz", + "integrity": "sha512-dOy+3AuW3a2wNbZHIuMZpTcgjGuLU/uBL/ubcZF9OXbDo8ff4O8yVp5Bf0efS8uEoYo5q4Fx7dY9OgQGXgAsQA==", + "dev": true + }, + "node_modules/smartwrap/node_modules/is-fullwidth-code-point": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/is-fullwidth-code-point/-/is-fullwidth-code-point-3.0.0.tgz", + "integrity": "sha512-zymm5+u+sCsSWyD9qNaejV3DFvhCKclKdizYaJUuHA83RLjb7nSuGnddCHGv0hk+KY7BMAlsWeK4Ueg6EV6XQg==", + "dev": true, + "engines": { + "node": ">=8" + } + }, + "node_modules/smartwrap/node_modules/string-width": { + "version": "4.2.3", + "resolved": "https://registry.npmjs.org/string-width/-/string-width-4.2.3.tgz", + "integrity": "sha512-wKyQRQpjJ0sIp62ErSZdGsjMJWsap5oRNihHhu6G7JVO/9jIB6UyevL+tXuOqrng8j/cxKTWyWUwvSTriiZz/g==", + "dev": true, + "dependencies": { + "emoji-regex": "^8.0.0", + "is-fullwidth-code-point": "^3.0.0", + "strip-ansi": "^6.0.1" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/smartwrap/node_modules/strip-ansi": { + "version": "6.0.1", + "resolved": "https://registry.npmjs.org/strip-ansi/-/strip-ansi-6.0.1.tgz", + "integrity": "sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A==", + "dev": true, + "dependencies": { + "ansi-regex": "^5.0.1" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/smartwrap/node_modules/wrap-ansi": { + "version": "6.2.0", + "resolved": "https://registry.npmjs.org/wrap-ansi/-/wrap-ansi-6.2.0.tgz", + "integrity": "sha512-r6lPcBGxZXlIcymEu7InxDMhdW0KDxpLgoFLcguasxCaJ/SOIZwINatK9KY/tf+ZrlywOKU0UDj3ATXUBfxJXA==", + "dev": true, + "dependencies": { + "ansi-styles": "^4.0.0", + "string-width": "^4.1.0", + "strip-ansi": "^6.0.0" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/smartwrap/node_modules/y18n": { + "version": "4.0.3", + "resolved": "https://registry.npmjs.org/y18n/-/y18n-4.0.3.tgz", + "integrity": "sha512-JKhqTOwSrqNA1NY5lSztJ1GrBiUodLMmIZuLiDaMRJ+itFd+ABVE8XBjOvIWL+rSqNDC74LCSFmlb/U4UZ4hJQ==", + "dev": true + }, + "node_modules/smartwrap/node_modules/yargs": { + "version": "15.4.1", + "resolved": "https://registry.npmjs.org/yargs/-/yargs-15.4.1.tgz", + "integrity": "sha512-aePbxDmcYW++PaqBsJ+HYUFwCdv4LVvdnhBy78E57PIor8/OVvhMrADFFEDh8DHDFRv/O9i3lPhsENjO7QX0+A==", + "dev": true, + "dependencies": { + "cliui": "^6.0.0", + "decamelize": "^1.2.0", + "find-up": "^4.1.0", + "get-caller-file": "^2.0.1", + "require-directory": "^2.1.1", + "require-main-filename": "^2.0.0", + "set-blocking": "^2.0.0", + "string-width": "^4.2.0", + "which-module": "^2.0.0", + "y18n": "^4.0.0", + "yargs-parser": "^18.1.2" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/snake-case": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/snake-case/-/snake-case-2.1.0.tgz", + "integrity": "sha512-FMR5YoPFwOLuh4rRz92dywJjyKYZNLpMn1R5ujVpIYkbA9p01fq8RMg0FkO4M+Yobt4MjHeLTJVm5xFFBHSV2Q==", + "dev": true, + "dependencies": { + "no-case": "^2.2.0" + } + }, + "node_modules/solc": { + "version": "0.4.26", + "resolved": "https://registry.npmjs.org/solc/-/solc-0.4.26.tgz", + "integrity": "sha512-o+c6FpkiHd+HPjmjEVpQgH7fqZ14tJpXhho+/bQXlXbliLIS/xjXb42Vxh+qQY1WCSTMQ0+a5vR9vi0MfhU6mA==", + "dev": true, + "dependencies": { + "fs-extra": "^0.30.0", + "memorystream": "^0.3.1", + "require-from-string": "^1.1.0", + "semver": "^5.3.0", + "yargs": "^4.7.1" + }, + "bin": { + "solcjs": "solcjs" + } + }, + "node_modules/solc/node_modules/ansi-regex": { + "version": "2.1.1", + "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-2.1.1.tgz", + "integrity": "sha512-TIGnTpdo+E3+pCyAluZvtED5p5wCqLdezCyhPZzKPcxvFplEt4i+W7OONCKgeZFT3+y5NZZfOOS/Bdcanm1MYA==", + "dev": true, + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/solc/node_modules/camelcase": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/camelcase/-/camelcase-3.0.0.tgz", + "integrity": "sha512-4nhGqUkc4BqbBBB4Q6zLuD7lzzrHYrjKGeYaEji/3tFR5VdJu9v+LilhGIVe8wxEJPPOeWo7eg8dwY13TZ1BNg==", + "dev": true, + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/solc/node_modules/cliui": { + "version": "3.2.0", + "resolved": "https://registry.npmjs.org/cliui/-/cliui-3.2.0.tgz", + "integrity": "sha512-0yayqDxWQbqk3ojkYqUKqaAQ6AfNKeKWRNA8kR0WXzAsdHpP4BIaOmMAG87JGuO6qcobyW4GjxHd9PmhEd+T9w==", + "dev": true, + "dependencies": { + "string-width": "^1.0.1", + "strip-ansi": "^3.0.1", + "wrap-ansi": "^2.0.0" + } + }, + "node_modules/solc/node_modules/find-up": { + "version": "1.1.2", + "resolved": "https://registry.npmjs.org/find-up/-/find-up-1.1.2.tgz", + "integrity": "sha512-jvElSjyuo4EMQGoTwo1uJU5pQMwTW5lS1x05zzfJuTIyLR3zwO27LYrxNg+dlvKpGOuGy/MzBdXh80g0ve5+HA==", + "dev": true, + "dependencies": { + "path-exists": "^2.0.0", + "pinkie-promise": "^2.0.0" + }, + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/solc/node_modules/fs-extra": { + "version": "0.30.0", + "resolved": "https://registry.npmjs.org/fs-extra/-/fs-extra-0.30.0.tgz", + "integrity": "sha512-UvSPKyhMn6LEd/WpUaV9C9t3zATuqoqfWc3QdPhPLb58prN9tqYPlPWi8Krxi44loBoUzlobqZ3+8tGpxxSzwA==", + "dev": true, + "dependencies": { + "graceful-fs": "^4.1.2", + "jsonfile": "^2.1.0", + "klaw": "^1.0.0", + "path-is-absolute": "^1.0.0", + "rimraf": "^2.2.8" + } + }, + "node_modules/solc/node_modules/get-caller-file": { + "version": "1.0.3", + "resolved": "https://registry.npmjs.org/get-caller-file/-/get-caller-file-1.0.3.tgz", + "integrity": "sha512-3t6rVToeoZfYSGd8YoLFR2DJkiQrIiUrGcjvFX2mDw3bn6k2OtwHN0TNCLbBO+w8qTvimhDkv+LSscbJY1vE6w==", + "dev": true + }, + "node_modules/solc/node_modules/glob": { + "version": "7.2.3", + "resolved": "https://registry.npmjs.org/glob/-/glob-7.2.3.tgz", + "integrity": "sha512-nFR0zLpU2YCaRxwoCJvL6UvCH2JFyFVIvwTLsIf21AuHlMskA1hhTdk+LlYJtOlYt9v6dvszD2BGRqBL+iQK9Q==", + "dev": true, + "dependencies": { + "fs.realpath": "^1.0.0", + "inflight": "^1.0.4", + "inherits": "2", + "minimatch": "^3.1.1", + "once": "^1.3.0", + "path-is-absolute": "^1.0.0" + }, + "engines": { + "node": "*" + }, + "funding": { + "url": "https://github.com/sponsors/isaacs" + } + }, + "node_modules/solc/node_modules/is-fullwidth-code-point": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/is-fullwidth-code-point/-/is-fullwidth-code-point-1.0.0.tgz", + "integrity": "sha512-1pqUqRjkhPJ9miNq9SwMfdvi6lBJcd6eFxvfaivQhaH3SgisfiuudvFntdKOmxuee/77l+FPjKrQjWvmPjWrRw==", + "dev": true, + "dependencies": { + "number-is-nan": "^1.0.0" + }, + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/solc/node_modules/jsonfile": { + "version": "2.4.0", + "resolved": "https://registry.npmjs.org/jsonfile/-/jsonfile-2.4.0.tgz", + "integrity": "sha512-PKllAqbgLgxHaj8TElYymKCAgrASebJrWpTnEkOaTowt23VKXXN0sUeriJ+eh7y6ufb/CC5ap11pz71/cM0hUw==", + "dev": true, + "optionalDependencies": { + "graceful-fs": "^4.1.6" + } + }, + "node_modules/solc/node_modules/path-exists": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/path-exists/-/path-exists-2.1.0.tgz", + "integrity": "sha512-yTltuKuhtNeFJKa1PiRzfLAU5182q1y4Eb4XCJ3PBqyzEDkAZRzBrKKBct682ls9reBVHf9udYLN5Nd+K1B9BQ==", + "dev": true, + "dependencies": { + "pinkie-promise": "^2.0.0" + }, + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/solc/node_modules/path-type": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/path-type/-/path-type-1.1.0.tgz", + "integrity": "sha512-S4eENJz1pkiQn9Znv33Q+deTOKmbl+jj1Fl+qiP/vYezj+S8x+J3Uo0ISrx/QoEvIlOaDWJhPaRd1flJ9HXZqg==", + "dev": true, + "dependencies": { + "graceful-fs": "^4.1.2", + "pify": "^2.0.0", + "pinkie-promise": "^2.0.0" + }, + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/solc/node_modules/pify": { + "version": "2.3.0", + "resolved": "https://registry.npmjs.org/pify/-/pify-2.3.0.tgz", + "integrity": "sha512-udgsAY+fTnvv7kI7aaxbqwWNb0AHiB0qBO89PZKPkoTmGOgdbrHDKD+0B2X4uTfJ/FT1R09r9gTsjUjNJotuog==", + "dev": true, + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/solc/node_modules/read-pkg": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/read-pkg/-/read-pkg-1.1.0.tgz", + "integrity": "sha512-7BGwRHqt4s/uVbuyoeejRn4YmFnYZiFl4AuaeXHlgZf3sONF0SOGlxs2Pw8g6hCKupo08RafIO5YXFNOKTfwsQ==", + "dev": true, + "dependencies": { + "load-json-file": "^1.0.0", + "normalize-package-data": "^2.3.2", + "path-type": "^1.0.0" + }, + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/solc/node_modules/read-pkg-up": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/read-pkg-up/-/read-pkg-up-1.0.1.tgz", + "integrity": "sha512-WD9MTlNtI55IwYUS27iHh9tK3YoIVhxis8yKhLpTqWtml739uXc9NWTpxoHkfZf3+DkCCsXox94/VWZniuZm6A==", + "dev": true, + "dependencies": { + "find-up": "^1.0.0", + "read-pkg": "^1.0.0" + }, + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/solc/node_modules/require-main-filename": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/require-main-filename/-/require-main-filename-1.0.1.tgz", + "integrity": "sha512-IqSUtOVP4ksd1C/ej5zeEh/BIP2ajqpn8c5x+q99gvcIG/Qf0cud5raVnE/Dwd0ua9TXYDoDc0RE5hBSdz22Ug==", + "dev": true + }, + "node_modules/solc/node_modules/rimraf": { + "version": "2.7.1", + "resolved": "https://registry.npmjs.org/rimraf/-/rimraf-2.7.1.tgz", + "integrity": "sha512-uWjbaKIK3T1OSVptzX7Nl6PvQ3qAGtKEtVRjRuazjfL3Bx5eI409VZSqgND+4UNnmzLVdPj9FqFJNPqBZFve4w==", + "dev": true, + "dependencies": { + "glob": "^7.1.3" + }, + "bin": { + "rimraf": "bin.js" + } + }, + "node_modules/solc/node_modules/semver": { + "version": "5.7.1", + "resolved": "https://registry.npmjs.org/semver/-/semver-5.7.1.tgz", + "integrity": "sha512-sauaDf/PZdVgrLTNYHRtpXa1iRiKcaebiKQ1BJdpQlWH2lCvexQdX55snPFyK7QzpudqbCI0qXFfOasHdyNDGQ==", + "dev": true, + "bin": { + "semver": "bin/semver" + } + }, + "node_modules/solc/node_modules/string-width": { + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/string-width/-/string-width-1.0.2.tgz", + "integrity": "sha512-0XsVpQLnVCXHJfyEs8tC0zpTVIr5PKKsQtkT29IwupnPTjtPmQ3xT/4yCREF9hYkV/3M3kzcUTSAZT6a6h81tw==", + "dev": true, + "dependencies": { + "code-point-at": "^1.0.0", + "is-fullwidth-code-point": "^1.0.0", + "strip-ansi": "^3.0.0" + }, + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/solc/node_modules/strip-ansi": { + "version": "3.0.1", + "resolved": "https://registry.npmjs.org/strip-ansi/-/strip-ansi-3.0.1.tgz", + "integrity": "sha512-VhumSSbBqDTP8p2ZLKj40UjBCV4+v8bUSEpUb4KjRgWk9pbqGF4REFj6KEagidb2f/M6AzC0EmFyDNGaw9OCzg==", + "dev": true, + "dependencies": { + "ansi-regex": "^2.0.0" + }, + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/solc/node_modules/which-module": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/which-module/-/which-module-1.0.0.tgz", + "integrity": "sha512-F6+WgncZi/mJDrammbTuHe1q0R5hOXv/mBaiNA2TCNT/LTHusX0V+CJnj9XT8ki5ln2UZyyddDgHfCzyrOH7MQ==", + "dev": true + }, + "node_modules/solc/node_modules/wrap-ansi": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/wrap-ansi/-/wrap-ansi-2.1.0.tgz", + "integrity": "sha512-vAaEaDM946gbNpH5pLVNR+vX2ht6n0Bt3GXwVB1AuAqZosOvHNF3P7wDnh8KLkSqgUh0uh77le7Owgoz+Z9XBw==", + "dev": true, + "dependencies": { + "string-width": "^1.0.1", + "strip-ansi": "^3.0.1" + }, + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/solc/node_modules/y18n": { + "version": "3.2.2", + "resolved": "https://registry.npmjs.org/y18n/-/y18n-3.2.2.tgz", + "integrity": "sha512-uGZHXkHnhF0XeeAPgnKfPv1bgKAYyVvmNL1xlKsPYZPaIHxGti2hHqvOCQv71XMsLxu1QjergkqogUnms5D3YQ==", + "dev": true + }, + "node_modules/solc/node_modules/yargs": { + "version": "4.8.1", + "resolved": "https://registry.npmjs.org/yargs/-/yargs-4.8.1.tgz", + "integrity": "sha512-LqodLrnIDM3IFT+Hf/5sxBnEGECrfdC1uIbgZeJmESCSo4HoCAaKEus8MylXHAkdacGc0ye+Qa+dpkuom8uVYA==", + "dev": true, + "dependencies": { + "cliui": "^3.2.0", + "decamelize": "^1.1.1", + "get-caller-file": "^1.0.1", + "lodash.assign": "^4.0.3", + "os-locale": "^1.4.0", + "read-pkg-up": "^1.0.1", + "require-directory": "^2.1.1", + "require-main-filename": "^1.0.1", + "set-blocking": "^2.0.0", + "string-width": "^1.0.1", + "which-module": "^1.0.0", + "window-size": "^0.2.0", + "y18n": "^3.2.1", + "yargs-parser": "^2.4.1" + } + }, + "node_modules/solc/node_modules/yargs-parser": { + "version": "2.4.1", + "resolved": "https://registry.npmjs.org/yargs-parser/-/yargs-parser-2.4.1.tgz", + "integrity": "sha512-9pIKIJhnI5tonzG6OnCFlz/yln8xHYcGl+pn3xR0Vzff0vzN1PbNRaelgfgRUwZ3s4i3jvxT9WhmUGL4whnasA==", + "dev": true, + "dependencies": { + "camelcase": "^3.0.0", + "lodash.assign": "^4.0.6" + } + }, + "node_modules/solhint": { + "version": "3.4.1", + "resolved": "https://registry.npmjs.org/solhint/-/solhint-3.4.1.tgz", + "integrity": "sha512-pzZn2RlZhws1XwvLPVSsxfHrwsteFf5eySOhpAytzXwKQYbTCJV6z8EevYDiSVKMpWrvbKpEtJ055CuEmzp4Xg==", + "dev": true, + "dependencies": { + "@solidity-parser/parser": "^0.16.0", + "ajv": "^6.12.6", + "antlr4": "^4.11.0", + "ast-parents": "^0.0.1", + "chalk": "^4.1.2", + "commander": "^10.0.0", + "cosmiconfig": "^8.0.0", + "fast-diff": "^1.2.0", + "glob": "^8.0.3", + "ignore": "^5.2.4", + "js-yaml": "^4.1.0", + "lodash": "^4.17.21", + "pluralize": "^8.0.0", + "semver": "^6.3.0", + "strip-ansi": "^6.0.1", + "table": "^6.8.1", + "text-table": "^0.2.0" + }, + "bin": { + "solhint": "solhint.js" + }, + "optionalDependencies": { + "prettier": "^2.8.3" + } + }, + "node_modules/solhint-plugin-openzeppelin": { + "resolved": "scripts/solhint-custom", + "link": true + }, + "node_modules/solhint/node_modules/@solidity-parser/parser": { + "version": "0.16.0", + "resolved": "https://registry.npmjs.org/@solidity-parser/parser/-/parser-0.16.0.tgz", + "integrity": "sha512-ESipEcHyRHg4Np4SqBCfcXwyxxna1DgFVz69bgpLV8vzl/NP1DtcKsJ4dJZXWQhY/Z4J2LeKBiOkOVZn9ct33Q==", + "dev": true, + "dependencies": { + "antlr4ts": "^0.5.0-alpha.4" + } + }, + "node_modules/solhint/node_modules/ansi-regex": { + "version": "5.0.1", + "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-5.0.1.tgz", + "integrity": "sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ==", + "dev": true, + "engines": { + "node": ">=8" + } + }, + "node_modules/solhint/node_modules/ansi-styles": { + "version": "4.3.0", + "resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-4.3.0.tgz", + "integrity": "sha512-zbB9rCJAT1rbjiVDb2hqKFHNYLxgtk8NURxZ3IZwD3F6NtxbXZQCnnSi1Lkx+IDohdPlFp222wVALIheZJQSEg==", + "dev": true, + "dependencies": { + "color-convert": "^2.0.1" + }, + "engines": { + "node": ">=8" + }, + "funding": { + "url": "https://github.com/chalk/ansi-styles?sponsor=1" + } + }, + "node_modules/solhint/node_modules/argparse": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/argparse/-/argparse-2.0.1.tgz", + "integrity": "sha512-8+9WqebbFzpX9OR+Wa6O29asIogeRMzcGtAINdpMHHyAg10f05aSFVBbcEqGf/PXw1EjAZ+q2/bEBg3DvurK3Q==", + "dev": true + }, + "node_modules/solhint/node_modules/chalk": { + "version": "4.1.2", + "resolved": "https://registry.npmjs.org/chalk/-/chalk-4.1.2.tgz", + "integrity": "sha512-oKnbhFyRIXpUuez8iBMmyEa4nbj4IOQyuhc/wy9kY7/WVPcwIO9VA668Pu8RkO7+0G76SLROeyw9CpQ061i4mA==", + "dev": true, + "dependencies": { + "ansi-styles": "^4.1.0", + "supports-color": "^7.1.0" + }, + "engines": { + "node": ">=10" + }, + "funding": { + "url": "https://github.com/chalk/chalk?sponsor=1" + } + }, + "node_modules/solhint/node_modules/color-convert": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/color-convert/-/color-convert-2.0.1.tgz", + "integrity": "sha512-RRECPsj7iu/xb5oKYcsFHSppFNnsj/52OVTRKb4zP5onXwVF3zVmmToNcOfGC+CRDpfK/U584fMg38ZHCaElKQ==", + "dev": true, + "dependencies": { + "color-name": "~1.1.4" + }, + "engines": { + "node": ">=7.0.0" + } + }, + "node_modules/solhint/node_modules/color-name": { + "version": "1.1.4", + "resolved": "https://registry.npmjs.org/color-name/-/color-name-1.1.4.tgz", + "integrity": "sha512-dOy+3AuW3a2wNbZHIuMZpTcgjGuLU/uBL/ubcZF9OXbDo8ff4O8yVp5Bf0efS8uEoYo5q4Fx7dY9OgQGXgAsQA==", + "dev": true + }, + "node_modules/solhint/node_modules/has-flag": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/has-flag/-/has-flag-4.0.0.tgz", + "integrity": "sha512-EykJT/Q1KjTWctppgIAgfSO0tKVuZUjhgMr17kqTumMl6Afv3EISleU7qZUzoXDFTAHTDC4NOoG/ZxU3EvlMPQ==", + "dev": true, + "engines": { + "node": ">=8" + } + }, + "node_modules/solhint/node_modules/js-yaml": { + "version": "4.1.0", + "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-4.1.0.tgz", + "integrity": "sha512-wpxZs9NoxZaJESJGIZTyDEaYpl0FKSA+FB9aJiyemKhMwkxQg63h4T1KJgUGHpTqPDNRcmmYLugrRjJlBtWvRA==", + "dev": true, + "dependencies": { + "argparse": "^2.0.1" + }, + "bin": { + "js-yaml": "bin/js-yaml.js" + } + }, + "node_modules/solhint/node_modules/prettier": { + "version": "2.8.8", + "resolved": "https://registry.npmjs.org/prettier/-/prettier-2.8.8.tgz", + "integrity": "sha512-tdN8qQGvNjw4CHbY+XXk0JgCXn9QiF21a55rBe5LJAU+kDyC4WQn4+awm2Xfk2lQMk5fKup9XgzTZtGkjBdP9Q==", + "dev": true, + "optional": true, + "bin": { + "prettier": "bin-prettier.js" + }, + "engines": { + "node": ">=10.13.0" + }, + "funding": { + "url": "https://github.com/prettier/prettier?sponsor=1" + } + }, + "node_modules/solhint/node_modules/semver": { + "version": "6.3.0", + "resolved": "https://registry.npmjs.org/semver/-/semver-6.3.0.tgz", + "integrity": "sha512-b39TBaTSfV6yBrapU89p5fKekE2m/NwnDocOVruQFS1/veMgdzuPcnOM34M6CwxW8jH/lxEa5rBoDeUwu5HHTw==", + "dev": true, + "bin": { + "semver": "bin/semver.js" + } + }, + "node_modules/solhint/node_modules/strip-ansi": { + "version": "6.0.1", + "resolved": "https://registry.npmjs.org/strip-ansi/-/strip-ansi-6.0.1.tgz", + "integrity": "sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A==", + "dev": true, + "dependencies": { + "ansi-regex": "^5.0.1" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/solhint/node_modules/supports-color": { + "version": "7.2.0", + "resolved": "https://registry.npmjs.org/supports-color/-/supports-color-7.2.0.tgz", + "integrity": "sha512-qpCAvRl9stuOHveKsn7HncJRvv501qIacKzQlO/+Lwxc9+0q2wLyv4Dfvt80/DPn2pqOBsJdDiogXGR9+OvwRw==", + "dev": true, + "dependencies": { + "has-flag": "^4.0.0" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/solidity-ast": { + "version": "0.4.50", + "resolved": "https://registry.npmjs.org/solidity-ast/-/solidity-ast-0.4.50.tgz", + "integrity": "sha512-WpIhaUibbjcBY4bg8TO2UXFWl8PQPhtH1QtMYJUqFUGxx0rRiEFsVLV+ow8XiWEnSPeu4xPp1/K43P4esxuK1Q==", + "dev": true, + "dependencies": { + "array.prototype.findlast": "^1.2.2" + } + }, + "node_modules/solidity-comments": { + "version": "0.0.2", + "resolved": "https://registry.npmjs.org/solidity-comments/-/solidity-comments-0.0.2.tgz", + "integrity": "sha512-G+aK6qtyUfkn1guS8uzqUeua1dURwPlcOjoTYW/TwmXAcE7z/1+oGCfZUdMSe4ZMKklNbVZNiG5ibnF8gkkFfw==", + "dev": true, + "engines": { + "node": ">= 12" + }, + "optionalDependencies": { + "solidity-comments-darwin-arm64": "0.0.2", + "solidity-comments-darwin-x64": "0.0.2", + "solidity-comments-freebsd-x64": "0.0.2", + "solidity-comments-linux-arm64-gnu": "0.0.2", + "solidity-comments-linux-arm64-musl": "0.0.2", + "solidity-comments-linux-x64-gnu": "0.0.2", + "solidity-comments-linux-x64-musl": "0.0.2", + "solidity-comments-win32-arm64-msvc": "0.0.2", + "solidity-comments-win32-ia32-msvc": "0.0.2", + "solidity-comments-win32-x64-msvc": "0.0.2" + } + }, + "node_modules/solidity-comments-darwin-arm64": { + "version": "0.0.2", + "resolved": "https://registry.npmjs.org/solidity-comments-darwin-arm64/-/solidity-comments-darwin-arm64-0.0.2.tgz", + "integrity": "sha512-HidWkVLSh7v+Vu0CA7oI21GWP/ZY7ro8g8OmIxE8oTqyMwgMbE8F1yc58Sj682Hj199HCZsjmtn1BE4PCbLiGA==", + "cpu": [ + "arm64" + ], + "dev": true, + "optional": true, + "os": [ + "darwin" + ], + "engines": { + "node": ">= 10" + } + }, + "node_modules/solidity-comments-darwin-x64": { + "version": "0.0.2", + "resolved": "https://registry.npmjs.org/solidity-comments-darwin-x64/-/solidity-comments-darwin-x64-0.0.2.tgz", + "integrity": "sha512-Zjs0Ruz6faBTPT6fBecUt6qh4CdloT8Bwoc0+qxRoTn9UhYscmbPQkUgQEbS0FQPysYqVzzxJB4h1Ofbf4wwtA==", + "cpu": [ + "x64" + ], + "dev": true, + "optional": true, + "os": [ + "darwin" + ], + "engines": { + "node": ">= 10" + } + }, + "node_modules/solidity-comments-extractor": { + "version": "0.0.7", + "resolved": "https://registry.npmjs.org/solidity-comments-extractor/-/solidity-comments-extractor-0.0.7.tgz", + "integrity": "sha512-wciNMLg/Irp8OKGrh3S2tfvZiZ0NEyILfcRCXCD4mp7SgK/i9gzLfhY2hY7VMCQJ3kH9UB9BzNdibIVMchzyYw==", + "dev": true + }, + "node_modules/solidity-comments-freebsd-x64": { + "version": "0.0.2", + "resolved": "https://registry.npmjs.org/solidity-comments-freebsd-x64/-/solidity-comments-freebsd-x64-0.0.2.tgz", + "integrity": "sha512-8Qe4mpjuAxFSwZJVk7B8gAoLCdbtS412bQzBwk63L8dmlHogvE39iT70aAk3RHUddAppT5RMBunlPUCFYJ3ZTw==", + "cpu": [ + "x64" + ], + "dev": true, + "optional": true, + "os": [ + "freebsd" + ], + "engines": { + "node": ">= 10" + } + }, + "node_modules/solidity-comments-linux-arm64-gnu": { + "version": "0.0.2", + "resolved": "https://registry.npmjs.org/solidity-comments-linux-arm64-gnu/-/solidity-comments-linux-arm64-gnu-0.0.2.tgz", + "integrity": "sha512-spkb0MZZnmrP+Wtq4UxP+nyPAVRe82idOjqndolcNR0S9Xvu4ebwq+LvF4HiUgjTDmeiqYiFZQ8T9KGdLSIoIg==", + "cpu": [ + "arm64" + ], + "dev": true, + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">= 10" + } + }, + "node_modules/solidity-comments-linux-arm64-musl": { + "version": "0.0.2", + "resolved": "https://registry.npmjs.org/solidity-comments-linux-arm64-musl/-/solidity-comments-linux-arm64-musl-0.0.2.tgz", + "integrity": "sha512-guCDbHArcjE+JDXYkxx5RZzY1YF6OnAKCo+sTC5fstyW/KGKaQJNPyBNWuwYsQiaEHpvhW1ha537IvlGek8GqA==", + "cpu": [ + "arm64" + ], + "dev": true, + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">= 10" + } + }, + "node_modules/solidity-comments-linux-x64-gnu": { + "version": "0.0.2", + "resolved": "https://registry.npmjs.org/solidity-comments-linux-x64-gnu/-/solidity-comments-linux-x64-gnu-0.0.2.tgz", + "integrity": "sha512-zIqLehBK/g7tvrFmQljrfZXfkEeLt2v6wbe+uFu6kH/qAHZa7ybt8Vc0wYcmjo2U0PeBm15d79ee3AkwbIjFdQ==", + "cpu": [ + "x64" + ], + "dev": true, + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">= 10" + } + }, + "node_modules/solidity-comments-linux-x64-musl": { + "version": "0.0.2", + "resolved": "https://registry.npmjs.org/solidity-comments-linux-x64-musl/-/solidity-comments-linux-x64-musl-0.0.2.tgz", + "integrity": "sha512-R9FeDloVlFGTaVkOlELDVC7+1Tjx5WBPI5L8r0AGOPHK3+jOcRh6sKYpI+VskSPDc3vOO46INkpDgUXrKydlIw==", + "cpu": [ + "x64" + ], + "dev": true, + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">= 10" + } + }, + "node_modules/solidity-comments-win32-arm64-msvc": { + "version": "0.0.2", + "resolved": "https://registry.npmjs.org/solidity-comments-win32-arm64-msvc/-/solidity-comments-win32-arm64-msvc-0.0.2.tgz", + "integrity": "sha512-QnWJoCQcJj+rnutULOihN9bixOtYWDdF5Rfz9fpHejL1BtNjdLW1om55XNVHGAHPqBxV4aeQQ6OirKnp9zKsug==", + "cpu": [ + "arm64" + ], + "dev": true, + "optional": true, + "os": [ + "win32" + ], + "engines": { + "node": ">= 10" + } + }, + "node_modules/solidity-comments-win32-ia32-msvc": { + "version": "0.0.2", + "resolved": "https://registry.npmjs.org/solidity-comments-win32-ia32-msvc/-/solidity-comments-win32-ia32-msvc-0.0.2.tgz", + "integrity": "sha512-vUg4nADtm/NcOtlIymG23NWJUSuMsvX15nU7ynhGBsdKtt8xhdP3C/zA6vjDk8Jg+FXGQL6IHVQ++g/7rSQi0w==", + "cpu": [ + "ia32" + ], + "dev": true, + "optional": true, + "os": [ + "win32" + ], + "engines": { + "node": ">= 10" + } + }, + "node_modules/solidity-comments-win32-x64-msvc": { + "version": "0.0.2", + "resolved": "https://registry.npmjs.org/solidity-comments-win32-x64-msvc/-/solidity-comments-win32-x64-msvc-0.0.2.tgz", + "integrity": "sha512-36j+KUF4V/y0t3qatHm/LF5sCUCBx2UndxE1kq5bOzh/s+nQgatuyB+Pd5BfuPQHdWu2KaExYe20FlAa6NL7+Q==", + "cpu": [ + "x64" + ], + "dev": true, + "optional": true, + "os": [ + "win32" + ], + "engines": { + "node": ">= 10" + } + }, + "node_modules/solidity-coverage": { + "version": "0.8.4", + "resolved": "https://registry.npmjs.org/solidity-coverage/-/solidity-coverage-0.8.4.tgz", + "integrity": "sha512-xeHOfBOjdMF6hWTbt42iH4x+7j1Atmrf5OldDPMxI+i/COdExUxszOswD9qqvcBTaLGiOrrpnh9UZjSpt4rBsg==", + "dev": true, + "dependencies": { + "@ethersproject/abi": "^5.0.9", + "@solidity-parser/parser": "^0.16.0", + "chalk": "^2.4.2", + "death": "^1.1.0", + "detect-port": "^1.3.0", + "difflib": "^0.2.4", + "fs-extra": "^8.1.0", + "ghost-testrpc": "^0.0.2", + "global-modules": "^2.0.0", + "globby": "^10.0.1", + "jsonschema": "^1.2.4", + "lodash": "^4.17.15", + "mocha": "7.1.2", + "node-emoji": "^1.10.0", + "pify": "^4.0.1", + "recursive-readdir": "^2.2.2", + "sc-istanbul": "^0.4.5", + "semver": "^7.3.4", + "shelljs": "^0.8.3", + "web3-utils": "^1.3.6" + }, + "bin": { + "solidity-coverage": "plugins/bin.js" + }, + "peerDependencies": { + "hardhat": "^2.11.0" + } + }, + "node_modules/solidity-coverage/node_modules/@solidity-parser/parser": { + "version": "0.16.1", + "resolved": "https://registry.npmjs.org/@solidity-parser/parser/-/parser-0.16.1.tgz", + "integrity": "sha512-PdhRFNhbTtu3x8Axm0uYpqOy/lODYQK+MlYSgqIsq2L8SFYEHJPHNUiOTAJbDGzNjjr1/n9AcIayxafR/fWmYw==", + "dev": true, + "dependencies": { + "antlr4ts": "^0.5.0-alpha.4" + } + }, + "node_modules/solidity-coverage/node_modules/ansi-colors": { + "version": "3.2.3", + "resolved": "https://registry.npmjs.org/ansi-colors/-/ansi-colors-3.2.3.tgz", + "integrity": "sha512-LEHHyuhlPY3TmuUYMh2oz89lTShfvgbmzaBcxve9t/9Wuy7Dwf4yoAKcND7KFT1HAQfqZ12qtc+DUrBMeKF9nw==", + "dev": true, + "engines": { + "node": ">=6" + } + }, + "node_modules/solidity-coverage/node_modules/ansi-regex": { + "version": "4.1.1", + "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-4.1.1.tgz", + "integrity": "sha512-ILlv4k/3f6vfQ4OoP2AGvirOktlQ98ZEL1k9FaQjxa3L1abBgbuTDAdPOpvbGncC0BTVQrl+OM8xZGK6tWXt7g==", + "dev": true, + "engines": { + "node": ">=6" + } + }, + "node_modules/solidity-coverage/node_modules/camelcase": { + "version": "5.3.1", + "resolved": "https://registry.npmjs.org/camelcase/-/camelcase-5.3.1.tgz", + "integrity": "sha512-L28STB170nwWS63UjtlEOE3dldQApaJXZkOI1uMFfzf3rRuPegHaHesyee+YxQ+W6SvRDQV6UrdOdRiR153wJg==", + "dev": true, + "engines": { + "node": ">=6" + } + }, + "node_modules/solidity-coverage/node_modules/chokidar": { + "version": "3.3.0", + "resolved": "https://registry.npmjs.org/chokidar/-/chokidar-3.3.0.tgz", + "integrity": "sha512-dGmKLDdT3Gdl7fBUe8XK+gAtGmzy5Fn0XkkWQuYxGIgWVPPse2CxFA5mtrlD0TOHaHjEUqkWNyP1XdHoJES/4A==", + "dev": true, + "dependencies": { + "anymatch": "~3.1.1", + "braces": "~3.0.2", + "glob-parent": "~5.1.0", + "is-binary-path": "~2.1.0", + "is-glob": "~4.0.1", + "normalize-path": "~3.0.0", + "readdirp": "~3.2.0" + }, + "engines": { + "node": ">= 8.10.0" + }, + "optionalDependencies": { + "fsevents": "~2.1.1" + } + }, + "node_modules/solidity-coverage/node_modules/cliui": { + "version": "5.0.0", + "resolved": "https://registry.npmjs.org/cliui/-/cliui-5.0.0.tgz", + "integrity": "sha512-PYeGSEmmHM6zvoef2w8TPzlrnNpXIjTipYK780YswmIP9vjxmd6Y2a3CB2Ks6/AU8NHjZugXvo8w3oWM2qnwXA==", + "dev": true, + "dependencies": { + "string-width": "^3.1.0", + "strip-ansi": "^5.2.0", + "wrap-ansi": "^5.1.0" + } + }, + "node_modules/solidity-coverage/node_modules/debug": { + "version": "3.2.6", + "resolved": "https://registry.npmjs.org/debug/-/debug-3.2.6.tgz", + "integrity": "sha512-mel+jf7nrtEl5Pn1Qx46zARXKDpBbvzezse7p7LqINmdoIk8PYP5SySaxEmYv6TZ0JyEKA1hsCId6DIhgITtWQ==", + "deprecated": "Debug versions >=3.2.0 <3.2.7 || >=4 <4.3.1 have a low-severity ReDos regression when used in a Node.js environment. It is recommended you upgrade to 3.2.7 or 4.3.1. (https://github.com/visionmedia/debug/issues/797)", + "dev": true, + "dependencies": { + "ms": "^2.1.1" + } + }, + "node_modules/solidity-coverage/node_modules/diff": { + "version": "3.5.0", + "resolved": "https://registry.npmjs.org/diff/-/diff-3.5.0.tgz", + "integrity": "sha512-A46qtFgd+g7pDZinpnwiRJtxbC1hpgf0uzP3iG89scHk0AUC7A1TGxf5OiiOUv/JMZR8GOt8hL900hV0bOy5xA==", + "dev": true, + "engines": { + "node": ">=0.3.1" + } + }, + "node_modules/solidity-coverage/node_modules/emoji-regex": { + "version": "7.0.3", + "resolved": "https://registry.npmjs.org/emoji-regex/-/emoji-regex-7.0.3.tgz", + "integrity": "sha512-CwBLREIQ7LvYFB0WyRvwhq5N5qPhc6PMjD6bYggFlI5YyDgl+0vxq5VHbMOFqLg7hfWzmu8T5Z1QofhmTIhItA==", + "dev": true + }, + "node_modules/solidity-coverage/node_modules/find-up": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/find-up/-/find-up-3.0.0.tgz", + "integrity": "sha512-1yD6RmLI1XBfxugvORwlck6f75tYL+iR0jqwsOrOxMZyGYqUuDhJ0l4AXdO1iX/FTs9cBAMEk1gWSEx1kSbylg==", + "dev": true, + "dependencies": { + "locate-path": "^3.0.0" + }, + "engines": { + "node": ">=6" + } + }, + "node_modules/solidity-coverage/node_modules/flat": { + "version": "4.1.1", + "resolved": "https://registry.npmjs.org/flat/-/flat-4.1.1.tgz", + "integrity": "sha512-FmTtBsHskrU6FJ2VxCnsDb84wu9zhmO3cUX2kGFb5tuwhfXxGciiT0oRY+cck35QmG+NmGh5eLz6lLCpWTqwpA==", + "dev": true, + "dependencies": { + "is-buffer": "~2.0.3" + }, + "bin": { + "flat": "cli.js" + } + }, + "node_modules/solidity-coverage/node_modules/fs-extra": { + "version": "8.1.0", + "resolved": "https://registry.npmjs.org/fs-extra/-/fs-extra-8.1.0.tgz", + "integrity": "sha512-yhlQgA6mnOJUKOsRUFsgJdQCvkKhcz8tlZG5HBQfReYZy46OwLcY+Zia0mtdHsOo9y/hP+CxMN0TU9QxoOtG4g==", + "dev": true, + "dependencies": { + "graceful-fs": "^4.2.0", + "jsonfile": "^4.0.0", + "universalify": "^0.1.0" + }, + "engines": { + "node": ">=6 <7 || >=8" + } + }, + "node_modules/solidity-coverage/node_modules/fsevents": { + "version": "2.1.3", + "resolved": "https://registry.npmjs.org/fsevents/-/fsevents-2.1.3.tgz", + "integrity": "sha512-Auw9a4AxqWpa9GUfj370BMPzzyncfBABW8Mab7BGWBYDj4Isgq+cDKtx0i6u9jcX9pQDnswsaaOTgTmA5pEjuQ==", + "deprecated": "\"Please update to latest v2.3 or v2.2\"", + "dev": true, + "hasInstallScript": true, + "optional": true, + "os": [ + "darwin" + ], + "engines": { + "node": "^8.16.0 || ^10.6.0 || >=11.0.0" + } + }, + "node_modules/solidity-coverage/node_modules/glob": { + "version": "7.2.3", + "resolved": "https://registry.npmjs.org/glob/-/glob-7.2.3.tgz", + "integrity": "sha512-nFR0zLpU2YCaRxwoCJvL6UvCH2JFyFVIvwTLsIf21AuHlMskA1hhTdk+LlYJtOlYt9v6dvszD2BGRqBL+iQK9Q==", + "dev": true, + "dependencies": { + "fs.realpath": "^1.0.0", + "inflight": "^1.0.4", + "inherits": "2", + "minimatch": "^3.1.1", + "once": "^1.3.0", + "path-is-absolute": "^1.0.0" + }, + "engines": { + "node": "*" + }, + "funding": { + "url": "https://github.com/sponsors/isaacs" + } + }, + "node_modules/solidity-coverage/node_modules/globby": { + "version": "10.0.2", + "resolved": "https://registry.npmjs.org/globby/-/globby-10.0.2.tgz", + "integrity": "sha512-7dUi7RvCoT/xast/o/dLN53oqND4yk0nsHkhRgn9w65C4PofCLOoJ39iSOg+qVDdWQPIEj+eszMHQ+aLVwwQSg==", + "dev": true, + "dependencies": { + "@types/glob": "^7.1.1", + "array-union": "^2.1.0", + "dir-glob": "^3.0.1", + "fast-glob": "^3.0.3", + "glob": "^7.1.3", + "ignore": "^5.1.1", + "merge2": "^1.2.3", + "slash": "^3.0.0" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/solidity-coverage/node_modules/js-yaml": { + "version": "3.13.1", + "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-3.13.1.tgz", + "integrity": "sha512-YfbcO7jXDdyj0DGxYVSlSeQNHbD7XPWvrVWeVUujrQEoZzWJIRrCPoyk6kL6IAjAG2IolMK4T0hNUe0HOUs5Jw==", + "dev": true, + "dependencies": { + "argparse": "^1.0.7", + "esprima": "^4.0.0" + }, + "bin": { + "js-yaml": "bin/js-yaml.js" + } + }, + "node_modules/solidity-coverage/node_modules/locate-path": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/locate-path/-/locate-path-3.0.0.tgz", + "integrity": "sha512-7AO748wWnIhNqAuaty2ZWHkQHRSNfPVIsPIfwEOWO22AmaoVrWavlOcMR5nzTLNYvp36X220/maaRsrec1G65A==", + "dev": true, + "dependencies": { + "p-locate": "^3.0.0", + "path-exists": "^3.0.0" + }, + "engines": { + "node": ">=6" + } + }, + "node_modules/solidity-coverage/node_modules/log-symbols": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/log-symbols/-/log-symbols-3.0.0.tgz", + "integrity": "sha512-dSkNGuI7iG3mfvDzUuYZyvk5dD9ocYCYzNU6CYDE6+Xqd+gwme6Z00NS3dUh8mq/73HaEtT7m6W+yUPtU6BZnQ==", + "dev": true, + "dependencies": { + "chalk": "^2.4.2" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/solidity-coverage/node_modules/mkdirp": { + "version": "0.5.5", + "resolved": "https://registry.npmjs.org/mkdirp/-/mkdirp-0.5.5.tgz", + "integrity": "sha512-NKmAlESf6jMGym1++R0Ra7wvhV+wFW63FaSOFPwRahvea0gMUcGUhVeAg/0BC0wiv9ih5NYPB1Wn1UEI1/L+xQ==", + "dev": true, + "dependencies": { + "minimist": "^1.2.5" + }, + "bin": { + "mkdirp": "bin/cmd.js" + } + }, + "node_modules/solidity-coverage/node_modules/mocha": { + "version": "7.1.2", + "resolved": "https://registry.npmjs.org/mocha/-/mocha-7.1.2.tgz", + "integrity": "sha512-o96kdRKMKI3E8U0bjnfqW4QMk12MwZ4mhdBTf+B5a1q9+aq2HRnj+3ZdJu0B/ZhJeK78MgYuv6L8d/rA5AeBJA==", + "dev": true, + "dependencies": { + "ansi-colors": "3.2.3", + "browser-stdout": "1.3.1", + "chokidar": "3.3.0", + "debug": "3.2.6", + "diff": "3.5.0", + "escape-string-regexp": "1.0.5", + "find-up": "3.0.0", + "glob": "7.1.3", + "growl": "1.10.5", + "he": "1.2.0", + "js-yaml": "3.13.1", + "log-symbols": "3.0.0", + "minimatch": "3.0.4", + "mkdirp": "0.5.5", + "ms": "2.1.1", + "node-environment-flags": "1.0.6", + "object.assign": "4.1.0", + "strip-json-comments": "2.0.1", + "supports-color": "6.0.0", + "which": "1.3.1", + "wide-align": "1.1.3", + "yargs": "13.3.2", + "yargs-parser": "13.1.2", + "yargs-unparser": "1.6.0" + }, + "bin": { + "_mocha": "bin/_mocha", + "mocha": "bin/mocha" + }, + "engines": { + "node": ">= 8.10.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/mochajs" + } + }, + "node_modules/solidity-coverage/node_modules/mocha/node_modules/glob": { + "version": "7.1.3", + "resolved": "https://registry.npmjs.org/glob/-/glob-7.1.3.tgz", + "integrity": "sha512-vcfuiIxogLV4DlGBHIUOwI0IbrJ8HWPc4MU7HzviGeNho/UJDfi6B5p3sHeWIQ0KGIU0Jpxi5ZHxemQfLkkAwQ==", + "dev": true, + "dependencies": { + "fs.realpath": "^1.0.0", + "inflight": "^1.0.4", + "inherits": "2", + "minimatch": "^3.0.4", + "once": "^1.3.0", + "path-is-absolute": "^1.0.0" + }, + "engines": { + "node": "*" + } + }, + "node_modules/solidity-coverage/node_modules/mocha/node_modules/minimatch": { + "version": "3.0.4", + "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-3.0.4.tgz", + "integrity": "sha512-yJHVQEhyqPLUTgt9B83PXu6W3rx4MvvHvSUvToogpwoGDOUQ+yDrR0HRot+yOCdCO7u4hX3pWft6kWBBcqh0UA==", + "dev": true, + "dependencies": { + "brace-expansion": "^1.1.7" + }, + "engines": { + "node": "*" + } + }, + "node_modules/solidity-coverage/node_modules/ms": { + "version": "2.1.1", + "resolved": "https://registry.npmjs.org/ms/-/ms-2.1.1.tgz", + "integrity": "sha512-tgp+dl5cGk28utYktBsrFqA7HKgrhgPsg6Z/EfhWI4gl1Hwq8B/GmY/0oXZ6nF8hDVesS/FpnYaD/kOWhYQvyg==", + "dev": true + }, + "node_modules/solidity-coverage/node_modules/object.assign": { + "version": "4.1.0", + "resolved": "https://registry.npmjs.org/object.assign/-/object.assign-4.1.0.tgz", + "integrity": "sha512-exHJeq6kBKj58mqGyTQ9DFvrZC/eR6OwxzoM9YRoGBqrXYonaFyGiFMuc9VZrXf7DarreEwMpurG3dd+CNyW5w==", + "dev": true, + "dependencies": { + "define-properties": "^1.1.2", + "function-bind": "^1.1.1", + "has-symbols": "^1.0.0", + "object-keys": "^1.0.11" + }, + "engines": { + "node": ">= 0.4" + } + }, + "node_modules/solidity-coverage/node_modules/p-limit": { + "version": "2.3.0", + "resolved": "https://registry.npmjs.org/p-limit/-/p-limit-2.3.0.tgz", + "integrity": "sha512-//88mFWSJx8lxCzwdAABTJL2MyWB12+eIY7MDL2SqLmAkeKU9qxRvWuSyTjm3FUmpBEMuFfckAIqEaVGUDxb6w==", + "dev": true, + "dependencies": { + "p-try": "^2.0.0" + }, + "engines": { + "node": ">=6" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/solidity-coverage/node_modules/p-locate": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/p-locate/-/p-locate-3.0.0.tgz", + "integrity": "sha512-x+12w/To+4GFfgJhBEpiDcLozRJGegY+Ei7/z0tSLkMmxGZNybVMSfWj9aJn8Z5Fc7dBUNJOOVgPv2H7IwulSQ==", + "dev": true, + "dependencies": { + "p-limit": "^2.0.0" + }, + "engines": { + "node": ">=6" + } + }, + "node_modules/solidity-coverage/node_modules/path-exists": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/path-exists/-/path-exists-3.0.0.tgz", + "integrity": "sha512-bpC7GYwiDYQ4wYLe+FA8lhRjhQCMcQGuSgGGqDkg/QerRWw9CmGRT0iSOVRSZJ29NMLZgIzqaljJ63oaL4NIJQ==", + "dev": true, + "engines": { + "node": ">=4" + } + }, + "node_modules/solidity-coverage/node_modules/readdirp": { + "version": "3.2.0", + "resolved": "https://registry.npmjs.org/readdirp/-/readdirp-3.2.0.tgz", + "integrity": "sha512-crk4Qu3pmXwgxdSgGhgA/eXiJAPQiX4GMOZZMXnqKxHX7TaoL+3gQVo/WeuAiogr07DpnfjIMpXXa+PAIvwPGQ==", + "dev": true, + "dependencies": { + "picomatch": "^2.0.4" + }, + "engines": { + "node": ">= 8" + } + }, + "node_modules/solidity-coverage/node_modules/string-width": { + "version": "3.1.0", + "resolved": "https://registry.npmjs.org/string-width/-/string-width-3.1.0.tgz", + "integrity": "sha512-vafcv6KjVZKSgz06oM/H6GDBrAtz8vdhQakGjFIvNrHA6y3HCF1CInLy+QLq8dTJPQ1b+KDUqDFctkdRW44e1w==", + "dev": true, + "dependencies": { + "emoji-regex": "^7.0.1", + "is-fullwidth-code-point": "^2.0.0", + "strip-ansi": "^5.1.0" + }, + "engines": { + "node": ">=6" + } + }, + "node_modules/solidity-coverage/node_modules/strip-ansi": { + "version": "5.2.0", + "resolved": "https://registry.npmjs.org/strip-ansi/-/strip-ansi-5.2.0.tgz", + "integrity": "sha512-DuRs1gKbBqsMKIZlrffwlug8MHkcnpjs5VPmL1PAh+mA30U0DTotfDZ0d2UUsXpPmPmMMJ6W773MaA3J+lbiWA==", + "dev": true, + "dependencies": { + "ansi-regex": "^4.1.0" + }, + "engines": { + "node": ">=6" + } + }, + "node_modules/solidity-coverage/node_modules/strip-json-comments": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/strip-json-comments/-/strip-json-comments-2.0.1.tgz", + "integrity": "sha512-4gB8na07fecVVkOI6Rs4e7T6NOTki5EmL7TUduTs6bu3EdnSycntVJ4re8kgZA+wx9IueI2Y11bfbgwtzuE0KQ==", + "dev": true, + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/solidity-coverage/node_modules/supports-color": { + "version": "6.0.0", + "resolved": "https://registry.npmjs.org/supports-color/-/supports-color-6.0.0.tgz", + "integrity": "sha512-on9Kwidc1IUQo+bQdhi8+Tijpo0e1SS6RoGo2guUwn5vdaxw8RXOF9Vb2ws+ihWOmh4JnCJOvaziZWP1VABaLg==", + "dev": true, + "dependencies": { + "has-flag": "^3.0.0" + }, + "engines": { + "node": ">=6" + } + }, + "node_modules/solidity-coverage/node_modules/which": { + "version": "1.3.1", + "resolved": "https://registry.npmjs.org/which/-/which-1.3.1.tgz", + "integrity": "sha512-HxJdYWq1MTIQbJ3nw0cqssHoTNU267KlrDuGZ1WYlxDStUtKUhOaJmh112/TZmHxxUfuJqPXSOm7tDyas0OSIQ==", + "dev": true, + "dependencies": { + "isexe": "^2.0.0" + }, + "bin": { + "which": "bin/which" + } + }, + "node_modules/solidity-coverage/node_modules/wrap-ansi": { + "version": "5.1.0", + "resolved": "https://registry.npmjs.org/wrap-ansi/-/wrap-ansi-5.1.0.tgz", + "integrity": "sha512-QC1/iN/2/RPVJ5jYK8BGttj5z83LmSKmvbvrXPNCLZSEb32KKVDJDl/MOt2N01qU2H/FkzEa9PKto1BqDjtd7Q==", + "dev": true, + "dependencies": { + "ansi-styles": "^3.2.0", + "string-width": "^3.0.0", + "strip-ansi": "^5.0.0" + }, + "engines": { + "node": ">=6" + } + }, + "node_modules/solidity-coverage/node_modules/y18n": { + "version": "4.0.3", + "resolved": "https://registry.npmjs.org/y18n/-/y18n-4.0.3.tgz", + "integrity": "sha512-JKhqTOwSrqNA1NY5lSztJ1GrBiUodLMmIZuLiDaMRJ+itFd+ABVE8XBjOvIWL+rSqNDC74LCSFmlb/U4UZ4hJQ==", + "dev": true + }, + "node_modules/solidity-coverage/node_modules/yargs": { + "version": "13.3.2", + "resolved": "https://registry.npmjs.org/yargs/-/yargs-13.3.2.tgz", + "integrity": "sha512-AX3Zw5iPruN5ie6xGRIDgqkT+ZhnRlZMLMHAs8tg7nRruy2Nb+i5o9bwghAogtM08q1dpr2LVoS8KSTMYpWXUw==", + "dev": true, + "dependencies": { + "cliui": "^5.0.0", + "find-up": "^3.0.0", + "get-caller-file": "^2.0.1", + "require-directory": "^2.1.1", + "require-main-filename": "^2.0.0", + "set-blocking": "^2.0.0", + "string-width": "^3.0.0", + "which-module": "^2.0.0", + "y18n": "^4.0.0", + "yargs-parser": "^13.1.2" + } + }, + "node_modules/solidity-coverage/node_modules/yargs-parser": { + "version": "13.1.2", + "resolved": "https://registry.npmjs.org/yargs-parser/-/yargs-parser-13.1.2.tgz", + "integrity": "sha512-3lbsNRf/j+A4QuSZfDRA7HRSfWrzO0YjqTJd5kjAq37Zep1CEgaYmrH9Q3GwPiB9cHyd1Y1UwggGhJGoxipbzg==", + "dev": true, + "dependencies": { + "camelcase": "^5.0.0", + "decamelize": "^1.2.0" + } + }, + "node_modules/solidity-coverage/node_modules/yargs-unparser": { + "version": "1.6.0", + "resolved": "https://registry.npmjs.org/yargs-unparser/-/yargs-unparser-1.6.0.tgz", + "integrity": "sha512-W9tKgmSn0DpSatfri0nx52Joq5hVXgeLiqR/5G0sZNDoLZFOr/xjBUDcShCOGNsBnEMNo1KAMBkTej1Hm62HTw==", + "dev": true, + "dependencies": { + "flat": "^4.1.0", + "lodash": "^4.17.15", + "yargs": "^13.3.0" + }, + "engines": { + "node": ">=6" + } + }, + "node_modules/solidity-docgen": { + "version": "0.6.0-beta.35", + "resolved": "https://registry.npmjs.org/solidity-docgen/-/solidity-docgen-0.6.0-beta.35.tgz", + "integrity": "sha512-9QdwK1THk/MWIdq1PEW/6dvtND0pUqpFTsbKwwU9YQIMYuRhH1lek9SsgnsGGYtdJ0VTrXXcVT30q20a8Y610A==", + "dev": true, + "dependencies": { + "handlebars": "^4.7.7", + "solidity-ast": "^0.4.38" + }, + "peerDependencies": { + "hardhat": "^2.8.0" + } + }, + "node_modules/source-map": { + "version": "0.2.0", + "resolved": "https://registry.npmjs.org/source-map/-/source-map-0.2.0.tgz", + "integrity": "sha512-CBdZ2oa/BHhS4xj5DlhjWNHcan57/5YuvfdLf17iVmIpd9KRm+DFLmC6nBNj+6Ua7Kt3TmOjDpQT1aTYOQtoUA==", + "dev": true, + "optional": true, + "dependencies": { + "amdefine": ">=0.0.4" + }, + "engines": { + "node": ">=0.8.0" + } + }, + "node_modules/source-map-support": { + "version": "0.5.21", + "resolved": "https://registry.npmjs.org/source-map-support/-/source-map-support-0.5.21.tgz", + "integrity": "sha512-uBHU3L3czsIyYXKX88fdrGovxdSCoTGDRZ6SYXtSRxLZUzHg5P/66Ht6uoUlHu9EZod+inXhKo3qQgwXUT/y1w==", + "dev": true, + "dependencies": { + "buffer-from": "^1.0.0", + "source-map": "^0.6.0" + } + }, + "node_modules/source-map-support/node_modules/source-map": { + "version": "0.6.1", + "resolved": "https://registry.npmjs.org/source-map/-/source-map-0.6.1.tgz", + "integrity": "sha512-UjgapumWlbMhkBgzT7Ykc5YXUT46F0iKu8SGXq0bcwP5dz/h0Plj6enJqjz1Zbq2l5WaqYnrVbwWOWMyF3F47g==", + "dev": true, + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/spawndamnit": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/spawndamnit/-/spawndamnit-2.0.0.tgz", + "integrity": "sha512-j4JKEcncSjFlqIwU5L/rp2N5SIPsdxaRsIv678+TZxZ0SRDJTm8JrxJMjE/XuiEZNEir3S8l0Fa3Ke339WI4qA==", + "dev": true, + "dependencies": { + "cross-spawn": "^5.1.0", + "signal-exit": "^3.0.2" + } + }, + "node_modules/spawndamnit/node_modules/cross-spawn": { + "version": "5.1.0", + "resolved": "https://registry.npmjs.org/cross-spawn/-/cross-spawn-5.1.0.tgz", + "integrity": "sha512-pTgQJ5KC0d2hcY8eyL1IzlBPYjTkyH72XRZPnLyKus2mBfNjQs3klqbJU2VILqZryAZUt9JOb3h/mWMy23/f5A==", + "dev": true, + "dependencies": { + "lru-cache": "^4.0.1", + "shebang-command": "^1.2.0", + "which": "^1.2.9" + } + }, + "node_modules/spawndamnit/node_modules/lru-cache": { + "version": "4.1.5", + "resolved": "https://registry.npmjs.org/lru-cache/-/lru-cache-4.1.5.tgz", + "integrity": "sha512-sWZlbEP2OsHNkXrMl5GYk/jKk70MBng6UU4YI/qGDYbgf6YbP4EvmqISbXCoJiRKs+1bSpFHVgQxvJ17F2li5g==", + "dev": true, + "dependencies": { + "pseudomap": "^1.0.2", + "yallist": "^2.1.2" + } + }, + "node_modules/spawndamnit/node_modules/shebang-command": { + "version": "1.2.0", + "resolved": "https://registry.npmjs.org/shebang-command/-/shebang-command-1.2.0.tgz", + "integrity": "sha512-EV3L1+UQWGor21OmnvojK36mhg+TyIKDh3iFBKBohr5xeXIhNBcx8oWdgkTEEQ+BEFFYdLRuqMfd5L84N1V5Vg==", + "dev": true, + "dependencies": { + "shebang-regex": "^1.0.0" + }, + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/spawndamnit/node_modules/shebang-regex": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/shebang-regex/-/shebang-regex-1.0.0.tgz", + "integrity": "sha512-wpoSFAxys6b2a2wHZ1XpDSgD7N9iVjg29Ph9uV/uaP9Ex/KXlkTZTeddxDPSYQpgvzKLGJke2UU0AzoGCjNIvQ==", + "dev": true, + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/spawndamnit/node_modules/which": { + "version": "1.3.1", + "resolved": "https://registry.npmjs.org/which/-/which-1.3.1.tgz", + "integrity": "sha512-HxJdYWq1MTIQbJ3nw0cqssHoTNU267KlrDuGZ1WYlxDStUtKUhOaJmh112/TZmHxxUfuJqPXSOm7tDyas0OSIQ==", + "dev": true, + "dependencies": { + "isexe": "^2.0.0" + }, + "bin": { + "which": "bin/which" + } + }, + "node_modules/spawndamnit/node_modules/yallist": { + "version": "2.1.2", + "resolved": "https://registry.npmjs.org/yallist/-/yallist-2.1.2.tgz", + "integrity": "sha512-ncTzHV7NvsQZkYe1DW7cbDLm0YpzHmZF5r/iyP3ZnQtMiJ+pjzisCiMNI+Sj+xQF5pXhSHxSB3uDbsBTzY/c2A==", + "dev": true + }, + "node_modules/spdx-correct": { + "version": "3.2.0", + "resolved": "https://registry.npmjs.org/spdx-correct/-/spdx-correct-3.2.0.tgz", + "integrity": "sha512-kN9dJbvnySHULIluDHy32WHRUu3Og7B9sbY7tsFLctQkIqnMh3hErYgdMjTYuqmcXX+lK5T1lnUt3G7zNswmZA==", + "dev": true, + "dependencies": { + "spdx-expression-parse": "^3.0.0", + "spdx-license-ids": "^3.0.0" + } + }, + "node_modules/spdx-exceptions": { + "version": "2.3.0", + "resolved": "https://registry.npmjs.org/spdx-exceptions/-/spdx-exceptions-2.3.0.tgz", + "integrity": "sha512-/tTrYOC7PPI1nUAgx34hUpqXuyJG+DTHJTnIULG4rDygi4xu/tfgmq1e1cIRwRzwZgo4NLySi+ricLkZkw4i5A==", + "dev": true + }, + "node_modules/spdx-expression-parse": { + "version": "3.0.1", + "resolved": "https://registry.npmjs.org/spdx-expression-parse/-/spdx-expression-parse-3.0.1.tgz", + "integrity": "sha512-cbqHunsQWnJNE6KhVSMsMeH5H/L9EpymbzqTQ3uLwNCLZ1Q481oWaofqH7nO6V07xlXwY6PhQdQ2IedWx/ZK4Q==", + "dev": true, + "dependencies": { + "spdx-exceptions": "^2.1.0", + "spdx-license-ids": "^3.0.0" + } + }, + "node_modules/spdx-license-ids": { + "version": "3.0.13", + "resolved": "https://registry.npmjs.org/spdx-license-ids/-/spdx-license-ids-3.0.13.tgz", + "integrity": "sha512-XkD+zwiqXHikFZm4AX/7JSCXA98U5Db4AFd5XUg/+9UNtnH75+Z9KxtpYiJZx36mUDVOwH83pl7yvCer6ewM3w==", + "dev": true + }, + "node_modules/sprintf-js": { + "version": "1.0.3", + "resolved": "https://registry.npmjs.org/sprintf-js/-/sprintf-js-1.0.3.tgz", + "integrity": "sha512-D9cPgkvLlV3t3IzL0D0YLvGA9Ahk4PcvVwUbN0dSGr1aP0Nrt4AEnTUbuGvquEC0mA64Gqt1fzirlRs5ibXx8g==", + "dev": true + }, + "node_modules/sshpk": { + "version": "1.17.0", + "resolved": "https://registry.npmjs.org/sshpk/-/sshpk-1.17.0.tgz", + "integrity": "sha512-/9HIEs1ZXGhSPE8X6Ccm7Nam1z8KcoCqPdI7ecm1N33EzAetWahvQWVqLZtaZQ+IDKX4IyA2o0gBzqIMkAagHQ==", + "dev": true, + "dependencies": { + "asn1": "~0.2.3", + "assert-plus": "^1.0.0", + "bcrypt-pbkdf": "^1.0.0", + "dashdash": "^1.12.0", + "ecc-jsbn": "~0.1.1", + "getpass": "^0.1.1", + "jsbn": "~0.1.0", + "safer-buffer": "^2.0.2", + "tweetnacl": "~0.14.0" + }, + "bin": { + "sshpk-conv": "bin/sshpk-conv", + "sshpk-sign": "bin/sshpk-sign", + "sshpk-verify": "bin/sshpk-verify" + }, + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/sshpk/node_modules/tweetnacl": { + "version": "0.14.5", + "resolved": "https://registry.npmjs.org/tweetnacl/-/tweetnacl-0.14.5.tgz", + "integrity": "sha512-KXXFFdAbFXY4geFIwoyNK+f5Z1b7swfXABfL7HXCmoIWMKU3dmS26672A4EeQtDzLKy7SXmfBu51JolvEKwtGA==", + "dev": true + }, + "node_modules/stacktrace-parser": { + "version": "0.1.10", + "resolved": "https://registry.npmjs.org/stacktrace-parser/-/stacktrace-parser-0.1.10.tgz", + "integrity": "sha512-KJP1OCML99+8fhOHxwwzyWrlUuVX5GQ0ZpJTd1DFXhdkrvg1szxfHhawXUZ3g9TkXORQd4/WG68jMlQZ2p8wlg==", + "dev": true, + "dependencies": { + "type-fest": "^0.7.1" + }, + "engines": { + "node": ">=6" + } + }, + "node_modules/stacktrace-parser/node_modules/type-fest": { + "version": "0.7.1", + "resolved": "https://registry.npmjs.org/type-fest/-/type-fest-0.7.1.tgz", + "integrity": "sha512-Ne2YiiGN8bmrmJJEuTWTLJR32nh/JdL1+PSicowtNb0WFpn59GK8/lfD61bVtzguz7b3PBt74nxpv/Pw5po5Rg==", + "dev": true, + "engines": { + "node": ">=8" + } + }, + "node_modules/statuses": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/statuses/-/statuses-2.0.1.tgz", + "integrity": "sha512-RwNA9Z/7PrK06rYLIzFMlaF+l73iwpzsqRIFgbMLbTcLD6cOao82TaWefPXQvB2fOC4AjuYSEndS7N/mTCbkdQ==", + "dev": true, + "engines": { + "node": ">= 0.8" + } + }, + "node_modules/stealthy-require": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/stealthy-require/-/stealthy-require-1.1.1.tgz", + "integrity": "sha512-ZnWpYnYugiOVEY5GkcuJK1io5V8QmNYChG62gSit9pQVGErXtrKuPC55ITaVSukmMta5qpMU7vqLt2Lnni4f/g==", + "dev": true, + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/stream-transform": { + "version": "2.1.3", + "resolved": "https://registry.npmjs.org/stream-transform/-/stream-transform-2.1.3.tgz", + "integrity": "sha512-9GHUiM5hMiCi6Y03jD2ARC1ettBXkQBoQAe7nJsPknnI0ow10aXjTnew8QtYQmLjzn974BnmWEAJgCY6ZP1DeQ==", + "dev": true, + "dependencies": { + "mixme": "^0.5.1" + } + }, + "node_modules/streamsearch": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/streamsearch/-/streamsearch-1.1.0.tgz", + "integrity": "sha512-Mcc5wHehp9aXz1ax6bZUyY5afg9u2rv5cqQI3mRrYkGC8rW2hM02jWuwjtL++LS5qinSyhj2QfLyNsuc+VsExg==", + "dev": true, + "engines": { + "node": ">=10.0.0" + } + }, + "node_modules/strict-uri-encode": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/strict-uri-encode/-/strict-uri-encode-1.1.0.tgz", + "integrity": "sha512-R3f198pcvnB+5IpnBlRkphuE9n46WyVl8I39W/ZUTZLz4nqSP/oLYUrcnJrw462Ds8he4YKMov2efsTIw1BDGQ==", + "dev": true, + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/string_decoder": { + "version": "1.3.0", + "resolved": "https://registry.npmjs.org/string_decoder/-/string_decoder-1.3.0.tgz", + "integrity": "sha512-hkRX8U1WjJFd8LsDJ2yQ/wWWxaopEsABU1XfkM8A+j0+85JAGppt16cr1Whg6KIbb4okU6Mql6BOj+uup/wKeA==", + "dev": true, + "dependencies": { + "safe-buffer": "~5.2.0" + } + }, + "node_modules/string-width": { + "version": "2.1.1", + "resolved": "https://registry.npmjs.org/string-width/-/string-width-2.1.1.tgz", + "integrity": "sha512-nOqH59deCq9SRHlxq1Aw85Jnt4w6KvLKqWVik6oA9ZklXLNIOlqg4F2yrT1MVaTjAqvVwdfeZ7w7aCvJD7ugkw==", + "dev": true, + "dependencies": { + "is-fullwidth-code-point": "^2.0.0", + "strip-ansi": "^4.0.0" + }, + "engines": { + "node": ">=4" + } + }, + "node_modules/string.prototype.trim": { + "version": "1.2.7", + "resolved": "https://registry.npmjs.org/string.prototype.trim/-/string.prototype.trim-1.2.7.tgz", + "integrity": "sha512-p6TmeT1T3411M8Cgg9wBTMRtY2q9+PNy9EV1i2lIXUN/btt763oIfxwN3RR8VU6wHX8j/1CFy0L+YuThm6bgOg==", + "dev": true, + "dependencies": { + "call-bind": "^1.0.2", + "define-properties": "^1.1.4", + "es-abstract": "^1.20.4" + }, + "engines": { + "node": ">= 0.4" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/string.prototype.trimend": { + "version": "1.0.6", + "resolved": "https://registry.npmjs.org/string.prototype.trimend/-/string.prototype.trimend-1.0.6.tgz", + "integrity": "sha512-JySq+4mrPf9EsDBEDYMOb/lM7XQLulwg5R/m1r0PXEFqrV0qHvl58sdTilSXtKOflCsK2E8jxf+GKC0T07RWwQ==", + "dev": true, + "dependencies": { + "call-bind": "^1.0.2", + "define-properties": "^1.1.4", + "es-abstract": "^1.20.4" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/string.prototype.trimstart": { + "version": "1.0.6", + "resolved": "https://registry.npmjs.org/string.prototype.trimstart/-/string.prototype.trimstart-1.0.6.tgz", + "integrity": "sha512-omqjMDaY92pbn5HOX7f9IccLA+U1tA9GvtU4JrodiXFfYB7jPzzHpRzpglLAjtUV6bB557zwClJezTqnAiYnQA==", + "dev": true, + "dependencies": { + "call-bind": "^1.0.2", + "define-properties": "^1.1.4", + "es-abstract": "^1.20.4" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/strip-ansi": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/strip-ansi/-/strip-ansi-4.0.0.tgz", + "integrity": "sha512-4XaJ2zQdCzROZDivEVIDPkcQn8LMFSa8kj8Gxb/Lnwzv9A8VctNZ+lfivC/sV3ivW8ElJTERXZoPBRrZKkNKow==", + "dev": true, + "dependencies": { + "ansi-regex": "^3.0.0" + }, + "engines": { + "node": ">=4" + } + }, + "node_modules/strip-bom": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/strip-bom/-/strip-bom-3.0.0.tgz", + "integrity": "sha512-vavAMRXOgBVNF6nyEEmL3DBK19iRpDcoIwW+swQ+CbGiu7lju6t+JklA1MHweoWtadgt4ISVUsXLyDq34ddcwA==", + "dev": true, + "engines": { + "node": ">=4" + } + }, + "node_modules/strip-hex-prefix": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/strip-hex-prefix/-/strip-hex-prefix-1.0.0.tgz", + "integrity": "sha512-q8d4ue7JGEiVcypji1bALTos+0pWtyGlivAWyPuTkHzuTCJqrK9sWxYQZUq6Nq3cuyv3bm734IhHvHtGGURU6A==", + "dev": true, + "dependencies": { + "is-hex-prefixed": "1.0.0" + }, + "engines": { + "node": ">=6.5.0", + "npm": ">=3" + } + }, + "node_modules/strip-indent": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/strip-indent/-/strip-indent-2.0.0.tgz", + "integrity": "sha512-RsSNPLpq6YUL7QYy44RnPVTn/lcVZtb48Uof3X5JLbF4zD/Gs7ZFDv2HWol+leoQN2mT86LAzSshGfkTlSOpsA==", + "dev": true, + "engines": { + "node": ">=4" + } + }, + "node_modules/strip-json-comments": { + "version": "3.1.1", + "resolved": "https://registry.npmjs.org/strip-json-comments/-/strip-json-comments-3.1.1.tgz", + "integrity": "sha512-6fPc+R4ihwqP6N/aIv2f1gMH8lOVtWQHoqC4yK6oSDVVocumAsfCqjkXnqiYMhmMwS/mEHLp7Vehlt3ql6lEig==", + "dev": true, + "engines": { + "node": ">=8" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/supports-color": { + "version": "5.5.0", + "resolved": "https://registry.npmjs.org/supports-color/-/supports-color-5.5.0.tgz", + "integrity": "sha512-QjVjwdXIt408MIiAqCX4oUKsgU2EqAGzs2Ppkm4aQYbjm+ZEWEcW4SfFNTr4uMNZma0ey4f5lgLrkB0aX0QMow==", + "dev": true, + "dependencies": { + "has-flag": "^3.0.0" + }, + "engines": { + "node": ">=4" + } + }, + "node_modules/swap-case": { + "version": "1.1.2", + "resolved": "https://registry.npmjs.org/swap-case/-/swap-case-1.1.2.tgz", + "integrity": "sha512-BAmWG6/bx8syfc6qXPprof3Mn5vQgf5dwdUNJhsNqU9WdPt5P+ES/wQ5bxfijy8zwZgZZHslC3iAsxsuQMCzJQ==", + "dev": true, + "dependencies": { + "lower-case": "^1.1.1", + "upper-case": "^1.1.1" + } + }, + "node_modules/swarm-js": { + "version": "0.1.42", + "resolved": "https://registry.npmjs.org/swarm-js/-/swarm-js-0.1.42.tgz", + "integrity": "sha512-BV7c/dVlA3R6ya1lMlSSNPLYrntt0LUq4YMgy3iwpCIc6rZnS5W2wUoctarZ5pXlpKtxDDf9hNziEkcfrxdhqQ==", + "dev": true, + "dependencies": { + "bluebird": "^3.5.0", + "buffer": "^5.0.5", + "eth-lib": "^0.1.26", + "fs-extra": "^4.0.2", + "got": "^11.8.5", + "mime-types": "^2.1.16", + "mkdirp-promise": "^5.0.1", + "mock-fs": "^4.1.0", + "setimmediate": "^1.0.5", + "tar": "^4.0.2", + "xhr-request": "^1.0.1" + } + }, + "node_modules/swarm-js/node_modules/@szmarczak/http-timer": { + "version": "4.0.6", + "resolved": "https://registry.npmjs.org/@szmarczak/http-timer/-/http-timer-4.0.6.tgz", + "integrity": "sha512-4BAffykYOgO+5nzBWYwE3W90sBgLJoUPRWWcL8wlyiM8IB8ipJz3UMJ9KXQd1RKQXpKp8Tutn80HZtWsu2u76w==", + "dev": true, + "dependencies": { + "defer-to-connect": "^2.0.0" + }, + "engines": { + "node": ">=10" + } + }, + "node_modules/swarm-js/node_modules/cacheable-lookup": { + "version": "5.0.4", + "resolved": "https://registry.npmjs.org/cacheable-lookup/-/cacheable-lookup-5.0.4.tgz", + "integrity": "sha512-2/kNscPhpcxrOigMZzbiWF7dz8ilhb/nIHU3EyZiXWXpeq/au8qJ8VhdftMkty3n7Gj6HIGalQG8oiBNB3AJgA==", + "dev": true, + "engines": { + "node": ">=10.6.0" + } + }, + "node_modules/swarm-js/node_modules/fs-extra": { + "version": "4.0.3", + "resolved": "https://registry.npmjs.org/fs-extra/-/fs-extra-4.0.3.tgz", + "integrity": "sha512-q6rbdDd1o2mAnQreO7YADIxf/Whx4AHBiRf6d+/cVT8h44ss+lHgxf1FemcqDnQt9X3ct4McHr+JMGlYSsK7Cg==", + "dev": true, + "dependencies": { + "graceful-fs": "^4.1.2", + "jsonfile": "^4.0.0", + "universalify": "^0.1.0" + } + }, + "node_modules/swarm-js/node_modules/got": { + "version": "11.8.6", + "resolved": "https://registry.npmjs.org/got/-/got-11.8.6.tgz", + "integrity": "sha512-6tfZ91bOr7bOXnK7PRDCGBLa1H4U080YHNaAQ2KsMGlLEzRbk44nsZF2E1IeRc3vtJHPVbKCYgdFbaGO2ljd8g==", + "dev": true, + "dependencies": { + "@sindresorhus/is": "^4.0.0", + "@szmarczak/http-timer": "^4.0.5", + "@types/cacheable-request": "^6.0.1", + "@types/responselike": "^1.0.0", + "cacheable-lookup": "^5.0.3", + "cacheable-request": "^7.0.2", + "decompress-response": "^6.0.0", + "http2-wrapper": "^1.0.0-beta.5.2", + "lowercase-keys": "^2.0.0", + "p-cancelable": "^2.0.0", + "responselike": "^2.0.0" + }, + "engines": { + "node": ">=10.19.0" + }, + "funding": { + "url": "https://github.com/sindresorhus/got?sponsor=1" + } + }, + "node_modules/swarm-js/node_modules/http2-wrapper": { + "version": "1.0.3", + "resolved": "https://registry.npmjs.org/http2-wrapper/-/http2-wrapper-1.0.3.tgz", + "integrity": "sha512-V+23sDMr12Wnz7iTcDeJr3O6AIxlnvT/bmaAAAP/Xda35C90p9599p0F1eHR/N1KILWSoWVAiOMFjBBXaXSMxg==", + "dev": true, + "dependencies": { + "quick-lru": "^5.1.1", + "resolve-alpn": "^1.0.0" + }, + "engines": { + "node": ">=10.19.0" + } + }, + "node_modules/swarm-js/node_modules/lowercase-keys": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/lowercase-keys/-/lowercase-keys-2.0.0.tgz", + "integrity": "sha512-tqNXrS78oMOE73NMxK4EMLQsQowWf8jKooH9g7xPavRT706R6bkQJ6DY2Te7QukaZsulxa30wQ7bk0pm4XiHmA==", + "dev": true, + "engines": { + "node": ">=8" + } + }, + "node_modules/swarm-js/node_modules/p-cancelable": { + "version": "2.1.1", + "resolved": "https://registry.npmjs.org/p-cancelable/-/p-cancelable-2.1.1.tgz", + "integrity": "sha512-BZOr3nRQHOntUjTrH8+Lh54smKHoHyur8We1V8DSMVrl5A2malOOwuJRnKRDjSnkoeBh4at6BwEnb5I7Jl31wg==", + "dev": true, + "engines": { + "node": ">=8" + } + }, + "node_modules/swarm-js/node_modules/quick-lru": { + "version": "5.1.1", + "resolved": "https://registry.npmjs.org/quick-lru/-/quick-lru-5.1.1.tgz", + "integrity": "sha512-WuyALRjWPDGtt/wzJiadO5AXY+8hZ80hVpe6MyivgraREW751X3SbhRvG3eLKOYN+8VEvqLcf3wdnt44Z4S4SA==", + "dev": true, + "engines": { + "node": ">=10" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/sync-request": { + "version": "6.1.0", + "resolved": "https://registry.npmjs.org/sync-request/-/sync-request-6.1.0.tgz", + "integrity": "sha512-8fjNkrNlNCrVc/av+Jn+xxqfCjYaBoHqCsDz6mt030UMxJGr+GSfCV1dQt2gRtlL63+VPidwDVLr7V2OcTSdRw==", + "dev": true, + "dependencies": { + "http-response-object": "^3.0.1", + "sync-rpc": "^1.2.1", + "then-request": "^6.0.0" + }, + "engines": { + "node": ">=8.0.0" + } + }, + "node_modules/sync-rpc": { + "version": "1.3.6", + "resolved": "https://registry.npmjs.org/sync-rpc/-/sync-rpc-1.3.6.tgz", + "integrity": "sha512-J8jTXuZzRlvU7HemDgHi3pGnh/rkoqR/OZSjhTyyZrEkkYQbk7Z33AXp37mkPfPpfdOuj7Ex3H/TJM1z48uPQw==", + "dev": true, + "dependencies": { + "get-port": "^3.1.0" + } + }, + "node_modules/table": { + "version": "6.8.1", + "resolved": "https://registry.npmjs.org/table/-/table-6.8.1.tgz", + "integrity": "sha512-Y4X9zqrCftUhMeH2EptSSERdVKt/nEdijTOacGD/97EKjhQ/Qs8RTlEGABSJNNN8lac9kheH+af7yAkEWlgneA==", + "dev": true, + "dependencies": { + "ajv": "^8.0.1", + "lodash.truncate": "^4.4.2", + "slice-ansi": "^4.0.0", + "string-width": "^4.2.3", + "strip-ansi": "^6.0.1" + }, + "engines": { + "node": ">=10.0.0" + } + }, + "node_modules/table/node_modules/ajv": { + "version": "8.12.0", + "resolved": "https://registry.npmjs.org/ajv/-/ajv-8.12.0.tgz", + "integrity": "sha512-sRu1kpcO9yLtYxBKvqfTeh9KzZEwO3STyX1HT+4CaDzC6HpTGYhIhPIzj9XuKU7KYDwnaeh5hcOwjy1QuJzBPA==", + "dev": true, + "dependencies": { + "fast-deep-equal": "^3.1.1", + "json-schema-traverse": "^1.0.0", + "require-from-string": "^2.0.2", + "uri-js": "^4.2.2" + }, + "funding": { + "type": "github", + "url": "https://github.com/sponsors/epoberezkin" + } + }, + "node_modules/table/node_modules/ansi-regex": { + "version": "5.0.1", + "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-5.0.1.tgz", + "integrity": "sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ==", + "dev": true, + "engines": { + "node": ">=8" + } + }, + "node_modules/table/node_modules/is-fullwidth-code-point": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/is-fullwidth-code-point/-/is-fullwidth-code-point-3.0.0.tgz", + "integrity": "sha512-zymm5+u+sCsSWyD9qNaejV3DFvhCKclKdizYaJUuHA83RLjb7nSuGnddCHGv0hk+KY7BMAlsWeK4Ueg6EV6XQg==", + "dev": true, + "engines": { + "node": ">=8" + } + }, + "node_modules/table/node_modules/json-schema-traverse": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/json-schema-traverse/-/json-schema-traverse-1.0.0.tgz", + "integrity": "sha512-NM8/P9n3XjXhIZn1lLhkFaACTOURQXjWhV4BA/RnOv8xvgqtqpAX9IO4mRQxSx1Rlo4tqzeqb0sOlruaOy3dug==", + "dev": true + }, + "node_modules/table/node_modules/require-from-string": { + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/require-from-string/-/require-from-string-2.0.2.tgz", + "integrity": "sha512-Xf0nWe6RseziFMu+Ap9biiUbmplq6S9/p+7w7YXP/JBHhrUDDUhwa+vANyubuqfZWTveU//DYVGsDG7RKL/vEw==", + "dev": true, + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/table/node_modules/string-width": { + "version": "4.2.3", + "resolved": "https://registry.npmjs.org/string-width/-/string-width-4.2.3.tgz", + "integrity": "sha512-wKyQRQpjJ0sIp62ErSZdGsjMJWsap5oRNihHhu6G7JVO/9jIB6UyevL+tXuOqrng8j/cxKTWyWUwvSTriiZz/g==", + "dev": true, + "dependencies": { + "emoji-regex": "^8.0.0", + "is-fullwidth-code-point": "^3.0.0", + "strip-ansi": "^6.0.1" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/table/node_modules/strip-ansi": { + "version": "6.0.1", + "resolved": "https://registry.npmjs.org/strip-ansi/-/strip-ansi-6.0.1.tgz", + "integrity": "sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A==", + "dev": true, + "dependencies": { + "ansi-regex": "^5.0.1" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/tar": { + "version": "4.4.19", + "resolved": "https://registry.npmjs.org/tar/-/tar-4.4.19.tgz", + "integrity": "sha512-a20gEsvHnWe0ygBY8JbxoM4w3SJdhc7ZAuxkLqh+nvNQN2IOt0B5lLgM490X5Hl8FF0dl0tOf2ewFYAlIFgzVA==", + "dev": true, + "dependencies": { + "chownr": "^1.1.4", + "fs-minipass": "^1.2.7", + "minipass": "^2.9.0", + "minizlib": "^1.3.3", + "mkdirp": "^0.5.5", + "safe-buffer": "^5.2.1", + "yallist": "^3.1.1" + }, + "engines": { + "node": ">=4.5" + } + }, + "node_modules/term-size": { + "version": "2.2.1", + "resolved": "https://registry.npmjs.org/term-size/-/term-size-2.2.1.tgz", + "integrity": "sha512-wK0Ri4fOGjv/XPy8SBHZChl8CM7uMc5VML7SqiQ0zG7+J5Vr+RMQDoHa2CNT6KHUnTGIXH34UDMkPzAUyapBZg==", + "dev": true, + "engines": { + "node": ">=8" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/testrpc": { + "version": "0.0.1", + "resolved": "https://registry.npmjs.org/testrpc/-/testrpc-0.0.1.tgz", + "integrity": "sha512-afH1hO+SQ/VPlmaLUFj2636QMeDvPCeQMc/9RBMW0IfjNe9gFD9Ra3ShqYkB7py0do1ZcCna/9acHyzTJ+GcNA==", + "deprecated": "testrpc has been renamed to ganache-cli, please use this package from now on.", + "dev": true + }, + "node_modules/text-table": { + "version": "0.2.0", + "resolved": "https://registry.npmjs.org/text-table/-/text-table-0.2.0.tgz", + "integrity": "sha512-N+8UisAXDGk8PFXP4HAzVR9nbfmVJ3zYLAWiTIoqC5v5isinhr+r5uaO8+7r3BMfuNIufIsA7RdpVgacC2cSpw==", + "dev": true + }, + "node_modules/then-request": { + "version": "6.0.2", + "resolved": "https://registry.npmjs.org/then-request/-/then-request-6.0.2.tgz", + "integrity": "sha512-3ZBiG7JvP3wbDzA9iNY5zJQcHL4jn/0BWtXIkagfz7QgOL/LqjCEOBQuJNZfu0XYnv5JhKh+cDxCPM4ILrqruA==", + "dev": true, + "dependencies": { + "@types/concat-stream": "^1.6.0", + "@types/form-data": "0.0.33", + "@types/node": "^8.0.0", + "@types/qs": "^6.2.31", + "caseless": "~0.12.0", + "concat-stream": "^1.6.0", + "form-data": "^2.2.0", + "http-basic": "^8.1.1", + "http-response-object": "^3.0.1", + "promise": "^8.0.0", + "qs": "^6.4.0" + }, + "engines": { + "node": ">=6.0.0" + } + }, + "node_modules/then-request/node_modules/@types/node": { + "version": "8.10.66", + "resolved": "https://registry.npmjs.org/@types/node/-/node-8.10.66.tgz", + "integrity": "sha512-tktOkFUA4kXx2hhhrB8bIFb5TbwzS4uOhKEmwiD+NoiL0qtP2OQ9mFldbgD4dV1djrlBYP6eBuQZiWjuHUpqFw==", + "dev": true + }, + "node_modules/timed-out": { + "version": "4.0.1", + "resolved": "https://registry.npmjs.org/timed-out/-/timed-out-4.0.1.tgz", + "integrity": "sha512-G7r3AhovYtr5YKOWQkta8RKAPb+J9IsO4uVmzjl8AZwfhs8UcUwTiD6gcJYSgOtzyjvQKrKYn41syHbUWMkafA==", + "dev": true, + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/title-case": { + "version": "2.1.1", + "resolved": "https://registry.npmjs.org/title-case/-/title-case-2.1.1.tgz", + "integrity": "sha512-EkJoZ2O3zdCz3zJsYCsxyq2OC5hrxR9mfdd5I+w8h/tmFfeOxJ+vvkxsKxdmN0WtS9zLdHEgfgVOiMVgv+Po4Q==", + "dev": true, + "dependencies": { + "no-case": "^2.2.0", + "upper-case": "^1.0.3" + } + }, + "node_modules/tmp": { + "version": "0.0.33", + "resolved": "https://registry.npmjs.org/tmp/-/tmp-0.0.33.tgz", + "integrity": "sha512-jRCJlojKnZ3addtTOjdIqoRuPEKBvNXcGYqzO6zWZX8KfKEpnGY5jfggJQ3EjKuu8D4bJRr0y+cYJFmYbImXGw==", + "dev": true, + "dependencies": { + "os-tmpdir": "~1.0.2" + }, + "engines": { + "node": ">=0.6.0" + } + }, + "node_modules/to-regex-range": { + "version": "5.0.1", + "resolved": "https://registry.npmjs.org/to-regex-range/-/to-regex-range-5.0.1.tgz", + "integrity": "sha512-65P7iz6X5yEr1cwcgvQxbbIw7Uk3gOy5dIdtZ4rDveLqhrdJP+Li/Hx6tyK0NEb+2GCyneCMJiGqrADCSNk8sQ==", + "dev": true, + "dependencies": { + "is-number": "^7.0.0" + }, + "engines": { + "node": ">=8.0" + } + }, + "node_modules/toidentifier": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/toidentifier/-/toidentifier-1.0.1.tgz", + "integrity": "sha512-o5sSPKEkg/DIQNmH43V0/uerLrpzVedkUh8tGNvaeXpfpuwjKenlSox/2O/BTlZUtEe+JG7s5YhEz608PlAHRA==", + "dev": true, + "engines": { + "node": ">=0.6" + } + }, + "node_modules/tough-cookie": { + "version": "2.5.0", + "resolved": "https://registry.npmjs.org/tough-cookie/-/tough-cookie-2.5.0.tgz", + "integrity": "sha512-nlLsUzgm1kfLXSXfRZMc1KLAugd4hqJHDTvc2hDIwS3mZAfMEuMbc03SujMF+GEcpaX/qboeycw6iO8JwVv2+g==", + "dev": true, + "dependencies": { + "psl": "^1.1.28", + "punycode": "^2.1.1" + }, + "engines": { + "node": ">=0.8" + } + }, + "node_modules/tough-cookie/node_modules/punycode": { + "version": "2.3.0", + "resolved": "https://registry.npmjs.org/punycode/-/punycode-2.3.0.tgz", + "integrity": "sha512-rRV+zQD8tVFys26lAGR9WUuS4iUAngJScM+ZRSKtvl5tKeZ2t5bvdNFdNHBW9FWR4guGHlgmsZ1G7BSm2wTbuA==", + "dev": true, + "engines": { + "node": ">=6" + } + }, + "node_modules/tr46": { + "version": "0.0.3", + "resolved": "https://registry.npmjs.org/tr46/-/tr46-0.0.3.tgz", + "integrity": "sha512-N3WMsuqV66lT30CrXNbEjx4GEwlow3v6rr4mCcv6prnfwhS01rkgyFdjPNBYd9br7LpXV1+Emh01fHnq2Gdgrw==", + "dev": true + }, + "node_modules/treeify": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/treeify/-/treeify-1.1.0.tgz", + "integrity": "sha512-1m4RA7xVAJrSGrrXGs0L3YTwyvBs2S8PbRHaLZAkFw7JR8oIFwYtysxlBZhYIa7xSyiYJKZ3iGrrk55cGA3i9A==", + "dev": true, + "engines": { + "node": ">=0.6" + } + }, + "node_modules/trim-newlines": { + "version": "3.0.1", + "resolved": "https://registry.npmjs.org/trim-newlines/-/trim-newlines-3.0.1.tgz", + "integrity": "sha512-c1PTsA3tYrIsLGkJkzHF+w9F2EyxfXGo4UyJc4pFL++FMjnq0HJS69T3M7d//gKrFKwy429bouPescbjecU+Zw==", + "dev": true, + "engines": { + "node": ">=8" + } + }, + "node_modules/tslib": { + "version": "1.14.1", + "resolved": "https://registry.npmjs.org/tslib/-/tslib-1.14.1.tgz", + "integrity": "sha512-Xni35NKzjgMrwevysHTCArtLDpPvye8zV/0E4EyYn43P7/7qvQwPh9BGkHewbMulVntbigmcT7rdX3BNo9wRJg==", + "dev": true + }, + "node_modules/tsort": { + "version": "0.0.1", + "resolved": "https://registry.npmjs.org/tsort/-/tsort-0.0.1.tgz", + "integrity": "sha512-Tyrf5mxF8Ofs1tNoxA13lFeZ2Zrbd6cKbuH3V+MQ5sb6DtBj5FjrXVsRWT8YvNAQTqNoz66dz1WsbigI22aEnw==", + "dev": true + }, + "node_modules/tty-table": { + "version": "4.2.1", + "resolved": "https://registry.npmjs.org/tty-table/-/tty-table-4.2.1.tgz", + "integrity": "sha512-xz0uKo+KakCQ+Dxj1D/tKn2FSyreSYWzdkL/BYhgN6oMW808g8QRMuh1atAV9fjTPbWBjfbkKQpI/5rEcnAc7g==", + "dev": true, + "dependencies": { + "chalk": "^4.1.2", + "csv": "^5.5.3", + "kleur": "^4.1.5", + "smartwrap": "^2.0.2", + "strip-ansi": "^6.0.1", + "wcwidth": "^1.0.1", + "yargs": "^17.7.1" + }, + "bin": { + "tty-table": "adapters/terminal-adapter.js" + }, + "engines": { + "node": ">=8.0.0" + } + }, + "node_modules/tty-table/node_modules/ansi-regex": { + "version": "5.0.1", + "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-5.0.1.tgz", + "integrity": "sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ==", + "dev": true, + "engines": { + "node": ">=8" + } + }, + "node_modules/tty-table/node_modules/ansi-styles": { + "version": "4.3.0", + "resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-4.3.0.tgz", + "integrity": "sha512-zbB9rCJAT1rbjiVDb2hqKFHNYLxgtk8NURxZ3IZwD3F6NtxbXZQCnnSi1Lkx+IDohdPlFp222wVALIheZJQSEg==", + "dev": true, + "dependencies": { + "color-convert": "^2.0.1" + }, + "engines": { + "node": ">=8" + }, + "funding": { + "url": "https://github.com/chalk/ansi-styles?sponsor=1" + } + }, + "node_modules/tty-table/node_modules/chalk": { + "version": "4.1.2", + "resolved": "https://registry.npmjs.org/chalk/-/chalk-4.1.2.tgz", + "integrity": "sha512-oKnbhFyRIXpUuez8iBMmyEa4nbj4IOQyuhc/wy9kY7/WVPcwIO9VA668Pu8RkO7+0G76SLROeyw9CpQ061i4mA==", + "dev": true, + "dependencies": { + "ansi-styles": "^4.1.0", + "supports-color": "^7.1.0" + }, + "engines": { + "node": ">=10" + }, + "funding": { + "url": "https://github.com/chalk/chalk?sponsor=1" + } + }, + "node_modules/tty-table/node_modules/color-convert": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/color-convert/-/color-convert-2.0.1.tgz", + "integrity": "sha512-RRECPsj7iu/xb5oKYcsFHSppFNnsj/52OVTRKb4zP5onXwVF3zVmmToNcOfGC+CRDpfK/U584fMg38ZHCaElKQ==", + "dev": true, + "dependencies": { + "color-name": "~1.1.4" + }, + "engines": { + "node": ">=7.0.0" + } + }, + "node_modules/tty-table/node_modules/color-name": { + "version": "1.1.4", + "resolved": "https://registry.npmjs.org/color-name/-/color-name-1.1.4.tgz", + "integrity": "sha512-dOy+3AuW3a2wNbZHIuMZpTcgjGuLU/uBL/ubcZF9OXbDo8ff4O8yVp5Bf0efS8uEoYo5q4Fx7dY9OgQGXgAsQA==", + "dev": true + }, + "node_modules/tty-table/node_modules/has-flag": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/has-flag/-/has-flag-4.0.0.tgz", + "integrity": "sha512-EykJT/Q1KjTWctppgIAgfSO0tKVuZUjhgMr17kqTumMl6Afv3EISleU7qZUzoXDFTAHTDC4NOoG/ZxU3EvlMPQ==", + "dev": true, + "engines": { + "node": ">=8" + } + }, + "node_modules/tty-table/node_modules/strip-ansi": { + "version": "6.0.1", + "resolved": "https://registry.npmjs.org/strip-ansi/-/strip-ansi-6.0.1.tgz", + "integrity": "sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A==", + "dev": true, + "dependencies": { + "ansi-regex": "^5.0.1" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/tty-table/node_modules/supports-color": { + "version": "7.2.0", + "resolved": "https://registry.npmjs.org/supports-color/-/supports-color-7.2.0.tgz", + "integrity": "sha512-qpCAvRl9stuOHveKsn7HncJRvv501qIacKzQlO/+Lwxc9+0q2wLyv4Dfvt80/DPn2pqOBsJdDiogXGR9+OvwRw==", + "dev": true, + "dependencies": { + "has-flag": "^4.0.0" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/tunnel-agent": { + "version": "0.6.0", + "resolved": "https://registry.npmjs.org/tunnel-agent/-/tunnel-agent-0.6.0.tgz", + "integrity": "sha512-McnNiV1l8RYeY8tBgEpuodCC1mLUdbSN+CYBL7kJsJNInOP8UjDDEwdk6Mw60vdLLrr5NHKZhMAOSrR2NZuQ+w==", + "dev": true, + "dependencies": { + "safe-buffer": "^5.0.1" + }, + "engines": { + "node": "*" + } + }, + "node_modules/tweetnacl": { + "version": "1.0.3", + "resolved": "https://registry.npmjs.org/tweetnacl/-/tweetnacl-1.0.3.tgz", + "integrity": "sha512-6rt+RN7aOi1nGMyC4Xa5DdYiukl2UWCbcJft7YhxReBGQD7OAM8Pbxw6YMo4r2diNEA8FEmu32YOn9rhaiE5yw==", + "dev": true + }, + "node_modules/tweetnacl-util": { + "version": "0.15.1", + "resolved": "https://registry.npmjs.org/tweetnacl-util/-/tweetnacl-util-0.15.1.tgz", + "integrity": "sha512-RKJBIj8lySrShN4w6i/BonWp2Z/uxwC3h4y7xsRrpP59ZboCd0GpEVsOnMDYLMmKBpYhb5TgHzZXy7wTfYFBRw==", + "dev": true + }, + "node_modules/type": { + "version": "1.2.0", + "resolved": "https://registry.npmjs.org/type/-/type-1.2.0.tgz", + "integrity": "sha512-+5nt5AAniqsCnu2cEQQdpzCAh33kVx8n0VoFidKpB1dVVLAN/F+bgVOqOJqOnEnrhp222clB5p3vUlD+1QAnfg==", + "dev": true + }, + "node_modules/type-check": { + "version": "0.4.0", + "resolved": "https://registry.npmjs.org/type-check/-/type-check-0.4.0.tgz", + "integrity": "sha512-XleUoc9uwGXqjWwXaUTZAmzMcFZ5858QA2vvx1Ur5xIcixXIP+8LnFDgRplU30us6teqdlskFfu+ae4K79Ooew==", + "dev": true, + "dependencies": { + "prelude-ls": "^1.2.1" + }, + "engines": { + "node": ">= 0.8.0" + } + }, + "node_modules/type-detect": { + "version": "4.0.8", + "resolved": "https://registry.npmjs.org/type-detect/-/type-detect-4.0.8.tgz", + "integrity": "sha512-0fr/mIH1dlO+x7TlcMy+bIDqKPsw/70tVyeHW787goQjhmqaZe10uwLujubK9q9Lg6Fiho1KUKDYz0Z7k7g5/g==", + "dev": true, + "engines": { + "node": ">=4" + } + }, + "node_modules/type-fest": { + "version": "0.20.2", + "resolved": "https://registry.npmjs.org/type-fest/-/type-fest-0.20.2.tgz", + "integrity": "sha512-Ne+eE4r0/iWnpAxD852z3A+N0Bt5RN//NjJwRd2VFHEmrywxf5vsZlh4R6lixl6B+wz/8d+maTSAkN1FIkI3LQ==", + "dev": true, + "engines": { + "node": ">=10" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/type-is": { + "version": "1.6.18", + "resolved": "https://registry.npmjs.org/type-is/-/type-is-1.6.18.tgz", + "integrity": "sha512-TkRKr9sUTxEH8MdfuCSP7VizJyzRNMjj2J2do2Jr3Kym598JVdEksuzPQCnlFPW4ky9Q+iA+ma9BGm06XQBy8g==", + "dev": true, + "dependencies": { + "media-typer": "0.3.0", + "mime-types": "~2.1.24" + }, + "engines": { + "node": ">= 0.6" + } + }, + "node_modules/typed-array-length": { + "version": "1.0.4", + "resolved": "https://registry.npmjs.org/typed-array-length/-/typed-array-length-1.0.4.tgz", + "integrity": "sha512-KjZypGq+I/H7HI5HlOoGHkWUUGq+Q0TPhQurLbyrVrvnKTBgzLhIJ7j6J/XTQOi0d1RjyZ0wdas8bKs2p0x3Ng==", + "dev": true, + "dependencies": { + "call-bind": "^1.0.2", + "for-each": "^0.3.3", + "is-typed-array": "^1.1.9" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/typedarray": { + "version": "0.0.6", + "resolved": "https://registry.npmjs.org/typedarray/-/typedarray-0.0.6.tgz", + "integrity": "sha512-/aCDEGatGvZ2BIk+HmLf4ifCJFwvKFNb9/JeZPMulfgFracn9QFcAf5GO8B/mweUjSoblS5In0cWhqpfs/5PQA==", + "dev": true + }, + "node_modules/typedarray-to-buffer": { + "version": "3.1.5", + "resolved": "https://registry.npmjs.org/typedarray-to-buffer/-/typedarray-to-buffer-3.1.5.tgz", + "integrity": "sha512-zdu8XMNEDepKKR+XYOXAVPtWui0ly0NtohUscw+UmaHiAWT8hrV1rr//H6V+0DvJ3OQ19S979M0laLfX8rm82Q==", + "dev": true, + "dependencies": { + "is-typedarray": "^1.0.0" + } + }, + "node_modules/uglify-js": { + "version": "3.17.4", + "resolved": "https://registry.npmjs.org/uglify-js/-/uglify-js-3.17.4.tgz", + "integrity": "sha512-T9q82TJI9e/C1TAxYvfb16xO120tMVFZrGA3f9/P4424DNu6ypK103y0GPFVa17yotwSyZW5iYXgjYHkGrJW/g==", + "dev": true, + "optional": true, + "bin": { + "uglifyjs": "bin/uglifyjs" + }, + "engines": { + "node": ">=0.8.0" + } + }, + "node_modules/ultron": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/ultron/-/ultron-1.1.1.tgz", + "integrity": "sha512-UIEXBNeYmKptWH6z8ZnqTeS8fV74zG0/eRU9VGkpzz+LIJNs8W/zM/L+7ctCkRrgbNnnR0xxw4bKOr0cW0N0Og==", + "dev": true + }, + "node_modules/unbox-primitive": { + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/unbox-primitive/-/unbox-primitive-1.0.2.tgz", + "integrity": "sha512-61pPlCD9h51VoreyJ0BReideM3MDKMKnh6+V9L08331ipq6Q8OFXZYiqP6n/tbHx4s5I9uRhcye6BrbkizkBDw==", + "dev": true, + "dependencies": { + "call-bind": "^1.0.2", + "has-bigints": "^1.0.2", + "has-symbols": "^1.0.3", + "which-boxed-primitive": "^1.0.2" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/underscore": { + "version": "1.13.6", + "resolved": "https://registry.npmjs.org/underscore/-/underscore-1.13.6.tgz", + "integrity": "sha512-+A5Sja4HP1M08MaXya7p5LvjuM7K6q/2EaC0+iovj/wOcMsTzMvDFbasi/oSapiwOlt252IqsKqPjCl7huKS0A==", + "dev": true + }, + "node_modules/undici": { + "version": "5.22.1", + "resolved": "https://registry.npmjs.org/undici/-/undici-5.22.1.tgz", + "integrity": "sha512-Ji2IJhFXZY0x/0tVBXeQwgPlLWw13GVzpsWPQ3rV50IFMMof2I55PZZxtm4P6iNq+L5znYN9nSTAq0ZyE6lSJw==", + "dev": true, + "dependencies": { + "busboy": "^1.6.0" + }, + "engines": { + "node": ">=14.0" + } + }, + "node_modules/universalify": { + "version": "0.1.2", + "resolved": "https://registry.npmjs.org/universalify/-/universalify-0.1.2.tgz", + "integrity": "sha512-rBJeI5CXAlmy1pV+617WB9J63U6XcazHHF2f2dbJix4XzpUF0RS3Zbj0FGIOCAva5P/d/GBOYaACQ1w+0azUkg==", + "dev": true, + "engines": { + "node": ">= 4.0.0" + } + }, + "node_modules/unpipe": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/unpipe/-/unpipe-1.0.0.tgz", + "integrity": "sha512-pjy2bYhSsufwWlKwPc+l3cN7+wuJlK6uz0YdJEOlQDbl6jo/YlPi4mb8agUkVC8BF7V8NuzeyPNqRksA3hztKQ==", + "dev": true, + "engines": { + "node": ">= 0.8" + } + }, + "node_modules/upper-case": { + "version": "1.1.3", + "resolved": "https://registry.npmjs.org/upper-case/-/upper-case-1.1.3.tgz", + "integrity": "sha512-WRbjgmYzgXkCV7zNVpy5YgrHgbBv126rMALQQMrmzOVC4GM2waQ9x7xtm8VU+1yF2kWyPzI9zbZ48n4vSxwfSA==", + "dev": true + }, + "node_modules/upper-case-first": { + "version": "1.1.2", + "resolved": "https://registry.npmjs.org/upper-case-first/-/upper-case-first-1.1.2.tgz", + "integrity": "sha512-wINKYvI3Db8dtjikdAqoBbZoP6Q+PZUyfMR7pmwHzjC2quzSkUq5DmPrTtPEqHaz8AGtmsB4TqwapMTM1QAQOQ==", + "dev": true, + "dependencies": { + "upper-case": "^1.1.1" + } + }, + "node_modules/uri-js": { + "version": "4.4.1", + "resolved": "https://registry.npmjs.org/uri-js/-/uri-js-4.4.1.tgz", + "integrity": "sha512-7rKUyy33Q1yc98pQ1DAmLtwX109F7TIfWlW1Ydo8Wl1ii1SeHieeh0HHfPeL2fMXK6z0s8ecKs9frCuLJvndBg==", + "dev": true, + "dependencies": { + "punycode": "^2.1.0" + } + }, + "node_modules/url-set-query": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/url-set-query/-/url-set-query-1.0.0.tgz", + "integrity": "sha512-3AChu4NiXquPfeckE5R5cGdiHCMWJx1dwCWOmWIL4KHAziJNOFIYJlpGFeKDvwLPHovZRCxK3cYlwzqI9Vp+Gg==", + "dev": true + }, + "node_modules/utf-8-validate": { + "version": "5.0.10", + "resolved": "https://registry.npmjs.org/utf-8-validate/-/utf-8-validate-5.0.10.tgz", + "integrity": "sha512-Z6czzLq4u8fPOyx7TU6X3dvUZVvoJmxSQ+IcrlmagKhilxlhZgxPK6C5Jqbkw1IDUmFTM+cz9QDnnLTwDz/2gQ==", + "dev": true, + "hasInstallScript": true, + "dependencies": { + "node-gyp-build": "^4.3.0" + }, + "engines": { + "node": ">=6.14.2" + } + }, + "node_modules/utf8": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/utf8/-/utf8-3.0.0.tgz", + "integrity": "sha512-E8VjFIQ/TyQgp+TZfS6l8yp/xWppSAHzidGiRrqe4bK4XP9pTRyKFgGJpO3SN7zdX4DeomTrwaseCHovfpFcqQ==", + "dev": true + }, + "node_modules/util": { + "version": "0.12.5", + "resolved": "https://registry.npmjs.org/util/-/util-0.12.5.tgz", + "integrity": "sha512-kZf/K6hEIrWHI6XqOFUiiMa+79wE/D8Q+NCNAWclkyg3b4d2k7s0QGepNjiABc+aR3N1PAyHL7p6UcLY6LmrnA==", + "dev": true, + "dependencies": { + "inherits": "^2.0.3", + "is-arguments": "^1.0.4", + "is-generator-function": "^1.0.7", + "is-typed-array": "^1.1.3", + "which-typed-array": "^1.1.2" + } + }, + "node_modules/util-deprecate": { + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/util-deprecate/-/util-deprecate-1.0.2.tgz", + "integrity": "sha512-EPD5q1uXyFxJpCrLnCc1nHnq3gOa6DZBocAIiI2TaSCA7VCJ1UJDMagCzIkXNsUYfD1daK//LTEQ8xiIbrHtcw==", + "dev": true + }, + "node_modules/utils-merge": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/utils-merge/-/utils-merge-1.0.1.tgz", + "integrity": "sha512-pMZTvIkT1d+TFGvDOqodOclx0QWkkgi6Tdoa8gC8ffGAAqz9pzPTZWAybbsHHoED/ztMtkv/VoYTYyShUn81hA==", + "dev": true, + "engines": { + "node": ">= 0.4.0" + } + }, + "node_modules/uuid": { + "version": "8.3.2", + "resolved": "https://registry.npmjs.org/uuid/-/uuid-8.3.2.tgz", + "integrity": "sha512-+NYs2QeMWy+GWFOEm9xnn6HCDp0l7QBD7ml8zLUmJ+93Q5NF0NocErnwkTkXVFNiX3/fpC6afS8Dhb/gz7R7eg==", + "dev": true, + "bin": { + "uuid": "dist/bin/uuid" + } + }, + "node_modules/validate-npm-package-license": { + "version": "3.0.4", + "resolved": "https://registry.npmjs.org/validate-npm-package-license/-/validate-npm-package-license-3.0.4.tgz", + "integrity": "sha512-DpKm2Ui/xN7/HQKCtpZxoRWBhZ9Z0kqtygG8XCgNQ8ZlDnxuQmWhj566j8fN4Cu3/JmbhsDo7fcAJq4s9h27Ew==", + "dev": true, + "dependencies": { + "spdx-correct": "^3.0.0", + "spdx-expression-parse": "^3.0.0" + } + }, + "node_modules/varint": { + "version": "5.0.2", + "resolved": "https://registry.npmjs.org/varint/-/varint-5.0.2.tgz", + "integrity": "sha512-lKxKYG6H03yCZUpAGOPOsMcGxd1RHCu1iKvEHYDPmTyq2HueGhD73ssNBqqQWfvYs04G9iUFRvmAVLW20Jw6ow==", + "dev": true + }, + "node_modules/vary": { + "version": "1.1.2", + "resolved": "https://registry.npmjs.org/vary/-/vary-1.1.2.tgz", + "integrity": "sha512-BNGbWLfd0eUPabhkXUVm0j8uuvREyTh5ovRa/dyow/BqAbZJyC+5fU+IzQOzmAKzYqYRAISoRhdQr3eIZ/PXqg==", + "dev": true, + "engines": { + "node": ">= 0.8" + } + }, + "node_modules/verror": { + "version": "1.10.0", + "resolved": "https://registry.npmjs.org/verror/-/verror-1.10.0.tgz", + "integrity": "sha512-ZZKSmDAEFOijERBLkmYfJ+vmk3w+7hOLYDNkRCuRuMJGEmqYNCNLyBBFwWKVMhfwaEF3WOd0Zlw86U/WC/+nYw==", + "dev": true, + "engines": [ + "node >=0.6.0" + ], + "dependencies": { + "assert-plus": "^1.0.0", + "core-util-is": "1.0.2", + "extsprintf": "^1.2.0" + } + }, + "node_modules/wcwidth": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/wcwidth/-/wcwidth-1.0.1.tgz", + "integrity": "sha512-XHPEwS0q6TaxcvG85+8EYkbiCux2XtWG2mkc47Ng2A77BQu9+DqIOJldST4HgPkuea7dvKSj5VgX3P1d4rW8Tg==", + "dev": true, + "dependencies": { + "defaults": "^1.0.3" + } + }, + "node_modules/web3": { + "version": "1.10.0", + "resolved": "https://registry.npmjs.org/web3/-/web3-1.10.0.tgz", + "integrity": "sha512-YfKY9wSkGcM8seO+daR89oVTcbu18NsVfvOngzqMYGUU0pPSQmE57qQDvQzUeoIOHAnXEBNzrhjQJmm8ER0rng==", + "dev": true, + "hasInstallScript": true, + "dependencies": { + "web3-bzz": "1.10.0", + "web3-core": "1.10.0", + "web3-eth": "1.10.0", + "web3-eth-personal": "1.10.0", + "web3-net": "1.10.0", + "web3-shh": "1.10.0", + "web3-utils": "1.10.0" + }, + "engines": { + "node": ">=8.0.0" + } + }, + "node_modules/web3-bzz": { + "version": "1.10.0", + "resolved": "https://registry.npmjs.org/web3-bzz/-/web3-bzz-1.10.0.tgz", + "integrity": "sha512-o9IR59io3pDUsXTsps5pO5hW1D5zBmg46iNc2t4j2DkaYHNdDLwk2IP9ukoM2wg47QILfPEJYzhTfkS/CcX0KA==", + "dev": true, + "hasInstallScript": true, + "dependencies": { + "@types/node": "^12.12.6", + "got": "12.1.0", + "swarm-js": "^0.1.40" + }, + "engines": { + "node": ">=8.0.0" + } + }, + "node_modules/web3-core": { + "version": "1.10.0", + "resolved": "https://registry.npmjs.org/web3-core/-/web3-core-1.10.0.tgz", + "integrity": "sha512-fWySwqy2hn3TL89w5TM8wXF1Z2Q6frQTKHWmP0ppRQorEK8NcHJRfeMiv/mQlSKoTS1F6n/nv2uyZsixFycjYQ==", + "dev": true, + "dependencies": { + "@types/bn.js": "^5.1.1", + "@types/node": "^12.12.6", + "bignumber.js": "^9.0.0", + "web3-core-helpers": "1.10.0", + "web3-core-method": "1.10.0", + "web3-core-requestmanager": "1.10.0", + "web3-utils": "1.10.0" + }, + "engines": { + "node": ">=8.0.0" + } + }, + "node_modules/web3-core-helpers": { + "version": "1.10.0", + "resolved": "https://registry.npmjs.org/web3-core-helpers/-/web3-core-helpers-1.10.0.tgz", + "integrity": "sha512-pIxAzFDS5vnbXvfvLSpaA1tfRykAe9adw43YCKsEYQwH0gCLL0kMLkaCX3q+Q8EVmAh+e1jWL/nl9U0de1+++g==", + "dev": true, + "dependencies": { + "web3-eth-iban": "1.10.0", + "web3-utils": "1.10.0" + }, + "engines": { + "node": ">=8.0.0" + } + }, + "node_modules/web3-core-method": { + "version": "1.10.0", + "resolved": "https://registry.npmjs.org/web3-core-method/-/web3-core-method-1.10.0.tgz", + "integrity": "sha512-4R700jTLAMKDMhQ+nsVfIXvH6IGJlJzGisIfMKWAIswH31h5AZz7uDUW2YctI+HrYd+5uOAlS4OJeeT9bIpvkA==", + "dev": true, + "dependencies": { + "@ethersproject/transactions": "^5.6.2", + "web3-core-helpers": "1.10.0", + "web3-core-promievent": "1.10.0", + "web3-core-subscriptions": "1.10.0", + "web3-utils": "1.10.0" + }, + "engines": { + "node": ">=8.0.0" + } + }, + "node_modules/web3-core-promievent": { + "version": "1.10.0", + "resolved": "https://registry.npmjs.org/web3-core-promievent/-/web3-core-promievent-1.10.0.tgz", + "integrity": "sha512-68N7k5LWL5R38xRaKFrTFT2pm2jBNFaM4GioS00YjAKXRQ3KjmhijOMG3TICz6Aa5+6GDWYelDNx21YAeZ4YTg==", + "dev": true, + "dependencies": { + "eventemitter3": "4.0.4" + }, + "engines": { + "node": ">=8.0.0" + } + }, + "node_modules/web3-core-requestmanager": { + "version": "1.10.0", + "resolved": "https://registry.npmjs.org/web3-core-requestmanager/-/web3-core-requestmanager-1.10.0.tgz", + "integrity": "sha512-3z/JKE++Os62APml4dvBM+GAuId4h3L9ckUrj7ebEtS2AR0ixyQPbrBodgL91Sv7j7cQ3Y+hllaluqjguxvSaQ==", + "dev": true, + "dependencies": { + "util": "^0.12.5", + "web3-core-helpers": "1.10.0", + "web3-providers-http": "1.10.0", + "web3-providers-ipc": "1.10.0", + "web3-providers-ws": "1.10.0" + }, + "engines": { + "node": ">=8.0.0" + } + }, + "node_modules/web3-core-subscriptions": { + "version": "1.10.0", + "resolved": "https://registry.npmjs.org/web3-core-subscriptions/-/web3-core-subscriptions-1.10.0.tgz", + "integrity": "sha512-HGm1PbDqsxejI075gxBc5OSkwymilRWZufIy9zEpnWKNmfbuv5FfHgW1/chtJP6aP3Uq2vHkvTDl3smQBb8l+g==", + "dev": true, + "dependencies": { + "eventemitter3": "4.0.4", + "web3-core-helpers": "1.10.0" + }, + "engines": { + "node": ">=8.0.0" + } + }, + "node_modules/web3-core/node_modules/bignumber.js": { + "version": "9.1.1", + "resolved": "https://registry.npmjs.org/bignumber.js/-/bignumber.js-9.1.1.tgz", + "integrity": "sha512-pHm4LsMJ6lzgNGVfZHjMoO8sdoRhOzOH4MLmY65Jg70bpxCKu5iOHNJyfF6OyvYw7t8Fpf35RuzUyqnQsj8Vig==", + "dev": true, + "engines": { + "node": "*" + } + }, + "node_modules/web3-eth": { + "version": "1.10.0", + "resolved": "https://registry.npmjs.org/web3-eth/-/web3-eth-1.10.0.tgz", + "integrity": "sha512-Z5vT6slNMLPKuwRyKGbqeGYC87OAy8bOblaqRTgg94CXcn/mmqU7iPIlG4506YdcdK3x6cfEDG7B6w+jRxypKA==", + "dev": true, + "dependencies": { + "web3-core": "1.10.0", + "web3-core-helpers": "1.10.0", + "web3-core-method": "1.10.0", + "web3-core-subscriptions": "1.10.0", + "web3-eth-abi": "1.10.0", + "web3-eth-accounts": "1.10.0", + "web3-eth-contract": "1.10.0", + "web3-eth-ens": "1.10.0", + "web3-eth-iban": "1.10.0", + "web3-eth-personal": "1.10.0", + "web3-net": "1.10.0", + "web3-utils": "1.10.0" + }, + "engines": { + "node": ">=8.0.0" + } + }, + "node_modules/web3-eth-abi": { + "version": "1.10.0", + "resolved": "https://registry.npmjs.org/web3-eth-abi/-/web3-eth-abi-1.10.0.tgz", + "integrity": "sha512-cwS+qRBWpJ43aI9L3JS88QYPfFcSJJ3XapxOQ4j40v6mk7ATpA8CVK1vGTzpihNlOfMVRBkR95oAj7oL6aiDOg==", + "dev": true, + "dependencies": { + "@ethersproject/abi": "^5.6.3", + "web3-utils": "1.10.0" + }, + "engines": { + "node": ">=8.0.0" + } + }, + "node_modules/web3-eth-accounts": { + "version": "1.10.0", + "resolved": "https://registry.npmjs.org/web3-eth-accounts/-/web3-eth-accounts-1.10.0.tgz", + "integrity": "sha512-wiq39Uc3mOI8rw24wE2n15hboLE0E9BsQLdlmsL4Zua9diDS6B5abXG0XhFcoNsXIGMWXVZz4TOq3u4EdpXF/Q==", + "dev": true, + "dependencies": { + "@ethereumjs/common": "2.5.0", + "@ethereumjs/tx": "3.3.2", + "eth-lib": "0.2.8", + "ethereumjs-util": "^7.1.5", + "scrypt-js": "^3.0.1", + "uuid": "^9.0.0", + "web3-core": "1.10.0", + "web3-core-helpers": "1.10.0", + "web3-core-method": "1.10.0", + "web3-utils": "1.10.0" + }, + "engines": { + "node": ">=8.0.0" + } + }, + "node_modules/web3-eth-accounts/node_modules/eth-lib": { + "version": "0.2.8", + "resolved": "https://registry.npmjs.org/eth-lib/-/eth-lib-0.2.8.tgz", + "integrity": "sha512-ArJ7x1WcWOlSpzdoTBX8vkwlkSQ85CjjifSZtV4co64vWxSV8geWfPI9x4SVYu3DSxnX4yWFVTtGL+j9DUFLNw==", + "dev": true, + "dependencies": { + "bn.js": "^4.11.6", + "elliptic": "^6.4.0", + "xhr-request-promise": "^0.1.2" + } + }, + "node_modules/web3-eth-accounts/node_modules/uuid": { + "version": "9.0.0", + "resolved": "https://registry.npmjs.org/uuid/-/uuid-9.0.0.tgz", + "integrity": "sha512-MXcSTerfPa4uqyzStbRoTgt5XIe3x5+42+q1sDuy3R5MDk66URdLMOZe5aPX/SQd+kuYAh0FdP/pO28IkQyTeg==", + "dev": true, + "bin": { + "uuid": "dist/bin/uuid" + } + }, + "node_modules/web3-eth-contract": { + "version": "1.10.0", + "resolved": "https://registry.npmjs.org/web3-eth-contract/-/web3-eth-contract-1.10.0.tgz", + "integrity": "sha512-MIC5FOzP/+2evDksQQ/dpcXhSqa/2hFNytdl/x61IeWxhh6vlFeSjq0YVTAyIzdjwnL7nEmZpjfI6y6/Ufhy7w==", + "dev": true, + "dependencies": { + "@types/bn.js": "^5.1.1", + "web3-core": "1.10.0", + "web3-core-helpers": "1.10.0", + "web3-core-method": "1.10.0", + "web3-core-promievent": "1.10.0", + "web3-core-subscriptions": "1.10.0", + "web3-eth-abi": "1.10.0", + "web3-utils": "1.10.0" + }, + "engines": { + "node": ">=8.0.0" + } + }, + "node_modules/web3-eth-ens": { + "version": "1.10.0", + "resolved": "https://registry.npmjs.org/web3-eth-ens/-/web3-eth-ens-1.10.0.tgz", + "integrity": "sha512-3hpGgzX3qjgxNAmqdrC2YUQMTfnZbs4GeLEmy8aCWziVwogbuqQZ+Gzdfrym45eOZodk+lmXyLuAdqkNlvkc1g==", + "dev": true, + "dependencies": { + "content-hash": "^2.5.2", + "eth-ens-namehash": "2.0.8", + "web3-core": "1.10.0", + "web3-core-helpers": "1.10.0", + "web3-core-promievent": "1.10.0", + "web3-eth-abi": "1.10.0", + "web3-eth-contract": "1.10.0", + "web3-utils": "1.10.0" + }, + "engines": { + "node": ">=8.0.0" + } + }, + "node_modules/web3-eth-iban": { + "version": "1.10.0", + "resolved": "https://registry.npmjs.org/web3-eth-iban/-/web3-eth-iban-1.10.0.tgz", + "integrity": "sha512-0l+SP3IGhInw7Q20LY3IVafYEuufo4Dn75jAHT7c2aDJsIolvf2Lc6ugHkBajlwUneGfbRQs/ccYPQ9JeMUbrg==", + "dev": true, + "dependencies": { + "bn.js": "^5.2.1", + "web3-utils": "1.10.0" + }, + "engines": { + "node": ">=8.0.0" + } + }, + "node_modules/web3-eth-iban/node_modules/bn.js": { + "version": "5.2.1", + "resolved": "https://registry.npmjs.org/bn.js/-/bn.js-5.2.1.tgz", + "integrity": "sha512-eXRvHzWyYPBuB4NBy0cmYQjGitUrtqwbvlzP3G6VFnNRbsZQIxQ10PbKKHt8gZ/HW/D/747aDl+QkDqg3KQLMQ==", + "dev": true + }, + "node_modules/web3-eth-personal": { + "version": "1.10.0", + "resolved": "https://registry.npmjs.org/web3-eth-personal/-/web3-eth-personal-1.10.0.tgz", + "integrity": "sha512-anseKn98w/d703eWq52uNuZi7GhQeVjTC5/svrBWEKob0WZ5kPdo+EZoFN0sp5a5ubbrk/E0xSl1/M5yORMtpg==", + "dev": true, + "dependencies": { + "@types/node": "^12.12.6", + "web3-core": "1.10.0", + "web3-core-helpers": "1.10.0", + "web3-core-method": "1.10.0", + "web3-net": "1.10.0", + "web3-utils": "1.10.0" + }, + "engines": { + "node": ">=8.0.0" + } + }, + "node_modules/web3-net": { + "version": "1.10.0", + "resolved": "https://registry.npmjs.org/web3-net/-/web3-net-1.10.0.tgz", + "integrity": "sha512-NLH/N3IshYWASpxk4/18Ge6n60GEvWBVeM8inx2dmZJVmRI6SJIlUxbL8jySgiTn3MMZlhbdvrGo8fpUW7a1GA==", + "dev": true, + "dependencies": { + "web3-core": "1.10.0", + "web3-core-method": "1.10.0", + "web3-utils": "1.10.0" + }, + "engines": { + "node": ">=8.0.0" + } + }, + "node_modules/web3-providers-http": { + "version": "1.10.0", + "resolved": "https://registry.npmjs.org/web3-providers-http/-/web3-providers-http-1.10.0.tgz", + "integrity": "sha512-eNr965YB8a9mLiNrkjAWNAPXgmQWfpBfkkn7tpEFlghfww0u3I0tktMZiaToJVcL2+Xq+81cxbkpeWJ5XQDwOA==", + "dev": true, + "dependencies": { + "abortcontroller-polyfill": "^1.7.3", + "cross-fetch": "^3.1.4", + "es6-promise": "^4.2.8", + "web3-core-helpers": "1.10.0" + }, + "engines": { + "node": ">=8.0.0" + } + }, + "node_modules/web3-providers-ipc": { + "version": "1.10.0", + "resolved": "https://registry.npmjs.org/web3-providers-ipc/-/web3-providers-ipc-1.10.0.tgz", + "integrity": "sha512-OfXG1aWN8L1OUqppshzq8YISkWrYHaATW9H8eh0p89TlWMc1KZOL9vttBuaBEi96D/n0eYDn2trzt22bqHWfXA==", + "dev": true, + "dependencies": { + "oboe": "2.1.5", + "web3-core-helpers": "1.10.0" + }, + "engines": { + "node": ">=8.0.0" + } + }, + "node_modules/web3-providers-ws": { + "version": "1.10.0", + "resolved": "https://registry.npmjs.org/web3-providers-ws/-/web3-providers-ws-1.10.0.tgz", + "integrity": "sha512-sK0fNcglW36yD5xjnjtSGBnEtf59cbw4vZzJ+CmOWIKGIR96mP5l684g0WD0Eo+f4NQc2anWWXG74lRc9OVMCQ==", + "dev": true, + "dependencies": { + "eventemitter3": "4.0.4", + "web3-core-helpers": "1.10.0", + "websocket": "^1.0.32" + }, + "engines": { + "node": ">=8.0.0" + } + }, + "node_modules/web3-shh": { + "version": "1.10.0", + "resolved": "https://registry.npmjs.org/web3-shh/-/web3-shh-1.10.0.tgz", + "integrity": "sha512-uNUUuNsO2AjX41GJARV9zJibs11eq6HtOe6Wr0FtRUcj8SN6nHeYIzwstAvJ4fXA53gRqFMTxdntHEt9aXVjpg==", + "dev": true, + "hasInstallScript": true, + "dependencies": { + "web3-core": "1.10.0", + "web3-core-method": "1.10.0", + "web3-core-subscriptions": "1.10.0", + "web3-net": "1.10.0" + }, + "engines": { + "node": ">=8.0.0" + } + }, + "node_modules/web3-utils": { + "version": "1.10.0", + "resolved": "https://registry.npmjs.org/web3-utils/-/web3-utils-1.10.0.tgz", + "integrity": "sha512-kSaCM0uMcZTNUSmn5vMEhlo02RObGNRRCkdX0V9UTAU0+lrvn0HSaudyCo6CQzuXUsnuY2ERJGCGPfeWmv19Rg==", + "dev": true, + "dependencies": { + "bn.js": "^5.2.1", + "ethereum-bloom-filters": "^1.0.6", + "ethereumjs-util": "^7.1.0", + "ethjs-unit": "0.1.6", + "number-to-bn": "1.7.0", + "randombytes": "^2.1.0", + "utf8": "3.0.0" + }, + "engines": { + "node": ">=8.0.0" + } + }, + "node_modules/web3-utils/node_modules/bn.js": { + "version": "5.2.1", + "resolved": "https://registry.npmjs.org/bn.js/-/bn.js-5.2.1.tgz", + "integrity": "sha512-eXRvHzWyYPBuB4NBy0cmYQjGitUrtqwbvlzP3G6VFnNRbsZQIxQ10PbKKHt8gZ/HW/D/747aDl+QkDqg3KQLMQ==", + "dev": true + }, + "node_modules/webidl-conversions": { + "version": "3.0.1", + "resolved": "https://registry.npmjs.org/webidl-conversions/-/webidl-conversions-3.0.1.tgz", + "integrity": "sha512-2JAn3z8AR6rjK8Sm8orRC0h/bcl/DqL7tRPdGZ4I1CjdF+EaMLmYxBHyXuKL849eucPFhvBoxMsflfOb8kxaeQ==", + "dev": true + }, + "node_modules/websocket": { + "version": "1.0.34", + "resolved": "https://registry.npmjs.org/websocket/-/websocket-1.0.34.tgz", + "integrity": "sha512-PRDso2sGwF6kM75QykIesBijKSVceR6jL2G8NGYyq2XrItNC2P5/qL5XeR056GhA+Ly7JMFvJb9I312mJfmqnQ==", + "dev": true, + "dependencies": { + "bufferutil": "^4.0.1", + "debug": "^2.2.0", + "es5-ext": "^0.10.50", + "typedarray-to-buffer": "^3.1.5", + "utf-8-validate": "^5.0.2", + "yaeti": "^0.0.6" + }, + "engines": { + "node": ">=4.0.0" + } + }, + "node_modules/websocket/node_modules/debug": { + "version": "2.6.9", + "resolved": "https://registry.npmjs.org/debug/-/debug-2.6.9.tgz", + "integrity": "sha512-bC7ElrdJaJnPbAP+1EotYvqZsb3ecl5wi6Bfi6BJTUcNowp6cvspg0jXznRTKDjm/E7AdgFBVeAPVMNcKGsHMA==", + "dev": true, + "dependencies": { + "ms": "2.0.0" + } + }, + "node_modules/websocket/node_modules/ms": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/ms/-/ms-2.0.0.tgz", + "integrity": "sha512-Tpp60P6IUJDTuOq/5Z8cdskzJujfwqfOTkrwIwj7IRISpnkJnT6SyJ4PCPnGMoFjC9ddhal5KVIYtAt97ix05A==", + "dev": true + }, + "node_modules/whatwg-url": { + "version": "5.0.0", + "resolved": "https://registry.npmjs.org/whatwg-url/-/whatwg-url-5.0.0.tgz", + "integrity": "sha512-saE57nupxk6v3HY35+jzBwYa0rKSy0XR8JSxZPwgLr7ys0IBzhGviA1/TUGJLmSVqs8pb9AnvICXEuOHLprYTw==", + "dev": true, + "dependencies": { + "tr46": "~0.0.3", + "webidl-conversions": "^3.0.0" + } + }, + "node_modules/which": { + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/which/-/which-2.0.2.tgz", + "integrity": "sha512-BLI3Tl1TW3Pvl70l3yq3Y64i+awpwXqsGBYWkkqMtnbXgrMD+yj7rhW0kuEDxzJaYXGjEW5ogapKNMEKNMjibA==", + "dev": true, + "dependencies": { + "isexe": "^2.0.0" + }, + "bin": { + "node-which": "bin/node-which" + }, + "engines": { + "node": ">= 8" + } + }, + "node_modules/which-boxed-primitive": { + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/which-boxed-primitive/-/which-boxed-primitive-1.0.2.tgz", + "integrity": "sha512-bwZdv0AKLpplFY2KZRX6TvyuN7ojjr7lwkg6ml0roIy9YeuSr7JS372qlNW18UQYzgYK9ziGcerWqZOmEn9VNg==", + "dev": true, + "dependencies": { + "is-bigint": "^1.0.1", + "is-boolean-object": "^1.1.0", + "is-number-object": "^1.0.4", + "is-string": "^1.0.5", + "is-symbol": "^1.0.3" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/which-module": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/which-module/-/which-module-2.0.1.tgz", + "integrity": "sha512-iBdZ57RDvnOR9AGBhML2vFZf7h8vmBjhoaZqODJBFWHVtKkDmKuHai3cx5PgVMrX5YDNp27AofYbAwctSS+vhQ==", + "dev": true + }, + "node_modules/which-pm": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/which-pm/-/which-pm-2.0.0.tgz", + "integrity": "sha512-Lhs9Pmyph0p5n5Z3mVnN0yWcbQYUAD7rbQUiMsQxOJ3T57k7RFe35SUwWMf7dsbDZks1uOmw4AecB/JMDj3v/w==", + "dev": true, + "dependencies": { + "load-yaml-file": "^0.2.0", + "path-exists": "^4.0.0" + }, + "engines": { + "node": ">=8.15" + } + }, + "node_modules/which-typed-array": { + "version": "1.1.9", + "resolved": "https://registry.npmjs.org/which-typed-array/-/which-typed-array-1.1.9.tgz", + "integrity": "sha512-w9c4xkx6mPidwp7180ckYWfMmvxpjlZuIudNtDf4N/tTAUB8VJbX25qZoAsrtGuYNnGw3pa0AXgbGKRB8/EceA==", + "dev": true, + "dependencies": { + "available-typed-arrays": "^1.0.5", + "call-bind": "^1.0.2", + "for-each": "^0.3.3", + "gopd": "^1.0.1", + "has-tostringtag": "^1.0.0", + "is-typed-array": "^1.1.10" + }, + "engines": { + "node": ">= 0.4" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/wide-align": { + "version": "1.1.3", + "resolved": "https://registry.npmjs.org/wide-align/-/wide-align-1.1.3.tgz", + "integrity": "sha512-QGkOQc8XL6Bt5PwnsExKBPuMKBxnGxWWW3fU55Xt4feHozMUhdUMaBCk290qpm/wG5u/RSKzwdAC4i51YigihA==", + "dev": true, + "dependencies": { + "string-width": "^1.0.2 || 2" + } + }, + "node_modules/window-size": { + "version": "0.2.0", + "resolved": "https://registry.npmjs.org/window-size/-/window-size-0.2.0.tgz", + "integrity": "sha512-UD7d8HFA2+PZsbKyaOCEy8gMh1oDtHgJh1LfgjQ4zVXmYjAT/kvz3PueITKuqDiIXQe7yzpPnxX3lNc+AhQMyw==", + "dev": true, + "bin": { + "window-size": "cli.js" + }, + "engines": { + "node": ">= 0.10.0" + } + }, + "node_modules/word-wrap": { + "version": "1.2.4", + "resolved": "https://registry.npmjs.org/word-wrap/-/word-wrap-1.2.4.tgz", + "integrity": "sha512-2V81OA4ugVo5pRo46hAoD2ivUJx8jXmWXfUkY4KFNw0hEptvN0QfH3K4nHiwzGeKl5rFKedV48QVoqYavy4YpA==", + "dev": true, + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/wordwrap": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/wordwrap/-/wordwrap-1.0.0.tgz", + "integrity": "sha512-gvVzJFlPycKc5dZN4yPkP8w7Dc37BtP1yczEneOb4uq34pXZcvrtRTmWV8W+Ume+XCxKgbjM+nevkyFPMybd4Q==", + "dev": true + }, + "node_modules/workerpool": { + "version": "6.2.1", + "resolved": "https://registry.npmjs.org/workerpool/-/workerpool-6.2.1.tgz", + "integrity": "sha512-ILEIE97kDZvF9Wb9f6h5aXK4swSlKGUcOEGiIYb2OOu/IrDU9iwj0fD//SsA6E5ibwJxpEvhullJY4Sl4GcpAw==", + "dev": true + }, + "node_modules/wrap-ansi": { + "version": "7.0.0", + "resolved": "https://registry.npmjs.org/wrap-ansi/-/wrap-ansi-7.0.0.tgz", + "integrity": "sha512-YVGIj2kamLSTxw6NsZjoBxfSwsn0ycdesmc4p+Q21c5zPuZ1pl+NfxVdxPtdHvmNVOQ6XSYG4AUtyt/Fi7D16Q==", + "dev": true, + "dependencies": { + "ansi-styles": "^4.0.0", + "string-width": "^4.1.0", + "strip-ansi": "^6.0.0" + }, + "engines": { + "node": ">=10" + }, + "funding": { + "url": "https://github.com/chalk/wrap-ansi?sponsor=1" + } + }, + "node_modules/wrap-ansi/node_modules/ansi-regex": { + "version": "5.0.1", + "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-5.0.1.tgz", + "integrity": "sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ==", + "dev": true, + "engines": { + "node": ">=8" + } + }, + "node_modules/wrap-ansi/node_modules/ansi-styles": { + "version": "4.3.0", + "resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-4.3.0.tgz", + "integrity": "sha512-zbB9rCJAT1rbjiVDb2hqKFHNYLxgtk8NURxZ3IZwD3F6NtxbXZQCnnSi1Lkx+IDohdPlFp222wVALIheZJQSEg==", + "dev": true, + "dependencies": { + "color-convert": "^2.0.1" + }, + "engines": { + "node": ">=8" + }, + "funding": { + "url": "https://github.com/chalk/ansi-styles?sponsor=1" + } + }, + "node_modules/wrap-ansi/node_modules/color-convert": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/color-convert/-/color-convert-2.0.1.tgz", + "integrity": "sha512-RRECPsj7iu/xb5oKYcsFHSppFNnsj/52OVTRKb4zP5onXwVF3zVmmToNcOfGC+CRDpfK/U584fMg38ZHCaElKQ==", + "dev": true, + "dependencies": { + "color-name": "~1.1.4" + }, + "engines": { + "node": ">=7.0.0" + } + }, + "node_modules/wrap-ansi/node_modules/color-name": { + "version": "1.1.4", + "resolved": "https://registry.npmjs.org/color-name/-/color-name-1.1.4.tgz", + "integrity": "sha512-dOy+3AuW3a2wNbZHIuMZpTcgjGuLU/uBL/ubcZF9OXbDo8ff4O8yVp5Bf0efS8uEoYo5q4Fx7dY9OgQGXgAsQA==", + "dev": true + }, + "node_modules/wrap-ansi/node_modules/is-fullwidth-code-point": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/is-fullwidth-code-point/-/is-fullwidth-code-point-3.0.0.tgz", + "integrity": "sha512-zymm5+u+sCsSWyD9qNaejV3DFvhCKclKdizYaJUuHA83RLjb7nSuGnddCHGv0hk+KY7BMAlsWeK4Ueg6EV6XQg==", + "dev": true, + "engines": { + "node": ">=8" + } + }, + "node_modules/wrap-ansi/node_modules/string-width": { + "version": "4.2.3", + "resolved": "https://registry.npmjs.org/string-width/-/string-width-4.2.3.tgz", + "integrity": "sha512-wKyQRQpjJ0sIp62ErSZdGsjMJWsap5oRNihHhu6G7JVO/9jIB6UyevL+tXuOqrng8j/cxKTWyWUwvSTriiZz/g==", + "dev": true, + "dependencies": { + "emoji-regex": "^8.0.0", + "is-fullwidth-code-point": "^3.0.0", + "strip-ansi": "^6.0.1" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/wrap-ansi/node_modules/strip-ansi": { + "version": "6.0.1", + "resolved": "https://registry.npmjs.org/strip-ansi/-/strip-ansi-6.0.1.tgz", + "integrity": "sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A==", + "dev": true, + "dependencies": { + "ansi-regex": "^5.0.1" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/wrappy": { + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/wrappy/-/wrappy-1.0.2.tgz", + "integrity": "sha512-l4Sp/DRseor9wL6EvV2+TuQn63dMkPjZ/sp9XkghTEbV9KlPS1xUsZ3u7/IQO4wxtcFB4bgpQPRcR3QCvezPcQ==", + "dev": true + }, + "node_modules/ws": { + "version": "7.5.9", + "resolved": "https://registry.npmjs.org/ws/-/ws-7.5.9.tgz", + "integrity": "sha512-F+P9Jil7UiSKSkppIiD94dN07AwvFixvLIj1Og1Rl9GGMuNipJnV9JzjD6XuqmAeiswGvUmNLjr5cFuXwNS77Q==", + "dev": true, + "engines": { + "node": ">=8.3.0" + }, + "peerDependencies": { + "bufferutil": "^4.0.1", + "utf-8-validate": "^5.0.2" + }, + "peerDependenciesMeta": { + "bufferutil": { + "optional": true + }, + "utf-8-validate": { + "optional": true + } + } + }, + "node_modules/xhr": { + "version": "2.6.0", + "resolved": "https://registry.npmjs.org/xhr/-/xhr-2.6.0.tgz", + "integrity": "sha512-/eCGLb5rxjx5e3mF1A7s+pLlR6CGyqWN91fv1JgER5mVWg1MZmlhBvy9kjcsOdRk8RrIujotWyJamfyrp+WIcA==", + "dev": true, + "dependencies": { + "global": "~4.4.0", + "is-function": "^1.0.1", + "parse-headers": "^2.0.0", + "xtend": "^4.0.0" + } + }, + "node_modules/xhr-request": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/xhr-request/-/xhr-request-1.1.0.tgz", + "integrity": "sha512-Y7qzEaR3FDtL3fP30k9wO/e+FBnBByZeybKOhASsGP30NIkRAAkKD/sCnLvgEfAIEC1rcmK7YG8f4oEnIrrWzA==", + "dev": true, + "dependencies": { + "buffer-to-arraybuffer": "^0.0.5", + "object-assign": "^4.1.1", + "query-string": "^5.0.1", + "simple-get": "^2.7.0", + "timed-out": "^4.0.1", + "url-set-query": "^1.0.0", + "xhr": "^2.0.4" + } + }, + "node_modules/xhr-request-promise": { + "version": "0.1.3", + "resolved": "https://registry.npmjs.org/xhr-request-promise/-/xhr-request-promise-0.1.3.tgz", + "integrity": "sha512-YUBytBsuwgitWtdRzXDDkWAXzhdGB8bYm0sSzMPZT7Z2MBjMSTHFsyCT1yCRATY+XC69DUrQraRAEgcoCRaIPg==", + "dev": true, + "dependencies": { + "xhr-request": "^1.1.0" + } + }, + "node_modules/xmlhttprequest": { + "version": "1.8.0", + "resolved": "https://registry.npmjs.org/xmlhttprequest/-/xmlhttprequest-1.8.0.tgz", + "integrity": "sha512-58Im/U0mlVBLM38NdZjHyhuMtCqa61469k2YP/AaPbvCoV9aQGUpbJBj1QRm2ytRiVQBD/fsw7L2bJGDVQswBA==", + "dev": true, + "engines": { + "node": ">=0.4.0" + } + }, + "node_modules/xtend": { + "version": "4.0.2", + "resolved": "https://registry.npmjs.org/xtend/-/xtend-4.0.2.tgz", + "integrity": "sha512-LKYU1iAXJXUgAXn9URjiu+MWhyUXHsvfp7mcuYm9dSUKK0/CjtrUwFAxD82/mCWbtLsGjFIad0wIsod4zrTAEQ==", + "dev": true, + "engines": { + "node": ">=0.4" + } + }, + "node_modules/y18n": { + "version": "5.0.8", + "resolved": "https://registry.npmjs.org/y18n/-/y18n-5.0.8.tgz", + "integrity": "sha512-0pfFzegeDWJHJIAmTLRP2DwHjdF5s7jo9tuztdQxAhINCdvS+3nGINqPd00AphqJR/0LhANUS6/+7SCb98YOfA==", + "dev": true, + "engines": { + "node": ">=10" + } + }, + "node_modules/yaeti": { + "version": "0.0.6", + "resolved": "https://registry.npmjs.org/yaeti/-/yaeti-0.0.6.tgz", + "integrity": "sha512-MvQa//+KcZCUkBTIC9blM+CU9J2GzuTytsOUwf2lidtvkx/6gnEp1QvJv34t9vdjhFmha/mUiNDbN0D0mJWdug==", + "dev": true, + "engines": { + "node": ">=0.10.32" + } + }, + "node_modules/yallist": { + "version": "3.1.1", + "resolved": "https://registry.npmjs.org/yallist/-/yallist-3.1.1.tgz", + "integrity": "sha512-a4UGQaWPH59mOXUYnAG2ewncQS4i4F43Tv3JoAM+s2VDAmS9NsK8GpDMLrCHPksFT7h3K6TOoUNn2pb7RoXx4g==", + "dev": true + }, + "node_modules/yargs": { + "version": "17.7.2", + "resolved": "https://registry.npmjs.org/yargs/-/yargs-17.7.2.tgz", + "integrity": "sha512-7dSzzRQ++CKnNI/krKnYRV7JKKPUXMEh61soaHKg9mrWEhzFWhFnxPxGl+69cD1Ou63C13NUPCnmIcrvqCuM6w==", + "dev": true, + "dependencies": { + "cliui": "^8.0.1", + "escalade": "^3.1.1", + "get-caller-file": "^2.0.5", + "require-directory": "^2.1.1", + "string-width": "^4.2.3", + "y18n": "^5.0.5", + "yargs-parser": "^21.1.1" + }, + "engines": { + "node": ">=12" + } + }, + "node_modules/yargs-parser": { + "version": "18.1.3", + "resolved": "https://registry.npmjs.org/yargs-parser/-/yargs-parser-18.1.3.tgz", + "integrity": "sha512-o50j0JeToy/4K6OZcaQmW6lyXXKhq7csREXcDwk2omFPJEwUNOVtJKvmDr9EI1fAJZUyZcRF7kxGBWmRXudrCQ==", + "dev": true, + "dependencies": { + "camelcase": "^5.0.0", + "decamelize": "^1.2.0" + }, + "engines": { + "node": ">=6" + } + }, + "node_modules/yargs-parser/node_modules/camelcase": { + "version": "5.3.1", + "resolved": "https://registry.npmjs.org/camelcase/-/camelcase-5.3.1.tgz", + "integrity": "sha512-L28STB170nwWS63UjtlEOE3dldQApaJXZkOI1uMFfzf3rRuPegHaHesyee+YxQ+W6SvRDQV6UrdOdRiR153wJg==", + "dev": true, + "engines": { + "node": ">=6" + } + }, + "node_modules/yargs-unparser": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/yargs-unparser/-/yargs-unparser-2.0.0.tgz", + "integrity": "sha512-7pRTIA9Qc1caZ0bZ6RYRGbHJthJWuakf+WmHK0rVeLkNrrGhfoabBNdue6kdINI6r4if7ocq9aD/n7xwKOdzOA==", + "dev": true, + "dependencies": { + "camelcase": "^6.0.0", + "decamelize": "^4.0.0", + "flat": "^5.0.2", + "is-plain-obj": "^2.1.0" + }, + "engines": { + "node": ">=10" + } + }, + "node_modules/yargs-unparser/node_modules/camelcase": { + "version": "6.3.0", + "resolved": "https://registry.npmjs.org/camelcase/-/camelcase-6.3.0.tgz", + "integrity": "sha512-Gmy6FhYlCY7uOElZUSbxo2UCDH8owEk996gkbrpsgGtrJLM3J7jGxl9Ic7Qwwj4ivOE5AWZWRMecDdF7hqGjFA==", + "dev": true, + "engines": { + "node": ">=10" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/yargs-unparser/node_modules/decamelize": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/decamelize/-/decamelize-4.0.0.tgz", + "integrity": "sha512-9iE1PgSik9HeIIw2JO94IidnE3eBoQrFJ3w7sFuzSX4DpmZ3v5sZpUiV5Swcf6mQEF+Y0ru8Neo+p+nyh2J+hQ==", + "dev": true, + "engines": { + "node": ">=10" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/yargs-unparser/node_modules/is-plain-obj": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/is-plain-obj/-/is-plain-obj-2.1.0.tgz", + "integrity": "sha512-YWnfyRwxL/+SsrWYfOpUtz5b3YD+nyfkHvjbcanzk8zgyO4ASD67uVMRt8k5bM4lLMDnXfriRhOpemw+NfT1eA==", + "dev": true, + "engines": { + "node": ">=8" + } + }, + "node_modules/yargs/node_modules/ansi-regex": { + "version": "5.0.1", + "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-5.0.1.tgz", + "integrity": "sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ==", + "dev": true, + "engines": { + "node": ">=8" + } + }, + "node_modules/yargs/node_modules/is-fullwidth-code-point": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/is-fullwidth-code-point/-/is-fullwidth-code-point-3.0.0.tgz", + "integrity": "sha512-zymm5+u+sCsSWyD9qNaejV3DFvhCKclKdizYaJUuHA83RLjb7nSuGnddCHGv0hk+KY7BMAlsWeK4Ueg6EV6XQg==", + "dev": true, + "engines": { + "node": ">=8" + } + }, + "node_modules/yargs/node_modules/string-width": { + "version": "4.2.3", + "resolved": "https://registry.npmjs.org/string-width/-/string-width-4.2.3.tgz", + "integrity": "sha512-wKyQRQpjJ0sIp62ErSZdGsjMJWsap5oRNihHhu6G7JVO/9jIB6UyevL+tXuOqrng8j/cxKTWyWUwvSTriiZz/g==", + "dev": true, + "dependencies": { + "emoji-regex": "^8.0.0", + "is-fullwidth-code-point": "^3.0.0", + "strip-ansi": "^6.0.1" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/yargs/node_modules/strip-ansi": { + "version": "6.0.1", + "resolved": "https://registry.npmjs.org/strip-ansi/-/strip-ansi-6.0.1.tgz", + "integrity": "sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A==", + "dev": true, + "dependencies": { + "ansi-regex": "^5.0.1" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/yargs/node_modules/yargs-parser": { + "version": "21.1.1", + "resolved": "https://registry.npmjs.org/yargs-parser/-/yargs-parser-21.1.1.tgz", + "integrity": "sha512-tVpsJW7DdjecAiFpbIB1e3qxIQsE6NoPc5/eTdrbbIC4h0LVsWhnoa3g+m2HclBIujHzsxZ4VJVA+GUuc2/LBw==", + "dev": true, + "engines": { + "node": ">=12" + } + }, + "node_modules/yocto-queue": { + "version": "0.1.0", + "resolved": "https://registry.npmjs.org/yocto-queue/-/yocto-queue-0.1.0.tgz", + "integrity": "sha512-rVksvsnNCdJ/ohGc6xgPwyN8eheCxsiLM8mxuE/t/mOVqJewPuO1miLpTHQiRgTKCLexL4MeAFVagts7HmNZ2Q==", + "dev": true, + "engines": { + "node": ">=10" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "scripts/lints": { + "version": "1.0.2", + "extraneous": true, + "license": "MIT" + }, + "scripts/solhint-custom": { + "name": "solhint-plugin-openzeppelin", + "dev": true + } + }, + "dependencies": { + "@aashutoshrathi/word-wrap": { + "version": "1.2.6", + "resolved": "https://registry.npmjs.org/@aashutoshrathi/word-wrap/-/word-wrap-1.2.6.tgz", + "integrity": "sha512-1Yjs2SvM8TflER/OD3cOjhWWOZb58A2t7wpE2S9XfBYTiIl+XFhQG2bjy4Pu1I+EAlCNUzRDYDdFwFYUKvXcIA==", + "dev": true + }, + "@babel/code-frame": { + "version": "7.22.5", + "resolved": "https://registry.npmjs.org/@babel/code-frame/-/code-frame-7.22.5.tgz", + "integrity": "sha512-Xmwn266vad+6DAqEB2A6V/CcZVp62BbwVmcOJc2RPuwih1kw02TjQvWVWlcKGbBPd+8/0V5DEkOcizRGYsspYQ==", + "dev": true, + "requires": { + "@babel/highlight": "^7.22.5" + } + }, + "@babel/helper-validator-identifier": { + "version": "7.22.5", + "resolved": "https://registry.npmjs.org/@babel/helper-validator-identifier/-/helper-validator-identifier-7.22.5.tgz", + "integrity": "sha512-aJXu+6lErq8ltp+JhkJUfk1MTGyuA4v7f3pA+BJ5HLfNC6nAQ0Cpi9uOquUj8Hehg0aUiHzWQbOVJGao6ztBAQ==", + "dev": true + }, + "@babel/highlight": { + "version": "7.22.5", + "resolved": "https://registry.npmjs.org/@babel/highlight/-/highlight-7.22.5.tgz", + "integrity": "sha512-BSKlD1hgnedS5XRnGOljZawtag7H1yPfQp0tdNJCHoH6AZ+Pcm9VvkrK59/Yy593Ypg0zMxH2BxD1VPYUQ7UIw==", + "dev": true, + "requires": { + "@babel/helper-validator-identifier": "^7.22.5", + "chalk": "^2.0.0", + "js-tokens": "^4.0.0" + } + }, + "@babel/runtime": { + "version": "7.22.6", + "resolved": "https://registry.npmjs.org/@babel/runtime/-/runtime-7.22.6.tgz", + "integrity": "sha512-wDb5pWm4WDdF6LFUde3Jl8WzPA+3ZbxYqkC6xAXuD3irdEHN1k0NfTRrJD8ZD378SJ61miMLCqIOXYhd8x+AJQ==", + "dev": true, + "requires": { + "regenerator-runtime": "^0.13.11" + } + }, + "@chainsafe/as-sha256": { + "version": "0.3.1", + "resolved": "https://registry.npmjs.org/@chainsafe/as-sha256/-/as-sha256-0.3.1.tgz", + "integrity": "sha512-hldFFYuf49ed7DAakWVXSJODuq3pzJEguD8tQ7h+sGkM18vja+OFoJI9krnGmgzyuZC2ETX0NOIcCTy31v2Mtg==", + "dev": true + }, + "@chainsafe/persistent-merkle-tree": { + "version": "0.4.2", + "resolved": "https://registry.npmjs.org/@chainsafe/persistent-merkle-tree/-/persistent-merkle-tree-0.4.2.tgz", + "integrity": "sha512-lLO3ihKPngXLTus/L7WHKaw9PnNJWizlOF1H9NNzHP6Xvh82vzg9F2bzkXhYIFshMZ2gTCEz8tq6STe7r5NDfQ==", + "dev": true, + "requires": { + "@chainsafe/as-sha256": "^0.3.1" + } + }, + "@chainsafe/ssz": { + "version": "0.9.4", + "resolved": "https://registry.npmjs.org/@chainsafe/ssz/-/ssz-0.9.4.tgz", + "integrity": "sha512-77Qtg2N1ayqs4Bg/wvnWfg5Bta7iy7IRh8XqXh7oNMeP2HBbBwx8m6yTpA8p0EHItWPEBkgZd5S5/LSlp3GXuQ==", + "dev": true, + "requires": { + "@chainsafe/as-sha256": "^0.3.1", + "@chainsafe/persistent-merkle-tree": "^0.4.2", + "case": "^1.6.3" + } + }, + "@changesets/apply-release-plan": { + "version": "6.1.4", + "resolved": "https://registry.npmjs.org/@changesets/apply-release-plan/-/apply-release-plan-6.1.4.tgz", + "integrity": "sha512-FMpKF1fRlJyCZVYHr3CbinpZZ+6MwvOtWUuO8uo+svcATEoc1zRDcj23pAurJ2TZ/uVz1wFHH6K3NlACy0PLew==", + "dev": true, + "requires": { + "@babel/runtime": "^7.20.1", + "@changesets/config": "^2.3.1", + "@changesets/get-version-range-type": "^0.3.2", + "@changesets/git": "^2.0.0", + "@changesets/types": "^5.2.1", + "@manypkg/get-packages": "^1.1.3", + "detect-indent": "^6.0.0", + "fs-extra": "^7.0.1", + "lodash.startcase": "^4.4.0", + "outdent": "^0.5.0", + "prettier": "^2.7.1", + "resolve-from": "^5.0.0", + "semver": "^7.5.3" + }, + "dependencies": { + "prettier": { + "version": "2.8.8", + "resolved": "https://registry.npmjs.org/prettier/-/prettier-2.8.8.tgz", + "integrity": "sha512-tdN8qQGvNjw4CHbY+XXk0JgCXn9QiF21a55rBe5LJAU+kDyC4WQn4+awm2Xfk2lQMk5fKup9XgzTZtGkjBdP9Q==", + "dev": true + } + } + }, + "@changesets/assemble-release-plan": { + "version": "5.2.4", + "resolved": "https://registry.npmjs.org/@changesets/assemble-release-plan/-/assemble-release-plan-5.2.4.tgz", + "integrity": "sha512-xJkWX+1/CUaOUWTguXEbCDTyWJFECEhmdtbkjhn5GVBGxdP/JwaHBIU9sW3FR6gD07UwZ7ovpiPclQZs+j+mvg==", + "dev": true, + "requires": { + "@babel/runtime": "^7.20.1", + "@changesets/errors": "^0.1.4", + "@changesets/get-dependents-graph": "^1.3.6", + "@changesets/types": "^5.2.1", + "@manypkg/get-packages": "^1.1.3", + "semver": "^7.5.3" + } + }, + "@changesets/changelog-git": { + "version": "0.1.14", + "resolved": "https://registry.npmjs.org/@changesets/changelog-git/-/changelog-git-0.1.14.tgz", + "integrity": "sha512-+vRfnKtXVWsDDxGctOfzJsPhaCdXRYoe+KyWYoq5X/GqoISREiat0l3L8B0a453B2B4dfHGcZaGyowHbp9BSaA==", + "dev": true, + "requires": { + "@changesets/types": "^5.2.1" + } + }, + "@changesets/changelog-github": { + "version": "0.4.8", + "resolved": "https://registry.npmjs.org/@changesets/changelog-github/-/changelog-github-0.4.8.tgz", + "integrity": "sha512-jR1DHibkMAb5v/8ym77E4AMNWZKB5NPzw5a5Wtqm1JepAuIF+hrKp2u04NKM14oBZhHglkCfrla9uq8ORnK/dw==", + "dev": true, + "requires": { + "@changesets/get-github-info": "^0.5.2", + "@changesets/types": "^5.2.1", + "dotenv": "^8.1.0" + } + }, + "@changesets/cli": { + "version": "2.26.2", + "resolved": "https://registry.npmjs.org/@changesets/cli/-/cli-2.26.2.tgz", + "integrity": "sha512-dnWrJTmRR8bCHikJHl9b9HW3gXACCehz4OasrXpMp7sx97ECuBGGNjJhjPhdZNCvMy9mn4BWdplI323IbqsRig==", + "dev": true, + "requires": { + "@babel/runtime": "^7.20.1", + "@changesets/apply-release-plan": "^6.1.4", + "@changesets/assemble-release-plan": "^5.2.4", + "@changesets/changelog-git": "^0.1.14", + "@changesets/config": "^2.3.1", + "@changesets/errors": "^0.1.4", + "@changesets/get-dependents-graph": "^1.3.6", + "@changesets/get-release-plan": "^3.0.17", + "@changesets/git": "^2.0.0", + "@changesets/logger": "^0.0.5", + "@changesets/pre": "^1.0.14", + "@changesets/read": "^0.5.9", + "@changesets/types": "^5.2.1", + "@changesets/write": "^0.2.3", + "@manypkg/get-packages": "^1.1.3", + "@types/is-ci": "^3.0.0", + "@types/semver": "^7.5.0", + "ansi-colors": "^4.1.3", + "chalk": "^2.1.0", + "enquirer": "^2.3.0", + "external-editor": "^3.1.0", + "fs-extra": "^7.0.1", + "human-id": "^1.0.2", + "is-ci": "^3.0.1", + "meow": "^6.0.0", + "outdent": "^0.5.0", + "p-limit": "^2.2.0", + "preferred-pm": "^3.0.0", + "resolve-from": "^5.0.0", + "semver": "^7.5.3", + "spawndamnit": "^2.0.0", + "term-size": "^2.1.0", + "tty-table": "^4.1.5" + }, + "dependencies": { + "p-limit": { + "version": "2.3.0", + "resolved": "https://registry.npmjs.org/p-limit/-/p-limit-2.3.0.tgz", + "integrity": "sha512-//88mFWSJx8lxCzwdAABTJL2MyWB12+eIY7MDL2SqLmAkeKU9qxRvWuSyTjm3FUmpBEMuFfckAIqEaVGUDxb6w==", + "dev": true, + "requires": { + "p-try": "^2.0.0" + } + } + } + }, + "@changesets/config": { + "version": "2.3.1", + "resolved": "https://registry.npmjs.org/@changesets/config/-/config-2.3.1.tgz", + "integrity": "sha512-PQXaJl82CfIXddUOppj4zWu+987GCw2M+eQcOepxN5s+kvnsZOwjEJO3DH9eVy+OP6Pg/KFEWdsECFEYTtbg6w==", + "dev": true, + "requires": { + "@changesets/errors": "^0.1.4", + "@changesets/get-dependents-graph": "^1.3.6", + "@changesets/logger": "^0.0.5", + "@changesets/types": "^5.2.1", + "@manypkg/get-packages": "^1.1.3", + "fs-extra": "^7.0.1", + "micromatch": "^4.0.2" + } + }, + "@changesets/errors": { + "version": "0.1.4", + "resolved": "https://registry.npmjs.org/@changesets/errors/-/errors-0.1.4.tgz", + "integrity": "sha512-HAcqPF7snsUJ/QzkWoKfRfXushHTu+K5KZLJWPb34s4eCZShIf8BFO3fwq6KU8+G7L5KdtN2BzQAXOSXEyiY9Q==", + "dev": true, + "requires": { + "extendable-error": "^0.1.5" + } + }, + "@changesets/get-dependents-graph": { + "version": "1.3.6", + "resolved": "https://registry.npmjs.org/@changesets/get-dependents-graph/-/get-dependents-graph-1.3.6.tgz", + "integrity": "sha512-Q/sLgBANmkvUm09GgRsAvEtY3p1/5OCzgBE5vX3vgb5CvW0j7CEljocx5oPXeQSNph6FXulJlXV3Re/v3K3P3Q==", + "dev": true, + "requires": { + "@changesets/types": "^5.2.1", + "@manypkg/get-packages": "^1.1.3", + "chalk": "^2.1.0", + "fs-extra": "^7.0.1", + "semver": "^7.5.3" + } + }, + "@changesets/get-github-info": { + "version": "0.5.2", + "resolved": "https://registry.npmjs.org/@changesets/get-github-info/-/get-github-info-0.5.2.tgz", + "integrity": "sha512-JppheLu7S114aEs157fOZDjFqUDpm7eHdq5E8SSR0gUBTEK0cNSHsrSR5a66xs0z3RWuo46QvA3vawp8BxDHvg==", + "dev": true, + "requires": { + "dataloader": "^1.4.0", + "node-fetch": "^2.5.0" + } + }, + "@changesets/get-release-plan": { + "version": "3.0.17", + "resolved": "https://registry.npmjs.org/@changesets/get-release-plan/-/get-release-plan-3.0.17.tgz", + "integrity": "sha512-6IwKTubNEgoOZwDontYc2x2cWXfr6IKxP3IhKeK+WjyD6y3M4Gl/jdQvBw+m/5zWILSOCAaGLu2ZF6Q+WiPniw==", + "dev": true, + "requires": { + "@babel/runtime": "^7.20.1", + "@changesets/assemble-release-plan": "^5.2.4", + "@changesets/config": "^2.3.1", + "@changesets/pre": "^1.0.14", + "@changesets/read": "^0.5.9", + "@changesets/types": "^5.2.1", + "@manypkg/get-packages": "^1.1.3" + } + }, + "@changesets/get-version-range-type": { + "version": "0.3.2", + "resolved": "https://registry.npmjs.org/@changesets/get-version-range-type/-/get-version-range-type-0.3.2.tgz", + "integrity": "sha512-SVqwYs5pULYjYT4op21F2pVbcrca4qA/bAA3FmFXKMN7Y+HcO8sbZUTx3TAy2VXulP2FACd1aC7f2nTuqSPbqg==", + "dev": true + }, + "@changesets/git": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/@changesets/git/-/git-2.0.0.tgz", + "integrity": "sha512-enUVEWbiqUTxqSnmesyJGWfzd51PY4H7mH9yUw0hPVpZBJ6tQZFMU3F3mT/t9OJ/GjyiM4770i+sehAn6ymx6A==", + "dev": true, + "requires": { + "@babel/runtime": "^7.20.1", + "@changesets/errors": "^0.1.4", + "@changesets/types": "^5.2.1", + "@manypkg/get-packages": "^1.1.3", + "is-subdir": "^1.1.1", + "micromatch": "^4.0.2", + "spawndamnit": "^2.0.0" + } + }, + "@changesets/logger": { + "version": "0.0.5", + "resolved": "https://registry.npmjs.org/@changesets/logger/-/logger-0.0.5.tgz", + "integrity": "sha512-gJyZHomu8nASHpaANzc6bkQMO9gU/ib20lqew1rVx753FOxffnCrJlGIeQVxNWCqM+o6OOleCo/ivL8UAO5iFw==", + "dev": true, + "requires": { + "chalk": "^2.1.0" + } + }, + "@changesets/parse": { + "version": "0.3.16", + "resolved": "https://registry.npmjs.org/@changesets/parse/-/parse-0.3.16.tgz", + "integrity": "sha512-127JKNd167ayAuBjUggZBkmDS5fIKsthnr9jr6bdnuUljroiERW7FBTDNnNVyJ4l69PzR57pk6mXQdtJyBCJKg==", + "dev": true, + "requires": { + "@changesets/types": "^5.2.1", + "js-yaml": "^3.13.1" + } + }, + "@changesets/pre": { + "version": "1.0.14", + "resolved": "https://registry.npmjs.org/@changesets/pre/-/pre-1.0.14.tgz", + "integrity": "sha512-dTsHmxQWEQekHYHbg+M1mDVYFvegDh9j/kySNuDKdylwfMEevTeDouR7IfHNyVodxZXu17sXoJuf2D0vi55FHQ==", + "dev": true, + "requires": { + "@babel/runtime": "^7.20.1", + "@changesets/errors": "^0.1.4", + "@changesets/types": "^5.2.1", + "@manypkg/get-packages": "^1.1.3", + "fs-extra": "^7.0.1" + } + }, + "@changesets/read": { + "version": "0.5.9", + "resolved": "https://registry.npmjs.org/@changesets/read/-/read-0.5.9.tgz", + "integrity": "sha512-T8BJ6JS6j1gfO1HFq50kU3qawYxa4NTbI/ASNVVCBTsKquy2HYwM9r7ZnzkiMe8IEObAJtUVGSrePCOxAK2haQ==", + "dev": true, + "requires": { + "@babel/runtime": "^7.20.1", + "@changesets/git": "^2.0.0", + "@changesets/logger": "^0.0.5", + "@changesets/parse": "^0.3.16", + "@changesets/types": "^5.2.1", + "chalk": "^2.1.0", + "fs-extra": "^7.0.1", + "p-filter": "^2.1.0" + } + }, + "@changesets/types": { + "version": "5.2.1", + "resolved": "https://registry.npmjs.org/@changesets/types/-/types-5.2.1.tgz", + "integrity": "sha512-myLfHbVOqaq9UtUKqR/nZA/OY7xFjQMdfgfqeZIBK4d0hA6pgxArvdv8M+6NUzzBsjWLOtvApv8YHr4qM+Kpfg==", + "dev": true + }, + "@changesets/write": { + "version": "0.2.3", + "resolved": "https://registry.npmjs.org/@changesets/write/-/write-0.2.3.tgz", + "integrity": "sha512-Dbamr7AIMvslKnNYsLFafaVORx4H0pvCA2MHqgtNCySMe1blImEyAEOzDmcgKAkgz4+uwoLz7demIrX+JBr/Xw==", + "dev": true, + "requires": { + "@babel/runtime": "^7.20.1", + "@changesets/types": "^5.2.1", + "fs-extra": "^7.0.1", + "human-id": "^1.0.2", + "prettier": "^2.7.1" + }, + "dependencies": { + "prettier": { + "version": "2.8.8", + "resolved": "https://registry.npmjs.org/prettier/-/prettier-2.8.8.tgz", + "integrity": "sha512-tdN8qQGvNjw4CHbY+XXk0JgCXn9QiF21a55rBe5LJAU+kDyC4WQn4+awm2Xfk2lQMk5fKup9XgzTZtGkjBdP9Q==", + "dev": true + } + } + }, + "@ensdomains/address-encoder": { + "version": "0.1.9", + "resolved": "https://registry.npmjs.org/@ensdomains/address-encoder/-/address-encoder-0.1.9.tgz", + "integrity": "sha512-E2d2gP4uxJQnDu2Kfg1tHNspefzbLT8Tyjrm5sEuim32UkU2sm5xL4VXtgc2X33fmPEw9+jUMpGs4veMbf+PYg==", + "dev": true, + "requires": { + "bech32": "^1.1.3", + "blakejs": "^1.1.0", + "bn.js": "^4.11.8", + "bs58": "^4.0.1", + "crypto-addr-codec": "^0.1.7", + "nano-base32": "^1.0.1", + "ripemd160": "^2.0.2" + } + }, + "@ensdomains/ens": { + "version": "0.4.5", + "resolved": "https://registry.npmjs.org/@ensdomains/ens/-/ens-0.4.5.tgz", + "integrity": "sha512-JSvpj1iNMFjK6K+uVl4unqMoa9rf5jopb8cya5UGBWz23Nw8hSNT7efgUx4BTlAPAgpNlEioUfeTyQ6J9ZvTVw==", + "dev": true, + "requires": { + "bluebird": "^3.5.2", + "eth-ens-namehash": "^2.0.8", + "solc": "^0.4.20", + "testrpc": "0.0.1", + "web3-utils": "^1.0.0-beta.31" + } + }, + "@ensdomains/ensjs": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/@ensdomains/ensjs/-/ensjs-2.1.0.tgz", + "integrity": "sha512-GRbGPT8Z/OJMDuxs75U/jUNEC0tbL0aj7/L/QQznGYKm/tiasp+ndLOaoULy9kKJFC0TBByqfFliEHDgoLhyog==", + "dev": true, + "requires": { + "@babel/runtime": "^7.4.4", + "@ensdomains/address-encoder": "^0.1.7", + "@ensdomains/ens": "0.4.5", + "@ensdomains/resolver": "0.2.4", + "content-hash": "^2.5.2", + "eth-ens-namehash": "^2.0.8", + "ethers": "^5.0.13", + "js-sha3": "^0.8.0" + }, + "dependencies": { + "ethers": { + "version": "5.7.2", + "resolved": "https://registry.npmjs.org/ethers/-/ethers-5.7.2.tgz", + "integrity": "sha512-wswUsmWo1aOK8rR7DIKiWSw9DbLWe6x98Jrn8wcTflTVvaXhAMaB5zGAXy0GYQEQp9iO1iSHWVyARQm11zUtyg==", + "dev": true, + "requires": { + "@ethersproject/abi": "5.7.0", + "@ethersproject/abstract-provider": "5.7.0", + "@ethersproject/abstract-signer": "5.7.0", + "@ethersproject/address": "5.7.0", + "@ethersproject/base64": "5.7.0", + "@ethersproject/basex": "5.7.0", + "@ethersproject/bignumber": "5.7.0", + "@ethersproject/bytes": "5.7.0", + "@ethersproject/constants": "5.7.0", + "@ethersproject/contracts": "5.7.0", + "@ethersproject/hash": "5.7.0", + "@ethersproject/hdnode": "5.7.0", + "@ethersproject/json-wallets": "5.7.0", + "@ethersproject/keccak256": "5.7.0", + "@ethersproject/logger": "5.7.0", + "@ethersproject/networks": "5.7.1", + "@ethersproject/pbkdf2": "5.7.0", + "@ethersproject/properties": "5.7.0", + "@ethersproject/providers": "5.7.2", + "@ethersproject/random": "5.7.0", + "@ethersproject/rlp": "5.7.0", + "@ethersproject/sha2": "5.7.0", + "@ethersproject/signing-key": "5.7.0", + "@ethersproject/solidity": "5.7.0", + "@ethersproject/strings": "5.7.0", + "@ethersproject/transactions": "5.7.0", + "@ethersproject/units": "5.7.0", + "@ethersproject/wallet": "5.7.0", + "@ethersproject/web": "5.7.1", + "@ethersproject/wordlists": "5.7.0" + } + } + } + }, + "@ensdomains/resolver": { + "version": "0.2.4", + "resolved": "https://registry.npmjs.org/@ensdomains/resolver/-/resolver-0.2.4.tgz", + "integrity": "sha512-bvaTH34PMCbv6anRa9I/0zjLJgY4EuznbEMgbV77JBCQ9KNC46rzi0avuxpOfu+xDjPEtSFGqVEOr5GlUSGudA==", + "dev": true + }, + "@eslint-community/eslint-utils": { + "version": "4.4.0", + "resolved": "https://registry.npmjs.org/@eslint-community/eslint-utils/-/eslint-utils-4.4.0.tgz", + "integrity": "sha512-1/sA4dwrzBAyeUoQ6oxahHKmrZvsnLCg4RfxW3ZFGGmQkSNQPFNLV9CUEFQP1x9EYXHTo5p6xdhZM1Ne9p/AfA==", + "dev": true, + "requires": { + "eslint-visitor-keys": "^3.3.0" + } + }, + "@eslint-community/regexpp": { + "version": "4.5.1", + "resolved": "https://registry.npmjs.org/@eslint-community/regexpp/-/regexpp-4.5.1.tgz", + "integrity": "sha512-Z5ba73P98O1KUYCCJTUeVpja9RcGoMdncZ6T49FCUl2lN38JtCJ+3WgIDBv0AuY4WChU5PmtJmOCTlN6FZTFKQ==", + "dev": true + }, + "@eslint/eslintrc": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/@eslint/eslintrc/-/eslintrc-2.1.0.tgz", + "integrity": "sha512-Lj7DECXqIVCqnqjjHMPna4vn6GJcMgul/wuS0je9OZ9gsL0zzDpKPVtcG1HaDVc+9y+qgXneTeUMbCqXJNpH1A==", + "dev": true, + "requires": { + "ajv": "^6.12.4", + "debug": "^4.3.2", + "espree": "^9.6.0", + "globals": "^13.19.0", + "ignore": "^5.2.0", + "import-fresh": "^3.2.1", + "js-yaml": "^4.1.0", + "minimatch": "^3.1.2", + "strip-json-comments": "^3.1.1" + }, + "dependencies": { + "argparse": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/argparse/-/argparse-2.0.1.tgz", + "integrity": "sha512-8+9WqebbFzpX9OR+Wa6O29asIogeRMzcGtAINdpMHHyAg10f05aSFVBbcEqGf/PXw1EjAZ+q2/bEBg3DvurK3Q==", + "dev": true + }, + "js-yaml": { + "version": "4.1.0", + "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-4.1.0.tgz", + "integrity": "sha512-wpxZs9NoxZaJESJGIZTyDEaYpl0FKSA+FB9aJiyemKhMwkxQg63h4T1KJgUGHpTqPDNRcmmYLugrRjJlBtWvRA==", + "dev": true, + "requires": { + "argparse": "^2.0.1" + } + } + } + }, + "@eslint/js": { + "version": "8.44.0", + "resolved": "https://registry.npmjs.org/@eslint/js/-/js-8.44.0.tgz", + "integrity": "sha512-Ag+9YM4ocKQx9AarydN0KY2j0ErMHNIocPDrVo8zAE44xLTjEtz81OdR68/cydGtk6m6jDb5Za3r2useMzYmSw==", + "dev": true + }, + "@ethereumjs/common": { + "version": "2.5.0", + "resolved": "https://registry.npmjs.org/@ethereumjs/common/-/common-2.5.0.tgz", + "integrity": "sha512-DEHjW6e38o+JmB/NO3GZBpW4lpaiBpkFgXF6jLcJ6gETBYpEyaA5nTimsWBUJR3Vmtm/didUEbNjajskugZORg==", + "dev": true, + "requires": { + "crc-32": "^1.2.0", + "ethereumjs-util": "^7.1.1" + } + }, + "@ethereumjs/tx": { + "version": "3.3.2", + "resolved": "https://registry.npmjs.org/@ethereumjs/tx/-/tx-3.3.2.tgz", + "integrity": "sha512-6AaJhwg4ucmwTvw/1qLaZUX5miWrwZ4nLOUsKyb/HtzS3BMw/CasKhdi1ims9mBKeK9sOJCH4qGKOBGyJCeeog==", + "dev": true, + "requires": { + "@ethereumjs/common": "^2.5.0", + "ethereumjs-util": "^7.1.2" + } + }, + "@ethersproject/abi": { + "version": "5.7.0", + "resolved": "https://registry.npmjs.org/@ethersproject/abi/-/abi-5.7.0.tgz", + "integrity": "sha512-351ktp42TiRcYB3H1OP8yajPeAQstMW/yCFokj/AthP9bLHzQFPlOrxOcwYEDkUAICmOHljvN4K39OMTMUa9RA==", + "dev": true, + "requires": { + "@ethersproject/address": "^5.7.0", + "@ethersproject/bignumber": "^5.7.0", + "@ethersproject/bytes": "^5.7.0", + "@ethersproject/constants": "^5.7.0", + "@ethersproject/hash": "^5.7.0", + "@ethersproject/keccak256": "^5.7.0", + "@ethersproject/logger": "^5.7.0", + "@ethersproject/properties": "^5.7.0", + "@ethersproject/strings": "^5.7.0" + } + }, + "@ethersproject/abstract-provider": { + "version": "5.7.0", + "resolved": "https://registry.npmjs.org/@ethersproject/abstract-provider/-/abstract-provider-5.7.0.tgz", + "integrity": "sha512-R41c9UkchKCpAqStMYUpdunjo3pkEvZC3FAwZn5S5MGbXoMQOHIdHItezTETxAO5bevtMApSyEhn9+CHcDsWBw==", + "dev": true, + "requires": { + "@ethersproject/bignumber": "^5.7.0", + "@ethersproject/bytes": "^5.7.0", + "@ethersproject/logger": "^5.7.0", + "@ethersproject/networks": "^5.7.0", + "@ethersproject/properties": "^5.7.0", + "@ethersproject/transactions": "^5.7.0", + "@ethersproject/web": "^5.7.0" + } + }, + "@ethersproject/abstract-signer": { + "version": "5.7.0", + "resolved": "https://registry.npmjs.org/@ethersproject/abstract-signer/-/abstract-signer-5.7.0.tgz", + "integrity": "sha512-a16V8bq1/Cz+TGCkE2OPMTOUDLS3grCpdjoJCYNnVBbdYEMSgKrU0+B90s8b6H+ByYTBZN7a3g76jdIJi7UfKQ==", + "dev": true, + "requires": { + "@ethersproject/abstract-provider": "^5.7.0", + "@ethersproject/bignumber": "^5.7.0", + "@ethersproject/bytes": "^5.7.0", + "@ethersproject/logger": "^5.7.0", + "@ethersproject/properties": "^5.7.0" + } + }, + "@ethersproject/address": { + "version": "5.7.0", + "resolved": "https://registry.npmjs.org/@ethersproject/address/-/address-5.7.0.tgz", + "integrity": "sha512-9wYhYt7aghVGo758POM5nqcOMaE168Q6aRLJZwUmiqSrAungkG74gSSeKEIR7ukixesdRZGPgVqme6vmxs1fkA==", + "dev": true, + "requires": { + "@ethersproject/bignumber": "^5.7.0", + "@ethersproject/bytes": "^5.7.0", + "@ethersproject/keccak256": "^5.7.0", + "@ethersproject/logger": "^5.7.0", + "@ethersproject/rlp": "^5.7.0" + } + }, + "@ethersproject/base64": { + "version": "5.7.0", + "resolved": "https://registry.npmjs.org/@ethersproject/base64/-/base64-5.7.0.tgz", + "integrity": "sha512-Dr8tcHt2mEbsZr/mwTPIQAf3Ai0Bks/7gTw9dSqk1mQvhW3XvRlmDJr/4n+wg1JmCl16NZue17CDh8xb/vZ0sQ==", + "dev": true, + "requires": { + "@ethersproject/bytes": "^5.7.0" + } + }, + "@ethersproject/basex": { + "version": "5.7.0", + "resolved": "https://registry.npmjs.org/@ethersproject/basex/-/basex-5.7.0.tgz", + "integrity": "sha512-ywlh43GwZLv2Voc2gQVTKBoVQ1mti3d8HK5aMxsfu/nRDnMmNqaSJ3r3n85HBByT8OpoY96SXM1FogC533T4zw==", + "dev": true, + "requires": { + "@ethersproject/bytes": "^5.7.0", + "@ethersproject/properties": "^5.7.0" + } + }, + "@ethersproject/bignumber": { + "version": "5.7.0", + "resolved": "https://registry.npmjs.org/@ethersproject/bignumber/-/bignumber-5.7.0.tgz", + "integrity": "sha512-n1CAdIHRWjSucQO3MC1zPSVgV/6dy/fjL9pMrPP9peL+QxEg9wOsVqwD4+818B6LUEtaXzVHQiuivzRoxPxUGw==", + "dev": true, + "requires": { + "@ethersproject/bytes": "^5.7.0", + "@ethersproject/logger": "^5.7.0", + "bn.js": "^5.2.1" + }, + "dependencies": { + "bn.js": { + "version": "5.2.1", + "resolved": "https://registry.npmjs.org/bn.js/-/bn.js-5.2.1.tgz", + "integrity": "sha512-eXRvHzWyYPBuB4NBy0cmYQjGitUrtqwbvlzP3G6VFnNRbsZQIxQ10PbKKHt8gZ/HW/D/747aDl+QkDqg3KQLMQ==", + "dev": true + } + } + }, + "@ethersproject/bytes": { + "version": "5.7.0", + "resolved": "https://registry.npmjs.org/@ethersproject/bytes/-/bytes-5.7.0.tgz", + "integrity": "sha512-nsbxwgFXWh9NyYWo+U8atvmMsSdKJprTcICAkvbBffT75qDocbuggBU0SJiVK2MuTrp0q+xvLkTnGMPK1+uA9A==", + "dev": true, + "requires": { + "@ethersproject/logger": "^5.7.0" + } + }, + "@ethersproject/constants": { + "version": "5.7.0", + "resolved": "https://registry.npmjs.org/@ethersproject/constants/-/constants-5.7.0.tgz", + "integrity": "sha512-DHI+y5dBNvkpYUMiRQyxRBYBefZkJfo70VUkUAsRjcPs47muV9evftfZ0PJVCXYbAiCgght0DtcF9srFQmIgWA==", + "dev": true, + "requires": { + "@ethersproject/bignumber": "^5.7.0" + } + }, + "@ethersproject/contracts": { + "version": "5.7.0", + "resolved": "https://registry.npmjs.org/@ethersproject/contracts/-/contracts-5.7.0.tgz", + "integrity": "sha512-5GJbzEU3X+d33CdfPhcyS+z8MzsTrBGk/sc+G+59+tPa9yFkl6HQ9D6L0QMgNTA9q8dT0XKxxkyp883XsQvbbg==", + "dev": true, + "requires": { + "@ethersproject/abi": "^5.7.0", + "@ethersproject/abstract-provider": "^5.7.0", + "@ethersproject/abstract-signer": "^5.7.0", + "@ethersproject/address": "^5.7.0", + "@ethersproject/bignumber": "^5.7.0", + "@ethersproject/bytes": "^5.7.0", + "@ethersproject/constants": "^5.7.0", + "@ethersproject/logger": "^5.7.0", + "@ethersproject/properties": "^5.7.0", + "@ethersproject/transactions": "^5.7.0" + } + }, + "@ethersproject/hash": { + "version": "5.7.0", + "resolved": "https://registry.npmjs.org/@ethersproject/hash/-/hash-5.7.0.tgz", + "integrity": "sha512-qX5WrQfnah1EFnO5zJv1v46a8HW0+E5xuBBDTwMFZLuVTx0tbU2kkx15NqdjxecrLGatQN9FGQKpb1FKdHCt+g==", + "dev": true, + "requires": { + "@ethersproject/abstract-signer": "^5.7.0", + "@ethersproject/address": "^5.7.0", + "@ethersproject/base64": "^5.7.0", + "@ethersproject/bignumber": "^5.7.0", + "@ethersproject/bytes": "^5.7.0", + "@ethersproject/keccak256": "^5.7.0", + "@ethersproject/logger": "^5.7.0", + "@ethersproject/properties": "^5.7.0", + "@ethersproject/strings": "^5.7.0" + } + }, + "@ethersproject/hdnode": { + "version": "5.7.0", + "resolved": "https://registry.npmjs.org/@ethersproject/hdnode/-/hdnode-5.7.0.tgz", + "integrity": "sha512-OmyYo9EENBPPf4ERhR7oj6uAtUAhYGqOnIS+jE5pTXvdKBS99ikzq1E7Iv0ZQZ5V36Lqx1qZLeak0Ra16qpeOg==", + "dev": true, + "requires": { + "@ethersproject/abstract-signer": "^5.7.0", + "@ethersproject/basex": "^5.7.0", + "@ethersproject/bignumber": "^5.7.0", + "@ethersproject/bytes": "^5.7.0", + "@ethersproject/logger": "^5.7.0", + "@ethersproject/pbkdf2": "^5.7.0", + "@ethersproject/properties": "^5.7.0", + "@ethersproject/sha2": "^5.7.0", + "@ethersproject/signing-key": "^5.7.0", + "@ethersproject/strings": "^5.7.0", + "@ethersproject/transactions": "^5.7.0", + "@ethersproject/wordlists": "^5.7.0" + } + }, + "@ethersproject/json-wallets": { + "version": "5.7.0", + "resolved": "https://registry.npmjs.org/@ethersproject/json-wallets/-/json-wallets-5.7.0.tgz", + "integrity": "sha512-8oee5Xgu6+RKgJTkvEMl2wDgSPSAQ9MB/3JYjFV9jlKvcYHUXZC+cQp0njgmxdHkYWn8s6/IqIZYm0YWCjO/0g==", + "dev": true, + "requires": { + "@ethersproject/abstract-signer": "^5.7.0", + "@ethersproject/address": "^5.7.0", + "@ethersproject/bytes": "^5.7.0", + "@ethersproject/hdnode": "^5.7.0", + "@ethersproject/keccak256": "^5.7.0", + "@ethersproject/logger": "^5.7.0", + "@ethersproject/pbkdf2": "^5.7.0", + "@ethersproject/properties": "^5.7.0", + "@ethersproject/random": "^5.7.0", + "@ethersproject/strings": "^5.7.0", + "@ethersproject/transactions": "^5.7.0", + "aes-js": "3.0.0", + "scrypt-js": "3.0.1" + }, + "dependencies": { + "aes-js": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/aes-js/-/aes-js-3.0.0.tgz", + "integrity": "sha512-H7wUZRn8WpTq9jocdxQ2c8x2sKo9ZVmzfRE13GiNJXfp7NcKYEdvl3vspKjXox6RIG2VtaRe4JFvxG4rqp2Zuw==", + "dev": true + } + } + }, + "@ethersproject/keccak256": { + "version": "5.7.0", + "resolved": "https://registry.npmjs.org/@ethersproject/keccak256/-/keccak256-5.7.0.tgz", + "integrity": "sha512-2UcPboeL/iW+pSg6vZ6ydF8tCnv3Iu/8tUmLLzWWGzxWKFFqOBQFLo6uLUv6BDrLgCDfN28RJ/wtByx+jZ4KBg==", + "dev": true, + "requires": { + "@ethersproject/bytes": "^5.7.0", + "js-sha3": "0.8.0" + } + }, + "@ethersproject/logger": { + "version": "5.7.0", + "resolved": "https://registry.npmjs.org/@ethersproject/logger/-/logger-5.7.0.tgz", + "integrity": "sha512-0odtFdXu/XHtjQXJYA3u9G0G8btm0ND5Cu8M7i5vhEcE8/HmF4Lbdqanwyv4uQTr2tx6b7fQRmgLrsnpQlmnig==", + "dev": true + }, + "@ethersproject/networks": { + "version": "5.7.1", + "resolved": "https://registry.npmjs.org/@ethersproject/networks/-/networks-5.7.1.tgz", + "integrity": "sha512-n/MufjFYv3yFcUyfhnXotyDlNdFb7onmkSy8aQERi2PjNcnWQ66xXxa3XlS8nCcA8aJKJjIIMNJTC7tu80GwpQ==", + "dev": true, + "requires": { + "@ethersproject/logger": "^5.7.0" + } + }, + "@ethersproject/pbkdf2": { + "version": "5.7.0", + "resolved": "https://registry.npmjs.org/@ethersproject/pbkdf2/-/pbkdf2-5.7.0.tgz", + "integrity": "sha512-oR/dBRZR6GTyaofd86DehG72hY6NpAjhabkhxgr3X2FpJtJuodEl2auADWBZfhDHgVCbu3/H/Ocq2uC6dpNjjw==", + "dev": true, + "requires": { + "@ethersproject/bytes": "^5.7.0", + "@ethersproject/sha2": "^5.7.0" + } + }, + "@ethersproject/properties": { + "version": "5.7.0", + "resolved": "https://registry.npmjs.org/@ethersproject/properties/-/properties-5.7.0.tgz", + "integrity": "sha512-J87jy8suntrAkIZtecpxEPxY//szqr1mlBaYlQ0r4RCaiD2hjheqF9s1LVE8vVuJCXisjIP+JgtK/Do54ej4Sw==", + "dev": true, + "requires": { + "@ethersproject/logger": "^5.7.0" + } + }, + "@ethersproject/providers": { + "version": "5.7.2", + "resolved": "https://registry.npmjs.org/@ethersproject/providers/-/providers-5.7.2.tgz", + "integrity": "sha512-g34EWZ1WWAVgr4aptGlVBF8mhl3VWjv+8hoAnzStu8Ah22VHBsuGzP17eb6xDVRzw895G4W7vvx60lFFur/1Rg==", + "dev": true, + "requires": { + "@ethersproject/abstract-provider": "^5.7.0", + "@ethersproject/abstract-signer": "^5.7.0", + "@ethersproject/address": "^5.7.0", + "@ethersproject/base64": "^5.7.0", + "@ethersproject/basex": "^5.7.0", + "@ethersproject/bignumber": "^5.7.0", + "@ethersproject/bytes": "^5.7.0", + "@ethersproject/constants": "^5.7.0", + "@ethersproject/hash": "^5.7.0", + "@ethersproject/logger": "^5.7.0", + "@ethersproject/networks": "^5.7.0", + "@ethersproject/properties": "^5.7.0", + "@ethersproject/random": "^5.7.0", + "@ethersproject/rlp": "^5.7.0", + "@ethersproject/sha2": "^5.7.0", + "@ethersproject/strings": "^5.7.0", + "@ethersproject/transactions": "^5.7.0", + "@ethersproject/web": "^5.7.0", + "bech32": "1.1.4", + "ws": "7.4.6" + }, + "dependencies": { + "ws": { + "version": "7.4.6", + "resolved": "https://registry.npmjs.org/ws/-/ws-7.4.6.tgz", + "integrity": "sha512-YmhHDO4MzaDLB+M9ym/mDA5z0naX8j7SIlT8f8z+I0VtzsRbekxEutHSme7NPS2qE8StCYQNUnfWdXta/Yu85A==", + "dev": true, + "requires": {} + } + } + }, + "@ethersproject/random": { + "version": "5.7.0", + "resolved": "https://registry.npmjs.org/@ethersproject/random/-/random-5.7.0.tgz", + "integrity": "sha512-19WjScqRA8IIeWclFme75VMXSBvi4e6InrUNuaR4s5pTF2qNhcGdCUwdxUVGtDDqC00sDLCO93jPQoDUH4HVmQ==", + "dev": true, + "requires": { + "@ethersproject/bytes": "^5.7.0", + "@ethersproject/logger": "^5.7.0" + } + }, + "@ethersproject/rlp": { + "version": "5.7.0", + "resolved": "https://registry.npmjs.org/@ethersproject/rlp/-/rlp-5.7.0.tgz", + "integrity": "sha512-rBxzX2vK8mVF7b0Tol44t5Tb8gomOHkj5guL+HhzQ1yBh/ydjGnpw6at+X6Iw0Kp3OzzzkcKp8N9r0W4kYSs9w==", + "dev": true, + "requires": { + "@ethersproject/bytes": "^5.7.0", + "@ethersproject/logger": "^5.7.0" + } + }, + "@ethersproject/sha2": { + "version": "5.7.0", + "resolved": "https://registry.npmjs.org/@ethersproject/sha2/-/sha2-5.7.0.tgz", + "integrity": "sha512-gKlH42riwb3KYp0reLsFTokByAKoJdgFCwI+CCiX/k+Jm2mbNs6oOaCjYQSlI1+XBVejwH2KrmCbMAT/GnRDQw==", + "dev": true, + "requires": { + "@ethersproject/bytes": "^5.7.0", + "@ethersproject/logger": "^5.7.0", + "hash.js": "1.1.7" + } + }, + "@ethersproject/signing-key": { + "version": "5.7.0", + "resolved": "https://registry.npmjs.org/@ethersproject/signing-key/-/signing-key-5.7.0.tgz", + "integrity": "sha512-MZdy2nL3wO0u7gkB4nA/pEf8lu1TlFswPNmy8AiYkfKTdO6eXBJyUdmHO/ehm/htHw9K/qF8ujnTyUAD+Ry54Q==", + "dev": true, + "requires": { + "@ethersproject/bytes": "^5.7.0", + "@ethersproject/logger": "^5.7.0", + "@ethersproject/properties": "^5.7.0", + "bn.js": "^5.2.1", + "elliptic": "6.5.4", + "hash.js": "1.1.7" + }, + "dependencies": { + "bn.js": { + "version": "5.2.1", + "resolved": "https://registry.npmjs.org/bn.js/-/bn.js-5.2.1.tgz", + "integrity": "sha512-eXRvHzWyYPBuB4NBy0cmYQjGitUrtqwbvlzP3G6VFnNRbsZQIxQ10PbKKHt8gZ/HW/D/747aDl+QkDqg3KQLMQ==", + "dev": true + } + } + }, + "@ethersproject/solidity": { + "version": "5.7.0", + "resolved": "https://registry.npmjs.org/@ethersproject/solidity/-/solidity-5.7.0.tgz", + "integrity": "sha512-HmabMd2Dt/raavyaGukF4XxizWKhKQ24DoLtdNbBmNKUOPqwjsKQSdV9GQtj9CBEea9DlzETlVER1gYeXXBGaA==", + "dev": true, + "requires": { + "@ethersproject/bignumber": "^5.7.0", + "@ethersproject/bytes": "^5.7.0", + "@ethersproject/keccak256": "^5.7.0", + "@ethersproject/logger": "^5.7.0", + "@ethersproject/sha2": "^5.7.0", + "@ethersproject/strings": "^5.7.0" + } + }, + "@ethersproject/strings": { + "version": "5.7.0", + "resolved": "https://registry.npmjs.org/@ethersproject/strings/-/strings-5.7.0.tgz", + "integrity": "sha512-/9nu+lj0YswRNSH0NXYqrh8775XNyEdUQAuf3f+SmOrnVewcJ5SBNAjF7lpgehKi4abvNNXyf+HX86czCdJ8Mg==", + "dev": true, + "requires": { + "@ethersproject/bytes": "^5.7.0", + "@ethersproject/constants": "^5.7.0", + "@ethersproject/logger": "^5.7.0" + } + }, + "@ethersproject/transactions": { + "version": "5.7.0", + "resolved": "https://registry.npmjs.org/@ethersproject/transactions/-/transactions-5.7.0.tgz", + "integrity": "sha512-kmcNicCp1lp8qanMTC3RIikGgoJ80ztTyvtsFvCYpSCfkjhD0jZ2LOrnbcuxuToLIUYYf+4XwD1rP+B/erDIhQ==", + "dev": true, + "requires": { + "@ethersproject/address": "^5.7.0", + "@ethersproject/bignumber": "^5.7.0", + "@ethersproject/bytes": "^5.7.0", + "@ethersproject/constants": "^5.7.0", + "@ethersproject/keccak256": "^5.7.0", + "@ethersproject/logger": "^5.7.0", + "@ethersproject/properties": "^5.7.0", + "@ethersproject/rlp": "^5.7.0", + "@ethersproject/signing-key": "^5.7.0" + } + }, + "@ethersproject/units": { + "version": "5.7.0", + "resolved": "https://registry.npmjs.org/@ethersproject/units/-/units-5.7.0.tgz", + "integrity": "sha512-pD3xLMy3SJu9kG5xDGI7+xhTEmGXlEqXU4OfNapmfnxLVY4EMSSRp7j1k7eezutBPH7RBN/7QPnwR7hzNlEFeg==", + "dev": true, + "requires": { + "@ethersproject/bignumber": "^5.7.0", + "@ethersproject/constants": "^5.7.0", + "@ethersproject/logger": "^5.7.0" + } + }, + "@ethersproject/wallet": { + "version": "5.7.0", + "resolved": "https://registry.npmjs.org/@ethersproject/wallet/-/wallet-5.7.0.tgz", + "integrity": "sha512-MhmXlJXEJFBFVKrDLB4ZdDzxcBxQ3rLyCkhNqVu3CDYvR97E+8r01UgrI+TI99Le+aYm/in/0vp86guJuM7FCA==", + "dev": true, + "requires": { + "@ethersproject/abstract-provider": "^5.7.0", + "@ethersproject/abstract-signer": "^5.7.0", + "@ethersproject/address": "^5.7.0", + "@ethersproject/bignumber": "^5.7.0", + "@ethersproject/bytes": "^5.7.0", + "@ethersproject/hash": "^5.7.0", + "@ethersproject/hdnode": "^5.7.0", + "@ethersproject/json-wallets": "^5.7.0", + "@ethersproject/keccak256": "^5.7.0", + "@ethersproject/logger": "^5.7.0", + "@ethersproject/properties": "^5.7.0", + "@ethersproject/random": "^5.7.0", + "@ethersproject/signing-key": "^5.7.0", + "@ethersproject/transactions": "^5.7.0", + "@ethersproject/wordlists": "^5.7.0" + } + }, + "@ethersproject/web": { + "version": "5.7.1", + "resolved": "https://registry.npmjs.org/@ethersproject/web/-/web-5.7.1.tgz", + "integrity": "sha512-Gueu8lSvyjBWL4cYsWsjh6MtMwM0+H4HvqFPZfB6dV8ctbP9zFAO73VG1cMWae0FLPCtz0peKPpZY8/ugJJX2w==", + "dev": true, + "requires": { + "@ethersproject/base64": "^5.7.0", + "@ethersproject/bytes": "^5.7.0", + "@ethersproject/logger": "^5.7.0", + "@ethersproject/properties": "^5.7.0", + "@ethersproject/strings": "^5.7.0" + } + }, + "@ethersproject/wordlists": { + "version": "5.7.0", + "resolved": "https://registry.npmjs.org/@ethersproject/wordlists/-/wordlists-5.7.0.tgz", + "integrity": "sha512-S2TFNJNfHWVHNE6cNDjbVlZ6MgE17MIxMbMg2zv3wn+3XSJGosL1m9ZVv3GXCf/2ymSsQ+hRI5IzoMJTG6aoVA==", + "dev": true, + "requires": { + "@ethersproject/bytes": "^5.7.0", + "@ethersproject/hash": "^5.7.0", + "@ethersproject/logger": "^5.7.0", + "@ethersproject/properties": "^5.7.0", + "@ethersproject/strings": "^5.7.0" + } + }, + "@frangio/servbot": { + "version": "0.2.5", + "resolved": "https://registry.npmjs.org/@frangio/servbot/-/servbot-0.2.5.tgz", + "integrity": "sha512-ogja4iAPZ1VwM5MU3C1ZhB88358F0PGbmSTGOkIZwOyLaDoMHIqOVCnavHjR7DV5h+oAI4Z4KDqlam3myQUrmg==", + "dev": true + }, + "@humanwhocodes/config-array": { + "version": "0.11.10", + "resolved": "https://registry.npmjs.org/@humanwhocodes/config-array/-/config-array-0.11.10.tgz", + "integrity": "sha512-KVVjQmNUepDVGXNuoRRdmmEjruj0KfiGSbS8LVc12LMsWDQzRXJ0qdhN8L8uUigKpfEHRhlaQFY0ib1tnUbNeQ==", + "dev": true, + "requires": { + "@humanwhocodes/object-schema": "^1.2.1", + "debug": "^4.1.1", + "minimatch": "^3.0.5" + } + }, + "@humanwhocodes/module-importer": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/@humanwhocodes/module-importer/-/module-importer-1.0.1.tgz", + "integrity": "sha512-bxveV4V8v5Yb4ncFTT3rPSgZBOpCkjfK0y4oVVVJwIuDVBRMDXrPyXRL988i5ap9m9bnyEEjWfm5WkBmtffLfA==", + "dev": true + }, + "@humanwhocodes/object-schema": { + "version": "1.2.1", + "resolved": "https://registry.npmjs.org/@humanwhocodes/object-schema/-/object-schema-1.2.1.tgz", + "integrity": "sha512-ZnQMnLV4e7hDlUvw8H+U8ASL02SS2Gn6+9Ac3wGGLIe7+je2AeAOxPY+izIPJDfFDb7eDjev0Us8MO1iFRN8hA==", + "dev": true + }, + "@manypkg/find-root": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/@manypkg/find-root/-/find-root-1.1.0.tgz", + "integrity": "sha512-mki5uBvhHzO8kYYix/WRy2WX8S3B5wdVSc9D6KcU5lQNglP2yt58/VfLuAK49glRXChosY8ap2oJ1qgma3GUVA==", + "dev": true, + "requires": { + "@babel/runtime": "^7.5.5", + "@types/node": "^12.7.1", + "find-up": "^4.1.0", + "fs-extra": "^8.1.0" + }, + "dependencies": { + "fs-extra": { + "version": "8.1.0", + "resolved": "https://registry.npmjs.org/fs-extra/-/fs-extra-8.1.0.tgz", + "integrity": "sha512-yhlQgA6mnOJUKOsRUFsgJdQCvkKhcz8tlZG5HBQfReYZy46OwLcY+Zia0mtdHsOo9y/hP+CxMN0TU9QxoOtG4g==", + "dev": true, + "requires": { + "graceful-fs": "^4.2.0", + "jsonfile": "^4.0.0", + "universalify": "^0.1.0" + } + } + } + }, + "@manypkg/get-packages": { + "version": "1.1.3", + "resolved": "https://registry.npmjs.org/@manypkg/get-packages/-/get-packages-1.1.3.tgz", + "integrity": "sha512-fo+QhuU3qE/2TQMQmbVMqaQ6EWbMhi4ABWP+O4AM1NqPBuy0OrApV5LO6BrrgnhtAHS2NH6RrVk9OL181tTi8A==", + "dev": true, + "requires": { + "@babel/runtime": "^7.5.5", + "@changesets/types": "^4.0.1", + "@manypkg/find-root": "^1.1.0", + "fs-extra": "^8.1.0", + "globby": "^11.0.0", + "read-yaml-file": "^1.1.0" + }, + "dependencies": { + "@changesets/types": { + "version": "4.1.0", + "resolved": "https://registry.npmjs.org/@changesets/types/-/types-4.1.0.tgz", + "integrity": "sha512-LDQvVDv5Kb50ny2s25Fhm3d9QSZimsoUGBsUioj6MC3qbMUCuC8GPIvk/M6IvXx3lYhAs0lwWUQLb+VIEUCECw==", + "dev": true + }, + "fs-extra": { + "version": "8.1.0", + "resolved": "https://registry.npmjs.org/fs-extra/-/fs-extra-8.1.0.tgz", + "integrity": "sha512-yhlQgA6mnOJUKOsRUFsgJdQCvkKhcz8tlZG5HBQfReYZy46OwLcY+Zia0mtdHsOo9y/hP+CxMN0TU9QxoOtG4g==", + "dev": true, + "requires": { + "graceful-fs": "^4.2.0", + "jsonfile": "^4.0.0", + "universalify": "^0.1.0" + } + } + } + }, + "@metamask/eth-sig-util": { + "version": "4.0.1", + "resolved": "https://registry.npmjs.org/@metamask/eth-sig-util/-/eth-sig-util-4.0.1.tgz", + "integrity": "sha512-tghyZKLHZjcdlDqCA3gNZmLeR0XvOE9U1qoQO9ohyAZT6Pya+H9vkBPcsyXytmYLNgVoin7CKCmweo/R43V+tQ==", + "dev": true, + "requires": { + "ethereumjs-abi": "^0.6.8", + "ethereumjs-util": "^6.2.1", + "ethjs-util": "^0.1.6", + "tweetnacl": "^1.0.3", + "tweetnacl-util": "^0.15.1" + }, + "dependencies": { + "@types/bn.js": { + "version": "4.11.6", + "resolved": "https://registry.npmjs.org/@types/bn.js/-/bn.js-4.11.6.tgz", + "integrity": "sha512-pqr857jrp2kPuO9uRjZ3PwnJTjoQy+fcdxvBTvHm6dkmEL9q+hDD/2j/0ELOBPtPnS8LjCX0gI9nbl8lVkadpg==", + "dev": true, + "requires": { + "@types/node": "*" + } + }, + "ethereumjs-util": { + "version": "6.2.1", + "resolved": "https://registry.npmjs.org/ethereumjs-util/-/ethereumjs-util-6.2.1.tgz", + "integrity": "sha512-W2Ktez4L01Vexijrm5EB6w7dg4n/TgpoYU4avuT5T3Vmnw/eCRtiBrJfQYS/DCSvDIOLn2k57GcHdeBcgVxAqw==", + "dev": true, + "requires": { + "@types/bn.js": "^4.11.3", + "bn.js": "^4.11.0", + "create-hash": "^1.1.2", + "elliptic": "^6.5.2", + "ethereum-cryptography": "^0.1.3", + "ethjs-util": "0.1.6", + "rlp": "^2.2.3" + } + } + } + }, + "@noble/hashes": { + "version": "1.2.0", + "resolved": "https://registry.npmjs.org/@noble/hashes/-/hashes-1.2.0.tgz", + "integrity": "sha512-FZfhjEDbT5GRswV3C6uvLPHMiVD6lQBmpoX5+eSiPaMTXte/IKqI5dykDxzZB/WBeK/CDuQRBWarPdi3FNY2zQ==", + "dev": true + }, + "@noble/secp256k1": { + "version": "1.7.1", + "resolved": "https://registry.npmjs.org/@noble/secp256k1/-/secp256k1-1.7.1.tgz", + "integrity": "sha512-hOUk6AyBFmqVrv7k5WAw/LpszxVbj9gGN4JRkIX52fdFAj1UA61KXmZDvqVEm+pOyec3+fIeZB02LYa/pWOArw==", + "dev": true + }, + "@nodelib/fs.scandir": { + "version": "2.1.5", + "resolved": "https://registry.npmjs.org/@nodelib/fs.scandir/-/fs.scandir-2.1.5.tgz", + "integrity": "sha512-vq24Bq3ym5HEQm2NKCr3yXDwjc7vTsEThRDnkp2DK9p1uqLR+DHurm/NOTo0KG7HYHU7eppKZj3MyqYuMBf62g==", + "dev": true, + "requires": { + "@nodelib/fs.stat": "2.0.5", + "run-parallel": "^1.1.9" + } + }, + "@nodelib/fs.stat": { + "version": "2.0.5", + "resolved": "https://registry.npmjs.org/@nodelib/fs.stat/-/fs.stat-2.0.5.tgz", + "integrity": "sha512-RkhPPp2zrqDAQA/2jNhnztcPAlv64XdhIp7a7454A5ovI7Bukxgt7MX7udwAu3zg1DcpPU0rz3VV1SeaqvY4+A==", + "dev": true + }, + "@nodelib/fs.walk": { + "version": "1.2.8", + "resolved": "https://registry.npmjs.org/@nodelib/fs.walk/-/fs.walk-1.2.8.tgz", + "integrity": "sha512-oGB+UxlgWcgQkgwo8GcEGwemoTFt3FIO9ababBmaGwXIoBKZ+GTy0pP185beGg7Llih/NSHSV2XAs1lnznocSg==", + "dev": true, + "requires": { + "@nodelib/fs.scandir": "2.1.5", + "fastq": "^1.6.0" + } + }, + "@nomicfoundation/ethereumjs-block": { + "version": "5.0.1", + "resolved": "https://registry.npmjs.org/@nomicfoundation/ethereumjs-block/-/ethereumjs-block-5.0.1.tgz", + "integrity": "sha512-u1Yioemi6Ckj3xspygu/SfFvm8vZEO8/Yx5a1QLzi6nVU0jz3Pg2OmHKJ5w+D9Ogk1vhwRiqEBAqcb0GVhCyHw==", + "dev": true, + "requires": { + "@nomicfoundation/ethereumjs-common": "4.0.1", + "@nomicfoundation/ethereumjs-rlp": "5.0.1", + "@nomicfoundation/ethereumjs-trie": "6.0.1", + "@nomicfoundation/ethereumjs-tx": "5.0.1", + "@nomicfoundation/ethereumjs-util": "9.0.1", + "ethereum-cryptography": "0.1.3", + "ethers": "^5.7.1" + }, + "dependencies": { + "ethers": { + "version": "5.7.2", + "resolved": "https://registry.npmjs.org/ethers/-/ethers-5.7.2.tgz", + "integrity": "sha512-wswUsmWo1aOK8rR7DIKiWSw9DbLWe6x98Jrn8wcTflTVvaXhAMaB5zGAXy0GYQEQp9iO1iSHWVyARQm11zUtyg==", + "dev": true, + "requires": { + "@ethersproject/abi": "5.7.0", + "@ethersproject/abstract-provider": "5.7.0", + "@ethersproject/abstract-signer": "5.7.0", + "@ethersproject/address": "5.7.0", + "@ethersproject/base64": "5.7.0", + "@ethersproject/basex": "5.7.0", + "@ethersproject/bignumber": "5.7.0", + "@ethersproject/bytes": "5.7.0", + "@ethersproject/constants": "5.7.0", + "@ethersproject/contracts": "5.7.0", + "@ethersproject/hash": "5.7.0", + "@ethersproject/hdnode": "5.7.0", + "@ethersproject/json-wallets": "5.7.0", + "@ethersproject/keccak256": "5.7.0", + "@ethersproject/logger": "5.7.0", + "@ethersproject/networks": "5.7.1", + "@ethersproject/pbkdf2": "5.7.0", + "@ethersproject/properties": "5.7.0", + "@ethersproject/providers": "5.7.2", + "@ethersproject/random": "5.7.0", + "@ethersproject/rlp": "5.7.0", + "@ethersproject/sha2": "5.7.0", + "@ethersproject/signing-key": "5.7.0", + "@ethersproject/solidity": "5.7.0", + "@ethersproject/strings": "5.7.0", + "@ethersproject/transactions": "5.7.0", + "@ethersproject/units": "5.7.0", + "@ethersproject/wallet": "5.7.0", + "@ethersproject/web": "5.7.1", + "@ethersproject/wordlists": "5.7.0" + } + } + } + }, + "@nomicfoundation/ethereumjs-blockchain": { + "version": "7.0.1", + "resolved": "https://registry.npmjs.org/@nomicfoundation/ethereumjs-blockchain/-/ethereumjs-blockchain-7.0.1.tgz", + "integrity": "sha512-NhzndlGg829XXbqJEYrF1VeZhAwSPgsK/OB7TVrdzft3y918hW5KNd7gIZ85sn6peDZOdjBsAXIpXZ38oBYE5A==", + "dev": true, + "requires": { + "@nomicfoundation/ethereumjs-block": "5.0.1", + "@nomicfoundation/ethereumjs-common": "4.0.1", + "@nomicfoundation/ethereumjs-ethash": "3.0.1", + "@nomicfoundation/ethereumjs-rlp": "5.0.1", + "@nomicfoundation/ethereumjs-trie": "6.0.1", + "@nomicfoundation/ethereumjs-tx": "5.0.1", + "@nomicfoundation/ethereumjs-util": "9.0.1", + "abstract-level": "^1.0.3", + "debug": "^4.3.3", + "ethereum-cryptography": "0.1.3", + "level": "^8.0.0", + "lru-cache": "^5.1.1", + "memory-level": "^1.0.0" + } + }, + "@nomicfoundation/ethereumjs-common": { + "version": "4.0.1", + "resolved": "https://registry.npmjs.org/@nomicfoundation/ethereumjs-common/-/ethereumjs-common-4.0.1.tgz", + "integrity": "sha512-OBErlkfp54GpeiE06brBW/TTbtbuBJV5YI5Nz/aB2evTDo+KawyEzPjBlSr84z/8MFfj8wS2wxzQX1o32cev5g==", + "dev": true, + "requires": { + "@nomicfoundation/ethereumjs-util": "9.0.1", + "crc-32": "^1.2.0" + } + }, + "@nomicfoundation/ethereumjs-ethash": { + "version": "3.0.1", + "resolved": "https://registry.npmjs.org/@nomicfoundation/ethereumjs-ethash/-/ethereumjs-ethash-3.0.1.tgz", + "integrity": "sha512-KDjGIB5igzWOp8Ik5I6QiRH5DH+XgILlplsHR7TEuWANZA759G6krQ6o8bvj+tRUz08YygMQu/sGd9mJ1DYT8w==", + "dev": true, + "requires": { + "@nomicfoundation/ethereumjs-block": "5.0.1", + "@nomicfoundation/ethereumjs-rlp": "5.0.1", + "@nomicfoundation/ethereumjs-util": "9.0.1", + "abstract-level": "^1.0.3", + "bigint-crypto-utils": "^3.0.23", + "ethereum-cryptography": "0.1.3" + } + }, + "@nomicfoundation/ethereumjs-evm": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/@nomicfoundation/ethereumjs-evm/-/ethereumjs-evm-2.0.1.tgz", + "integrity": "sha512-oL8vJcnk0Bx/onl+TgQOQ1t/534GKFaEG17fZmwtPFeH8S5soiBYPCLUrvANOl4sCp9elYxIMzIiTtMtNNN8EQ==", + "dev": true, + "requires": { + "@ethersproject/providers": "^5.7.1", + "@nomicfoundation/ethereumjs-common": "4.0.1", + "@nomicfoundation/ethereumjs-tx": "5.0.1", + "@nomicfoundation/ethereumjs-util": "9.0.1", + "debug": "^4.3.3", + "ethereum-cryptography": "0.1.3", + "mcl-wasm": "^0.7.1", + "rustbn.js": "~0.2.0" + } + }, + "@nomicfoundation/ethereumjs-rlp": { + "version": "5.0.1", + "resolved": "https://registry.npmjs.org/@nomicfoundation/ethereumjs-rlp/-/ethereumjs-rlp-5.0.1.tgz", + "integrity": "sha512-xtxrMGa8kP4zF5ApBQBtjlSbN5E2HI8m8FYgVSYAnO6ssUoY5pVPGy2H8+xdf/bmMa22Ce8nWMH3aEW8CcqMeQ==", + "dev": true + }, + "@nomicfoundation/ethereumjs-statemanager": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/@nomicfoundation/ethereumjs-statemanager/-/ethereumjs-statemanager-2.0.1.tgz", + "integrity": "sha512-B5ApMOnlruVOR7gisBaYwFX+L/AP7i/2oAahatssjPIBVDF6wTX1K7Qpa39E/nzsH8iYuL3krkYeUFIdO3EMUQ==", + "dev": true, + "requires": { + "@nomicfoundation/ethereumjs-common": "4.0.1", + "@nomicfoundation/ethereumjs-rlp": "5.0.1", + "debug": "^4.3.3", + "ethereum-cryptography": "0.1.3", + "ethers": "^5.7.1", + "js-sdsl": "^4.1.4" + }, + "dependencies": { + "ethers": { + "version": "5.7.2", + "resolved": "https://registry.npmjs.org/ethers/-/ethers-5.7.2.tgz", + "integrity": "sha512-wswUsmWo1aOK8rR7DIKiWSw9DbLWe6x98Jrn8wcTflTVvaXhAMaB5zGAXy0GYQEQp9iO1iSHWVyARQm11zUtyg==", + "dev": true, + "requires": { + "@ethersproject/abi": "5.7.0", + "@ethersproject/abstract-provider": "5.7.0", + "@ethersproject/abstract-signer": "5.7.0", + "@ethersproject/address": "5.7.0", + "@ethersproject/base64": "5.7.0", + "@ethersproject/basex": "5.7.0", + "@ethersproject/bignumber": "5.7.0", + "@ethersproject/bytes": "5.7.0", + "@ethersproject/constants": "5.7.0", + "@ethersproject/contracts": "5.7.0", + "@ethersproject/hash": "5.7.0", + "@ethersproject/hdnode": "5.7.0", + "@ethersproject/json-wallets": "5.7.0", + "@ethersproject/keccak256": "5.7.0", + "@ethersproject/logger": "5.7.0", + "@ethersproject/networks": "5.7.1", + "@ethersproject/pbkdf2": "5.7.0", + "@ethersproject/properties": "5.7.0", + "@ethersproject/providers": "5.7.2", + "@ethersproject/random": "5.7.0", + "@ethersproject/rlp": "5.7.0", + "@ethersproject/sha2": "5.7.0", + "@ethersproject/signing-key": "5.7.0", + "@ethersproject/solidity": "5.7.0", + "@ethersproject/strings": "5.7.0", + "@ethersproject/transactions": "5.7.0", + "@ethersproject/units": "5.7.0", + "@ethersproject/wallet": "5.7.0", + "@ethersproject/web": "5.7.1", + "@ethersproject/wordlists": "5.7.0" + } + } + } + }, + "@nomicfoundation/ethereumjs-trie": { + "version": "6.0.1", + "resolved": "https://registry.npmjs.org/@nomicfoundation/ethereumjs-trie/-/ethereumjs-trie-6.0.1.tgz", + "integrity": "sha512-A64It/IMpDVODzCgxDgAAla8jNjNtsoQZIzZUfIV5AY6Coi4nvn7+VReBn5itlxMiL2yaTlQr9TRWp3CSI6VoA==", + "dev": true, + "requires": { + "@nomicfoundation/ethereumjs-rlp": "5.0.1", + "@nomicfoundation/ethereumjs-util": "9.0.1", + "@types/readable-stream": "^2.3.13", + "ethereum-cryptography": "0.1.3", + "readable-stream": "^3.6.0" + } + }, + "@nomicfoundation/ethereumjs-tx": { + "version": "5.0.1", + "resolved": "https://registry.npmjs.org/@nomicfoundation/ethereumjs-tx/-/ethereumjs-tx-5.0.1.tgz", + "integrity": "sha512-0HwxUF2u2hrsIM1fsasjXvlbDOq1ZHFV2dd1yGq8CA+MEYhaxZr8OTScpVkkxqMwBcc5y83FyPl0J9MZn3kY0w==", + "dev": true, + "requires": { + "@chainsafe/ssz": "^0.9.2", + "@ethersproject/providers": "^5.7.2", + "@nomicfoundation/ethereumjs-common": "4.0.1", + "@nomicfoundation/ethereumjs-rlp": "5.0.1", + "@nomicfoundation/ethereumjs-util": "9.0.1", + "ethereum-cryptography": "0.1.3" + } + }, + "@nomicfoundation/ethereumjs-util": { + "version": "9.0.1", + "resolved": "https://registry.npmjs.org/@nomicfoundation/ethereumjs-util/-/ethereumjs-util-9.0.1.tgz", + "integrity": "sha512-TwbhOWQ8QoSCFhV/DDfSmyfFIHjPjFBj957219+V3jTZYZ2rf9PmDtNOeZWAE3p3vlp8xb02XGpd0v6nTUPbsA==", + "dev": true, + "requires": { + "@chainsafe/ssz": "^0.10.0", + "@nomicfoundation/ethereumjs-rlp": "5.0.1", + "ethereum-cryptography": "0.1.3" + }, + "dependencies": { + "@chainsafe/persistent-merkle-tree": { + "version": "0.5.0", + "resolved": "https://registry.npmjs.org/@chainsafe/persistent-merkle-tree/-/persistent-merkle-tree-0.5.0.tgz", + "integrity": "sha512-l0V1b5clxA3iwQLXP40zYjyZYospQLZXzBVIhhr9kDg/1qHZfzzHw0jj4VPBijfYCArZDlPkRi1wZaV2POKeuw==", + "dev": true, + "requires": { + "@chainsafe/as-sha256": "^0.3.1" + } + }, + "@chainsafe/ssz": { + "version": "0.10.2", + "resolved": "https://registry.npmjs.org/@chainsafe/ssz/-/ssz-0.10.2.tgz", + "integrity": "sha512-/NL3Lh8K+0q7A3LsiFq09YXS9fPE+ead2rr7vM2QK8PLzrNsw3uqrif9bpRX5UxgeRjM+vYi+boCM3+GM4ovXg==", + "dev": true, + "requires": { + "@chainsafe/as-sha256": "^0.3.1", + "@chainsafe/persistent-merkle-tree": "^0.5.0" + } + } + } + }, + "@nomicfoundation/ethereumjs-vm": { + "version": "7.0.1", + "resolved": "https://registry.npmjs.org/@nomicfoundation/ethereumjs-vm/-/ethereumjs-vm-7.0.1.tgz", + "integrity": "sha512-rArhyn0jPsS/D+ApFsz3yVJMQ29+pVzNZ0VJgkzAZ+7FqXSRtThl1C1prhmlVr3YNUlfpZ69Ak+RUT4g7VoOuQ==", + "dev": true, + "requires": { + "@nomicfoundation/ethereumjs-block": "5.0.1", + "@nomicfoundation/ethereumjs-blockchain": "7.0.1", + "@nomicfoundation/ethereumjs-common": "4.0.1", + "@nomicfoundation/ethereumjs-evm": "2.0.1", + "@nomicfoundation/ethereumjs-rlp": "5.0.1", + "@nomicfoundation/ethereumjs-statemanager": "2.0.1", + "@nomicfoundation/ethereumjs-trie": "6.0.1", + "@nomicfoundation/ethereumjs-tx": "5.0.1", + "@nomicfoundation/ethereumjs-util": "9.0.1", + "debug": "^4.3.3", + "ethereum-cryptography": "0.1.3", + "mcl-wasm": "^0.7.1", + "rustbn.js": "~0.2.0" + } + }, + "@nomicfoundation/hardhat-network-helpers": { + "version": "1.0.8", + "resolved": "https://registry.npmjs.org/@nomicfoundation/hardhat-network-helpers/-/hardhat-network-helpers-1.0.8.tgz", + "integrity": "sha512-MNqQbzUJZnCMIYvlniC3U+kcavz/PhhQSsY90tbEtUyMj/IQqsLwIRZa4ctjABh3Bz0KCh9OXUZ7Yk/d9hr45Q==", + "dev": true, + "requires": { + "ethereumjs-util": "^7.1.4" + } + }, + "@nomicfoundation/solidity-analyzer": { + "version": "0.1.1", + "resolved": "https://registry.npmjs.org/@nomicfoundation/solidity-analyzer/-/solidity-analyzer-0.1.1.tgz", + "integrity": "sha512-1LMtXj1puAxyFusBgUIy5pZk3073cNXYnXUpuNKFghHbIit/xZgbk0AokpUADbNm3gyD6bFWl3LRFh3dhVdREg==", + "dev": true, + "requires": { + "@nomicfoundation/solidity-analyzer-darwin-arm64": "0.1.1", + "@nomicfoundation/solidity-analyzer-darwin-x64": "0.1.1", + "@nomicfoundation/solidity-analyzer-freebsd-x64": "0.1.1", + "@nomicfoundation/solidity-analyzer-linux-arm64-gnu": "0.1.1", + "@nomicfoundation/solidity-analyzer-linux-arm64-musl": "0.1.1", + "@nomicfoundation/solidity-analyzer-linux-x64-gnu": "0.1.1", + "@nomicfoundation/solidity-analyzer-linux-x64-musl": "0.1.1", + "@nomicfoundation/solidity-analyzer-win32-arm64-msvc": "0.1.1", + "@nomicfoundation/solidity-analyzer-win32-ia32-msvc": "0.1.1", + "@nomicfoundation/solidity-analyzer-win32-x64-msvc": "0.1.1" + } + }, + "@nomicfoundation/solidity-analyzer-darwin-arm64": { + "version": "0.1.1", + "resolved": "https://registry.npmjs.org/@nomicfoundation/solidity-analyzer-darwin-arm64/-/solidity-analyzer-darwin-arm64-0.1.1.tgz", + "integrity": "sha512-KcTodaQw8ivDZyF+D76FokN/HdpgGpfjc/gFCImdLUyqB6eSWVaZPazMbeAjmfhx3R0zm/NYVzxwAokFKgrc0w==", + "dev": true, + "optional": true + }, + "@nomicfoundation/solidity-analyzer-darwin-x64": { + "version": "0.1.1", + "resolved": "https://registry.npmjs.org/@nomicfoundation/solidity-analyzer-darwin-x64/-/solidity-analyzer-darwin-x64-0.1.1.tgz", + "integrity": "sha512-XhQG4BaJE6cIbjAVtzGOGbK3sn1BO9W29uhk9J8y8fZF1DYz0Doj8QDMfpMu+A6TjPDs61lbsmeYodIDnfveSA==", + "dev": true, + "optional": true + }, + "@nomicfoundation/solidity-analyzer-freebsd-x64": { + "version": "0.1.1", + "resolved": "https://registry.npmjs.org/@nomicfoundation/solidity-analyzer-freebsd-x64/-/solidity-analyzer-freebsd-x64-0.1.1.tgz", + "integrity": "sha512-GHF1VKRdHW3G8CndkwdaeLkVBi5A9u2jwtlS7SLhBc8b5U/GcoL39Q+1CSO3hYqePNP+eV5YI7Zgm0ea6kMHoA==", + "dev": true, + "optional": true + }, + "@nomicfoundation/solidity-analyzer-linux-arm64-gnu": { + "version": "0.1.1", + "resolved": "https://registry.npmjs.org/@nomicfoundation/solidity-analyzer-linux-arm64-gnu/-/solidity-analyzer-linux-arm64-gnu-0.1.1.tgz", + "integrity": "sha512-g4Cv2fO37ZsUENQ2vwPnZc2zRenHyAxHcyBjKcjaSmmkKrFr64yvzeNO8S3GBFCo90rfochLs99wFVGT/0owpg==", + "dev": true, + "optional": true + }, + "@nomicfoundation/solidity-analyzer-linux-arm64-musl": { + "version": "0.1.1", + "resolved": "https://registry.npmjs.org/@nomicfoundation/solidity-analyzer-linux-arm64-musl/-/solidity-analyzer-linux-arm64-musl-0.1.1.tgz", + "integrity": "sha512-WJ3CE5Oek25OGE3WwzK7oaopY8xMw9Lhb0mlYuJl/maZVo+WtP36XoQTb7bW/i8aAdHW5Z+BqrHMux23pvxG3w==", + "dev": true, + "optional": true + }, + "@nomicfoundation/solidity-analyzer-linux-x64-gnu": { + "version": "0.1.1", + "resolved": "https://registry.npmjs.org/@nomicfoundation/solidity-analyzer-linux-x64-gnu/-/solidity-analyzer-linux-x64-gnu-0.1.1.tgz", + "integrity": "sha512-5WN7leSr5fkUBBjE4f3wKENUy9HQStu7HmWqbtknfXkkil+eNWiBV275IOlpXku7v3uLsXTOKpnnGHJYI2qsdA==", + "dev": true, + "optional": true + }, + "@nomicfoundation/solidity-analyzer-linux-x64-musl": { + "version": "0.1.1", + "resolved": "https://registry.npmjs.org/@nomicfoundation/solidity-analyzer-linux-x64-musl/-/solidity-analyzer-linux-x64-musl-0.1.1.tgz", + "integrity": "sha512-KdYMkJOq0SYPQMmErv/63CwGwMm5XHenEna9X9aB8mQmhDBrYrlAOSsIPgFCUSL0hjxE3xHP65/EPXR/InD2+w==", + "dev": true, + "optional": true + }, + "@nomicfoundation/solidity-analyzer-win32-arm64-msvc": { + "version": "0.1.1", + "resolved": "https://registry.npmjs.org/@nomicfoundation/solidity-analyzer-win32-arm64-msvc/-/solidity-analyzer-win32-arm64-msvc-0.1.1.tgz", + "integrity": "sha512-VFZASBfl4qiBYwW5xeY20exWhmv6ww9sWu/krWSesv3q5hA0o1JuzmPHR4LPN6SUZj5vcqci0O6JOL8BPw+APg==", + "dev": true, + "optional": true + }, + "@nomicfoundation/solidity-analyzer-win32-ia32-msvc": { + "version": "0.1.1", + "resolved": "https://registry.npmjs.org/@nomicfoundation/solidity-analyzer-win32-ia32-msvc/-/solidity-analyzer-win32-ia32-msvc-0.1.1.tgz", + "integrity": "sha512-JnFkYuyCSA70j6Si6cS1A9Gh1aHTEb8kOTBApp/c7NRTFGNMH8eaInKlyuuiIbvYFhlXW4LicqyYuWNNq9hkpQ==", + "dev": true, + "optional": true + }, + "@nomicfoundation/solidity-analyzer-win32-x64-msvc": { + "version": "0.1.1", + "resolved": "https://registry.npmjs.org/@nomicfoundation/solidity-analyzer-win32-x64-msvc/-/solidity-analyzer-win32-x64-msvc-0.1.1.tgz", + "integrity": "sha512-HrVJr6+WjIXGnw3Q9u6KQcbZCtk0caVWhCdFADySvRyUxJ8PnzlaP+MhwNE8oyT8OZ6ejHBRrrgjSqDCFXGirw==", + "dev": true, + "optional": true + }, + "@nomiclabs/hardhat-truffle5": { + "version": "2.0.7", + "resolved": "https://registry.npmjs.org/@nomiclabs/hardhat-truffle5/-/hardhat-truffle5-2.0.7.tgz", + "integrity": "sha512-Pw8451IUZp1bTp0QqCHCYfCHs66sCnyxPcaorapu9mfOV9xnZsVaFdtutnhNEiXdiZwbed7LFKpRsde4BjFwig==", + "dev": true, + "requires": { + "@nomiclabs/truffle-contract": "^4.2.23", + "@types/chai": "^4.2.0", + "chai": "^4.2.0", + "ethereumjs-util": "^7.1.4", + "fs-extra": "^7.0.1" + } + }, + "@nomiclabs/hardhat-web3": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/@nomiclabs/hardhat-web3/-/hardhat-web3-2.0.0.tgz", + "integrity": "sha512-zt4xN+D+fKl3wW2YlTX3k9APR3XZgPkxJYf36AcliJn3oujnKEVRZaHu0PhgLjO+gR+F/kiYayo9fgd2L8970Q==", + "dev": true, + "requires": { + "@types/bignumber.js": "^5.0.0" + } + }, + "@nomiclabs/truffle-contract": { + "version": "4.5.10", + "resolved": "https://registry.npmjs.org/@nomiclabs/truffle-contract/-/truffle-contract-4.5.10.tgz", + "integrity": "sha512-nF/6InFV+0hUvutyFgsdOMCoYlr//2fJbRER4itxYtQtc4/O1biTwZIKRu+5l2J5Sq6LU2WX7vZHtDgQdhWxIQ==", + "dev": true, + "requires": { + "@ensdomains/ensjs": "^2.0.1", + "@truffle/blockchain-utils": "^0.1.3", + "@truffle/contract-schema": "^3.4.7", + "@truffle/debug-utils": "^6.0.22", + "@truffle/error": "^0.1.0", + "@truffle/interface-adapter": "^0.5.16", + "bignumber.js": "^7.2.1", + "ethereum-ens": "^0.8.0", + "ethers": "^4.0.0-beta.1", + "source-map-support": "^0.5.19" + } + }, + "@openzeppelin/contract-loader": { + "version": "0.6.3", + "resolved": "https://registry.npmjs.org/@openzeppelin/contract-loader/-/contract-loader-0.6.3.tgz", + "integrity": "sha512-cOFIjBjwbGgZhDZsitNgJl0Ye1rd5yu/Yx5LMgeq3u0ZYzldm4uObzHDFq4gjDdoypvyORjjJa3BlFA7eAnVIg==", + "dev": true, + "requires": { + "find-up": "^4.1.0", + "fs-extra": "^8.1.0" + }, + "dependencies": { + "fs-extra": { + "version": "8.1.0", + "resolved": "https://registry.npmjs.org/fs-extra/-/fs-extra-8.1.0.tgz", + "integrity": "sha512-yhlQgA6mnOJUKOsRUFsgJdQCvkKhcz8tlZG5HBQfReYZy46OwLcY+Zia0mtdHsOo9y/hP+CxMN0TU9QxoOtG4g==", + "dev": true, + "requires": { + "graceful-fs": "^4.2.0", + "jsonfile": "^4.0.0", + "universalify": "^0.1.0" + } + } + } + }, + "@openzeppelin/docs-utils": { + "version": "0.1.4", + "resolved": "https://registry.npmjs.org/@openzeppelin/docs-utils/-/docs-utils-0.1.4.tgz", + "integrity": "sha512-2I56U1GhnNlymz0gGmJbyZKhnErGIaJ+rqtKTGyNf7YX3jgeS9/Twv8H0T+OgLV4dimtCHPz/27w6CYhWQ/TGg==", + "dev": true, + "requires": { + "@frangio/servbot": "^0.2.5", + "chalk": "^3.0.0", + "chokidar": "^3.5.3", + "env-paths": "^2.2.0", + "find-up": "^4.1.0", + "is-port-reachable": "^3.0.0", + "js-yaml": "^3.13.1", + "lodash.startcase": "^4.4.0", + "minimist": "^1.2.0" + }, + "dependencies": { + "ansi-styles": { + "version": "4.3.0", + "resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-4.3.0.tgz", + "integrity": "sha512-zbB9rCJAT1rbjiVDb2hqKFHNYLxgtk8NURxZ3IZwD3F6NtxbXZQCnnSi1Lkx+IDohdPlFp222wVALIheZJQSEg==", + "dev": true, + "requires": { + "color-convert": "^2.0.1" + } + }, + "chalk": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/chalk/-/chalk-3.0.0.tgz", + "integrity": "sha512-4D3B6Wf41KOYRFdszmDqMCGq5VV/uMAB273JILmO+3jAlh8X4qDtdtgCR3fxtbLEMzSx22QdhnDcJvu2u1fVwg==", + "dev": true, + "requires": { + "ansi-styles": "^4.1.0", + "supports-color": "^7.1.0" + } + }, + "color-convert": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/color-convert/-/color-convert-2.0.1.tgz", + "integrity": "sha512-RRECPsj7iu/xb5oKYcsFHSppFNnsj/52OVTRKb4zP5onXwVF3zVmmToNcOfGC+CRDpfK/U584fMg38ZHCaElKQ==", + "dev": true, + "requires": { + "color-name": "~1.1.4" + } + }, + "color-name": { + "version": "1.1.4", + "resolved": "https://registry.npmjs.org/color-name/-/color-name-1.1.4.tgz", + "integrity": "sha512-dOy+3AuW3a2wNbZHIuMZpTcgjGuLU/uBL/ubcZF9OXbDo8ff4O8yVp5Bf0efS8uEoYo5q4Fx7dY9OgQGXgAsQA==", + "dev": true + }, + "has-flag": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/has-flag/-/has-flag-4.0.0.tgz", + "integrity": "sha512-EykJT/Q1KjTWctppgIAgfSO0tKVuZUjhgMr17kqTumMl6Afv3EISleU7qZUzoXDFTAHTDC4NOoG/ZxU3EvlMPQ==", + "dev": true + }, + "supports-color": { + "version": "7.2.0", + "resolved": "https://registry.npmjs.org/supports-color/-/supports-color-7.2.0.tgz", + "integrity": "sha512-qpCAvRl9stuOHveKsn7HncJRvv501qIacKzQlO/+Lwxc9+0q2wLyv4Dfvt80/DPn2pqOBsJdDiogXGR9+OvwRw==", + "dev": true, + "requires": { + "has-flag": "^4.0.0" + } + } + } + }, + "@openzeppelin/test-helpers": { + "version": "0.5.16", + "resolved": "https://registry.npmjs.org/@openzeppelin/test-helpers/-/test-helpers-0.5.16.tgz", + "integrity": "sha512-T1EvspSfH1qQO/sgGlskLfYVBbqzJR23SZzYl/6B2JnT4EhThcI85UpvDk0BkLWKaDScQTabGHt4GzHW+3SfZg==", + "dev": true, + "requires": { + "@openzeppelin/contract-loader": "^0.6.2", + "@truffle/contract": "^4.0.35", + "ansi-colors": "^3.2.3", + "chai": "^4.2.0", + "chai-bn": "^0.2.1", + "ethjs-abi": "^0.2.1", + "lodash.flatten": "^4.4.0", + "semver": "^5.6.0", + "web3": "^1.2.5", + "web3-utils": "^1.2.5" + }, + "dependencies": { + "ansi-colors": { + "version": "3.2.4", + "resolved": "https://registry.npmjs.org/ansi-colors/-/ansi-colors-3.2.4.tgz", + "integrity": "sha512-hHUXGagefjN2iRrID63xckIvotOXOojhQKWIPUZ4mNUZ9nLZW+7FMNoE1lOkEhNWYsx/7ysGIuJYCiMAA9FnrA==", + "dev": true + }, + "semver": { + "version": "5.7.1", + "resolved": "https://registry.npmjs.org/semver/-/semver-5.7.1.tgz", + "integrity": "sha512-sauaDf/PZdVgrLTNYHRtpXa1iRiKcaebiKQ1BJdpQlWH2lCvexQdX55snPFyK7QzpudqbCI0qXFfOasHdyNDGQ==", + "dev": true + } + } + }, + "@openzeppelin/upgrades-core": { + "version": "1.27.1", + "resolved": "https://registry.npmjs.org/@openzeppelin/upgrades-core/-/upgrades-core-1.27.1.tgz", + "integrity": "sha512-6tLcu6jt0nYdJNr+LRicBgP3jp+//B+dixgB3KsvycSglCHNfmBNDf0ZQ3ZquDdLL0QQmKzIs1EBRVp6lNvPnQ==", + "dev": true, + "requires": { + "cbor": "^8.0.0", + "chalk": "^4.1.0", + "compare-versions": "^5.0.0", + "debug": "^4.1.1", + "ethereumjs-util": "^7.0.3", + "minimist": "^1.2.7", + "proper-lockfile": "^4.1.1", + "solidity-ast": "^0.4.15" + }, + "dependencies": { + "ansi-styles": { + "version": "4.3.0", + "resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-4.3.0.tgz", + "integrity": "sha512-zbB9rCJAT1rbjiVDb2hqKFHNYLxgtk8NURxZ3IZwD3F6NtxbXZQCnnSi1Lkx+IDohdPlFp222wVALIheZJQSEg==", + "dev": true, + "requires": { + "color-convert": "^2.0.1" + } + }, + "chalk": { + "version": "4.1.2", + "resolved": "https://registry.npmjs.org/chalk/-/chalk-4.1.2.tgz", + "integrity": "sha512-oKnbhFyRIXpUuez8iBMmyEa4nbj4IOQyuhc/wy9kY7/WVPcwIO9VA668Pu8RkO7+0G76SLROeyw9CpQ061i4mA==", + "dev": true, + "requires": { + "ansi-styles": "^4.1.0", + "supports-color": "^7.1.0" + } + }, + "color-convert": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/color-convert/-/color-convert-2.0.1.tgz", + "integrity": "sha512-RRECPsj7iu/xb5oKYcsFHSppFNnsj/52OVTRKb4zP5onXwVF3zVmmToNcOfGC+CRDpfK/U584fMg38ZHCaElKQ==", + "dev": true, + "requires": { + "color-name": "~1.1.4" + } + }, + "color-name": { + "version": "1.1.4", + "resolved": "https://registry.npmjs.org/color-name/-/color-name-1.1.4.tgz", + "integrity": "sha512-dOy+3AuW3a2wNbZHIuMZpTcgjGuLU/uBL/ubcZF9OXbDo8ff4O8yVp5Bf0efS8uEoYo5q4Fx7dY9OgQGXgAsQA==", + "dev": true + }, + "has-flag": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/has-flag/-/has-flag-4.0.0.tgz", + "integrity": "sha512-EykJT/Q1KjTWctppgIAgfSO0tKVuZUjhgMr17kqTumMl6Afv3EISleU7qZUzoXDFTAHTDC4NOoG/ZxU3EvlMPQ==", + "dev": true + }, + "supports-color": { + "version": "7.2.0", + "resolved": "https://registry.npmjs.org/supports-color/-/supports-color-7.2.0.tgz", + "integrity": "sha512-qpCAvRl9stuOHveKsn7HncJRvv501qIacKzQlO/+Lwxc9+0q2wLyv4Dfvt80/DPn2pqOBsJdDiogXGR9+OvwRw==", + "dev": true, + "requires": { + "has-flag": "^4.0.0" + } + } + } + }, + "@scure/base": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/@scure/base/-/base-1.1.1.tgz", + "integrity": "sha512-ZxOhsSyxYwLJj3pLZCefNitxsj093tb2vq90mp2txoYeBqbcjDjqFhyM8eUjq/uFm6zJ+mUuqxlS2FkuSY1MTA==", + "dev": true + }, + "@scure/bip32": { + "version": "1.1.5", + "resolved": "https://registry.npmjs.org/@scure/bip32/-/bip32-1.1.5.tgz", + "integrity": "sha512-XyNh1rB0SkEqd3tXcXMi+Xe1fvg+kUIcoRIEujP1Jgv7DqW2r9lg3Ah0NkFaCs9sTkQAQA8kw7xiRXzENi9Rtw==", + "dev": true, + "requires": { + "@noble/hashes": "~1.2.0", + "@noble/secp256k1": "~1.7.0", + "@scure/base": "~1.1.0" + } + }, + "@scure/bip39": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/@scure/bip39/-/bip39-1.1.1.tgz", + "integrity": "sha512-t+wDck2rVkh65Hmv280fYdVdY25J9YeEUIgn2LG1WM6gxFkGzcksoDiUkWVpVp3Oex9xGC68JU2dSbUfwZ2jPg==", + "dev": true, + "requires": { + "@noble/hashes": "~1.2.0", + "@scure/base": "~1.1.0" + } + }, + "@sentry/core": { + "version": "5.30.0", + "resolved": "https://registry.npmjs.org/@sentry/core/-/core-5.30.0.tgz", + "integrity": "sha512-TmfrII8w1PQZSZgPpUESqjB+jC6MvZJZdLtE/0hZ+SrnKhW3x5WlYLvTXZpcWePYBku7rl2wn1RZu6uT0qCTeg==", + "dev": true, + "requires": { + "@sentry/hub": "5.30.0", + "@sentry/minimal": "5.30.0", + "@sentry/types": "5.30.0", + "@sentry/utils": "5.30.0", + "tslib": "^1.9.3" + } + }, + "@sentry/hub": { + "version": "5.30.0", + "resolved": "https://registry.npmjs.org/@sentry/hub/-/hub-5.30.0.tgz", + "integrity": "sha512-2tYrGnzb1gKz2EkMDQcfLrDTvmGcQPuWxLnJKXJvYTQDGLlEvi2tWz1VIHjunmOvJrB5aIQLhm+dcMRwFZDCqQ==", + "dev": true, + "requires": { + "@sentry/types": "5.30.0", + "@sentry/utils": "5.30.0", + "tslib": "^1.9.3" + } + }, + "@sentry/minimal": { + "version": "5.30.0", + "resolved": "https://registry.npmjs.org/@sentry/minimal/-/minimal-5.30.0.tgz", + "integrity": "sha512-BwWb/owZKtkDX+Sc4zCSTNcvZUq7YcH3uAVlmh/gtR9rmUvbzAA3ewLuB3myi4wWRAMEtny6+J/FN/x+2wn9Xw==", + "dev": true, + "requires": { + "@sentry/hub": "5.30.0", + "@sentry/types": "5.30.0", + "tslib": "^1.9.3" + } + }, + "@sentry/node": { + "version": "5.30.0", + "resolved": "https://registry.npmjs.org/@sentry/node/-/node-5.30.0.tgz", + "integrity": "sha512-Br5oyVBF0fZo6ZS9bxbJZG4ApAjRqAnqFFurMVJJdunNb80brh7a5Qva2kjhm+U6r9NJAB5OmDyPkA1Qnt+QVg==", + "dev": true, + "requires": { + "@sentry/core": "5.30.0", + "@sentry/hub": "5.30.0", + "@sentry/tracing": "5.30.0", + "@sentry/types": "5.30.0", + "@sentry/utils": "5.30.0", + "cookie": "^0.4.1", + "https-proxy-agent": "^5.0.0", + "lru_map": "^0.3.3", + "tslib": "^1.9.3" + } + }, + "@sentry/tracing": { + "version": "5.30.0", + "resolved": "https://registry.npmjs.org/@sentry/tracing/-/tracing-5.30.0.tgz", + "integrity": "sha512-dUFowCr0AIMwiLD7Fs314Mdzcug+gBVo/+NCMyDw8tFxJkwWAKl7Qa2OZxLQ0ZHjakcj1hNKfCQJ9rhyfOl4Aw==", + "dev": true, + "requires": { + "@sentry/hub": "5.30.0", + "@sentry/minimal": "5.30.0", + "@sentry/types": "5.30.0", + "@sentry/utils": "5.30.0", + "tslib": "^1.9.3" + } + }, + "@sentry/types": { + "version": "5.30.0", + "resolved": "https://registry.npmjs.org/@sentry/types/-/types-5.30.0.tgz", + "integrity": "sha512-R8xOqlSTZ+htqrfteCWU5Nk0CDN5ApUTvrlvBuiH1DyP6czDZ4ktbZB0hAgBlVcK0U+qpD3ag3Tqqpa5Q67rPw==", + "dev": true + }, + "@sentry/utils": { + "version": "5.30.0", + "resolved": "https://registry.npmjs.org/@sentry/utils/-/utils-5.30.0.tgz", + "integrity": "sha512-zaYmoH0NWWtvnJjC9/CBseXMtKHm/tm40sz3YfJRxeQjyzRqNQPgivpd9R/oDJCYj999mzdW382p/qi2ypjLww==", + "dev": true, + "requires": { + "@sentry/types": "5.30.0", + "tslib": "^1.9.3" + } + }, + "@sindresorhus/is": { + "version": "4.6.0", + "resolved": "https://registry.npmjs.org/@sindresorhus/is/-/is-4.6.0.tgz", + "integrity": "sha512-t09vSN3MdfsyCHoFcTRCH/iUtG7OJ0CsjzB8cjAmKc/va/kIgeDI/TxsigdncE/4be734m0cvIYwNaV4i2XqAw==", + "dev": true + }, + "@solidity-parser/parser": { + "version": "0.14.5", + "resolved": "https://registry.npmjs.org/@solidity-parser/parser/-/parser-0.14.5.tgz", + "integrity": "sha512-6dKnHZn7fg/iQATVEzqyUOyEidbn05q7YA2mQ9hC0MMXhhV3/JrsxmFSYZAcr7j1yUP700LLhTruvJ3MiQmjJg==", + "dev": true, + "requires": { + "antlr4ts": "^0.5.0-alpha.4" + } + }, + "@szmarczak/http-timer": { + "version": "5.0.1", + "resolved": "https://registry.npmjs.org/@szmarczak/http-timer/-/http-timer-5.0.1.tgz", + "integrity": "sha512-+PmQX0PiAYPMeVYe237LJAYvOMYW1j2rH5YROyS3b4CTVJum34HfRvKvAzozHAQG0TnHNdUfY9nCeUyRAs//cw==", + "dev": true, + "requires": { + "defer-to-connect": "^2.0.1" + } + }, + "@truffle/abi-utils": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/@truffle/abi-utils/-/abi-utils-1.0.1.tgz", + "integrity": "sha512-ZQUY3XUxEPdqxNaoXsOqF0spTtb6f5RNlnN4MUrVsJ64sOh0FJsY7rxZiUI3khfePmNh4i2qcJrQlKT36YcWUA==", + "dev": true, + "requires": { + "change-case": "3.0.2", + "fast-check": "3.1.1", + "web3-utils": "1.10.0" + } + }, + "@truffle/blockchain-utils": { + "version": "0.1.8", + "resolved": "https://registry.npmjs.org/@truffle/blockchain-utils/-/blockchain-utils-0.1.8.tgz", + "integrity": "sha512-ZskpYDNHkXD3ota4iU3pZz6kLth87RC+wDn66Rp2Or+DqqJCKdnmS9GDctBi1EcMPDEi0BqpkdrfBuzA9uIkGg==", + "dev": true + }, + "@truffle/codec": { + "version": "0.17.0", + "resolved": "https://registry.npmjs.org/@truffle/codec/-/codec-0.17.0.tgz", + "integrity": "sha512-0Z7DQNCnvW++JuvNj35v/CuJoaFSAp7/+lXWwe+Zoe++E27V+hzRI88ZYxRJa0/q1HE81epd1r0ipqc7WBotig==", + "dev": true, + "requires": { + "@truffle/abi-utils": "^1.0.1", + "@truffle/compile-common": "^0.9.6", + "big.js": "^6.0.3", + "bn.js": "^5.1.3", + "cbor": "^5.2.0", + "debug": "^4.3.1", + "lodash": "^4.17.21", + "semver": "7.5.2", + "utf8": "^3.0.0", + "web3-utils": "1.10.0" + }, + "dependencies": { + "bignumber.js": { + "version": "9.1.1", + "resolved": "https://registry.npmjs.org/bignumber.js/-/bignumber.js-9.1.1.tgz", + "integrity": "sha512-pHm4LsMJ6lzgNGVfZHjMoO8sdoRhOzOH4MLmY65Jg70bpxCKu5iOHNJyfF6OyvYw7t8Fpf35RuzUyqnQsj8Vig==", + "dev": true + }, + "bn.js": { + "version": "5.2.1", + "resolved": "https://registry.npmjs.org/bn.js/-/bn.js-5.2.1.tgz", + "integrity": "sha512-eXRvHzWyYPBuB4NBy0cmYQjGitUrtqwbvlzP3G6VFnNRbsZQIxQ10PbKKHt8gZ/HW/D/747aDl+QkDqg3KQLMQ==", + "dev": true + }, + "cbor": { + "version": "5.2.0", + "resolved": "https://registry.npmjs.org/cbor/-/cbor-5.2.0.tgz", + "integrity": "sha512-5IMhi9e1QU76ppa5/ajP1BmMWZ2FHkhAhjeVKQ/EFCgYSEaeVaoGtL7cxJskf9oCCk+XjzaIdc3IuU/dbA/o2A==", + "dev": true, + "requires": { + "bignumber.js": "^9.0.1", + "nofilter": "^1.0.4" + } + }, + "lru-cache": { + "version": "6.0.0", + "resolved": "https://registry.npmjs.org/lru-cache/-/lru-cache-6.0.0.tgz", + "integrity": "sha512-Jo6dJ04CmSjuznwJSS3pUeWmd/H0ffTlkXXgwZi+eq1UCmqQwCh+eLsYOYCwY991i2Fah4h1BEMCx4qThGbsiA==", + "dev": true, + "requires": { + "yallist": "^4.0.0" + } + }, + "nofilter": { + "version": "1.0.4", + "resolved": "https://registry.npmjs.org/nofilter/-/nofilter-1.0.4.tgz", + "integrity": "sha512-N8lidFp+fCz+TD51+haYdbDGrcBWwuHX40F5+z0qkUjMJ5Tp+rdSuAkMJ9N9eoolDlEVTf6u5icM+cNKkKW2mA==", + "dev": true + }, + "semver": { + "version": "7.5.2", + "resolved": "https://registry.npmjs.org/semver/-/semver-7.5.2.tgz", + "integrity": "sha512-SoftuTROv/cRjCze/scjGyiDtcUyxw1rgYQSZY7XTmtR5hX+dm76iDbTH8TkLPHCQmlbQVSSbNZCPM2hb0knnQ==", + "dev": true, + "requires": { + "lru-cache": "^6.0.0" + } + }, + "yallist": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/yallist/-/yallist-4.0.0.tgz", + "integrity": "sha512-3wdGidZyq5PB084XLES5TpOSRA3wjXAlIWMhum2kRcv/41Sn2emQ0dycQW4uZXLejwKvg6EsvbdlVL+FYEct7A==", + "dev": true + } + } + }, + "@truffle/compile-common": { + "version": "0.9.6", + "resolved": "https://registry.npmjs.org/@truffle/compile-common/-/compile-common-0.9.6.tgz", + "integrity": "sha512-TCcmr1E0GqMZJ2tOaCRNEllxTBJ/g7TuD6jDJpw5Gt9Bw0YO3Cmp6yPQRynRSO4xMJbHUgiEsSfRgIhswut5UA==", + "dev": true, + "requires": { + "@truffle/error": "^0.2.1", + "colors": "1.4.0" + }, + "dependencies": { + "@truffle/error": { + "version": "0.2.1", + "resolved": "https://registry.npmjs.org/@truffle/error/-/error-0.2.1.tgz", + "integrity": "sha512-5Qy+z9dg9hP37WNdLnXH4b9MzemWrjTufRq7/DTKqimjyxCP/1zlL8gQEMdiSx1BBtAZz0xypkID/jb7AF/Osg==", + "dev": true + } + } + }, + "@truffle/contract": { + "version": "4.6.26", + "resolved": "https://registry.npmjs.org/@truffle/contract/-/contract-4.6.26.tgz", + "integrity": "sha512-B3KM8fW9dKJCzMRD40r+u+iqQtBGFbcMr2GML31iUkjC77Wn/KlM9cCGZiuXcOquWmBlKrpD4nJCoGirPhyPTQ==", + "dev": true, + "requires": { + "@ensdomains/ensjs": "^2.1.0", + "@truffle/blockchain-utils": "^0.1.8", + "@truffle/contract-schema": "^3.4.14", + "@truffle/debug-utils": "^6.0.54", + "@truffle/error": "^0.2.1", + "@truffle/interface-adapter": "^0.5.34", + "bignumber.js": "^7.2.1", + "debug": "^4.3.1", + "ethers": "^4.0.32", + "web3": "1.10.0", + "web3-core-helpers": "1.10.0", + "web3-core-promievent": "1.10.0", + "web3-eth-abi": "1.10.0", + "web3-utils": "1.10.0" + }, + "dependencies": { + "@truffle/error": { + "version": "0.2.1", + "resolved": "https://registry.npmjs.org/@truffle/error/-/error-0.2.1.tgz", + "integrity": "sha512-5Qy+z9dg9hP37WNdLnXH4b9MzemWrjTufRq7/DTKqimjyxCP/1zlL8gQEMdiSx1BBtAZz0xypkID/jb7AF/Osg==", + "dev": true + } + } + }, + "@truffle/contract-schema": { + "version": "3.4.14", + "resolved": "https://registry.npmjs.org/@truffle/contract-schema/-/contract-schema-3.4.14.tgz", + "integrity": "sha512-IwVQZG9RVNwTdn321+jbFIcky3/kZLkCtq8tqil4jZwivvmZQg8rIVC8GJ7Lkrmixl9/yTyQNL6GtIUUvkZxyA==", + "dev": true, + "requires": { + "ajv": "^6.10.0", + "debug": "^4.3.1" + } + }, + "@truffle/debug-utils": { + "version": "6.0.54", + "resolved": "https://registry.npmjs.org/@truffle/debug-utils/-/debug-utils-6.0.54.tgz", + "integrity": "sha512-ENv5TQQv+CJrwSX9AdXXTDHVNHpPfH+yCpRSnM3Sg0dx7IeWJAjGA66/BiucNBUiAgLhV2EcvkMo+4tEPoR+YQ==", + "dev": true, + "requires": { + "@truffle/codec": "^0.17.0", + "@trufflesuite/chromafi": "^3.0.0", + "bn.js": "^5.1.3", + "chalk": "^2.4.2", + "debug": "^4.3.1", + "highlightjs-solidity": "^2.0.6" + }, + "dependencies": { + "bn.js": { + "version": "5.2.1", + "resolved": "https://registry.npmjs.org/bn.js/-/bn.js-5.2.1.tgz", + "integrity": "sha512-eXRvHzWyYPBuB4NBy0cmYQjGitUrtqwbvlzP3G6VFnNRbsZQIxQ10PbKKHt8gZ/HW/D/747aDl+QkDqg3KQLMQ==", + "dev": true + } + } + }, + "@truffle/error": { + "version": "0.1.1", + "resolved": "https://registry.npmjs.org/@truffle/error/-/error-0.1.1.tgz", + "integrity": "sha512-sE7c9IHIGdbK4YayH4BC8i8qMjoAOeg6nUXUDZZp8wlU21/EMpaG+CLx+KqcIPyR+GSWIW3Dm0PXkr2nlggFDA==", + "dev": true + }, + "@truffle/interface-adapter": { + "version": "0.5.34", + "resolved": "https://registry.npmjs.org/@truffle/interface-adapter/-/interface-adapter-0.5.34.tgz", + "integrity": "sha512-gPxabfMi2TueE4VxnNuyeudOfvGJQ1ofVC02PFw14cnRQhzH327JikjjQbZ1bT6S7kWl9H6P3hQPFeYFMHdm1g==", + "dev": true, + "requires": { + "bn.js": "^5.1.3", + "ethers": "^4.0.32", + "web3": "1.10.0" + }, + "dependencies": { + "bn.js": { + "version": "5.2.1", + "resolved": "https://registry.npmjs.org/bn.js/-/bn.js-5.2.1.tgz", + "integrity": "sha512-eXRvHzWyYPBuB4NBy0cmYQjGitUrtqwbvlzP3G6VFnNRbsZQIxQ10PbKKHt8gZ/HW/D/747aDl+QkDqg3KQLMQ==", + "dev": true + } + } + }, + "@trufflesuite/chromafi": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/@trufflesuite/chromafi/-/chromafi-3.0.0.tgz", + "integrity": "sha512-oqWcOqn8nT1bwlPPfidfzS55vqcIDdpfzo3HbU9EnUmcSTX+I8z0UyUFI3tZQjByVJulbzxHxUGS3ZJPwK/GPQ==", + "dev": true, + "requires": { + "camelcase": "^4.1.0", + "chalk": "^2.3.2", + "cheerio": "^1.0.0-rc.2", + "detect-indent": "^5.0.0", + "highlight.js": "^10.4.1", + "lodash.merge": "^4.6.2", + "strip-ansi": "^4.0.0", + "strip-indent": "^2.0.0" + }, + "dependencies": { + "detect-indent": { + "version": "5.0.0", + "resolved": "https://registry.npmjs.org/detect-indent/-/detect-indent-5.0.0.tgz", + "integrity": "sha512-rlpvsxUtM0PQvy9iZe640/IWwWYyBsTApREbA1pHOpmOUIl9MkP/U4z7vTtg4Oaojvqhxt7sdufnT0EzGaR31g==", + "dev": true + } + } + }, + "@types/bignumber.js": { + "version": "5.0.0", + "resolved": "https://registry.npmjs.org/@types/bignumber.js/-/bignumber.js-5.0.0.tgz", + "integrity": "sha512-0DH7aPGCClywOFaxxjE6UwpN2kQYe9LwuDQMv+zYA97j5GkOMo8e66LYT+a8JYU7jfmUFRZLa9KycxHDsKXJCA==", + "dev": true, + "requires": { + "bignumber.js": "*" + } + }, + "@types/bn.js": { + "version": "5.1.1", + "resolved": "https://registry.npmjs.org/@types/bn.js/-/bn.js-5.1.1.tgz", + "integrity": "sha512-qNrYbZqMx0uJAfKnKclPh+dTwK33KfLHYqtyODwd5HnXOjnkhc4qgn3BrK6RWyGZm5+sIFE7Q7Vz6QQtJB7w7g==", + "dev": true, + "requires": { + "@types/node": "*" + } + }, + "@types/cacheable-request": { + "version": "6.0.3", + "resolved": "https://registry.npmjs.org/@types/cacheable-request/-/cacheable-request-6.0.3.tgz", + "integrity": "sha512-IQ3EbTzGxIigb1I3qPZc1rWJnH0BmSKv5QYTalEwweFvyBDLSAe24zP0le/hyi7ecGfZVlIVAg4BZqb8WBwKqw==", + "dev": true, + "requires": { + "@types/http-cache-semantics": "*", + "@types/keyv": "^3.1.4", + "@types/node": "*", + "@types/responselike": "^1.0.0" + } + }, + "@types/chai": { + "version": "4.3.5", + "resolved": "https://registry.npmjs.org/@types/chai/-/chai-4.3.5.tgz", + "integrity": "sha512-mEo1sAde+UCE6b2hxn332f1g1E8WfYRu6p5SvTKr2ZKC1f7gFJXk4h5PyGP9Dt6gCaG8y8XhwnXWC6Iy2cmBng==", + "dev": true + }, + "@types/concat-stream": { + "version": "1.6.1", + "resolved": "https://registry.npmjs.org/@types/concat-stream/-/concat-stream-1.6.1.tgz", + "integrity": "sha512-eHE4cQPoj6ngxBZMvVf6Hw7Mh4jMW4U9lpGmS5GBPB9RYxlFg+CHaVN7ErNY4W9XfLIEn20b4VDYaIrbq0q4uA==", + "dev": true, + "requires": { + "@types/node": "*" + } + }, + "@types/form-data": { + "version": "0.0.33", + "resolved": "https://registry.npmjs.org/@types/form-data/-/form-data-0.0.33.tgz", + "integrity": "sha512-8BSvG1kGm83cyJITQMZSulnl6QV8jqAGreJsc5tPu1Jq0vTSOiY/k24Wx82JRpWwZSqrala6sd5rWi6aNXvqcw==", + "dev": true, + "requires": { + "@types/node": "*" + } + }, + "@types/glob": { + "version": "7.2.0", + "resolved": "https://registry.npmjs.org/@types/glob/-/glob-7.2.0.tgz", + "integrity": "sha512-ZUxbzKl0IfJILTS6t7ip5fQQM/J3TJYubDm3nMbgubNNYS62eXeUpoLUC8/7fJNiFYHTrGPQn7hspDUzIHX3UA==", + "dev": true, + "requires": { + "@types/minimatch": "*", + "@types/node": "*" + } + }, + "@types/http-cache-semantics": { + "version": "4.0.1", + "resolved": "https://registry.npmjs.org/@types/http-cache-semantics/-/http-cache-semantics-4.0.1.tgz", + "integrity": "sha512-SZs7ekbP8CN0txVG2xVRH6EgKmEm31BOxA07vkFaETzZz1xh+cbt8BcI0slpymvwhx5dlFnQG2rTlPVQn+iRPQ==", + "dev": true + }, + "@types/is-ci": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/@types/is-ci/-/is-ci-3.0.0.tgz", + "integrity": "sha512-Q0Op0hdWbYd1iahB+IFNQcWXFq4O0Q5MwQP7uN0souuQ4rPg1vEYcnIOfr1gY+M+6rc8FGoRaBO1mOOvL29sEQ==", + "dev": true, + "requires": { + "ci-info": "^3.1.0" + } + }, + "@types/keyv": { + "version": "3.1.4", + "resolved": "https://registry.npmjs.org/@types/keyv/-/keyv-3.1.4.tgz", + "integrity": "sha512-BQ5aZNSCpj7D6K2ksrRCTmKRLEpnPvWDiLPfoGyhZ++8YtiK9d/3DBKPJgry359X/P1PfruyYwvnvwFjuEiEIg==", + "dev": true, + "requires": { + "@types/node": "*" + } + }, + "@types/lru-cache": { + "version": "5.1.1", + "resolved": "https://registry.npmjs.org/@types/lru-cache/-/lru-cache-5.1.1.tgz", + "integrity": "sha512-ssE3Vlrys7sdIzs5LOxCzTVMsU7i9oa/IaW92wF32JFb3CVczqOkru2xspuKczHEbG3nvmPY7IFqVmGGHdNbYw==", + "dev": true + }, + "@types/minimatch": { + "version": "5.1.2", + "resolved": "https://registry.npmjs.org/@types/minimatch/-/minimatch-5.1.2.tgz", + "integrity": "sha512-K0VQKziLUWkVKiRVrx4a40iPaxTUefQmjtkQofBkYRcoaaL/8rhwDWww9qWbrgicNOgnpIsMxyNIUM4+n6dUIA==", + "dev": true + }, + "@types/minimist": { + "version": "1.2.2", + "resolved": "https://registry.npmjs.org/@types/minimist/-/minimist-1.2.2.tgz", + "integrity": "sha512-jhuKLIRrhvCPLqwPcx6INqmKeiA5EWrsCOPhrlFSrbrmU4ZMPjj5Ul/oLCMDO98XRUIwVm78xICz4EPCektzeQ==", + "dev": true + }, + "@types/node": { + "version": "12.20.55", + "resolved": "https://registry.npmjs.org/@types/node/-/node-12.20.55.tgz", + "integrity": "sha512-J8xLz7q2OFulZ2cyGTLE1TbbZcjpno7FaN6zdJNrgAdrJ+DZzh/uFR6YrTb4C+nXakvud8Q4+rbhoIWlYQbUFQ==", + "dev": true + }, + "@types/normalize-package-data": { + "version": "2.4.1", + "resolved": "https://registry.npmjs.org/@types/normalize-package-data/-/normalize-package-data-2.4.1.tgz", + "integrity": "sha512-Gj7cI7z+98M282Tqmp2K5EIsoouUEzbBJhQQzDE3jSIRk6r9gsz0oUokqIUR4u1R3dMHo0pDHM7sNOHyhulypw==", + "dev": true + }, + "@types/pbkdf2": { + "version": "3.1.0", + "resolved": "https://registry.npmjs.org/@types/pbkdf2/-/pbkdf2-3.1.0.tgz", + "integrity": "sha512-Cf63Rv7jCQ0LaL8tNXmEyqTHuIJxRdlS5vMh1mj5voN4+QFhVZnlZruezqpWYDiJ8UTzhP0VmeLXCmBk66YrMQ==", + "dev": true, + "requires": { + "@types/node": "*" + } + }, + "@types/qs": { + "version": "6.9.7", + "resolved": "https://registry.npmjs.org/@types/qs/-/qs-6.9.7.tgz", + "integrity": "sha512-FGa1F62FT09qcrueBA6qYTrJPVDzah9a+493+o2PCXsesWHIn27G98TsSMs3WPNbZIEj4+VJf6saSFpvD+3Zsw==", + "dev": true + }, + "@types/readable-stream": { + "version": "2.3.15", + "resolved": "https://registry.npmjs.org/@types/readable-stream/-/readable-stream-2.3.15.tgz", + "integrity": "sha512-oM5JSKQCcICF1wvGgmecmHldZ48OZamtMxcGGVICOJA8o8cahXC1zEVAif8iwoc5j8etxFaRFnf095+CDsuoFQ==", + "dev": true, + "requires": { + "@types/node": "*", + "safe-buffer": "~5.1.1" + }, + "dependencies": { + "safe-buffer": { + "version": "5.1.2", + "resolved": "https://registry.npmjs.org/safe-buffer/-/safe-buffer-5.1.2.tgz", + "integrity": "sha512-Gd2UZBJDkXlY7GbJxfsE8/nvKkUEU1G38c1siN6QP6a9PT9MmHB8GnpscSmMJSoF8LOIrt8ud/wPtojys4G6+g==", + "dev": true + } + } + }, + "@types/responselike": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/@types/responselike/-/responselike-1.0.0.tgz", + "integrity": "sha512-85Y2BjiufFzaMIlvJDvTTB8Fxl2xfLo4HgmHzVBz08w4wDePCTjYw66PdrolO0kzli3yam/YCgRufyo1DdQVTA==", + "dev": true, + "requires": { + "@types/node": "*" + } + }, + "@types/secp256k1": { + "version": "4.0.3", + "resolved": "https://registry.npmjs.org/@types/secp256k1/-/secp256k1-4.0.3.tgz", + "integrity": "sha512-Da66lEIFeIz9ltsdMZcpQvmrmmoqrfju8pm1BH8WbYjZSwUgCwXLb9C+9XYogwBITnbsSaMdVPb2ekf7TV+03w==", + "dev": true, + "requires": { + "@types/node": "*" + } + }, + "@types/semver": { + "version": "7.5.0", + "resolved": "https://registry.npmjs.org/@types/semver/-/semver-7.5.0.tgz", + "integrity": "sha512-G8hZ6XJiHnuhQKR7ZmysCeJWE08o8T0AXtk5darsCaTVsYZhhgUrq53jizaR2FvsoeCwJhlmwTjkXBY5Pn/ZHw==", + "dev": true + }, + "abbrev": { + "version": "1.0.9", + "resolved": "https://registry.npmjs.org/abbrev/-/abbrev-1.0.9.tgz", + "integrity": "sha512-LEyx4aLEC3x6T0UguF6YILf+ntvmOaWsVfENmIW0E9H09vKlLDGelMjjSm0jkDHALj8A8quZ/HapKNigzwge+Q==", + "dev": true + }, + "abort-controller": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/abort-controller/-/abort-controller-3.0.0.tgz", + "integrity": "sha512-h8lQ8tacZYnR3vNQTgibj+tODHI5/+l06Au2Pcriv/Gmet0eaj4TwWH41sO9wnHDiQsEj19q0drzdWdeAHtweg==", + "dev": true, + "requires": { + "event-target-shim": "^5.0.0" + } + }, + "abortcontroller-polyfill": { + "version": "1.7.5", + "resolved": "https://registry.npmjs.org/abortcontroller-polyfill/-/abortcontroller-polyfill-1.7.5.tgz", + "integrity": "sha512-JMJ5soJWP18htbbxJjG7bG6yuI6pRhgJ0scHHTfkUjf6wjP912xZWvM+A4sJK3gqd9E8fcPbDnOefbA9Th/FIQ==", + "dev": true + }, + "abstract-level": { + "version": "1.0.3", + "resolved": "https://registry.npmjs.org/abstract-level/-/abstract-level-1.0.3.tgz", + "integrity": "sha512-t6jv+xHy+VYwc4xqZMn2Pa9DjcdzvzZmQGRjTFc8spIbRGHgBrEKbPq+rYXc7CCo0lxgYvSgKVg9qZAhpVQSjA==", + "dev": true, + "requires": { + "buffer": "^6.0.3", + "catering": "^2.1.0", + "is-buffer": "^2.0.5", + "level-supports": "^4.0.0", + "level-transcoder": "^1.0.1", + "module-error": "^1.0.1", + "queue-microtask": "^1.2.3" + }, + "dependencies": { + "buffer": { + "version": "6.0.3", + "resolved": "https://registry.npmjs.org/buffer/-/buffer-6.0.3.tgz", + "integrity": "sha512-FTiCpNxtwiZZHEZbcbTIcZjERVICn9yq/pDFkTl95/AxzD1naBctN7YO68riM/gLSDY7sdrMby8hofADYuuqOA==", + "dev": true, + "requires": { + "base64-js": "^1.3.1", + "ieee754": "^1.2.1" + } + } + } + }, + "accepts": { + "version": "1.3.8", + "resolved": "https://registry.npmjs.org/accepts/-/accepts-1.3.8.tgz", + "integrity": "sha512-PYAthTa2m2VKxuvSD3DPC/Gy+U+sOA1LAuT8mkmRuvw+NACSaeXEQ+NHcVF7rONl6qcaxV3Uuemwawk+7+SJLw==", + "dev": true, + "requires": { + "mime-types": "~2.1.34", + "negotiator": "0.6.3" + } + }, + "acorn": { + "version": "8.10.0", + "resolved": "https://registry.npmjs.org/acorn/-/acorn-8.10.0.tgz", + "integrity": "sha512-F0SAmZ8iUtS//m8DmCTA0jlh6TDKkHQyK6xc6V4KDTyZKA9dnvX9/3sRTVQrWm79glUAZbnmmNcdYwUIHWVybw==", + "dev": true + }, + "acorn-jsx": { + "version": "5.3.2", + "resolved": "https://registry.npmjs.org/acorn-jsx/-/acorn-jsx-5.3.2.tgz", + "integrity": "sha512-rq9s+JNhf0IChjtDXxllJ7g41oZk5SlXtp0LHwyA5cejwn7vKmKp4pPri6YEePv2PU65sAsegbXtIinmDFDXgQ==", + "dev": true, + "requires": {} + }, + "address": { + "version": "1.2.2", + "resolved": "https://registry.npmjs.org/address/-/address-1.2.2.tgz", + "integrity": "sha512-4B/qKCfeE/ODUaAUpSwfzazo5x29WD4r3vXiWsB7I2mSDAihwEqKO+g8GELZUQSSAo5e1XTYh3ZVfLyxBc12nA==", + "dev": true + }, + "adm-zip": { + "version": "0.4.16", + "resolved": "https://registry.npmjs.org/adm-zip/-/adm-zip-0.4.16.tgz", + "integrity": "sha512-TFi4HBKSGfIKsK5YCkKaaFG2m4PEDyViZmEwof3MTIgzimHLto6muaHVpbrljdIvIrFZzEq/p4nafOeLcYegrg==", + "dev": true + }, + "aes-js": { + "version": "3.1.2", + "resolved": "https://registry.npmjs.org/aes-js/-/aes-js-3.1.2.tgz", + "integrity": "sha512-e5pEa2kBnBOgR4Y/p20pskXI74UEz7de8ZGVo58asOtvSVG5YAbJeELPZxOmt+Bnz3rX753YKhfIn4X4l1PPRQ==", + "dev": true + }, + "agent-base": { + "version": "6.0.2", + "resolved": "https://registry.npmjs.org/agent-base/-/agent-base-6.0.2.tgz", + "integrity": "sha512-RZNwNclF7+MS/8bDg70amg32dyeZGZxiDuQmZxKLAlQjr3jGyLx+4Kkk58UO7D2QdgFIQCovuSuZESne6RG6XQ==", + "dev": true, + "requires": { + "debug": "4" + } + }, + "aggregate-error": { + "version": "3.1.0", + "resolved": "https://registry.npmjs.org/aggregate-error/-/aggregate-error-3.1.0.tgz", + "integrity": "sha512-4I7Td01quW/RpocfNayFdFVk1qSuoh0E7JrbRJ16nH01HhKFQ88INq9Sd+nd72zqRySlr9BmDA8xlEJ6vJMrYA==", + "dev": true, + "requires": { + "clean-stack": "^2.0.0", + "indent-string": "^4.0.0" + } + }, + "ajv": { + "version": "6.12.6", + "resolved": "https://registry.npmjs.org/ajv/-/ajv-6.12.6.tgz", + "integrity": "sha512-j3fVLgvTo527anyYyJOGTYJbG+vnnQYvE0m5mmkc1TK+nxAppkCLMIL0aZ4dblVCNoGShhm+kzE4ZUykBoMg4g==", + "dev": true, + "requires": { + "fast-deep-equal": "^3.1.1", + "fast-json-stable-stringify": "^2.0.0", + "json-schema-traverse": "^0.4.1", + "uri-js": "^4.2.2" + } + }, + "amdefine": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/amdefine/-/amdefine-1.0.1.tgz", + "integrity": "sha512-S2Hw0TtNkMJhIabBwIojKL9YHO5T0n5eNqWJ7Lrlel/zDbftQpxpapi8tZs3X1HWa+u+QeydGmzzNU0m09+Rcg==", + "dev": true, + "optional": true + }, + "ansi-colors": { + "version": "4.1.3", + "resolved": "https://registry.npmjs.org/ansi-colors/-/ansi-colors-4.1.3.tgz", + "integrity": "sha512-/6w/C21Pm1A7aZitlI5Ni/2J6FFQN8i1Cvz3kHABAAbw93v/NlvKdVOqz7CCWz/3iv/JplRSEEZ83XION15ovw==", + "dev": true + }, + "ansi-escapes": { + "version": "4.3.2", + "resolved": "https://registry.npmjs.org/ansi-escapes/-/ansi-escapes-4.3.2.tgz", + "integrity": "sha512-gKXj5ALrKWQLsYG9jlTRmR/xKluxHV+Z9QEwNIgCfM1/uwPMCuzVVnh5mwTd+OuBZcwSIMbqssNWRm1lE51QaQ==", + "dev": true, + "requires": { + "type-fest": "^0.21.3" + }, + "dependencies": { + "type-fest": { + "version": "0.21.3", + "resolved": "https://registry.npmjs.org/type-fest/-/type-fest-0.21.3.tgz", + "integrity": "sha512-t0rzBq87m3fVcduHDUFhKmyyX+9eo6WQjZvf51Ea/M0Q7+T374Jp1aUiyUl0GKxp8M/OETVHSDvmkyPgvX+X2w==", + "dev": true + } + } + }, + "ansi-regex": { + "version": "3.0.1", + "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-3.0.1.tgz", + "integrity": "sha512-+O9Jct8wf++lXxxFc4hc8LsjaSq0HFzzL7cVsw8pRDIPdjKD2mT4ytDZlLuSBZ4cLKZFXIrMGO7DbQCtMJJMKw==", + "dev": true + }, + "ansi-styles": { + "version": "3.2.1", + "resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-3.2.1.tgz", + "integrity": "sha512-VT0ZI6kZRdTh8YyJw3SMbYm/u+NqfsAxEpWO0Pf9sq8/e94WxxOpPKx9FR1FlyCtOVDNOQ+8ntlqFxiRc+r5qA==", + "dev": true, + "requires": { + "color-convert": "^1.9.0" + } + }, + "antlr4": { + "version": "4.13.0", + "resolved": "https://registry.npmjs.org/antlr4/-/antlr4-4.13.0.tgz", + "integrity": "sha512-zooUbt+UscjnWyOrsuY/tVFL4rwrAGwOivpQmvmUDE22hy/lUA467Rc1rcixyRwcRUIXFYBwv7+dClDSHdmmew==", + "dev": true + }, + "antlr4ts": { + "version": "0.5.0-alpha.4", + "resolved": "https://registry.npmjs.org/antlr4ts/-/antlr4ts-0.5.0-alpha.4.tgz", + "integrity": "sha512-WPQDt1B74OfPv/IMS2ekXAKkTZIHl88uMetg6q3OTqgFxZ/dxDXI0EWLyZid/1Pe6hTftyg5N7gel5wNAGxXyQ==", + "dev": true + }, + "anymatch": { + "version": "3.1.3", + "resolved": "https://registry.npmjs.org/anymatch/-/anymatch-3.1.3.tgz", + "integrity": "sha512-KMReFUr0B4t+D+OBkjR3KYqvocp2XaSzO55UcB6mgQMd3KbcE+mWTyvVV7D/zsdEbNnV6acZUutkiHQXvTr1Rw==", + "dev": true, + "requires": { + "normalize-path": "^3.0.0", + "picomatch": "^2.0.4" + } + }, + "argparse": { + "version": "1.0.10", + "resolved": "https://registry.npmjs.org/argparse/-/argparse-1.0.10.tgz", + "integrity": "sha512-o5Roy6tNG4SL/FOkCAN6RzjiakZS25RLYFrcMttJqbdd8BWrnA+fGz57iN5Pb06pvBGvl5gQ0B48dJlslXvoTg==", + "dev": true, + "requires": { + "sprintf-js": "~1.0.2" + } + }, + "array-buffer-byte-length": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/array-buffer-byte-length/-/array-buffer-byte-length-1.0.0.tgz", + "integrity": "sha512-LPuwb2P+NrQw3XhxGc36+XSvuBPopovXYTR9Ew++Du9Yb/bx5AzBfrIsBoj0EZUifjQU+sHL21sseZ3jerWO/A==", + "dev": true, + "requires": { + "call-bind": "^1.0.2", + "is-array-buffer": "^3.0.1" + } + }, + "array-flatten": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/array-flatten/-/array-flatten-1.1.1.tgz", + "integrity": "sha512-PCVAQswWemu6UdxsDFFX/+gVeYqKAod3D3UVm91jHwynguOwAvYPhx8nNlM++NqRcK6CxxpUafjmhIdKiHibqg==", + "dev": true + }, + "array-union": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/array-union/-/array-union-2.1.0.tgz", + "integrity": "sha512-HGyxoOTYUyCM6stUe6EJgnd4EoewAI7zMdfqO+kGjnlZmBDz/cR5pf8r/cR4Wq60sL/p0IkcjUEEPwS3GFrIyw==", + "dev": true + }, + "array-uniq": { + "version": "1.0.3", + "resolved": "https://registry.npmjs.org/array-uniq/-/array-uniq-1.0.3.tgz", + "integrity": "sha512-MNha4BWQ6JbwhFhj03YK552f7cb3AzoE8SzeljgChvL1dl3IcvggXVz1DilzySZkCja+CXuZbdW7yATchWn8/Q==", + "dev": true + }, + "array.prototype.at": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/array.prototype.at/-/array.prototype.at-1.1.1.tgz", + "integrity": "sha512-n/wYNLJy/fVEU9EGPt2ww920hy1XX3XB2yTREFy1QsxctBgQV/tZIwg1G8jVxELna4pLCzg/xvvS/DDXtI4NNg==", + "dev": true, + "requires": { + "call-bind": "^1.0.2", + "define-properties": "^1.1.4", + "es-abstract": "^1.20.4", + "es-shim-unscopables": "^1.0.0" + } + }, + "array.prototype.findlast": { + "version": "1.2.2", + "resolved": "https://registry.npmjs.org/array.prototype.findlast/-/array.prototype.findlast-1.2.2.tgz", + "integrity": "sha512-p1YDNPNqA+P6cPX9ATsxg7DKir7gOmJ+jh5dEP3LlumMNYVC1F2Jgnyh6oI3n/qD9FeIkqR2jXfd73G68ImYUQ==", + "dev": true, + "requires": { + "call-bind": "^1.0.2", + "define-properties": "^1.1.4", + "es-abstract": "^1.20.4", + "es-shim-unscopables": "^1.0.0", + "get-intrinsic": "^1.1.3" + } + }, + "array.prototype.flat": { + "version": "1.3.1", + "resolved": "https://registry.npmjs.org/array.prototype.flat/-/array.prototype.flat-1.3.1.tgz", + "integrity": "sha512-roTU0KWIOmJ4DRLmwKd19Otg0/mT3qPNt0Qb3GWW8iObuZXxrjB/pzn0R3hqpRSWg4HCwqx+0vwOnWnvlOyeIA==", + "dev": true, + "requires": { + "call-bind": "^1.0.2", + "define-properties": "^1.1.4", + "es-abstract": "^1.20.4", + "es-shim-unscopables": "^1.0.0" + } + }, + "array.prototype.reduce": { + "version": "1.0.5", + "resolved": "https://registry.npmjs.org/array.prototype.reduce/-/array.prototype.reduce-1.0.5.tgz", + "integrity": "sha512-kDdugMl7id9COE8R7MHF5jWk7Dqt/fs4Pv+JXoICnYwqpjjjbUurz6w5fT5IG6brLdJhv6/VoHB0H7oyIBXd+Q==", + "dev": true, + "requires": { + "call-bind": "^1.0.2", + "define-properties": "^1.1.4", + "es-abstract": "^1.20.4", + "es-array-method-boxes-properly": "^1.0.0", + "is-string": "^1.0.7" + } + }, + "arrify": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/arrify/-/arrify-1.0.1.tgz", + "integrity": "sha512-3CYzex9M9FGQjCGMGyi6/31c8GJbgb0qGyrx5HWxPd0aCwh4cB2YjMb2Xf9UuoogrMrlO9cTqnB5rI5GHZTcUA==", + "dev": true + }, + "asap": { + "version": "2.0.6", + "resolved": "https://registry.npmjs.org/asap/-/asap-2.0.6.tgz", + "integrity": "sha512-BSHWgDSAiKs50o2Re8ppvp3seVHXSRM44cdSsT9FfNEUUZLOGWVCsiWaRPWM1Znn+mqZ1OfVZ3z3DWEzSp7hRA==", + "dev": true + }, + "asn1": { + "version": "0.2.6", + "resolved": "https://registry.npmjs.org/asn1/-/asn1-0.2.6.tgz", + "integrity": "sha512-ix/FxPn0MDjeyJ7i/yoHGFt/EX6LyNbxSEhPPXODPL+KB0VPk86UYfL0lMdy+KCnv+fmvIzySwaK5COwqVbWTQ==", + "dev": true, + "requires": { + "safer-buffer": "~2.1.0" + } + }, + "assert-plus": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/assert-plus/-/assert-plus-1.0.0.tgz", + "integrity": "sha512-NfJ4UzBCcQGLDlQq7nHxH+tv3kyZ0hHQqF5BO6J7tNJeP5do1llPr8dZ8zHonfhAu0PHAdMkSo+8o0wxg9lZWw==", + "dev": true + }, + "assertion-error": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/assertion-error/-/assertion-error-1.1.0.tgz", + "integrity": "sha512-jgsaNduz+ndvGyFt3uSuWqvy4lCnIJiovtouQN5JZHOKCS2QuhEdbcQHFhVksz2N2U9hXJo8odG7ETyWlEeuDw==", + "dev": true + }, + "ast-parents": { + "version": "0.0.1", + "resolved": "https://registry.npmjs.org/ast-parents/-/ast-parents-0.0.1.tgz", + "integrity": "sha512-XHusKxKz3zoYk1ic8Un640joHbFMhbqneyoZfoKnEGtf2ey9Uh/IdpcQplODdO/kENaMIWsD0nJm4+wX3UNLHA==", + "dev": true + }, + "astral-regex": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/astral-regex/-/astral-regex-2.0.0.tgz", + "integrity": "sha512-Z7tMw1ytTXt5jqMcOP+OQteU1VuNK9Y02uuJtKQ1Sv69jXQKKg5cibLwGJow8yzZP+eAc18EmLGPal0bp36rvQ==", + "dev": true + }, + "async": { + "version": "1.5.2", + "resolved": "https://registry.npmjs.org/async/-/async-1.5.2.tgz", + "integrity": "sha512-nSVgobk4rv61R9PUSDtYt7mPVB2olxNR5RWJcAsH676/ef11bUZwvu7+RGYrYauVdDPcO519v68wRhXQtxsV9w==", + "dev": true + }, + "async-limiter": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/async-limiter/-/async-limiter-1.0.1.tgz", + "integrity": "sha512-csOlWGAcRFJaI6m+F2WKdnMKr4HhdhFVBk0H/QbJFMCr+uO2kwohwXQPxw/9OCxp05r5ghVBFSyioixx3gfkNQ==", + "dev": true + }, + "asynckit": { + "version": "0.4.0", + "resolved": "https://registry.npmjs.org/asynckit/-/asynckit-0.4.0.tgz", + "integrity": "sha512-Oei9OH4tRh0YqU3GxhX79dM/mwVgvbZJaSNaRk+bshkj0S5cfHcgYakreBjrHwatXKbz+IoIdYLxrKim2MjW0Q==", + "dev": true + }, + "available-typed-arrays": { + "version": "1.0.5", + "resolved": "https://registry.npmjs.org/available-typed-arrays/-/available-typed-arrays-1.0.5.tgz", + "integrity": "sha512-DMD0KiN46eipeziST1LPP/STfDU0sufISXmjSgvVsoU2tqxctQeASejWcfNtxYKqETM1UxQ8sp2OrSBWpHY6sw==", + "dev": true + }, + "aws-sign2": { + "version": "0.7.0", + "resolved": "https://registry.npmjs.org/aws-sign2/-/aws-sign2-0.7.0.tgz", + "integrity": "sha512-08kcGqnYf/YmjoRhfxyu+CLxBjUtHLXLXX/vUfx9l2LYzG3c1m61nrpyFUZI6zeS+Li/wWMMidD9KgrqtGq3mA==", + "dev": true + }, + "aws4": { + "version": "1.12.0", + "resolved": "https://registry.npmjs.org/aws4/-/aws4-1.12.0.tgz", + "integrity": "sha512-NmWvPnx0F1SfrQbYwOi7OeaNGokp9XhzNioJ/CSBs8Qa4vxug81mhJEAVZwxXuBmYB5KDRfMq/F3RR0BIU7sWg==", + "dev": true + }, + "balanced-match": { + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/balanced-match/-/balanced-match-1.0.2.tgz", + "integrity": "sha512-3oSeUO0TMV67hN1AmbXsK4yaqU7tjiHlbxRDZOpH0KW9+CeX4bRAaX0Anxt0tx2MrpRpWwQaPwIlISEJhYU5Pw==", + "dev": true + }, + "base-x": { + "version": "3.0.9", + "resolved": "https://registry.npmjs.org/base-x/-/base-x-3.0.9.tgz", + "integrity": "sha512-H7JU6iBHTal1gp56aKoaa//YUxEaAOUiydvrV/pILqIHXTtqxSkATOnDA2u+jZ/61sD+L/412+7kzXRtWukhpQ==", + "dev": true, + "requires": { + "safe-buffer": "^5.0.1" + } + }, + "base64-js": { + "version": "1.5.1", + "resolved": "https://registry.npmjs.org/base64-js/-/base64-js-1.5.1.tgz", + "integrity": "sha512-AKpaYlHn8t4SVbOHCy+b5+KKgvR4vrsD8vbvrbiQJps7fKDTkjkDry6ji0rUJjC0kzbNePLwzxq8iypo41qeWA==", + "dev": true + }, + "bcrypt-pbkdf": { + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/bcrypt-pbkdf/-/bcrypt-pbkdf-1.0.2.tgz", + "integrity": "sha512-qeFIXtP4MSoi6NLqO12WfqARWWuCKi2Rn/9hJLEmtB5yTNr9DqFWkJRCf2qShWzPeAMRnOgCrq0sg/KLv5ES9w==", + "dev": true, + "requires": { + "tweetnacl": "^0.14.3" + }, + "dependencies": { + "tweetnacl": { + "version": "0.14.5", + "resolved": "https://registry.npmjs.org/tweetnacl/-/tweetnacl-0.14.5.tgz", + "integrity": "sha512-KXXFFdAbFXY4geFIwoyNK+f5Z1b7swfXABfL7HXCmoIWMKU3dmS26672A4EeQtDzLKy7SXmfBu51JolvEKwtGA==", + "dev": true + } + } + }, + "bech32": { + "version": "1.1.4", + "resolved": "https://registry.npmjs.org/bech32/-/bech32-1.1.4.tgz", + "integrity": "sha512-s0IrSOzLlbvX7yp4WBfPITzpAU8sqQcpsmwXDiKwrG4r491vwCO/XpejasRNl0piBMe/DvP4Tz0mIS/X1DPJBQ==", + "dev": true + }, + "better-path-resolve": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/better-path-resolve/-/better-path-resolve-1.0.0.tgz", + "integrity": "sha512-pbnl5XzGBdrFU/wT4jqmJVPn2B6UHPBOhzMQkY/SPUPB6QtUXtmBHBIwCbXJol93mOpGMnQyP/+BB19q04xj7g==", + "dev": true, + "requires": { + "is-windows": "^1.0.0" + } + }, + "big-integer": { + "version": "1.6.36", + "resolved": "https://registry.npmjs.org/big-integer/-/big-integer-1.6.36.tgz", + "integrity": "sha512-t70bfa7HYEA1D9idDbmuv7YbsbVkQ+Hp+8KFSul4aE5e/i1bjCNIRYJZlA8Q8p0r9T8cF/RVvwUgRA//FydEyg==", + "dev": true + }, + "big.js": { + "version": "6.2.1", + "resolved": "https://registry.npmjs.org/big.js/-/big.js-6.2.1.tgz", + "integrity": "sha512-bCtHMwL9LeDIozFn+oNhhFoq+yQ3BNdnsLSASUxLciOb1vgvpHsIO1dsENiGMgbb4SkP5TrzWzRiLddn8ahVOQ==", + "dev": true + }, + "bigint-crypto-utils": { + "version": "3.3.0", + "resolved": "https://registry.npmjs.org/bigint-crypto-utils/-/bigint-crypto-utils-3.3.0.tgz", + "integrity": "sha512-jOTSb+drvEDxEq6OuUybOAv/xxoh3cuYRUIPyu8sSHQNKM303UQ2R1DAo45o1AkcIXw6fzbaFI1+xGGdaXs2lg==", + "dev": true + }, + "bignumber.js": { + "version": "7.2.1", + "resolved": "https://registry.npmjs.org/bignumber.js/-/bignumber.js-7.2.1.tgz", + "integrity": "sha512-S4XzBk5sMB+Rcb/LNcpzXr57VRTxgAvaAEDAl1AwRx27j00hT84O6OkteE7u8UB3NuaaygCRrEpqox4uDOrbdQ==", + "dev": true + }, + "binary-extensions": { + "version": "2.2.0", + "resolved": "https://registry.npmjs.org/binary-extensions/-/binary-extensions-2.2.0.tgz", + "integrity": "sha512-jDctJ/IVQbZoJykoeHbhXpOlNBqGNcwXJKJog42E5HDPUwQTSdjCHdihjj0DlnheQ7blbT6dHOafNAiS8ooQKA==", + "dev": true + }, + "blakejs": { + "version": "1.2.1", + "resolved": "https://registry.npmjs.org/blakejs/-/blakejs-1.2.1.tgz", + "integrity": "sha512-QXUSXI3QVc/gJME0dBpXrag1kbzOqCjCX8/b54ntNyW6sjtoqxqRk3LTmXzaJoh71zMsDCjM+47jS7XiwN/+fQ==", + "dev": true + }, + "bluebird": { + "version": "3.7.2", + "resolved": "https://registry.npmjs.org/bluebird/-/bluebird-3.7.2.tgz", + "integrity": "sha512-XpNj6GDQzdfW+r2Wnn7xiSAd7TM3jzkxGXBGTtWKuSXv1xUV+azxAm8jdWZN06QTQk+2N2XB9jRDkvbmQmcRtg==", + "dev": true + }, + "bn.js": { + "version": "4.12.0", + "resolved": "https://registry.npmjs.org/bn.js/-/bn.js-4.12.0.tgz", + "integrity": "sha512-c98Bf3tPniI+scsdk237ku1Dc3ujXQTSgyiPUDEOe7tRkhrqridvh8klBv0HCEso1OLOYcHuCv/cS6DNxKH+ZA==", + "dev": true + }, + "body-parser": { + "version": "1.20.2", + "resolved": "https://registry.npmjs.org/body-parser/-/body-parser-1.20.2.tgz", + "integrity": "sha512-ml9pReCu3M61kGlqoTm2umSXTlRTuGTx0bfYj+uIUKKYycG5NtSbeetV3faSU6R7ajOPw0g/J1PvK4qNy7s5bA==", + "dev": true, + "requires": { + "bytes": "3.1.2", + "content-type": "~1.0.5", + "debug": "2.6.9", + "depd": "2.0.0", + "destroy": "1.2.0", + "http-errors": "2.0.0", + "iconv-lite": "0.4.24", + "on-finished": "2.4.1", + "qs": "6.11.0", + "raw-body": "2.5.2", + "type-is": "~1.6.18", + "unpipe": "1.0.0" + }, + "dependencies": { + "debug": { + "version": "2.6.9", + "resolved": "https://registry.npmjs.org/debug/-/debug-2.6.9.tgz", + "integrity": "sha512-bC7ElrdJaJnPbAP+1EotYvqZsb3ecl5wi6Bfi6BJTUcNowp6cvspg0jXznRTKDjm/E7AdgFBVeAPVMNcKGsHMA==", + "dev": true, + "requires": { + "ms": "2.0.0" + } + }, + "ms": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/ms/-/ms-2.0.0.tgz", + "integrity": "sha512-Tpp60P6IUJDTuOq/5Z8cdskzJujfwqfOTkrwIwj7IRISpnkJnT6SyJ4PCPnGMoFjC9ddhal5KVIYtAt97ix05A==", + "dev": true + }, + "qs": { + "version": "6.11.0", + "resolved": "https://registry.npmjs.org/qs/-/qs-6.11.0.tgz", + "integrity": "sha512-MvjoMCJwEarSbUYk5O+nmoSzSutSsTwF85zcHPQ9OrlFoZOYIjaqBAJIqIXjptyD5vThxGq52Xu/MaJzRkIk4Q==", + "dev": true, + "requires": { + "side-channel": "^1.0.4" + } + } + } + }, + "boolbase": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/boolbase/-/boolbase-1.0.0.tgz", + "integrity": "sha512-JZOSA7Mo9sNGB8+UjSgzdLtokWAky1zbztM3WRLCbZ70/3cTANmQmOdR7y2g+J0e2WXywy1yS468tY+IruqEww==", + "dev": true + }, + "brace-expansion": { + "version": "1.1.11", + "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.11.tgz", + "integrity": "sha512-iCuPHDFgrHX7H2vEI/5xpz07zSHB00TpugqhmYtVmMO6518mCuRMoOYFldEBl0g187ufozdaHgWKcYFb61qGiA==", + "dev": true, + "requires": { + "balanced-match": "^1.0.0", + "concat-map": "0.0.1" + } + }, + "braces": { + "version": "3.0.2", + "resolved": "https://registry.npmjs.org/braces/-/braces-3.0.2.tgz", + "integrity": "sha512-b8um+L1RzM3WDSzvhm6gIz1yfTbBt6YTlcEKAvsmqCZZFw46z626lVj9j1yEPW33H5H+lBQpZMP1k8l+78Ha0A==", + "dev": true, + "requires": { + "fill-range": "^7.0.1" + } + }, + "breakword": { + "version": "1.0.6", + "resolved": "https://registry.npmjs.org/breakword/-/breakword-1.0.6.tgz", + "integrity": "sha512-yjxDAYyK/pBvws9H4xKYpLDpYKEH6CzrBPAuXq3x18I+c/2MkVtT3qAr7Oloi6Dss9qNhPVueAAVU1CSeNDIXw==", + "dev": true, + "requires": { + "wcwidth": "^1.0.1" + } + }, + "brorand": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/brorand/-/brorand-1.1.0.tgz", + "integrity": "sha512-cKV8tMCEpQs4hK/ik71d6LrPOnpkpGBR0wzxqr68g2m/LB2GxVYQroAjMJZRVM1Y4BCjCKc3vAamxSzOY2RP+w==", + "dev": true + }, + "browser-level": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/browser-level/-/browser-level-1.0.1.tgz", + "integrity": "sha512-XECYKJ+Dbzw0lbydyQuJzwNXtOpbMSq737qxJN11sIRTErOMShvDpbzTlgju7orJKvx4epULolZAuJGLzCmWRQ==", + "dev": true, + "requires": { + "abstract-level": "^1.0.2", + "catering": "^2.1.1", + "module-error": "^1.0.2", + "run-parallel-limit": "^1.1.0" + } + }, + "browser-stdout": { + "version": "1.3.1", + "resolved": "https://registry.npmjs.org/browser-stdout/-/browser-stdout-1.3.1.tgz", + "integrity": "sha512-qhAVI1+Av2X7qelOfAIYwXONood6XlZE/fXaBSmW/T5SzLAmCgzi+eiWE7fUvbHaeNBQH13UftjpXxsfLkMpgw==", + "dev": true + }, + "browserify-aes": { + "version": "1.2.0", + "resolved": "https://registry.npmjs.org/browserify-aes/-/browserify-aes-1.2.0.tgz", + "integrity": "sha512-+7CHXqGuspUn/Sl5aO7Ea0xWGAtETPXNSAjHo48JfLdPWcMng33Xe4znFvQweqc/uzk5zSOI3H52CYnjCfb5hA==", + "dev": true, + "requires": { + "buffer-xor": "^1.0.3", + "cipher-base": "^1.0.0", + "create-hash": "^1.1.0", + "evp_bytestokey": "^1.0.3", + "inherits": "^2.0.1", + "safe-buffer": "^5.0.1" + } + }, + "bs58": { + "version": "4.0.1", + "resolved": "https://registry.npmjs.org/bs58/-/bs58-4.0.1.tgz", + "integrity": "sha512-Ok3Wdf5vOIlBrgCvTq96gBkJw+JUEzdBgyaza5HLtPm7yTHkjRy8+JzNyHF7BHa0bNWOQIp3m5YF0nnFcOIKLw==", + "dev": true, + "requires": { + "base-x": "^3.0.2" + } + }, + "bs58check": { + "version": "2.1.2", + "resolved": "https://registry.npmjs.org/bs58check/-/bs58check-2.1.2.tgz", + "integrity": "sha512-0TS1jicxdU09dwJMNZtVAfzPi6Q6QeN0pM1Fkzrjn+XYHvzMKPU3pHVpva+769iNVSfIYWf7LJ6WR+BuuMf8cA==", + "dev": true, + "requires": { + "bs58": "^4.0.0", + "create-hash": "^1.1.0", + "safe-buffer": "^5.1.2" + } + }, + "buffer": { + "version": "5.7.1", + "resolved": "https://registry.npmjs.org/buffer/-/buffer-5.7.1.tgz", + "integrity": "sha512-EHcyIPBQ4BSGlvjB16k5KgAJ27CIsHY/2JBmCRReo48y9rQ3MaUzWX3KVlBa4U7MyX02HdVj0K7C3WaB3ju7FQ==", + "dev": true, + "requires": { + "base64-js": "^1.3.1", + "ieee754": "^1.1.13" + } + }, + "buffer-from": { + "version": "1.1.2", + "resolved": "https://registry.npmjs.org/buffer-from/-/buffer-from-1.1.2.tgz", + "integrity": "sha512-E+XQCRwSbaaiChtv6k6Dwgc+bx+Bs6vuKJHHl5kox/BaKbhiXzqQOwK4cO22yElGp2OCmjwVhT3HmxgyPGnJfQ==", + "dev": true + }, + "buffer-reverse": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/buffer-reverse/-/buffer-reverse-1.0.1.tgz", + "integrity": "sha512-M87YIUBsZ6N924W57vDwT/aOu8hw7ZgdByz6ijksLjmHJELBASmYTTlNHRgjE+pTsT9oJXGaDSgqqwfdHotDUg==", + "dev": true + }, + "buffer-to-arraybuffer": { + "version": "0.0.5", + "resolved": "https://registry.npmjs.org/buffer-to-arraybuffer/-/buffer-to-arraybuffer-0.0.5.tgz", + "integrity": "sha512-3dthu5CYiVB1DEJp61FtApNnNndTckcqe4pFcLdvHtrpG+kcyekCJKg4MRiDcFW7A6AODnXB9U4dwQiCW5kzJQ==", + "dev": true + }, + "buffer-xor": { + "version": "1.0.3", + "resolved": "https://registry.npmjs.org/buffer-xor/-/buffer-xor-1.0.3.tgz", + "integrity": "sha512-571s0T7nZWK6vB67HI5dyUF7wXiNcfaPPPTl6zYCNApANjIvYJTg7hlud/+cJpdAhS7dVzqMLmfhfHR3rAcOjQ==", + "dev": true + }, + "bufferutil": { + "version": "4.0.7", + "resolved": "https://registry.npmjs.org/bufferutil/-/bufferutil-4.0.7.tgz", + "integrity": "sha512-kukuqc39WOHtdxtw4UScxF/WVnMFVSQVKhtx3AjZJzhd0RGZZldcrfSEbVsWWe6KNH253574cq5F+wpv0G9pJw==", + "dev": true, + "requires": { + "node-gyp-build": "^4.3.0" + } + }, + "busboy": { + "version": "1.6.0", + "resolved": "https://registry.npmjs.org/busboy/-/busboy-1.6.0.tgz", + "integrity": "sha512-8SFQbg/0hQ9xy3UNTB0YEnsNBbWfhf7RtnzpL7TkBiTBRfrQ9Fxcnz7VJsleJpyp6rVLvXiuORqjlHi5q+PYuA==", + "dev": true, + "requires": { + "streamsearch": "^1.1.0" + } + }, + "bytes": { + "version": "3.1.2", + "resolved": "https://registry.npmjs.org/bytes/-/bytes-3.1.2.tgz", + "integrity": "sha512-/Nf7TyzTx6S3yRJObOAV7956r8cr2+Oj8AC5dt8wSP3BQAoeX58NoHyCU8P8zGkNXStjTSi6fzO6F0pBdcYbEg==", + "dev": true + }, + "cacheable-lookup": { + "version": "6.1.0", + "resolved": "https://registry.npmjs.org/cacheable-lookup/-/cacheable-lookup-6.1.0.tgz", + "integrity": "sha512-KJ/Dmo1lDDhmW2XDPMo+9oiy/CeqosPguPCrgcVzKyZrL6pM1gU2GmPY/xo6OQPTUaA/c0kwHuywB4E6nmT9ww==", + "dev": true + }, + "cacheable-request": { + "version": "7.0.4", + "resolved": "https://registry.npmjs.org/cacheable-request/-/cacheable-request-7.0.4.tgz", + "integrity": "sha512-v+p6ongsrp0yTGbJXjgxPow2+DL93DASP4kXCDKb8/bwRtt9OEF3whggkkDkGNzgcWy2XaF4a8nZglC7uElscg==", + "dev": true, + "requires": { + "clone-response": "^1.0.2", + "get-stream": "^5.1.0", + "http-cache-semantics": "^4.0.0", + "keyv": "^4.0.0", + "lowercase-keys": "^2.0.0", + "normalize-url": "^6.0.1", + "responselike": "^2.0.0" + }, + "dependencies": { + "get-stream": { + "version": "5.2.0", + "resolved": "https://registry.npmjs.org/get-stream/-/get-stream-5.2.0.tgz", + "integrity": "sha512-nBF+F1rAZVCu/p7rjzgA+Yb4lfYXrpl7a6VmJrU8wF9I1CKvP/QwPNZHnOlwbTkY6dvtFIzFMSyQXbLoTQPRpA==", + "dev": true, + "requires": { + "pump": "^3.0.0" + } + }, + "lowercase-keys": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/lowercase-keys/-/lowercase-keys-2.0.0.tgz", + "integrity": "sha512-tqNXrS78oMOE73NMxK4EMLQsQowWf8jKooH9g7xPavRT706R6bkQJ6DY2Te7QukaZsulxa30wQ7bk0pm4XiHmA==", + "dev": true + } + } + }, + "call-bind": { + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/call-bind/-/call-bind-1.0.2.tgz", + "integrity": "sha512-7O+FbCihrB5WGbFYesctwmTKae6rOiIzmz1icreWJ+0aA7LJfuqhEso2T9ncpcFtzMQtzXf2QGGueWJGTYsqrA==", + "dev": true, + "requires": { + "function-bind": "^1.1.1", + "get-intrinsic": "^1.0.2" + } + }, + "callsites": { + "version": "3.1.0", + "resolved": "https://registry.npmjs.org/callsites/-/callsites-3.1.0.tgz", + "integrity": "sha512-P8BjAsXvZS+VIDUI11hHCQEv74YT67YUi5JJFNWIqL235sBmjX4+qx9Muvls5ivyNENctx46xQLQ3aTuE7ssaQ==", + "dev": true + }, + "camel-case": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/camel-case/-/camel-case-3.0.0.tgz", + "integrity": "sha512-+MbKztAYHXPr1jNTSKQF52VpcFjwY5RkR7fxksV8Doo4KAYc5Fl4UJRgthBbTmEx8C54DqahhbLJkDwjI3PI/w==", + "dev": true, + "requires": { + "no-case": "^2.2.0", + "upper-case": "^1.1.1" + } + }, + "camelcase": { + "version": "4.1.0", + "resolved": "https://registry.npmjs.org/camelcase/-/camelcase-4.1.0.tgz", + "integrity": "sha512-FxAv7HpHrXbh3aPo4o2qxHay2lkLY3x5Mw3KeE4KQE8ysVfziWeRZDwcjauvwBSGEC/nXUPzZy8zeh4HokqOnw==", + "dev": true + }, + "camelcase-keys": { + "version": "6.2.2", + "resolved": "https://registry.npmjs.org/camelcase-keys/-/camelcase-keys-6.2.2.tgz", + "integrity": "sha512-YrwaA0vEKazPBkn0ipTiMpSajYDSe+KjQfrjhcBMxJt/znbvlHd8Pw/Vamaz5EB4Wfhs3SUR3Z9mwRu/P3s3Yg==", + "dev": true, + "requires": { + "camelcase": "^5.3.1", + "map-obj": "^4.0.0", + "quick-lru": "^4.0.1" + }, + "dependencies": { + "camelcase": { + "version": "5.3.1", + "resolved": "https://registry.npmjs.org/camelcase/-/camelcase-5.3.1.tgz", + "integrity": "sha512-L28STB170nwWS63UjtlEOE3dldQApaJXZkOI1uMFfzf3rRuPegHaHesyee+YxQ+W6SvRDQV6UrdOdRiR153wJg==", + "dev": true + } + } + }, + "case": { + "version": "1.6.3", + "resolved": "https://registry.npmjs.org/case/-/case-1.6.3.tgz", + "integrity": "sha512-mzDSXIPaFwVDvZAHqZ9VlbyF4yyXRuX6IvB06WvPYkqJVO24kX1PPhv9bfpKNFZyxYFmmgo03HUiD8iklmJYRQ==", + "dev": true + }, + "caseless": { + "version": "0.12.0", + "resolved": "https://registry.npmjs.org/caseless/-/caseless-0.12.0.tgz", + "integrity": "sha512-4tYFyifaFfGacoiObjJegolkwSU4xQNGbVgUiNYVUxbQ2x2lUsFvY4hVgVzGiIe6WLOPqycWXA40l+PWsxthUw==", + "dev": true + }, + "catering": { + "version": "2.1.1", + "resolved": "https://registry.npmjs.org/catering/-/catering-2.1.1.tgz", + "integrity": "sha512-K7Qy8O9p76sL3/3m7/zLKbRkyOlSZAgzEaLhyj2mXS8PsCud2Eo4hAb8aLtZqHh0QGqLcb9dlJSu6lHRVENm1w==", + "dev": true + }, + "cbor": { + "version": "8.1.0", + "resolved": "https://registry.npmjs.org/cbor/-/cbor-8.1.0.tgz", + "integrity": "sha512-DwGjNW9omn6EwP70aXsn7FQJx5kO12tX0bZkaTjzdVFM6/7nhA4t0EENocKGx6D2Bch9PE2KzCUf5SceBdeijg==", + "dev": true, + "requires": { + "nofilter": "^3.1.0" + } + }, + "chai": { + "version": "4.3.7", + "resolved": "https://registry.npmjs.org/chai/-/chai-4.3.7.tgz", + "integrity": "sha512-HLnAzZ2iupm25PlN0xFreAlBA5zaBSv3og0DdeGA4Ar6h6rJ3A0rolRUKJhSF2V10GZKDgWF/VmAEsNWjCRB+A==", + "dev": true, + "requires": { + "assertion-error": "^1.1.0", + "check-error": "^1.0.2", + "deep-eql": "^4.1.2", + "get-func-name": "^2.0.0", + "loupe": "^2.3.1", + "pathval": "^1.1.1", + "type-detect": "^4.0.5" + } + }, + "chai-bn": { + "version": "0.2.2", + "resolved": "https://registry.npmjs.org/chai-bn/-/chai-bn-0.2.2.tgz", + "integrity": "sha512-MzjelH0p8vWn65QKmEq/DLBG1Hle4WeyqT79ANhXZhn/UxRWO0OogkAxi5oGGtfzwU9bZR8mvbvYdoqNVWQwFg==", + "dev": true, + "requires": {} + }, + "chalk": { + "version": "2.4.2", + "resolved": "https://registry.npmjs.org/chalk/-/chalk-2.4.2.tgz", + "integrity": "sha512-Mti+f9lpJNcwF4tWV8/OrTTtF1gZi+f8FqlyAdouralcFWFQWF2+NgCHShjkCb+IFBLq9buZwE1xckQU4peSuQ==", + "dev": true, + "requires": { + "ansi-styles": "^3.2.1", + "escape-string-regexp": "^1.0.5", + "supports-color": "^5.3.0" + } + }, + "change-case": { + "version": "3.0.2", + "resolved": "https://registry.npmjs.org/change-case/-/change-case-3.0.2.tgz", + "integrity": "sha512-Mww+SLF6MZ0U6kdg11algyKd5BARbyM4TbFBepwowYSR5ClfQGCGtxNXgykpN0uF/bstWeaGDT4JWaDh8zWAHA==", + "dev": true, + "requires": { + "camel-case": "^3.0.0", + "constant-case": "^2.0.0", + "dot-case": "^2.1.0", + "header-case": "^1.0.0", + "is-lower-case": "^1.1.0", + "is-upper-case": "^1.1.0", + "lower-case": "^1.1.1", + "lower-case-first": "^1.0.0", + "no-case": "^2.3.2", + "param-case": "^2.1.0", + "pascal-case": "^2.0.0", + "path-case": "^2.1.0", + "sentence-case": "^2.1.0", + "snake-case": "^2.1.0", + "swap-case": "^1.1.0", + "title-case": "^2.1.0", + "upper-case": "^1.1.1", + "upper-case-first": "^1.1.0" + } + }, + "chardet": { + "version": "0.7.0", + "resolved": "https://registry.npmjs.org/chardet/-/chardet-0.7.0.tgz", + "integrity": "sha512-mT8iDcrh03qDGRRmoA2hmBJnxpllMR+0/0qlzjqZES6NdiWDcZkCNAk4rPFZ9Q85r27unkiNNg8ZOiwZXBHwcA==", + "dev": true + }, + "charenc": { + "version": "0.0.2", + "resolved": "https://registry.npmjs.org/charenc/-/charenc-0.0.2.tgz", + "integrity": "sha512-yrLQ/yVUFXkzg7EDQsPieE/53+0RlaWTs+wBrvW36cyilJ2SaDWfl4Yj7MtLTXleV9uEKefbAGUPv2/iWSooRA==", + "dev": true + }, + "check-error": { + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/check-error/-/check-error-1.0.2.tgz", + "integrity": "sha512-BrgHpW9NURQgzoNyjfq0Wu6VFO6D7IZEmJNdtgNqpzGG8RuNFHt2jQxWlAs4HMe119chBnv+34syEZtc6IhLtA==", + "dev": true + }, + "cheerio": { + "version": "1.0.0-rc.12", + "resolved": "https://registry.npmjs.org/cheerio/-/cheerio-1.0.0-rc.12.tgz", + "integrity": "sha512-VqR8m68vM46BNnuZ5NtnGBKIE/DfN0cRIzg9n40EIq9NOv90ayxLBXA8fXC5gquFRGJSTRqBq25Jt2ECLR431Q==", + "dev": true, + "requires": { + "cheerio-select": "^2.1.0", + "dom-serializer": "^2.0.0", + "domhandler": "^5.0.3", + "domutils": "^3.0.1", + "htmlparser2": "^8.0.1", + "parse5": "^7.0.0", + "parse5-htmlparser2-tree-adapter": "^7.0.0" + } + }, + "cheerio-select": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/cheerio-select/-/cheerio-select-2.1.0.tgz", + "integrity": "sha512-9v9kG0LvzrlcungtnJtpGNxY+fzECQKhK4EGJX2vByejiMX84MFNQw4UxPJl3bFbTMw+Dfs37XaIkCwTZfLh4g==", + "dev": true, + "requires": { + "boolbase": "^1.0.0", + "css-select": "^5.1.0", + "css-what": "^6.1.0", + "domelementtype": "^2.3.0", + "domhandler": "^5.0.3", + "domutils": "^3.0.1" + } + }, + "chokidar": { + "version": "3.5.3", + "resolved": "https://registry.npmjs.org/chokidar/-/chokidar-3.5.3.tgz", + "integrity": "sha512-Dr3sfKRP6oTcjf2JmUmFJfeVMvXBdegxB0iVQ5eb2V10uFJUCAS8OByZdVAyVb8xXNz3GjjTgj9kLWsZTqE6kw==", + "dev": true, + "requires": { + "anymatch": "~3.1.2", + "braces": "~3.0.2", + "fsevents": "~2.3.2", + "glob-parent": "~5.1.2", + "is-binary-path": "~2.1.0", + "is-glob": "~4.0.1", + "normalize-path": "~3.0.0", + "readdirp": "~3.6.0" + } + }, + "chownr": { + "version": "1.1.4", + "resolved": "https://registry.npmjs.org/chownr/-/chownr-1.1.4.tgz", + "integrity": "sha512-jJ0bqzaylmJtVnNgzTeSOs8DPavpbYgEr/b0YL8/2GO3xJEhInFmhKMUnEJQjZumK7KXGFhUy89PrsJWlakBVg==", + "dev": true + }, + "ci-info": { + "version": "3.8.0", + "resolved": "https://registry.npmjs.org/ci-info/-/ci-info-3.8.0.tgz", + "integrity": "sha512-eXTggHWSooYhq49F2opQhuHWgzucfF2YgODK4e1566GQs5BIfP30B0oenwBJHfWxAs2fyPB1s7Mg949zLf61Yw==", + "dev": true + }, + "cids": { + "version": "0.7.5", + "resolved": "https://registry.npmjs.org/cids/-/cids-0.7.5.tgz", + "integrity": "sha512-zT7mPeghoWAu+ppn8+BS1tQ5qGmbMfB4AregnQjA/qHY3GC1m1ptI9GkWNlgeu38r7CuRdXB47uY2XgAYt6QVA==", + "dev": true, + "requires": { + "buffer": "^5.5.0", + "class-is": "^1.1.0", + "multibase": "~0.6.0", + "multicodec": "^1.0.0", + "multihashes": "~0.4.15" + }, + "dependencies": { + "multicodec": { + "version": "1.0.4", + "resolved": "https://registry.npmjs.org/multicodec/-/multicodec-1.0.4.tgz", + "integrity": "sha512-NDd7FeS3QamVtbgfvu5h7fd1IlbaC4EQ0/pgU4zqE2vdHCmBGsUa0TiM8/TdSeG6BMPC92OOCf8F1ocE/Wkrrg==", + "dev": true, + "requires": { + "buffer": "^5.6.0", + "varint": "^5.0.0" + } + } + } + }, + "cipher-base": { + "version": "1.0.4", + "resolved": "https://registry.npmjs.org/cipher-base/-/cipher-base-1.0.4.tgz", + "integrity": "sha512-Kkht5ye6ZGmwv40uUDZztayT2ThLQGfnj/T71N/XzeZeo3nf8foyW7zGTsPYkEya3m5f3cAypH+qe7YOrM1U2Q==", + "dev": true, + "requires": { + "inherits": "^2.0.1", + "safe-buffer": "^5.0.1" + } + }, + "class-is": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/class-is/-/class-is-1.1.0.tgz", + "integrity": "sha512-rhjH9AG1fvabIDoGRVH587413LPjTZgmDF9fOFCbFJQV4yuocX1mHxxvXI4g3cGwbVY9wAYIoKlg1N79frJKQw==", + "dev": true + }, + "classic-level": { + "version": "1.3.0", + "resolved": "https://registry.npmjs.org/classic-level/-/classic-level-1.3.0.tgz", + "integrity": "sha512-iwFAJQYtqRTRM0F6L8h4JCt00ZSGdOyqh7yVrhhjrOpFhmBjNlRUey64MCiyo6UmQHMJ+No3c81nujPv+n9yrg==", + "dev": true, + "requires": { + "abstract-level": "^1.0.2", + "catering": "^2.1.0", + "module-error": "^1.0.1", + "napi-macros": "^2.2.2", + "node-gyp-build": "^4.3.0" + } + }, + "clean-stack": { + "version": "2.2.0", + "resolved": "https://registry.npmjs.org/clean-stack/-/clean-stack-2.2.0.tgz", + "integrity": "sha512-4diC9HaTE+KRAMWhDhrGOECgWZxoevMc5TlkObMqNSsVU62PYzXZ/SMTjzyGAFF1YusgxGcSWTEXBhp0CPwQ1A==", + "dev": true + }, + "cli-table3": { + "version": "0.5.1", + "resolved": "https://registry.npmjs.org/cli-table3/-/cli-table3-0.5.1.tgz", + "integrity": "sha512-7Qg2Jrep1S/+Q3EceiZtQcDPWxhAvBw+ERf1162v4sikJrvojMHFqXt8QIVha8UlH9rgU0BeWPytZ9/TzYqlUw==", + "dev": true, + "requires": { + "colors": "^1.1.2", + "object-assign": "^4.1.0", + "string-width": "^2.1.1" + } + }, + "cliui": { + "version": "8.0.1", + "resolved": "https://registry.npmjs.org/cliui/-/cliui-8.0.1.tgz", + "integrity": "sha512-BSeNnyus75C4//NQ9gQt1/csTXyo/8Sb+afLAkzAptFuMsod9HFokGNudZpi/oQV73hnVK+sR+5PVRMd+Dr7YQ==", + "dev": true, + "requires": { + "string-width": "^4.2.0", + "strip-ansi": "^6.0.1", + "wrap-ansi": "^7.0.0" + }, + "dependencies": { + "ansi-regex": { + "version": "5.0.1", + "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-5.0.1.tgz", + "integrity": "sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ==", + "dev": true + }, + "is-fullwidth-code-point": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/is-fullwidth-code-point/-/is-fullwidth-code-point-3.0.0.tgz", + "integrity": "sha512-zymm5+u+sCsSWyD9qNaejV3DFvhCKclKdizYaJUuHA83RLjb7nSuGnddCHGv0hk+KY7BMAlsWeK4Ueg6EV6XQg==", + "dev": true + }, + "string-width": { + "version": "4.2.3", + "resolved": "https://registry.npmjs.org/string-width/-/string-width-4.2.3.tgz", + "integrity": "sha512-wKyQRQpjJ0sIp62ErSZdGsjMJWsap5oRNihHhu6G7JVO/9jIB6UyevL+tXuOqrng8j/cxKTWyWUwvSTriiZz/g==", + "dev": true, + "requires": { + "emoji-regex": "^8.0.0", + "is-fullwidth-code-point": "^3.0.0", + "strip-ansi": "^6.0.1" + } + }, + "strip-ansi": { + "version": "6.0.1", + "resolved": "https://registry.npmjs.org/strip-ansi/-/strip-ansi-6.0.1.tgz", + "integrity": "sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A==", + "dev": true, + "requires": { + "ansi-regex": "^5.0.1" + } + } + } + }, + "clone": { + "version": "1.0.4", + "resolved": "https://registry.npmjs.org/clone/-/clone-1.0.4.tgz", + "integrity": "sha512-JQHZ2QMW6l3aH/j6xCqQThY/9OH4D/9ls34cgkUBiEeocRTU04tHfKPBsUK1PqZCUQM7GiA0IIXJSuXHI64Kbg==", + "dev": true + }, + "clone-response": { + "version": "1.0.3", + "resolved": "https://registry.npmjs.org/clone-response/-/clone-response-1.0.3.tgz", + "integrity": "sha512-ROoL94jJH2dUVML2Y/5PEDNaSHgeOdSDicUyS7izcF63G6sTc/FTjLub4b8Il9S8S0beOfYt0TaA5qvFK+w0wA==", + "dev": true, + "requires": { + "mimic-response": "^1.0.0" + } + }, + "code-point-at": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/code-point-at/-/code-point-at-1.1.0.tgz", + "integrity": "sha512-RpAVKQA5T63xEj6/giIbUEtZwJ4UFIc3ZtvEkiaUERylqe8xb5IvqcgOurZLahv93CLKfxcw5YI+DZcUBRyLXA==", + "dev": true + }, + "color-convert": { + "version": "1.9.3", + "resolved": "https://registry.npmjs.org/color-convert/-/color-convert-1.9.3.tgz", + "integrity": "sha512-QfAUtd+vFdAtFQcC8CCyYt1fYWxSqAiK2cSD6zDB8N3cpsEBAvRxp9zOGg6G/SHHJYAT88/az/IuDGALsNVbGg==", + "dev": true, + "requires": { + "color-name": "1.1.3" + } + }, + "color-name": { + "version": "1.1.3", + "resolved": "https://registry.npmjs.org/color-name/-/color-name-1.1.3.tgz", + "integrity": "sha512-72fSenhMw2HZMTVHeCA9KCmpEIbzWiQsjN+BHcBbS9vr1mtt+vJjPdksIBNUmKAW8TFUDPJK5SUU3QhE9NEXDw==", + "dev": true + }, + "colors": { + "version": "1.4.0", + "resolved": "https://registry.npmjs.org/colors/-/colors-1.4.0.tgz", + "integrity": "sha512-a+UqTh4kgZg/SlGvfbzDHpgRu7AAQOmmqRHJnxhRZICKFUT91brVhNNt58CMWU9PsBbv3PDCZUHbVxuDiH2mtA==", + "dev": true + }, + "combined-stream": { + "version": "1.0.8", + "resolved": "https://registry.npmjs.org/combined-stream/-/combined-stream-1.0.8.tgz", + "integrity": "sha512-FQN4MRfuJeHf7cBbBMJFXhKSDq+2kAArBlmRBvcvFE5BB1HZKXtSFASDhdlz9zOYwxh8lDdnvmMOe/+5cdoEdg==", + "dev": true, + "requires": { + "delayed-stream": "~1.0.0" + } + }, + "command-exists": { + "version": "1.2.9", + "resolved": "https://registry.npmjs.org/command-exists/-/command-exists-1.2.9.tgz", + "integrity": "sha512-LTQ/SGc+s0Xc0Fu5WaKnR0YiygZkm9eKFvyS+fRsU7/ZWFF8ykFM6Pc9aCVf1+xasOOZpO3BAVgVrKvsqKHV7w==", + "dev": true + }, + "commander": { + "version": "10.0.1", + "resolved": "https://registry.npmjs.org/commander/-/commander-10.0.1.tgz", + "integrity": "sha512-y4Mg2tXshplEbSGzx7amzPwKKOCGuoSRP/CjEdwwk0FOGlUbq6lKuoyDZTNZkmxHdJtp54hdfY/JUrdL7Xfdug==", + "dev": true + }, + "compare-versions": { + "version": "5.0.3", + "resolved": "https://registry.npmjs.org/compare-versions/-/compare-versions-5.0.3.tgz", + "integrity": "sha512-4UZlZP8Z99MGEY+Ovg/uJxJuvoXuN4M6B3hKaiackiHrgzQFEe3diJi1mf1PNHbFujM7FvLrK2bpgIaImbtZ1A==", + "dev": true + }, + "concat-map": { + "version": "0.0.1", + "resolved": "https://registry.npmjs.org/concat-map/-/concat-map-0.0.1.tgz", + "integrity": "sha512-/Srv4dswyQNBfohGpz9o6Yb3Gz3SrUDqBH5rTuhGR7ahtlbYKnVxw2bCFMRljaA7EXHaXZ8wsHdodFvbkhKmqg==", + "dev": true + }, + "concat-stream": { + "version": "1.6.2", + "resolved": "https://registry.npmjs.org/concat-stream/-/concat-stream-1.6.2.tgz", + "integrity": "sha512-27HBghJxjiZtIk3Ycvn/4kbJk/1uZuJFfuPEns6LaEvpvG1f0hTea8lilrouyo9mVc2GWdcEZ8OLoGmSADlrCw==", + "dev": true, + "requires": { + "buffer-from": "^1.0.0", + "inherits": "^2.0.3", + "readable-stream": "^2.2.2", + "typedarray": "^0.0.6" + }, + "dependencies": { + "readable-stream": { + "version": "2.3.8", + "resolved": "https://registry.npmjs.org/readable-stream/-/readable-stream-2.3.8.tgz", + "integrity": "sha512-8p0AUk4XODgIewSi0l8Epjs+EVnWiK7NoDIEGU0HhE7+ZyY8D1IMY7odu5lRrFXGg71L15KG8QrPmum45RTtdA==", + "dev": true, + "requires": { + "core-util-is": "~1.0.0", + "inherits": "~2.0.3", + "isarray": "~1.0.0", + "process-nextick-args": "~2.0.0", + "safe-buffer": "~5.1.1", + "string_decoder": "~1.1.1", + "util-deprecate": "~1.0.1" + } + }, + "safe-buffer": { + "version": "5.1.2", + "resolved": "https://registry.npmjs.org/safe-buffer/-/safe-buffer-5.1.2.tgz", + "integrity": "sha512-Gd2UZBJDkXlY7GbJxfsE8/nvKkUEU1G38c1siN6QP6a9PT9MmHB8GnpscSmMJSoF8LOIrt8ud/wPtojys4G6+g==", + "dev": true + }, + "string_decoder": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/string_decoder/-/string_decoder-1.1.1.tgz", + "integrity": "sha512-n/ShnvDi6FHbbVfviro+WojiFzv+s8MPMHBczVePfUpDJLwoLT0ht1l4YwBCbi8pJAveEEdnkHyPyTP/mzRfwg==", + "dev": true, + "requires": { + "safe-buffer": "~5.1.0" + } + } + } + }, + "constant-case": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/constant-case/-/constant-case-2.0.0.tgz", + "integrity": "sha512-eS0N9WwmjTqrOmR3o83F5vW8Z+9R1HnVz3xmzT2PMFug9ly+Au/fxRWlEBSb6LcZwspSsEn9Xs1uw9YgzAg1EQ==", + "dev": true, + "requires": { + "snake-case": "^2.1.0", + "upper-case": "^1.1.1" + } + }, + "content-disposition": { + "version": "0.5.4", + "resolved": "https://registry.npmjs.org/content-disposition/-/content-disposition-0.5.4.tgz", + "integrity": "sha512-FveZTNuGw04cxlAiWbzi6zTAL/lhehaWbTtgluJh4/E95DqMwTmha3KZN1aAWA8cFIhHzMZUvLevkw5Rqk+tSQ==", + "dev": true, + "requires": { + "safe-buffer": "5.2.1" + } + }, + "content-hash": { + "version": "2.5.2", + "resolved": "https://registry.npmjs.org/content-hash/-/content-hash-2.5.2.tgz", + "integrity": "sha512-FvIQKy0S1JaWV10sMsA7TRx8bpU+pqPkhbsfvOJAdjRXvYxEckAwQWGwtRjiaJfh+E0DvcWUGqcdjwMGFjsSdw==", + "dev": true, + "requires": { + "cids": "^0.7.1", + "multicodec": "^0.5.5", + "multihashes": "^0.4.15" + } + }, + "content-type": { + "version": "1.0.5", + "resolved": "https://registry.npmjs.org/content-type/-/content-type-1.0.5.tgz", + "integrity": "sha512-nTjqfcBFEipKdXCv4YDQWCfmcLZKm81ldF0pAopTvyrFGVbcR6P/VAAd5G7N+0tTr8QqiU0tFadD6FK4NtJwOA==", + "dev": true + }, + "cookie": { + "version": "0.4.2", + "resolved": "https://registry.npmjs.org/cookie/-/cookie-0.4.2.tgz", + "integrity": "sha512-aSWTXFzaKWkvHO1Ny/s+ePFpvKsPnjc551iI41v3ny/ow6tBG5Vd+FuqGNhh1LxOmVzOlGUriIlOaokOvhaStA==", + "dev": true + }, + "cookie-signature": { + "version": "1.0.6", + "resolved": "https://registry.npmjs.org/cookie-signature/-/cookie-signature-1.0.6.tgz", + "integrity": "sha512-QADzlaHc8icV8I7vbaJXJwod9HWYp8uCqf1xa4OfNu1T7JVxQIrUgOWtHdNDtPiywmFbiS12VjotIXLrKM3orQ==", + "dev": true + }, + "core-util-is": { + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/core-util-is/-/core-util-is-1.0.2.tgz", + "integrity": "sha512-3lqz5YjWTYnW6dlDa5TLaTCcShfar1e40rmcJVwCBJC6mWlFuj0eCHIElmG1g5kyuJ/GD+8Wn4FFCcz4gJPfaQ==", + "dev": true + }, + "cors": { + "version": "2.8.5", + "resolved": "https://registry.npmjs.org/cors/-/cors-2.8.5.tgz", + "integrity": "sha512-KIHbLJqu73RGr/hnbrO9uBeixNGuvSQjul/jdFvS/KFSIH1hWVd1ng7zOHx+YrEfInLG7q4n6GHQ9cDtxv/P6g==", + "dev": true, + "requires": { + "object-assign": "^4", + "vary": "^1" + } + }, + "cosmiconfig": { + "version": "8.2.0", + "resolved": "https://registry.npmjs.org/cosmiconfig/-/cosmiconfig-8.2.0.tgz", + "integrity": "sha512-3rTMnFJA1tCOPwRxtgF4wd7Ab2qvDbL8jX+3smjIbS4HlZBagTlpERbdN7iAbWlrfxE3M8c27kTwTawQ7st+OQ==", + "dev": true, + "requires": { + "import-fresh": "^3.2.1", + "js-yaml": "^4.1.0", + "parse-json": "^5.0.0", + "path-type": "^4.0.0" + }, + "dependencies": { + "argparse": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/argparse/-/argparse-2.0.1.tgz", + "integrity": "sha512-8+9WqebbFzpX9OR+Wa6O29asIogeRMzcGtAINdpMHHyAg10f05aSFVBbcEqGf/PXw1EjAZ+q2/bEBg3DvurK3Q==", + "dev": true + }, + "js-yaml": { + "version": "4.1.0", + "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-4.1.0.tgz", + "integrity": "sha512-wpxZs9NoxZaJESJGIZTyDEaYpl0FKSA+FB9aJiyemKhMwkxQg63h4T1KJgUGHpTqPDNRcmmYLugrRjJlBtWvRA==", + "dev": true, + "requires": { + "argparse": "^2.0.1" + } + } + } + }, + "crc-32": { + "version": "1.2.2", + "resolved": "https://registry.npmjs.org/crc-32/-/crc-32-1.2.2.tgz", + "integrity": "sha512-ROmzCKrTnOwybPcJApAA6WBWij23HVfGVNKqqrZpuyZOHqK2CwHSvpGuyt/UNNvaIjEd8X5IFGp4Mh+Ie1IHJQ==", + "dev": true + }, + "create-hash": { + "version": "1.2.0", + "resolved": "https://registry.npmjs.org/create-hash/-/create-hash-1.2.0.tgz", + "integrity": "sha512-z00bCGNHDG8mHAkP7CtT1qVu+bFQUPjYq/4Iv3C3kWjTFV10zIjfSoeqXo9Asws8gwSHDGj/hl2u4OGIjapeCg==", + "dev": true, + "requires": { + "cipher-base": "^1.0.1", + "inherits": "^2.0.1", + "md5.js": "^1.3.4", + "ripemd160": "^2.0.1", + "sha.js": "^2.4.0" + } + }, + "create-hmac": { + "version": "1.1.7", + "resolved": "https://registry.npmjs.org/create-hmac/-/create-hmac-1.1.7.tgz", + "integrity": "sha512-MJG9liiZ+ogc4TzUwuvbER1JRdgvUFSB5+VR/g5h82fGaIRWMWddtKBHi7/sVhfjQZ6SehlyhvQYrcYkaUIpLg==", + "dev": true, + "requires": { + "cipher-base": "^1.0.3", + "create-hash": "^1.1.0", + "inherits": "^2.0.1", + "ripemd160": "^2.0.0", + "safe-buffer": "^5.0.1", + "sha.js": "^2.4.8" + } + }, + "cross-fetch": { + "version": "3.1.8", + "resolved": "https://registry.npmjs.org/cross-fetch/-/cross-fetch-3.1.8.tgz", + "integrity": "sha512-cvA+JwZoU0Xq+h6WkMvAUqPEYy92Obet6UdKLfW60qn99ftItKjB5T+BkyWOFWe2pUyfQ+IJHmpOTznqk1M6Kg==", + "dev": true, + "requires": { + "node-fetch": "^2.6.12" + } + }, + "cross-spawn": { + "version": "7.0.3", + "resolved": "https://registry.npmjs.org/cross-spawn/-/cross-spawn-7.0.3.tgz", + "integrity": "sha512-iRDPJKUPVEND7dHPO8rkbOnPpyDygcDFtWjpeWNCgy8WP2rXcxXL8TskReQl6OrB2G7+UJrags1q15Fudc7G6w==", + "dev": true, + "requires": { + "path-key": "^3.1.0", + "shebang-command": "^2.0.0", + "which": "^2.0.1" + } + }, + "crypt": { + "version": "0.0.2", + "resolved": "https://registry.npmjs.org/crypt/-/crypt-0.0.2.tgz", + "integrity": "sha512-mCxBlsHFYh9C+HVpiEacem8FEBnMXgU9gy4zmNC+SXAZNB/1idgp/aulFJ4FgCi7GPEVbfyng092GqL2k2rmow==", + "dev": true + }, + "crypto-addr-codec": { + "version": "0.1.7", + "resolved": "https://registry.npmjs.org/crypto-addr-codec/-/crypto-addr-codec-0.1.7.tgz", + "integrity": "sha512-X4hzfBzNhy4mAc3UpiXEC/L0jo5E8wAa9unsnA8nNXYzXjCcGk83hfC5avJWCSGT8V91xMnAS9AKMHmjw5+XCg==", + "dev": true, + "requires": { + "base-x": "^3.0.8", + "big-integer": "1.6.36", + "blakejs": "^1.1.0", + "bs58": "^4.0.1", + "ripemd160-min": "0.0.6", + "safe-buffer": "^5.2.0", + "sha3": "^2.1.1" + } + }, + "crypto-js": { + "version": "3.3.0", + "resolved": "https://registry.npmjs.org/crypto-js/-/crypto-js-3.3.0.tgz", + "integrity": "sha512-DIT51nX0dCfKltpRiXV+/TVZq+Qq2NgF4644+K7Ttnla7zEzqc+kjJyiB96BHNyUTBxyjzRcZYpUdZa+QAqi6Q==", + "dev": true + }, + "css-select": { + "version": "5.1.0", + "resolved": "https://registry.npmjs.org/css-select/-/css-select-5.1.0.tgz", + "integrity": "sha512-nwoRF1rvRRnnCqqY7updORDsuqKzqYJ28+oSMaJMMgOauh3fvwHqMS7EZpIPqK8GL+g9mKxF1vP/ZjSeNjEVHg==", + "dev": true, + "requires": { + "boolbase": "^1.0.0", + "css-what": "^6.1.0", + "domhandler": "^5.0.2", + "domutils": "^3.0.1", + "nth-check": "^2.0.1" + } + }, + "css-what": { + "version": "6.1.0", + "resolved": "https://registry.npmjs.org/css-what/-/css-what-6.1.0.tgz", + "integrity": "sha512-HTUrgRJ7r4dsZKU6GjmpfRK1O76h97Z8MfS1G0FozR+oF2kG6Vfe8JE6zwrkbxigziPHinCJ+gCPjA9EaBDtRw==", + "dev": true + }, + "csv": { + "version": "5.5.3", + "resolved": "https://registry.npmjs.org/csv/-/csv-5.5.3.tgz", + "integrity": "sha512-QTaY0XjjhTQOdguARF0lGKm5/mEq9PD9/VhZZegHDIBq2tQwgNpHc3dneD4mGo2iJs+fTKv5Bp0fZ+BRuY3Z0g==", + "dev": true, + "requires": { + "csv-generate": "^3.4.3", + "csv-parse": "^4.16.3", + "csv-stringify": "^5.6.5", + "stream-transform": "^2.1.3" + } + }, + "csv-generate": { + "version": "3.4.3", + "resolved": "https://registry.npmjs.org/csv-generate/-/csv-generate-3.4.3.tgz", + "integrity": "sha512-w/T+rqR0vwvHqWs/1ZyMDWtHHSJaN06klRqJXBEpDJaM/+dZkso0OKh1VcuuYvK3XM53KysVNq8Ko/epCK8wOw==", + "dev": true + }, + "csv-parse": { + "version": "4.16.3", + "resolved": "https://registry.npmjs.org/csv-parse/-/csv-parse-4.16.3.tgz", + "integrity": "sha512-cO1I/zmz4w2dcKHVvpCr7JVRu8/FymG5OEpmvsZYlccYolPBLoVGKUHgNoc4ZGkFeFlWGEDmMyBM+TTqRdW/wg==", + "dev": true + }, + "csv-stringify": { + "version": "5.6.5", + "resolved": "https://registry.npmjs.org/csv-stringify/-/csv-stringify-5.6.5.tgz", + "integrity": "sha512-PjiQ659aQ+fUTQqSrd1XEDnOr52jh30RBurfzkscaE2tPaFsDH5wOAHJiw8XAHphRknCwMUE9KRayc4K/NbO8A==", + "dev": true + }, + "d": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/d/-/d-1.0.1.tgz", + "integrity": "sha512-m62ShEObQ39CfralilEQRjH6oAMtNCV1xJyEx5LpRYUVN+EviphDgUc/F3hnYbADmkiNs67Y+3ylmlG7Lnu+FA==", + "dev": true, + "requires": { + "es5-ext": "^0.10.50", + "type": "^1.0.1" + } + }, + "dashdash": { + "version": "1.14.1", + "resolved": "https://registry.npmjs.org/dashdash/-/dashdash-1.14.1.tgz", + "integrity": "sha512-jRFi8UDGo6j+odZiEpjazZaWqEal3w/basFjQHQEwVtZJGDpxbH1MeYluwCS8Xq5wmLJooDlMgvVarmWfGM44g==", + "dev": true, + "requires": { + "assert-plus": "^1.0.0" + } + }, + "dataloader": { + "version": "1.4.0", + "resolved": "https://registry.npmjs.org/dataloader/-/dataloader-1.4.0.tgz", + "integrity": "sha512-68s5jYdlvasItOJnCuI2Q9s4q98g0pCyL3HrcKJu8KNugUl8ahgmZYg38ysLTgQjjXX3H8CJLkAvWrclWfcalw==", + "dev": true + }, + "death": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/death/-/death-1.1.0.tgz", + "integrity": "sha512-vsV6S4KVHvTGxbEcij7hkWRv0It+sGGWVOM67dQde/o5Xjnr+KmLjxWJii2uEObIrt1CcM9w0Yaovx+iOlIL+w==", + "dev": true + }, + "debug": { + "version": "4.3.4", + "resolved": "https://registry.npmjs.org/debug/-/debug-4.3.4.tgz", + "integrity": "sha512-PRWFHuSU3eDtQJPvnNY7Jcket1j0t5OuOsFzPPzsekD52Zl8qUfFIPEiswXqIvHWGVHOgX+7G/vCNNhehwxfkQ==", + "dev": true, + "requires": { + "ms": "2.1.2" + } + }, + "decamelize": { + "version": "1.2.0", + "resolved": "https://registry.npmjs.org/decamelize/-/decamelize-1.2.0.tgz", + "integrity": "sha512-z2S+W9X73hAUUki+N+9Za2lBlun89zigOyGrsax+KUQ6wKW4ZoWpEYBkGhQjwAjjDCkWxhY0VKEhk8wzY7F5cA==", + "dev": true + }, + "decamelize-keys": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/decamelize-keys/-/decamelize-keys-1.1.1.tgz", + "integrity": "sha512-WiPxgEirIV0/eIOMcnFBA3/IJZAZqKnwAwWyvvdi4lsr1WCN22nhdf/3db3DoZcUjTV2SqfzIwNyp6y2xs3nmg==", + "dev": true, + "requires": { + "decamelize": "^1.1.0", + "map-obj": "^1.0.0" + }, + "dependencies": { + "map-obj": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/map-obj/-/map-obj-1.0.1.tgz", + "integrity": "sha512-7N/q3lyZ+LVCp7PzuxrJr4KMbBE2hW7BT7YNia330OFxIf4d3r5zVpicP2650l7CPN6RM9zOJRl3NGpqSiw3Eg==", + "dev": true + } + } + }, + "decode-uri-component": { + "version": "0.2.2", + "resolved": "https://registry.npmjs.org/decode-uri-component/-/decode-uri-component-0.2.2.tgz", + "integrity": "sha512-FqUYQ+8o158GyGTrMFJms9qh3CqTKvAqgqsTnkLI8sKu0028orqBhxNMFkFen0zGyg6epACD32pjVk58ngIErQ==", + "dev": true + }, + "decompress-response": { + "version": "6.0.0", + "resolved": "https://registry.npmjs.org/decompress-response/-/decompress-response-6.0.0.tgz", + "integrity": "sha512-aW35yZM6Bb/4oJlZncMH2LCoZtJXTRxES17vE3hoRiowU2kWHaJKFkSBDnDR+cm9J+9QhXmREyIfv0pji9ejCQ==", + "dev": true, + "requires": { + "mimic-response": "^3.1.0" + }, + "dependencies": { + "mimic-response": { + "version": "3.1.0", + "resolved": "https://registry.npmjs.org/mimic-response/-/mimic-response-3.1.0.tgz", + "integrity": "sha512-z0yWI+4FDrrweS8Zmt4Ej5HdJmky15+L2e6Wgn3+iK5fWzb6T3fhNFq2+MeTRb064c6Wr4N/wv0DzQTjNzHNGQ==", + "dev": true + } + } + }, + "deep-eql": { + "version": "4.1.3", + "resolved": "https://registry.npmjs.org/deep-eql/-/deep-eql-4.1.3.tgz", + "integrity": "sha512-WaEtAOpRA1MQ0eohqZjpGD8zdI0Ovsm8mmFhaDN8dvDZzyoUMcYDnf5Y6iu7HTXxf8JDS23qWa4a+hKCDyOPzw==", + "dev": true, + "requires": { + "type-detect": "^4.0.0" + } + }, + "deep-is": { + "version": "0.1.4", + "resolved": "https://registry.npmjs.org/deep-is/-/deep-is-0.1.4.tgz", + "integrity": "sha512-oIPzksmTg4/MriiaYGO+okXDT7ztn/w3Eptv/+gSIdMdKsJo0u4CfYNFJPy+4SKMuCqGw2wxnA+URMg3t8a/bQ==", + "dev": true + }, + "defaults": { + "version": "1.0.4", + "resolved": "https://registry.npmjs.org/defaults/-/defaults-1.0.4.tgz", + "integrity": "sha512-eFuaLoy/Rxalv2kr+lqMlUnrDWV+3j4pljOIJgLIhI058IQfWJ7vXhyEIHu+HtC738klGALYxOKDO0bQP3tg8A==", + "dev": true, + "requires": { + "clone": "^1.0.2" + } + }, + "defer-to-connect": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/defer-to-connect/-/defer-to-connect-2.0.1.tgz", + "integrity": "sha512-4tvttepXG1VaYGrRibk5EwJd1t4udunSOVMdLSAL6mId1ix438oPwPZMALY41FCijukO1L0twNcGsdzS7dHgDg==", + "dev": true + }, + "define-properties": { + "version": "1.2.0", + "resolved": "https://registry.npmjs.org/define-properties/-/define-properties-1.2.0.tgz", + "integrity": "sha512-xvqAVKGfT1+UAvPwKTVw/njhdQ8ZhXK4lI0bCIuCMrp2up9nPnaDftrLtmpTazqd1o+UY4zgzU+avtMbDP+ldA==", + "dev": true, + "requires": { + "has-property-descriptors": "^1.0.0", + "object-keys": "^1.1.1" + } + }, + "delayed-stream": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/delayed-stream/-/delayed-stream-1.0.0.tgz", + "integrity": "sha512-ZySD7Nf91aLB0RxL4KGrKHBXl7Eds1DAmEdcoVawXnLD7SDhpNgtuII2aAkg7a7QS41jxPSZ17p4VdGnMHk3MQ==", + "dev": true + }, + "depd": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/depd/-/depd-2.0.0.tgz", + "integrity": "sha512-g7nH6P6dyDioJogAAGprGpCtVImJhpPk/roCzdb3fIh61/s/nPsfR6onyMwkCAR/OlC3yBC0lESvUoQEAssIrw==", + "dev": true + }, + "destroy": { + "version": "1.2.0", + "resolved": "https://registry.npmjs.org/destroy/-/destroy-1.2.0.tgz", + "integrity": "sha512-2sJGJTaXIIaR1w4iJSNoN0hnMY7Gpc/n8D4qSCJw8QqFWXf7cuAgnEHxBpweaVcPevC2l3KpjYCx3NypQQgaJg==", + "dev": true + }, + "detect-indent": { + "version": "6.1.0", + "resolved": "https://registry.npmjs.org/detect-indent/-/detect-indent-6.1.0.tgz", + "integrity": "sha512-reYkTUJAZb9gUuZ2RvVCNhVHdg62RHnJ7WJl8ftMi4diZ6NWlciOzQN88pUhSELEwflJht4oQDv0F0BMlwaYtA==", + "dev": true + }, + "detect-port": { + "version": "1.5.1", + "resolved": "https://registry.npmjs.org/detect-port/-/detect-port-1.5.1.tgz", + "integrity": "sha512-aBzdj76lueB6uUst5iAs7+0H/oOjqI5D16XUWxlWMIMROhcM0rfsNVk93zTngq1dDNpoXRr++Sus7ETAExppAQ==", + "dev": true, + "requires": { + "address": "^1.0.1", + "debug": "4" + } + }, + "diff": { + "version": "5.0.0", + "resolved": "https://registry.npmjs.org/diff/-/diff-5.0.0.tgz", + "integrity": "sha512-/VTCrvm5Z0JGty/BWHljh+BAiw3IK+2j87NGMu8Nwc/f48WoDAC395uomO9ZD117ZOBaHmkX1oyLvkVM/aIT3w==", + "dev": true + }, + "difflib": { + "version": "0.2.4", + "resolved": "https://registry.npmjs.org/difflib/-/difflib-0.2.4.tgz", + "integrity": "sha512-9YVwmMb0wQHQNr5J9m6BSj6fk4pfGITGQOOs+D9Fl+INODWFOfvhIU1hNv6GgR1RBoC/9NJcwu77zShxV0kT7w==", + "dev": true, + "requires": { + "heap": ">= 0.2.0" + } + }, + "dir-glob": { + "version": "3.0.1", + "resolved": "https://registry.npmjs.org/dir-glob/-/dir-glob-3.0.1.tgz", + "integrity": "sha512-WkrWp9GR4KXfKGYzOLmTuGVi1UWFfws377n9cc55/tb6DuqyF6pcQ5AbiHEshaDpY9v6oaSr2XCDidGmMwdzIA==", + "dev": true, + "requires": { + "path-type": "^4.0.0" + } + }, + "doctrine": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/doctrine/-/doctrine-3.0.0.tgz", + "integrity": "sha512-yS+Q5i3hBf7GBkd4KG8a7eBNNWNGLTaEwwYWUijIYM7zrlYDM0BFXHjjPWlWZ1Rg7UaddZeIDmi9jF3HmqiQ2w==", + "dev": true, + "requires": { + "esutils": "^2.0.2" + } + }, + "dom-serializer": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/dom-serializer/-/dom-serializer-2.0.0.tgz", + "integrity": "sha512-wIkAryiqt/nV5EQKqQpo3SToSOV9J0DnbJqwK7Wv/Trc92zIAYZ4FlMu+JPFW1DfGFt81ZTCGgDEabffXeLyJg==", + "dev": true, + "requires": { + "domelementtype": "^2.3.0", + "domhandler": "^5.0.2", + "entities": "^4.2.0" + } + }, + "dom-walk": { + "version": "0.1.2", + "resolved": "https://registry.npmjs.org/dom-walk/-/dom-walk-0.1.2.tgz", + "integrity": "sha512-6QvTW9mrGeIegrFXdtQi9pk7O/nSK6lSdXW2eqUspN5LWD7UTji2Fqw5V2YLjBpHEoU9Xl/eUWNpDeZvoyOv2w==", + "dev": true + }, + "domelementtype": { + "version": "2.3.0", + "resolved": "https://registry.npmjs.org/domelementtype/-/domelementtype-2.3.0.tgz", + "integrity": "sha512-OLETBj6w0OsagBwdXnPdN0cnMfF9opN69co+7ZrbfPGrdpPVNBUj02spi6B1N7wChLQiPn4CSH/zJvXw56gmHw==", + "dev": true + }, + "domhandler": { + "version": "5.0.3", + "resolved": "https://registry.npmjs.org/domhandler/-/domhandler-5.0.3.tgz", + "integrity": "sha512-cgwlv/1iFQiFnU96XXgROh8xTeetsnJiDsTc7TYCLFd9+/WNkIqPTxiM/8pSd8VIrhXGTf1Ny1q1hquVqDJB5w==", + "dev": true, + "requires": { + "domelementtype": "^2.3.0" + } + }, + "domutils": { + "version": "3.1.0", + "resolved": "https://registry.npmjs.org/domutils/-/domutils-3.1.0.tgz", + "integrity": "sha512-H78uMmQtI2AhgDJjWeQmHwJJ2bLPD3GMmO7Zja/ZZh84wkm+4ut+IUnUdRa8uCGX88DiVx1j6FRe1XfxEgjEZA==", + "dev": true, + "requires": { + "dom-serializer": "^2.0.0", + "domelementtype": "^2.3.0", + "domhandler": "^5.0.3" + } + }, + "dot-case": { + "version": "2.1.1", + "resolved": "https://registry.npmjs.org/dot-case/-/dot-case-2.1.1.tgz", + "integrity": "sha512-HnM6ZlFqcajLsyudHq7LeeLDr2rFAVYtDv/hV5qchQEidSck8j9OPUsXY9KwJv/lHMtYlX4DjRQqwFYa+0r8Ug==", + "dev": true, + "requires": { + "no-case": "^2.2.0" + } + }, + "dotenv": { + "version": "8.6.0", + "resolved": "https://registry.npmjs.org/dotenv/-/dotenv-8.6.0.tgz", + "integrity": "sha512-IrPdXQsk2BbzvCBGBOTmmSH5SodmqZNt4ERAZDmW4CT+tL8VtvinqywuANaFu4bOMWki16nqf0e4oC0QIaDr/g==", + "dev": true + }, + "ecc-jsbn": { + "version": "0.1.2", + "resolved": "https://registry.npmjs.org/ecc-jsbn/-/ecc-jsbn-0.1.2.tgz", + "integrity": "sha512-eh9O+hwRHNbG4BLTjEl3nw044CkGm5X6LoaCf7LPp7UU8Qrt47JYNi6nPX8xjW97TKGKm1ouctg0QSpZe9qrnw==", + "dev": true, + "requires": { + "jsbn": "~0.1.0", + "safer-buffer": "^2.1.0" + } + }, + "ee-first": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/ee-first/-/ee-first-1.1.1.tgz", + "integrity": "sha512-WMwm9LhRUo+WUaRN+vRuETqG89IgZphVSNkdFgeb6sS/E4OrDIN7t48CAewSHXc6C8lefD8KKfr5vY61brQlow==", + "dev": true + }, + "elliptic": { + "version": "6.5.4", + "resolved": "https://registry.npmjs.org/elliptic/-/elliptic-6.5.4.tgz", + "integrity": "sha512-iLhC6ULemrljPZb+QutR5TQGB+pdW6KGD5RSegS+8sorOZT+rdQFbsQFJgvN3eRqNALqJer4oQ16YvJHlU8hzQ==", + "dev": true, + "requires": { + "bn.js": "^4.11.9", + "brorand": "^1.1.0", + "hash.js": "^1.0.0", + "hmac-drbg": "^1.0.1", + "inherits": "^2.0.4", + "minimalistic-assert": "^1.0.1", + "minimalistic-crypto-utils": "^1.0.1" + } + }, + "emoji-regex": { + "version": "8.0.0", + "resolved": "https://registry.npmjs.org/emoji-regex/-/emoji-regex-8.0.0.tgz", + "integrity": "sha512-MSjYzcWNOA0ewAHpz0MxpYFvwg6yjy1NG3xteoqz644VCo/RPgnr1/GGt+ic3iJTzQ8Eu3TdM14SawnVUmGE6A==", + "dev": true + }, + "encodeurl": { + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/encodeurl/-/encodeurl-1.0.2.tgz", + "integrity": "sha512-TPJXq8JqFaVYm2CWmPvnP2Iyo4ZSM7/QKcSmuMLDObfpH5fi7RUGmd/rTDf+rut/saiDiQEeVTNgAmJEdAOx0w==", + "dev": true + }, + "end-of-stream": { + "version": "1.4.4", + "resolved": "https://registry.npmjs.org/end-of-stream/-/end-of-stream-1.4.4.tgz", + "integrity": "sha512-+uw1inIHVPQoaVuHzRyXd21icM+cnt4CzD5rW+NC1wjOUSTOs+Te7FOv7AhN7vS9x/oIyhLP5PR1H+phQAHu5Q==", + "dev": true, + "requires": { + "once": "^1.4.0" + } + }, + "enquirer": { + "version": "2.3.6", + "resolved": "https://registry.npmjs.org/enquirer/-/enquirer-2.3.6.tgz", + "integrity": "sha512-yjNnPr315/FjS4zIsUxYguYUPP2e1NK4d7E7ZOLiyYCcbFBiTMyID+2wvm2w6+pZ/odMA7cRkjhsPbltwBOrLg==", + "dev": true, + "requires": { + "ansi-colors": "^4.1.1" + } + }, + "entities": { + "version": "4.5.0", + "resolved": "https://registry.npmjs.org/entities/-/entities-4.5.0.tgz", + "integrity": "sha512-V0hjH4dGPh9Ao5p0MoRY6BVqtwCjhz6vI5LT8AJ55H+4g9/4vbHx1I54fS0XuclLhDHArPQCiMjDxjaL8fPxhw==", + "dev": true + }, + "env-paths": { + "version": "2.2.1", + "resolved": "https://registry.npmjs.org/env-paths/-/env-paths-2.2.1.tgz", + "integrity": "sha512-+h1lkLKhZMTYjog1VEpJNG7NZJWcuc2DDk/qsqSTRRCOXiLjeQ1d1/udrUGhqMxUgAlwKNZ0cf2uqan5GLuS2A==", + "dev": true + }, + "error-ex": { + "version": "1.3.2", + "resolved": "https://registry.npmjs.org/error-ex/-/error-ex-1.3.2.tgz", + "integrity": "sha512-7dFHNmqeFSEt2ZBsCriorKnn3Z2pj+fd9kmI6QoWw4//DL+icEBfc0U7qJCisqrTsKTjw4fNFy2pW9OqStD84g==", + "dev": true, + "requires": { + "is-arrayish": "^0.2.1" + } + }, + "es-abstract": { + "version": "1.21.2", + "resolved": "https://registry.npmjs.org/es-abstract/-/es-abstract-1.21.2.tgz", + "integrity": "sha512-y/B5POM2iBnIxCiernH1G7rC9qQoM77lLIMQLuob0zhp8C56Po81+2Nj0WFKnd0pNReDTnkYryc+zhOzpEIROg==", + "dev": true, + "requires": { + "array-buffer-byte-length": "^1.0.0", + "available-typed-arrays": "^1.0.5", + "call-bind": "^1.0.2", + "es-set-tostringtag": "^2.0.1", + "es-to-primitive": "^1.2.1", + "function.prototype.name": "^1.1.5", + "get-intrinsic": "^1.2.0", + "get-symbol-description": "^1.0.0", + "globalthis": "^1.0.3", + "gopd": "^1.0.1", + "has": "^1.0.3", + "has-property-descriptors": "^1.0.0", + "has-proto": "^1.0.1", + "has-symbols": "^1.0.3", + "internal-slot": "^1.0.5", + "is-array-buffer": "^3.0.2", + "is-callable": "^1.2.7", + "is-negative-zero": "^2.0.2", + "is-regex": "^1.1.4", + "is-shared-array-buffer": "^1.0.2", + "is-string": "^1.0.7", + "is-typed-array": "^1.1.10", + "is-weakref": "^1.0.2", + "object-inspect": "^1.12.3", + "object-keys": "^1.1.1", + "object.assign": "^4.1.4", + "regexp.prototype.flags": "^1.4.3", + "safe-regex-test": "^1.0.0", + "string.prototype.trim": "^1.2.7", + "string.prototype.trimend": "^1.0.6", + "string.prototype.trimstart": "^1.0.6", + "typed-array-length": "^1.0.4", + "unbox-primitive": "^1.0.2", + "which-typed-array": "^1.1.9" + } + }, + "es-array-method-boxes-properly": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/es-array-method-boxes-properly/-/es-array-method-boxes-properly-1.0.0.tgz", + "integrity": "sha512-wd6JXUmyHmt8T5a2xreUwKcGPq6f1f+WwIJkijUqiGcJz1qqnZgP6XIK+QyIWU5lT7imeNxUll48bziG+TSYcA==", + "dev": true + }, + "es-set-tostringtag": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/es-set-tostringtag/-/es-set-tostringtag-2.0.1.tgz", + "integrity": "sha512-g3OMbtlwY3QewlqAiMLI47KywjWZoEytKr8pf6iTC8uJq5bIAH52Z9pnQ8pVL6whrCto53JZDuUIsifGeLorTg==", + "dev": true, + "requires": { + "get-intrinsic": "^1.1.3", + "has": "^1.0.3", + "has-tostringtag": "^1.0.0" + } + }, + "es-shim-unscopables": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/es-shim-unscopables/-/es-shim-unscopables-1.0.0.tgz", + "integrity": "sha512-Jm6GPcCdC30eMLbZ2x8z2WuRwAws3zTBBKuusffYVUrNj/GVSUAZ+xKMaUpfNDR5IbyNA5LJbaecoUVbmUcB1w==", + "dev": true, + "requires": { + "has": "^1.0.3" + } + }, + "es-to-primitive": { + "version": "1.2.1", + "resolved": "https://registry.npmjs.org/es-to-primitive/-/es-to-primitive-1.2.1.tgz", + "integrity": "sha512-QCOllgZJtaUo9miYBcLChTUaHNjJF3PYs1VidD7AwiEj1kYxKeQTctLAezAOH5ZKRH0g2IgPn6KwB4IT8iRpvA==", + "dev": true, + "requires": { + "is-callable": "^1.1.4", + "is-date-object": "^1.0.1", + "is-symbol": "^1.0.2" + } + }, + "es5-ext": { + "version": "0.10.62", + "resolved": "https://registry.npmjs.org/es5-ext/-/es5-ext-0.10.62.tgz", + "integrity": "sha512-BHLqn0klhEpnOKSrzn/Xsz2UIW8j+cGmo9JLzr8BiUapV8hPL9+FliFqjwr9ngW7jWdnxv6eO+/LqyhJVqgrjA==", + "dev": true, + "requires": { + "es6-iterator": "^2.0.3", + "es6-symbol": "^3.1.3", + "next-tick": "^1.1.0" + } + }, + "es6-iterator": { + "version": "2.0.3", + "resolved": "https://registry.npmjs.org/es6-iterator/-/es6-iterator-2.0.3.tgz", + "integrity": "sha512-zw4SRzoUkd+cl+ZoE15A9o1oQd920Bb0iOJMQkQhl3jNc03YqVjAhG7scf9C5KWRU/R13Orf588uCC6525o02g==", + "dev": true, + "requires": { + "d": "1", + "es5-ext": "^0.10.35", + "es6-symbol": "^3.1.1" + } + }, + "es6-promise": { + "version": "4.2.8", + "resolved": "https://registry.npmjs.org/es6-promise/-/es6-promise-4.2.8.tgz", + "integrity": "sha512-HJDGx5daxeIvxdBxvG2cb9g4tEvwIk3i8+nhX0yGrYmZUzbkdg8QbDevheDB8gd0//uPj4c1EQua8Q+MViT0/w==", + "dev": true + }, + "es6-symbol": { + "version": "3.1.3", + "resolved": "https://registry.npmjs.org/es6-symbol/-/es6-symbol-3.1.3.tgz", + "integrity": "sha512-NJ6Yn3FuDinBaBRWl/q5X/s4koRHBrgKAu+yGI6JCBeiu3qrcbJhwT2GeR/EXVfylRk8dpQVJoLEFhK+Mu31NA==", + "dev": true, + "requires": { + "d": "^1.0.1", + "ext": "^1.1.2" + } + }, + "escalade": { + "version": "3.1.1", + "resolved": "https://registry.npmjs.org/escalade/-/escalade-3.1.1.tgz", + "integrity": "sha512-k0er2gUkLf8O0zKJiAhmkTnJlTvINGv7ygDNPbeIsX/TJjGJZHuh9B2UxbsaEkmlEo9MfhrSzmhIlhRlI2GXnw==", + "dev": true + }, + "escape-html": { + "version": "1.0.3", + "resolved": "https://registry.npmjs.org/escape-html/-/escape-html-1.0.3.tgz", + "integrity": "sha512-NiSupZ4OeuGwr68lGIeym/ksIZMJodUGOSCZ/FSnTxcrekbvqrgdUxlJOMpijaKZVjAJrWrGs/6Jy8OMuyj9ow==", + "dev": true + }, + "escape-string-regexp": { + "version": "1.0.5", + "resolved": "https://registry.npmjs.org/escape-string-regexp/-/escape-string-regexp-1.0.5.tgz", + "integrity": "sha512-vbRorB5FUQWvla16U8R/qgaFIya2qGzwDrNmCZuYKrbdSUMG6I1ZCGQRefkRVhuOkIGVne7BQ35DSfo1qvJqFg==", + "dev": true + }, + "escodegen": { + "version": "1.8.1", + "resolved": "https://registry.npmjs.org/escodegen/-/escodegen-1.8.1.tgz", + "integrity": "sha512-yhi5S+mNTOuRvyW4gWlg5W1byMaQGWWSYHXsuFZ7GBo7tpyOwi2EdzMP/QWxh9hwkD2m+wDVHJsxhRIj+v/b/A==", + "dev": true, + "requires": { + "esprima": "^2.7.1", + "estraverse": "^1.9.1", + "esutils": "^2.0.2", + "optionator": "^0.8.1", + "source-map": "~0.2.0" + }, + "dependencies": { + "esprima": { + "version": "2.7.3", + "resolved": "https://registry.npmjs.org/esprima/-/esprima-2.7.3.tgz", + "integrity": "sha512-OarPfz0lFCiW4/AV2Oy1Rp9qu0iusTKqykwTspGCZtPxmF81JR4MmIebvF1F9+UOKth2ZubLQ4XGGaU+hSn99A==", + "dev": true + }, + "estraverse": { + "version": "1.9.3", + "resolved": "https://registry.npmjs.org/estraverse/-/estraverse-1.9.3.tgz", + "integrity": "sha512-25w1fMXQrGdoquWnScXZGckOv+Wes+JDnuN/+7ex3SauFRS72r2lFDec0EKPt2YD1wUJ/IrfEex+9yp4hfSOJA==", + "dev": true + }, + "levn": { + "version": "0.3.0", + "resolved": "https://registry.npmjs.org/levn/-/levn-0.3.0.tgz", + "integrity": "sha512-0OO4y2iOHix2W6ujICbKIaEQXvFQHue65vUG3pb5EUomzPI90z9hsA1VsO/dbIIpC53J8gxM9Q4Oho0jrCM/yA==", + "dev": true, + "requires": { + "prelude-ls": "~1.1.2", + "type-check": "~0.3.2" + } + }, + "optionator": { + "version": "0.8.3", + "resolved": "https://registry.npmjs.org/optionator/-/optionator-0.8.3.tgz", + "integrity": "sha512-+IW9pACdk3XWmmTXG8m3upGUJst5XRGzxMRjXzAuJ1XnIFNvfhjjIuYkDvysnPQ7qzqVzLt78BCruntqRhWQbA==", + "dev": true, + "requires": { + "deep-is": "~0.1.3", + "fast-levenshtein": "~2.0.6", + "levn": "~0.3.0", + "prelude-ls": "~1.1.2", + "type-check": "~0.3.2", + "word-wrap": "~1.2.3" + } + }, + "prelude-ls": { + "version": "1.1.2", + "resolved": "https://registry.npmjs.org/prelude-ls/-/prelude-ls-1.1.2.tgz", + "integrity": "sha512-ESF23V4SKG6lVSGZgYNpbsiaAkdab6ZgOxe52p7+Kid3W3u3bxR4Vfd/o21dmN7jSt0IwgZ4v5MUd26FEtXE9w==", + "dev": true + }, + "type-check": { + "version": "0.3.2", + "resolved": "https://registry.npmjs.org/type-check/-/type-check-0.3.2.tgz", + "integrity": "sha512-ZCmOJdvOWDBYJlzAoFkC+Q0+bUyEOS1ltgp1MGU03fqHG+dbi9tBFU2Rd9QKiDZFAYrhPh2JUf7rZRIuHRKtOg==", + "dev": true, + "requires": { + "prelude-ls": "~1.1.2" + } + } + } + }, + "eslint": { + "version": "8.44.0", + "resolved": "https://registry.npmjs.org/eslint/-/eslint-8.44.0.tgz", + "integrity": "sha512-0wpHoUbDUHgNCyvFB5aXLiQVfK9B0at6gUvzy83k4kAsQ/u769TQDX6iKC+aO4upIHO9WSaA3QoXYQDHbNwf1A==", + "dev": true, + "requires": { + "@eslint-community/eslint-utils": "^4.2.0", + "@eslint-community/regexpp": "^4.4.0", + "@eslint/eslintrc": "^2.1.0", + "@eslint/js": "8.44.0", + "@humanwhocodes/config-array": "^0.11.10", + "@humanwhocodes/module-importer": "^1.0.1", + "@nodelib/fs.walk": "^1.2.8", + "ajv": "^6.10.0", + "chalk": "^4.0.0", + "cross-spawn": "^7.0.2", + "debug": "^4.3.2", + "doctrine": "^3.0.0", + "escape-string-regexp": "^4.0.0", + "eslint-scope": "^7.2.0", + "eslint-visitor-keys": "^3.4.1", + "espree": "^9.6.0", + "esquery": "^1.4.2", + "esutils": "^2.0.2", + "fast-deep-equal": "^3.1.3", + "file-entry-cache": "^6.0.1", + "find-up": "^5.0.0", + "glob-parent": "^6.0.2", + "globals": "^13.19.0", + "graphemer": "^1.4.0", + "ignore": "^5.2.0", + "import-fresh": "^3.0.0", + "imurmurhash": "^0.1.4", + "is-glob": "^4.0.0", + "is-path-inside": "^3.0.3", + "js-yaml": "^4.1.0", + "json-stable-stringify-without-jsonify": "^1.0.1", + "levn": "^0.4.1", + "lodash.merge": "^4.6.2", + "minimatch": "^3.1.2", + "natural-compare": "^1.4.0", + "optionator": "^0.9.3", + "strip-ansi": "^6.0.1", + "strip-json-comments": "^3.1.0", + "text-table": "^0.2.0" + }, + "dependencies": { + "ansi-regex": { + "version": "5.0.1", + "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-5.0.1.tgz", + "integrity": "sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ==", + "dev": true + }, + "ansi-styles": { + "version": "4.3.0", + "resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-4.3.0.tgz", + "integrity": "sha512-zbB9rCJAT1rbjiVDb2hqKFHNYLxgtk8NURxZ3IZwD3F6NtxbXZQCnnSi1Lkx+IDohdPlFp222wVALIheZJQSEg==", + "dev": true, + "requires": { + "color-convert": "^2.0.1" + } + }, + "argparse": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/argparse/-/argparse-2.0.1.tgz", + "integrity": "sha512-8+9WqebbFzpX9OR+Wa6O29asIogeRMzcGtAINdpMHHyAg10f05aSFVBbcEqGf/PXw1EjAZ+q2/bEBg3DvurK3Q==", + "dev": true + }, + "chalk": { + "version": "4.1.2", + "resolved": "https://registry.npmjs.org/chalk/-/chalk-4.1.2.tgz", + "integrity": "sha512-oKnbhFyRIXpUuez8iBMmyEa4nbj4IOQyuhc/wy9kY7/WVPcwIO9VA668Pu8RkO7+0G76SLROeyw9CpQ061i4mA==", + "dev": true, + "requires": { + "ansi-styles": "^4.1.0", + "supports-color": "^7.1.0" + } + }, + "color-convert": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/color-convert/-/color-convert-2.0.1.tgz", + "integrity": "sha512-RRECPsj7iu/xb5oKYcsFHSppFNnsj/52OVTRKb4zP5onXwVF3zVmmToNcOfGC+CRDpfK/U584fMg38ZHCaElKQ==", + "dev": true, + "requires": { + "color-name": "~1.1.4" + } + }, + "color-name": { + "version": "1.1.4", + "resolved": "https://registry.npmjs.org/color-name/-/color-name-1.1.4.tgz", + "integrity": "sha512-dOy+3AuW3a2wNbZHIuMZpTcgjGuLU/uBL/ubcZF9OXbDo8ff4O8yVp5Bf0efS8uEoYo5q4Fx7dY9OgQGXgAsQA==", + "dev": true + }, + "escape-string-regexp": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/escape-string-regexp/-/escape-string-regexp-4.0.0.tgz", + "integrity": "sha512-TtpcNJ3XAzx3Gq8sWRzJaVajRs0uVxA2YAkdb1jm2YkPz4G6egUFAyA3n5vtEIZefPk5Wa4UXbKuS5fKkJWdgA==", + "dev": true + }, + "find-up": { + "version": "5.0.0", + "resolved": "https://registry.npmjs.org/find-up/-/find-up-5.0.0.tgz", + "integrity": "sha512-78/PXT1wlLLDgTzDs7sjq9hzz0vXD+zn+7wypEe4fXQxCmdmqfGsEPQxmiCSQI3ajFV91bVSsvNtrJRiW6nGng==", + "dev": true, + "requires": { + "locate-path": "^6.0.0", + "path-exists": "^4.0.0" + } + }, + "glob-parent": { + "version": "6.0.2", + "resolved": "https://registry.npmjs.org/glob-parent/-/glob-parent-6.0.2.tgz", + "integrity": "sha512-XxwI8EOhVQgWp6iDL+3b0r86f4d6AX6zSU55HfB4ydCEuXLXc5FcYeOu+nnGftS4TEju/11rt4KJPTMgbfmv4A==", + "dev": true, + "requires": { + "is-glob": "^4.0.3" + } + }, + "has-flag": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/has-flag/-/has-flag-4.0.0.tgz", + "integrity": "sha512-EykJT/Q1KjTWctppgIAgfSO0tKVuZUjhgMr17kqTumMl6Afv3EISleU7qZUzoXDFTAHTDC4NOoG/ZxU3EvlMPQ==", + "dev": true + }, + "js-yaml": { + "version": "4.1.0", + "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-4.1.0.tgz", + "integrity": "sha512-wpxZs9NoxZaJESJGIZTyDEaYpl0FKSA+FB9aJiyemKhMwkxQg63h4T1KJgUGHpTqPDNRcmmYLugrRjJlBtWvRA==", + "dev": true, + "requires": { + "argparse": "^2.0.1" + } + }, + "locate-path": { + "version": "6.0.0", + "resolved": "https://registry.npmjs.org/locate-path/-/locate-path-6.0.0.tgz", + "integrity": "sha512-iPZK6eYjbxRu3uB4/WZ3EsEIMJFMqAoopl3R+zuq0UjcAm/MO6KCweDgPfP3elTztoKP3KtnVHxTn2NHBSDVUw==", + "dev": true, + "requires": { + "p-locate": "^5.0.0" + } + }, + "p-locate": { + "version": "5.0.0", + "resolved": "https://registry.npmjs.org/p-locate/-/p-locate-5.0.0.tgz", + "integrity": "sha512-LaNjtRWUBY++zB5nE/NwcaoMylSPk+S+ZHNB1TzdbMJMny6dynpAGt7X/tl/QYq3TIeE6nxHppbo2LGymrG5Pw==", + "dev": true, + "requires": { + "p-limit": "^3.0.2" + } + }, + "strip-ansi": { + "version": "6.0.1", + "resolved": "https://registry.npmjs.org/strip-ansi/-/strip-ansi-6.0.1.tgz", + "integrity": "sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A==", + "dev": true, + "requires": { + "ansi-regex": "^5.0.1" + } + }, + "supports-color": { + "version": "7.2.0", + "resolved": "https://registry.npmjs.org/supports-color/-/supports-color-7.2.0.tgz", + "integrity": "sha512-qpCAvRl9stuOHveKsn7HncJRvv501qIacKzQlO/+Lwxc9+0q2wLyv4Dfvt80/DPn2pqOBsJdDiogXGR9+OvwRw==", + "dev": true, + "requires": { + "has-flag": "^4.0.0" + } + } + } + }, + "eslint-config-prettier": { + "version": "9.0.0", + "resolved": "https://registry.npmjs.org/eslint-config-prettier/-/eslint-config-prettier-9.0.0.tgz", + "integrity": "sha512-IcJsTkJae2S35pRsRAwoCE+925rJJStOdkKnLVgtE+tEpqU0EVVM7OqrwxqgptKdX29NUwC82I5pXsGFIgSevw==", + "dev": true, + "requires": {} + }, + "eslint-scope": { + "version": "7.2.0", + "resolved": "https://registry.npmjs.org/eslint-scope/-/eslint-scope-7.2.0.tgz", + "integrity": "sha512-DYj5deGlHBfMt15J7rdtyKNq/Nqlv5KfU4iodrQ019XESsRnwXH9KAE0y3cwtUHDo2ob7CypAnCqefh6vioWRw==", + "dev": true, + "requires": { + "esrecurse": "^4.3.0", + "estraverse": "^5.2.0" + } + }, + "eslint-visitor-keys": { + "version": "3.4.1", + "resolved": "https://registry.npmjs.org/eslint-visitor-keys/-/eslint-visitor-keys-3.4.1.tgz", + "integrity": "sha512-pZnmmLwYzf+kWaM/Qgrvpen51upAktaaiI01nsJD/Yr3lMOdNtq0cxkrrg16w64VtisN6okbs7Q8AfGqj4c9fA==", + "dev": true + }, + "espree": { + "version": "9.6.0", + "resolved": "https://registry.npmjs.org/espree/-/espree-9.6.0.tgz", + "integrity": "sha512-1FH/IiruXZ84tpUlm0aCUEwMl2Ho5ilqVh0VvQXw+byAz/4SAciyHLlfmL5WYqsvD38oymdUwBss0LtK8m4s/A==", + "dev": true, + "requires": { + "acorn": "^8.9.0", + "acorn-jsx": "^5.3.2", + "eslint-visitor-keys": "^3.4.1" + } + }, + "esprima": { + "version": "4.0.1", + "resolved": "https://registry.npmjs.org/esprima/-/esprima-4.0.1.tgz", + "integrity": "sha512-eGuFFw7Upda+g4p+QHvnW0RyTX/SVeJBDM/gCtMARO0cLuT2HcEKnTPvhjV6aGeqrCB/sbNop0Kszm0jsaWU4A==", + "dev": true + }, + "esquery": { + "version": "1.5.0", + "resolved": "https://registry.npmjs.org/esquery/-/esquery-1.5.0.tgz", + "integrity": "sha512-YQLXUplAwJgCydQ78IMJywZCceoqk1oH01OERdSAJc/7U2AylwjhSCLDEtqwg811idIS/9fIU5GjG73IgjKMVg==", + "dev": true, + "requires": { + "estraverse": "^5.1.0" + } + }, + "esrecurse": { + "version": "4.3.0", + "resolved": "https://registry.npmjs.org/esrecurse/-/esrecurse-4.3.0.tgz", + "integrity": "sha512-KmfKL3b6G+RXvP8N1vr3Tq1kL/oCFgn2NYXEtqP8/L3pKapUA4G8cFVaoF3SU323CD4XypR/ffioHmkti6/Tag==", + "dev": true, + "requires": { + "estraverse": "^5.2.0" + } + }, + "estraverse": { + "version": "5.3.0", + "resolved": "https://registry.npmjs.org/estraverse/-/estraverse-5.3.0.tgz", + "integrity": "sha512-MMdARuVEQziNTeJD8DgMqmhwR11BRQ/cBP+pLtYdSTnf3MIO8fFeiINEbX36ZdNlfU/7A9f3gUw49B3oQsvwBA==", + "dev": true + }, + "esutils": { + "version": "2.0.3", + "resolved": "https://registry.npmjs.org/esutils/-/esutils-2.0.3.tgz", + "integrity": "sha512-kVscqXk4OCp68SZ0dkgEKVi6/8ij300KBWTJq32P/dYeWTSwK41WyTxalN1eRmA5Z9UU/LX9D7FWSmV9SAYx6g==", + "dev": true + }, + "etag": { + "version": "1.8.1", + "resolved": "https://registry.npmjs.org/etag/-/etag-1.8.1.tgz", + "integrity": "sha512-aIL5Fx7mawVa300al2BnEE4iNvo1qETxLrPI/o05L7z6go7fCw1J6EQmbK4FmJ2AS7kgVF/KEZWufBfdClMcPg==", + "dev": true + }, + "eth-ens-namehash": { + "version": "2.0.8", + "resolved": "https://registry.npmjs.org/eth-ens-namehash/-/eth-ens-namehash-2.0.8.tgz", + "integrity": "sha512-VWEI1+KJfz4Km//dadyvBBoBeSQ0MHTXPvr8UIXiLW6IanxvAV+DmlZAijZwAyggqGUfwQBeHf7tc9wzc1piSw==", + "dev": true, + "requires": { + "idna-uts46-hx": "^2.3.1", + "js-sha3": "^0.5.7" + }, + "dependencies": { + "js-sha3": { + "version": "0.5.7", + "resolved": "https://registry.npmjs.org/js-sha3/-/js-sha3-0.5.7.tgz", + "integrity": "sha512-GII20kjaPX0zJ8wzkTbNDYMY7msuZcTWk8S5UOh6806Jq/wz1J8/bnr8uGU0DAUmYDjj2Mr4X1cW8v/GLYnR+g==", + "dev": true + } + } + }, + "eth-gas-reporter": { + "version": "0.2.25", + "resolved": "https://registry.npmjs.org/eth-gas-reporter/-/eth-gas-reporter-0.2.25.tgz", + "integrity": "sha512-1fRgyE4xUB8SoqLgN3eDfpDfwEfRxh2Sz1b7wzFbyQA+9TekMmvSjjoRu9SKcSVyK+vLkLIsVbJDsTWjw195OQ==", + "dev": true, + "requires": { + "@ethersproject/abi": "^5.0.0-beta.146", + "@solidity-parser/parser": "^0.14.0", + "cli-table3": "^0.5.0", + "colors": "1.4.0", + "ethereum-cryptography": "^1.0.3", + "ethers": "^4.0.40", + "fs-readdir-recursive": "^1.1.0", + "lodash": "^4.17.14", + "markdown-table": "^1.1.3", + "mocha": "^7.1.1", + "req-cwd": "^2.0.0", + "request": "^2.88.0", + "request-promise-native": "^1.0.5", + "sha1": "^1.1.1", + "sync-request": "^6.0.0" + }, + "dependencies": { + "ansi-colors": { + "version": "3.2.3", + "resolved": "https://registry.npmjs.org/ansi-colors/-/ansi-colors-3.2.3.tgz", + "integrity": "sha512-LEHHyuhlPY3TmuUYMh2oz89lTShfvgbmzaBcxve9t/9Wuy7Dwf4yoAKcND7KFT1HAQfqZ12qtc+DUrBMeKF9nw==", + "dev": true + }, + "ansi-regex": { + "version": "4.1.1", + "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-4.1.1.tgz", + "integrity": "sha512-ILlv4k/3f6vfQ4OoP2AGvirOktlQ98ZEL1k9FaQjxa3L1abBgbuTDAdPOpvbGncC0BTVQrl+OM8xZGK6tWXt7g==", + "dev": true + }, + "camelcase": { + "version": "5.3.1", + "resolved": "https://registry.npmjs.org/camelcase/-/camelcase-5.3.1.tgz", + "integrity": "sha512-L28STB170nwWS63UjtlEOE3dldQApaJXZkOI1uMFfzf3rRuPegHaHesyee+YxQ+W6SvRDQV6UrdOdRiR153wJg==", + "dev": true + }, + "chokidar": { + "version": "3.3.0", + "resolved": "https://registry.npmjs.org/chokidar/-/chokidar-3.3.0.tgz", + "integrity": "sha512-dGmKLDdT3Gdl7fBUe8XK+gAtGmzy5Fn0XkkWQuYxGIgWVPPse2CxFA5mtrlD0TOHaHjEUqkWNyP1XdHoJES/4A==", + "dev": true, + "requires": { + "anymatch": "~3.1.1", + "braces": "~3.0.2", + "fsevents": "~2.1.1", + "glob-parent": "~5.1.0", + "is-binary-path": "~2.1.0", + "is-glob": "~4.0.1", + "normalize-path": "~3.0.0", + "readdirp": "~3.2.0" + } + }, + "cliui": { + "version": "5.0.0", + "resolved": "https://registry.npmjs.org/cliui/-/cliui-5.0.0.tgz", + "integrity": "sha512-PYeGSEmmHM6zvoef2w8TPzlrnNpXIjTipYK780YswmIP9vjxmd6Y2a3CB2Ks6/AU8NHjZugXvo8w3oWM2qnwXA==", + "dev": true, + "requires": { + "string-width": "^3.1.0", + "strip-ansi": "^5.2.0", + "wrap-ansi": "^5.1.0" + } + }, + "debug": { + "version": "3.2.6", + "resolved": "https://registry.npmjs.org/debug/-/debug-3.2.6.tgz", + "integrity": "sha512-mel+jf7nrtEl5Pn1Qx46zARXKDpBbvzezse7p7LqINmdoIk8PYP5SySaxEmYv6TZ0JyEKA1hsCId6DIhgITtWQ==", + "dev": true, + "requires": { + "ms": "^2.1.1" + } + }, + "diff": { + "version": "3.5.0", + "resolved": "https://registry.npmjs.org/diff/-/diff-3.5.0.tgz", + "integrity": "sha512-A46qtFgd+g7pDZinpnwiRJtxbC1hpgf0uzP3iG89scHk0AUC7A1TGxf5OiiOUv/JMZR8GOt8hL900hV0bOy5xA==", + "dev": true + }, + "emoji-regex": { + "version": "7.0.3", + "resolved": "https://registry.npmjs.org/emoji-regex/-/emoji-regex-7.0.3.tgz", + "integrity": "sha512-CwBLREIQ7LvYFB0WyRvwhq5N5qPhc6PMjD6bYggFlI5YyDgl+0vxq5VHbMOFqLg7hfWzmu8T5Z1QofhmTIhItA==", + "dev": true + }, + "ethereum-cryptography": { + "version": "1.2.0", + "resolved": "https://registry.npmjs.org/ethereum-cryptography/-/ethereum-cryptography-1.2.0.tgz", + "integrity": "sha512-6yFQC9b5ug6/17CQpCyE3k9eKBMdhyVjzUy1WkiuY/E4vj/SXDBbCw8QEIaXqf0Mf2SnY6RmpDcwlUmBSS0EJw==", + "dev": true, + "requires": { + "@noble/hashes": "1.2.0", + "@noble/secp256k1": "1.7.1", + "@scure/bip32": "1.1.5", + "@scure/bip39": "1.1.1" + } + }, + "find-up": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/find-up/-/find-up-3.0.0.tgz", + "integrity": "sha512-1yD6RmLI1XBfxugvORwlck6f75tYL+iR0jqwsOrOxMZyGYqUuDhJ0l4AXdO1iX/FTs9cBAMEk1gWSEx1kSbylg==", + "dev": true, + "requires": { + "locate-path": "^3.0.0" + } + }, + "flat": { + "version": "4.1.1", + "resolved": "https://registry.npmjs.org/flat/-/flat-4.1.1.tgz", + "integrity": "sha512-FmTtBsHskrU6FJ2VxCnsDb84wu9zhmO3cUX2kGFb5tuwhfXxGciiT0oRY+cck35QmG+NmGh5eLz6lLCpWTqwpA==", + "dev": true, + "requires": { + "is-buffer": "~2.0.3" + } + }, + "fsevents": { + "version": "2.1.3", + "resolved": "https://registry.npmjs.org/fsevents/-/fsevents-2.1.3.tgz", + "integrity": "sha512-Auw9a4AxqWpa9GUfj370BMPzzyncfBABW8Mab7BGWBYDj4Isgq+cDKtx0i6u9jcX9pQDnswsaaOTgTmA5pEjuQ==", + "dev": true, + "optional": true + }, + "glob": { + "version": "7.1.3", + "resolved": "https://registry.npmjs.org/glob/-/glob-7.1.3.tgz", + "integrity": "sha512-vcfuiIxogLV4DlGBHIUOwI0IbrJ8HWPc4MU7HzviGeNho/UJDfi6B5p3sHeWIQ0KGIU0Jpxi5ZHxemQfLkkAwQ==", + "dev": true, + "requires": { + "fs.realpath": "^1.0.0", + "inflight": "^1.0.4", + "inherits": "2", + "minimatch": "^3.0.4", + "once": "^1.3.0", + "path-is-absolute": "^1.0.0" + } + }, + "js-yaml": { + "version": "3.13.1", + "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-3.13.1.tgz", + "integrity": "sha512-YfbcO7jXDdyj0DGxYVSlSeQNHbD7XPWvrVWeVUujrQEoZzWJIRrCPoyk6kL6IAjAG2IolMK4T0hNUe0HOUs5Jw==", + "dev": true, + "requires": { + "argparse": "^1.0.7", + "esprima": "^4.0.0" + } + }, + "locate-path": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/locate-path/-/locate-path-3.0.0.tgz", + "integrity": "sha512-7AO748wWnIhNqAuaty2ZWHkQHRSNfPVIsPIfwEOWO22AmaoVrWavlOcMR5nzTLNYvp36X220/maaRsrec1G65A==", + "dev": true, + "requires": { + "p-locate": "^3.0.0", + "path-exists": "^3.0.0" + } + }, + "log-symbols": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/log-symbols/-/log-symbols-3.0.0.tgz", + "integrity": "sha512-dSkNGuI7iG3mfvDzUuYZyvk5dD9ocYCYzNU6CYDE6+Xqd+gwme6Z00NS3dUh8mq/73HaEtT7m6W+yUPtU6BZnQ==", + "dev": true, + "requires": { + "chalk": "^2.4.2" + } + }, + "minimatch": { + "version": "3.0.4", + "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-3.0.4.tgz", + "integrity": "sha512-yJHVQEhyqPLUTgt9B83PXu6W3rx4MvvHvSUvToogpwoGDOUQ+yDrR0HRot+yOCdCO7u4hX3pWft6kWBBcqh0UA==", + "dev": true, + "requires": { + "brace-expansion": "^1.1.7" + } + }, + "mkdirp": { + "version": "0.5.5", + "resolved": "https://registry.npmjs.org/mkdirp/-/mkdirp-0.5.5.tgz", + "integrity": "sha512-NKmAlESf6jMGym1++R0Ra7wvhV+wFW63FaSOFPwRahvea0gMUcGUhVeAg/0BC0wiv9ih5NYPB1Wn1UEI1/L+xQ==", + "dev": true, + "requires": { + "minimist": "^1.2.5" + } + }, + "mocha": { + "version": "7.2.0", + "resolved": "https://registry.npmjs.org/mocha/-/mocha-7.2.0.tgz", + "integrity": "sha512-O9CIypScywTVpNaRrCAgoUnJgozpIofjKUYmJhiCIJMiuYnLI6otcb1/kpW9/n/tJODHGZ7i8aLQoDVsMtOKQQ==", + "dev": true, + "requires": { + "ansi-colors": "3.2.3", + "browser-stdout": "1.3.1", + "chokidar": "3.3.0", + "debug": "3.2.6", + "diff": "3.5.0", + "escape-string-regexp": "1.0.5", + "find-up": "3.0.0", + "glob": "7.1.3", + "growl": "1.10.5", + "he": "1.2.0", + "js-yaml": "3.13.1", + "log-symbols": "3.0.0", + "minimatch": "3.0.4", + "mkdirp": "0.5.5", + "ms": "2.1.1", + "node-environment-flags": "1.0.6", + "object.assign": "4.1.0", + "strip-json-comments": "2.0.1", + "supports-color": "6.0.0", + "which": "1.3.1", + "wide-align": "1.1.3", + "yargs": "13.3.2", + "yargs-parser": "13.1.2", + "yargs-unparser": "1.6.0" + } + }, + "ms": { + "version": "2.1.1", + "resolved": "https://registry.npmjs.org/ms/-/ms-2.1.1.tgz", + "integrity": "sha512-tgp+dl5cGk28utYktBsrFqA7HKgrhgPsg6Z/EfhWI4gl1Hwq8B/GmY/0oXZ6nF8hDVesS/FpnYaD/kOWhYQvyg==", + "dev": true + }, + "object.assign": { + "version": "4.1.0", + "resolved": "https://registry.npmjs.org/object.assign/-/object.assign-4.1.0.tgz", + "integrity": "sha512-exHJeq6kBKj58mqGyTQ9DFvrZC/eR6OwxzoM9YRoGBqrXYonaFyGiFMuc9VZrXf7DarreEwMpurG3dd+CNyW5w==", + "dev": true, + "requires": { + "define-properties": "^1.1.2", + "function-bind": "^1.1.1", + "has-symbols": "^1.0.0", + "object-keys": "^1.0.11" + } + }, + "p-limit": { + "version": "2.3.0", + "resolved": "https://registry.npmjs.org/p-limit/-/p-limit-2.3.0.tgz", + "integrity": "sha512-//88mFWSJx8lxCzwdAABTJL2MyWB12+eIY7MDL2SqLmAkeKU9qxRvWuSyTjm3FUmpBEMuFfckAIqEaVGUDxb6w==", + "dev": true, + "requires": { + "p-try": "^2.0.0" + } + }, + "p-locate": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/p-locate/-/p-locate-3.0.0.tgz", + "integrity": "sha512-x+12w/To+4GFfgJhBEpiDcLozRJGegY+Ei7/z0tSLkMmxGZNybVMSfWj9aJn8Z5Fc7dBUNJOOVgPv2H7IwulSQ==", + "dev": true, + "requires": { + "p-limit": "^2.0.0" + } + }, + "path-exists": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/path-exists/-/path-exists-3.0.0.tgz", + "integrity": "sha512-bpC7GYwiDYQ4wYLe+FA8lhRjhQCMcQGuSgGGqDkg/QerRWw9CmGRT0iSOVRSZJ29NMLZgIzqaljJ63oaL4NIJQ==", + "dev": true + }, + "readdirp": { + "version": "3.2.0", + "resolved": "https://registry.npmjs.org/readdirp/-/readdirp-3.2.0.tgz", + "integrity": "sha512-crk4Qu3pmXwgxdSgGhgA/eXiJAPQiX4GMOZZMXnqKxHX7TaoL+3gQVo/WeuAiogr07DpnfjIMpXXa+PAIvwPGQ==", + "dev": true, + "requires": { + "picomatch": "^2.0.4" + } + }, + "string-width": { + "version": "3.1.0", + "resolved": "https://registry.npmjs.org/string-width/-/string-width-3.1.0.tgz", + "integrity": "sha512-vafcv6KjVZKSgz06oM/H6GDBrAtz8vdhQakGjFIvNrHA6y3HCF1CInLy+QLq8dTJPQ1b+KDUqDFctkdRW44e1w==", + "dev": true, + "requires": { + "emoji-regex": "^7.0.1", + "is-fullwidth-code-point": "^2.0.0", + "strip-ansi": "^5.1.0" + } + }, + "strip-ansi": { + "version": "5.2.0", + "resolved": "https://registry.npmjs.org/strip-ansi/-/strip-ansi-5.2.0.tgz", + "integrity": "sha512-DuRs1gKbBqsMKIZlrffwlug8MHkcnpjs5VPmL1PAh+mA30U0DTotfDZ0d2UUsXpPmPmMMJ6W773MaA3J+lbiWA==", + "dev": true, + "requires": { + "ansi-regex": "^4.1.0" + } + }, + "strip-json-comments": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/strip-json-comments/-/strip-json-comments-2.0.1.tgz", + "integrity": "sha512-4gB8na07fecVVkOI6Rs4e7T6NOTki5EmL7TUduTs6bu3EdnSycntVJ4re8kgZA+wx9IueI2Y11bfbgwtzuE0KQ==", + "dev": true + }, + "supports-color": { + "version": "6.0.0", + "resolved": "https://registry.npmjs.org/supports-color/-/supports-color-6.0.0.tgz", + "integrity": "sha512-on9Kwidc1IUQo+bQdhi8+Tijpo0e1SS6RoGo2guUwn5vdaxw8RXOF9Vb2ws+ihWOmh4JnCJOvaziZWP1VABaLg==", + "dev": true, + "requires": { + "has-flag": "^3.0.0" + } + }, + "which": { + "version": "1.3.1", + "resolved": "https://registry.npmjs.org/which/-/which-1.3.1.tgz", + "integrity": "sha512-HxJdYWq1MTIQbJ3nw0cqssHoTNU267KlrDuGZ1WYlxDStUtKUhOaJmh112/TZmHxxUfuJqPXSOm7tDyas0OSIQ==", + "dev": true, + "requires": { + "isexe": "^2.0.0" + } + }, + "wrap-ansi": { + "version": "5.1.0", + "resolved": "https://registry.npmjs.org/wrap-ansi/-/wrap-ansi-5.1.0.tgz", + "integrity": "sha512-QC1/iN/2/RPVJ5jYK8BGttj5z83LmSKmvbvrXPNCLZSEb32KKVDJDl/MOt2N01qU2H/FkzEa9PKto1BqDjtd7Q==", + "dev": true, + "requires": { + "ansi-styles": "^3.2.0", + "string-width": "^3.0.0", + "strip-ansi": "^5.0.0" + } + }, + "y18n": { + "version": "4.0.3", + "resolved": "https://registry.npmjs.org/y18n/-/y18n-4.0.3.tgz", + "integrity": "sha512-JKhqTOwSrqNA1NY5lSztJ1GrBiUodLMmIZuLiDaMRJ+itFd+ABVE8XBjOvIWL+rSqNDC74LCSFmlb/U4UZ4hJQ==", + "dev": true + }, + "yargs": { + "version": "13.3.2", + "resolved": "https://registry.npmjs.org/yargs/-/yargs-13.3.2.tgz", + "integrity": "sha512-AX3Zw5iPruN5ie6xGRIDgqkT+ZhnRlZMLMHAs8tg7nRruy2Nb+i5o9bwghAogtM08q1dpr2LVoS8KSTMYpWXUw==", + "dev": true, + "requires": { + "cliui": "^5.0.0", + "find-up": "^3.0.0", + "get-caller-file": "^2.0.1", + "require-directory": "^2.1.1", + "require-main-filename": "^2.0.0", + "set-blocking": "^2.0.0", + "string-width": "^3.0.0", + "which-module": "^2.0.0", + "y18n": "^4.0.0", + "yargs-parser": "^13.1.2" + } + }, + "yargs-parser": { + "version": "13.1.2", + "resolved": "https://registry.npmjs.org/yargs-parser/-/yargs-parser-13.1.2.tgz", + "integrity": "sha512-3lbsNRf/j+A4QuSZfDRA7HRSfWrzO0YjqTJd5kjAq37Zep1CEgaYmrH9Q3GwPiB9cHyd1Y1UwggGhJGoxipbzg==", + "dev": true, + "requires": { + "camelcase": "^5.0.0", + "decamelize": "^1.2.0" + } + }, + "yargs-unparser": { + "version": "1.6.0", + "resolved": "https://registry.npmjs.org/yargs-unparser/-/yargs-unparser-1.6.0.tgz", + "integrity": "sha512-W9tKgmSn0DpSatfri0nx52Joq5hVXgeLiqR/5G0sZNDoLZFOr/xjBUDcShCOGNsBnEMNo1KAMBkTej1Hm62HTw==", + "dev": true, + "requires": { + "flat": "^4.1.0", + "lodash": "^4.17.15", + "yargs": "^13.3.0" + } + } + } + }, + "eth-lib": { + "version": "0.1.29", + "resolved": "https://registry.npmjs.org/eth-lib/-/eth-lib-0.1.29.tgz", + "integrity": "sha512-bfttrr3/7gG4E02HoWTDUcDDslN003OlOoBxk9virpAZQ1ja/jDgwkWB8QfJF7ojuEowrqy+lzp9VcJG7/k5bQ==", + "dev": true, + "requires": { + "bn.js": "^4.11.6", + "elliptic": "^6.4.0", + "nano-json-stream-parser": "^0.1.2", + "servify": "^0.1.12", + "ws": "^3.0.0", + "xhr-request-promise": "^0.1.2" + }, + "dependencies": { + "safe-buffer": { + "version": "5.1.2", + "resolved": "https://registry.npmjs.org/safe-buffer/-/safe-buffer-5.1.2.tgz", + "integrity": "sha512-Gd2UZBJDkXlY7GbJxfsE8/nvKkUEU1G38c1siN6QP6a9PT9MmHB8GnpscSmMJSoF8LOIrt8ud/wPtojys4G6+g==", + "dev": true + }, + "ws": { + "version": "3.3.3", + "resolved": "https://registry.npmjs.org/ws/-/ws-3.3.3.tgz", + "integrity": "sha512-nnWLa/NwZSt4KQJu51MYlCcSQ5g7INpOrOMt4XV8j4dqTXdmlUmSHQ8/oLC069ckre0fRsgfvsKwbTdtKLCDkA==", + "dev": true, + "requires": { + "async-limiter": "~1.0.0", + "safe-buffer": "~5.1.0", + "ultron": "~1.1.0" + } + } + } + }, + "eth-sig-util": { + "version": "3.0.1", + "resolved": "https://registry.npmjs.org/eth-sig-util/-/eth-sig-util-3.0.1.tgz", + "integrity": "sha512-0Us50HiGGvZgjtWTyAI/+qTzYPMLy5Q451D0Xy68bxq1QMWdoOddDwGvsqcFT27uohKgalM9z/yxplyt+mY2iQ==", + "dev": true, + "requires": { + "ethereumjs-abi": "^0.6.8", + "ethereumjs-util": "^5.1.1", + "tweetnacl": "^1.0.3", + "tweetnacl-util": "^0.15.0" + }, + "dependencies": { + "ethereumjs-util": { + "version": "5.2.1", + "resolved": "https://registry.npmjs.org/ethereumjs-util/-/ethereumjs-util-5.2.1.tgz", + "integrity": "sha512-v3kT+7zdyCm1HIqWlLNrHGqHGLpGYIhjeHxQjnDXjLT2FyGJDsd3LWMYUo7pAFRrk86CR3nUJfhC81CCoJNNGQ==", + "dev": true, + "requires": { + "bn.js": "^4.11.0", + "create-hash": "^1.1.2", + "elliptic": "^6.5.2", + "ethereum-cryptography": "^0.1.3", + "ethjs-util": "^0.1.3", + "rlp": "^2.0.0", + "safe-buffer": "^5.1.1" + } + } + } + }, + "ethereum-bloom-filters": { + "version": "1.0.10", + "resolved": "https://registry.npmjs.org/ethereum-bloom-filters/-/ethereum-bloom-filters-1.0.10.tgz", + "integrity": "sha512-rxJ5OFN3RwjQxDcFP2Z5+Q9ho4eIdEmSc2ht0fCu8Se9nbXjZ7/031uXoUYJ87KHCOdVeiUuwSnoS7hmYAGVHA==", + "dev": true, + "requires": { + "js-sha3": "^0.8.0" + } + }, + "ethereum-cryptography": { + "version": "0.1.3", + "resolved": "https://registry.npmjs.org/ethereum-cryptography/-/ethereum-cryptography-0.1.3.tgz", + "integrity": "sha512-w8/4x1SGGzc+tO97TASLja6SLd3fRIK2tLVcV2Gx4IB21hE19atll5Cq9o3d0ZmAYC/8aw0ipieTSiekAea4SQ==", + "dev": true, + "requires": { + "@types/pbkdf2": "^3.0.0", + "@types/secp256k1": "^4.0.1", + "blakejs": "^1.1.0", + "browserify-aes": "^1.2.0", + "bs58check": "^2.1.2", + "create-hash": "^1.2.0", + "create-hmac": "^1.1.7", + "hash.js": "^1.1.7", + "keccak": "^3.0.0", + "pbkdf2": "^3.0.17", + "randombytes": "^2.1.0", + "safe-buffer": "^5.1.2", + "scrypt-js": "^3.0.0", + "secp256k1": "^4.0.1", + "setimmediate": "^1.0.5" + } + }, + "ethereum-ens": { + "version": "0.8.0", + "resolved": "https://registry.npmjs.org/ethereum-ens/-/ethereum-ens-0.8.0.tgz", + "integrity": "sha512-a8cBTF4AWw1Q1Y37V1LSCS9pRY4Mh3f8vCg5cbXCCEJ3eno1hbI/+Ccv9SZLISYpqQhaglP3Bxb/34lS4Qf7Bg==", + "dev": true, + "requires": { + "bluebird": "^3.4.7", + "eth-ens-namehash": "^2.0.0", + "js-sha3": "^0.5.7", + "pako": "^1.0.4", + "underscore": "^1.8.3", + "web3": "^1.0.0-beta.34" + }, + "dependencies": { + "js-sha3": { + "version": "0.5.7", + "resolved": "https://registry.npmjs.org/js-sha3/-/js-sha3-0.5.7.tgz", + "integrity": "sha512-GII20kjaPX0zJ8wzkTbNDYMY7msuZcTWk8S5UOh6806Jq/wz1J8/bnr8uGU0DAUmYDjj2Mr4X1cW8v/GLYnR+g==", + "dev": true + } + } + }, + "ethereumjs-abi": { + "version": "0.6.8", + "resolved": "https://registry.npmjs.org/ethereumjs-abi/-/ethereumjs-abi-0.6.8.tgz", + "integrity": "sha512-Tx0r/iXI6r+lRsdvkFDlut0N08jWMnKRZ6Gkq+Nmw75lZe4e6o3EkSnkaBP5NF6+m5PTGAr9JP43N3LyeoglsA==", + "dev": true, + "requires": { + "bn.js": "^4.11.8", + "ethereumjs-util": "^6.0.0" + }, + "dependencies": { + "@types/bn.js": { + "version": "4.11.6", + "resolved": "https://registry.npmjs.org/@types/bn.js/-/bn.js-4.11.6.tgz", + "integrity": "sha512-pqr857jrp2kPuO9uRjZ3PwnJTjoQy+fcdxvBTvHm6dkmEL9q+hDD/2j/0ELOBPtPnS8LjCX0gI9nbl8lVkadpg==", + "dev": true, + "requires": { + "@types/node": "*" + } + }, + "ethereumjs-util": { + "version": "6.2.1", + "resolved": "https://registry.npmjs.org/ethereumjs-util/-/ethereumjs-util-6.2.1.tgz", + "integrity": "sha512-W2Ktez4L01Vexijrm5EB6w7dg4n/TgpoYU4avuT5T3Vmnw/eCRtiBrJfQYS/DCSvDIOLn2k57GcHdeBcgVxAqw==", + "dev": true, + "requires": { + "@types/bn.js": "^4.11.3", + "bn.js": "^4.11.0", + "create-hash": "^1.1.2", + "elliptic": "^6.5.2", + "ethereum-cryptography": "^0.1.3", + "ethjs-util": "0.1.6", + "rlp": "^2.2.3" + } + } + } + }, + "ethereumjs-util": { + "version": "7.1.5", + "resolved": "https://registry.npmjs.org/ethereumjs-util/-/ethereumjs-util-7.1.5.tgz", + "integrity": "sha512-SDl5kKrQAudFBUe5OJM9Ac6WmMyYmXX/6sTmLZ3ffG2eY6ZIGBes3pEDxNN6V72WyOw4CPD5RomKdsa8DAAwLg==", + "dev": true, + "requires": { + "@types/bn.js": "^5.1.0", + "bn.js": "^5.1.2", + "create-hash": "^1.1.2", + "ethereum-cryptography": "^0.1.3", + "rlp": "^2.2.4" + }, + "dependencies": { + "bn.js": { + "version": "5.2.1", + "resolved": "https://registry.npmjs.org/bn.js/-/bn.js-5.2.1.tgz", + "integrity": "sha512-eXRvHzWyYPBuB4NBy0cmYQjGitUrtqwbvlzP3G6VFnNRbsZQIxQ10PbKKHt8gZ/HW/D/747aDl+QkDqg3KQLMQ==", + "dev": true + } + } + }, + "ethereumjs-wallet": { + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/ethereumjs-wallet/-/ethereumjs-wallet-1.0.2.tgz", + "integrity": "sha512-CCWV4RESJgRdHIvFciVQFnCHfqyhXWchTPlkfp28Qc53ufs+doi5I/cV2+xeK9+qEo25XCWfP9MiL+WEPAZfdA==", + "dev": true, + "requires": { + "aes-js": "^3.1.2", + "bs58check": "^2.1.2", + "ethereum-cryptography": "^0.1.3", + "ethereumjs-util": "^7.1.2", + "randombytes": "^2.1.0", + "scrypt-js": "^3.0.1", + "utf8": "^3.0.0", + "uuid": "^8.3.2" + } + }, + "ethers": { + "version": "4.0.49", + "resolved": "https://registry.npmjs.org/ethers/-/ethers-4.0.49.tgz", + "integrity": "sha512-kPltTvWiyu+OktYy1IStSO16i2e7cS9D9OxZ81q2UUaiNPVrm/RTcbxamCXF9VUSKzJIdJV68EAIhTEVBalRWg==", + "dev": true, + "requires": { + "aes-js": "3.0.0", + "bn.js": "^4.11.9", + "elliptic": "6.5.4", + "hash.js": "1.1.3", + "js-sha3": "0.5.7", + "scrypt-js": "2.0.4", + "setimmediate": "1.0.4", + "uuid": "2.0.1", + "xmlhttprequest": "1.8.0" + }, + "dependencies": { + "aes-js": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/aes-js/-/aes-js-3.0.0.tgz", + "integrity": "sha512-H7wUZRn8WpTq9jocdxQ2c8x2sKo9ZVmzfRE13GiNJXfp7NcKYEdvl3vspKjXox6RIG2VtaRe4JFvxG4rqp2Zuw==", + "dev": true + }, + "hash.js": { + "version": "1.1.3", + "resolved": "https://registry.npmjs.org/hash.js/-/hash.js-1.1.3.tgz", + "integrity": "sha512-/UETyP0W22QILqS+6HowevwhEFJ3MBJnwTf75Qob9Wz9t0DPuisL8kW8YZMK62dHAKE1c1p+gY1TtOLY+USEHA==", + "dev": true, + "requires": { + "inherits": "^2.0.3", + "minimalistic-assert": "^1.0.0" + } + }, + "js-sha3": { + "version": "0.5.7", + "resolved": "https://registry.npmjs.org/js-sha3/-/js-sha3-0.5.7.tgz", + "integrity": "sha512-GII20kjaPX0zJ8wzkTbNDYMY7msuZcTWk8S5UOh6806Jq/wz1J8/bnr8uGU0DAUmYDjj2Mr4X1cW8v/GLYnR+g==", + "dev": true + }, + "scrypt-js": { + "version": "2.0.4", + "resolved": "https://registry.npmjs.org/scrypt-js/-/scrypt-js-2.0.4.tgz", + "integrity": "sha512-4KsaGcPnuhtCZQCxFxN3GVYIhKFPTdLd8PLC552XwbMndtD0cjRFAhDuuydXQ0h08ZfPgzqe6EKHozpuH74iDw==", + "dev": true + }, + "setimmediate": { + "version": "1.0.4", + "resolved": "https://registry.npmjs.org/setimmediate/-/setimmediate-1.0.4.tgz", + "integrity": "sha512-/TjEmXQVEzdod/FFskf3o7oOAsGhHf2j1dZqRFbDzq4F3mvvxflIIi4Hd3bLQE9y/CpwqfSQam5JakI/mi3Pog==", + "dev": true + }, + "uuid": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/uuid/-/uuid-2.0.1.tgz", + "integrity": "sha512-nWg9+Oa3qD2CQzHIP4qKUqwNfzKn8P0LtFhotaCTFchsV7ZfDhAybeip/HZVeMIpZi9JgY1E3nUlwaCmZT1sEg==", + "dev": true + } + } + }, + "ethjs-abi": { + "version": "0.2.1", + "resolved": "https://registry.npmjs.org/ethjs-abi/-/ethjs-abi-0.2.1.tgz", + "integrity": "sha512-g2AULSDYI6nEJyJaEVEXtTimRY2aPC2fi7ddSy0W+LXvEVL8Fe1y76o43ecbgdUKwZD+xsmEgX1yJr1Ia3r1IA==", + "dev": true, + "requires": { + "bn.js": "4.11.6", + "js-sha3": "0.5.5", + "number-to-bn": "1.7.0" + }, + "dependencies": { + "bn.js": { + "version": "4.11.6", + "resolved": "https://registry.npmjs.org/bn.js/-/bn.js-4.11.6.tgz", + "integrity": "sha512-XWwnNNFCuuSQ0m3r3C4LE3EiORltHd9M05pq6FOlVeiophzRbMo50Sbz1ehl8K3Z+jw9+vmgnXefY1hz8X+2wA==", + "dev": true + }, + "js-sha3": { + "version": "0.5.5", + "resolved": "https://registry.npmjs.org/js-sha3/-/js-sha3-0.5.5.tgz", + "integrity": "sha512-yLLwn44IVeunwjpDVTDZmQeVbB0h+dZpY2eO68B/Zik8hu6dH+rKeLxwua79GGIvW6xr8NBAcrtiUbYrTjEFTA==", + "dev": true + } + } + }, + "ethjs-unit": { + "version": "0.1.6", + "resolved": "https://registry.npmjs.org/ethjs-unit/-/ethjs-unit-0.1.6.tgz", + "integrity": "sha512-/Sn9Y0oKl0uqQuvgFk/zQgR7aw1g36qX/jzSQ5lSwlO0GigPymk4eGQfeNTD03w1dPOqfz8V77Cy43jH56pagw==", + "dev": true, + "requires": { + "bn.js": "4.11.6", + "number-to-bn": "1.7.0" + }, + "dependencies": { + "bn.js": { + "version": "4.11.6", + "resolved": "https://registry.npmjs.org/bn.js/-/bn.js-4.11.6.tgz", + "integrity": "sha512-XWwnNNFCuuSQ0m3r3C4LE3EiORltHd9M05pq6FOlVeiophzRbMo50Sbz1ehl8K3Z+jw9+vmgnXefY1hz8X+2wA==", + "dev": true + } + } + }, + "ethjs-util": { + "version": "0.1.6", + "resolved": "https://registry.npmjs.org/ethjs-util/-/ethjs-util-0.1.6.tgz", + "integrity": "sha512-CUnVOQq7gSpDHZVVrQW8ExxUETWrnrvXYvYz55wOU8Uj4VCgw56XC2B/fVqQN+f7gmrnRHSLVnFAwsCuNwji8w==", + "dev": true, + "requires": { + "is-hex-prefixed": "1.0.0", + "strip-hex-prefix": "1.0.0" + } + }, + "event-target-shim": { + "version": "5.0.1", + "resolved": "https://registry.npmjs.org/event-target-shim/-/event-target-shim-5.0.1.tgz", + "integrity": "sha512-i/2XbnSz/uxRCU6+NdVJgKWDTM427+MqYbkQzD321DuCQJUqOuJKIA0IM2+W2xtYHdKOmZ4dR6fExsd4SXL+WQ==", + "dev": true + }, + "eventemitter3": { + "version": "4.0.4", + "resolved": "https://registry.npmjs.org/eventemitter3/-/eventemitter3-4.0.4.tgz", + "integrity": "sha512-rlaVLnVxtxvoyLsQQFBx53YmXHDxRIzzTLbdfxqi4yocpSjAxXwkU0cScM5JgSKMqEhrZpnvQ2D9gjylR0AimQ==", + "dev": true + }, + "evp_bytestokey": { + "version": "1.0.3", + "resolved": "https://registry.npmjs.org/evp_bytestokey/-/evp_bytestokey-1.0.3.tgz", + "integrity": "sha512-/f2Go4TognH/KvCISP7OUsHn85hT9nUkxxA9BEWxFn+Oj9o8ZNLm/40hdlgSLyuOimsrTKLUMEorQexp/aPQeA==", + "dev": true, + "requires": { + "md5.js": "^1.3.4", + "safe-buffer": "^5.1.1" + } + }, + "express": { + "version": "4.18.2", + "resolved": "https://registry.npmjs.org/express/-/express-4.18.2.tgz", + "integrity": "sha512-5/PsL6iGPdfQ/lKM1UuielYgv3BUoJfz1aUwU9vHZ+J7gyvwdQXFEBIEIaxeGf0GIcreATNyBExtalisDbuMqQ==", + "dev": true, + "requires": { + "accepts": "~1.3.8", + "array-flatten": "1.1.1", + "body-parser": "1.20.1", + "content-disposition": "0.5.4", + "content-type": "~1.0.4", + "cookie": "0.5.0", + "cookie-signature": "1.0.6", + "debug": "2.6.9", + "depd": "2.0.0", + "encodeurl": "~1.0.2", + "escape-html": "~1.0.3", + "etag": "~1.8.1", + "finalhandler": "1.2.0", + "fresh": "0.5.2", + "http-errors": "2.0.0", + "merge-descriptors": "1.0.1", + "methods": "~1.1.2", + "on-finished": "2.4.1", + "parseurl": "~1.3.3", + "path-to-regexp": "0.1.7", + "proxy-addr": "~2.0.7", + "qs": "6.11.0", + "range-parser": "~1.2.1", + "safe-buffer": "5.2.1", + "send": "0.18.0", + "serve-static": "1.15.0", + "setprototypeof": "1.2.0", + "statuses": "2.0.1", + "type-is": "~1.6.18", + "utils-merge": "1.0.1", + "vary": "~1.1.2" + }, + "dependencies": { + "body-parser": { + "version": "1.20.1", + "resolved": "https://registry.npmjs.org/body-parser/-/body-parser-1.20.1.tgz", + "integrity": "sha512-jWi7abTbYwajOytWCQc37VulmWiRae5RyTpaCyDcS5/lMdtwSz5lOpDE67srw/HYe35f1z3fDQw+3txg7gNtWw==", + "dev": true, + "requires": { + "bytes": "3.1.2", + "content-type": "~1.0.4", + "debug": "2.6.9", + "depd": "2.0.0", + "destroy": "1.2.0", + "http-errors": "2.0.0", + "iconv-lite": "0.4.24", + "on-finished": "2.4.1", + "qs": "6.11.0", + "raw-body": "2.5.1", + "type-is": "~1.6.18", + "unpipe": "1.0.0" + } + }, + "cookie": { + "version": "0.5.0", + "resolved": "https://registry.npmjs.org/cookie/-/cookie-0.5.0.tgz", + "integrity": "sha512-YZ3GUyn/o8gfKJlnlX7g7xq4gyO6OSuhGPKaaGssGB2qgDUS0gPgtTvoyZLTt9Ab6dC4hfc9dV5arkvc/OCmrw==", + "dev": true + }, + "debug": { + "version": "2.6.9", + "resolved": "https://registry.npmjs.org/debug/-/debug-2.6.9.tgz", + "integrity": "sha512-bC7ElrdJaJnPbAP+1EotYvqZsb3ecl5wi6Bfi6BJTUcNowp6cvspg0jXznRTKDjm/E7AdgFBVeAPVMNcKGsHMA==", + "dev": true, + "requires": { + "ms": "2.0.0" + } + }, + "ms": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/ms/-/ms-2.0.0.tgz", + "integrity": "sha512-Tpp60P6IUJDTuOq/5Z8cdskzJujfwqfOTkrwIwj7IRISpnkJnT6SyJ4PCPnGMoFjC9ddhal5KVIYtAt97ix05A==", + "dev": true + }, + "qs": { + "version": "6.11.0", + "resolved": "https://registry.npmjs.org/qs/-/qs-6.11.0.tgz", + "integrity": "sha512-MvjoMCJwEarSbUYk5O+nmoSzSutSsTwF85zcHPQ9OrlFoZOYIjaqBAJIqIXjptyD5vThxGq52Xu/MaJzRkIk4Q==", + "dev": true, + "requires": { + "side-channel": "^1.0.4" + } + }, + "raw-body": { + "version": "2.5.1", + "resolved": "https://registry.npmjs.org/raw-body/-/raw-body-2.5.1.tgz", + "integrity": "sha512-qqJBtEyVgS0ZmPGdCFPWJ3FreoqvG4MVQln/kCgF7Olq95IbOp0/BWyMwbdtn4VTvkM8Y7khCQ2Xgk/tcrCXig==", + "dev": true, + "requires": { + "bytes": "3.1.2", + "http-errors": "2.0.0", + "iconv-lite": "0.4.24", + "unpipe": "1.0.0" + } + } + } + }, + "ext": { + "version": "1.7.0", + "resolved": "https://registry.npmjs.org/ext/-/ext-1.7.0.tgz", + "integrity": "sha512-6hxeJYaL110a9b5TEJSj0gojyHQAmA2ch5Os+ySCiA1QGdS697XWY1pzsrSjqA9LDEEgdB/KypIlR59RcLuHYw==", + "dev": true, + "requires": { + "type": "^2.7.2" + }, + "dependencies": { + "type": { + "version": "2.7.2", + "resolved": "https://registry.npmjs.org/type/-/type-2.7.2.tgz", + "integrity": "sha512-dzlvlNlt6AXU7EBSfpAscydQ7gXB+pPGsPnfJnZpiNJBDj7IaJzQlBZYGdEi4R9HmPdBv2XmWJ6YUtoTa7lmCw==", + "dev": true + } + } + }, + "extend": { + "version": "3.0.2", + "resolved": "https://registry.npmjs.org/extend/-/extend-3.0.2.tgz", + "integrity": "sha512-fjquC59cD7CyW6urNXK0FBufkZcoiGG80wTuPujX590cB5Ttln20E2UB4S/WARVqhXffZl2LNgS+gQdPIIim/g==", + "dev": true + }, + "extendable-error": { + "version": "0.1.7", + "resolved": "https://registry.npmjs.org/extendable-error/-/extendable-error-0.1.7.tgz", + "integrity": "sha512-UOiS2in6/Q0FK0R0q6UY9vYpQ21mr/Qn1KOnte7vsACuNJf514WvCCUHSRCPcgjPT2bAhNIJdlE6bVap1GKmeg==", + "dev": true + }, + "external-editor": { + "version": "3.1.0", + "resolved": "https://registry.npmjs.org/external-editor/-/external-editor-3.1.0.tgz", + "integrity": "sha512-hMQ4CX1p1izmuLYyZqLMO/qGNw10wSv9QDCPfzXfyFrOaCSSoRfqE1Kf1s5an66J5JZC62NewG+mK49jOCtQew==", + "dev": true, + "requires": { + "chardet": "^0.7.0", + "iconv-lite": "^0.4.24", + "tmp": "^0.0.33" + } + }, + "extsprintf": { + "version": "1.3.0", + "resolved": "https://registry.npmjs.org/extsprintf/-/extsprintf-1.3.0.tgz", + "integrity": "sha512-11Ndz7Nv+mvAC1j0ktTa7fAb0vLyGGX+rMHNBYQviQDGU0Hw7lhctJANqbPhu9nV9/izT/IntTgZ7Im/9LJs9g==", + "dev": true + }, + "fast-check": { + "version": "3.1.1", + "resolved": "https://registry.npmjs.org/fast-check/-/fast-check-3.1.1.tgz", + "integrity": "sha512-3vtXinVyuUKCKFKYcwXhGE6NtGWkqF8Yh3rvMZNzmwz8EPrgoc/v4pDdLHyLnCyCI5MZpZZkDEwFyXyEONOxpA==", + "dev": true, + "requires": { + "pure-rand": "^5.0.1" + } + }, + "fast-deep-equal": { + "version": "3.1.3", + "resolved": "https://registry.npmjs.org/fast-deep-equal/-/fast-deep-equal-3.1.3.tgz", + "integrity": "sha512-f3qQ9oQy9j2AhBe/H9VC91wLmKBCCU/gDOnKNAYG5hswO7BLKj09Hc5HYNz9cGI++xlpDCIgDaitVs03ATR84Q==", + "dev": true + }, + "fast-diff": { + "version": "1.3.0", + "resolved": "https://registry.npmjs.org/fast-diff/-/fast-diff-1.3.0.tgz", + "integrity": "sha512-VxPP4NqbUjj6MaAOafWeUn2cXWLcCtljklUtZf0Ind4XQ+QPtmA0b18zZy0jIQx+ExRVCR/ZQpBmik5lXshNsw==", + "dev": true + }, + "fast-glob": { + "version": "3.3.0", + "resolved": "https://registry.npmjs.org/fast-glob/-/fast-glob-3.3.0.tgz", + "integrity": "sha512-ChDuvbOypPuNjO8yIDf36x7BlZX1smcUMTTcyoIjycexOxd6DFsKsg21qVBzEmr3G7fUKIRy2/psii+CIUt7FA==", + "dev": true, + "requires": { + "@nodelib/fs.stat": "^2.0.2", + "@nodelib/fs.walk": "^1.2.3", + "glob-parent": "^5.1.2", + "merge2": "^1.3.0", + "micromatch": "^4.0.4" + } + }, + "fast-json-stable-stringify": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/fast-json-stable-stringify/-/fast-json-stable-stringify-2.1.0.tgz", + "integrity": "sha512-lhd/wF+Lk98HZoTCtlVraHtfh5XYijIjalXck7saUtuanSDyLMxnHhSXEDJqHxD7msR8D0uCmqlkwjCV8xvwHw==", + "dev": true + }, + "fast-levenshtein": { + "version": "2.0.6", + "resolved": "https://registry.npmjs.org/fast-levenshtein/-/fast-levenshtein-2.0.6.tgz", + "integrity": "sha512-DCXu6Ifhqcks7TZKY3Hxp3y6qphY5SJZmrWMDrKcERSOXWQdMhU9Ig/PYrzyw/ul9jOIyh0N4M0tbC5hodg8dw==", + "dev": true + }, + "fastq": { + "version": "1.15.0", + "resolved": "https://registry.npmjs.org/fastq/-/fastq-1.15.0.tgz", + "integrity": "sha512-wBrocU2LCXXa+lWBt8RoIRD89Fi8OdABODa/kEnyeyjS5aZO5/GNvI5sEINADqP/h8M29UHTHUb53sUu5Ihqdw==", + "dev": true, + "requires": { + "reusify": "^1.0.4" + } + }, + "file-entry-cache": { + "version": "6.0.1", + "resolved": "https://registry.npmjs.org/file-entry-cache/-/file-entry-cache-6.0.1.tgz", + "integrity": "sha512-7Gps/XWymbLk2QLYK4NzpMOrYjMhdIxXuIvy2QBsLE6ljuodKvdkWs/cpyJJ3CVIVpH0Oi1Hvg1ovbMzLdFBBg==", + "dev": true, + "requires": { + "flat-cache": "^3.0.4" + } + }, + "fill-range": { + "version": "7.0.1", + "resolved": "https://registry.npmjs.org/fill-range/-/fill-range-7.0.1.tgz", + "integrity": "sha512-qOo9F+dMUmC2Lcb4BbVvnKJxTPjCm+RRpe4gDuGrzkL7mEVl/djYSu2OdQ2Pa302N4oqkSg9ir6jaLWJ2USVpQ==", + "dev": true, + "requires": { + "to-regex-range": "^5.0.1" + } + }, + "finalhandler": { + "version": "1.2.0", + "resolved": "https://registry.npmjs.org/finalhandler/-/finalhandler-1.2.0.tgz", + "integrity": "sha512-5uXcUVftlQMFnWC9qu/svkWv3GTd2PfUhK/3PLkYNAe7FbqJMt3515HaxE6eRL74GdsriiwujiawdaB1BpEISg==", + "dev": true, + "requires": { + "debug": "2.6.9", + "encodeurl": "~1.0.2", + "escape-html": "~1.0.3", + "on-finished": "2.4.1", + "parseurl": "~1.3.3", + "statuses": "2.0.1", + "unpipe": "~1.0.0" + }, + "dependencies": { + "debug": { + "version": "2.6.9", + "resolved": "https://registry.npmjs.org/debug/-/debug-2.6.9.tgz", + "integrity": "sha512-bC7ElrdJaJnPbAP+1EotYvqZsb3ecl5wi6Bfi6BJTUcNowp6cvspg0jXznRTKDjm/E7AdgFBVeAPVMNcKGsHMA==", + "dev": true, + "requires": { + "ms": "2.0.0" + } + }, + "ms": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/ms/-/ms-2.0.0.tgz", + "integrity": "sha512-Tpp60P6IUJDTuOq/5Z8cdskzJujfwqfOTkrwIwj7IRISpnkJnT6SyJ4PCPnGMoFjC9ddhal5KVIYtAt97ix05A==", + "dev": true + } + } + }, + "find-up": { + "version": "4.1.0", + "resolved": "https://registry.npmjs.org/find-up/-/find-up-4.1.0.tgz", + "integrity": "sha512-PpOwAdQ/YlXQ2vj8a3h8IipDuYRi3wceVQQGYWxNINccq40Anw7BlsEXCMbt1Zt+OLA6Fq9suIpIWD0OsnISlw==", + "dev": true, + "requires": { + "locate-path": "^5.0.0", + "path-exists": "^4.0.0" + } + }, + "find-yarn-workspace-root2": { + "version": "1.2.16", + "resolved": "https://registry.npmjs.org/find-yarn-workspace-root2/-/find-yarn-workspace-root2-1.2.16.tgz", + "integrity": "sha512-hr6hb1w8ePMpPVUK39S4RlwJzi+xPLuVuG8XlwXU3KD5Yn3qgBWVfy3AzNlDhWvE1EORCE65/Qm26rFQt3VLVA==", + "dev": true, + "requires": { + "micromatch": "^4.0.2", + "pkg-dir": "^4.2.0" + } + }, + "flat": { + "version": "5.0.2", + "resolved": "https://registry.npmjs.org/flat/-/flat-5.0.2.tgz", + "integrity": "sha512-b6suED+5/3rTpUBdG1gupIl8MPFCAMA0QXwmljLhvCUKcUvdE4gWky9zpuGCcXHOsz4J9wPGNWq6OKpmIzz3hQ==", + "dev": true + }, + "flat-cache": { + "version": "3.0.4", + "resolved": "https://registry.npmjs.org/flat-cache/-/flat-cache-3.0.4.tgz", + "integrity": "sha512-dm9s5Pw7Jc0GvMYbshN6zchCA9RgQlzzEZX3vylR9IqFfS8XciblUXOKfW6SiuJ0e13eDYZoZV5wdrev7P3Nwg==", + "dev": true, + "requires": { + "flatted": "^3.1.0", + "rimraf": "^3.0.2" + } + }, + "flatted": { + "version": "3.2.7", + "resolved": "https://registry.npmjs.org/flatted/-/flatted-3.2.7.tgz", + "integrity": "sha512-5nqDSxl8nn5BSNxyR3n4I6eDmbolI6WT+QqR547RwxQapgjQBmtktdP+HTBb/a/zLsbzERTONyUB5pefh5TtjQ==", + "dev": true + }, + "follow-redirects": { + "version": "1.15.2", + "resolved": "https://registry.npmjs.org/follow-redirects/-/follow-redirects-1.15.2.tgz", + "integrity": "sha512-VQLG33o04KaQ8uYi2tVNbdrWp1QWxNNea+nmIB4EVM28v0hmP17z7aG1+wAkNzVq4KeXTq3221ye5qTJP91JwA==", + "dev": true + }, + "for-each": { + "version": "0.3.3", + "resolved": "https://registry.npmjs.org/for-each/-/for-each-0.3.3.tgz", + "integrity": "sha512-jqYfLp7mo9vIyQf8ykW2v7A+2N4QjeCeI5+Dz9XraiO1ign81wjiH7Fb9vSOWvQfNtmSa4H2RoQTrrXivdUZmw==", + "dev": true, + "requires": { + "is-callable": "^1.1.3" + } + }, + "forever-agent": { + "version": "0.6.1", + "resolved": "https://registry.npmjs.org/forever-agent/-/forever-agent-0.6.1.tgz", + "integrity": "sha512-j0KLYPhm6zeac4lz3oJ3o65qvgQCcPubiyotZrXqEaG4hNagNYO8qdlUrX5vwqv9ohqeT/Z3j6+yW067yWWdUw==", + "dev": true + }, + "form-data": { + "version": "2.3.3", + "resolved": "https://registry.npmjs.org/form-data/-/form-data-2.3.3.tgz", + "integrity": "sha512-1lLKB2Mu3aGP1Q/2eCOx0fNbRMe7XdwktwOruhfqqd0rIJWwN4Dh+E3hrPSlDCXnSR7UtZ1N38rVXm+6+MEhJQ==", + "dev": true, + "requires": { + "asynckit": "^0.4.0", + "combined-stream": "^1.0.6", + "mime-types": "^2.1.12" + } + }, + "form-data-encoder": { + "version": "1.7.1", + "resolved": "https://registry.npmjs.org/form-data-encoder/-/form-data-encoder-1.7.1.tgz", + "integrity": "sha512-EFRDrsMm/kyqbTQocNvRXMLjc7Es2Vk+IQFx/YW7hkUH1eBl4J1fqiP34l74Yt0pFLCNpc06fkbVk00008mzjg==", + "dev": true + }, + "forwarded": { + "version": "0.2.0", + "resolved": "https://registry.npmjs.org/forwarded/-/forwarded-0.2.0.tgz", + "integrity": "sha512-buRG0fpBtRHSTCOASe6hD258tEubFoRLb4ZNA6NxMVHNw2gOcwHo9wyablzMzOA5z9xA9L1KNjk/Nt6MT9aYow==", + "dev": true + }, + "fp-ts": { + "version": "1.19.3", + "resolved": "https://registry.npmjs.org/fp-ts/-/fp-ts-1.19.3.tgz", + "integrity": "sha512-H5KQDspykdHuztLTg+ajGN0Z2qUjcEf3Ybxc6hLt0k7/zPkn29XnKnxlBPyW2XIddWrGaJBzBl4VLYOtk39yZg==", + "dev": true + }, + "fresh": { + "version": "0.5.2", + "resolved": "https://registry.npmjs.org/fresh/-/fresh-0.5.2.tgz", + "integrity": "sha512-zJ2mQYM18rEFOudeV4GShTGIQ7RbzA7ozbU9I/XBpm7kqgMywgmylMwXHxZJmkVoYkna9d2pVXVXPdYTP9ej8Q==", + "dev": true + }, + "fs-extra": { + "version": "7.0.1", + "resolved": "https://registry.npmjs.org/fs-extra/-/fs-extra-7.0.1.tgz", + "integrity": "sha512-YJDaCJZEnBmcbw13fvdAM9AwNOJwOzrE4pqMqBq5nFiEqXUqHwlK4B+3pUw6JNvfSPtX05xFHtYy/1ni01eGCw==", + "dev": true, + "requires": { + "graceful-fs": "^4.1.2", + "jsonfile": "^4.0.0", + "universalify": "^0.1.0" + } + }, + "fs-minipass": { + "version": "1.2.7", + "resolved": "https://registry.npmjs.org/fs-minipass/-/fs-minipass-1.2.7.tgz", + "integrity": "sha512-GWSSJGFy4e9GUeCcbIkED+bgAoFyj7XF1mV8rma3QW4NIqX9Kyx79N/PF61H5udOV3aY1IaMLs6pGbH71nlCTA==", + "dev": true, + "requires": { + "minipass": "^2.6.0" + } + }, + "fs-readdir-recursive": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/fs-readdir-recursive/-/fs-readdir-recursive-1.1.0.tgz", + "integrity": "sha512-GNanXlVr2pf02+sPN40XN8HG+ePaNcvM0q5mZBd668Obwb0yD5GiUbZOFgwn8kGMY6I3mdyDJzieUy3PTYyTRA==", + "dev": true + }, + "fs.realpath": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/fs.realpath/-/fs.realpath-1.0.0.tgz", + "integrity": "sha512-OO0pH2lK6a0hZnAdau5ItzHPI6pUlvI7jMVnxUQRtw4owF2wk8lOSabtGDCTP4Ggrg2MbGnWO9X8K1t4+fGMDw==", + "dev": true + }, + "fsevents": { + "version": "2.3.2", + "resolved": "https://registry.npmjs.org/fsevents/-/fsevents-2.3.2.tgz", + "integrity": "sha512-xiqMQR4xAeHTuB9uWm+fFRcIOgKBMiOBP+eXiyT7jsgVCq1bkVygt00oASowB7EdtpOHaaPgKt812P9ab+DDKA==", + "dev": true, + "optional": true + }, + "function-bind": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/function-bind/-/function-bind-1.1.1.tgz", + "integrity": "sha512-yIovAzMX49sF8Yl58fSCWJ5svSLuaibPxXQJFLmBObTuCr0Mf1KiPopGM9NiFjiYBCbfaa2Fh6breQ6ANVTI0A==", + "dev": true + }, + "function.prototype.name": { + "version": "1.1.5", + "resolved": "https://registry.npmjs.org/function.prototype.name/-/function.prototype.name-1.1.5.tgz", + "integrity": "sha512-uN7m/BzVKQnCUF/iW8jYea67v++2u7m5UgENbHRtdDVclOUP+FMPlCNdmk0h/ysGyo2tavMJEDqJAkJdRa1vMA==", + "dev": true, + "requires": { + "call-bind": "^1.0.2", + "define-properties": "^1.1.3", + "es-abstract": "^1.19.0", + "functions-have-names": "^1.2.2" + } + }, + "functional-red-black-tree": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/functional-red-black-tree/-/functional-red-black-tree-1.0.1.tgz", + "integrity": "sha512-dsKNQNdj6xA3T+QlADDA7mOSlX0qiMINjn0cgr+eGHGsbSHzTabcIogz2+p/iqP1Xs6EP/sS2SbqH+brGTbq0g==", + "dev": true + }, + "functions-have-names": { + "version": "1.2.3", + "resolved": "https://registry.npmjs.org/functions-have-names/-/functions-have-names-1.2.3.tgz", + "integrity": "sha512-xckBUXyTIqT97tq2x2AMb+g163b5JFysYk0x4qxNFwbfQkmNZoiRHb6sPzI9/QV33WeuvVYBUIiD4NzNIyqaRQ==", + "dev": true + }, + "get-caller-file": { + "version": "2.0.5", + "resolved": "https://registry.npmjs.org/get-caller-file/-/get-caller-file-2.0.5.tgz", + "integrity": "sha512-DyFP3BM/3YHTQOCUL/w0OZHR0lpKeGrxotcHWcqNEdnltqFwXVfhEBQ94eIo34AfQpo0rGki4cyIiftY06h2Fg==", + "dev": true + }, + "get-func-name": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/get-func-name/-/get-func-name-2.0.0.tgz", + "integrity": "sha512-Hm0ixYtaSZ/V7C8FJrtZIuBBI+iSgL+1Aq82zSu8VQNB4S3Gk8e7Qs3VwBDJAhmRZcFqkl3tQu36g/Foh5I5ig==", + "dev": true + }, + "get-intrinsic": { + "version": "1.2.1", + "resolved": "https://registry.npmjs.org/get-intrinsic/-/get-intrinsic-1.2.1.tgz", + "integrity": "sha512-2DcsyfABl+gVHEfCOaTrWgyt+tb6MSEGmKq+kI5HwLbIYgjgmMcV8KQ41uaKz1xxUcn9tJtgFbQUEVcEbd0FYw==", + "dev": true, + "requires": { + "function-bind": "^1.1.1", + "has": "^1.0.3", + "has-proto": "^1.0.1", + "has-symbols": "^1.0.3" + } + }, + "get-port": { + "version": "3.2.0", + "resolved": "https://registry.npmjs.org/get-port/-/get-port-3.2.0.tgz", + "integrity": "sha512-x5UJKlgeUiNT8nyo/AcnwLnZuZNcSjSw0kogRB+Whd1fjjFq4B1hySFxSFWWSn4mIBzg3sRNUDFYc4g5gjPoLg==", + "dev": true + }, + "get-stream": { + "version": "6.0.1", + "resolved": "https://registry.npmjs.org/get-stream/-/get-stream-6.0.1.tgz", + "integrity": "sha512-ts6Wi+2j3jQjqi70w5AlN8DFnkSwC+MqmxEzdEALB2qXZYV3X/b1CTfgPLGJNMeAWxdPfU8FO1ms3NUfaHCPYg==", + "dev": true + }, + "get-symbol-description": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/get-symbol-description/-/get-symbol-description-1.0.0.tgz", + "integrity": "sha512-2EmdH1YvIQiZpltCNgkuiUnyukzxM/R6NDJX31Ke3BG1Nq5b0S2PhX59UKi9vZpPDQVdqn+1IcaAwnzTT5vCjw==", + "dev": true, + "requires": { + "call-bind": "^1.0.2", + "get-intrinsic": "^1.1.1" + } + }, + "getpass": { + "version": "0.1.7", + "resolved": "https://registry.npmjs.org/getpass/-/getpass-0.1.7.tgz", + "integrity": "sha512-0fzj9JxOLfJ+XGLhR8ze3unN0KZCgZwiSSDz168VERjK8Wl8kVSdcu2kspd4s4wtAa1y/qrVRiAA0WclVsu0ng==", + "dev": true, + "requires": { + "assert-plus": "^1.0.0" + } + }, + "ghost-testrpc": { + "version": "0.0.2", + "resolved": "https://registry.npmjs.org/ghost-testrpc/-/ghost-testrpc-0.0.2.tgz", + "integrity": "sha512-i08dAEgJ2g8z5buJIrCTduwPIhih3DP+hOCTyyryikfV8T0bNvHnGXO67i0DD1H4GBDETTclPy9njZbfluQYrQ==", + "dev": true, + "requires": { + "chalk": "^2.4.2", + "node-emoji": "^1.10.0" + } + }, + "glob": { + "version": "8.1.0", + "resolved": "https://registry.npmjs.org/glob/-/glob-8.1.0.tgz", + "integrity": "sha512-r8hpEjiQEYlF2QU0df3dS+nxxSIreXQS1qRhMJM0Q5NDdR386C7jb7Hwwod8Fgiuex+k0GFjgft18yvxm5XoCQ==", + "dev": true, + "requires": { + "fs.realpath": "^1.0.0", + "inflight": "^1.0.4", + "inherits": "2", + "minimatch": "^5.0.1", + "once": "^1.3.0" + }, + "dependencies": { + "brace-expansion": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-2.0.1.tgz", + "integrity": "sha512-XnAIvQ8eM+kC6aULx6wuQiwVsnzsi9d3WxzV3FpWTGA19F621kwdbsAcFKXgKUHZWsy+mY6iL1sHTxWEFCytDA==", + "dev": true, + "requires": { + "balanced-match": "^1.0.0" + } + }, + "minimatch": { + "version": "5.1.6", + "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-5.1.6.tgz", + "integrity": "sha512-lKwV/1brpG6mBUFHtb7NUmtABCb2WZZmm2wNiOA5hAb8VdCS4B3dtMWyvcoViccwAW/COERjXLt0zP1zXUN26g==", + "dev": true, + "requires": { + "brace-expansion": "^2.0.1" + } + } + } + }, + "glob-parent": { + "version": "5.1.2", + "resolved": "https://registry.npmjs.org/glob-parent/-/glob-parent-5.1.2.tgz", + "integrity": "sha512-AOIgSQCepiJYwP3ARnGx+5VnTu2HBYdzbGP45eLw1vr3zB3vZLeyed1sC9hnbcOc9/SrMyM5RPQrkGz4aS9Zow==", + "dev": true, + "requires": { + "is-glob": "^4.0.1" + } + }, + "global": { + "version": "4.4.0", + "resolved": "https://registry.npmjs.org/global/-/global-4.4.0.tgz", + "integrity": "sha512-wv/LAoHdRE3BeTGz53FAamhGlPLhlssK45usmGFThIi4XqnBmjKQ16u+RNbP7WvigRZDxUsM0J3gcQ5yicaL0w==", + "dev": true, + "requires": { + "min-document": "^2.19.0", + "process": "^0.11.10" + } + }, + "global-modules": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/global-modules/-/global-modules-2.0.0.tgz", + "integrity": "sha512-NGbfmJBp9x8IxyJSd1P+otYK8vonoJactOogrVfFRIAEY1ukil8RSKDz2Yo7wh1oihl51l/r6W4epkeKJHqL8A==", + "dev": true, + "requires": { + "global-prefix": "^3.0.0" + } + }, + "global-prefix": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/global-prefix/-/global-prefix-3.0.0.tgz", + "integrity": "sha512-awConJSVCHVGND6x3tmMaKcQvwXLhjdkmomy2W+Goaui8YPgYgXJZewhg3fWC+DlfqqQuWg8AwqjGTD2nAPVWg==", + "dev": true, + "requires": { + "ini": "^1.3.5", + "kind-of": "^6.0.2", + "which": "^1.3.1" + }, + "dependencies": { + "which": { + "version": "1.3.1", + "resolved": "https://registry.npmjs.org/which/-/which-1.3.1.tgz", + "integrity": "sha512-HxJdYWq1MTIQbJ3nw0cqssHoTNU267KlrDuGZ1WYlxDStUtKUhOaJmh112/TZmHxxUfuJqPXSOm7tDyas0OSIQ==", + "dev": true, + "requires": { + "isexe": "^2.0.0" + } + } + } + }, + "globals": { + "version": "13.20.0", + "resolved": "https://registry.npmjs.org/globals/-/globals-13.20.0.tgz", + "integrity": "sha512-Qg5QtVkCy/kv3FUSlu4ukeZDVf9ee0iXLAUYX13gbR17bnejFTzr4iS9bY7kwCf1NztRNm1t91fjOiyx4CSwPQ==", + "dev": true, + "requires": { + "type-fest": "^0.20.2" + } + }, + "globalthis": { + "version": "1.0.3", + "resolved": "https://registry.npmjs.org/globalthis/-/globalthis-1.0.3.tgz", + "integrity": "sha512-sFdI5LyBiNTHjRd7cGPWapiHWMOXKyuBNX/cWJ3NfzrZQVa8GI/8cofCl74AOVqq9W5kNmguTIzJ/1s2gyI9wA==", + "dev": true, + "requires": { + "define-properties": "^1.1.3" + } + }, + "globby": { + "version": "11.1.0", + "resolved": "https://registry.npmjs.org/globby/-/globby-11.1.0.tgz", + "integrity": "sha512-jhIXaOzy1sb8IyocaruWSn1TjmnBVs8Ayhcy83rmxNJ8q2uWKCAj3CnJY+KpGSXCueAPc0i05kVvVKtP1t9S3g==", + "dev": true, + "requires": { + "array-union": "^2.1.0", + "dir-glob": "^3.0.1", + "fast-glob": "^3.2.9", + "ignore": "^5.2.0", + "merge2": "^1.4.1", + "slash": "^3.0.0" + } + }, + "gopd": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/gopd/-/gopd-1.0.1.tgz", + "integrity": "sha512-d65bNlIadxvpb/A2abVdlqKqV563juRnZ1Wtk6s1sIR8uNsXR70xqIzVqxVf1eTqDunwT2MkczEeaezCKTZhwA==", + "dev": true, + "requires": { + "get-intrinsic": "^1.1.3" + } + }, + "got": { + "version": "12.1.0", + "resolved": "https://registry.npmjs.org/got/-/got-12.1.0.tgz", + "integrity": "sha512-hBv2ty9QN2RdbJJMK3hesmSkFTjVIHyIDDbssCKnSmq62edGgImJWD10Eb1k77TiV1bxloxqcFAVK8+9pkhOig==", + "dev": true, + "requires": { + "@sindresorhus/is": "^4.6.0", + "@szmarczak/http-timer": "^5.0.1", + "@types/cacheable-request": "^6.0.2", + "@types/responselike": "^1.0.0", + "cacheable-lookup": "^6.0.4", + "cacheable-request": "^7.0.2", + "decompress-response": "^6.0.0", + "form-data-encoder": "1.7.1", + "get-stream": "^6.0.1", + "http2-wrapper": "^2.1.10", + "lowercase-keys": "^3.0.0", + "p-cancelable": "^3.0.0", + "responselike": "^2.0.0" + } + }, + "graceful-fs": { + "version": "4.2.11", + "resolved": "https://registry.npmjs.org/graceful-fs/-/graceful-fs-4.2.11.tgz", + "integrity": "sha512-RbJ5/jmFcNNCcDV5o9eTnBLJ/HszWV0P73bc+Ff4nS/rJj+YaS6IGyiOL0VoBYX+l1Wrl3k63h/KrH+nhJ0XvQ==", + "dev": true + }, + "grapheme-splitter": { + "version": "1.0.4", + "resolved": "https://registry.npmjs.org/grapheme-splitter/-/grapheme-splitter-1.0.4.tgz", + "integrity": "sha512-bzh50DW9kTPM00T8y4o8vQg89Di9oLJVLW/KaOGIXJWP/iqCN6WKYkbNOF04vFLJhwcpYUh9ydh/+5vpOqV4YQ==", + "dev": true + }, + "graphemer": { + "version": "1.4.0", + "resolved": "https://registry.npmjs.org/graphemer/-/graphemer-1.4.0.tgz", + "integrity": "sha512-EtKwoO6kxCL9WO5xipiHTZlSzBm7WLT627TqC/uVRd0HKmq8NXyebnNYxDoBi7wt8eTWrUrKXCOVaFq9x1kgag==", + "dev": true + }, + "graphlib": { + "version": "2.1.8", + "resolved": "https://registry.npmjs.org/graphlib/-/graphlib-2.1.8.tgz", + "integrity": "sha512-jcLLfkpoVGmH7/InMC/1hIvOPSUh38oJtGhvrOFGzioE1DZ+0YW16RgmOJhHiuWTvGiJQ9Z1Ik43JvkRPRvE+A==", + "dev": true, + "requires": { + "lodash": "^4.17.15" + } + }, + "growl": { + "version": "1.10.5", + "resolved": "https://registry.npmjs.org/growl/-/growl-1.10.5.tgz", + "integrity": "sha512-qBr4OuELkhPenW6goKVXiv47US3clb3/IbuWF9KNKEijAy9oeHxU9IgzjvJhHkUzhaj7rOUD7+YGWqUjLp5oSA==", + "dev": true + }, + "handlebars": { + "version": "4.7.7", + "resolved": "https://registry.npmjs.org/handlebars/-/handlebars-4.7.7.tgz", + "integrity": "sha512-aAcXm5OAfE/8IXkcZvCepKU3VzW1/39Fb5ZuqMtgI/hT8X2YgoMvBY5dLhq/cpOvw7Lk1nK/UF71aLG/ZnVYRA==", + "dev": true, + "requires": { + "minimist": "^1.2.5", + "neo-async": "^2.6.0", + "source-map": "^0.6.1", + "uglify-js": "^3.1.4", + "wordwrap": "^1.0.0" + }, + "dependencies": { + "source-map": { + "version": "0.6.1", + "resolved": "https://registry.npmjs.org/source-map/-/source-map-0.6.1.tgz", + "integrity": "sha512-UjgapumWlbMhkBgzT7Ykc5YXUT46F0iKu8SGXq0bcwP5dz/h0Plj6enJqjz1Zbq2l5WaqYnrVbwWOWMyF3F47g==", + "dev": true + } + } + }, + "har-schema": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/har-schema/-/har-schema-2.0.0.tgz", + "integrity": "sha512-Oqluz6zhGX8cyRaTQlFMPw80bSJVG2x/cFb8ZPhUILGgHka9SsokCCOQgpveePerqidZOrT14ipqfJb7ILcW5Q==", + "dev": true + }, + "har-validator": { + "version": "5.1.5", + "resolved": "https://registry.npmjs.org/har-validator/-/har-validator-5.1.5.tgz", + "integrity": "sha512-nmT2T0lljbxdQZfspsno9hgrG3Uir6Ks5afism62poxqBM6sDnMEuPmzTq8XN0OEwqKLLdh1jQI3qyE66Nzb3w==", + "dev": true, + "requires": { + "ajv": "^6.12.3", + "har-schema": "^2.0.0" + } + }, + "hard-rejection": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/hard-rejection/-/hard-rejection-2.1.0.tgz", + "integrity": "sha512-VIZB+ibDhx7ObhAe7OVtoEbuP4h/MuOTHJ+J8h/eBXotJYl0fBgR72xDFCKgIh22OJZIOVNxBMWuhAr10r8HdA==", + "dev": true + }, + "hardhat": { + "version": "2.16.1", + "resolved": "https://registry.npmjs.org/hardhat/-/hardhat-2.16.1.tgz", + "integrity": "sha512-QpBjGXFhhSYoYBGEHyoau/A63crZOP+i3GbNxzLGkL6IklzT+piN14+wGnINNCg5BLSKisQI/RAySPzaWRcx/g==", + "dev": true, + "requires": { + "@ethersproject/abi": "^5.1.2", + "@metamask/eth-sig-util": "^4.0.0", + "@nomicfoundation/ethereumjs-block": "5.0.1", + "@nomicfoundation/ethereumjs-blockchain": "7.0.1", + "@nomicfoundation/ethereumjs-common": "4.0.1", + "@nomicfoundation/ethereumjs-evm": "2.0.1", + "@nomicfoundation/ethereumjs-rlp": "5.0.1", + "@nomicfoundation/ethereumjs-statemanager": "2.0.1", + "@nomicfoundation/ethereumjs-trie": "6.0.1", + "@nomicfoundation/ethereumjs-tx": "5.0.1", + "@nomicfoundation/ethereumjs-util": "9.0.1", + "@nomicfoundation/ethereumjs-vm": "7.0.1", + "@nomicfoundation/solidity-analyzer": "^0.1.0", + "@sentry/node": "^5.18.1", + "@types/bn.js": "^5.1.0", + "@types/lru-cache": "^5.1.0", + "abort-controller": "^3.0.0", + "adm-zip": "^0.4.16", + "aggregate-error": "^3.0.0", + "ansi-escapes": "^4.3.0", + "chalk": "^2.4.2", + "chokidar": "^3.4.0", + "ci-info": "^2.0.0", + "debug": "^4.1.1", + "enquirer": "^2.3.0", + "env-paths": "^2.2.0", + "ethereum-cryptography": "^1.0.3", + "ethereumjs-abi": "^0.6.8", + "find-up": "^2.1.0", + "fp-ts": "1.19.3", + "fs-extra": "^7.0.1", + "glob": "7.2.0", + "immutable": "^4.0.0-rc.12", + "io-ts": "1.10.4", + "keccak": "^3.0.2", + "lodash": "^4.17.11", + "mnemonist": "^0.38.0", + "mocha": "^10.0.0", + "p-map": "^4.0.0", + "raw-body": "^2.4.1", + "resolve": "1.17.0", + "semver": "^6.3.0", + "solc": "0.7.3", + "source-map-support": "^0.5.13", + "stacktrace-parser": "^0.1.10", + "tsort": "0.0.1", + "undici": "^5.14.0", + "uuid": "^8.3.2", + "ws": "^7.4.6" + }, + "dependencies": { + "ci-info": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/ci-info/-/ci-info-2.0.0.tgz", + "integrity": "sha512-5tK7EtrZ0N+OLFMthtqOj4fI2Jeb88C4CAZPu25LDVUgXJ0A3Js4PMGqrn0JU1W0Mh1/Z8wZzYPxqUrXeBboCQ==", + "dev": true + }, + "commander": { + "version": "3.0.2", + "resolved": "https://registry.npmjs.org/commander/-/commander-3.0.2.tgz", + "integrity": "sha512-Gar0ASD4BDyKC4hl4DwHqDrmvjoxWKZigVnAbn5H1owvm4CxCPdb0HQDehwNYMJpla5+M2tPmPARzhtYuwpHow==", + "dev": true + }, + "ethereum-cryptography": { + "version": "1.2.0", + "resolved": "https://registry.npmjs.org/ethereum-cryptography/-/ethereum-cryptography-1.2.0.tgz", + "integrity": "sha512-6yFQC9b5ug6/17CQpCyE3k9eKBMdhyVjzUy1WkiuY/E4vj/SXDBbCw8QEIaXqf0Mf2SnY6RmpDcwlUmBSS0EJw==", + "dev": true, + "requires": { + "@noble/hashes": "1.2.0", + "@noble/secp256k1": "1.7.1", + "@scure/bip32": "1.1.5", + "@scure/bip39": "1.1.1" + } + }, + "find-up": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/find-up/-/find-up-2.1.0.tgz", + "integrity": "sha512-NWzkk0jSJtTt08+FBFMvXoeZnOJD+jTtsRmBYbAIzJdX6l7dLgR7CTubCM5/eDdPUBvLCeVasP1brfVR/9/EZQ==", + "dev": true, + "requires": { + "locate-path": "^2.0.0" + } + }, + "glob": { + "version": "7.2.0", + "resolved": "https://registry.npmjs.org/glob/-/glob-7.2.0.tgz", + "integrity": "sha512-lmLf6gtyrPq8tTjSmrO94wBeQbFR3HbLHbuyD69wuyQkImp2hWqMGB47OX65FBkPffO641IP9jWa1z4ivqG26Q==", + "dev": true, + "requires": { + "fs.realpath": "^1.0.0", + "inflight": "^1.0.4", + "inherits": "2", + "minimatch": "^3.0.4", + "once": "^1.3.0", + "path-is-absolute": "^1.0.0" + } + }, + "jsonfile": { + "version": "2.4.0", + "resolved": "https://registry.npmjs.org/jsonfile/-/jsonfile-2.4.0.tgz", + "integrity": "sha512-PKllAqbgLgxHaj8TElYymKCAgrASebJrWpTnEkOaTowt23VKXXN0sUeriJ+eh7y6ufb/CC5ap11pz71/cM0hUw==", + "dev": true, + "requires": { + "graceful-fs": "^4.1.6" + } + }, + "locate-path": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/locate-path/-/locate-path-2.0.0.tgz", + "integrity": "sha512-NCI2kiDkyR7VeEKm27Kda/iQHyKJe1Bu0FlTbYp3CqJu+9IFe9bLyAjMxf5ZDDbEg+iMPzB5zYyUTSm8wVTKmA==", + "dev": true, + "requires": { + "p-locate": "^2.0.0", + "path-exists": "^3.0.0" + } + }, + "p-limit": { + "version": "1.3.0", + "resolved": "https://registry.npmjs.org/p-limit/-/p-limit-1.3.0.tgz", + "integrity": "sha512-vvcXsLAJ9Dr5rQOPk7toZQZJApBl2K4J6dANSsEuh6QI41JYcsS/qhTGa9ErIUUgK3WNQoJYvylxvjqmiqEA9Q==", + "dev": true, + "requires": { + "p-try": "^1.0.0" + } + }, + "p-locate": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/p-locate/-/p-locate-2.0.0.tgz", + "integrity": "sha512-nQja7m7gSKuewoVRen45CtVfODR3crN3goVQ0DDZ9N3yHxgpkuBhZqsaiotSQRrADUrne346peY7kT3TSACykg==", + "dev": true, + "requires": { + "p-limit": "^1.1.0" + } + }, + "p-try": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/p-try/-/p-try-1.0.0.tgz", + "integrity": "sha512-U1etNYuMJoIz3ZXSrrySFjsXQTWOx2/jdi86L+2pRvph/qMKL6sbcCYdH23fqsbm8TH2Gn0OybpT4eSFlCVHww==", + "dev": true + }, + "path-exists": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/path-exists/-/path-exists-3.0.0.tgz", + "integrity": "sha512-bpC7GYwiDYQ4wYLe+FA8lhRjhQCMcQGuSgGGqDkg/QerRWw9CmGRT0iSOVRSZJ29NMLZgIzqaljJ63oaL4NIJQ==", + "dev": true + }, + "require-from-string": { + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/require-from-string/-/require-from-string-2.0.2.tgz", + "integrity": "sha512-Xf0nWe6RseziFMu+Ap9biiUbmplq6S9/p+7w7YXP/JBHhrUDDUhwa+vANyubuqfZWTveU//DYVGsDG7RKL/vEw==", + "dev": true + }, + "rimraf": { + "version": "2.7.1", + "resolved": "https://registry.npmjs.org/rimraf/-/rimraf-2.7.1.tgz", + "integrity": "sha512-uWjbaKIK3T1OSVptzX7Nl6PvQ3qAGtKEtVRjRuazjfL3Bx5eI409VZSqgND+4UNnmzLVdPj9FqFJNPqBZFve4w==", + "dev": true, + "requires": { + "glob": "^7.1.3" + } + }, + "semver": { + "version": "6.3.0", + "resolved": "https://registry.npmjs.org/semver/-/semver-6.3.0.tgz", + "integrity": "sha512-b39TBaTSfV6yBrapU89p5fKekE2m/NwnDocOVruQFS1/veMgdzuPcnOM34M6CwxW8jH/lxEa5rBoDeUwu5HHTw==", + "dev": true + }, + "solc": { + "version": "0.7.3", + "resolved": "https://registry.npmjs.org/solc/-/solc-0.7.3.tgz", + "integrity": "sha512-GAsWNAjGzIDg7VxzP6mPjdurby3IkGCjQcM8GFYZT6RyaoUZKmMU6Y7YwG+tFGhv7dwZ8rmR4iwFDrrD99JwqA==", + "dev": true, + "requires": { + "command-exists": "^1.2.8", + "commander": "3.0.2", + "follow-redirects": "^1.12.1", + "fs-extra": "^0.30.0", + "js-sha3": "0.8.0", + "memorystream": "^0.3.1", + "require-from-string": "^2.0.0", + "semver": "^5.5.0", + "tmp": "0.0.33" + }, + "dependencies": { + "fs-extra": { + "version": "0.30.0", + "resolved": "https://registry.npmjs.org/fs-extra/-/fs-extra-0.30.0.tgz", + "integrity": "sha512-UvSPKyhMn6LEd/WpUaV9C9t3zATuqoqfWc3QdPhPLb58prN9tqYPlPWi8Krxi44loBoUzlobqZ3+8tGpxxSzwA==", + "dev": true, + "requires": { + "graceful-fs": "^4.1.2", + "jsonfile": "^2.1.0", + "klaw": "^1.0.0", + "path-is-absolute": "^1.0.0", + "rimraf": "^2.2.8" + } + }, + "semver": { + "version": "5.7.1", + "resolved": "https://registry.npmjs.org/semver/-/semver-5.7.1.tgz", + "integrity": "sha512-sauaDf/PZdVgrLTNYHRtpXa1iRiKcaebiKQ1BJdpQlWH2lCvexQdX55snPFyK7QzpudqbCI0qXFfOasHdyNDGQ==", + "dev": true + } + } + } + } + }, + "hardhat-exposed": { + "version": "0.3.11", + "resolved": "https://registry.npmjs.org/hardhat-exposed/-/hardhat-exposed-0.3.11.tgz", + "integrity": "sha512-2Gwdfx1YpSWUX80kuq0zM1tNqDJoTBCd5Q5oXKPxz6STSy1TiDyDb1miUr4Dwc/Dp2lzWzM+fZjpUrMe5O08Hw==", + "dev": true, + "requires": { + "micromatch": "^4.0.4", + "solidity-ast": "^0.4.25" + } + }, + "hardhat-gas-reporter": { + "version": "1.0.9", + "resolved": "https://registry.npmjs.org/hardhat-gas-reporter/-/hardhat-gas-reporter-1.0.9.tgz", + "integrity": "sha512-INN26G3EW43adGKBNzYWOlI3+rlLnasXTwW79YNnUhXPDa+yHESgt639dJEs37gCjhkbNKcRRJnomXEuMFBXJg==", + "dev": true, + "requires": { + "array-uniq": "1.0.3", + "eth-gas-reporter": "^0.2.25", + "sha1": "^1.1.1" + } + }, + "hardhat-ignore-warnings": { + "version": "0.2.9", + "resolved": "https://registry.npmjs.org/hardhat-ignore-warnings/-/hardhat-ignore-warnings-0.2.9.tgz", + "integrity": "sha512-q1oj6/ixiAx+lgIyGLBajVCSC7qUtAoK7LS9Nr8UVHYo8Iuh5naBiVGo4RDJ6wxbDGYBkeSukUGZrMqzC2DWwA==", + "dev": true, + "requires": { + "minimatch": "^5.1.0", + "node-interval-tree": "^2.0.1", + "solidity-comments": "^0.0.2" + }, + "dependencies": { + "brace-expansion": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-2.0.1.tgz", + "integrity": "sha512-XnAIvQ8eM+kC6aULx6wuQiwVsnzsi9d3WxzV3FpWTGA19F621kwdbsAcFKXgKUHZWsy+mY6iL1sHTxWEFCytDA==", + "dev": true, + "requires": { + "balanced-match": "^1.0.0" + } + }, + "minimatch": { + "version": "5.1.6", + "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-5.1.6.tgz", + "integrity": "sha512-lKwV/1brpG6mBUFHtb7NUmtABCb2WZZmm2wNiOA5hAb8VdCS4B3dtMWyvcoViccwAW/COERjXLt0zP1zXUN26g==", + "dev": true, + "requires": { + "brace-expansion": "^2.0.1" + } + } + } + }, + "has": { + "version": "1.0.3", + "resolved": "https://registry.npmjs.org/has/-/has-1.0.3.tgz", + "integrity": "sha512-f2dvO0VU6Oej7RkWJGrehjbzMAjFp5/VKPp5tTpWIV4JHHZK1/BxbFRtf/siA2SWTe09caDmVtYYzWEIbBS4zw==", + "dev": true, + "requires": { + "function-bind": "^1.1.1" + } + }, + "has-bigints": { + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/has-bigints/-/has-bigints-1.0.2.tgz", + "integrity": "sha512-tSvCKtBr9lkF0Ex0aQiP9N+OpV4zi2r/Nee5VkRDbaqv35RLYMzbwQfFSZZH0kR+Rd6302UJZ2p/bJCEoR3VoQ==", + "dev": true + }, + "has-flag": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/has-flag/-/has-flag-3.0.0.tgz", + "integrity": "sha512-sKJf1+ceQBr4SMkvQnBDNDtf4TXpVhVGateu0t918bl30FnbE2m4vNLX+VWe/dpjlb+HugGYzW7uQXH98HPEYw==", + "dev": true + }, + "has-property-descriptors": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/has-property-descriptors/-/has-property-descriptors-1.0.0.tgz", + "integrity": "sha512-62DVLZGoiEBDHQyqG4w9xCuZ7eJEwNmJRWw2VY84Oedb7WFcA27fiEVe8oUQx9hAUJ4ekurquucTGwsyO1XGdQ==", + "dev": true, + "requires": { + "get-intrinsic": "^1.1.1" + } + }, + "has-proto": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/has-proto/-/has-proto-1.0.1.tgz", + "integrity": "sha512-7qE+iP+O+bgF9clE5+UoBFzE65mlBiVj3tKCrlNQ0Ogwm0BjpT/gK4SlLYDMybDh5I3TCTKnPPa0oMG7JDYrhg==", + "dev": true + }, + "has-symbols": { + "version": "1.0.3", + "resolved": "https://registry.npmjs.org/has-symbols/-/has-symbols-1.0.3.tgz", + "integrity": "sha512-l3LCuF6MgDNwTDKkdYGEihYjt5pRPbEg46rtlmnSPlUbgmB8LOIrKJbYYFBSbnPaJexMKtiPO8hmeRjRz2Td+A==", + "dev": true + }, + "has-tostringtag": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/has-tostringtag/-/has-tostringtag-1.0.0.tgz", + "integrity": "sha512-kFjcSNhnlGV1kyoGk7OXKSawH5JOb/LzUc5w9B02hOTO0dfFRjbHQKvg1d6cf3HbeUmtU9VbbV3qzZ2Teh97WQ==", + "dev": true, + "requires": { + "has-symbols": "^1.0.2" + } + }, + "hash-base": { + "version": "3.1.0", + "resolved": "https://registry.npmjs.org/hash-base/-/hash-base-3.1.0.tgz", + "integrity": "sha512-1nmYp/rhMDiE7AYkDw+lLwlAzz0AntGIe51F3RfFfEqyQ3feY2eI/NcwC6umIQVOASPMsWJLJScWKSSvzL9IVA==", + "dev": true, + "requires": { + "inherits": "^2.0.4", + "readable-stream": "^3.6.0", + "safe-buffer": "^5.2.0" + } + }, + "hash.js": { + "version": "1.1.7", + "resolved": "https://registry.npmjs.org/hash.js/-/hash.js-1.1.7.tgz", + "integrity": "sha512-taOaskGt4z4SOANNseOviYDvjEJinIkRgmp7LbKP2YTTmVxWBl87s/uzK9r+44BclBSp2X7K1hqeNfz9JbBeXA==", + "dev": true, + "requires": { + "inherits": "^2.0.3", + "minimalistic-assert": "^1.0.1" + } + }, + "he": { + "version": "1.2.0", + "resolved": "https://registry.npmjs.org/he/-/he-1.2.0.tgz", + "integrity": "sha512-F/1DnUGPopORZi0ni+CvrCgHQ5FyEAHRLSApuYWMmrbSwoN2Mn/7k+Gl38gJnR7yyDZk6WLXwiGod1JOWNDKGw==", + "dev": true + }, + "header-case": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/header-case/-/header-case-1.0.1.tgz", + "integrity": "sha512-i0q9mkOeSuhXw6bGgiQCCBgY/jlZuV/7dZXyZ9c6LcBrqwvT8eT719E9uxE5LiZftdl+z81Ugbg/VvXV4OJOeQ==", + "dev": true, + "requires": { + "no-case": "^2.2.0", + "upper-case": "^1.1.3" + } + }, + "heap": { + "version": "0.2.7", + "resolved": "https://registry.npmjs.org/heap/-/heap-0.2.7.tgz", + "integrity": "sha512-2bsegYkkHO+h/9MGbn6KWcE45cHZgPANo5LXF7EvWdT0yT2EguSVO1nDgU5c8+ZOPwp2vMNa7YFsJhVcDR9Sdg==", + "dev": true + }, + "highlight.js": { + "version": "10.7.3", + "resolved": "https://registry.npmjs.org/highlight.js/-/highlight.js-10.7.3.tgz", + "integrity": "sha512-tzcUFauisWKNHaRkN4Wjl/ZA07gENAjFl3J/c480dprkGTg5EQstgaNFqBfUqCq54kZRIEcreTsAgF/m2quD7A==", + "dev": true + }, + "highlightjs-solidity": { + "version": "2.0.6", + "resolved": "https://registry.npmjs.org/highlightjs-solidity/-/highlightjs-solidity-2.0.6.tgz", + "integrity": "sha512-DySXWfQghjm2l6a/flF+cteroJqD4gI8GSdL4PtvxZSsAHie8m3yVe2JFoRg03ROKT6hp2Lc/BxXkqerNmtQYg==", + "dev": true + }, + "hmac-drbg": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/hmac-drbg/-/hmac-drbg-1.0.1.tgz", + "integrity": "sha512-Tti3gMqLdZfhOQY1Mzf/AanLiqh1WTiJgEj26ZuYQ9fbkLomzGchCws4FyrSd4VkpBfiNhaE1On+lOz894jvXg==", + "dev": true, + "requires": { + "hash.js": "^1.0.3", + "minimalistic-assert": "^1.0.0", + "minimalistic-crypto-utils": "^1.0.1" + } + }, + "hosted-git-info": { + "version": "2.8.9", + "resolved": "https://registry.npmjs.org/hosted-git-info/-/hosted-git-info-2.8.9.tgz", + "integrity": "sha512-mxIDAb9Lsm6DoOJ7xH+5+X4y1LU/4Hi50L9C5sIswK3JzULS4bwk1FvjdBgvYR4bzT4tuUQiC15FE2f5HbLvYw==", + "dev": true + }, + "htmlparser2": { + "version": "8.0.2", + "resolved": "https://registry.npmjs.org/htmlparser2/-/htmlparser2-8.0.2.tgz", + "integrity": "sha512-GYdjWKDkbRLkZ5geuHs5NY1puJ+PXwP7+fHPRz06Eirsb9ugf6d8kkXav6ADhcODhFFPMIXyxkxSuMf3D6NCFA==", + "dev": true, + "requires": { + "domelementtype": "^2.3.0", + "domhandler": "^5.0.3", + "domutils": "^3.0.1", + "entities": "^4.4.0" + } + }, + "http-basic": { + "version": "8.1.3", + "resolved": "https://registry.npmjs.org/http-basic/-/http-basic-8.1.3.tgz", + "integrity": "sha512-/EcDMwJZh3mABI2NhGfHOGOeOZITqfkEO4p/xK+l3NpyncIHUQBoMvCSF/b5GqvKtySC2srL/GGG3+EtlqlmCw==", + "dev": true, + "requires": { + "caseless": "^0.12.0", + "concat-stream": "^1.6.2", + "http-response-object": "^3.0.1", + "parse-cache-control": "^1.0.1" + } + }, + "http-cache-semantics": { + "version": "4.1.1", + "resolved": "https://registry.npmjs.org/http-cache-semantics/-/http-cache-semantics-4.1.1.tgz", + "integrity": "sha512-er295DKPVsV82j5kw1Gjt+ADA/XYHsajl82cGNQG2eyoPkvgUhX+nDIyelzhIWbbsXP39EHcI6l5tYs2FYqYXQ==", + "dev": true + }, + "http-errors": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/http-errors/-/http-errors-2.0.0.tgz", + "integrity": "sha512-FtwrG/euBzaEjYeRqOgly7G0qviiXoJWnvEH2Z1plBdXgbyjv34pHTSb9zoeHMyDy33+DWy5Wt9Wo+TURtOYSQ==", + "dev": true, + "requires": { + "depd": "2.0.0", + "inherits": "2.0.4", + "setprototypeof": "1.2.0", + "statuses": "2.0.1", + "toidentifier": "1.0.1" + } + }, + "http-https": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/http-https/-/http-https-1.0.0.tgz", + "integrity": "sha512-o0PWwVCSp3O0wS6FvNr6xfBCHgt0m1tvPLFOCc2iFDKTRAXhB7m8klDf7ErowFH8POa6dVdGatKU5I1YYwzUyg==", + "dev": true + }, + "http-response-object": { + "version": "3.0.2", + "resolved": "https://registry.npmjs.org/http-response-object/-/http-response-object-3.0.2.tgz", + "integrity": "sha512-bqX0XTF6fnXSQcEJ2Iuyr75yVakyjIDCqroJQ/aHfSdlM743Cwqoi2nDYMzLGWUcuTWGWy8AAvOKXTfiv6q9RA==", + "dev": true, + "requires": { + "@types/node": "^10.0.3" + }, + "dependencies": { + "@types/node": { + "version": "10.17.60", + "resolved": "https://registry.npmjs.org/@types/node/-/node-10.17.60.tgz", + "integrity": "sha512-F0KIgDJfy2nA3zMLmWGKxcH2ZVEtCZXHHdOQs2gSaQ27+lNeEfGxzkIw90aXswATX7AZ33tahPbzy6KAfUreVw==", + "dev": true + } + } + }, + "http-signature": { + "version": "1.2.0", + "resolved": "https://registry.npmjs.org/http-signature/-/http-signature-1.2.0.tgz", + "integrity": "sha512-CAbnr6Rz4CYQkLYUtSNXxQPUH2gK8f3iWexVlsnMeD+GjlsQ0Xsy1cOX+mN3dtxYomRy21CiOzU8Uhw6OwncEQ==", + "dev": true, + "requires": { + "assert-plus": "^1.0.0", + "jsprim": "^1.2.2", + "sshpk": "^1.7.0" + } + }, + "http2-wrapper": { + "version": "2.2.0", + "resolved": "https://registry.npmjs.org/http2-wrapper/-/http2-wrapper-2.2.0.tgz", + "integrity": "sha512-kZB0wxMo0sh1PehyjJUWRFEd99KC5TLjZ2cULC4f9iqJBAmKQQXEICjxl5iPJRwP40dpeHFqqhm7tYCvODpqpQ==", + "dev": true, + "requires": { + "quick-lru": "^5.1.1", + "resolve-alpn": "^1.2.0" + }, + "dependencies": { + "quick-lru": { + "version": "5.1.1", + "resolved": "https://registry.npmjs.org/quick-lru/-/quick-lru-5.1.1.tgz", + "integrity": "sha512-WuyALRjWPDGtt/wzJiadO5AXY+8hZ80hVpe6MyivgraREW751X3SbhRvG3eLKOYN+8VEvqLcf3wdnt44Z4S4SA==", + "dev": true + } + } + }, + "https-proxy-agent": { + "version": "5.0.1", + "resolved": "https://registry.npmjs.org/https-proxy-agent/-/https-proxy-agent-5.0.1.tgz", + "integrity": "sha512-dFcAjpTQFgoLMzC2VwU+C/CbS7uRL0lWmxDITmqm7C+7F0Odmj6s9l6alZc6AELXhrnggM2CeWSXHGOdX2YtwA==", + "dev": true, + "requires": { + "agent-base": "6", + "debug": "4" + } + }, + "human-id": { + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/human-id/-/human-id-1.0.2.tgz", + "integrity": "sha512-UNopramDEhHJD+VR+ehk8rOslwSfByxPIZyJRfV739NDhN5LF1fa1MqnzKm2lGTQRjNrjK19Q5fhkgIfjlVUKw==", + "dev": true + }, + "iconv-lite": { + "version": "0.4.24", + "resolved": "https://registry.npmjs.org/iconv-lite/-/iconv-lite-0.4.24.tgz", + "integrity": "sha512-v3MXnZAcvnywkTUEZomIActle7RXXeedOR31wwl7VlyoXO4Qi9arvSenNQWne1TcRwhCL1HwLI21bEqdpj8/rA==", + "dev": true, + "requires": { + "safer-buffer": ">= 2.1.2 < 3" + } + }, + "idna-uts46-hx": { + "version": "2.3.1", + "resolved": "https://registry.npmjs.org/idna-uts46-hx/-/idna-uts46-hx-2.3.1.tgz", + "integrity": "sha512-PWoF9Keq6laYdIRwwCdhTPl60xRqAloYNMQLiyUnG42VjT53oW07BXIRM+NK7eQjzXjAk2gUvX9caRxlnF9TAA==", + "dev": true, + "requires": { + "punycode": "2.1.0" + } + }, + "ieee754": { + "version": "1.2.1", + "resolved": "https://registry.npmjs.org/ieee754/-/ieee754-1.2.1.tgz", + "integrity": "sha512-dcyqhDvX1C46lXZcVqCpK+FtMRQVdIMN6/Df5js2zouUsqG7I6sFxitIC+7KYK29KdXOLHdu9zL4sFnoVQnqaA==", + "dev": true + }, + "ignore": { + "version": "5.2.4", + "resolved": "https://registry.npmjs.org/ignore/-/ignore-5.2.4.tgz", + "integrity": "sha512-MAb38BcSbH0eHNBxn7ql2NH/kX33OkB3lZ1BNdh7ENeRChHTYsTvWrMubiIAMNS2llXEEgZ1MUOBtXChP3kaFQ==", + "dev": true + }, + "immutable": { + "version": "4.3.0", + "resolved": "https://registry.npmjs.org/immutable/-/immutable-4.3.0.tgz", + "integrity": "sha512-0AOCmOip+xgJwEVTQj1EfiDDOkPmuyllDuTuEX+DDXUgapLAsBIfkg3sxCYyCEA8mQqZrrxPUGjcOQ2JS3WLkg==", + "dev": true + }, + "import-fresh": { + "version": "3.3.0", + "resolved": "https://registry.npmjs.org/import-fresh/-/import-fresh-3.3.0.tgz", + "integrity": "sha512-veYYhQa+D1QBKznvhUHxb8faxlrwUnxseDAbAp457E0wLNio2bOSKnjYDhMj+YiAq61xrMGhQk9iXVk5FzgQMw==", + "dev": true, + "requires": { + "parent-module": "^1.0.0", + "resolve-from": "^4.0.0" + }, + "dependencies": { + "resolve-from": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/resolve-from/-/resolve-from-4.0.0.tgz", + "integrity": "sha512-pb/MYmXstAkysRFx8piNI1tGFNQIFA3vkE3Gq4EuA1dF6gHp/+vgZqsCGJapvy8N3Q+4o7FwvquPJcnZ7RYy4g==", + "dev": true + } + } + }, + "imurmurhash": { + "version": "0.1.4", + "resolved": "https://registry.npmjs.org/imurmurhash/-/imurmurhash-0.1.4.tgz", + "integrity": "sha512-JmXMZ6wuvDmLiHEml9ykzqO6lwFbof0GG4IkcGaENdCRDDmMVnny7s5HsIgHCbaq0w2MyPhDqkhTUgS2LU2PHA==", + "dev": true + }, + "indent-string": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/indent-string/-/indent-string-4.0.0.tgz", + "integrity": "sha512-EdDDZu4A2OyIK7Lr/2zG+w5jmbuk1DVBnEwREQvBzspBJkCEbRa8GxU1lghYcaGJCnRWibjDXlq779X1/y5xwg==", + "dev": true + }, + "inflight": { + "version": "1.0.6", + "resolved": "https://registry.npmjs.org/inflight/-/inflight-1.0.6.tgz", + "integrity": "sha512-k92I/b08q4wvFscXCLvqfsHCrjrF7yiXsQuIVvVE7N82W3+aqpzuUdBbfhWcy/FZR3/4IgflMgKLOsvPDrGCJA==", + "dev": true, + "requires": { + "once": "^1.3.0", + "wrappy": "1" + } + }, + "inherits": { + "version": "2.0.4", + "resolved": "https://registry.npmjs.org/inherits/-/inherits-2.0.4.tgz", + "integrity": "sha512-k/vGaX4/Yla3WzyMCvTQOXYeIHvqOKtnqBduzTHpzpQZzAskKMhZ2K+EnBiSM9zGSoIFeMpXKxa4dYeZIQqewQ==", + "dev": true + }, + "ini": { + "version": "1.3.8", + "resolved": "https://registry.npmjs.org/ini/-/ini-1.3.8.tgz", + "integrity": "sha512-JV/yugV2uzW5iMRSiZAyDtQd+nxtUnjeLt0acNdw98kKLrvuRVyB80tsREOE7yvGVgalhZ6RNXCmEHkUKBKxew==", + "dev": true + }, + "internal-slot": { + "version": "1.0.5", + "resolved": "https://registry.npmjs.org/internal-slot/-/internal-slot-1.0.5.tgz", + "integrity": "sha512-Y+R5hJrzs52QCG2laLn4udYVnxsfny9CpOhNhUvk/SSSVyF6T27FzRbF0sroPidSu3X8oEAkOn2K804mjpt6UQ==", + "dev": true, + "requires": { + "get-intrinsic": "^1.2.0", + "has": "^1.0.3", + "side-channel": "^1.0.4" + } + }, + "interpret": { + "version": "1.4.0", + "resolved": "https://registry.npmjs.org/interpret/-/interpret-1.4.0.tgz", + "integrity": "sha512-agE4QfB2Lkp9uICn7BAqoscw4SZP9kTE2hxiFI3jBPmXJfdqiahTbUuKGsMoN2GtqL9AxhYioAcVvgsb1HvRbA==", + "dev": true + }, + "invert-kv": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/invert-kv/-/invert-kv-1.0.0.tgz", + "integrity": "sha512-xgs2NH9AE66ucSq4cNG1nhSFghr5l6tdL15Pk+jl46bmmBapgoaY/AacXyaDznAqmGL99TiLSQgO/XazFSKYeQ==", + "dev": true + }, + "io-ts": { + "version": "1.10.4", + "resolved": "https://registry.npmjs.org/io-ts/-/io-ts-1.10.4.tgz", + "integrity": "sha512-b23PteSnYXSONJ6JQXRAlvJhuw8KOtkqa87W4wDtvMrud/DTJd5X+NpOOI+O/zZwVq6v0VLAaJ+1EDViKEuN9g==", + "dev": true, + "requires": { + "fp-ts": "^1.0.0" + } + }, + "ipaddr.js": { + "version": "1.9.1", + "resolved": "https://registry.npmjs.org/ipaddr.js/-/ipaddr.js-1.9.1.tgz", + "integrity": "sha512-0KI/607xoxSToH7GjN1FfSbLoU0+btTicjsQSWQlh/hZykN8KpmMf7uYwPW3R+akZ6R/w18ZlXSHBYXiYUPO3g==", + "dev": true + }, + "is-arguments": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/is-arguments/-/is-arguments-1.1.1.tgz", + "integrity": "sha512-8Q7EARjzEnKpt/PCD7e1cgUS0a6X8u5tdSiMqXhojOdoV9TsMsiO+9VLC5vAmO8N7/GmXn7yjR8qnA6bVAEzfA==", + "dev": true, + "requires": { + "call-bind": "^1.0.2", + "has-tostringtag": "^1.0.0" + } + }, + "is-array-buffer": { + "version": "3.0.2", + "resolved": "https://registry.npmjs.org/is-array-buffer/-/is-array-buffer-3.0.2.tgz", + "integrity": "sha512-y+FyyR/w8vfIRq4eQcM1EYgSTnmHXPqaF+IgzgraytCFq5Xh8lllDVmAZolPJiZttZLeFSINPYMaEJ7/vWUa1w==", + "dev": true, + "requires": { + "call-bind": "^1.0.2", + "get-intrinsic": "^1.2.0", + "is-typed-array": "^1.1.10" + } + }, + "is-arrayish": { + "version": "0.2.1", + "resolved": "https://registry.npmjs.org/is-arrayish/-/is-arrayish-0.2.1.tgz", + "integrity": "sha512-zz06S8t0ozoDXMG+ube26zeCTNXcKIPJZJi8hBrF4idCLms4CG9QtK7qBl1boi5ODzFpjswb5JPmHCbMpjaYzg==", + "dev": true + }, + "is-bigint": { + "version": "1.0.4", + "resolved": "https://registry.npmjs.org/is-bigint/-/is-bigint-1.0.4.tgz", + "integrity": "sha512-zB9CruMamjym81i2JZ3UMn54PKGsQzsJeo6xvN3HJJ4CAsQNB6iRutp2To77OfCNuoxspsIhzaPoO1zyCEhFOg==", + "dev": true, + "requires": { + "has-bigints": "^1.0.1" + } + }, + "is-binary-path": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/is-binary-path/-/is-binary-path-2.1.0.tgz", + "integrity": "sha512-ZMERYes6pDydyuGidse7OsHxtbI7WVeUEozgR/g7rd0xUimYNlvZRE/K2MgZTjWy725IfelLeVcEM97mmtRGXw==", + "dev": true, + "requires": { + "binary-extensions": "^2.0.0" + } + }, + "is-boolean-object": { + "version": "1.1.2", + "resolved": "https://registry.npmjs.org/is-boolean-object/-/is-boolean-object-1.1.2.tgz", + "integrity": "sha512-gDYaKHJmnj4aWxyj6YHyXVpdQawtVLHU5cb+eztPGczf6cjuTdwve5ZIEfgXqH4e57An1D1AKf8CZ3kYrQRqYA==", + "dev": true, + "requires": { + "call-bind": "^1.0.2", + "has-tostringtag": "^1.0.0" + } + }, + "is-buffer": { + "version": "2.0.5", + "resolved": "https://registry.npmjs.org/is-buffer/-/is-buffer-2.0.5.tgz", + "integrity": "sha512-i2R6zNFDwgEHJyQUtJEk0XFi1i0dPFn/oqjK3/vPCcDeJvW5NQ83V8QbicfF1SupOaB0h8ntgBC2YiE7dfyctQ==", + "dev": true + }, + "is-callable": { + "version": "1.2.7", + "resolved": "https://registry.npmjs.org/is-callable/-/is-callable-1.2.7.tgz", + "integrity": "sha512-1BC0BVFhS/p0qtw6enp8e+8OD0UrK0oFLztSjNzhcKA3WDuJxxAPXzPuPtKkjEY9UUoEWlX/8fgKeu2S8i9JTA==", + "dev": true + }, + "is-ci": { + "version": "3.0.1", + "resolved": "https://registry.npmjs.org/is-ci/-/is-ci-3.0.1.tgz", + "integrity": "sha512-ZYvCgrefwqoQ6yTyYUbQu64HsITZ3NfKX1lzaEYdkTDcfKzzCI/wthRRYKkdjHKFVgNiXKAKm65Zo1pk2as/QQ==", + "dev": true, + "requires": { + "ci-info": "^3.2.0" + } + }, + "is-date-object": { + "version": "1.0.5", + "resolved": "https://registry.npmjs.org/is-date-object/-/is-date-object-1.0.5.tgz", + "integrity": "sha512-9YQaSxsAiSwcvS33MBk3wTCVnWK+HhF8VZR2jRxehM16QcVOdHqPn4VPHmRK4lSr38n9JriurInLcP90xsYNfQ==", + "dev": true, + "requires": { + "has-tostringtag": "^1.0.0" + } + }, + "is-extglob": { + "version": "2.1.1", + "resolved": "https://registry.npmjs.org/is-extglob/-/is-extglob-2.1.1.tgz", + "integrity": "sha512-SbKbANkN603Vi4jEZv49LeVJMn4yGwsbzZworEoyEiutsN3nJYdbO36zfhGJ6QEDpOZIFkDtnq5JRxmvl3jsoQ==", + "dev": true + }, + "is-fullwidth-code-point": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/is-fullwidth-code-point/-/is-fullwidth-code-point-2.0.0.tgz", + "integrity": "sha512-VHskAKYM8RfSFXwee5t5cbN5PZeq1Wrh6qd5bkyiXIf6UQcN6w/A0eXM9r6t8d+GYOh+o6ZhiEnb88LN/Y8m2w==", + "dev": true + }, + "is-function": { + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/is-function/-/is-function-1.0.2.tgz", + "integrity": "sha512-lw7DUp0aWXYg+CBCN+JKkcE0Q2RayZnSvnZBlwgxHBQhqt5pZNVy4Ri7H9GmmXkdu7LUthszM+Tor1u/2iBcpQ==", + "dev": true + }, + "is-generator-function": { + "version": "1.0.10", + "resolved": "https://registry.npmjs.org/is-generator-function/-/is-generator-function-1.0.10.tgz", + "integrity": "sha512-jsEjy9l3yiXEQ+PsXdmBwEPcOxaXWLspKdplFUVI9vq1iZgIekeC0L167qeu86czQaxed3q/Uzuw0swL0irL8A==", + "dev": true, + "requires": { + "has-tostringtag": "^1.0.0" + } + }, + "is-glob": { + "version": "4.0.3", + "resolved": "https://registry.npmjs.org/is-glob/-/is-glob-4.0.3.tgz", + "integrity": "sha512-xelSayHH36ZgE7ZWhli7pW34hNbNl8Ojv5KVmkJD4hBdD3th8Tfk9vYasLM+mXWOZhFkgZfxhLSnrwRr4elSSg==", + "dev": true, + "requires": { + "is-extglob": "^2.1.1" + } + }, + "is-hex-prefixed": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/is-hex-prefixed/-/is-hex-prefixed-1.0.0.tgz", + "integrity": "sha512-WvtOiug1VFrE9v1Cydwm+FnXd3+w9GaeVUss5W4v/SLy3UW00vP+6iNF2SdnfiBoLy4bTqVdkftNGTUeOFVsbA==", + "dev": true + }, + "is-lower-case": { + "version": "1.1.3", + "resolved": "https://registry.npmjs.org/is-lower-case/-/is-lower-case-1.1.3.tgz", + "integrity": "sha512-+5A1e/WJpLLXZEDlgz4G//WYSHyQBD32qa4Jd3Lw06qQlv3fJHnp3YIHjTQSGzHMgzmVKz2ZP3rBxTHkPw/lxA==", + "dev": true, + "requires": { + "lower-case": "^1.1.0" + } + }, + "is-negative-zero": { + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/is-negative-zero/-/is-negative-zero-2.0.2.tgz", + "integrity": "sha512-dqJvarLawXsFbNDeJW7zAz8ItJ9cd28YufuuFzh0G8pNHjJMnY08Dv7sYX2uF5UpQOwieAeOExEYAWWfu7ZZUA==", + "dev": true + }, + "is-number": { + "version": "7.0.0", + "resolved": "https://registry.npmjs.org/is-number/-/is-number-7.0.0.tgz", + "integrity": "sha512-41Cifkg6e8TylSpdtTpeLVMqvSBEVzTttHvERD741+pnZ8ANv0004MRL43QKPDlK9cGvNp6NZWZUBlbGXYxxng==", + "dev": true + }, + "is-number-object": { + "version": "1.0.7", + "resolved": "https://registry.npmjs.org/is-number-object/-/is-number-object-1.0.7.tgz", + "integrity": "sha512-k1U0IRzLMo7ZlYIfzRu23Oh6MiIFasgpb9X76eqfFZAqwH44UI4KTBvBYIZ1dSL9ZzChTB9ShHfLkR4pdW5krQ==", + "dev": true, + "requires": { + "has-tostringtag": "^1.0.0" + } + }, + "is-path-inside": { + "version": "3.0.3", + "resolved": "https://registry.npmjs.org/is-path-inside/-/is-path-inside-3.0.3.tgz", + "integrity": "sha512-Fd4gABb+ycGAmKou8eMftCupSir5lRxqf4aD/vd0cD2qc4HL07OjCeuHMr8Ro4CoMaeCKDB0/ECBOVWjTwUvPQ==", + "dev": true + }, + "is-plain-obj": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/is-plain-obj/-/is-plain-obj-1.1.0.tgz", + "integrity": "sha512-yvkRyxmFKEOQ4pNXCmJG5AEQNlXJS5LaONXo5/cLdTZdWvsZ1ioJEonLGAosKlMWE8lwUy/bJzMjcw8az73+Fg==", + "dev": true + }, + "is-port-reachable": { + "version": "3.1.0", + "resolved": "https://registry.npmjs.org/is-port-reachable/-/is-port-reachable-3.1.0.tgz", + "integrity": "sha512-vjc0SSRNZ32s9SbZBzGaiP6YVB+xglLShhgZD/FHMZUXBvQWaV9CtzgeVhjccFJrI6RAMV+LX7NYxueW/A8W5A==", + "dev": true + }, + "is-regex": { + "version": "1.1.4", + "resolved": "https://registry.npmjs.org/is-regex/-/is-regex-1.1.4.tgz", + "integrity": "sha512-kvRdxDsxZjhzUX07ZnLydzS1TU/TJlTUHHY4YLL87e37oUA49DfkLqgy+VjFocowy29cKvcSiu+kIv728jTTVg==", + "dev": true, + "requires": { + "call-bind": "^1.0.2", + "has-tostringtag": "^1.0.0" + } + }, + "is-shared-array-buffer": { + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/is-shared-array-buffer/-/is-shared-array-buffer-1.0.2.tgz", + "integrity": "sha512-sqN2UDu1/0y6uvXyStCOzyhAjCSlHceFoMKJW8W9EU9cvic/QdsZ0kEU93HEy3IUEFZIiH/3w+AH/UQbPHNdhA==", + "dev": true, + "requires": { + "call-bind": "^1.0.2" + } + }, + "is-string": { + "version": "1.0.7", + "resolved": "https://registry.npmjs.org/is-string/-/is-string-1.0.7.tgz", + "integrity": "sha512-tE2UXzivje6ofPW7l23cjDOMa09gb7xlAqG6jG5ej6uPV32TlWP3NKPigtaGeHNu9fohccRYvIiZMfOOnOYUtg==", + "dev": true, + "requires": { + "has-tostringtag": "^1.0.0" + } + }, + "is-subdir": { + "version": "1.2.0", + "resolved": "https://registry.npmjs.org/is-subdir/-/is-subdir-1.2.0.tgz", + "integrity": "sha512-2AT6j+gXe/1ueqbW6fLZJiIw3F8iXGJtt0yDrZaBhAZEG1raiTxKWU+IPqMCzQAXOUCKdA4UDMgacKH25XG2Cw==", + "dev": true, + "requires": { + "better-path-resolve": "1.0.0" + } + }, + "is-symbol": { + "version": "1.0.4", + "resolved": "https://registry.npmjs.org/is-symbol/-/is-symbol-1.0.4.tgz", + "integrity": "sha512-C/CPBqKWnvdcxqIARxyOh4v1UUEOCHpgDa0WYgpKDFMszcrPcffg5uhwSgPCLD2WWxmq6isisz87tzT01tuGhg==", + "dev": true, + "requires": { + "has-symbols": "^1.0.2" + } + }, + "is-typed-array": { + "version": "1.1.10", + "resolved": "https://registry.npmjs.org/is-typed-array/-/is-typed-array-1.1.10.tgz", + "integrity": "sha512-PJqgEHiWZvMpaFZ3uTc8kHPM4+4ADTlDniuQL7cU/UDA0Ql7F70yGfHph3cLNe+c9toaigv+DFzTJKhc2CtO6A==", + "dev": true, + "requires": { + "available-typed-arrays": "^1.0.5", + "call-bind": "^1.0.2", + "for-each": "^0.3.3", + "gopd": "^1.0.1", + "has-tostringtag": "^1.0.0" + } + }, + "is-typedarray": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/is-typedarray/-/is-typedarray-1.0.0.tgz", + "integrity": "sha512-cyA56iCMHAh5CdzjJIa4aohJyeO1YbwLi3Jc35MmRU6poroFjIGZzUzupGiRPOjgHg9TLu43xbpwXk523fMxKA==", + "dev": true + }, + "is-unicode-supported": { + "version": "0.1.0", + "resolved": "https://registry.npmjs.org/is-unicode-supported/-/is-unicode-supported-0.1.0.tgz", + "integrity": "sha512-knxG2q4UC3u8stRGyAVJCOdxFmv5DZiRcdlIaAQXAbSfJya+OhopNotLQrstBhququ4ZpuKbDc/8S6mgXgPFPw==", + "dev": true + }, + "is-upper-case": { + "version": "1.1.2", + "resolved": "https://registry.npmjs.org/is-upper-case/-/is-upper-case-1.1.2.tgz", + "integrity": "sha512-GQYSJMgfeAmVwh9ixyk888l7OIhNAGKtY6QA+IrWlu9MDTCaXmeozOZ2S9Knj7bQwBO/H6J2kb+pbyTUiMNbsw==", + "dev": true, + "requires": { + "upper-case": "^1.1.0" + } + }, + "is-utf8": { + "version": "0.2.1", + "resolved": "https://registry.npmjs.org/is-utf8/-/is-utf8-0.2.1.tgz", + "integrity": "sha512-rMYPYvCzsXywIsldgLaSoPlw5PfoB/ssr7hY4pLfcodrA5M/eArza1a9VmTiNIBNMjOGr1Ow9mTyU2o69U6U9Q==", + "dev": true + }, + "is-weakref": { + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/is-weakref/-/is-weakref-1.0.2.tgz", + "integrity": "sha512-qctsuLZmIQ0+vSSMfoVvyFe2+GSEvnmZ2ezTup1SBse9+twCCeial6EEi3Nc2KFcf6+qz2FBPnjXsk8xhKSaPQ==", + "dev": true, + "requires": { + "call-bind": "^1.0.2" + } + }, + "is-windows": { + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/is-windows/-/is-windows-1.0.2.tgz", + "integrity": "sha512-eXK1UInq2bPmjyX6e3VHIzMLobc4J94i4AWn+Hpq3OU5KkrRC96OAcR3PRJ/pGu6m8TRnBHP9dkXQVsT/COVIA==", + "dev": true + }, + "isarray": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/isarray/-/isarray-1.0.0.tgz", + "integrity": "sha512-VLghIWNM6ELQzo7zwmcg0NmTVyWKYjvIeM83yjp0wRDTmUnrM678fQbcKBo6n2CJEF0szoG//ytg+TKla89ALQ==", + "dev": true + }, + "isexe": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/isexe/-/isexe-2.0.0.tgz", + "integrity": "sha512-RHxMLp9lnKHGHRng9QFhRCMbYAcVpn69smSGcq3f36xjgVVWThj4qqLbTLlq7Ssj8B+fIQ1EuCEGI2lKsyQeIw==", + "dev": true + }, + "isstream": { + "version": "0.1.2", + "resolved": "https://registry.npmjs.org/isstream/-/isstream-0.1.2.tgz", + "integrity": "sha512-Yljz7ffyPbrLpLngrMtZ7NduUgVvi6wG9RJ9IUcyCd59YQ911PBJphODUcbOVbqYfxe1wuYf/LJ8PauMRwsM/g==", + "dev": true + }, + "js-sdsl": { + "version": "4.4.1", + "resolved": "https://registry.npmjs.org/js-sdsl/-/js-sdsl-4.4.1.tgz", + "integrity": "sha512-6Gsx8R0RucyePbWqPssR8DyfuXmLBooYN5cZFZKjHGnQuaf7pEzhtpceagJxVu4LqhYY5EYA7nko3FmeHZ1KbA==", + "dev": true + }, + "js-sha3": { + "version": "0.8.0", + "resolved": "https://registry.npmjs.org/js-sha3/-/js-sha3-0.8.0.tgz", + "integrity": "sha512-gF1cRrHhIzNfToc802P800N8PpXS+evLLXfsVpowqmAFR9uwbi89WvXg2QspOmXL8QL86J4T1EpFu+yUkwJY3Q==", + "dev": true + }, + "js-tokens": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/js-tokens/-/js-tokens-4.0.0.tgz", + "integrity": "sha512-RdJUflcE3cUzKiMqQgsCu06FPu9UdIJO0beYbPhHN4k6apgJtifcoCtT9bcxOpYBtpD2kCM6Sbzg4CausW/PKQ==", + "dev": true + }, + "js-yaml": { + "version": "3.14.1", + "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-3.14.1.tgz", + "integrity": "sha512-okMH7OXXJ7YrN9Ok3/SXrnu4iX9yOk+25nqX4imS2npuvTYDmo/QEZoqwZkYaIDk3jVvBOTOIEgEhaLOynBS9g==", + "dev": true, + "requires": { + "argparse": "^1.0.7", + "esprima": "^4.0.0" + } + }, + "jsbn": { + "version": "0.1.1", + "resolved": "https://registry.npmjs.org/jsbn/-/jsbn-0.1.1.tgz", + "integrity": "sha512-UVU9dibq2JcFWxQPA6KCqj5O42VOmAY3zQUfEKxU0KpTGXwNoCjkX1e13eHNvw/xPynt6pU0rZ1htjWTNTSXsg==", + "dev": true + }, + "json-buffer": { + "version": "3.0.1", + "resolved": "https://registry.npmjs.org/json-buffer/-/json-buffer-3.0.1.tgz", + "integrity": "sha512-4bV5BfR2mqfQTJm+V5tPPdf+ZpuhiIvTuAB5g8kcrXOZpTT/QwwVRWBywX1ozr6lEuPdbHxwaJlm9G6mI2sfSQ==", + "dev": true + }, + "json-parse-even-better-errors": { + "version": "2.3.1", + "resolved": "https://registry.npmjs.org/json-parse-even-better-errors/-/json-parse-even-better-errors-2.3.1.tgz", + "integrity": "sha512-xyFwyhro/JEof6Ghe2iz2NcXoj2sloNsWr/XsERDK/oiPCfaNhl5ONfp+jQdAZRQQ0IJWNzH9zIZF7li91kh2w==", + "dev": true + }, + "json-schema": { + "version": "0.4.0", + "resolved": "https://registry.npmjs.org/json-schema/-/json-schema-0.4.0.tgz", + "integrity": "sha512-es94M3nTIfsEPisRafak+HDLfHXnKBhV3vU5eqPcS3flIWqcxJWgXHXiey3YrpaNsanY5ei1VoYEbOzijuq9BA==", + "dev": true + }, + "json-schema-traverse": { + "version": "0.4.1", + "resolved": "https://registry.npmjs.org/json-schema-traverse/-/json-schema-traverse-0.4.1.tgz", + "integrity": "sha512-xbbCH5dCYU5T8LcEhhuh7HJ88HXuW3qsI3Y0zOZFKfZEHcpWiHU/Jxzk629Brsab/mMiHQti9wMP+845RPe3Vg==", + "dev": true + }, + "json-stable-stringify-without-jsonify": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/json-stable-stringify-without-jsonify/-/json-stable-stringify-without-jsonify-1.0.1.tgz", + "integrity": "sha512-Bdboy+l7tA3OGW6FjyFHWkP5LuByj1Tk33Ljyq0axyzdk9//JSi2u3fP1QSmd1KNwq6VOKYGlAu87CisVir6Pw==", + "dev": true + }, + "json-stringify-safe": { + "version": "5.0.1", + "resolved": "https://registry.npmjs.org/json-stringify-safe/-/json-stringify-safe-5.0.1.tgz", + "integrity": "sha512-ZClg6AaYvamvYEE82d3Iyd3vSSIjQ+odgjaTzRuO3s7toCdFKczob2i0zCh7JE8kWn17yvAWhUVxvqGwUalsRA==", + "dev": true + }, + "jsonfile": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/jsonfile/-/jsonfile-4.0.0.tgz", + "integrity": "sha512-m6F1R3z8jjlf2imQHS2Qez5sjKWQzbuuhuJ/FKYFRZvPE3PuHcSMVZzfsLhGVOkfd20obL5SWEBew5ShlquNxg==", + "dev": true, + "requires": { + "graceful-fs": "^4.1.6" + } + }, + "jsonschema": { + "version": "1.4.1", + "resolved": "https://registry.npmjs.org/jsonschema/-/jsonschema-1.4.1.tgz", + "integrity": "sha512-S6cATIPVv1z0IlxdN+zUk5EPjkGCdnhN4wVSBlvoUO1tOLJootbo9CquNJmbIh4yikWHiUedhRYrNPn1arpEmQ==", + "dev": true + }, + "jsprim": { + "version": "1.4.2", + "resolved": "https://registry.npmjs.org/jsprim/-/jsprim-1.4.2.tgz", + "integrity": "sha512-P2bSOMAc/ciLz6DzgjVlGJP9+BrJWu5UDGK70C2iweC5QBIeFf0ZXRvGjEj2uYgrY2MkAAhsSWHDWlFtEroZWw==", + "dev": true, + "requires": { + "assert-plus": "1.0.0", + "extsprintf": "1.3.0", + "json-schema": "0.4.0", + "verror": "1.10.0" + } + }, + "keccak": { + "version": "3.0.3", + "resolved": "https://registry.npmjs.org/keccak/-/keccak-3.0.3.tgz", + "integrity": "sha512-JZrLIAJWuZxKbCilMpNz5Vj7Vtb4scDG3dMXLOsbzBmQGyjwE61BbW7bJkfKKCShXiQZt3T6sBgALRtmd+nZaQ==", + "dev": true, + "requires": { + "node-addon-api": "^2.0.0", + "node-gyp-build": "^4.2.0", + "readable-stream": "^3.6.0" + } + }, + "keccak256": { + "version": "1.0.6", + "resolved": "https://registry.npmjs.org/keccak256/-/keccak256-1.0.6.tgz", + "integrity": "sha512-8GLiM01PkdJVGUhR1e6M/AvWnSqYS0HaERI+K/QtStGDGlSTx2B1zTqZk4Zlqu5TxHJNTxWAdP9Y+WI50OApUw==", + "dev": true, + "requires": { + "bn.js": "^5.2.0", + "buffer": "^6.0.3", + "keccak": "^3.0.2" + }, + "dependencies": { + "bn.js": { + "version": "5.2.1", + "resolved": "https://registry.npmjs.org/bn.js/-/bn.js-5.2.1.tgz", + "integrity": "sha512-eXRvHzWyYPBuB4NBy0cmYQjGitUrtqwbvlzP3G6VFnNRbsZQIxQ10PbKKHt8gZ/HW/D/747aDl+QkDqg3KQLMQ==", + "dev": true + }, + "buffer": { + "version": "6.0.3", + "resolved": "https://registry.npmjs.org/buffer/-/buffer-6.0.3.tgz", + "integrity": "sha512-FTiCpNxtwiZZHEZbcbTIcZjERVICn9yq/pDFkTl95/AxzD1naBctN7YO68riM/gLSDY7sdrMby8hofADYuuqOA==", + "dev": true, + "requires": { + "base64-js": "^1.3.1", + "ieee754": "^1.2.1" + } + } + } + }, + "keyv": { + "version": "4.5.2", + "resolved": "https://registry.npmjs.org/keyv/-/keyv-4.5.2.tgz", + "integrity": "sha512-5MHbFaKn8cNSmVW7BYnijeAVlE4cYA/SVkifVgrh7yotnfhKmjuXpDKjrABLnT0SfHWV21P8ow07OGfRrNDg8g==", + "dev": true, + "requires": { + "json-buffer": "3.0.1" + } + }, + "kind-of": { + "version": "6.0.3", + "resolved": "https://registry.npmjs.org/kind-of/-/kind-of-6.0.3.tgz", + "integrity": "sha512-dcS1ul+9tmeD95T+x28/ehLgd9mENa3LsvDTtzm3vyBEO7RPptvAD+t44WVXaUjTBRcrpFeFlC8WCruUR456hw==", + "dev": true + }, + "klaw": { + "version": "1.3.1", + "resolved": "https://registry.npmjs.org/klaw/-/klaw-1.3.1.tgz", + "integrity": "sha512-TED5xi9gGQjGpNnvRWknrwAB1eL5GciPfVFOt3Vk1OJCVDQbzuSfrF3hkUQKlsgKrG1F+0t5W0m+Fje1jIt8rw==", + "dev": true, + "requires": { + "graceful-fs": "^4.1.9" + } + }, + "kleur": { + "version": "4.1.5", + "resolved": "https://registry.npmjs.org/kleur/-/kleur-4.1.5.tgz", + "integrity": "sha512-o+NO+8WrRiQEE4/7nwRJhN1HWpVmJm511pBHUxPLtp0BUISzlBplORYSmTclCnJvQq2tKu/sgl3xVpkc7ZWuQQ==", + "dev": true + }, + "lcid": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/lcid/-/lcid-1.0.0.tgz", + "integrity": "sha512-YiGkH6EnGrDGqLMITnGjXtGmNtjoXw9SVUzcaos8RBi7Ps0VBylkq+vOcY9QE5poLasPCR849ucFUkl0UzUyOw==", + "dev": true, + "requires": { + "invert-kv": "^1.0.0" + } + }, + "level": { + "version": "8.0.0", + "resolved": "https://registry.npmjs.org/level/-/level-8.0.0.tgz", + "integrity": "sha512-ypf0jjAk2BWI33yzEaaotpq7fkOPALKAgDBxggO6Q9HGX2MRXn0wbP1Jn/tJv1gtL867+YOjOB49WaUF3UoJNQ==", + "dev": true, + "requires": { + "browser-level": "^1.0.1", + "classic-level": "^1.2.0" + } + }, + "level-supports": { + "version": "4.0.1", + "resolved": "https://registry.npmjs.org/level-supports/-/level-supports-4.0.1.tgz", + "integrity": "sha512-PbXpve8rKeNcZ9C1mUicC9auIYFyGpkV9/i6g76tLgANwWhtG2v7I4xNBUlkn3lE2/dZF3Pi0ygYGtLc4RXXdA==", + "dev": true + }, + "level-transcoder": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/level-transcoder/-/level-transcoder-1.0.1.tgz", + "integrity": "sha512-t7bFwFtsQeD8cl8NIoQ2iwxA0CL/9IFw7/9gAjOonH0PWTTiRfY7Hq+Ejbsxh86tXobDQ6IOiddjNYIfOBs06w==", + "dev": true, + "requires": { + "buffer": "^6.0.3", + "module-error": "^1.0.1" + }, + "dependencies": { + "buffer": { + "version": "6.0.3", + "resolved": "https://registry.npmjs.org/buffer/-/buffer-6.0.3.tgz", + "integrity": "sha512-FTiCpNxtwiZZHEZbcbTIcZjERVICn9yq/pDFkTl95/AxzD1naBctN7YO68riM/gLSDY7sdrMby8hofADYuuqOA==", + "dev": true, + "requires": { + "base64-js": "^1.3.1", + "ieee754": "^1.2.1" + } + } + } + }, + "levn": { + "version": "0.4.1", + "resolved": "https://registry.npmjs.org/levn/-/levn-0.4.1.tgz", + "integrity": "sha512-+bT2uH4E5LGE7h/n3evcS/sQlJXCpIp6ym8OWJ5eV6+67Dsql/LaaT7qJBAt2rzfoa/5QBGBhxDix1dMt2kQKQ==", + "dev": true, + "requires": { + "prelude-ls": "^1.2.1", + "type-check": "~0.4.0" + } + }, + "lines-and-columns": { + "version": "1.2.4", + "resolved": "https://registry.npmjs.org/lines-and-columns/-/lines-and-columns-1.2.4.tgz", + "integrity": "sha512-7ylylesZQ/PV29jhEDl3Ufjo6ZX7gCqJr5F7PKrqc93v7fzSymt1BpwEU8nAUXs8qzzvqhbjhK5QZg6Mt/HkBg==", + "dev": true + }, + "load-json-file": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/load-json-file/-/load-json-file-1.1.0.tgz", + "integrity": "sha512-cy7ZdNRXdablkXYNI049pthVeXFurRyb9+hA/dZzerZ0pGTx42z+y+ssxBaVV2l70t1muq5IdKhn4UtcoGUY9A==", + "dev": true, + "requires": { + "graceful-fs": "^4.1.2", + "parse-json": "^2.2.0", + "pify": "^2.0.0", + "pinkie-promise": "^2.0.0", + "strip-bom": "^2.0.0" + }, + "dependencies": { + "parse-json": { + "version": "2.2.0", + "resolved": "https://registry.npmjs.org/parse-json/-/parse-json-2.2.0.tgz", + "integrity": "sha512-QR/GGaKCkhwk1ePQNYDRKYZ3mwU9ypsKhB0XyFnLQdomyEqk3e8wpW3V5Jp88zbxK4n5ST1nqo+g9juTpownhQ==", + "dev": true, + "requires": { + "error-ex": "^1.2.0" + } + }, + "pify": { + "version": "2.3.0", + "resolved": "https://registry.npmjs.org/pify/-/pify-2.3.0.tgz", + "integrity": "sha512-udgsAY+fTnvv7kI7aaxbqwWNb0AHiB0qBO89PZKPkoTmGOgdbrHDKD+0B2X4uTfJ/FT1R09r9gTsjUjNJotuog==", + "dev": true + }, + "strip-bom": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/strip-bom/-/strip-bom-2.0.0.tgz", + "integrity": "sha512-kwrX1y7czp1E69n2ajbG65mIo9dqvJ+8aBQXOGVxqwvNbsXdFM6Lq37dLAY3mknUwru8CfcCbfOLL/gMo+fi3g==", + "dev": true, + "requires": { + "is-utf8": "^0.2.0" + } + } + } + }, + "load-yaml-file": { + "version": "0.2.0", + "resolved": "https://registry.npmjs.org/load-yaml-file/-/load-yaml-file-0.2.0.tgz", + "integrity": "sha512-OfCBkGEw4nN6JLtgRidPX6QxjBQGQf72q3si2uvqyFEMbycSFFHwAZeXx6cJgFM9wmLrf9zBwCP3Ivqa+LLZPw==", + "dev": true, + "requires": { + "graceful-fs": "^4.1.5", + "js-yaml": "^3.13.0", + "pify": "^4.0.1", + "strip-bom": "^3.0.0" + } + }, + "locate-path": { + "version": "5.0.0", + "resolved": "https://registry.npmjs.org/locate-path/-/locate-path-5.0.0.tgz", + "integrity": "sha512-t7hw9pI+WvuwNJXwk5zVHpyhIqzg2qTlklJOf0mVxGSbe3Fp2VieZcduNYjaLDoy6p9uGpQEGWG87WpMKlNq8g==", + "dev": true, + "requires": { + "p-locate": "^4.1.0" + } + }, + "lodash": { + "version": "4.17.21", + "resolved": "https://registry.npmjs.org/lodash/-/lodash-4.17.21.tgz", + "integrity": "sha512-v2kDEe57lecTulaDIuNTPy3Ry4gLGJ6Z1O3vE1krgXZNrsQ+LFTGHVxVjcXPs17LhbZVGedAJv8XZ1tvj5FvSg==", + "dev": true + }, + "lodash.assign": { + "version": "4.2.0", + "resolved": "https://registry.npmjs.org/lodash.assign/-/lodash.assign-4.2.0.tgz", + "integrity": "sha512-hFuH8TY+Yji7Eja3mGiuAxBqLagejScbG8GbG0j6o9vzn0YL14My+ktnqtZgFTosKymC9/44wP6s7xyuLfnClw==", + "dev": true + }, + "lodash.flatten": { + "version": "4.4.0", + "resolved": "https://registry.npmjs.org/lodash.flatten/-/lodash.flatten-4.4.0.tgz", + "integrity": "sha512-C5N2Z3DgnnKr0LOpv/hKCgKdb7ZZwafIrsesve6lmzvZIRZRGaZ/l6Q8+2W7NaT+ZwO3fFlSCzCzrDCFdJfZ4g==", + "dev": true + }, + "lodash.merge": { + "version": "4.6.2", + "resolved": "https://registry.npmjs.org/lodash.merge/-/lodash.merge-4.6.2.tgz", + "integrity": "sha512-0KpjqXRVvrYyCsX1swR/XTK0va6VQkQM6MNo7PqW77ByjAhoARA8EfrP1N4+KlKj8YS0ZUCtRT/YUuhyYDujIQ==", + "dev": true + }, + "lodash.startcase": { + "version": "4.4.0", + "resolved": "https://registry.npmjs.org/lodash.startcase/-/lodash.startcase-4.4.0.tgz", + "integrity": "sha512-+WKqsK294HMSc2jEbNgpHpd0JfIBhp7rEV4aqXWqFr6AlXov+SlcgB1Fv01y2kGe3Gc8nMW7VA0SrGuSkRfIEg==", + "dev": true + }, + "lodash.truncate": { + "version": "4.4.2", + "resolved": "https://registry.npmjs.org/lodash.truncate/-/lodash.truncate-4.4.2.tgz", + "integrity": "sha512-jttmRe7bRse52OsWIMDLaXxWqRAmtIUccAQ3garviCqJjafXOfNMO0yMfNpdD6zbGaTU0P5Nz7e7gAT6cKmJRw==", + "dev": true + }, + "lodash.zip": { + "version": "4.2.0", + "resolved": "https://registry.npmjs.org/lodash.zip/-/lodash.zip-4.2.0.tgz", + "integrity": "sha512-C7IOaBBK/0gMORRBd8OETNx3kmOkgIWIPvyDpZSCTwUrpYmgZwJkjZeOD8ww4xbOUOs4/attY+pciKvadNfFbg==", + "dev": true + }, + "log-symbols": { + "version": "4.1.0", + "resolved": "https://registry.npmjs.org/log-symbols/-/log-symbols-4.1.0.tgz", + "integrity": "sha512-8XPvpAA8uyhfteu8pIvQxpJZ7SYYdpUivZpGy6sFsBuKRY/7rQGavedeB8aK+Zkyq6upMFVL/9AW6vOYzfRyLg==", + "dev": true, + "requires": { + "chalk": "^4.1.0", + "is-unicode-supported": "^0.1.0" + }, + "dependencies": { + "ansi-styles": { + "version": "4.3.0", + "resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-4.3.0.tgz", + "integrity": "sha512-zbB9rCJAT1rbjiVDb2hqKFHNYLxgtk8NURxZ3IZwD3F6NtxbXZQCnnSi1Lkx+IDohdPlFp222wVALIheZJQSEg==", + "dev": true, + "requires": { + "color-convert": "^2.0.1" + } + }, + "chalk": { + "version": "4.1.2", + "resolved": "https://registry.npmjs.org/chalk/-/chalk-4.1.2.tgz", + "integrity": "sha512-oKnbhFyRIXpUuez8iBMmyEa4nbj4IOQyuhc/wy9kY7/WVPcwIO9VA668Pu8RkO7+0G76SLROeyw9CpQ061i4mA==", + "dev": true, + "requires": { + "ansi-styles": "^4.1.0", + "supports-color": "^7.1.0" + } + }, + "color-convert": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/color-convert/-/color-convert-2.0.1.tgz", + "integrity": "sha512-RRECPsj7iu/xb5oKYcsFHSppFNnsj/52OVTRKb4zP5onXwVF3zVmmToNcOfGC+CRDpfK/U584fMg38ZHCaElKQ==", + "dev": true, + "requires": { + "color-name": "~1.1.4" + } + }, + "color-name": { + "version": "1.1.4", + "resolved": "https://registry.npmjs.org/color-name/-/color-name-1.1.4.tgz", + "integrity": "sha512-dOy+3AuW3a2wNbZHIuMZpTcgjGuLU/uBL/ubcZF9OXbDo8ff4O8yVp5Bf0efS8uEoYo5q4Fx7dY9OgQGXgAsQA==", + "dev": true + }, + "has-flag": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/has-flag/-/has-flag-4.0.0.tgz", + "integrity": "sha512-EykJT/Q1KjTWctppgIAgfSO0tKVuZUjhgMr17kqTumMl6Afv3EISleU7qZUzoXDFTAHTDC4NOoG/ZxU3EvlMPQ==", + "dev": true + }, + "supports-color": { + "version": "7.2.0", + "resolved": "https://registry.npmjs.org/supports-color/-/supports-color-7.2.0.tgz", + "integrity": "sha512-qpCAvRl9stuOHveKsn7HncJRvv501qIacKzQlO/+Lwxc9+0q2wLyv4Dfvt80/DPn2pqOBsJdDiogXGR9+OvwRw==", + "dev": true, + "requires": { + "has-flag": "^4.0.0" + } + } + } + }, + "loupe": { + "version": "2.3.6", + "resolved": "https://registry.npmjs.org/loupe/-/loupe-2.3.6.tgz", + "integrity": "sha512-RaPMZKiMy8/JruncMU5Bt6na1eftNoo++R4Y+N2FrxkDVTrGvcyzFTsaGif4QTeKESheMGegbhw6iUAq+5A8zA==", + "dev": true, + "requires": { + "get-func-name": "^2.0.0" + } + }, + "lower-case": { + "version": "1.1.4", + "resolved": "https://registry.npmjs.org/lower-case/-/lower-case-1.1.4.tgz", + "integrity": "sha512-2Fgx1Ycm599x+WGpIYwJOvsjmXFzTSc34IwDWALRA/8AopUKAVPwfJ+h5+f85BCp0PWmmJcWzEpxOpoXycMpdA==", + "dev": true + }, + "lower-case-first": { + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/lower-case-first/-/lower-case-first-1.0.2.tgz", + "integrity": "sha512-UuxaYakO7XeONbKrZf5FEgkantPf5DUqDayzP5VXZrtRPdH86s4kN47I8B3TW10S4QKiE3ziHNf3kRN//okHjA==", + "dev": true, + "requires": { + "lower-case": "^1.1.2" + } + }, + "lowercase-keys": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/lowercase-keys/-/lowercase-keys-3.0.0.tgz", + "integrity": "sha512-ozCC6gdQ+glXOQsveKD0YsDy8DSQFjDTz4zyzEHNV5+JP5D62LmfDZ6o1cycFx9ouG940M5dE8C8CTewdj2YWQ==", + "dev": true + }, + "lru_map": { + "version": "0.3.3", + "resolved": "https://registry.npmjs.org/lru_map/-/lru_map-0.3.3.tgz", + "integrity": "sha512-Pn9cox5CsMYngeDbmChANltQl+5pi6XmTrraMSzhPmMBbmgcxmqWry0U3PGapCU1yB4/LqCcom7qhHZiF/jGfQ==", + "dev": true + }, + "lru-cache": { + "version": "5.1.1", + "resolved": "https://registry.npmjs.org/lru-cache/-/lru-cache-5.1.1.tgz", + "integrity": "sha512-KpNARQA3Iwv+jTA0utUVVbrh+Jlrr1Fv0e56GGzAFOXN7dk/FviaDW8LHmK52DlcH4WP2n6gI8vN1aesBFgo9w==", + "dev": true, + "requires": { + "yallist": "^3.0.2" + } + }, + "map-obj": { + "version": "4.3.0", + "resolved": "https://registry.npmjs.org/map-obj/-/map-obj-4.3.0.tgz", + "integrity": "sha512-hdN1wVrZbb29eBGiGjJbeP8JbKjq1urkHJ/LIP/NY48MZ1QVXUsQBV1G1zvYFHn1XE06cwjBsOI2K3Ulnj1YXQ==", + "dev": true + }, + "markdown-table": { + "version": "1.1.3", + "resolved": "https://registry.npmjs.org/markdown-table/-/markdown-table-1.1.3.tgz", + "integrity": "sha512-1RUZVgQlpJSPWYbFSpmudq5nHY1doEIv89gBtF0s4gW1GF2XorxcA/70M5vq7rLv0a6mhOUccRsqkwhwLCIQ2Q==", + "dev": true + }, + "mcl-wasm": { + "version": "0.7.9", + "resolved": "https://registry.npmjs.org/mcl-wasm/-/mcl-wasm-0.7.9.tgz", + "integrity": "sha512-iJIUcQWA88IJB/5L15GnJVnSQJmf/YaxxV6zRavv83HILHaJQb6y0iFyDMdDO0gN8X37tdxmAOrH/P8B6RB8sQ==", + "dev": true + }, + "md5.js": { + "version": "1.3.5", + "resolved": "https://registry.npmjs.org/md5.js/-/md5.js-1.3.5.tgz", + "integrity": "sha512-xitP+WxNPcTTOgnTJcrhM0xvdPepipPSf3I8EIpGKeFLjt3PlJLIDG3u8EX53ZIubkb+5U2+3rELYpEhHhzdkg==", + "dev": true, + "requires": { + "hash-base": "^3.0.0", + "inherits": "^2.0.1", + "safe-buffer": "^5.1.2" + } + }, + "media-typer": { + "version": "0.3.0", + "resolved": "https://registry.npmjs.org/media-typer/-/media-typer-0.3.0.tgz", + "integrity": "sha512-dq+qelQ9akHpcOl/gUVRTxVIOkAJ1wR3QAvb4RsVjS8oVoFjDGTc679wJYmUmknUF5HwMLOgb5O+a3KxfWapPQ==", + "dev": true + }, + "memory-level": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/memory-level/-/memory-level-1.0.0.tgz", + "integrity": "sha512-UXzwewuWeHBz5krr7EvehKcmLFNoXxGcvuYhC41tRnkrTbJohtS7kVn9akmgirtRygg+f7Yjsfi8Uu5SGSQ4Og==", + "dev": true, + "requires": { + "abstract-level": "^1.0.0", + "functional-red-black-tree": "^1.0.1", + "module-error": "^1.0.1" + } + }, + "memorystream": { + "version": "0.3.1", + "resolved": "https://registry.npmjs.org/memorystream/-/memorystream-0.3.1.tgz", + "integrity": "sha512-S3UwM3yj5mtUSEfP41UZmt/0SCoVYUcU1rkXv+BQ5Ig8ndL4sPoJNBUJERafdPb5jjHJGuMgytgKvKIf58XNBw==", + "dev": true + }, + "meow": { + "version": "6.1.1", + "resolved": "https://registry.npmjs.org/meow/-/meow-6.1.1.tgz", + "integrity": "sha512-3YffViIt2QWgTy6Pale5QpopX/IvU3LPL03jOTqp6pGj3VjesdO/U8CuHMKpnQr4shCNCM5fd5XFFvIIl6JBHg==", + "dev": true, + "requires": { + "@types/minimist": "^1.2.0", + "camelcase-keys": "^6.2.2", + "decamelize-keys": "^1.1.0", + "hard-rejection": "^2.1.0", + "minimist-options": "^4.0.2", + "normalize-package-data": "^2.5.0", + "read-pkg-up": "^7.0.1", + "redent": "^3.0.0", + "trim-newlines": "^3.0.0", + "type-fest": "^0.13.1", + "yargs-parser": "^18.1.3" + }, + "dependencies": { + "type-fest": { + "version": "0.13.1", + "resolved": "https://registry.npmjs.org/type-fest/-/type-fest-0.13.1.tgz", + "integrity": "sha512-34R7HTnG0XIJcBSn5XhDd7nNFPRcXYRZrBB2O2jdKqYODldSzBAqzsWoZYYvduky73toYS/ESqxPvkDf/F0XMg==", + "dev": true + } + } + }, + "merge-descriptors": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/merge-descriptors/-/merge-descriptors-1.0.1.tgz", + "integrity": "sha512-cCi6g3/Zr1iqQi6ySbseM1Xvooa98N0w31jzUYrXPX2xqObmFGHJ0tQ5u74H3mVh7wLouTseZyYIq39g8cNp1w==", + "dev": true + }, + "merge2": { + "version": "1.4.1", + "resolved": "https://registry.npmjs.org/merge2/-/merge2-1.4.1.tgz", + "integrity": "sha512-8q7VEgMJW4J8tcfVPy8g09NcQwZdbwFEqhe/WZkoIzjn/3TGDwtOCYtXGxA3O8tPzpczCCDgv+P2P5y00ZJOOg==", + "dev": true + }, + "merkletreejs": { + "version": "0.2.32", + "resolved": "https://registry.npmjs.org/merkletreejs/-/merkletreejs-0.2.32.tgz", + "integrity": "sha512-TostQBiwYRIwSE5++jGmacu3ODcKAgqb0Y/pnIohXS7sWxh1gCkSptbmF1a43faehRDpcHf7J/kv0Ml2D/zblQ==", + "dev": true, + "requires": { + "bignumber.js": "^9.0.1", + "buffer-reverse": "^1.0.1", + "crypto-js": "^3.1.9-1", + "treeify": "^1.1.0", + "web3-utils": "^1.3.4" + }, + "dependencies": { + "bignumber.js": { + "version": "9.1.1", + "resolved": "https://registry.npmjs.org/bignumber.js/-/bignumber.js-9.1.1.tgz", + "integrity": "sha512-pHm4LsMJ6lzgNGVfZHjMoO8sdoRhOzOH4MLmY65Jg70bpxCKu5iOHNJyfF6OyvYw7t8Fpf35RuzUyqnQsj8Vig==", + "dev": true + } + } + }, + "methods": { + "version": "1.1.2", + "resolved": "https://registry.npmjs.org/methods/-/methods-1.1.2.tgz", + "integrity": "sha512-iclAHeNqNm68zFtnZ0e+1L2yUIdvzNoauKU4WBA3VvH/vPFieF7qfRlwUZU+DA9P9bPXIS90ulxoUoCH23sV2w==", + "dev": true + }, + "micromatch": { + "version": "4.0.5", + "resolved": "https://registry.npmjs.org/micromatch/-/micromatch-4.0.5.tgz", + "integrity": "sha512-DMy+ERcEW2q8Z2Po+WNXuw3c5YaUSFjAO5GsJqfEl7UjvtIuFKO6ZrKvcItdy98dwFI2N1tg3zNIdKaQT+aNdA==", + "dev": true, + "requires": { + "braces": "^3.0.2", + "picomatch": "^2.3.1" + } + }, + "mime": { + "version": "1.6.0", + "resolved": "https://registry.npmjs.org/mime/-/mime-1.6.0.tgz", + "integrity": "sha512-x0Vn8spI+wuJ1O6S7gnbaQg8Pxh4NNHb7KSINmEWKiPE4RKOplvijn+NkmYmmRgP68mc70j2EbeTFRsrswaQeg==", + "dev": true + }, + "mime-db": { + "version": "1.52.0", + "resolved": "https://registry.npmjs.org/mime-db/-/mime-db-1.52.0.tgz", + "integrity": "sha512-sPU4uV7dYlvtWJxwwxHD0PuihVNiE7TyAbQ5SWxDCB9mUYvOgroQOwYQQOKPJ8CIbE+1ETVlOoK1UC2nU3gYvg==", + "dev": true + }, + "mime-types": { + "version": "2.1.35", + "resolved": "https://registry.npmjs.org/mime-types/-/mime-types-2.1.35.tgz", + "integrity": "sha512-ZDY+bPm5zTTF+YpCrAU9nK0UgICYPT0QtT1NZWFv4s++TNkcgVaT0g6+4R2uI4MjQjzysHB1zxuWL50hzaeXiw==", + "dev": true, + "requires": { + "mime-db": "1.52.0" + } + }, + "mimic-response": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/mimic-response/-/mimic-response-1.0.1.tgz", + "integrity": "sha512-j5EctnkH7amfV/q5Hgmoal1g2QHFJRraOtmx0JpIqkxhBhI/lJSl1nMpQ45hVarwNETOoWEimndZ4QK0RHxuxQ==", + "dev": true + }, + "min-document": { + "version": "2.19.0", + "resolved": "https://registry.npmjs.org/min-document/-/min-document-2.19.0.tgz", + "integrity": "sha512-9Wy1B3m3f66bPPmU5hdA4DR4PB2OfDU/+GS3yAB7IQozE3tqXaVv2zOjgla7MEGSRv95+ILmOuvhLkOK6wJtCQ==", + "dev": true, + "requires": { + "dom-walk": "^0.1.0" + } + }, + "min-indent": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/min-indent/-/min-indent-1.0.1.tgz", + "integrity": "sha512-I9jwMn07Sy/IwOj3zVkVik2JTvgpaykDZEigL6Rx6N9LbMywwUSMtxET+7lVoDLLd3O3IXwJwvuuns8UB/HeAg==", + "dev": true + }, + "minimalistic-assert": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/minimalistic-assert/-/minimalistic-assert-1.0.1.tgz", + "integrity": "sha512-UtJcAD4yEaGtjPezWuO9wC4nwUnVH/8/Im3yEHQP4b67cXlD/Qr9hdITCU1xDbSEXg2XKNaP8jsReV7vQd00/A==", + "dev": true + }, + "minimalistic-crypto-utils": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/minimalistic-crypto-utils/-/minimalistic-crypto-utils-1.0.1.tgz", + "integrity": "sha512-JIYlbt6g8i5jKfJ3xz7rF0LXmv2TkDxBLUkiBeZ7bAx4GnnNMr8xFpGnOxn6GhTEHx3SjRrZEoU+j04prX1ktg==", + "dev": true + }, + "minimatch": { + "version": "3.1.2", + "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-3.1.2.tgz", + "integrity": "sha512-J7p63hRiAjw1NDEww1W7i37+ByIrOWO5XQQAzZ3VOcL0PNybwpfmV/N05zFAzwQ9USyEcX6t3UO+K5aqBQOIHw==", + "dev": true, + "requires": { + "brace-expansion": "^1.1.7" + } + }, + "minimist": { + "version": "1.2.8", + "resolved": "https://registry.npmjs.org/minimist/-/minimist-1.2.8.tgz", + "integrity": "sha512-2yyAR8qBkN3YuheJanUpWC5U3bb5osDywNB8RzDVlDwDHbocAJveqqj1u8+SVD7jkWT4yvsHCpWqqWqAxb0zCA==", + "dev": true + }, + "minimist-options": { + "version": "4.1.0", + "resolved": "https://registry.npmjs.org/minimist-options/-/minimist-options-4.1.0.tgz", + "integrity": "sha512-Q4r8ghd80yhO/0j1O3B2BjweX3fiHg9cdOwjJd2J76Q135c+NDxGCqdYKQ1SKBuFfgWbAUzBfvYjPUEeNgqN1A==", + "dev": true, + "requires": { + "arrify": "^1.0.1", + "is-plain-obj": "^1.1.0", + "kind-of": "^6.0.3" + } + }, + "minipass": { + "version": "2.9.0", + "resolved": "https://registry.npmjs.org/minipass/-/minipass-2.9.0.tgz", + "integrity": "sha512-wxfUjg9WebH+CUDX/CdbRlh5SmfZiy/hpkxaRI16Y9W56Pa75sWgd/rvFilSgrauD9NyFymP/+JFV3KwzIsJeg==", + "dev": true, + "requires": { + "safe-buffer": "^5.1.2", + "yallist": "^3.0.0" + } + }, + "minizlib": { + "version": "1.3.3", + "resolved": "https://registry.npmjs.org/minizlib/-/minizlib-1.3.3.tgz", + "integrity": "sha512-6ZYMOEnmVsdCeTJVE0W9ZD+pVnE8h9Hma/iOwwRDsdQoePpoX56/8B6z3P9VNwppJuBKNRuFDRNRqRWexT9G9Q==", + "dev": true, + "requires": { + "minipass": "^2.9.0" + } + }, + "mixme": { + "version": "0.5.9", + "resolved": "https://registry.npmjs.org/mixme/-/mixme-0.5.9.tgz", + "integrity": "sha512-VC5fg6ySUscaWUpI4gxCBTQMH2RdUpNrk+MsbpCYtIvf9SBJdiUey4qE7BXviJsJR4nDQxCZ+3yaYNW3guz/Pw==", + "dev": true + }, + "mkdirp": { + "version": "0.5.6", + "resolved": "https://registry.npmjs.org/mkdirp/-/mkdirp-0.5.6.tgz", + "integrity": "sha512-FP+p8RB8OWpF3YZBCrP5gtADmtXApB5AMLn+vdyA+PyxCjrCs00mjyUozssO33cwDeT3wNGdLxJ5M//YqtHAJw==", + "dev": true, + "requires": { + "minimist": "^1.2.6" + } + }, + "mkdirp-promise": { + "version": "5.0.1", + "resolved": "https://registry.npmjs.org/mkdirp-promise/-/mkdirp-promise-5.0.1.tgz", + "integrity": "sha512-Hepn5kb1lJPtVW84RFT40YG1OddBNTOVUZR2bzQUHc+Z03en8/3uX0+060JDhcEzyO08HmipsN9DcnFMxhIL9w==", + "dev": true, + "requires": { + "mkdirp": "*" + } + }, + "mnemonist": { + "version": "0.38.5", + "resolved": "https://registry.npmjs.org/mnemonist/-/mnemonist-0.38.5.tgz", + "integrity": "sha512-bZTFT5rrPKtPJxj8KSV0WkPyNxl72vQepqqVUAW2ARUpUSF2qXMB6jZj7hW5/k7C1rtpzqbD/IIbJwLXUjCHeg==", + "dev": true, + "requires": { + "obliterator": "^2.0.0" + } + }, + "mocha": { + "version": "10.2.0", + "resolved": "https://registry.npmjs.org/mocha/-/mocha-10.2.0.tgz", + "integrity": "sha512-IDY7fl/BecMwFHzoqF2sg/SHHANeBoMMXFlS9r0OXKDssYE1M5O43wUY/9BVPeIvfH2zmEbBfseqN9gBQZzXkg==", + "dev": true, + "requires": { + "ansi-colors": "4.1.1", + "browser-stdout": "1.3.1", + "chokidar": "3.5.3", + "debug": "4.3.4", + "diff": "5.0.0", + "escape-string-regexp": "4.0.0", + "find-up": "5.0.0", + "glob": "7.2.0", + "he": "1.2.0", + "js-yaml": "4.1.0", + "log-symbols": "4.1.0", + "minimatch": "5.0.1", + "ms": "2.1.3", + "nanoid": "3.3.3", + "serialize-javascript": "6.0.0", + "strip-json-comments": "3.1.1", + "supports-color": "8.1.1", + "workerpool": "6.2.1", + "yargs": "16.2.0", + "yargs-parser": "20.2.4", + "yargs-unparser": "2.0.0" + }, + "dependencies": { + "ansi-colors": { + "version": "4.1.1", + "resolved": "https://registry.npmjs.org/ansi-colors/-/ansi-colors-4.1.1.tgz", + "integrity": "sha512-JoX0apGbHaUJBNl6yF+p6JAFYZ666/hhCGKN5t9QFjbJQKUU/g8MNbFDbvfrgKXvI1QpZplPOnwIo99lX/AAmA==", + "dev": true + }, + "ansi-regex": { + "version": "5.0.1", + "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-5.0.1.tgz", + "integrity": "sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ==", + "dev": true + }, + "argparse": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/argparse/-/argparse-2.0.1.tgz", + "integrity": "sha512-8+9WqebbFzpX9OR+Wa6O29asIogeRMzcGtAINdpMHHyAg10f05aSFVBbcEqGf/PXw1EjAZ+q2/bEBg3DvurK3Q==", + "dev": true + }, + "cliui": { + "version": "7.0.4", + "resolved": "https://registry.npmjs.org/cliui/-/cliui-7.0.4.tgz", + "integrity": "sha512-OcRE68cOsVMXp1Yvonl/fzkQOyjLSu/8bhPDfQt0e0/Eb283TKP20Fs2MqoPsr9SwA595rRCA+QMzYc9nBP+JQ==", + "dev": true, + "requires": { + "string-width": "^4.2.0", + "strip-ansi": "^6.0.0", + "wrap-ansi": "^7.0.0" + } + }, + "escape-string-regexp": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/escape-string-regexp/-/escape-string-regexp-4.0.0.tgz", + "integrity": "sha512-TtpcNJ3XAzx3Gq8sWRzJaVajRs0uVxA2YAkdb1jm2YkPz4G6egUFAyA3n5vtEIZefPk5Wa4UXbKuS5fKkJWdgA==", + "dev": true + }, + "find-up": { + "version": "5.0.0", + "resolved": "https://registry.npmjs.org/find-up/-/find-up-5.0.0.tgz", + "integrity": "sha512-78/PXT1wlLLDgTzDs7sjq9hzz0vXD+zn+7wypEe4fXQxCmdmqfGsEPQxmiCSQI3ajFV91bVSsvNtrJRiW6nGng==", + "dev": true, + "requires": { + "locate-path": "^6.0.0", + "path-exists": "^4.0.0" + } + }, + "glob": { + "version": "7.2.0", + "resolved": "https://registry.npmjs.org/glob/-/glob-7.2.0.tgz", + "integrity": "sha512-lmLf6gtyrPq8tTjSmrO94wBeQbFR3HbLHbuyD69wuyQkImp2hWqMGB47OX65FBkPffO641IP9jWa1z4ivqG26Q==", + "dev": true, + "requires": { + "fs.realpath": "^1.0.0", + "inflight": "^1.0.4", + "inherits": "2", + "minimatch": "^3.0.4", + "once": "^1.3.0", + "path-is-absolute": "^1.0.0" + }, + "dependencies": { + "minimatch": { + "version": "3.1.2", + "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-3.1.2.tgz", + "integrity": "sha512-J7p63hRiAjw1NDEww1W7i37+ByIrOWO5XQQAzZ3VOcL0PNybwpfmV/N05zFAzwQ9USyEcX6t3UO+K5aqBQOIHw==", + "dev": true, + "requires": { + "brace-expansion": "^1.1.7" + } + } + } + }, + "has-flag": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/has-flag/-/has-flag-4.0.0.tgz", + "integrity": "sha512-EykJT/Q1KjTWctppgIAgfSO0tKVuZUjhgMr17kqTumMl6Afv3EISleU7qZUzoXDFTAHTDC4NOoG/ZxU3EvlMPQ==", + "dev": true + }, + "is-fullwidth-code-point": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/is-fullwidth-code-point/-/is-fullwidth-code-point-3.0.0.tgz", + "integrity": "sha512-zymm5+u+sCsSWyD9qNaejV3DFvhCKclKdizYaJUuHA83RLjb7nSuGnddCHGv0hk+KY7BMAlsWeK4Ueg6EV6XQg==", + "dev": true + }, + "js-yaml": { + "version": "4.1.0", + "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-4.1.0.tgz", + "integrity": "sha512-wpxZs9NoxZaJESJGIZTyDEaYpl0FKSA+FB9aJiyemKhMwkxQg63h4T1KJgUGHpTqPDNRcmmYLugrRjJlBtWvRA==", + "dev": true, + "requires": { + "argparse": "^2.0.1" + } + }, + "locate-path": { + "version": "6.0.0", + "resolved": "https://registry.npmjs.org/locate-path/-/locate-path-6.0.0.tgz", + "integrity": "sha512-iPZK6eYjbxRu3uB4/WZ3EsEIMJFMqAoopl3R+zuq0UjcAm/MO6KCweDgPfP3elTztoKP3KtnVHxTn2NHBSDVUw==", + "dev": true, + "requires": { + "p-locate": "^5.0.0" + } + }, + "minimatch": { + "version": "5.0.1", + "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-5.0.1.tgz", + "integrity": "sha512-nLDxIFRyhDblz3qMuq+SoRZED4+miJ/G+tdDrjkkkRnjAsBexeGpgjLEQ0blJy7rHhR2b93rhQY4SvyWu9v03g==", + "dev": true, + "requires": { + "brace-expansion": "^2.0.1" + }, + "dependencies": { + "brace-expansion": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-2.0.1.tgz", + "integrity": "sha512-XnAIvQ8eM+kC6aULx6wuQiwVsnzsi9d3WxzV3FpWTGA19F621kwdbsAcFKXgKUHZWsy+mY6iL1sHTxWEFCytDA==", + "dev": true, + "requires": { + "balanced-match": "^1.0.0" + } + } + } + }, + "ms": { + "version": "2.1.3", + "resolved": "https://registry.npmjs.org/ms/-/ms-2.1.3.tgz", + "integrity": "sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==", + "dev": true + }, + "p-locate": { + "version": "5.0.0", + "resolved": "https://registry.npmjs.org/p-locate/-/p-locate-5.0.0.tgz", + "integrity": "sha512-LaNjtRWUBY++zB5nE/NwcaoMylSPk+S+ZHNB1TzdbMJMny6dynpAGt7X/tl/QYq3TIeE6nxHppbo2LGymrG5Pw==", + "dev": true, + "requires": { + "p-limit": "^3.0.2" + } + }, + "string-width": { + "version": "4.2.3", + "resolved": "https://registry.npmjs.org/string-width/-/string-width-4.2.3.tgz", + "integrity": "sha512-wKyQRQpjJ0sIp62ErSZdGsjMJWsap5oRNihHhu6G7JVO/9jIB6UyevL+tXuOqrng8j/cxKTWyWUwvSTriiZz/g==", + "dev": true, + "requires": { + "emoji-regex": "^8.0.0", + "is-fullwidth-code-point": "^3.0.0", + "strip-ansi": "^6.0.1" + } + }, + "strip-ansi": { + "version": "6.0.1", + "resolved": "https://registry.npmjs.org/strip-ansi/-/strip-ansi-6.0.1.tgz", + "integrity": "sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A==", + "dev": true, + "requires": { + "ansi-regex": "^5.0.1" + } + }, + "supports-color": { + "version": "8.1.1", + "resolved": "https://registry.npmjs.org/supports-color/-/supports-color-8.1.1.tgz", + "integrity": "sha512-MpUEN2OodtUzxvKQl72cUF7RQ5EiHsGvSsVG0ia9c5RbWGL2CI4C7EpPS8UTBIplnlzZiNuV56w+FuNxy3ty2Q==", + "dev": true, + "requires": { + "has-flag": "^4.0.0" + } + }, + "yargs": { + "version": "16.2.0", + "resolved": "https://registry.npmjs.org/yargs/-/yargs-16.2.0.tgz", + "integrity": "sha512-D1mvvtDG0L5ft/jGWkLpG1+m0eQxOfaBvTNELraWj22wSVUMWxZUvYgJYcKh6jGGIkJFhH4IZPQhR4TKpc8mBw==", + "dev": true, + "requires": { + "cliui": "^7.0.2", + "escalade": "^3.1.1", + "get-caller-file": "^2.0.5", + "require-directory": "^2.1.1", + "string-width": "^4.2.0", + "y18n": "^5.0.5", + "yargs-parser": "^20.2.2" + } + }, + "yargs-parser": { + "version": "20.2.4", + "resolved": "https://registry.npmjs.org/yargs-parser/-/yargs-parser-20.2.4.tgz", + "integrity": "sha512-WOkpgNhPTlE73h4VFAFsOnomJVaovO8VqLDzy5saChRBFQFBoMYirowyW+Q9HB4HFF4Z7VZTiG3iSzJJA29yRA==", + "dev": true + } + } + }, + "mock-fs": { + "version": "4.14.0", + "resolved": "https://registry.npmjs.org/mock-fs/-/mock-fs-4.14.0.tgz", + "integrity": "sha512-qYvlv/exQ4+svI3UOvPUpLDF0OMX5euvUH0Ny4N5QyRyhNdgAgUrVH3iUINSzEPLvx0kbo/Bp28GJKIqvE7URw==", + "dev": true + }, + "module-error": { + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/module-error/-/module-error-1.0.2.tgz", + "integrity": "sha512-0yuvsqSCv8LbaOKhnsQ/T5JhyFlCYLPXK3U2sgV10zoKQwzs/MyfuQUOZQ1V/6OCOJsK/TRgNVrPuPDqtdMFtA==", + "dev": true + }, + "ms": { + "version": "2.1.2", + "resolved": "https://registry.npmjs.org/ms/-/ms-2.1.2.tgz", + "integrity": "sha512-sGkPx+VjMtmA6MX27oA4FBFELFCZZ4S4XqeGOXCv68tT+jb3vk/RyaKWP0PTKyWtmLSM0b+adUTEvbs1PEaH2w==", + "dev": true + }, + "multibase": { + "version": "0.6.1", + "resolved": "https://registry.npmjs.org/multibase/-/multibase-0.6.1.tgz", + "integrity": "sha512-pFfAwyTjbbQgNc3G7D48JkJxWtoJoBMaR4xQUOuB8RnCgRqaYmWNFeJTTvrJ2w51bjLq2zTby6Rqj9TQ9elSUw==", + "dev": true, + "requires": { + "base-x": "^3.0.8", + "buffer": "^5.5.0" + } + }, + "multicodec": { + "version": "0.5.7", + "resolved": "https://registry.npmjs.org/multicodec/-/multicodec-0.5.7.tgz", + "integrity": "sha512-PscoRxm3f+88fAtELwUnZxGDkduE2HD9Q6GHUOywQLjOGT/HAdhjLDYNZ1e7VR0s0TP0EwZ16LNUTFpoBGivOA==", + "dev": true, + "requires": { + "varint": "^5.0.0" + } + }, + "multihashes": { + "version": "0.4.21", + "resolved": "https://registry.npmjs.org/multihashes/-/multihashes-0.4.21.tgz", + "integrity": "sha512-uVSvmeCWf36pU2nB4/1kzYZjsXD9vofZKpgudqkceYY5g2aZZXJ5r9lxuzoRLl1OAp28XljXsEJ/X/85ZsKmKw==", + "dev": true, + "requires": { + "buffer": "^5.5.0", + "multibase": "^0.7.0", + "varint": "^5.0.0" + }, + "dependencies": { + "multibase": { + "version": "0.7.0", + "resolved": "https://registry.npmjs.org/multibase/-/multibase-0.7.0.tgz", + "integrity": "sha512-TW8q03O0f6PNFTQDvh3xxH03c8CjGaaYrjkl9UQPG6rz53TQzzxJVCIWVjzcbN/Q5Y53Zd0IBQBMVktVgNx4Fg==", + "dev": true, + "requires": { + "base-x": "^3.0.8", + "buffer": "^5.5.0" + } + } + } + }, + "nano-base32": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/nano-base32/-/nano-base32-1.0.1.tgz", + "integrity": "sha512-sxEtoTqAPdjWVGv71Q17koMFGsOMSiHsIFEvzOM7cNp8BXB4AnEwmDabm5dorusJf/v1z7QxaZYxUorU9RKaAw==", + "dev": true + }, + "nano-json-stream-parser": { + "version": "0.1.2", + "resolved": "https://registry.npmjs.org/nano-json-stream-parser/-/nano-json-stream-parser-0.1.2.tgz", + "integrity": "sha512-9MqxMH/BSJC7dnLsEMPyfN5Dvoo49IsPFYMcHw3Bcfc2kN0lpHRBSzlMSVx4HGyJ7s9B31CyBTVehWJoQ8Ctew==", + "dev": true + }, + "nanoid": { + "version": "3.3.3", + "resolved": "https://registry.npmjs.org/nanoid/-/nanoid-3.3.3.tgz", + "integrity": "sha512-p1sjXuopFs0xg+fPASzQ28agW1oHD7xDsd9Xkf3T15H3c/cifrFHVwrh74PdoklAPi+i7MdRsE47vm2r6JoB+w==", + "dev": true + }, + "napi-macros": { + "version": "2.2.2", + "resolved": "https://registry.npmjs.org/napi-macros/-/napi-macros-2.2.2.tgz", + "integrity": "sha512-hmEVtAGYzVQpCKdbQea4skABsdXW4RUh5t5mJ2zzqowJS2OyXZTU1KhDVFhx+NlWZ4ap9mqR9TcDO3LTTttd+g==", + "dev": true + }, + "natural-compare": { + "version": "1.4.0", + "resolved": "https://registry.npmjs.org/natural-compare/-/natural-compare-1.4.0.tgz", + "integrity": "sha512-OWND8ei3VtNC9h7V60qff3SVobHr996CTwgxubgyQYEpg290h9J0buyECNNJexkFm5sOajh5G116RYA1c8ZMSw==", + "dev": true + }, + "negotiator": { + "version": "0.6.3", + "resolved": "https://registry.npmjs.org/negotiator/-/negotiator-0.6.3.tgz", + "integrity": "sha512-+EUsqGPLsM+j/zdChZjsnX51g4XrHFOIXwfnCVPGlQk/k5giakcKsuxCObBRu6DSm9opw/O6slWbJdghQM4bBg==", + "dev": true + }, + "neo-async": { + "version": "2.6.2", + "resolved": "https://registry.npmjs.org/neo-async/-/neo-async-2.6.2.tgz", + "integrity": "sha512-Yd3UES5mWCSqR+qNT93S3UoYUkqAZ9lLg8a7g9rimsWmYGK8cVToA4/sF3RrshdyV3sAGMXVUmpMYOw+dLpOuw==", + "dev": true + }, + "next-tick": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/next-tick/-/next-tick-1.1.0.tgz", + "integrity": "sha512-CXdUiJembsNjuToQvxayPZF9Vqht7hewsvy2sOWafLvi2awflj9mOC6bHIg50orX8IJvWKY9wYQ/zB2kogPslQ==", + "dev": true + }, + "no-case": { + "version": "2.3.2", + "resolved": "https://registry.npmjs.org/no-case/-/no-case-2.3.2.tgz", + "integrity": "sha512-rmTZ9kz+f3rCvK2TD1Ue/oZlns7OGoIWP4fc3llxxRXlOkHKoWPPWJOfFYpITabSow43QJbRIoHQXtt10VldyQ==", + "dev": true, + "requires": { + "lower-case": "^1.1.1" + } + }, + "node-addon-api": { + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/node-addon-api/-/node-addon-api-2.0.2.tgz", + "integrity": "sha512-Ntyt4AIXyaLIuMHF6IOoTakB3K+RWxwtsHNRxllEoA6vPwP9o4866g6YWDLUdnucilZhmkxiHwHr11gAENw+QA==", + "dev": true + }, + "node-emoji": { + "version": "1.11.0", + "resolved": "https://registry.npmjs.org/node-emoji/-/node-emoji-1.11.0.tgz", + "integrity": "sha512-wo2DpQkQp7Sjm2A0cq+sN7EHKO6Sl0ctXeBdFZrL9T9+UywORbufTcTZxom8YqpLQt/FqNMUkOpkZrJVYSKD3A==", + "dev": true, + "requires": { + "lodash": "^4.17.21" + } + }, + "node-environment-flags": { + "version": "1.0.6", + "resolved": "https://registry.npmjs.org/node-environment-flags/-/node-environment-flags-1.0.6.tgz", + "integrity": "sha512-5Evy2epuL+6TM0lCQGpFIj6KwiEsGh1SrHUhTbNX+sLbBtjidPZFAnVK9y5yU1+h//RitLbRHTIMyxQPtxMdHw==", + "dev": true, + "requires": { + "object.getownpropertydescriptors": "^2.0.3", + "semver": "^5.7.0" + }, + "dependencies": { + "semver": { + "version": "5.7.1", + "resolved": "https://registry.npmjs.org/semver/-/semver-5.7.1.tgz", + "integrity": "sha512-sauaDf/PZdVgrLTNYHRtpXa1iRiKcaebiKQ1BJdpQlWH2lCvexQdX55snPFyK7QzpudqbCI0qXFfOasHdyNDGQ==", + "dev": true + } + } + }, + "node-fetch": { + "version": "2.6.12", + "resolved": "https://registry.npmjs.org/node-fetch/-/node-fetch-2.6.12.tgz", + "integrity": "sha512-C/fGU2E8ToujUivIO0H+tpQ6HWo4eEmchoPIoXtxCrVghxdKq+QOHqEZW7tuP3KlV3bC8FRMO5nMCC7Zm1VP6g==", + "dev": true, + "requires": { + "whatwg-url": "^5.0.0" + } + }, + "node-gyp-build": { + "version": "4.6.0", + "resolved": "https://registry.npmjs.org/node-gyp-build/-/node-gyp-build-4.6.0.tgz", + "integrity": "sha512-NTZVKn9IylLwUzaKjkas1e4u2DLNcV4rdYagA4PWdPwW87Bi7z+BznyKSRwS/761tV/lzCGXplWsiaMjLqP2zQ==", + "dev": true + }, + "node-interval-tree": { + "version": "2.1.2", + "resolved": "https://registry.npmjs.org/node-interval-tree/-/node-interval-tree-2.1.2.tgz", + "integrity": "sha512-bJ9zMDuNGzVQg1xv0bCPzyEDxHgbrx7/xGj6CDokvizZZmastPsOh0JJLuY8wA5q2SfX1TLNMk7XNV8WxbGxzA==", + "dev": true, + "requires": { + "shallowequal": "^1.1.0" + } + }, + "nofilter": { + "version": "3.1.0", + "resolved": "https://registry.npmjs.org/nofilter/-/nofilter-3.1.0.tgz", + "integrity": "sha512-l2NNj07e9afPnhAhvgVrCD/oy2Ai1yfLpuo3EpiO1jFTsB4sFz6oIfAfSZyQzVpkZQ9xS8ZS5g1jCBgq4Hwo0g==", + "dev": true + }, + "nopt": { + "version": "3.0.6", + "resolved": "https://registry.npmjs.org/nopt/-/nopt-3.0.6.tgz", + "integrity": "sha512-4GUt3kSEYmk4ITxzB/b9vaIDfUVWN/Ml1Fwl11IlnIG2iaJ9O6WXZ9SrYM9NLI8OCBieN2Y8SWC2oJV0RQ7qYg==", + "dev": true, + "requires": { + "abbrev": "1" + } + }, + "normalize-package-data": { + "version": "2.5.0", + "resolved": "https://registry.npmjs.org/normalize-package-data/-/normalize-package-data-2.5.0.tgz", + "integrity": "sha512-/5CMN3T0R4XTj4DcGaexo+roZSdSFW/0AOOTROrjxzCG1wrWXEsGbRKevjlIL+ZDE4sZlJr5ED4YW0yqmkK+eA==", + "dev": true, + "requires": { + "hosted-git-info": "^2.1.4", + "resolve": "^1.10.0", + "semver": "2 || 3 || 4 || 5", + "validate-npm-package-license": "^3.0.1" + }, + "dependencies": { + "semver": { + "version": "5.7.1", + "resolved": "https://registry.npmjs.org/semver/-/semver-5.7.1.tgz", + "integrity": "sha512-sauaDf/PZdVgrLTNYHRtpXa1iRiKcaebiKQ1BJdpQlWH2lCvexQdX55snPFyK7QzpudqbCI0qXFfOasHdyNDGQ==", + "dev": true + } + } + }, + "normalize-path": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/normalize-path/-/normalize-path-3.0.0.tgz", + "integrity": "sha512-6eZs5Ls3WtCisHWp9S2GUy8dqkpGi4BVSz3GaqiE6ezub0512ESztXUwUB6C6IKbQkY2Pnb/mD4WYojCRwcwLA==", + "dev": true + }, + "normalize-url": { + "version": "6.1.0", + "resolved": "https://registry.npmjs.org/normalize-url/-/normalize-url-6.1.0.tgz", + "integrity": "sha512-DlL+XwOy3NxAQ8xuC0okPgK46iuVNAK01YN7RueYBqqFeGsBjV9XmCAzAdgt+667bCl5kPh9EqKKDwnaPG1I7A==", + "dev": true + }, + "nth-check": { + "version": "2.1.1", + "resolved": "https://registry.npmjs.org/nth-check/-/nth-check-2.1.1.tgz", + "integrity": "sha512-lqjrjmaOoAnWfMmBPL+XNnynZh2+swxiX3WUE0s4yEHI6m+AwrK2UZOimIRl3X/4QctVqS8AiZjFqyOGrMXb/w==", + "dev": true, + "requires": { + "boolbase": "^1.0.0" + } + }, + "number-is-nan": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/number-is-nan/-/number-is-nan-1.0.1.tgz", + "integrity": "sha512-4jbtZXNAsfZbAHiiqjLPBiCl16dES1zI4Hpzzxw61Tk+loF+sBDBKx1ICKKKwIqQ7M0mFn1TmkN7euSncWgHiQ==", + "dev": true + }, + "number-to-bn": { + "version": "1.7.0", + "resolved": "https://registry.npmjs.org/number-to-bn/-/number-to-bn-1.7.0.tgz", + "integrity": "sha512-wsJ9gfSz1/s4ZsJN01lyonwuxA1tml6X1yBDnfpMglypcBRFZZkus26EdPSlqS5GJfYddVZa22p3VNb3z5m5Ig==", + "dev": true, + "requires": { + "bn.js": "4.11.6", + "strip-hex-prefix": "1.0.0" + }, + "dependencies": { + "bn.js": { + "version": "4.11.6", + "resolved": "https://registry.npmjs.org/bn.js/-/bn.js-4.11.6.tgz", + "integrity": "sha512-XWwnNNFCuuSQ0m3r3C4LE3EiORltHd9M05pq6FOlVeiophzRbMo50Sbz1ehl8K3Z+jw9+vmgnXefY1hz8X+2wA==", + "dev": true + } + } + }, + "oauth-sign": { + "version": "0.9.0", + "resolved": "https://registry.npmjs.org/oauth-sign/-/oauth-sign-0.9.0.tgz", + "integrity": "sha512-fexhUFFPTGV8ybAtSIGbV6gOkSv8UtRbDBnAyLQw4QPKkgNlsH2ByPGtMUqdWkos6YCRmAqViwgZrJc/mRDzZQ==", + "dev": true + }, + "object-assign": { + "version": "4.1.1", + "resolved": "https://registry.npmjs.org/object-assign/-/object-assign-4.1.1.tgz", + "integrity": "sha512-rJgTQnkUnH1sFw8yT6VSU3zD3sWmu6sZhIseY8VX+GRu3P6F7Fu+JNDoXfklElbLJSnc3FUQHVe4cU5hj+BcUg==", + "dev": true + }, + "object-inspect": { + "version": "1.12.3", + "resolved": "https://registry.npmjs.org/object-inspect/-/object-inspect-1.12.3.tgz", + "integrity": "sha512-geUvdk7c+eizMNUDkRpW1wJwgfOiOeHbxBR/hLXK1aT6zmVSO0jsQcs7fj6MGw89jC/cjGfLcNOrtMYtGqm81g==", + "dev": true + }, + "object-keys": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/object-keys/-/object-keys-1.1.1.tgz", + "integrity": "sha512-NuAESUOUMrlIXOfHKzD6bpPu3tYt3xvjNdRIQ+FeT0lNb4K8WR70CaDxhuNguS2XG+GjkyMwOzsN5ZktImfhLA==", + "dev": true + }, + "object.assign": { + "version": "4.1.4", + "resolved": "https://registry.npmjs.org/object.assign/-/object.assign-4.1.4.tgz", + "integrity": "sha512-1mxKf0e58bvyjSCtKYY4sRe9itRk3PJpquJOjeIkz885CczcI4IvJJDLPS72oowuSh+pBxUFROpX+TU++hxhZQ==", + "dev": true, + "requires": { + "call-bind": "^1.0.2", + "define-properties": "^1.1.4", + "has-symbols": "^1.0.3", + "object-keys": "^1.1.1" + } + }, + "object.getownpropertydescriptors": { + "version": "2.1.6", + "resolved": "https://registry.npmjs.org/object.getownpropertydescriptors/-/object.getownpropertydescriptors-2.1.6.tgz", + "integrity": "sha512-lq+61g26E/BgHv0ZTFgRvi7NMEPuAxLkFU7rukXjc/AlwH4Am5xXVnIXy3un1bg/JPbXHrixRkK1itUzzPiIjQ==", + "dev": true, + "requires": { + "array.prototype.reduce": "^1.0.5", + "call-bind": "^1.0.2", + "define-properties": "^1.2.0", + "es-abstract": "^1.21.2", + "safe-array-concat": "^1.0.0" + } + }, + "obliterator": { + "version": "2.0.4", + "resolved": "https://registry.npmjs.org/obliterator/-/obliterator-2.0.4.tgz", + "integrity": "sha512-lgHwxlxV1qIg1Eap7LgIeoBWIMFibOjbrYPIPJZcI1mmGAI2m3lNYpK12Y+GBdPQ0U1hRwSord7GIaawz962qQ==", + "dev": true + }, + "oboe": { + "version": "2.1.5", + "resolved": "https://registry.npmjs.org/oboe/-/oboe-2.1.5.tgz", + "integrity": "sha512-zRFWiF+FoicxEs3jNI/WYUrVEgA7DeET/InK0XQuudGHRg8iIob3cNPrJTKaz4004uaA9Pbe+Dwa8iluhjLZWA==", + "dev": true, + "requires": { + "http-https": "^1.0.0" + } + }, + "on-finished": { + "version": "2.4.1", + "resolved": "https://registry.npmjs.org/on-finished/-/on-finished-2.4.1.tgz", + "integrity": "sha512-oVlzkg3ENAhCk2zdv7IJwd/QUD4z2RxRwpkcGY8psCVcCYZNq4wYnVWALHM+brtuJjePWiYF/ClmuDr8Ch5+kg==", + "dev": true, + "requires": { + "ee-first": "1.1.1" + } + }, + "once": { + "version": "1.4.0", + "resolved": "https://registry.npmjs.org/once/-/once-1.4.0.tgz", + "integrity": "sha512-lNaJgI+2Q5URQBkccEKHTQOPaXdUxnZZElQTZY0MFUAuaEqe1E+Nyvgdz/aIyNi6Z9MzO5dv1H8n58/GELp3+w==", + "dev": true, + "requires": { + "wrappy": "1" + } + }, + "optionator": { + "version": "0.9.3", + "resolved": "https://registry.npmjs.org/optionator/-/optionator-0.9.3.tgz", + "integrity": "sha512-JjCoypp+jKn1ttEFExxhetCKeJt9zhAgAve5FXHixTvFDW/5aEktX9bufBKLRRMdU7bNtpLfcGu94B3cdEJgjg==", + "dev": true, + "requires": { + "@aashutoshrathi/word-wrap": "^1.2.3", + "deep-is": "^0.1.3", + "fast-levenshtein": "^2.0.6", + "levn": "^0.4.1", + "prelude-ls": "^1.2.1", + "type-check": "^0.4.0" + } + }, + "os-locale": { + "version": "1.4.0", + "resolved": "https://registry.npmjs.org/os-locale/-/os-locale-1.4.0.tgz", + "integrity": "sha512-PRT7ZORmwu2MEFt4/fv3Q+mEfN4zetKxufQrkShY2oGvUms9r8otu5HfdyIFHkYXjO7laNsoVGmM2MANfuTA8g==", + "dev": true, + "requires": { + "lcid": "^1.0.0" + } + }, + "os-tmpdir": { + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/os-tmpdir/-/os-tmpdir-1.0.2.tgz", + "integrity": "sha512-D2FR03Vir7FIu45XBY20mTb+/ZSWB00sjU9jdQXt83gDrI4Ztz5Fs7/yy74g2N5SVQY4xY1qDr4rNddwYRVX0g==", + "dev": true + }, + "outdent": { + "version": "0.5.0", + "resolved": "https://registry.npmjs.org/outdent/-/outdent-0.5.0.tgz", + "integrity": "sha512-/jHxFIzoMXdqPzTaCpFzAAWhpkSjZPF4Vsn6jAfNpmbH/ymsmd7Qc6VE9BGn0L6YMj6uwpQLxCECpus4ukKS9Q==", + "dev": true + }, + "p-cancelable": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/p-cancelable/-/p-cancelable-3.0.0.tgz", + "integrity": "sha512-mlVgR3PGuzlo0MmTdk4cXqXWlwQDLnONTAg6sm62XkMJEiRxN3GL3SffkYvqwonbkJBcrI7Uvv5Zh9yjvn2iUw==", + "dev": true + }, + "p-filter": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/p-filter/-/p-filter-2.1.0.tgz", + "integrity": "sha512-ZBxxZ5sL2HghephhpGAQdoskxplTwr7ICaehZwLIlfL6acuVgZPm8yBNuRAFBGEqtD/hmUeq9eqLg2ys9Xr/yw==", + "dev": true, + "requires": { + "p-map": "^2.0.0" + }, + "dependencies": { + "p-map": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/p-map/-/p-map-2.1.0.tgz", + "integrity": "sha512-y3b8Kpd8OAN444hxfBbFfj1FY/RjtTd8tzYwhUqNYXx0fXx2iX4maP4Qr6qhIKbQXI02wTLAda4fYUbDagTUFw==", + "dev": true + } + } + }, + "p-limit": { + "version": "3.1.0", + "resolved": "https://registry.npmjs.org/p-limit/-/p-limit-3.1.0.tgz", + "integrity": "sha512-TYOanM3wGwNGsZN2cVTYPArw454xnXj5qmWF1bEoAc4+cU/ol7GVh7odevjp1FNHduHc3KZMcFduxU5Xc6uJRQ==", + "dev": true, + "requires": { + "yocto-queue": "^0.1.0" + } + }, + "p-locate": { + "version": "4.1.0", + "resolved": "https://registry.npmjs.org/p-locate/-/p-locate-4.1.0.tgz", + "integrity": "sha512-R79ZZ/0wAxKGu3oYMlz8jy/kbhsNrS7SKZ7PxEHBgJ5+F2mtFW2fK2cOtBh1cHYkQsbzFV7I+EoRKe6Yt0oK7A==", + "dev": true, + "requires": { + "p-limit": "^2.2.0" + }, + "dependencies": { + "p-limit": { + "version": "2.3.0", + "resolved": "https://registry.npmjs.org/p-limit/-/p-limit-2.3.0.tgz", + "integrity": "sha512-//88mFWSJx8lxCzwdAABTJL2MyWB12+eIY7MDL2SqLmAkeKU9qxRvWuSyTjm3FUmpBEMuFfckAIqEaVGUDxb6w==", + "dev": true, + "requires": { + "p-try": "^2.0.0" + } + } + } + }, + "p-map": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/p-map/-/p-map-4.0.0.tgz", + "integrity": "sha512-/bjOqmgETBYB5BoEeGVea8dmvHb2m9GLy1E9W43yeyfP6QQCZGFNa+XRceJEuDB6zqr+gKpIAmlLebMpykw/MQ==", + "dev": true, + "requires": { + "aggregate-error": "^3.0.0" + } + }, + "p-try": { + "version": "2.2.0", + "resolved": "https://registry.npmjs.org/p-try/-/p-try-2.2.0.tgz", + "integrity": "sha512-R4nPAVTAU0B9D35/Gk3uJf/7XYbQcyohSKdvAxIRSNghFl4e71hVoGnBNQz9cWaXxO2I10KTC+3jMdvvoKw6dQ==", + "dev": true + }, + "pako": { + "version": "1.0.11", + "resolved": "https://registry.npmjs.org/pako/-/pako-1.0.11.tgz", + "integrity": "sha512-4hLB8Py4zZce5s4yd9XzopqwVv/yGNhV1Bl8NTmCq1763HeK2+EwVTv+leGeL13Dnh2wfbqowVPXCIO0z4taYw==", + "dev": true + }, + "param-case": { + "version": "2.1.1", + "resolved": "https://registry.npmjs.org/param-case/-/param-case-2.1.1.tgz", + "integrity": "sha512-eQE845L6ot89sk2N8liD8HAuH4ca6Vvr7VWAWwt7+kvvG5aBcPmmphQ68JsEG2qa9n1TykS2DLeMt363AAH8/w==", + "dev": true, + "requires": { + "no-case": "^2.2.0" + } + }, + "parent-module": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/parent-module/-/parent-module-1.0.1.tgz", + "integrity": "sha512-GQ2EWRpQV8/o+Aw8YqtfZZPfNRWZYkbidE9k5rpl/hC3vtHHBfGm2Ifi6qWV+coDGkrUKZAxE3Lot5kcsRlh+g==", + "dev": true, + "requires": { + "callsites": "^3.0.0" + } + }, + "parse-cache-control": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/parse-cache-control/-/parse-cache-control-1.0.1.tgz", + "integrity": "sha512-60zvsJReQPX5/QP0Kzfd/VrpjScIQ7SHBW6bFCYfEP+fp0Eppr1SHhIO5nd1PjZtvclzSzES9D/p5nFJurwfWg==", + "dev": true + }, + "parse-headers": { + "version": "2.0.5", + "resolved": "https://registry.npmjs.org/parse-headers/-/parse-headers-2.0.5.tgz", + "integrity": "sha512-ft3iAoLOB/MlwbNXgzy43SWGP6sQki2jQvAyBg/zDFAgr9bfNWZIUj42Kw2eJIl8kEi4PbgE6U1Zau/HwI75HA==", + "dev": true + }, + "parse-json": { + "version": "5.2.0", + "resolved": "https://registry.npmjs.org/parse-json/-/parse-json-5.2.0.tgz", + "integrity": "sha512-ayCKvm/phCGxOkYRSCM82iDwct8/EonSEgCSxWxD7ve6jHggsFl4fZVQBPRNgQoKiuV/odhFrGzQXZwbifC8Rg==", + "dev": true, + "requires": { + "@babel/code-frame": "^7.0.0", + "error-ex": "^1.3.1", + "json-parse-even-better-errors": "^2.3.0", + "lines-and-columns": "^1.1.6" + } + }, + "parse5": { + "version": "7.1.2", + "resolved": "https://registry.npmjs.org/parse5/-/parse5-7.1.2.tgz", + "integrity": "sha512-Czj1WaSVpaoj0wbhMzLmWD69anp2WH7FXMB9n1Sy8/ZFF9jolSQVMu1Ij5WIyGmcBmhk7EOndpO4mIpihVqAXw==", + "dev": true, + "requires": { + "entities": "^4.4.0" + } + }, + "parse5-htmlparser2-tree-adapter": { + "version": "7.0.0", + "resolved": "https://registry.npmjs.org/parse5-htmlparser2-tree-adapter/-/parse5-htmlparser2-tree-adapter-7.0.0.tgz", + "integrity": "sha512-B77tOZrqqfUfnVcOrUvfdLbz4pu4RopLD/4vmu3HUPswwTA8OH0EMW9BlWR2B0RCoiZRAHEUu7IxeP1Pd1UU+g==", + "dev": true, + "requires": { + "domhandler": "^5.0.2", + "parse5": "^7.0.0" + } + }, + "parseurl": { + "version": "1.3.3", + "resolved": "https://registry.npmjs.org/parseurl/-/parseurl-1.3.3.tgz", + "integrity": "sha512-CiyeOxFT/JZyN5m0z9PfXw4SCBJ6Sygz1Dpl0wqjlhDEGGBP1GnsUVEL0p63hoG1fcj3fHynXi9NYO4nWOL+qQ==", + "dev": true + }, + "pascal-case": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/pascal-case/-/pascal-case-2.0.1.tgz", + "integrity": "sha512-qjS4s8rBOJa2Xm0jmxXiyh1+OFf6ekCWOvUaRgAQSktzlTbMotS0nmG9gyYAybCWBcuP4fsBeRCKNwGBnMe2OQ==", + "dev": true, + "requires": { + "camel-case": "^3.0.0", + "upper-case-first": "^1.1.0" + } + }, + "path-case": { + "version": "2.1.1", + "resolved": "https://registry.npmjs.org/path-case/-/path-case-2.1.1.tgz", + "integrity": "sha512-Ou0N05MioItesaLr9q8TtHVWmJ6fxWdqKB2RohFmNWVyJ+2zeKIeDNWAN6B/Pe7wpzWChhZX6nONYmOnMeJQ/Q==", + "dev": true, + "requires": { + "no-case": "^2.2.0" + } + }, + "path-exists": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/path-exists/-/path-exists-4.0.0.tgz", + "integrity": "sha512-ak9Qy5Q7jYb2Wwcey5Fpvg2KoAc/ZIhLSLOSBmRmygPsGwkVVt0fZa0qrtMz+m6tJTAHfZQ8FnmB4MG4LWy7/w==", + "dev": true + }, + "path-is-absolute": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/path-is-absolute/-/path-is-absolute-1.0.1.tgz", + "integrity": "sha512-AVbw3UJ2e9bq64vSaS9Am0fje1Pa8pbGqTTsmXfaIiMpnr5DlDhfJOuLj9Sf95ZPVDAUerDfEk88MPmPe7UCQg==", + "dev": true + }, + "path-key": { + "version": "3.1.1", + "resolved": "https://registry.npmjs.org/path-key/-/path-key-3.1.1.tgz", + "integrity": "sha512-ojmeN0qd+y0jszEtoY48r0Peq5dwMEkIlCOu6Q5f41lfkswXuKtYrhgoTpLnyIcHm24Uhqx+5Tqm2InSwLhE6Q==", + "dev": true + }, + "path-parse": { + "version": "1.0.7", + "resolved": "https://registry.npmjs.org/path-parse/-/path-parse-1.0.7.tgz", + "integrity": "sha512-LDJzPVEEEPR+y48z93A0Ed0yXb8pAByGWo/k5YYdYgpY2/2EsOsksJrq7lOHxryrVOn1ejG6oAp8ahvOIQD8sw==", + "dev": true + }, + "path-to-regexp": { + "version": "0.1.7", + "resolved": "https://registry.npmjs.org/path-to-regexp/-/path-to-regexp-0.1.7.tgz", + "integrity": "sha512-5DFkuoqlv1uYQKxy8omFBeJPQcdoE07Kv2sferDCrAq1ohOU+MSDswDIbnx3YAM60qIOnYa53wBhXW0EbMonrQ==", + "dev": true + }, + "path-type": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/path-type/-/path-type-4.0.0.tgz", + "integrity": "sha512-gDKb8aZMDeD/tZWs9P6+q0J9Mwkdl6xMV8TjnGP3qJVJ06bdMgkbBlLU8IdfOsIsFz2BW1rNVT3XuNEl8zPAvw==", + "dev": true + }, + "pathval": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/pathval/-/pathval-1.1.1.tgz", + "integrity": "sha512-Dp6zGqpTdETdR63lehJYPeIOqpiNBNtc7BpWSLrOje7UaIsE5aY92r/AunQA7rsXvet3lrJ3JnZX29UPTKXyKQ==", + "dev": true + }, + "pbkdf2": { + "version": "3.1.2", + "resolved": "https://registry.npmjs.org/pbkdf2/-/pbkdf2-3.1.2.tgz", + "integrity": "sha512-iuh7L6jA7JEGu2WxDwtQP1ddOpaJNC4KlDEFfdQajSGgGPNi4OyDc2R7QnbY2bR9QjBVGwgvTdNJZoE7RaxUMA==", + "dev": true, + "requires": { + "create-hash": "^1.1.2", + "create-hmac": "^1.1.4", + "ripemd160": "^2.0.1", + "safe-buffer": "^5.0.1", + "sha.js": "^2.4.8" + } + }, + "performance-now": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/performance-now/-/performance-now-2.1.0.tgz", + "integrity": "sha512-7EAHlyLHI56VEIdK57uwHdHKIaAGbnXPiw0yWbarQZOKaKpvUIgW0jWRVLiatnM+XXlSwsanIBH/hzGMJulMow==", + "dev": true + }, + "picomatch": { + "version": "2.3.1", + "resolved": "https://registry.npmjs.org/picomatch/-/picomatch-2.3.1.tgz", + "integrity": "sha512-JU3teHTNjmE2VCGFzuY8EXzCDVwEqB2a8fsIvwaStHhAWJEeVd1o1QD80CU6+ZdEXXSLbSsuLwJjkCBWqRQUVA==", + "dev": true + }, + "pify": { + "version": "4.0.1", + "resolved": "https://registry.npmjs.org/pify/-/pify-4.0.1.tgz", + "integrity": "sha512-uB80kBFb/tfd68bVleG9T5GGsGPjJrLAUpR5PZIrhBnIaRTQRjqdJSsIKkOP6OAIFbj7GOrcudc5pNjZ+geV2g==", + "dev": true + }, + "pinkie": { + "version": "2.0.4", + "resolved": "https://registry.npmjs.org/pinkie/-/pinkie-2.0.4.tgz", + "integrity": "sha512-MnUuEycAemtSaeFSjXKW/aroV7akBbY+Sv+RkyqFjgAe73F+MR0TBWKBRDkmfWq/HiFmdavfZ1G7h4SPZXaCSg==", + "dev": true + }, + "pinkie-promise": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/pinkie-promise/-/pinkie-promise-2.0.1.tgz", + "integrity": "sha512-0Gni6D4UcLTbv9c57DfxDGdr41XfgUjqWZu492f0cIGr16zDU06BWP/RAEvOuo7CQ0CNjHaLlM59YJJFm3NWlw==", + "dev": true, + "requires": { + "pinkie": "^2.0.0" + } + }, + "pkg-dir": { + "version": "4.2.0", + "resolved": "https://registry.npmjs.org/pkg-dir/-/pkg-dir-4.2.0.tgz", + "integrity": "sha512-HRDzbaKjC+AOWVXxAU/x54COGeIv9eb+6CkDSQoNTt4XyWoIJvuPsXizxu/Fr23EiekbtZwmh1IcIG/l/a10GQ==", + "dev": true, + "requires": { + "find-up": "^4.0.0" + } + }, + "pluralize": { + "version": "8.0.0", + "resolved": "https://registry.npmjs.org/pluralize/-/pluralize-8.0.0.tgz", + "integrity": "sha512-Nc3IT5yHzflTfbjgqWcCPpo7DaKy4FnpB0l/zCAW0Tc7jxAiuqSxHasntB3D7887LSrA93kDJ9IXovxJYxyLCA==", + "dev": true + }, + "preferred-pm": { + "version": "3.0.3", + "resolved": "https://registry.npmjs.org/preferred-pm/-/preferred-pm-3.0.3.tgz", + "integrity": "sha512-+wZgbxNES/KlJs9q40F/1sfOd/j7f1O9JaHcW5Dsn3aUUOZg3L2bjpVUcKV2jvtElYfoTuQiNeMfQJ4kwUAhCQ==", + "dev": true, + "requires": { + "find-up": "^5.0.0", + "find-yarn-workspace-root2": "1.2.16", + "path-exists": "^4.0.0", + "which-pm": "2.0.0" + }, + "dependencies": { + "find-up": { + "version": "5.0.0", + "resolved": "https://registry.npmjs.org/find-up/-/find-up-5.0.0.tgz", + "integrity": "sha512-78/PXT1wlLLDgTzDs7sjq9hzz0vXD+zn+7wypEe4fXQxCmdmqfGsEPQxmiCSQI3ajFV91bVSsvNtrJRiW6nGng==", + "dev": true, + "requires": { + "locate-path": "^6.0.0", + "path-exists": "^4.0.0" + } + }, + "locate-path": { + "version": "6.0.0", + "resolved": "https://registry.npmjs.org/locate-path/-/locate-path-6.0.0.tgz", + "integrity": "sha512-iPZK6eYjbxRu3uB4/WZ3EsEIMJFMqAoopl3R+zuq0UjcAm/MO6KCweDgPfP3elTztoKP3KtnVHxTn2NHBSDVUw==", + "dev": true, + "requires": { + "p-locate": "^5.0.0" + } + }, + "p-locate": { + "version": "5.0.0", + "resolved": "https://registry.npmjs.org/p-locate/-/p-locate-5.0.0.tgz", + "integrity": "sha512-LaNjtRWUBY++zB5nE/NwcaoMylSPk+S+ZHNB1TzdbMJMny6dynpAGt7X/tl/QYq3TIeE6nxHppbo2LGymrG5Pw==", + "dev": true, + "requires": { + "p-limit": "^3.0.2" + } + } + } + }, + "prelude-ls": { + "version": "1.2.1", + "resolved": "https://registry.npmjs.org/prelude-ls/-/prelude-ls-1.2.1.tgz", + "integrity": "sha512-vkcDPrRZo1QZLbn5RLGPpg/WmIQ65qoWWhcGKf/b5eplkkarX0m9z8ppCat4mlOqUsWpyNuYgO3VRyrYHSzX5g==", + "dev": true + }, + "prettier": { + "version": "3.0.3", + "resolved": "https://registry.npmjs.org/prettier/-/prettier-3.0.3.tgz", + "integrity": "sha512-L/4pUDMxcNa8R/EthV08Zt42WBO4h1rarVtK0K+QJG0X187OLo7l699jWw0GKuwzkPQ//jMFA/8Xm6Fh3J/DAg==", + "dev": true + }, + "prettier-plugin-solidity": { + "version": "1.1.3", + "resolved": "https://registry.npmjs.org/prettier-plugin-solidity/-/prettier-plugin-solidity-1.1.3.tgz", + "integrity": "sha512-fQ9yucPi2sBbA2U2Xjh6m4isUTJ7S7QLc/XDDsktqqxYfTwdYKJ0EnnywXHwCGAaYbQNK+HIYPL1OemxuMsgeg==", + "dev": true, + "requires": { + "@solidity-parser/parser": "^0.16.0", + "semver": "^7.3.8", + "solidity-comments-extractor": "^0.0.7" + }, + "dependencies": { + "@solidity-parser/parser": { + "version": "0.16.0", + "resolved": "https://registry.npmjs.org/@solidity-parser/parser/-/parser-0.16.0.tgz", + "integrity": "sha512-ESipEcHyRHg4Np4SqBCfcXwyxxna1DgFVz69bgpLV8vzl/NP1DtcKsJ4dJZXWQhY/Z4J2LeKBiOkOVZn9ct33Q==", + "dev": true, + "requires": { + "antlr4ts": "^0.5.0-alpha.4" + } + } + } + }, + "process": { + "version": "0.11.10", + "resolved": "https://registry.npmjs.org/process/-/process-0.11.10.tgz", + "integrity": "sha512-cdGef/drWFoydD1JsMzuFf8100nZl+GT+yacc2bEced5f9Rjk4z+WtFUTBu9PhOi9j/jfmBPu0mMEY4wIdAF8A==", + "dev": true + }, + "process-nextick-args": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/process-nextick-args/-/process-nextick-args-2.0.1.tgz", + "integrity": "sha512-3ouUOpQhtgrbOa17J7+uxOTpITYWaGP7/AhoR3+A+/1e9skrzelGi/dXzEYyvbxubEF6Wn2ypscTKiKJFFn1ag==", + "dev": true + }, + "promise": { + "version": "8.3.0", + "resolved": "https://registry.npmjs.org/promise/-/promise-8.3.0.tgz", + "integrity": "sha512-rZPNPKTOYVNEEKFaq1HqTgOwZD+4/YHS5ukLzQCypkj+OkYx7iv0mA91lJlpPPZ8vMau3IIGj5Qlwrx+8iiSmg==", + "dev": true, + "requires": { + "asap": "~2.0.6" + } + }, + "proper-lockfile": { + "version": "4.1.2", + "resolved": "https://registry.npmjs.org/proper-lockfile/-/proper-lockfile-4.1.2.tgz", + "integrity": "sha512-TjNPblN4BwAWMXU8s9AEz4JmQxnD1NNL7bNOY/AKUzyamc379FWASUhc/K1pL2noVb+XmZKLL68cjzLsiOAMaA==", + "dev": true, + "requires": { + "graceful-fs": "^4.2.4", + "retry": "^0.12.0", + "signal-exit": "^3.0.2" + } + }, + "proxy-addr": { + "version": "2.0.7", + "resolved": "https://registry.npmjs.org/proxy-addr/-/proxy-addr-2.0.7.tgz", + "integrity": "sha512-llQsMLSUDUPT44jdrU/O37qlnifitDP+ZwrmmZcoSKyLKvtZxpyV0n2/bD/N4tBAAZ/gJEdZU7KMraoK1+XYAg==", + "dev": true, + "requires": { + "forwarded": "0.2.0", + "ipaddr.js": "1.9.1" + } + }, + "pseudomap": { + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/pseudomap/-/pseudomap-1.0.2.tgz", + "integrity": "sha512-b/YwNhb8lk1Zz2+bXXpS/LK9OisiZZ1SNsSLxN1x2OXVEhW2Ckr/7mWE5vrC1ZTiJlD9g19jWszTmJsB+oEpFQ==", + "dev": true + }, + "psl": { + "version": "1.9.0", + "resolved": "https://registry.npmjs.org/psl/-/psl-1.9.0.tgz", + "integrity": "sha512-E/ZsdU4HLs/68gYzgGTkMicWTLPdAftJLfJFlLUAAKZGkStNU72sZjT66SnMDVOfOWY/YAoiD7Jxa9iHvngcag==", + "dev": true + }, + "pump": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/pump/-/pump-3.0.0.tgz", + "integrity": "sha512-LwZy+p3SFs1Pytd/jYct4wpv49HiYCqd9Rlc5ZVdk0V+8Yzv6jR5Blk3TRmPL1ft69TxP0IMZGJ+WPFU2BFhww==", + "dev": true, + "requires": { + "end-of-stream": "^1.1.0", + "once": "^1.3.1" + } + }, + "punycode": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/punycode/-/punycode-2.1.0.tgz", + "integrity": "sha512-Yxz2kRwT90aPiWEMHVYnEf4+rhwF1tBmmZ4KepCP+Wkium9JxtWnUm1nqGwpiAHr/tnTSeHqr3wb++jgSkXjhA==", + "dev": true + }, + "pure-rand": { + "version": "5.0.5", + "resolved": "https://registry.npmjs.org/pure-rand/-/pure-rand-5.0.5.tgz", + "integrity": "sha512-BwQpbqxSCBJVpamI6ydzcKqyFmnd5msMWUGvzXLm1aXvusbbgkbOto/EUPM00hjveJEaJtdbhUjKSzWRhQVkaw==", + "dev": true + }, + "qs": { + "version": "6.5.3", + "resolved": "https://registry.npmjs.org/qs/-/qs-6.5.3.tgz", + "integrity": "sha512-qxXIEh4pCGfHICj1mAJQ2/2XVZkjCDTcEgfoSQxc/fYivUZxTkk7L3bDBJSoNrEzXI17oUO5Dp07ktqE5KzczA==", + "dev": true + }, + "query-string": { + "version": "5.1.1", + "resolved": "https://registry.npmjs.org/query-string/-/query-string-5.1.1.tgz", + "integrity": "sha512-gjWOsm2SoGlgLEdAGt7a6slVOk9mGiXmPFMqrEhLQ68rhQuBnpfs3+EmlvqKyxnCo9/PPlF+9MtY02S1aFg+Jw==", + "dev": true, + "requires": { + "decode-uri-component": "^0.2.0", + "object-assign": "^4.1.0", + "strict-uri-encode": "^1.0.0" + } + }, + "queue-microtask": { + "version": "1.2.3", + "resolved": "https://registry.npmjs.org/queue-microtask/-/queue-microtask-1.2.3.tgz", + "integrity": "sha512-NuaNSa6flKT5JaSYQzJok04JzTL1CA6aGhv5rfLW3PgqA+M2ChpZQnAC8h8i4ZFkBS8X5RqkDBHA7r4hej3K9A==", + "dev": true + }, + "quick-lru": { + "version": "4.0.1", + "resolved": "https://registry.npmjs.org/quick-lru/-/quick-lru-4.0.1.tgz", + "integrity": "sha512-ARhCpm70fzdcvNQfPoy49IaanKkTlRWF2JMzqhcJbhSFRZv7nPTvZJdcY7301IPmvW+/p0RgIWnQDLJxifsQ7g==", + "dev": true + }, + "randombytes": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/randombytes/-/randombytes-2.1.0.tgz", + "integrity": "sha512-vYl3iOX+4CKUWuxGi9Ukhie6fsqXqS9FE2Zaic4tNFD2N2QQaXOMFbuKK4QmDHC0JO6B1Zp41J0LpT0oR68amQ==", + "dev": true, + "requires": { + "safe-buffer": "^5.1.0" + } + }, + "range-parser": { + "version": "1.2.1", + "resolved": "https://registry.npmjs.org/range-parser/-/range-parser-1.2.1.tgz", + "integrity": "sha512-Hrgsx+orqoygnmhFbKaHE6c296J+HTAQXoxEF6gNupROmmGJRoyzfG3ccAveqCBrwr/2yxQ5BVd/GTl5agOwSg==", + "dev": true + }, + "raw-body": { + "version": "2.5.2", + "resolved": "https://registry.npmjs.org/raw-body/-/raw-body-2.5.2.tgz", + "integrity": "sha512-8zGqypfENjCIqGhgXToC8aB2r7YrBX+AQAfIPs/Mlk+BtPTztOvTS01NRW/3Eh60J+a48lt8qsCzirQ6loCVfA==", + "dev": true, + "requires": { + "bytes": "3.1.2", + "http-errors": "2.0.0", + "iconv-lite": "0.4.24", + "unpipe": "1.0.0" + } + }, + "read-pkg": { + "version": "5.2.0", + "resolved": "https://registry.npmjs.org/read-pkg/-/read-pkg-5.2.0.tgz", + "integrity": "sha512-Ug69mNOpfvKDAc2Q8DRpMjjzdtrnv9HcSMX+4VsZxD1aZ6ZzrIE7rlzXBtWTyhULSMKg076AW6WR5iZpD0JiOg==", + "dev": true, + "requires": { + "@types/normalize-package-data": "^2.4.0", + "normalize-package-data": "^2.5.0", + "parse-json": "^5.0.0", + "type-fest": "^0.6.0" + }, + "dependencies": { + "type-fest": { + "version": "0.6.0", + "resolved": "https://registry.npmjs.org/type-fest/-/type-fest-0.6.0.tgz", + "integrity": "sha512-q+MB8nYR1KDLrgr4G5yemftpMC7/QLqVndBmEEdqzmNj5dcFOO4Oo8qlwZE3ULT3+Zim1F8Kq4cBnikNhlCMlg==", + "dev": true + } + } + }, + "read-pkg-up": { + "version": "7.0.1", + "resolved": "https://registry.npmjs.org/read-pkg-up/-/read-pkg-up-7.0.1.tgz", + "integrity": "sha512-zK0TB7Xd6JpCLmlLmufqykGE+/TlOePD6qKClNW7hHDKFh/J7/7gCWGR7joEQEW1bKq3a3yUZSObOoWLFQ4ohg==", + "dev": true, + "requires": { + "find-up": "^4.1.0", + "read-pkg": "^5.2.0", + "type-fest": "^0.8.1" + }, + "dependencies": { + "type-fest": { + "version": "0.8.1", + "resolved": "https://registry.npmjs.org/type-fest/-/type-fest-0.8.1.tgz", + "integrity": "sha512-4dbzIzqvjtgiM5rw1k5rEHtBANKmdudhGyBEajN01fEyhaAIhsoKNy6y7+IN93IfpFtwY9iqi7kD+xwKhQsNJA==", + "dev": true + } + } + }, + "read-yaml-file": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/read-yaml-file/-/read-yaml-file-1.1.0.tgz", + "integrity": "sha512-VIMnQi/Z4HT2Fxuwg5KrY174U1VdUIASQVWXXyqtNRtxSr9IYkn1rsI6Tb6HsrHCmB7gVpNwX6JxPTHcH6IoTA==", + "dev": true, + "requires": { + "graceful-fs": "^4.1.5", + "js-yaml": "^3.6.1", + "pify": "^4.0.1", + "strip-bom": "^3.0.0" + } + }, + "readable-stream": { + "version": "3.6.2", + "resolved": "https://registry.npmjs.org/readable-stream/-/readable-stream-3.6.2.tgz", + "integrity": "sha512-9u/sniCrY3D5WdsERHzHE4G2YCXqoG5FTHUiCC4SIbr6XcLZBY05ya9EKjYek9O5xOAwjGq+1JdGBAS7Q9ScoA==", + "dev": true, + "requires": { + "inherits": "^2.0.3", + "string_decoder": "^1.1.1", + "util-deprecate": "^1.0.1" + } + }, + "readdirp": { + "version": "3.6.0", + "resolved": "https://registry.npmjs.org/readdirp/-/readdirp-3.6.0.tgz", + "integrity": "sha512-hOS089on8RduqdbhvQ5Z37A0ESjsqz6qnRcffsMU3495FuTdqSm+7bhJ29JvIOsBDEEnan5DPu9t3To9VRlMzA==", + "dev": true, + "requires": { + "picomatch": "^2.2.1" + } + }, + "rechoir": { + "version": "0.6.2", + "resolved": "https://registry.npmjs.org/rechoir/-/rechoir-0.6.2.tgz", + "integrity": "sha512-HFM8rkZ+i3zrV+4LQjwQ0W+ez98pApMGM3HUrN04j3CqzPOzl9nmP15Y8YXNm8QHGv/eacOVEjqhmWpkRV0NAw==", + "dev": true, + "requires": { + "resolve": "^1.1.6" + } + }, + "recursive-readdir": { + "version": "2.2.3", + "resolved": "https://registry.npmjs.org/recursive-readdir/-/recursive-readdir-2.2.3.tgz", + "integrity": "sha512-8HrF5ZsXk5FAH9dgsx3BlUer73nIhuj+9OrQwEbLTPOBzGkL1lsFCR01am+v+0m2Cmbs1nP12hLDl5FA7EszKA==", + "dev": true, + "requires": { + "minimatch": "^3.0.5" + } + }, + "redent": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/redent/-/redent-3.0.0.tgz", + "integrity": "sha512-6tDA8g98We0zd0GvVeMT9arEOnTw9qM03L9cJXaCjrip1OO764RDBLBfrB4cwzNGDj5OA5ioymC9GkizgWJDUg==", + "dev": true, + "requires": { + "indent-string": "^4.0.0", + "strip-indent": "^3.0.0" + }, + "dependencies": { + "strip-indent": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/strip-indent/-/strip-indent-3.0.0.tgz", + "integrity": "sha512-laJTa3Jb+VQpaC6DseHhF7dXVqHTfJPCRDaEbid/drOhgitgYku/letMUqOXFoWV0zIIUbjpdH2t+tYj4bQMRQ==", + "dev": true, + "requires": { + "min-indent": "^1.0.0" + } + } + } + }, + "regenerator-runtime": { + "version": "0.13.11", + "resolved": "https://registry.npmjs.org/regenerator-runtime/-/regenerator-runtime-0.13.11.tgz", + "integrity": "sha512-kY1AZVr2Ra+t+piVaJ4gxaFaReZVH40AKNo7UCX6W+dEwBo/2oZJzqfuN1qLq1oL45o56cPaTXELwrTh8Fpggg==", + "dev": true + }, + "regexp.prototype.flags": { + "version": "1.5.0", + "resolved": "https://registry.npmjs.org/regexp.prototype.flags/-/regexp.prototype.flags-1.5.0.tgz", + "integrity": "sha512-0SutC3pNudRKgquxGoRGIz946MZVHqbNfPjBdxeOhBrdgDKlRoXmYLQN9xRbrR09ZXWeGAdPuif7egofn6v5LA==", + "dev": true, + "requires": { + "call-bind": "^1.0.2", + "define-properties": "^1.2.0", + "functions-have-names": "^1.2.3" + } + }, + "req-cwd": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/req-cwd/-/req-cwd-2.0.0.tgz", + "integrity": "sha512-ueoIoLo1OfB6b05COxAA9UpeoscNpYyM+BqYlA7H6LVF4hKGPXQQSSaD2YmvDVJMkk4UDpAHIeU1zG53IqjvlQ==", + "dev": true, + "requires": { + "req-from": "^2.0.0" + } + }, + "req-from": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/req-from/-/req-from-2.0.0.tgz", + "integrity": "sha512-LzTfEVDVQHBRfjOUMgNBA+V6DWsSnoeKzf42J7l0xa/B4jyPOuuF5MlNSmomLNGemWTnV2TIdjSSLnEn95fOQA==", + "dev": true, + "requires": { + "resolve-from": "^3.0.0" + }, + "dependencies": { + "resolve-from": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/resolve-from/-/resolve-from-3.0.0.tgz", + "integrity": "sha512-GnlH6vxLymXJNMBo7XP1fJIzBFbdYt49CuTwmB/6N53t+kMPRMFKz783LlQ4tv28XoQfMWinAJX6WCGf2IlaIw==", + "dev": true + } + } + }, + "request": { + "version": "2.88.2", + "resolved": "https://registry.npmjs.org/request/-/request-2.88.2.tgz", + "integrity": "sha512-MsvtOrfG9ZcrOwAW+Qi+F6HbD0CWXEh9ou77uOb7FM2WPhwT7smM833PzanhJLsgXjN89Ir6V2PczXNnMpwKhw==", + "dev": true, + "requires": { + "aws-sign2": "~0.7.0", + "aws4": "^1.8.0", + "caseless": "~0.12.0", + "combined-stream": "~1.0.6", + "extend": "~3.0.2", + "forever-agent": "~0.6.1", + "form-data": "~2.3.2", + "har-validator": "~5.1.3", + "http-signature": "~1.2.0", + "is-typedarray": "~1.0.0", + "isstream": "~0.1.2", + "json-stringify-safe": "~5.0.1", + "mime-types": "~2.1.19", + "oauth-sign": "~0.9.0", + "performance-now": "^2.1.0", + "qs": "~6.5.2", + "safe-buffer": "^5.1.2", + "tough-cookie": "~2.5.0", + "tunnel-agent": "^0.6.0", + "uuid": "^3.3.2" + }, + "dependencies": { + "uuid": { + "version": "3.4.0", + "resolved": "https://registry.npmjs.org/uuid/-/uuid-3.4.0.tgz", + "integrity": "sha512-HjSDRw6gZE5JMggctHBcjVak08+KEVhSIiDzFnT9S9aegmp85S/bReBVTb4QTFaRNptJ9kuYaNhnbNEOkbKb/A==", + "dev": true + } + } + }, + "request-promise-core": { + "version": "1.1.4", + "resolved": "https://registry.npmjs.org/request-promise-core/-/request-promise-core-1.1.4.tgz", + "integrity": "sha512-TTbAfBBRdWD7aNNOoVOBH4pN/KigV6LyapYNNlAPA8JwbovRti1E88m3sYAwsLi5ryhPKsE9APwnjFTgdUjTpw==", + "dev": true, + "requires": { + "lodash": "^4.17.19" + } + }, + "request-promise-native": { + "version": "1.0.9", + "resolved": "https://registry.npmjs.org/request-promise-native/-/request-promise-native-1.0.9.tgz", + "integrity": "sha512-wcW+sIUiWnKgNY0dqCpOZkUbF/I+YPi+f09JZIDa39Ec+q82CpSYniDp+ISgTTbKmnpJWASeJBPZmoxH84wt3g==", + "dev": true, + "requires": { + "request-promise-core": "1.1.4", + "stealthy-require": "^1.1.1", + "tough-cookie": "^2.3.3" + } + }, + "require-directory": { + "version": "2.1.1", + "resolved": "https://registry.npmjs.org/require-directory/-/require-directory-2.1.1.tgz", + "integrity": "sha512-fGxEI7+wsG9xrvdjsrlmL22OMTTiHRwAMroiEeMgq8gzoLC/PQr7RsRDSTLUg/bZAZtF+TVIkHc6/4RIKrui+Q==", + "dev": true + }, + "require-from-string": { + "version": "1.2.1", + "resolved": "https://registry.npmjs.org/require-from-string/-/require-from-string-1.2.1.tgz", + "integrity": "sha512-H7AkJWMobeskkttHyhTVtS0fxpFLjxhbfMa6Bk3wimP7sdPRGL3EyCg3sAQenFfAe+xQ+oAc85Nmtvq0ROM83Q==", + "dev": true + }, + "require-main-filename": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/require-main-filename/-/require-main-filename-2.0.0.tgz", + "integrity": "sha512-NKN5kMDylKuldxYLSUfrbo5Tuzh4hd+2E8NPPX02mZtn1VuREQToYe/ZdlJy+J3uCpfaiGF05e7B8W0iXbQHmg==", + "dev": true + }, + "resolve": { + "version": "1.17.0", + "resolved": "https://registry.npmjs.org/resolve/-/resolve-1.17.0.tgz", + "integrity": "sha512-ic+7JYiV8Vi2yzQGFWOkiZD5Z9z7O2Zhm9XMaTxdJExKasieFCr+yXZ/WmXsckHiKl12ar0y6XiXDx3m4RHn1w==", + "dev": true, + "requires": { + "path-parse": "^1.0.6" + } + }, + "resolve-alpn": { + "version": "1.2.1", + "resolved": "https://registry.npmjs.org/resolve-alpn/-/resolve-alpn-1.2.1.tgz", + "integrity": "sha512-0a1F4l73/ZFZOakJnQ3FvkJ2+gSTQWz/r2KE5OdDY0TxPm5h4GkqkWWfM47T7HsbnOtcJVEF4epCVy6u7Q3K+g==", + "dev": true + }, + "resolve-from": { + "version": "5.0.0", + "resolved": "https://registry.npmjs.org/resolve-from/-/resolve-from-5.0.0.tgz", + "integrity": "sha512-qYg9KP24dD5qka9J47d0aVky0N+b4fTU89LN9iDnjB5waksiC49rvMB0PrUJQGoTmH50XPiqOvAjDfaijGxYZw==", + "dev": true + }, + "responselike": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/responselike/-/responselike-2.0.1.tgz", + "integrity": "sha512-4gl03wn3hj1HP3yzgdI7d3lCkF95F21Pz4BPGvKHinyQzALR5CapwC8yIi0Rh58DEMQ/SguC03wFj2k0M/mHhw==", + "dev": true, + "requires": { + "lowercase-keys": "^2.0.0" + }, + "dependencies": { + "lowercase-keys": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/lowercase-keys/-/lowercase-keys-2.0.0.tgz", + "integrity": "sha512-tqNXrS78oMOE73NMxK4EMLQsQowWf8jKooH9g7xPavRT706R6bkQJ6DY2Te7QukaZsulxa30wQ7bk0pm4XiHmA==", + "dev": true + } + } + }, + "retry": { + "version": "0.12.0", + "resolved": "https://registry.npmjs.org/retry/-/retry-0.12.0.tgz", + "integrity": "sha512-9LkiTwjUh6rT555DtE9rTX+BKByPfrMzEAtnlEtdEwr3Nkffwiihqe2bWADg+OQRjt9gl6ICdmB/ZFDCGAtSow==", + "dev": true + }, + "reusify": { + "version": "1.0.4", + "resolved": "https://registry.npmjs.org/reusify/-/reusify-1.0.4.tgz", + "integrity": "sha512-U9nH88a3fc/ekCF1l0/UP1IosiuIjyTh7hBvXVMHYgVcfGvt897Xguj2UOLDeI5BG2m7/uwyaLVT6fbtCwTyzw==", + "dev": true + }, + "rimraf": { + "version": "3.0.2", + "resolved": "https://registry.npmjs.org/rimraf/-/rimraf-3.0.2.tgz", + "integrity": "sha512-JZkJMZkAGFFPP2YqXZXPbMlMBgsxzE8ILs4lMIX/2o0L9UBw9O/Y3o6wFw/i9YLapcUJWwqbi3kdxIPdC62TIA==", + "dev": true, + "requires": { + "glob": "^7.1.3" + }, + "dependencies": { + "glob": { + "version": "7.2.3", + "resolved": "https://registry.npmjs.org/glob/-/glob-7.2.3.tgz", + "integrity": "sha512-nFR0zLpU2YCaRxwoCJvL6UvCH2JFyFVIvwTLsIf21AuHlMskA1hhTdk+LlYJtOlYt9v6dvszD2BGRqBL+iQK9Q==", + "dev": true, + "requires": { + "fs.realpath": "^1.0.0", + "inflight": "^1.0.4", + "inherits": "2", + "minimatch": "^3.1.1", + "once": "^1.3.0", + "path-is-absolute": "^1.0.0" + } + } + } + }, + "ripemd160": { + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/ripemd160/-/ripemd160-2.0.2.tgz", + "integrity": "sha512-ii4iagi25WusVoiC4B4lq7pbXfAp3D9v5CwfkY33vffw2+pkDjY1D8GaN7spsxvCSx8dkPqOZCEZyfxcmJG2IA==", + "dev": true, + "requires": { + "hash-base": "^3.0.0", + "inherits": "^2.0.1" + } + }, + "ripemd160-min": { + "version": "0.0.6", + "resolved": "https://registry.npmjs.org/ripemd160-min/-/ripemd160-min-0.0.6.tgz", + "integrity": "sha512-+GcJgQivhs6S9qvLogusiTcS9kQUfgR75whKuy5jIhuiOfQuJ8fjqxV6EGD5duH1Y/FawFUMtMhyeq3Fbnib8A==", + "dev": true + }, + "rlp": { + "version": "2.2.7", + "resolved": "https://registry.npmjs.org/rlp/-/rlp-2.2.7.tgz", + "integrity": "sha512-d5gdPmgQ0Z+AklL2NVXr/IoSjNZFfTVvQWzL/AM2AOcSzYP2xjlb0AC8YyCLc41MSNf6P6QVtjgPdmVtzb+4lQ==", + "dev": true, + "requires": { + "bn.js": "^5.2.0" + }, + "dependencies": { + "bn.js": { + "version": "5.2.1", + "resolved": "https://registry.npmjs.org/bn.js/-/bn.js-5.2.1.tgz", + "integrity": "sha512-eXRvHzWyYPBuB4NBy0cmYQjGitUrtqwbvlzP3G6VFnNRbsZQIxQ10PbKKHt8gZ/HW/D/747aDl+QkDqg3KQLMQ==", + "dev": true + } + } + }, + "run-parallel": { + "version": "1.2.0", + "resolved": "https://registry.npmjs.org/run-parallel/-/run-parallel-1.2.0.tgz", + "integrity": "sha512-5l4VyZR86LZ/lDxZTR6jqL8AFE2S0IFLMP26AbjsLVADxHdhB/c0GUsH+y39UfCi3dzz8OlQuPmnaJOMoDHQBA==", + "dev": true, + "requires": { + "queue-microtask": "^1.2.2" + } + }, + "run-parallel-limit": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/run-parallel-limit/-/run-parallel-limit-1.1.0.tgz", + "integrity": "sha512-jJA7irRNM91jaKc3Hcl1npHsFLOXOoTkPCUL1JEa1R82O2miplXXRaGdjW/KM/98YQWDhJLiSs793CnXfblJUw==", + "dev": true, + "requires": { + "queue-microtask": "^1.2.2" + } + }, + "rustbn.js": { + "version": "0.2.0", + "resolved": "https://registry.npmjs.org/rustbn.js/-/rustbn.js-0.2.0.tgz", + "integrity": "sha512-4VlvkRUuCJvr2J6Y0ImW7NvTCriMi7ErOAqWk1y69vAdoNIzCF3yPmgeNzx+RQTLEDFq5sHfscn1MwHxP9hNfA==", + "dev": true + }, + "safe-array-concat": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/safe-array-concat/-/safe-array-concat-1.0.0.tgz", + "integrity": "sha512-9dVEFruWIsnie89yym+xWTAYASdpw3CJV7Li/6zBewGf9z2i1j31rP6jnY0pHEO4QZh6N0K11bFjWmdR8UGdPQ==", + "dev": true, + "requires": { + "call-bind": "^1.0.2", + "get-intrinsic": "^1.2.0", + "has-symbols": "^1.0.3", + "isarray": "^2.0.5" + }, + "dependencies": { + "isarray": { + "version": "2.0.5", + "resolved": "https://registry.npmjs.org/isarray/-/isarray-2.0.5.tgz", + "integrity": "sha512-xHjhDr3cNBK0BzdUJSPXZntQUx/mwMS5Rw4A7lPJ90XGAO6ISP/ePDNuo0vhqOZU+UD5JoodwCAAoZQd3FeAKw==", + "dev": true + } + } + }, + "safe-buffer": { + "version": "5.2.1", + "resolved": "https://registry.npmjs.org/safe-buffer/-/safe-buffer-5.2.1.tgz", + "integrity": "sha512-rp3So07KcdmmKbGvgaNxQSJr7bGVSVk5S9Eq1F+ppbRo70+YeaDxkw5Dd8NPN+GD6bjnYm2VuPuCXmpuYvmCXQ==", + "dev": true + }, + "safe-regex-test": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/safe-regex-test/-/safe-regex-test-1.0.0.tgz", + "integrity": "sha512-JBUUzyOgEwXQY1NuPtvcj/qcBDbDmEvWufhlnXZIm75DEHp+afM1r1ujJpJsV/gSM4t59tpDyPi1sd6ZaPFfsA==", + "dev": true, + "requires": { + "call-bind": "^1.0.2", + "get-intrinsic": "^1.1.3", + "is-regex": "^1.1.4" + } + }, + "safer-buffer": { + "version": "2.1.2", + "resolved": "https://registry.npmjs.org/safer-buffer/-/safer-buffer-2.1.2.tgz", + "integrity": "sha512-YZo3K82SD7Riyi0E1EQPojLz7kpepnSQI9IyPbHHg1XXXevb5dJI7tpyN2ADxGcQbHG7vcyRHk0cbwqcQriUtg==", + "dev": true + }, + "sc-istanbul": { + "version": "0.4.6", + "resolved": "https://registry.npmjs.org/sc-istanbul/-/sc-istanbul-0.4.6.tgz", + "integrity": "sha512-qJFF/8tW/zJsbyfh/iT/ZM5QNHE3CXxtLJbZsL+CzdJLBsPD7SedJZoUA4d8iAcN2IoMp/Dx80shOOd2x96X/g==", + "dev": true, + "requires": { + "abbrev": "1.0.x", + "async": "1.x", + "escodegen": "1.8.x", + "esprima": "2.7.x", + "glob": "^5.0.15", + "handlebars": "^4.0.1", + "js-yaml": "3.x", + "mkdirp": "0.5.x", + "nopt": "3.x", + "once": "1.x", + "resolve": "1.1.x", + "supports-color": "^3.1.0", + "which": "^1.1.1", + "wordwrap": "^1.0.0" + }, + "dependencies": { + "esprima": { + "version": "2.7.3", + "resolved": "https://registry.npmjs.org/esprima/-/esprima-2.7.3.tgz", + "integrity": "sha512-OarPfz0lFCiW4/AV2Oy1Rp9qu0iusTKqykwTspGCZtPxmF81JR4MmIebvF1F9+UOKth2ZubLQ4XGGaU+hSn99A==", + "dev": true + }, + "glob": { + "version": "5.0.15", + "resolved": "https://registry.npmjs.org/glob/-/glob-5.0.15.tgz", + "integrity": "sha512-c9IPMazfRITpmAAKi22dK1VKxGDX9ehhqfABDriL/lzO92xcUKEJPQHrVA/2YHSNFB4iFlykVmWvwo48nr3OxA==", + "dev": true, + "requires": { + "inflight": "^1.0.4", + "inherits": "2", + "minimatch": "2 || 3", + "once": "^1.3.0", + "path-is-absolute": "^1.0.0" + } + }, + "has-flag": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/has-flag/-/has-flag-1.0.0.tgz", + "integrity": "sha512-DyYHfIYwAJmjAjSSPKANxI8bFY9YtFrgkAfinBojQ8YJTOuOuav64tMUJv584SES4xl74PmuaevIyaLESHdTAA==", + "dev": true + }, + "resolve": { + "version": "1.1.7", + "resolved": "https://registry.npmjs.org/resolve/-/resolve-1.1.7.tgz", + "integrity": "sha512-9znBF0vBcaSN3W2j7wKvdERPwqTxSpCq+if5C0WoTCyV9n24rua28jeuQ2pL/HOf+yUe/Mef+H/5p60K0Id3bg==", + "dev": true + }, + "supports-color": { + "version": "3.2.3", + "resolved": "https://registry.npmjs.org/supports-color/-/supports-color-3.2.3.tgz", + "integrity": "sha512-Jds2VIYDrlp5ui7t8abHN2bjAu4LV/q4N2KivFPpGH0lrka0BMq/33AmECUXlKPcHigkNaqfXRENFju+rlcy+A==", + "dev": true, + "requires": { + "has-flag": "^1.0.0" + } + }, + "which": { + "version": "1.3.1", + "resolved": "https://registry.npmjs.org/which/-/which-1.3.1.tgz", + "integrity": "sha512-HxJdYWq1MTIQbJ3nw0cqssHoTNU267KlrDuGZ1WYlxDStUtKUhOaJmh112/TZmHxxUfuJqPXSOm7tDyas0OSIQ==", + "dev": true, + "requires": { + "isexe": "^2.0.0" + } + } + } + }, + "scrypt-js": { + "version": "3.0.1", + "resolved": "https://registry.npmjs.org/scrypt-js/-/scrypt-js-3.0.1.tgz", + "integrity": "sha512-cdwTTnqPu0Hyvf5in5asVdZocVDTNRmR7XEcJuIzMjJeSHybHl7vpB66AzwTaIg6CLSbtjcxc8fqcySfnTkccA==", + "dev": true + }, + "secp256k1": { + "version": "4.0.3", + "resolved": "https://registry.npmjs.org/secp256k1/-/secp256k1-4.0.3.tgz", + "integrity": "sha512-NLZVf+ROMxwtEj3Xa562qgv2BK5e2WNmXPiOdVIPLgs6lyTzMvBq0aWTYMI5XCP9jZMVKOcqZLw/Wc4vDkuxhA==", + "dev": true, + "requires": { + "elliptic": "^6.5.4", + "node-addon-api": "^2.0.0", + "node-gyp-build": "^4.2.0" + } + }, + "semver": { + "version": "7.5.3", + "resolved": "https://registry.npmjs.org/semver/-/semver-7.5.3.tgz", + "integrity": "sha512-QBlUtyVk/5EeHbi7X0fw6liDZc7BBmEaSYn01fMU1OUYbf6GPsbTtd8WmnqbI20SeycoHSeiybkE/q1Q+qlThQ==", + "dev": true, + "requires": { + "lru-cache": "^6.0.0" + }, + "dependencies": { + "lru-cache": { + "version": "6.0.0", + "resolved": "https://registry.npmjs.org/lru-cache/-/lru-cache-6.0.0.tgz", + "integrity": "sha512-Jo6dJ04CmSjuznwJSS3pUeWmd/H0ffTlkXXgwZi+eq1UCmqQwCh+eLsYOYCwY991i2Fah4h1BEMCx4qThGbsiA==", + "dev": true, + "requires": { + "yallist": "^4.0.0" + } + }, + "yallist": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/yallist/-/yallist-4.0.0.tgz", + "integrity": "sha512-3wdGidZyq5PB084XLES5TpOSRA3wjXAlIWMhum2kRcv/41Sn2emQ0dycQW4uZXLejwKvg6EsvbdlVL+FYEct7A==", + "dev": true + } + } + }, + "send": { + "version": "0.18.0", + "resolved": "https://registry.npmjs.org/send/-/send-0.18.0.tgz", + "integrity": "sha512-qqWzuOjSFOuqPjFe4NOsMLafToQQwBSOEpS+FwEt3A2V3vKubTquT3vmLTQpFgMXp8AlFWFuP1qKaJZOtPpVXg==", + "dev": true, + "requires": { + "debug": "2.6.9", + "depd": "2.0.0", + "destroy": "1.2.0", + "encodeurl": "~1.0.2", + "escape-html": "~1.0.3", + "etag": "~1.8.1", + "fresh": "0.5.2", + "http-errors": "2.0.0", + "mime": "1.6.0", + "ms": "2.1.3", + "on-finished": "2.4.1", + "range-parser": "~1.2.1", + "statuses": "2.0.1" + }, + "dependencies": { + "debug": { + "version": "2.6.9", + "resolved": "https://registry.npmjs.org/debug/-/debug-2.6.9.tgz", + "integrity": "sha512-bC7ElrdJaJnPbAP+1EotYvqZsb3ecl5wi6Bfi6BJTUcNowp6cvspg0jXznRTKDjm/E7AdgFBVeAPVMNcKGsHMA==", + "dev": true, + "requires": { + "ms": "2.0.0" + }, + "dependencies": { + "ms": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/ms/-/ms-2.0.0.tgz", + "integrity": "sha512-Tpp60P6IUJDTuOq/5Z8cdskzJujfwqfOTkrwIwj7IRISpnkJnT6SyJ4PCPnGMoFjC9ddhal5KVIYtAt97ix05A==", + "dev": true + } + } + }, + "ms": { + "version": "2.1.3", + "resolved": "https://registry.npmjs.org/ms/-/ms-2.1.3.tgz", + "integrity": "sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==", + "dev": true + } + } + }, + "sentence-case": { + "version": "2.1.1", + "resolved": "https://registry.npmjs.org/sentence-case/-/sentence-case-2.1.1.tgz", + "integrity": "sha512-ENl7cYHaK/Ktwk5OTD+aDbQ3uC8IByu/6Bkg+HDv8Mm+XnBnppVNalcfJTNsp1ibstKh030/JKQQWglDvtKwEQ==", + "dev": true, + "requires": { + "no-case": "^2.2.0", + "upper-case-first": "^1.1.2" + } + }, + "serialize-javascript": { + "version": "6.0.0", + "resolved": "https://registry.npmjs.org/serialize-javascript/-/serialize-javascript-6.0.0.tgz", + "integrity": "sha512-Qr3TosvguFt8ePWqsvRfrKyQXIiW+nGbYpy8XK24NQHE83caxWt+mIymTT19DGFbNWNLfEwsrkSmN64lVWB9ag==", + "dev": true, + "requires": { + "randombytes": "^2.1.0" + } + }, + "serve-static": { + "version": "1.15.0", + "resolved": "https://registry.npmjs.org/serve-static/-/serve-static-1.15.0.tgz", + "integrity": "sha512-XGuRDNjXUijsUL0vl6nSD7cwURuzEgglbOaFuZM9g3kwDXOWVTck0jLzjPzGD+TazWbboZYu52/9/XPdUgne9g==", + "dev": true, + "requires": { + "encodeurl": "~1.0.2", + "escape-html": "~1.0.3", + "parseurl": "~1.3.3", + "send": "0.18.0" + } + }, + "servify": { + "version": "0.1.12", + "resolved": "https://registry.npmjs.org/servify/-/servify-0.1.12.tgz", + "integrity": "sha512-/xE6GvsKKqyo1BAY+KxOWXcLpPsUUyji7Qg3bVD7hh1eRze5bR1uYiuDA/k3Gof1s9BTzQZEJK8sNcNGFIzeWw==", + "dev": true, + "requires": { + "body-parser": "^1.16.0", + "cors": "^2.8.1", + "express": "^4.14.0", + "request": "^2.79.0", + "xhr": "^2.3.3" + } + }, + "set-blocking": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/set-blocking/-/set-blocking-2.0.0.tgz", + "integrity": "sha512-KiKBS8AnWGEyLzofFfmvKwpdPzqiy16LvQfK3yv/fVH7Bj13/wl3JSR1J+rfgRE9q7xUJK4qvgS8raSOeLUehw==", + "dev": true + }, + "setimmediate": { + "version": "1.0.5", + "resolved": "https://registry.npmjs.org/setimmediate/-/setimmediate-1.0.5.tgz", + "integrity": "sha512-MATJdZp8sLqDl/68LfQmbP8zKPLQNV6BIZoIgrscFDQ+RsvK/BxeDQOgyxKKoh0y/8h3BqVFnCqQ/gd+reiIXA==", + "dev": true + }, + "setprototypeof": { + "version": "1.2.0", + "resolved": "https://registry.npmjs.org/setprototypeof/-/setprototypeof-1.2.0.tgz", + "integrity": "sha512-E5LDX7Wrp85Kil5bhZv46j8jOeboKq5JMmYM3gVGdGH8xFpPWXUMsNrlODCrkoxMEeNi/XZIwuRvY4XNwYMJpw==", + "dev": true + }, + "sha.js": { + "version": "2.4.11", + "resolved": "https://registry.npmjs.org/sha.js/-/sha.js-2.4.11.tgz", + "integrity": "sha512-QMEp5B7cftE7APOjk5Y6xgrbWu+WkLVQwk8JNjZ8nKRciZaByEW6MubieAiToS7+dwvrjGhH8jRXz3MVd0AYqQ==", + "dev": true, + "requires": { + "inherits": "^2.0.1", + "safe-buffer": "^5.0.1" + } + }, + "sha1": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/sha1/-/sha1-1.1.1.tgz", + "integrity": "sha512-dZBS6OrMjtgVkopB1Gmo4RQCDKiZsqcpAQpkV/aaj+FCrCg8r4I4qMkDPQjBgLIxlmu9k4nUbWq6ohXahOneYA==", + "dev": true, + "requires": { + "charenc": ">= 0.0.1", + "crypt": ">= 0.0.1" + } + }, + "sha3": { + "version": "2.1.4", + "resolved": "https://registry.npmjs.org/sha3/-/sha3-2.1.4.tgz", + "integrity": "sha512-S8cNxbyb0UGUM2VhRD4Poe5N58gJnJsLJ5vC7FYWGUmGhcsj4++WaIOBFVDxlG0W3To6xBuiRh+i0Qp2oNCOtg==", + "dev": true, + "requires": { + "buffer": "6.0.3" + }, + "dependencies": { + "buffer": { + "version": "6.0.3", + "resolved": "https://registry.npmjs.org/buffer/-/buffer-6.0.3.tgz", + "integrity": "sha512-FTiCpNxtwiZZHEZbcbTIcZjERVICn9yq/pDFkTl95/AxzD1naBctN7YO68riM/gLSDY7sdrMby8hofADYuuqOA==", + "dev": true, + "requires": { + "base64-js": "^1.3.1", + "ieee754": "^1.2.1" + } + } + } + }, + "shallowequal": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/shallowequal/-/shallowequal-1.1.0.tgz", + "integrity": "sha512-y0m1JoUZSlPAjXVtPPW70aZWfIL/dSP7AFkRnniLCrK/8MDKog3TySTBmckD+RObVxH0v4Tox67+F14PdED2oQ==", + "dev": true + }, + "shebang-command": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/shebang-command/-/shebang-command-2.0.0.tgz", + "integrity": "sha512-kHxr2zZpYtdmrN1qDjrrX/Z1rR1kG8Dx+gkpK1G4eXmvXswmcE1hTWBWYUzlraYw1/yZp6YuDY77YtvbN0dmDA==", + "dev": true, + "requires": { + "shebang-regex": "^3.0.0" + } + }, + "shebang-regex": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/shebang-regex/-/shebang-regex-3.0.0.tgz", + "integrity": "sha512-7++dFhtcx3353uBaq8DDR4NuxBetBzC7ZQOhmTQInHEd6bSrXdiEyzCvG07Z44UYdLShWUyXt5M/yhz8ekcb1A==", + "dev": true + }, + "shelljs": { + "version": "0.8.5", + "resolved": "https://registry.npmjs.org/shelljs/-/shelljs-0.8.5.tgz", + "integrity": "sha512-TiwcRcrkhHvbrZbnRcFYMLl30Dfov3HKqzp5tO5b4pt6G/SezKcYhmDg15zXVBswHmctSAQKznqNW2LO5tTDow==", + "dev": true, + "requires": { + "glob": "^7.0.0", + "interpret": "^1.0.0", + "rechoir": "^0.6.2" + }, + "dependencies": { + "glob": { + "version": "7.2.3", + "resolved": "https://registry.npmjs.org/glob/-/glob-7.2.3.tgz", + "integrity": "sha512-nFR0zLpU2YCaRxwoCJvL6UvCH2JFyFVIvwTLsIf21AuHlMskA1hhTdk+LlYJtOlYt9v6dvszD2BGRqBL+iQK9Q==", + "dev": true, + "requires": { + "fs.realpath": "^1.0.0", + "inflight": "^1.0.4", + "inherits": "2", + "minimatch": "^3.1.1", + "once": "^1.3.0", + "path-is-absolute": "^1.0.0" + } + } + } + }, + "side-channel": { + "version": "1.0.4", + "resolved": "https://registry.npmjs.org/side-channel/-/side-channel-1.0.4.tgz", + "integrity": "sha512-q5XPytqFEIKHkGdiMIrY10mvLRvnQh42/+GoBlFW3b2LXLE2xxJpZFdm94we0BaoV3RwJyGqg5wS7epxTv0Zvw==", + "dev": true, + "requires": { + "call-bind": "^1.0.0", + "get-intrinsic": "^1.0.2", + "object-inspect": "^1.9.0" + } + }, + "signal-exit": { + "version": "3.0.7", + "resolved": "https://registry.npmjs.org/signal-exit/-/signal-exit-3.0.7.tgz", + "integrity": "sha512-wnD2ZE+l+SPC/uoS0vXeE9L1+0wuaMqKlfz9AMUo38JsyLSBWSFcHR1Rri62LZc12vLr1gb3jl7iwQhgwpAbGQ==", + "dev": true + }, + "simple-concat": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/simple-concat/-/simple-concat-1.0.1.tgz", + "integrity": "sha512-cSFtAPtRhljv69IK0hTVZQ+OfE9nePi/rtJmw5UjHeVyVroEqJXP1sFztKUy1qU+xvz3u/sfYJLa947b7nAN2Q==", + "dev": true + }, + "simple-get": { + "version": "2.8.2", + "resolved": "https://registry.npmjs.org/simple-get/-/simple-get-2.8.2.tgz", + "integrity": "sha512-Ijd/rV5o+mSBBs4F/x9oDPtTx9Zb6X9brmnXvMW4J7IR15ngi9q5xxqWBKU744jTZiaXtxaPL7uHG6vtN8kUkw==", + "dev": true, + "requires": { + "decompress-response": "^3.3.0", + "once": "^1.3.1", + "simple-concat": "^1.0.0" + }, + "dependencies": { + "decompress-response": { + "version": "3.3.0", + "resolved": "https://registry.npmjs.org/decompress-response/-/decompress-response-3.3.0.tgz", + "integrity": "sha512-BzRPQuY1ip+qDonAOz42gRm/pg9F768C+npV/4JOsxRC2sq+Rlk+Q4ZCAsOhnIaMrgarILY+RMUIvMmmX1qAEA==", + "dev": true, + "requires": { + "mimic-response": "^1.0.0" + } + } + } + }, + "slash": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/slash/-/slash-3.0.0.tgz", + "integrity": "sha512-g9Q1haeby36OSStwb4ntCGGGaKsaVSjQ68fBxoQcutl5fS1vuY18H3wSt3jFyFtrkx+Kz0V1G85A4MyAdDMi2Q==", + "dev": true + }, + "slice-ansi": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/slice-ansi/-/slice-ansi-4.0.0.tgz", + "integrity": "sha512-qMCMfhY040cVHT43K9BFygqYbUPFZKHOg7K73mtTWJRb8pyP3fzf4Ixd5SzdEJQ6MRUg/WBnOLxghZtKKurENQ==", + "dev": true, + "requires": { + "ansi-styles": "^4.0.0", + "astral-regex": "^2.0.0", + "is-fullwidth-code-point": "^3.0.0" + }, + "dependencies": { + "ansi-styles": { + "version": "4.3.0", + "resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-4.3.0.tgz", + "integrity": "sha512-zbB9rCJAT1rbjiVDb2hqKFHNYLxgtk8NURxZ3IZwD3F6NtxbXZQCnnSi1Lkx+IDohdPlFp222wVALIheZJQSEg==", + "dev": true, + "requires": { + "color-convert": "^2.0.1" + } + }, + "color-convert": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/color-convert/-/color-convert-2.0.1.tgz", + "integrity": "sha512-RRECPsj7iu/xb5oKYcsFHSppFNnsj/52OVTRKb4zP5onXwVF3zVmmToNcOfGC+CRDpfK/U584fMg38ZHCaElKQ==", + "dev": true, + "requires": { + "color-name": "~1.1.4" + } + }, + "color-name": { + "version": "1.1.4", + "resolved": "https://registry.npmjs.org/color-name/-/color-name-1.1.4.tgz", + "integrity": "sha512-dOy+3AuW3a2wNbZHIuMZpTcgjGuLU/uBL/ubcZF9OXbDo8ff4O8yVp5Bf0efS8uEoYo5q4Fx7dY9OgQGXgAsQA==", + "dev": true + }, + "is-fullwidth-code-point": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/is-fullwidth-code-point/-/is-fullwidth-code-point-3.0.0.tgz", + "integrity": "sha512-zymm5+u+sCsSWyD9qNaejV3DFvhCKclKdizYaJUuHA83RLjb7nSuGnddCHGv0hk+KY7BMAlsWeK4Ueg6EV6XQg==", + "dev": true + } + } + }, + "smartwrap": { + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/smartwrap/-/smartwrap-2.0.2.tgz", + "integrity": "sha512-vCsKNQxb7PnCNd2wY1WClWifAc2lwqsG8OaswpJkVJsvMGcnEntdTCDajZCkk93Ay1U3t/9puJmb525Rg5MZBA==", + "dev": true, + "requires": { + "array.prototype.flat": "^1.2.3", + "breakword": "^1.0.5", + "grapheme-splitter": "^1.0.4", + "strip-ansi": "^6.0.0", + "wcwidth": "^1.0.1", + "yargs": "^15.1.0" + }, + "dependencies": { + "ansi-regex": { + "version": "5.0.1", + "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-5.0.1.tgz", + "integrity": "sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ==", + "dev": true + }, + "ansi-styles": { + "version": "4.3.0", + "resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-4.3.0.tgz", + "integrity": "sha512-zbB9rCJAT1rbjiVDb2hqKFHNYLxgtk8NURxZ3IZwD3F6NtxbXZQCnnSi1Lkx+IDohdPlFp222wVALIheZJQSEg==", + "dev": true, + "requires": { + "color-convert": "^2.0.1" + } + }, + "cliui": { + "version": "6.0.0", + "resolved": "https://registry.npmjs.org/cliui/-/cliui-6.0.0.tgz", + "integrity": "sha512-t6wbgtoCXvAzst7QgXxJYqPt0usEfbgQdftEPbLL/cvv6HPE5VgvqCuAIDR0NgU52ds6rFwqrgakNLrHEjCbrQ==", + "dev": true, + "requires": { + "string-width": "^4.2.0", + "strip-ansi": "^6.0.0", + "wrap-ansi": "^6.2.0" + } + }, + "color-convert": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/color-convert/-/color-convert-2.0.1.tgz", + "integrity": "sha512-RRECPsj7iu/xb5oKYcsFHSppFNnsj/52OVTRKb4zP5onXwVF3zVmmToNcOfGC+CRDpfK/U584fMg38ZHCaElKQ==", + "dev": true, + "requires": { + "color-name": "~1.1.4" + } + }, + "color-name": { + "version": "1.1.4", + "resolved": "https://registry.npmjs.org/color-name/-/color-name-1.1.4.tgz", + "integrity": "sha512-dOy+3AuW3a2wNbZHIuMZpTcgjGuLU/uBL/ubcZF9OXbDo8ff4O8yVp5Bf0efS8uEoYo5q4Fx7dY9OgQGXgAsQA==", + "dev": true + }, + "is-fullwidth-code-point": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/is-fullwidth-code-point/-/is-fullwidth-code-point-3.0.0.tgz", + "integrity": "sha512-zymm5+u+sCsSWyD9qNaejV3DFvhCKclKdizYaJUuHA83RLjb7nSuGnddCHGv0hk+KY7BMAlsWeK4Ueg6EV6XQg==", + "dev": true + }, + "string-width": { + "version": "4.2.3", + "resolved": "https://registry.npmjs.org/string-width/-/string-width-4.2.3.tgz", + "integrity": "sha512-wKyQRQpjJ0sIp62ErSZdGsjMJWsap5oRNihHhu6G7JVO/9jIB6UyevL+tXuOqrng8j/cxKTWyWUwvSTriiZz/g==", + "dev": true, + "requires": { + "emoji-regex": "^8.0.0", + "is-fullwidth-code-point": "^3.0.0", + "strip-ansi": "^6.0.1" + } + }, + "strip-ansi": { + "version": "6.0.1", + "resolved": "https://registry.npmjs.org/strip-ansi/-/strip-ansi-6.0.1.tgz", + "integrity": "sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A==", + "dev": true, + "requires": { + "ansi-regex": "^5.0.1" + } + }, + "wrap-ansi": { + "version": "6.2.0", + "resolved": "https://registry.npmjs.org/wrap-ansi/-/wrap-ansi-6.2.0.tgz", + "integrity": "sha512-r6lPcBGxZXlIcymEu7InxDMhdW0KDxpLgoFLcguasxCaJ/SOIZwINatK9KY/tf+ZrlywOKU0UDj3ATXUBfxJXA==", + "dev": true, + "requires": { + "ansi-styles": "^4.0.0", + "string-width": "^4.1.0", + "strip-ansi": "^6.0.0" + } + }, + "y18n": { + "version": "4.0.3", + "resolved": "https://registry.npmjs.org/y18n/-/y18n-4.0.3.tgz", + "integrity": "sha512-JKhqTOwSrqNA1NY5lSztJ1GrBiUodLMmIZuLiDaMRJ+itFd+ABVE8XBjOvIWL+rSqNDC74LCSFmlb/U4UZ4hJQ==", + "dev": true + }, + "yargs": { + "version": "15.4.1", + "resolved": "https://registry.npmjs.org/yargs/-/yargs-15.4.1.tgz", + "integrity": "sha512-aePbxDmcYW++PaqBsJ+HYUFwCdv4LVvdnhBy78E57PIor8/OVvhMrADFFEDh8DHDFRv/O9i3lPhsENjO7QX0+A==", + "dev": true, + "requires": { + "cliui": "^6.0.0", + "decamelize": "^1.2.0", + "find-up": "^4.1.0", + "get-caller-file": "^2.0.1", + "require-directory": "^2.1.1", + "require-main-filename": "^2.0.0", + "set-blocking": "^2.0.0", + "string-width": "^4.2.0", + "which-module": "^2.0.0", + "y18n": "^4.0.0", + "yargs-parser": "^18.1.2" + } + } + } + }, + "snake-case": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/snake-case/-/snake-case-2.1.0.tgz", + "integrity": "sha512-FMR5YoPFwOLuh4rRz92dywJjyKYZNLpMn1R5ujVpIYkbA9p01fq8RMg0FkO4M+Yobt4MjHeLTJVm5xFFBHSV2Q==", + "dev": true, + "requires": { + "no-case": "^2.2.0" + } + }, + "solc": { + "version": "0.4.26", + "resolved": "https://registry.npmjs.org/solc/-/solc-0.4.26.tgz", + "integrity": "sha512-o+c6FpkiHd+HPjmjEVpQgH7fqZ14tJpXhho+/bQXlXbliLIS/xjXb42Vxh+qQY1WCSTMQ0+a5vR9vi0MfhU6mA==", + "dev": true, + "requires": { + "fs-extra": "^0.30.0", + "memorystream": "^0.3.1", + "require-from-string": "^1.1.0", + "semver": "^5.3.0", + "yargs": "^4.7.1" + }, + "dependencies": { + "ansi-regex": { + "version": "2.1.1", + "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-2.1.1.tgz", + "integrity": "sha512-TIGnTpdo+E3+pCyAluZvtED5p5wCqLdezCyhPZzKPcxvFplEt4i+W7OONCKgeZFT3+y5NZZfOOS/Bdcanm1MYA==", + "dev": true + }, + "camelcase": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/camelcase/-/camelcase-3.0.0.tgz", + "integrity": "sha512-4nhGqUkc4BqbBBB4Q6zLuD7lzzrHYrjKGeYaEji/3tFR5VdJu9v+LilhGIVe8wxEJPPOeWo7eg8dwY13TZ1BNg==", + "dev": true + }, + "cliui": { + "version": "3.2.0", + "resolved": "https://registry.npmjs.org/cliui/-/cliui-3.2.0.tgz", + "integrity": "sha512-0yayqDxWQbqk3ojkYqUKqaAQ6AfNKeKWRNA8kR0WXzAsdHpP4BIaOmMAG87JGuO6qcobyW4GjxHd9PmhEd+T9w==", + "dev": true, + "requires": { + "string-width": "^1.0.1", + "strip-ansi": "^3.0.1", + "wrap-ansi": "^2.0.0" + } + }, + "find-up": { + "version": "1.1.2", + "resolved": "https://registry.npmjs.org/find-up/-/find-up-1.1.2.tgz", + "integrity": "sha512-jvElSjyuo4EMQGoTwo1uJU5pQMwTW5lS1x05zzfJuTIyLR3zwO27LYrxNg+dlvKpGOuGy/MzBdXh80g0ve5+HA==", + "dev": true, + "requires": { + "path-exists": "^2.0.0", + "pinkie-promise": "^2.0.0" + } + }, + "fs-extra": { + "version": "0.30.0", + "resolved": "https://registry.npmjs.org/fs-extra/-/fs-extra-0.30.0.tgz", + "integrity": "sha512-UvSPKyhMn6LEd/WpUaV9C9t3zATuqoqfWc3QdPhPLb58prN9tqYPlPWi8Krxi44loBoUzlobqZ3+8tGpxxSzwA==", + "dev": true, + "requires": { + "graceful-fs": "^4.1.2", + "jsonfile": "^2.1.0", + "klaw": "^1.0.0", + "path-is-absolute": "^1.0.0", + "rimraf": "^2.2.8" + } + }, + "get-caller-file": { + "version": "1.0.3", + "resolved": "https://registry.npmjs.org/get-caller-file/-/get-caller-file-1.0.3.tgz", + "integrity": "sha512-3t6rVToeoZfYSGd8YoLFR2DJkiQrIiUrGcjvFX2mDw3bn6k2OtwHN0TNCLbBO+w8qTvimhDkv+LSscbJY1vE6w==", + "dev": true + }, + "glob": { + "version": "7.2.3", + "resolved": "https://registry.npmjs.org/glob/-/glob-7.2.3.tgz", + "integrity": "sha512-nFR0zLpU2YCaRxwoCJvL6UvCH2JFyFVIvwTLsIf21AuHlMskA1hhTdk+LlYJtOlYt9v6dvszD2BGRqBL+iQK9Q==", + "dev": true, + "requires": { + "fs.realpath": "^1.0.0", + "inflight": "^1.0.4", + "inherits": "2", + "minimatch": "^3.1.1", + "once": "^1.3.0", + "path-is-absolute": "^1.0.0" + } + }, + "is-fullwidth-code-point": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/is-fullwidth-code-point/-/is-fullwidth-code-point-1.0.0.tgz", + "integrity": "sha512-1pqUqRjkhPJ9miNq9SwMfdvi6lBJcd6eFxvfaivQhaH3SgisfiuudvFntdKOmxuee/77l+FPjKrQjWvmPjWrRw==", + "dev": true, + "requires": { + "number-is-nan": "^1.0.0" + } + }, + "jsonfile": { + "version": "2.4.0", + "resolved": "https://registry.npmjs.org/jsonfile/-/jsonfile-2.4.0.tgz", + "integrity": "sha512-PKllAqbgLgxHaj8TElYymKCAgrASebJrWpTnEkOaTowt23VKXXN0sUeriJ+eh7y6ufb/CC5ap11pz71/cM0hUw==", + "dev": true, + "requires": { + "graceful-fs": "^4.1.6" + } + }, + "path-exists": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/path-exists/-/path-exists-2.1.0.tgz", + "integrity": "sha512-yTltuKuhtNeFJKa1PiRzfLAU5182q1y4Eb4XCJ3PBqyzEDkAZRzBrKKBct682ls9reBVHf9udYLN5Nd+K1B9BQ==", + "dev": true, + "requires": { + "pinkie-promise": "^2.0.0" + } + }, + "path-type": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/path-type/-/path-type-1.1.0.tgz", + "integrity": "sha512-S4eENJz1pkiQn9Znv33Q+deTOKmbl+jj1Fl+qiP/vYezj+S8x+J3Uo0ISrx/QoEvIlOaDWJhPaRd1flJ9HXZqg==", + "dev": true, + "requires": { + "graceful-fs": "^4.1.2", + "pify": "^2.0.0", + "pinkie-promise": "^2.0.0" + } + }, + "pify": { + "version": "2.3.0", + "resolved": "https://registry.npmjs.org/pify/-/pify-2.3.0.tgz", + "integrity": "sha512-udgsAY+fTnvv7kI7aaxbqwWNb0AHiB0qBO89PZKPkoTmGOgdbrHDKD+0B2X4uTfJ/FT1R09r9gTsjUjNJotuog==", + "dev": true + }, + "read-pkg": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/read-pkg/-/read-pkg-1.1.0.tgz", + "integrity": "sha512-7BGwRHqt4s/uVbuyoeejRn4YmFnYZiFl4AuaeXHlgZf3sONF0SOGlxs2Pw8g6hCKupo08RafIO5YXFNOKTfwsQ==", + "dev": true, + "requires": { + "load-json-file": "^1.0.0", + "normalize-package-data": "^2.3.2", + "path-type": "^1.0.0" + } + }, + "read-pkg-up": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/read-pkg-up/-/read-pkg-up-1.0.1.tgz", + "integrity": "sha512-WD9MTlNtI55IwYUS27iHh9tK3YoIVhxis8yKhLpTqWtml739uXc9NWTpxoHkfZf3+DkCCsXox94/VWZniuZm6A==", + "dev": true, + "requires": { + "find-up": "^1.0.0", + "read-pkg": "^1.0.0" + } + }, + "require-main-filename": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/require-main-filename/-/require-main-filename-1.0.1.tgz", + "integrity": "sha512-IqSUtOVP4ksd1C/ej5zeEh/BIP2ajqpn8c5x+q99gvcIG/Qf0cud5raVnE/Dwd0ua9TXYDoDc0RE5hBSdz22Ug==", + "dev": true + }, + "rimraf": { + "version": "2.7.1", + "resolved": "https://registry.npmjs.org/rimraf/-/rimraf-2.7.1.tgz", + "integrity": "sha512-uWjbaKIK3T1OSVptzX7Nl6PvQ3qAGtKEtVRjRuazjfL3Bx5eI409VZSqgND+4UNnmzLVdPj9FqFJNPqBZFve4w==", + "dev": true, + "requires": { + "glob": "^7.1.3" + } + }, + "semver": { + "version": "5.7.1", + "resolved": "https://registry.npmjs.org/semver/-/semver-5.7.1.tgz", + "integrity": "sha512-sauaDf/PZdVgrLTNYHRtpXa1iRiKcaebiKQ1BJdpQlWH2lCvexQdX55snPFyK7QzpudqbCI0qXFfOasHdyNDGQ==", + "dev": true + }, + "string-width": { + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/string-width/-/string-width-1.0.2.tgz", + "integrity": "sha512-0XsVpQLnVCXHJfyEs8tC0zpTVIr5PKKsQtkT29IwupnPTjtPmQ3xT/4yCREF9hYkV/3M3kzcUTSAZT6a6h81tw==", + "dev": true, + "requires": { + "code-point-at": "^1.0.0", + "is-fullwidth-code-point": "^1.0.0", + "strip-ansi": "^3.0.0" + } + }, + "strip-ansi": { + "version": "3.0.1", + "resolved": "https://registry.npmjs.org/strip-ansi/-/strip-ansi-3.0.1.tgz", + "integrity": "sha512-VhumSSbBqDTP8p2ZLKj40UjBCV4+v8bUSEpUb4KjRgWk9pbqGF4REFj6KEagidb2f/M6AzC0EmFyDNGaw9OCzg==", + "dev": true, + "requires": { + "ansi-regex": "^2.0.0" + } + }, + "which-module": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/which-module/-/which-module-1.0.0.tgz", + "integrity": "sha512-F6+WgncZi/mJDrammbTuHe1q0R5hOXv/mBaiNA2TCNT/LTHusX0V+CJnj9XT8ki5ln2UZyyddDgHfCzyrOH7MQ==", + "dev": true + }, + "wrap-ansi": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/wrap-ansi/-/wrap-ansi-2.1.0.tgz", + "integrity": "sha512-vAaEaDM946gbNpH5pLVNR+vX2ht6n0Bt3GXwVB1AuAqZosOvHNF3P7wDnh8KLkSqgUh0uh77le7Owgoz+Z9XBw==", + "dev": true, + "requires": { + "string-width": "^1.0.1", + "strip-ansi": "^3.0.1" + } + }, + "y18n": { + "version": "3.2.2", + "resolved": "https://registry.npmjs.org/y18n/-/y18n-3.2.2.tgz", + "integrity": "sha512-uGZHXkHnhF0XeeAPgnKfPv1bgKAYyVvmNL1xlKsPYZPaIHxGti2hHqvOCQv71XMsLxu1QjergkqogUnms5D3YQ==", + "dev": true + }, + "yargs": { + "version": "4.8.1", + "resolved": "https://registry.npmjs.org/yargs/-/yargs-4.8.1.tgz", + "integrity": "sha512-LqodLrnIDM3IFT+Hf/5sxBnEGECrfdC1uIbgZeJmESCSo4HoCAaKEus8MylXHAkdacGc0ye+Qa+dpkuom8uVYA==", + "dev": true, + "requires": { + "cliui": "^3.2.0", + "decamelize": "^1.1.1", + "get-caller-file": "^1.0.1", + "lodash.assign": "^4.0.3", + "os-locale": "^1.4.0", + "read-pkg-up": "^1.0.1", + "require-directory": "^2.1.1", + "require-main-filename": "^1.0.1", + "set-blocking": "^2.0.0", + "string-width": "^1.0.1", + "which-module": "^1.0.0", + "window-size": "^0.2.0", + "y18n": "^3.2.1", + "yargs-parser": "^2.4.1" + } + }, + "yargs-parser": { + "version": "2.4.1", + "resolved": "https://registry.npmjs.org/yargs-parser/-/yargs-parser-2.4.1.tgz", + "integrity": "sha512-9pIKIJhnI5tonzG6OnCFlz/yln8xHYcGl+pn3xR0Vzff0vzN1PbNRaelgfgRUwZ3s4i3jvxT9WhmUGL4whnasA==", + "dev": true, + "requires": { + "camelcase": "^3.0.0", + "lodash.assign": "^4.0.6" + } + } + } + }, + "solhint": { + "version": "3.4.1", + "resolved": "https://registry.npmjs.org/solhint/-/solhint-3.4.1.tgz", + "integrity": "sha512-pzZn2RlZhws1XwvLPVSsxfHrwsteFf5eySOhpAytzXwKQYbTCJV6z8EevYDiSVKMpWrvbKpEtJ055CuEmzp4Xg==", + "dev": true, + "requires": { + "@solidity-parser/parser": "^0.16.0", + "ajv": "^6.12.6", + "antlr4": "^4.11.0", + "ast-parents": "^0.0.1", + "chalk": "^4.1.2", + "commander": "^10.0.0", + "cosmiconfig": "^8.0.0", + "fast-diff": "^1.2.0", + "glob": "^8.0.3", + "ignore": "^5.2.4", + "js-yaml": "^4.1.0", + "lodash": "^4.17.21", + "pluralize": "^8.0.0", + "prettier": "^2.8.3", + "semver": "^6.3.0", + "strip-ansi": "^6.0.1", + "table": "^6.8.1", + "text-table": "^0.2.0" + }, + "dependencies": { + "@solidity-parser/parser": { + "version": "0.16.0", + "resolved": "https://registry.npmjs.org/@solidity-parser/parser/-/parser-0.16.0.tgz", + "integrity": "sha512-ESipEcHyRHg4Np4SqBCfcXwyxxna1DgFVz69bgpLV8vzl/NP1DtcKsJ4dJZXWQhY/Z4J2LeKBiOkOVZn9ct33Q==", + "dev": true, + "requires": { + "antlr4ts": "^0.5.0-alpha.4" + } + }, + "ansi-regex": { + "version": "5.0.1", + "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-5.0.1.tgz", + "integrity": "sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ==", + "dev": true + }, + "ansi-styles": { + "version": "4.3.0", + "resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-4.3.0.tgz", + "integrity": "sha512-zbB9rCJAT1rbjiVDb2hqKFHNYLxgtk8NURxZ3IZwD3F6NtxbXZQCnnSi1Lkx+IDohdPlFp222wVALIheZJQSEg==", + "dev": true, + "requires": { + "color-convert": "^2.0.1" + } + }, + "argparse": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/argparse/-/argparse-2.0.1.tgz", + "integrity": "sha512-8+9WqebbFzpX9OR+Wa6O29asIogeRMzcGtAINdpMHHyAg10f05aSFVBbcEqGf/PXw1EjAZ+q2/bEBg3DvurK3Q==", + "dev": true + }, + "chalk": { + "version": "4.1.2", + "resolved": "https://registry.npmjs.org/chalk/-/chalk-4.1.2.tgz", + "integrity": "sha512-oKnbhFyRIXpUuez8iBMmyEa4nbj4IOQyuhc/wy9kY7/WVPcwIO9VA668Pu8RkO7+0G76SLROeyw9CpQ061i4mA==", + "dev": true, + "requires": { + "ansi-styles": "^4.1.0", + "supports-color": "^7.1.0" + } + }, + "color-convert": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/color-convert/-/color-convert-2.0.1.tgz", + "integrity": "sha512-RRECPsj7iu/xb5oKYcsFHSppFNnsj/52OVTRKb4zP5onXwVF3zVmmToNcOfGC+CRDpfK/U584fMg38ZHCaElKQ==", + "dev": true, + "requires": { + "color-name": "~1.1.4" + } + }, + "color-name": { + "version": "1.1.4", + "resolved": "https://registry.npmjs.org/color-name/-/color-name-1.1.4.tgz", + "integrity": "sha512-dOy+3AuW3a2wNbZHIuMZpTcgjGuLU/uBL/ubcZF9OXbDo8ff4O8yVp5Bf0efS8uEoYo5q4Fx7dY9OgQGXgAsQA==", + "dev": true + }, + "has-flag": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/has-flag/-/has-flag-4.0.0.tgz", + "integrity": "sha512-EykJT/Q1KjTWctppgIAgfSO0tKVuZUjhgMr17kqTumMl6Afv3EISleU7qZUzoXDFTAHTDC4NOoG/ZxU3EvlMPQ==", + "dev": true + }, + "js-yaml": { + "version": "4.1.0", + "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-4.1.0.tgz", + "integrity": "sha512-wpxZs9NoxZaJESJGIZTyDEaYpl0FKSA+FB9aJiyemKhMwkxQg63h4T1KJgUGHpTqPDNRcmmYLugrRjJlBtWvRA==", + "dev": true, + "requires": { + "argparse": "^2.0.1" + } + }, + "prettier": { + "version": "2.8.8", + "resolved": "https://registry.npmjs.org/prettier/-/prettier-2.8.8.tgz", + "integrity": "sha512-tdN8qQGvNjw4CHbY+XXk0JgCXn9QiF21a55rBe5LJAU+kDyC4WQn4+awm2Xfk2lQMk5fKup9XgzTZtGkjBdP9Q==", + "dev": true, + "optional": true + }, + "semver": { + "version": "6.3.0", + "resolved": "https://registry.npmjs.org/semver/-/semver-6.3.0.tgz", + "integrity": "sha512-b39TBaTSfV6yBrapU89p5fKekE2m/NwnDocOVruQFS1/veMgdzuPcnOM34M6CwxW8jH/lxEa5rBoDeUwu5HHTw==", + "dev": true + }, + "strip-ansi": { + "version": "6.0.1", + "resolved": "https://registry.npmjs.org/strip-ansi/-/strip-ansi-6.0.1.tgz", + "integrity": "sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A==", + "dev": true, + "requires": { + "ansi-regex": "^5.0.1" + } + }, + "supports-color": { + "version": "7.2.0", + "resolved": "https://registry.npmjs.org/supports-color/-/supports-color-7.2.0.tgz", + "integrity": "sha512-qpCAvRl9stuOHveKsn7HncJRvv501qIacKzQlO/+Lwxc9+0q2wLyv4Dfvt80/DPn2pqOBsJdDiogXGR9+OvwRw==", + "dev": true, + "requires": { + "has-flag": "^4.0.0" + } + } + } + }, + "solhint-plugin-openzeppelin": { + "version": "file:scripts/solhint-custom" + }, + "solidity-ast": { + "version": "0.4.50", + "resolved": "https://registry.npmjs.org/solidity-ast/-/solidity-ast-0.4.50.tgz", + "integrity": "sha512-WpIhaUibbjcBY4bg8TO2UXFWl8PQPhtH1QtMYJUqFUGxx0rRiEFsVLV+ow8XiWEnSPeu4xPp1/K43P4esxuK1Q==", + "dev": true, + "requires": { + "array.prototype.findlast": "^1.2.2" + } + }, + "solidity-comments": { + "version": "0.0.2", + "resolved": "https://registry.npmjs.org/solidity-comments/-/solidity-comments-0.0.2.tgz", + "integrity": "sha512-G+aK6qtyUfkn1guS8uzqUeua1dURwPlcOjoTYW/TwmXAcE7z/1+oGCfZUdMSe4ZMKklNbVZNiG5ibnF8gkkFfw==", + "dev": true, + "requires": { + "solidity-comments-darwin-arm64": "0.0.2", + "solidity-comments-darwin-x64": "0.0.2", + "solidity-comments-freebsd-x64": "0.0.2", + "solidity-comments-linux-arm64-gnu": "0.0.2", + "solidity-comments-linux-arm64-musl": "0.0.2", + "solidity-comments-linux-x64-gnu": "0.0.2", + "solidity-comments-linux-x64-musl": "0.0.2", + "solidity-comments-win32-arm64-msvc": "0.0.2", + "solidity-comments-win32-ia32-msvc": "0.0.2", + "solidity-comments-win32-x64-msvc": "0.0.2" + } + }, + "solidity-comments-darwin-arm64": { + "version": "0.0.2", + "resolved": "https://registry.npmjs.org/solidity-comments-darwin-arm64/-/solidity-comments-darwin-arm64-0.0.2.tgz", + "integrity": "sha512-HidWkVLSh7v+Vu0CA7oI21GWP/ZY7ro8g8OmIxE8oTqyMwgMbE8F1yc58Sj682Hj199HCZsjmtn1BE4PCbLiGA==", + "dev": true, + "optional": true + }, + "solidity-comments-darwin-x64": { + "version": "0.0.2", + "resolved": "https://registry.npmjs.org/solidity-comments-darwin-x64/-/solidity-comments-darwin-x64-0.0.2.tgz", + "integrity": "sha512-Zjs0Ruz6faBTPT6fBecUt6qh4CdloT8Bwoc0+qxRoTn9UhYscmbPQkUgQEbS0FQPysYqVzzxJB4h1Ofbf4wwtA==", + "dev": true, + "optional": true + }, + "solidity-comments-extractor": { + "version": "0.0.7", + "resolved": "https://registry.npmjs.org/solidity-comments-extractor/-/solidity-comments-extractor-0.0.7.tgz", + "integrity": "sha512-wciNMLg/Irp8OKGrh3S2tfvZiZ0NEyILfcRCXCD4mp7SgK/i9gzLfhY2hY7VMCQJ3kH9UB9BzNdibIVMchzyYw==", + "dev": true + }, + "solidity-comments-freebsd-x64": { + "version": "0.0.2", + "resolved": "https://registry.npmjs.org/solidity-comments-freebsd-x64/-/solidity-comments-freebsd-x64-0.0.2.tgz", + "integrity": "sha512-8Qe4mpjuAxFSwZJVk7B8gAoLCdbtS412bQzBwk63L8dmlHogvE39iT70aAk3RHUddAppT5RMBunlPUCFYJ3ZTw==", + "dev": true, + "optional": true + }, + "solidity-comments-linux-arm64-gnu": { + "version": "0.0.2", + "resolved": "https://registry.npmjs.org/solidity-comments-linux-arm64-gnu/-/solidity-comments-linux-arm64-gnu-0.0.2.tgz", + "integrity": "sha512-spkb0MZZnmrP+Wtq4UxP+nyPAVRe82idOjqndolcNR0S9Xvu4ebwq+LvF4HiUgjTDmeiqYiFZQ8T9KGdLSIoIg==", + "dev": true, + "optional": true + }, + "solidity-comments-linux-arm64-musl": { + "version": "0.0.2", + "resolved": "https://registry.npmjs.org/solidity-comments-linux-arm64-musl/-/solidity-comments-linux-arm64-musl-0.0.2.tgz", + "integrity": "sha512-guCDbHArcjE+JDXYkxx5RZzY1YF6OnAKCo+sTC5fstyW/KGKaQJNPyBNWuwYsQiaEHpvhW1ha537IvlGek8GqA==", + "dev": true, + "optional": true + }, + "solidity-comments-linux-x64-gnu": { + "version": "0.0.2", + "resolved": "https://registry.npmjs.org/solidity-comments-linux-x64-gnu/-/solidity-comments-linux-x64-gnu-0.0.2.tgz", + "integrity": "sha512-zIqLehBK/g7tvrFmQljrfZXfkEeLt2v6wbe+uFu6kH/qAHZa7ybt8Vc0wYcmjo2U0PeBm15d79ee3AkwbIjFdQ==", + "dev": true, + "optional": true + }, + "solidity-comments-linux-x64-musl": { + "version": "0.0.2", + "resolved": "https://registry.npmjs.org/solidity-comments-linux-x64-musl/-/solidity-comments-linux-x64-musl-0.0.2.tgz", + "integrity": "sha512-R9FeDloVlFGTaVkOlELDVC7+1Tjx5WBPI5L8r0AGOPHK3+jOcRh6sKYpI+VskSPDc3vOO46INkpDgUXrKydlIw==", + "dev": true, + "optional": true + }, + "solidity-comments-win32-arm64-msvc": { + "version": "0.0.2", + "resolved": "https://registry.npmjs.org/solidity-comments-win32-arm64-msvc/-/solidity-comments-win32-arm64-msvc-0.0.2.tgz", + "integrity": "sha512-QnWJoCQcJj+rnutULOihN9bixOtYWDdF5Rfz9fpHejL1BtNjdLW1om55XNVHGAHPqBxV4aeQQ6OirKnp9zKsug==", + "dev": true, + "optional": true + }, + "solidity-comments-win32-ia32-msvc": { + "version": "0.0.2", + "resolved": "https://registry.npmjs.org/solidity-comments-win32-ia32-msvc/-/solidity-comments-win32-ia32-msvc-0.0.2.tgz", + "integrity": "sha512-vUg4nADtm/NcOtlIymG23NWJUSuMsvX15nU7ynhGBsdKtt8xhdP3C/zA6vjDk8Jg+FXGQL6IHVQ++g/7rSQi0w==", + "dev": true, + "optional": true + }, + "solidity-comments-win32-x64-msvc": { + "version": "0.0.2", + "resolved": "https://registry.npmjs.org/solidity-comments-win32-x64-msvc/-/solidity-comments-win32-x64-msvc-0.0.2.tgz", + "integrity": "sha512-36j+KUF4V/y0t3qatHm/LF5sCUCBx2UndxE1kq5bOzh/s+nQgatuyB+Pd5BfuPQHdWu2KaExYe20FlAa6NL7+Q==", + "dev": true, + "optional": true + }, + "solidity-coverage": { + "version": "0.8.4", + "resolved": "https://registry.npmjs.org/solidity-coverage/-/solidity-coverage-0.8.4.tgz", + "integrity": "sha512-xeHOfBOjdMF6hWTbt42iH4x+7j1Atmrf5OldDPMxI+i/COdExUxszOswD9qqvcBTaLGiOrrpnh9UZjSpt4rBsg==", + "dev": true, + "requires": { + "@ethersproject/abi": "^5.0.9", + "@solidity-parser/parser": "^0.16.0", + "chalk": "^2.4.2", + "death": "^1.1.0", + "detect-port": "^1.3.0", + "difflib": "^0.2.4", + "fs-extra": "^8.1.0", + "ghost-testrpc": "^0.0.2", + "global-modules": "^2.0.0", + "globby": "^10.0.1", + "jsonschema": "^1.2.4", + "lodash": "^4.17.15", + "mocha": "7.1.2", + "node-emoji": "^1.10.0", + "pify": "^4.0.1", + "recursive-readdir": "^2.2.2", + "sc-istanbul": "^0.4.5", + "semver": "^7.3.4", + "shelljs": "^0.8.3", + "web3-utils": "^1.3.6" + }, + "dependencies": { + "@solidity-parser/parser": { + "version": "0.16.1", + "resolved": "https://registry.npmjs.org/@solidity-parser/parser/-/parser-0.16.1.tgz", + "integrity": "sha512-PdhRFNhbTtu3x8Axm0uYpqOy/lODYQK+MlYSgqIsq2L8SFYEHJPHNUiOTAJbDGzNjjr1/n9AcIayxafR/fWmYw==", + "dev": true, + "requires": { + "antlr4ts": "^0.5.0-alpha.4" + } + }, + "ansi-colors": { + "version": "3.2.3", + "resolved": "https://registry.npmjs.org/ansi-colors/-/ansi-colors-3.2.3.tgz", + "integrity": "sha512-LEHHyuhlPY3TmuUYMh2oz89lTShfvgbmzaBcxve9t/9Wuy7Dwf4yoAKcND7KFT1HAQfqZ12qtc+DUrBMeKF9nw==", + "dev": true + }, + "ansi-regex": { + "version": "4.1.1", + "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-4.1.1.tgz", + "integrity": "sha512-ILlv4k/3f6vfQ4OoP2AGvirOktlQ98ZEL1k9FaQjxa3L1abBgbuTDAdPOpvbGncC0BTVQrl+OM8xZGK6tWXt7g==", + "dev": true + }, + "camelcase": { + "version": "5.3.1", + "resolved": "https://registry.npmjs.org/camelcase/-/camelcase-5.3.1.tgz", + "integrity": "sha512-L28STB170nwWS63UjtlEOE3dldQApaJXZkOI1uMFfzf3rRuPegHaHesyee+YxQ+W6SvRDQV6UrdOdRiR153wJg==", + "dev": true + }, + "chokidar": { + "version": "3.3.0", + "resolved": "https://registry.npmjs.org/chokidar/-/chokidar-3.3.0.tgz", + "integrity": "sha512-dGmKLDdT3Gdl7fBUe8XK+gAtGmzy5Fn0XkkWQuYxGIgWVPPse2CxFA5mtrlD0TOHaHjEUqkWNyP1XdHoJES/4A==", + "dev": true, + "requires": { + "anymatch": "~3.1.1", + "braces": "~3.0.2", + "fsevents": "~2.1.1", + "glob-parent": "~5.1.0", + "is-binary-path": "~2.1.0", + "is-glob": "~4.0.1", + "normalize-path": "~3.0.0", + "readdirp": "~3.2.0" + } + }, + "cliui": { + "version": "5.0.0", + "resolved": "https://registry.npmjs.org/cliui/-/cliui-5.0.0.tgz", + "integrity": "sha512-PYeGSEmmHM6zvoef2w8TPzlrnNpXIjTipYK780YswmIP9vjxmd6Y2a3CB2Ks6/AU8NHjZugXvo8w3oWM2qnwXA==", + "dev": true, + "requires": { + "string-width": "^3.1.0", + "strip-ansi": "^5.2.0", + "wrap-ansi": "^5.1.0" + } + }, + "debug": { + "version": "3.2.6", + "resolved": "https://registry.npmjs.org/debug/-/debug-3.2.6.tgz", + "integrity": "sha512-mel+jf7nrtEl5Pn1Qx46zARXKDpBbvzezse7p7LqINmdoIk8PYP5SySaxEmYv6TZ0JyEKA1hsCId6DIhgITtWQ==", + "dev": true, + "requires": { + "ms": "^2.1.1" + } + }, + "diff": { + "version": "3.5.0", + "resolved": "https://registry.npmjs.org/diff/-/diff-3.5.0.tgz", + "integrity": "sha512-A46qtFgd+g7pDZinpnwiRJtxbC1hpgf0uzP3iG89scHk0AUC7A1TGxf5OiiOUv/JMZR8GOt8hL900hV0bOy5xA==", + "dev": true + }, + "emoji-regex": { + "version": "7.0.3", + "resolved": "https://registry.npmjs.org/emoji-regex/-/emoji-regex-7.0.3.tgz", + "integrity": "sha512-CwBLREIQ7LvYFB0WyRvwhq5N5qPhc6PMjD6bYggFlI5YyDgl+0vxq5VHbMOFqLg7hfWzmu8T5Z1QofhmTIhItA==", + "dev": true + }, + "find-up": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/find-up/-/find-up-3.0.0.tgz", + "integrity": "sha512-1yD6RmLI1XBfxugvORwlck6f75tYL+iR0jqwsOrOxMZyGYqUuDhJ0l4AXdO1iX/FTs9cBAMEk1gWSEx1kSbylg==", + "dev": true, + "requires": { + "locate-path": "^3.0.0" + } + }, + "flat": { + "version": "4.1.1", + "resolved": "https://registry.npmjs.org/flat/-/flat-4.1.1.tgz", + "integrity": "sha512-FmTtBsHskrU6FJ2VxCnsDb84wu9zhmO3cUX2kGFb5tuwhfXxGciiT0oRY+cck35QmG+NmGh5eLz6lLCpWTqwpA==", + "dev": true, + "requires": { + "is-buffer": "~2.0.3" + } + }, + "fs-extra": { + "version": "8.1.0", + "resolved": "https://registry.npmjs.org/fs-extra/-/fs-extra-8.1.0.tgz", + "integrity": "sha512-yhlQgA6mnOJUKOsRUFsgJdQCvkKhcz8tlZG5HBQfReYZy46OwLcY+Zia0mtdHsOo9y/hP+CxMN0TU9QxoOtG4g==", + "dev": true, + "requires": { + "graceful-fs": "^4.2.0", + "jsonfile": "^4.0.0", + "universalify": "^0.1.0" + } + }, + "fsevents": { + "version": "2.1.3", + "resolved": "https://registry.npmjs.org/fsevents/-/fsevents-2.1.3.tgz", + "integrity": "sha512-Auw9a4AxqWpa9GUfj370BMPzzyncfBABW8Mab7BGWBYDj4Isgq+cDKtx0i6u9jcX9pQDnswsaaOTgTmA5pEjuQ==", + "dev": true, + "optional": true + }, + "glob": { + "version": "7.2.3", + "resolved": "https://registry.npmjs.org/glob/-/glob-7.2.3.tgz", + "integrity": "sha512-nFR0zLpU2YCaRxwoCJvL6UvCH2JFyFVIvwTLsIf21AuHlMskA1hhTdk+LlYJtOlYt9v6dvszD2BGRqBL+iQK9Q==", + "dev": true, + "requires": { + "fs.realpath": "^1.0.0", + "inflight": "^1.0.4", + "inherits": "2", + "minimatch": "^3.1.1", + "once": "^1.3.0", + "path-is-absolute": "^1.0.0" + } + }, + "globby": { + "version": "10.0.2", + "resolved": "https://registry.npmjs.org/globby/-/globby-10.0.2.tgz", + "integrity": "sha512-7dUi7RvCoT/xast/o/dLN53oqND4yk0nsHkhRgn9w65C4PofCLOoJ39iSOg+qVDdWQPIEj+eszMHQ+aLVwwQSg==", + "dev": true, + "requires": { + "@types/glob": "^7.1.1", + "array-union": "^2.1.0", + "dir-glob": "^3.0.1", + "fast-glob": "^3.0.3", + "glob": "^7.1.3", + "ignore": "^5.1.1", + "merge2": "^1.2.3", + "slash": "^3.0.0" + } + }, + "js-yaml": { + "version": "3.13.1", + "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-3.13.1.tgz", + "integrity": "sha512-YfbcO7jXDdyj0DGxYVSlSeQNHbD7XPWvrVWeVUujrQEoZzWJIRrCPoyk6kL6IAjAG2IolMK4T0hNUe0HOUs5Jw==", + "dev": true, + "requires": { + "argparse": "^1.0.7", + "esprima": "^4.0.0" + } + }, + "locate-path": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/locate-path/-/locate-path-3.0.0.tgz", + "integrity": "sha512-7AO748wWnIhNqAuaty2ZWHkQHRSNfPVIsPIfwEOWO22AmaoVrWavlOcMR5nzTLNYvp36X220/maaRsrec1G65A==", + "dev": true, + "requires": { + "p-locate": "^3.0.0", + "path-exists": "^3.0.0" + } + }, + "log-symbols": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/log-symbols/-/log-symbols-3.0.0.tgz", + "integrity": "sha512-dSkNGuI7iG3mfvDzUuYZyvk5dD9ocYCYzNU6CYDE6+Xqd+gwme6Z00NS3dUh8mq/73HaEtT7m6W+yUPtU6BZnQ==", + "dev": true, + "requires": { + "chalk": "^2.4.2" + } + }, + "mkdirp": { + "version": "0.5.5", + "resolved": "https://registry.npmjs.org/mkdirp/-/mkdirp-0.5.5.tgz", + "integrity": "sha512-NKmAlESf6jMGym1++R0Ra7wvhV+wFW63FaSOFPwRahvea0gMUcGUhVeAg/0BC0wiv9ih5NYPB1Wn1UEI1/L+xQ==", + "dev": true, + "requires": { + "minimist": "^1.2.5" + } + }, + "mocha": { + "version": "7.1.2", + "resolved": "https://registry.npmjs.org/mocha/-/mocha-7.1.2.tgz", + "integrity": "sha512-o96kdRKMKI3E8U0bjnfqW4QMk12MwZ4mhdBTf+B5a1q9+aq2HRnj+3ZdJu0B/ZhJeK78MgYuv6L8d/rA5AeBJA==", + "dev": true, + "requires": { + "ansi-colors": "3.2.3", + "browser-stdout": "1.3.1", + "chokidar": "3.3.0", + "debug": "3.2.6", + "diff": "3.5.0", + "escape-string-regexp": "1.0.5", + "find-up": "3.0.0", + "glob": "7.1.3", + "growl": "1.10.5", + "he": "1.2.0", + "js-yaml": "3.13.1", + "log-symbols": "3.0.0", + "minimatch": "3.0.4", + "mkdirp": "0.5.5", + "ms": "2.1.1", + "node-environment-flags": "1.0.6", + "object.assign": "4.1.0", + "strip-json-comments": "2.0.1", + "supports-color": "6.0.0", + "which": "1.3.1", + "wide-align": "1.1.3", + "yargs": "13.3.2", + "yargs-parser": "13.1.2", + "yargs-unparser": "1.6.0" + }, + "dependencies": { + "glob": { + "version": "7.1.3", + "resolved": "https://registry.npmjs.org/glob/-/glob-7.1.3.tgz", + "integrity": "sha512-vcfuiIxogLV4DlGBHIUOwI0IbrJ8HWPc4MU7HzviGeNho/UJDfi6B5p3sHeWIQ0KGIU0Jpxi5ZHxemQfLkkAwQ==", + "dev": true, + "requires": { + "fs.realpath": "^1.0.0", + "inflight": "^1.0.4", + "inherits": "2", + "minimatch": "^3.0.4", + "once": "^1.3.0", + "path-is-absolute": "^1.0.0" + } + }, + "minimatch": { + "version": "3.0.4", + "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-3.0.4.tgz", + "integrity": "sha512-yJHVQEhyqPLUTgt9B83PXu6W3rx4MvvHvSUvToogpwoGDOUQ+yDrR0HRot+yOCdCO7u4hX3pWft6kWBBcqh0UA==", + "dev": true, + "requires": { + "brace-expansion": "^1.1.7" + } + } + } + }, + "ms": { + "version": "2.1.1", + "resolved": "https://registry.npmjs.org/ms/-/ms-2.1.1.tgz", + "integrity": "sha512-tgp+dl5cGk28utYktBsrFqA7HKgrhgPsg6Z/EfhWI4gl1Hwq8B/GmY/0oXZ6nF8hDVesS/FpnYaD/kOWhYQvyg==", + "dev": true + }, + "object.assign": { + "version": "4.1.0", + "resolved": "https://registry.npmjs.org/object.assign/-/object.assign-4.1.0.tgz", + "integrity": "sha512-exHJeq6kBKj58mqGyTQ9DFvrZC/eR6OwxzoM9YRoGBqrXYonaFyGiFMuc9VZrXf7DarreEwMpurG3dd+CNyW5w==", + "dev": true, + "requires": { + "define-properties": "^1.1.2", + "function-bind": "^1.1.1", + "has-symbols": "^1.0.0", + "object-keys": "^1.0.11" + } + }, + "p-limit": { + "version": "2.3.0", + "resolved": "https://registry.npmjs.org/p-limit/-/p-limit-2.3.0.tgz", + "integrity": "sha512-//88mFWSJx8lxCzwdAABTJL2MyWB12+eIY7MDL2SqLmAkeKU9qxRvWuSyTjm3FUmpBEMuFfckAIqEaVGUDxb6w==", + "dev": true, + "requires": { + "p-try": "^2.0.0" + } + }, + "p-locate": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/p-locate/-/p-locate-3.0.0.tgz", + "integrity": "sha512-x+12w/To+4GFfgJhBEpiDcLozRJGegY+Ei7/z0tSLkMmxGZNybVMSfWj9aJn8Z5Fc7dBUNJOOVgPv2H7IwulSQ==", + "dev": true, + "requires": { + "p-limit": "^2.0.0" + } + }, + "path-exists": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/path-exists/-/path-exists-3.0.0.tgz", + "integrity": "sha512-bpC7GYwiDYQ4wYLe+FA8lhRjhQCMcQGuSgGGqDkg/QerRWw9CmGRT0iSOVRSZJ29NMLZgIzqaljJ63oaL4NIJQ==", + "dev": true + }, + "readdirp": { + "version": "3.2.0", + "resolved": "https://registry.npmjs.org/readdirp/-/readdirp-3.2.0.tgz", + "integrity": "sha512-crk4Qu3pmXwgxdSgGhgA/eXiJAPQiX4GMOZZMXnqKxHX7TaoL+3gQVo/WeuAiogr07DpnfjIMpXXa+PAIvwPGQ==", + "dev": true, + "requires": { + "picomatch": "^2.0.4" + } + }, + "string-width": { + "version": "3.1.0", + "resolved": "https://registry.npmjs.org/string-width/-/string-width-3.1.0.tgz", + "integrity": "sha512-vafcv6KjVZKSgz06oM/H6GDBrAtz8vdhQakGjFIvNrHA6y3HCF1CInLy+QLq8dTJPQ1b+KDUqDFctkdRW44e1w==", + "dev": true, + "requires": { + "emoji-regex": "^7.0.1", + "is-fullwidth-code-point": "^2.0.0", + "strip-ansi": "^5.1.0" + } + }, + "strip-ansi": { + "version": "5.2.0", + "resolved": "https://registry.npmjs.org/strip-ansi/-/strip-ansi-5.2.0.tgz", + "integrity": "sha512-DuRs1gKbBqsMKIZlrffwlug8MHkcnpjs5VPmL1PAh+mA30U0DTotfDZ0d2UUsXpPmPmMMJ6W773MaA3J+lbiWA==", + "dev": true, + "requires": { + "ansi-regex": "^4.1.0" + } + }, + "strip-json-comments": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/strip-json-comments/-/strip-json-comments-2.0.1.tgz", + "integrity": "sha512-4gB8na07fecVVkOI6Rs4e7T6NOTki5EmL7TUduTs6bu3EdnSycntVJ4re8kgZA+wx9IueI2Y11bfbgwtzuE0KQ==", + "dev": true + }, + "supports-color": { + "version": "6.0.0", + "resolved": "https://registry.npmjs.org/supports-color/-/supports-color-6.0.0.tgz", + "integrity": "sha512-on9Kwidc1IUQo+bQdhi8+Tijpo0e1SS6RoGo2guUwn5vdaxw8RXOF9Vb2ws+ihWOmh4JnCJOvaziZWP1VABaLg==", + "dev": true, + "requires": { + "has-flag": "^3.0.0" + } + }, + "which": { + "version": "1.3.1", + "resolved": "https://registry.npmjs.org/which/-/which-1.3.1.tgz", + "integrity": "sha512-HxJdYWq1MTIQbJ3nw0cqssHoTNU267KlrDuGZ1WYlxDStUtKUhOaJmh112/TZmHxxUfuJqPXSOm7tDyas0OSIQ==", + "dev": true, + "requires": { + "isexe": "^2.0.0" + } + }, + "wrap-ansi": { + "version": "5.1.0", + "resolved": "https://registry.npmjs.org/wrap-ansi/-/wrap-ansi-5.1.0.tgz", + "integrity": "sha512-QC1/iN/2/RPVJ5jYK8BGttj5z83LmSKmvbvrXPNCLZSEb32KKVDJDl/MOt2N01qU2H/FkzEa9PKto1BqDjtd7Q==", + "dev": true, + "requires": { + "ansi-styles": "^3.2.0", + "string-width": "^3.0.0", + "strip-ansi": "^5.0.0" + } + }, + "y18n": { + "version": "4.0.3", + "resolved": "https://registry.npmjs.org/y18n/-/y18n-4.0.3.tgz", + "integrity": "sha512-JKhqTOwSrqNA1NY5lSztJ1GrBiUodLMmIZuLiDaMRJ+itFd+ABVE8XBjOvIWL+rSqNDC74LCSFmlb/U4UZ4hJQ==", + "dev": true + }, + "yargs": { + "version": "13.3.2", + "resolved": "https://registry.npmjs.org/yargs/-/yargs-13.3.2.tgz", + "integrity": "sha512-AX3Zw5iPruN5ie6xGRIDgqkT+ZhnRlZMLMHAs8tg7nRruy2Nb+i5o9bwghAogtM08q1dpr2LVoS8KSTMYpWXUw==", + "dev": true, + "requires": { + "cliui": "^5.0.0", + "find-up": "^3.0.0", + "get-caller-file": "^2.0.1", + "require-directory": "^2.1.1", + "require-main-filename": "^2.0.0", + "set-blocking": "^2.0.0", + "string-width": "^3.0.0", + "which-module": "^2.0.0", + "y18n": "^4.0.0", + "yargs-parser": "^13.1.2" + } + }, + "yargs-parser": { + "version": "13.1.2", + "resolved": "https://registry.npmjs.org/yargs-parser/-/yargs-parser-13.1.2.tgz", + "integrity": "sha512-3lbsNRf/j+A4QuSZfDRA7HRSfWrzO0YjqTJd5kjAq37Zep1CEgaYmrH9Q3GwPiB9cHyd1Y1UwggGhJGoxipbzg==", + "dev": true, + "requires": { + "camelcase": "^5.0.0", + "decamelize": "^1.2.0" + } + }, + "yargs-unparser": { + "version": "1.6.0", + "resolved": "https://registry.npmjs.org/yargs-unparser/-/yargs-unparser-1.6.0.tgz", + "integrity": "sha512-W9tKgmSn0DpSatfri0nx52Joq5hVXgeLiqR/5G0sZNDoLZFOr/xjBUDcShCOGNsBnEMNo1KAMBkTej1Hm62HTw==", + "dev": true, + "requires": { + "flat": "^4.1.0", + "lodash": "^4.17.15", + "yargs": "^13.3.0" + } + } + } + }, + "solidity-docgen": { + "version": "0.6.0-beta.35", + "resolved": "https://registry.npmjs.org/solidity-docgen/-/solidity-docgen-0.6.0-beta.35.tgz", + "integrity": "sha512-9QdwK1THk/MWIdq1PEW/6dvtND0pUqpFTsbKwwU9YQIMYuRhH1lek9SsgnsGGYtdJ0VTrXXcVT30q20a8Y610A==", + "dev": true, + "requires": { + "handlebars": "^4.7.7", + "solidity-ast": "^0.4.38" + } + }, + "source-map": { + "version": "0.2.0", + "resolved": "https://registry.npmjs.org/source-map/-/source-map-0.2.0.tgz", + "integrity": "sha512-CBdZ2oa/BHhS4xj5DlhjWNHcan57/5YuvfdLf17iVmIpd9KRm+DFLmC6nBNj+6Ua7Kt3TmOjDpQT1aTYOQtoUA==", + "dev": true, + "optional": true, + "requires": { + "amdefine": ">=0.0.4" + } + }, + "source-map-support": { + "version": "0.5.21", + "resolved": "https://registry.npmjs.org/source-map-support/-/source-map-support-0.5.21.tgz", + "integrity": "sha512-uBHU3L3czsIyYXKX88fdrGovxdSCoTGDRZ6SYXtSRxLZUzHg5P/66Ht6uoUlHu9EZod+inXhKo3qQgwXUT/y1w==", + "dev": true, + "requires": { + "buffer-from": "^1.0.0", + "source-map": "^0.6.0" + }, + "dependencies": { + "source-map": { + "version": "0.6.1", + "resolved": "https://registry.npmjs.org/source-map/-/source-map-0.6.1.tgz", + "integrity": "sha512-UjgapumWlbMhkBgzT7Ykc5YXUT46F0iKu8SGXq0bcwP5dz/h0Plj6enJqjz1Zbq2l5WaqYnrVbwWOWMyF3F47g==", + "dev": true + } + } + }, + "spawndamnit": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/spawndamnit/-/spawndamnit-2.0.0.tgz", + "integrity": "sha512-j4JKEcncSjFlqIwU5L/rp2N5SIPsdxaRsIv678+TZxZ0SRDJTm8JrxJMjE/XuiEZNEir3S8l0Fa3Ke339WI4qA==", + "dev": true, + "requires": { + "cross-spawn": "^5.1.0", + "signal-exit": "^3.0.2" + }, + "dependencies": { + "cross-spawn": { + "version": "5.1.0", + "resolved": "https://registry.npmjs.org/cross-spawn/-/cross-spawn-5.1.0.tgz", + "integrity": "sha512-pTgQJ5KC0d2hcY8eyL1IzlBPYjTkyH72XRZPnLyKus2mBfNjQs3klqbJU2VILqZryAZUt9JOb3h/mWMy23/f5A==", + "dev": true, + "requires": { + "lru-cache": "^4.0.1", + "shebang-command": "^1.2.0", + "which": "^1.2.9" + } + }, + "lru-cache": { + "version": "4.1.5", + "resolved": "https://registry.npmjs.org/lru-cache/-/lru-cache-4.1.5.tgz", + "integrity": "sha512-sWZlbEP2OsHNkXrMl5GYk/jKk70MBng6UU4YI/qGDYbgf6YbP4EvmqISbXCoJiRKs+1bSpFHVgQxvJ17F2li5g==", + "dev": true, + "requires": { + "pseudomap": "^1.0.2", + "yallist": "^2.1.2" + } + }, + "shebang-command": { + "version": "1.2.0", + "resolved": "https://registry.npmjs.org/shebang-command/-/shebang-command-1.2.0.tgz", + "integrity": "sha512-EV3L1+UQWGor21OmnvojK36mhg+TyIKDh3iFBKBohr5xeXIhNBcx8oWdgkTEEQ+BEFFYdLRuqMfd5L84N1V5Vg==", + "dev": true, + "requires": { + "shebang-regex": "^1.0.0" + } + }, + "shebang-regex": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/shebang-regex/-/shebang-regex-1.0.0.tgz", + "integrity": "sha512-wpoSFAxys6b2a2wHZ1XpDSgD7N9iVjg29Ph9uV/uaP9Ex/KXlkTZTeddxDPSYQpgvzKLGJke2UU0AzoGCjNIvQ==", + "dev": true + }, + "which": { + "version": "1.3.1", + "resolved": "https://registry.npmjs.org/which/-/which-1.3.1.tgz", + "integrity": "sha512-HxJdYWq1MTIQbJ3nw0cqssHoTNU267KlrDuGZ1WYlxDStUtKUhOaJmh112/TZmHxxUfuJqPXSOm7tDyas0OSIQ==", + "dev": true, + "requires": { + "isexe": "^2.0.0" + } + }, + "yallist": { + "version": "2.1.2", + "resolved": "https://registry.npmjs.org/yallist/-/yallist-2.1.2.tgz", + "integrity": "sha512-ncTzHV7NvsQZkYe1DW7cbDLm0YpzHmZF5r/iyP3ZnQtMiJ+pjzisCiMNI+Sj+xQF5pXhSHxSB3uDbsBTzY/c2A==", + "dev": true + } + } + }, + "spdx-correct": { + "version": "3.2.0", + "resolved": "https://registry.npmjs.org/spdx-correct/-/spdx-correct-3.2.0.tgz", + "integrity": "sha512-kN9dJbvnySHULIluDHy32WHRUu3Og7B9sbY7tsFLctQkIqnMh3hErYgdMjTYuqmcXX+lK5T1lnUt3G7zNswmZA==", + "dev": true, + "requires": { + "spdx-expression-parse": "^3.0.0", + "spdx-license-ids": "^3.0.0" + } + }, + "spdx-exceptions": { + "version": "2.3.0", + "resolved": "https://registry.npmjs.org/spdx-exceptions/-/spdx-exceptions-2.3.0.tgz", + "integrity": "sha512-/tTrYOC7PPI1nUAgx34hUpqXuyJG+DTHJTnIULG4rDygi4xu/tfgmq1e1cIRwRzwZgo4NLySi+ricLkZkw4i5A==", + "dev": true + }, + "spdx-expression-parse": { + "version": "3.0.1", + "resolved": "https://registry.npmjs.org/spdx-expression-parse/-/spdx-expression-parse-3.0.1.tgz", + "integrity": "sha512-cbqHunsQWnJNE6KhVSMsMeH5H/L9EpymbzqTQ3uLwNCLZ1Q481oWaofqH7nO6V07xlXwY6PhQdQ2IedWx/ZK4Q==", + "dev": true, + "requires": { + "spdx-exceptions": "^2.1.0", + "spdx-license-ids": "^3.0.0" + } + }, + "spdx-license-ids": { + "version": "3.0.13", + "resolved": "https://registry.npmjs.org/spdx-license-ids/-/spdx-license-ids-3.0.13.tgz", + "integrity": "sha512-XkD+zwiqXHikFZm4AX/7JSCXA98U5Db4AFd5XUg/+9UNtnH75+Z9KxtpYiJZx36mUDVOwH83pl7yvCer6ewM3w==", + "dev": true + }, + "sprintf-js": { + "version": "1.0.3", + "resolved": "https://registry.npmjs.org/sprintf-js/-/sprintf-js-1.0.3.tgz", + "integrity": "sha512-D9cPgkvLlV3t3IzL0D0YLvGA9Ahk4PcvVwUbN0dSGr1aP0Nrt4AEnTUbuGvquEC0mA64Gqt1fzirlRs5ibXx8g==", + "dev": true + }, + "sshpk": { + "version": "1.17.0", + "resolved": "https://registry.npmjs.org/sshpk/-/sshpk-1.17.0.tgz", + "integrity": "sha512-/9HIEs1ZXGhSPE8X6Ccm7Nam1z8KcoCqPdI7ecm1N33EzAetWahvQWVqLZtaZQ+IDKX4IyA2o0gBzqIMkAagHQ==", + "dev": true, + "requires": { + "asn1": "~0.2.3", + "assert-plus": "^1.0.0", + "bcrypt-pbkdf": "^1.0.0", + "dashdash": "^1.12.0", + "ecc-jsbn": "~0.1.1", + "getpass": "^0.1.1", + "jsbn": "~0.1.0", + "safer-buffer": "^2.0.2", + "tweetnacl": "~0.14.0" + }, + "dependencies": { + "tweetnacl": { + "version": "0.14.5", + "resolved": "https://registry.npmjs.org/tweetnacl/-/tweetnacl-0.14.5.tgz", + "integrity": "sha512-KXXFFdAbFXY4geFIwoyNK+f5Z1b7swfXABfL7HXCmoIWMKU3dmS26672A4EeQtDzLKy7SXmfBu51JolvEKwtGA==", + "dev": true + } + } + }, + "stacktrace-parser": { + "version": "0.1.10", + "resolved": "https://registry.npmjs.org/stacktrace-parser/-/stacktrace-parser-0.1.10.tgz", + "integrity": "sha512-KJP1OCML99+8fhOHxwwzyWrlUuVX5GQ0ZpJTd1DFXhdkrvg1szxfHhawXUZ3g9TkXORQd4/WG68jMlQZ2p8wlg==", + "dev": true, + "requires": { + "type-fest": "^0.7.1" + }, + "dependencies": { + "type-fest": { + "version": "0.7.1", + "resolved": "https://registry.npmjs.org/type-fest/-/type-fest-0.7.1.tgz", + "integrity": "sha512-Ne2YiiGN8bmrmJJEuTWTLJR32nh/JdL1+PSicowtNb0WFpn59GK8/lfD61bVtzguz7b3PBt74nxpv/Pw5po5Rg==", + "dev": true + } + } + }, + "statuses": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/statuses/-/statuses-2.0.1.tgz", + "integrity": "sha512-RwNA9Z/7PrK06rYLIzFMlaF+l73iwpzsqRIFgbMLbTcLD6cOao82TaWefPXQvB2fOC4AjuYSEndS7N/mTCbkdQ==", + "dev": true + }, + "stealthy-require": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/stealthy-require/-/stealthy-require-1.1.1.tgz", + "integrity": "sha512-ZnWpYnYugiOVEY5GkcuJK1io5V8QmNYChG62gSit9pQVGErXtrKuPC55ITaVSukmMta5qpMU7vqLt2Lnni4f/g==", + "dev": true + }, + "stream-transform": { + "version": "2.1.3", + "resolved": "https://registry.npmjs.org/stream-transform/-/stream-transform-2.1.3.tgz", + "integrity": "sha512-9GHUiM5hMiCi6Y03jD2ARC1ettBXkQBoQAe7nJsPknnI0ow10aXjTnew8QtYQmLjzn974BnmWEAJgCY6ZP1DeQ==", + "dev": true, + "requires": { + "mixme": "^0.5.1" + } + }, + "streamsearch": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/streamsearch/-/streamsearch-1.1.0.tgz", + "integrity": "sha512-Mcc5wHehp9aXz1ax6bZUyY5afg9u2rv5cqQI3mRrYkGC8rW2hM02jWuwjtL++LS5qinSyhj2QfLyNsuc+VsExg==", + "dev": true + }, + "strict-uri-encode": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/strict-uri-encode/-/strict-uri-encode-1.1.0.tgz", + "integrity": "sha512-R3f198pcvnB+5IpnBlRkphuE9n46WyVl8I39W/ZUTZLz4nqSP/oLYUrcnJrw462Ds8he4YKMov2efsTIw1BDGQ==", + "dev": true + }, + "string_decoder": { + "version": "1.3.0", + "resolved": "https://registry.npmjs.org/string_decoder/-/string_decoder-1.3.0.tgz", + "integrity": "sha512-hkRX8U1WjJFd8LsDJ2yQ/wWWxaopEsABU1XfkM8A+j0+85JAGppt16cr1Whg6KIbb4okU6Mql6BOj+uup/wKeA==", + "dev": true, + "requires": { + "safe-buffer": "~5.2.0" + } + }, + "string-width": { + "version": "2.1.1", + "resolved": "https://registry.npmjs.org/string-width/-/string-width-2.1.1.tgz", + "integrity": "sha512-nOqH59deCq9SRHlxq1Aw85Jnt4w6KvLKqWVik6oA9ZklXLNIOlqg4F2yrT1MVaTjAqvVwdfeZ7w7aCvJD7ugkw==", + "dev": true, + "requires": { + "is-fullwidth-code-point": "^2.0.0", + "strip-ansi": "^4.0.0" + } + }, + "string.prototype.trim": { + "version": "1.2.7", + "resolved": "https://registry.npmjs.org/string.prototype.trim/-/string.prototype.trim-1.2.7.tgz", + "integrity": "sha512-p6TmeT1T3411M8Cgg9wBTMRtY2q9+PNy9EV1i2lIXUN/btt763oIfxwN3RR8VU6wHX8j/1CFy0L+YuThm6bgOg==", + "dev": true, + "requires": { + "call-bind": "^1.0.2", + "define-properties": "^1.1.4", + "es-abstract": "^1.20.4" + } + }, + "string.prototype.trimend": { + "version": "1.0.6", + "resolved": "https://registry.npmjs.org/string.prototype.trimend/-/string.prototype.trimend-1.0.6.tgz", + "integrity": "sha512-JySq+4mrPf9EsDBEDYMOb/lM7XQLulwg5R/m1r0PXEFqrV0qHvl58sdTilSXtKOflCsK2E8jxf+GKC0T07RWwQ==", + "dev": true, + "requires": { + "call-bind": "^1.0.2", + "define-properties": "^1.1.4", + "es-abstract": "^1.20.4" + } + }, + "string.prototype.trimstart": { + "version": "1.0.6", + "resolved": "https://registry.npmjs.org/string.prototype.trimstart/-/string.prototype.trimstart-1.0.6.tgz", + "integrity": "sha512-omqjMDaY92pbn5HOX7f9IccLA+U1tA9GvtU4JrodiXFfYB7jPzzHpRzpglLAjtUV6bB557zwClJezTqnAiYnQA==", + "dev": true, + "requires": { + "call-bind": "^1.0.2", + "define-properties": "^1.1.4", + "es-abstract": "^1.20.4" + } + }, + "strip-ansi": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/strip-ansi/-/strip-ansi-4.0.0.tgz", + "integrity": "sha512-4XaJ2zQdCzROZDivEVIDPkcQn8LMFSa8kj8Gxb/Lnwzv9A8VctNZ+lfivC/sV3ivW8ElJTERXZoPBRrZKkNKow==", + "dev": true, + "requires": { + "ansi-regex": "^3.0.0" + } + }, + "strip-bom": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/strip-bom/-/strip-bom-3.0.0.tgz", + "integrity": "sha512-vavAMRXOgBVNF6nyEEmL3DBK19iRpDcoIwW+swQ+CbGiu7lju6t+JklA1MHweoWtadgt4ISVUsXLyDq34ddcwA==", + "dev": true + }, + "strip-hex-prefix": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/strip-hex-prefix/-/strip-hex-prefix-1.0.0.tgz", + "integrity": "sha512-q8d4ue7JGEiVcypji1bALTos+0pWtyGlivAWyPuTkHzuTCJqrK9sWxYQZUq6Nq3cuyv3bm734IhHvHtGGURU6A==", + "dev": true, + "requires": { + "is-hex-prefixed": "1.0.0" + } + }, + "strip-indent": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/strip-indent/-/strip-indent-2.0.0.tgz", + "integrity": "sha512-RsSNPLpq6YUL7QYy44RnPVTn/lcVZtb48Uof3X5JLbF4zD/Gs7ZFDv2HWol+leoQN2mT86LAzSshGfkTlSOpsA==", + "dev": true + }, + "strip-json-comments": { + "version": "3.1.1", + "resolved": "https://registry.npmjs.org/strip-json-comments/-/strip-json-comments-3.1.1.tgz", + "integrity": "sha512-6fPc+R4ihwqP6N/aIv2f1gMH8lOVtWQHoqC4yK6oSDVVocumAsfCqjkXnqiYMhmMwS/mEHLp7Vehlt3ql6lEig==", + "dev": true + }, + "supports-color": { + "version": "5.5.0", + "resolved": "https://registry.npmjs.org/supports-color/-/supports-color-5.5.0.tgz", + "integrity": "sha512-QjVjwdXIt408MIiAqCX4oUKsgU2EqAGzs2Ppkm4aQYbjm+ZEWEcW4SfFNTr4uMNZma0ey4f5lgLrkB0aX0QMow==", + "dev": true, + "requires": { + "has-flag": "^3.0.0" + } + }, + "swap-case": { + "version": "1.1.2", + "resolved": "https://registry.npmjs.org/swap-case/-/swap-case-1.1.2.tgz", + "integrity": "sha512-BAmWG6/bx8syfc6qXPprof3Mn5vQgf5dwdUNJhsNqU9WdPt5P+ES/wQ5bxfijy8zwZgZZHslC3iAsxsuQMCzJQ==", + "dev": true, + "requires": { + "lower-case": "^1.1.1", + "upper-case": "^1.1.1" + } + }, + "swarm-js": { + "version": "0.1.42", + "resolved": "https://registry.npmjs.org/swarm-js/-/swarm-js-0.1.42.tgz", + "integrity": "sha512-BV7c/dVlA3R6ya1lMlSSNPLYrntt0LUq4YMgy3iwpCIc6rZnS5W2wUoctarZ5pXlpKtxDDf9hNziEkcfrxdhqQ==", + "dev": true, + "requires": { + "bluebird": "^3.5.0", + "buffer": "^5.0.5", + "eth-lib": "^0.1.26", + "fs-extra": "^4.0.2", + "got": "^11.8.5", + "mime-types": "^2.1.16", + "mkdirp-promise": "^5.0.1", + "mock-fs": "^4.1.0", + "setimmediate": "^1.0.5", + "tar": "^4.0.2", + "xhr-request": "^1.0.1" + }, + "dependencies": { + "@szmarczak/http-timer": { + "version": "4.0.6", + "resolved": "https://registry.npmjs.org/@szmarczak/http-timer/-/http-timer-4.0.6.tgz", + "integrity": "sha512-4BAffykYOgO+5nzBWYwE3W90sBgLJoUPRWWcL8wlyiM8IB8ipJz3UMJ9KXQd1RKQXpKp8Tutn80HZtWsu2u76w==", + "dev": true, + "requires": { + "defer-to-connect": "^2.0.0" + } + }, + "cacheable-lookup": { + "version": "5.0.4", + "resolved": "https://registry.npmjs.org/cacheable-lookup/-/cacheable-lookup-5.0.4.tgz", + "integrity": "sha512-2/kNscPhpcxrOigMZzbiWF7dz8ilhb/nIHU3EyZiXWXpeq/au8qJ8VhdftMkty3n7Gj6HIGalQG8oiBNB3AJgA==", + "dev": true + }, + "fs-extra": { + "version": "4.0.3", + "resolved": "https://registry.npmjs.org/fs-extra/-/fs-extra-4.0.3.tgz", + "integrity": "sha512-q6rbdDd1o2mAnQreO7YADIxf/Whx4AHBiRf6d+/cVT8h44ss+lHgxf1FemcqDnQt9X3ct4McHr+JMGlYSsK7Cg==", + "dev": true, + "requires": { + "graceful-fs": "^4.1.2", + "jsonfile": "^4.0.0", + "universalify": "^0.1.0" + } + }, + "got": { + "version": "11.8.6", + "resolved": "https://registry.npmjs.org/got/-/got-11.8.6.tgz", + "integrity": "sha512-6tfZ91bOr7bOXnK7PRDCGBLa1H4U080YHNaAQ2KsMGlLEzRbk44nsZF2E1IeRc3vtJHPVbKCYgdFbaGO2ljd8g==", + "dev": true, + "requires": { + "@sindresorhus/is": "^4.0.0", + "@szmarczak/http-timer": "^4.0.5", + "@types/cacheable-request": "^6.0.1", + "@types/responselike": "^1.0.0", + "cacheable-lookup": "^5.0.3", + "cacheable-request": "^7.0.2", + "decompress-response": "^6.0.0", + "http2-wrapper": "^1.0.0-beta.5.2", + "lowercase-keys": "^2.0.0", + "p-cancelable": "^2.0.0", + "responselike": "^2.0.0" + } + }, + "http2-wrapper": { + "version": "1.0.3", + "resolved": "https://registry.npmjs.org/http2-wrapper/-/http2-wrapper-1.0.3.tgz", + "integrity": "sha512-V+23sDMr12Wnz7iTcDeJr3O6AIxlnvT/bmaAAAP/Xda35C90p9599p0F1eHR/N1KILWSoWVAiOMFjBBXaXSMxg==", + "dev": true, + "requires": { + "quick-lru": "^5.1.1", + "resolve-alpn": "^1.0.0" + } + }, + "lowercase-keys": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/lowercase-keys/-/lowercase-keys-2.0.0.tgz", + "integrity": "sha512-tqNXrS78oMOE73NMxK4EMLQsQowWf8jKooH9g7xPavRT706R6bkQJ6DY2Te7QukaZsulxa30wQ7bk0pm4XiHmA==", + "dev": true + }, + "p-cancelable": { + "version": "2.1.1", + "resolved": "https://registry.npmjs.org/p-cancelable/-/p-cancelable-2.1.1.tgz", + "integrity": "sha512-BZOr3nRQHOntUjTrH8+Lh54smKHoHyur8We1V8DSMVrl5A2malOOwuJRnKRDjSnkoeBh4at6BwEnb5I7Jl31wg==", + "dev": true + }, + "quick-lru": { + "version": "5.1.1", + "resolved": "https://registry.npmjs.org/quick-lru/-/quick-lru-5.1.1.tgz", + "integrity": "sha512-WuyALRjWPDGtt/wzJiadO5AXY+8hZ80hVpe6MyivgraREW751X3SbhRvG3eLKOYN+8VEvqLcf3wdnt44Z4S4SA==", + "dev": true + } + } + }, + "sync-request": { + "version": "6.1.0", + "resolved": "https://registry.npmjs.org/sync-request/-/sync-request-6.1.0.tgz", + "integrity": "sha512-8fjNkrNlNCrVc/av+Jn+xxqfCjYaBoHqCsDz6mt030UMxJGr+GSfCV1dQt2gRtlL63+VPidwDVLr7V2OcTSdRw==", + "dev": true, + "requires": { + "http-response-object": "^3.0.1", + "sync-rpc": "^1.2.1", + "then-request": "^6.0.0" + } + }, + "sync-rpc": { + "version": "1.3.6", + "resolved": "https://registry.npmjs.org/sync-rpc/-/sync-rpc-1.3.6.tgz", + "integrity": "sha512-J8jTXuZzRlvU7HemDgHi3pGnh/rkoqR/OZSjhTyyZrEkkYQbk7Z33AXp37mkPfPpfdOuj7Ex3H/TJM1z48uPQw==", + "dev": true, + "requires": { + "get-port": "^3.1.0" + } + }, + "table": { + "version": "6.8.1", + "resolved": "https://registry.npmjs.org/table/-/table-6.8.1.tgz", + "integrity": "sha512-Y4X9zqrCftUhMeH2EptSSERdVKt/nEdijTOacGD/97EKjhQ/Qs8RTlEGABSJNNN8lac9kheH+af7yAkEWlgneA==", + "dev": true, + "requires": { + "ajv": "^8.0.1", + "lodash.truncate": "^4.4.2", + "slice-ansi": "^4.0.0", + "string-width": "^4.2.3", + "strip-ansi": "^6.0.1" + }, + "dependencies": { + "ajv": { + "version": "8.12.0", + "resolved": "https://registry.npmjs.org/ajv/-/ajv-8.12.0.tgz", + "integrity": "sha512-sRu1kpcO9yLtYxBKvqfTeh9KzZEwO3STyX1HT+4CaDzC6HpTGYhIhPIzj9XuKU7KYDwnaeh5hcOwjy1QuJzBPA==", + "dev": true, + "requires": { + "fast-deep-equal": "^3.1.1", + "json-schema-traverse": "^1.0.0", + "require-from-string": "^2.0.2", + "uri-js": "^4.2.2" + } + }, + "ansi-regex": { + "version": "5.0.1", + "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-5.0.1.tgz", + "integrity": "sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ==", + "dev": true + }, + "is-fullwidth-code-point": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/is-fullwidth-code-point/-/is-fullwidth-code-point-3.0.0.tgz", + "integrity": "sha512-zymm5+u+sCsSWyD9qNaejV3DFvhCKclKdizYaJUuHA83RLjb7nSuGnddCHGv0hk+KY7BMAlsWeK4Ueg6EV6XQg==", + "dev": true + }, + "json-schema-traverse": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/json-schema-traverse/-/json-schema-traverse-1.0.0.tgz", + "integrity": "sha512-NM8/P9n3XjXhIZn1lLhkFaACTOURQXjWhV4BA/RnOv8xvgqtqpAX9IO4mRQxSx1Rlo4tqzeqb0sOlruaOy3dug==", + "dev": true + }, + "require-from-string": { + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/require-from-string/-/require-from-string-2.0.2.tgz", + "integrity": "sha512-Xf0nWe6RseziFMu+Ap9biiUbmplq6S9/p+7w7YXP/JBHhrUDDUhwa+vANyubuqfZWTveU//DYVGsDG7RKL/vEw==", + "dev": true + }, + "string-width": { + "version": "4.2.3", + "resolved": "https://registry.npmjs.org/string-width/-/string-width-4.2.3.tgz", + "integrity": "sha512-wKyQRQpjJ0sIp62ErSZdGsjMJWsap5oRNihHhu6G7JVO/9jIB6UyevL+tXuOqrng8j/cxKTWyWUwvSTriiZz/g==", + "dev": true, + "requires": { + "emoji-regex": "^8.0.0", + "is-fullwidth-code-point": "^3.0.0", + "strip-ansi": "^6.0.1" + } + }, + "strip-ansi": { + "version": "6.0.1", + "resolved": "https://registry.npmjs.org/strip-ansi/-/strip-ansi-6.0.1.tgz", + "integrity": "sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A==", + "dev": true, + "requires": { + "ansi-regex": "^5.0.1" + } + } + } + }, + "tar": { + "version": "4.4.19", + "resolved": "https://registry.npmjs.org/tar/-/tar-4.4.19.tgz", + "integrity": "sha512-a20gEsvHnWe0ygBY8JbxoM4w3SJdhc7ZAuxkLqh+nvNQN2IOt0B5lLgM490X5Hl8FF0dl0tOf2ewFYAlIFgzVA==", + "dev": true, + "requires": { + "chownr": "^1.1.4", + "fs-minipass": "^1.2.7", + "minipass": "^2.9.0", + "minizlib": "^1.3.3", + "mkdirp": "^0.5.5", + "safe-buffer": "^5.2.1", + "yallist": "^3.1.1" + } + }, + "term-size": { + "version": "2.2.1", + "resolved": "https://registry.npmjs.org/term-size/-/term-size-2.2.1.tgz", + "integrity": "sha512-wK0Ri4fOGjv/XPy8SBHZChl8CM7uMc5VML7SqiQ0zG7+J5Vr+RMQDoHa2CNT6KHUnTGIXH34UDMkPzAUyapBZg==", + "dev": true + }, + "testrpc": { + "version": "0.0.1", + "resolved": "https://registry.npmjs.org/testrpc/-/testrpc-0.0.1.tgz", + "integrity": "sha512-afH1hO+SQ/VPlmaLUFj2636QMeDvPCeQMc/9RBMW0IfjNe9gFD9Ra3ShqYkB7py0do1ZcCna/9acHyzTJ+GcNA==", + "dev": true + }, + "text-table": { + "version": "0.2.0", + "resolved": "https://registry.npmjs.org/text-table/-/text-table-0.2.0.tgz", + "integrity": "sha512-N+8UisAXDGk8PFXP4HAzVR9nbfmVJ3zYLAWiTIoqC5v5isinhr+r5uaO8+7r3BMfuNIufIsA7RdpVgacC2cSpw==", + "dev": true + }, + "then-request": { + "version": "6.0.2", + "resolved": "https://registry.npmjs.org/then-request/-/then-request-6.0.2.tgz", + "integrity": "sha512-3ZBiG7JvP3wbDzA9iNY5zJQcHL4jn/0BWtXIkagfz7QgOL/LqjCEOBQuJNZfu0XYnv5JhKh+cDxCPM4ILrqruA==", + "dev": true, + "requires": { + "@types/concat-stream": "^1.6.0", + "@types/form-data": "0.0.33", + "@types/node": "^8.0.0", + "@types/qs": "^6.2.31", + "caseless": "~0.12.0", + "concat-stream": "^1.6.0", + "form-data": "^2.2.0", + "http-basic": "^8.1.1", + "http-response-object": "^3.0.1", + "promise": "^8.0.0", + "qs": "^6.4.0" + }, + "dependencies": { + "@types/node": { + "version": "8.10.66", + "resolved": "https://registry.npmjs.org/@types/node/-/node-8.10.66.tgz", + "integrity": "sha512-tktOkFUA4kXx2hhhrB8bIFb5TbwzS4uOhKEmwiD+NoiL0qtP2OQ9mFldbgD4dV1djrlBYP6eBuQZiWjuHUpqFw==", + "dev": true + } + } + }, + "timed-out": { + "version": "4.0.1", + "resolved": "https://registry.npmjs.org/timed-out/-/timed-out-4.0.1.tgz", + "integrity": "sha512-G7r3AhovYtr5YKOWQkta8RKAPb+J9IsO4uVmzjl8AZwfhs8UcUwTiD6gcJYSgOtzyjvQKrKYn41syHbUWMkafA==", + "dev": true + }, + "title-case": { + "version": "2.1.1", + "resolved": "https://registry.npmjs.org/title-case/-/title-case-2.1.1.tgz", + "integrity": "sha512-EkJoZ2O3zdCz3zJsYCsxyq2OC5hrxR9mfdd5I+w8h/tmFfeOxJ+vvkxsKxdmN0WtS9zLdHEgfgVOiMVgv+Po4Q==", + "dev": true, + "requires": { + "no-case": "^2.2.0", + "upper-case": "^1.0.3" + } + }, + "tmp": { + "version": "0.0.33", + "resolved": "https://registry.npmjs.org/tmp/-/tmp-0.0.33.tgz", + "integrity": "sha512-jRCJlojKnZ3addtTOjdIqoRuPEKBvNXcGYqzO6zWZX8KfKEpnGY5jfggJQ3EjKuu8D4bJRr0y+cYJFmYbImXGw==", + "dev": true, + "requires": { + "os-tmpdir": "~1.0.2" + } + }, + "to-regex-range": { + "version": "5.0.1", + "resolved": "https://registry.npmjs.org/to-regex-range/-/to-regex-range-5.0.1.tgz", + "integrity": "sha512-65P7iz6X5yEr1cwcgvQxbbIw7Uk3gOy5dIdtZ4rDveLqhrdJP+Li/Hx6tyK0NEb+2GCyneCMJiGqrADCSNk8sQ==", + "dev": true, + "requires": { + "is-number": "^7.0.0" + } + }, + "toidentifier": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/toidentifier/-/toidentifier-1.0.1.tgz", + "integrity": "sha512-o5sSPKEkg/DIQNmH43V0/uerLrpzVedkUh8tGNvaeXpfpuwjKenlSox/2O/BTlZUtEe+JG7s5YhEz608PlAHRA==", + "dev": true + }, + "tough-cookie": { + "version": "2.5.0", + "resolved": "https://registry.npmjs.org/tough-cookie/-/tough-cookie-2.5.0.tgz", + "integrity": "sha512-nlLsUzgm1kfLXSXfRZMc1KLAugd4hqJHDTvc2hDIwS3mZAfMEuMbc03SujMF+GEcpaX/qboeycw6iO8JwVv2+g==", + "dev": true, + "requires": { + "psl": "^1.1.28", + "punycode": "^2.1.1" + }, + "dependencies": { + "punycode": { + "version": "2.3.0", + "resolved": "https://registry.npmjs.org/punycode/-/punycode-2.3.0.tgz", + "integrity": "sha512-rRV+zQD8tVFys26lAGR9WUuS4iUAngJScM+ZRSKtvl5tKeZ2t5bvdNFdNHBW9FWR4guGHlgmsZ1G7BSm2wTbuA==", + "dev": true + } + } + }, + "tr46": { + "version": "0.0.3", + "resolved": "https://registry.npmjs.org/tr46/-/tr46-0.0.3.tgz", + "integrity": "sha512-N3WMsuqV66lT30CrXNbEjx4GEwlow3v6rr4mCcv6prnfwhS01rkgyFdjPNBYd9br7LpXV1+Emh01fHnq2Gdgrw==", + "dev": true + }, + "treeify": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/treeify/-/treeify-1.1.0.tgz", + "integrity": "sha512-1m4RA7xVAJrSGrrXGs0L3YTwyvBs2S8PbRHaLZAkFw7JR8oIFwYtysxlBZhYIa7xSyiYJKZ3iGrrk55cGA3i9A==", + "dev": true + }, + "trim-newlines": { + "version": "3.0.1", + "resolved": "https://registry.npmjs.org/trim-newlines/-/trim-newlines-3.0.1.tgz", + "integrity": "sha512-c1PTsA3tYrIsLGkJkzHF+w9F2EyxfXGo4UyJc4pFL++FMjnq0HJS69T3M7d//gKrFKwy429bouPescbjecU+Zw==", + "dev": true + }, + "tslib": { + "version": "1.14.1", + "resolved": "https://registry.npmjs.org/tslib/-/tslib-1.14.1.tgz", + "integrity": "sha512-Xni35NKzjgMrwevysHTCArtLDpPvye8zV/0E4EyYn43P7/7qvQwPh9BGkHewbMulVntbigmcT7rdX3BNo9wRJg==", + "dev": true + }, + "tsort": { + "version": "0.0.1", + "resolved": "https://registry.npmjs.org/tsort/-/tsort-0.0.1.tgz", + "integrity": "sha512-Tyrf5mxF8Ofs1tNoxA13lFeZ2Zrbd6cKbuH3V+MQ5sb6DtBj5FjrXVsRWT8YvNAQTqNoz66dz1WsbigI22aEnw==", + "dev": true + }, + "tty-table": { + "version": "4.2.1", + "resolved": "https://registry.npmjs.org/tty-table/-/tty-table-4.2.1.tgz", + "integrity": "sha512-xz0uKo+KakCQ+Dxj1D/tKn2FSyreSYWzdkL/BYhgN6oMW808g8QRMuh1atAV9fjTPbWBjfbkKQpI/5rEcnAc7g==", + "dev": true, + "requires": { + "chalk": "^4.1.2", + "csv": "^5.5.3", + "kleur": "^4.1.5", + "smartwrap": "^2.0.2", + "strip-ansi": "^6.0.1", + "wcwidth": "^1.0.1", + "yargs": "^17.7.1" + }, + "dependencies": { + "ansi-regex": { + "version": "5.0.1", + "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-5.0.1.tgz", + "integrity": "sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ==", + "dev": true + }, + "ansi-styles": { + "version": "4.3.0", + "resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-4.3.0.tgz", + "integrity": "sha512-zbB9rCJAT1rbjiVDb2hqKFHNYLxgtk8NURxZ3IZwD3F6NtxbXZQCnnSi1Lkx+IDohdPlFp222wVALIheZJQSEg==", + "dev": true, + "requires": { + "color-convert": "^2.0.1" + } + }, + "chalk": { + "version": "4.1.2", + "resolved": "https://registry.npmjs.org/chalk/-/chalk-4.1.2.tgz", + "integrity": "sha512-oKnbhFyRIXpUuez8iBMmyEa4nbj4IOQyuhc/wy9kY7/WVPcwIO9VA668Pu8RkO7+0G76SLROeyw9CpQ061i4mA==", + "dev": true, + "requires": { + "ansi-styles": "^4.1.0", + "supports-color": "^7.1.0" + } + }, + "color-convert": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/color-convert/-/color-convert-2.0.1.tgz", + "integrity": "sha512-RRECPsj7iu/xb5oKYcsFHSppFNnsj/52OVTRKb4zP5onXwVF3zVmmToNcOfGC+CRDpfK/U584fMg38ZHCaElKQ==", + "dev": true, + "requires": { + "color-name": "~1.1.4" + } + }, + "color-name": { + "version": "1.1.4", + "resolved": "https://registry.npmjs.org/color-name/-/color-name-1.1.4.tgz", + "integrity": "sha512-dOy+3AuW3a2wNbZHIuMZpTcgjGuLU/uBL/ubcZF9OXbDo8ff4O8yVp5Bf0efS8uEoYo5q4Fx7dY9OgQGXgAsQA==", + "dev": true + }, + "has-flag": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/has-flag/-/has-flag-4.0.0.tgz", + "integrity": "sha512-EykJT/Q1KjTWctppgIAgfSO0tKVuZUjhgMr17kqTumMl6Afv3EISleU7qZUzoXDFTAHTDC4NOoG/ZxU3EvlMPQ==", + "dev": true + }, + "strip-ansi": { + "version": "6.0.1", + "resolved": "https://registry.npmjs.org/strip-ansi/-/strip-ansi-6.0.1.tgz", + "integrity": "sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A==", + "dev": true, + "requires": { + "ansi-regex": "^5.0.1" + } + }, + "supports-color": { + "version": "7.2.0", + "resolved": "https://registry.npmjs.org/supports-color/-/supports-color-7.2.0.tgz", + "integrity": "sha512-qpCAvRl9stuOHveKsn7HncJRvv501qIacKzQlO/+Lwxc9+0q2wLyv4Dfvt80/DPn2pqOBsJdDiogXGR9+OvwRw==", + "dev": true, + "requires": { + "has-flag": "^4.0.0" + } + } + } + }, + "tunnel-agent": { + "version": "0.6.0", + "resolved": "https://registry.npmjs.org/tunnel-agent/-/tunnel-agent-0.6.0.tgz", + "integrity": "sha512-McnNiV1l8RYeY8tBgEpuodCC1mLUdbSN+CYBL7kJsJNInOP8UjDDEwdk6Mw60vdLLrr5NHKZhMAOSrR2NZuQ+w==", + "dev": true, + "requires": { + "safe-buffer": "^5.0.1" + } + }, + "tweetnacl": { + "version": "1.0.3", + "resolved": "https://registry.npmjs.org/tweetnacl/-/tweetnacl-1.0.3.tgz", + "integrity": "sha512-6rt+RN7aOi1nGMyC4Xa5DdYiukl2UWCbcJft7YhxReBGQD7OAM8Pbxw6YMo4r2diNEA8FEmu32YOn9rhaiE5yw==", + "dev": true + }, + "tweetnacl-util": { + "version": "0.15.1", + "resolved": "https://registry.npmjs.org/tweetnacl-util/-/tweetnacl-util-0.15.1.tgz", + "integrity": "sha512-RKJBIj8lySrShN4w6i/BonWp2Z/uxwC3h4y7xsRrpP59ZboCd0GpEVsOnMDYLMmKBpYhb5TgHzZXy7wTfYFBRw==", + "dev": true + }, + "type": { + "version": "1.2.0", + "resolved": "https://registry.npmjs.org/type/-/type-1.2.0.tgz", + "integrity": "sha512-+5nt5AAniqsCnu2cEQQdpzCAh33kVx8n0VoFidKpB1dVVLAN/F+bgVOqOJqOnEnrhp222clB5p3vUlD+1QAnfg==", + "dev": true + }, + "type-check": { + "version": "0.4.0", + "resolved": "https://registry.npmjs.org/type-check/-/type-check-0.4.0.tgz", + "integrity": "sha512-XleUoc9uwGXqjWwXaUTZAmzMcFZ5858QA2vvx1Ur5xIcixXIP+8LnFDgRplU30us6teqdlskFfu+ae4K79Ooew==", + "dev": true, + "requires": { + "prelude-ls": "^1.2.1" + } + }, + "type-detect": { + "version": "4.0.8", + "resolved": "https://registry.npmjs.org/type-detect/-/type-detect-4.0.8.tgz", + "integrity": "sha512-0fr/mIH1dlO+x7TlcMy+bIDqKPsw/70tVyeHW787goQjhmqaZe10uwLujubK9q9Lg6Fiho1KUKDYz0Z7k7g5/g==", + "dev": true + }, + "type-fest": { + "version": "0.20.2", + "resolved": "https://registry.npmjs.org/type-fest/-/type-fest-0.20.2.tgz", + "integrity": "sha512-Ne+eE4r0/iWnpAxD852z3A+N0Bt5RN//NjJwRd2VFHEmrywxf5vsZlh4R6lixl6B+wz/8d+maTSAkN1FIkI3LQ==", + "dev": true + }, + "type-is": { + "version": "1.6.18", + "resolved": "https://registry.npmjs.org/type-is/-/type-is-1.6.18.tgz", + "integrity": "sha512-TkRKr9sUTxEH8MdfuCSP7VizJyzRNMjj2J2do2Jr3Kym598JVdEksuzPQCnlFPW4ky9Q+iA+ma9BGm06XQBy8g==", + "dev": true, + "requires": { + "media-typer": "0.3.0", + "mime-types": "~2.1.24" + } + }, + "typed-array-length": { + "version": "1.0.4", + "resolved": "https://registry.npmjs.org/typed-array-length/-/typed-array-length-1.0.4.tgz", + "integrity": "sha512-KjZypGq+I/H7HI5HlOoGHkWUUGq+Q0TPhQurLbyrVrvnKTBgzLhIJ7j6J/XTQOi0d1RjyZ0wdas8bKs2p0x3Ng==", + "dev": true, + "requires": { + "call-bind": "^1.0.2", + "for-each": "^0.3.3", + "is-typed-array": "^1.1.9" + } + }, + "typedarray": { + "version": "0.0.6", + "resolved": "https://registry.npmjs.org/typedarray/-/typedarray-0.0.6.tgz", + "integrity": "sha512-/aCDEGatGvZ2BIk+HmLf4ifCJFwvKFNb9/JeZPMulfgFracn9QFcAf5GO8B/mweUjSoblS5In0cWhqpfs/5PQA==", + "dev": true + }, + "typedarray-to-buffer": { + "version": "3.1.5", + "resolved": "https://registry.npmjs.org/typedarray-to-buffer/-/typedarray-to-buffer-3.1.5.tgz", + "integrity": "sha512-zdu8XMNEDepKKR+XYOXAVPtWui0ly0NtohUscw+UmaHiAWT8hrV1rr//H6V+0DvJ3OQ19S979M0laLfX8rm82Q==", + "dev": true, + "requires": { + "is-typedarray": "^1.0.0" + } + }, + "uglify-js": { + "version": "3.17.4", + "resolved": "https://registry.npmjs.org/uglify-js/-/uglify-js-3.17.4.tgz", + "integrity": "sha512-T9q82TJI9e/C1TAxYvfb16xO120tMVFZrGA3f9/P4424DNu6ypK103y0GPFVa17yotwSyZW5iYXgjYHkGrJW/g==", + "dev": true, + "optional": true + }, + "ultron": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/ultron/-/ultron-1.1.1.tgz", + "integrity": "sha512-UIEXBNeYmKptWH6z8ZnqTeS8fV74zG0/eRU9VGkpzz+LIJNs8W/zM/L+7ctCkRrgbNnnR0xxw4bKOr0cW0N0Og==", + "dev": true + }, + "unbox-primitive": { + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/unbox-primitive/-/unbox-primitive-1.0.2.tgz", + "integrity": "sha512-61pPlCD9h51VoreyJ0BReideM3MDKMKnh6+V9L08331ipq6Q8OFXZYiqP6n/tbHx4s5I9uRhcye6BrbkizkBDw==", + "dev": true, + "requires": { + "call-bind": "^1.0.2", + "has-bigints": "^1.0.2", + "has-symbols": "^1.0.3", + "which-boxed-primitive": "^1.0.2" + } + }, + "underscore": { + "version": "1.13.6", + "resolved": "https://registry.npmjs.org/underscore/-/underscore-1.13.6.tgz", + "integrity": "sha512-+A5Sja4HP1M08MaXya7p5LvjuM7K6q/2EaC0+iovj/wOcMsTzMvDFbasi/oSapiwOlt252IqsKqPjCl7huKS0A==", + "dev": true + }, + "undici": { + "version": "5.22.1", + "resolved": "https://registry.npmjs.org/undici/-/undici-5.22.1.tgz", + "integrity": "sha512-Ji2IJhFXZY0x/0tVBXeQwgPlLWw13GVzpsWPQ3rV50IFMMof2I55PZZxtm4P6iNq+L5znYN9nSTAq0ZyE6lSJw==", + "dev": true, + "requires": { + "busboy": "^1.6.0" + } + }, + "universalify": { + "version": "0.1.2", + "resolved": "https://registry.npmjs.org/universalify/-/universalify-0.1.2.tgz", + "integrity": "sha512-rBJeI5CXAlmy1pV+617WB9J63U6XcazHHF2f2dbJix4XzpUF0RS3Zbj0FGIOCAva5P/d/GBOYaACQ1w+0azUkg==", + "dev": true + }, + "unpipe": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/unpipe/-/unpipe-1.0.0.tgz", + "integrity": "sha512-pjy2bYhSsufwWlKwPc+l3cN7+wuJlK6uz0YdJEOlQDbl6jo/YlPi4mb8agUkVC8BF7V8NuzeyPNqRksA3hztKQ==", + "dev": true + }, + "upper-case": { + "version": "1.1.3", + "resolved": "https://registry.npmjs.org/upper-case/-/upper-case-1.1.3.tgz", + "integrity": "sha512-WRbjgmYzgXkCV7zNVpy5YgrHgbBv126rMALQQMrmzOVC4GM2waQ9x7xtm8VU+1yF2kWyPzI9zbZ48n4vSxwfSA==", + "dev": true + }, + "upper-case-first": { + "version": "1.1.2", + "resolved": "https://registry.npmjs.org/upper-case-first/-/upper-case-first-1.1.2.tgz", + "integrity": "sha512-wINKYvI3Db8dtjikdAqoBbZoP6Q+PZUyfMR7pmwHzjC2quzSkUq5DmPrTtPEqHaz8AGtmsB4TqwapMTM1QAQOQ==", + "dev": true, + "requires": { + "upper-case": "^1.1.1" + } + }, + "uri-js": { + "version": "4.4.1", + "resolved": "https://registry.npmjs.org/uri-js/-/uri-js-4.4.1.tgz", + "integrity": "sha512-7rKUyy33Q1yc98pQ1DAmLtwX109F7TIfWlW1Ydo8Wl1ii1SeHieeh0HHfPeL2fMXK6z0s8ecKs9frCuLJvndBg==", + "dev": true, + "requires": { + "punycode": "^2.1.0" + } + }, + "url-set-query": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/url-set-query/-/url-set-query-1.0.0.tgz", + "integrity": "sha512-3AChu4NiXquPfeckE5R5cGdiHCMWJx1dwCWOmWIL4KHAziJNOFIYJlpGFeKDvwLPHovZRCxK3cYlwzqI9Vp+Gg==", + "dev": true + }, + "utf-8-validate": { + "version": "5.0.10", + "resolved": "https://registry.npmjs.org/utf-8-validate/-/utf-8-validate-5.0.10.tgz", + "integrity": "sha512-Z6czzLq4u8fPOyx7TU6X3dvUZVvoJmxSQ+IcrlmagKhilxlhZgxPK6C5Jqbkw1IDUmFTM+cz9QDnnLTwDz/2gQ==", + "dev": true, + "requires": { + "node-gyp-build": "^4.3.0" + } + }, + "utf8": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/utf8/-/utf8-3.0.0.tgz", + "integrity": "sha512-E8VjFIQ/TyQgp+TZfS6l8yp/xWppSAHzidGiRrqe4bK4XP9pTRyKFgGJpO3SN7zdX4DeomTrwaseCHovfpFcqQ==", + "dev": true + }, + "util": { + "version": "0.12.5", + "resolved": "https://registry.npmjs.org/util/-/util-0.12.5.tgz", + "integrity": "sha512-kZf/K6hEIrWHI6XqOFUiiMa+79wE/D8Q+NCNAWclkyg3b4d2k7s0QGepNjiABc+aR3N1PAyHL7p6UcLY6LmrnA==", + "dev": true, + "requires": { + "inherits": "^2.0.3", + "is-arguments": "^1.0.4", + "is-generator-function": "^1.0.7", + "is-typed-array": "^1.1.3", + "which-typed-array": "^1.1.2" + } + }, + "util-deprecate": { + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/util-deprecate/-/util-deprecate-1.0.2.tgz", + "integrity": "sha512-EPD5q1uXyFxJpCrLnCc1nHnq3gOa6DZBocAIiI2TaSCA7VCJ1UJDMagCzIkXNsUYfD1daK//LTEQ8xiIbrHtcw==", + "dev": true + }, + "utils-merge": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/utils-merge/-/utils-merge-1.0.1.tgz", + "integrity": "sha512-pMZTvIkT1d+TFGvDOqodOclx0QWkkgi6Tdoa8gC8ffGAAqz9pzPTZWAybbsHHoED/ztMtkv/VoYTYyShUn81hA==", + "dev": true + }, + "uuid": { + "version": "8.3.2", + "resolved": "https://registry.npmjs.org/uuid/-/uuid-8.3.2.tgz", + "integrity": "sha512-+NYs2QeMWy+GWFOEm9xnn6HCDp0l7QBD7ml8zLUmJ+93Q5NF0NocErnwkTkXVFNiX3/fpC6afS8Dhb/gz7R7eg==", + "dev": true + }, + "validate-npm-package-license": { + "version": "3.0.4", + "resolved": "https://registry.npmjs.org/validate-npm-package-license/-/validate-npm-package-license-3.0.4.tgz", + "integrity": "sha512-DpKm2Ui/xN7/HQKCtpZxoRWBhZ9Z0kqtygG8XCgNQ8ZlDnxuQmWhj566j8fN4Cu3/JmbhsDo7fcAJq4s9h27Ew==", + "dev": true, + "requires": { + "spdx-correct": "^3.0.0", + "spdx-expression-parse": "^3.0.0" + } + }, + "varint": { + "version": "5.0.2", + "resolved": "https://registry.npmjs.org/varint/-/varint-5.0.2.tgz", + "integrity": "sha512-lKxKYG6H03yCZUpAGOPOsMcGxd1RHCu1iKvEHYDPmTyq2HueGhD73ssNBqqQWfvYs04G9iUFRvmAVLW20Jw6ow==", + "dev": true + }, + "vary": { + "version": "1.1.2", + "resolved": "https://registry.npmjs.org/vary/-/vary-1.1.2.tgz", + "integrity": "sha512-BNGbWLfd0eUPabhkXUVm0j8uuvREyTh5ovRa/dyow/BqAbZJyC+5fU+IzQOzmAKzYqYRAISoRhdQr3eIZ/PXqg==", + "dev": true + }, + "verror": { + "version": "1.10.0", + "resolved": "https://registry.npmjs.org/verror/-/verror-1.10.0.tgz", + "integrity": "sha512-ZZKSmDAEFOijERBLkmYfJ+vmk3w+7hOLYDNkRCuRuMJGEmqYNCNLyBBFwWKVMhfwaEF3WOd0Zlw86U/WC/+nYw==", + "dev": true, + "requires": { + "assert-plus": "^1.0.0", + "core-util-is": "1.0.2", + "extsprintf": "^1.2.0" + } + }, + "wcwidth": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/wcwidth/-/wcwidth-1.0.1.tgz", + "integrity": "sha512-XHPEwS0q6TaxcvG85+8EYkbiCux2XtWG2mkc47Ng2A77BQu9+DqIOJldST4HgPkuea7dvKSj5VgX3P1d4rW8Tg==", + "dev": true, + "requires": { + "defaults": "^1.0.3" + } + }, + "web3": { + "version": "1.10.0", + "resolved": "https://registry.npmjs.org/web3/-/web3-1.10.0.tgz", + "integrity": "sha512-YfKY9wSkGcM8seO+daR89oVTcbu18NsVfvOngzqMYGUU0pPSQmE57qQDvQzUeoIOHAnXEBNzrhjQJmm8ER0rng==", + "dev": true, + "requires": { + "web3-bzz": "1.10.0", + "web3-core": "1.10.0", + "web3-eth": "1.10.0", + "web3-eth-personal": "1.10.0", + "web3-net": "1.10.0", + "web3-shh": "1.10.0", + "web3-utils": "1.10.0" + } + }, + "web3-bzz": { + "version": "1.10.0", + "resolved": "https://registry.npmjs.org/web3-bzz/-/web3-bzz-1.10.0.tgz", + "integrity": "sha512-o9IR59io3pDUsXTsps5pO5hW1D5zBmg46iNc2t4j2DkaYHNdDLwk2IP9ukoM2wg47QILfPEJYzhTfkS/CcX0KA==", + "dev": true, + "requires": { + "@types/node": "^12.12.6", + "got": "12.1.0", + "swarm-js": "^0.1.40" + } + }, + "web3-core": { + "version": "1.10.0", + "resolved": "https://registry.npmjs.org/web3-core/-/web3-core-1.10.0.tgz", + "integrity": "sha512-fWySwqy2hn3TL89w5TM8wXF1Z2Q6frQTKHWmP0ppRQorEK8NcHJRfeMiv/mQlSKoTS1F6n/nv2uyZsixFycjYQ==", + "dev": true, + "requires": { + "@types/bn.js": "^5.1.1", + "@types/node": "^12.12.6", + "bignumber.js": "^9.0.0", + "web3-core-helpers": "1.10.0", + "web3-core-method": "1.10.0", + "web3-core-requestmanager": "1.10.0", + "web3-utils": "1.10.0" + }, + "dependencies": { + "bignumber.js": { + "version": "9.1.1", + "resolved": "https://registry.npmjs.org/bignumber.js/-/bignumber.js-9.1.1.tgz", + "integrity": "sha512-pHm4LsMJ6lzgNGVfZHjMoO8sdoRhOzOH4MLmY65Jg70bpxCKu5iOHNJyfF6OyvYw7t8Fpf35RuzUyqnQsj8Vig==", + "dev": true + } + } + }, + "web3-core-helpers": { + "version": "1.10.0", + "resolved": "https://registry.npmjs.org/web3-core-helpers/-/web3-core-helpers-1.10.0.tgz", + "integrity": "sha512-pIxAzFDS5vnbXvfvLSpaA1tfRykAe9adw43YCKsEYQwH0gCLL0kMLkaCX3q+Q8EVmAh+e1jWL/nl9U0de1+++g==", + "dev": true, + "requires": { + "web3-eth-iban": "1.10.0", + "web3-utils": "1.10.0" + } + }, + "web3-core-method": { + "version": "1.10.0", + "resolved": "https://registry.npmjs.org/web3-core-method/-/web3-core-method-1.10.0.tgz", + "integrity": "sha512-4R700jTLAMKDMhQ+nsVfIXvH6IGJlJzGisIfMKWAIswH31h5AZz7uDUW2YctI+HrYd+5uOAlS4OJeeT9bIpvkA==", + "dev": true, + "requires": { + "@ethersproject/transactions": "^5.6.2", + "web3-core-helpers": "1.10.0", + "web3-core-promievent": "1.10.0", + "web3-core-subscriptions": "1.10.0", + "web3-utils": "1.10.0" + } + }, + "web3-core-promievent": { + "version": "1.10.0", + "resolved": "https://registry.npmjs.org/web3-core-promievent/-/web3-core-promievent-1.10.0.tgz", + "integrity": "sha512-68N7k5LWL5R38xRaKFrTFT2pm2jBNFaM4GioS00YjAKXRQ3KjmhijOMG3TICz6Aa5+6GDWYelDNx21YAeZ4YTg==", + "dev": true, + "requires": { + "eventemitter3": "4.0.4" + } + }, + "web3-core-requestmanager": { + "version": "1.10.0", + "resolved": "https://registry.npmjs.org/web3-core-requestmanager/-/web3-core-requestmanager-1.10.0.tgz", + "integrity": "sha512-3z/JKE++Os62APml4dvBM+GAuId4h3L9ckUrj7ebEtS2AR0ixyQPbrBodgL91Sv7j7cQ3Y+hllaluqjguxvSaQ==", + "dev": true, + "requires": { + "util": "^0.12.5", + "web3-core-helpers": "1.10.0", + "web3-providers-http": "1.10.0", + "web3-providers-ipc": "1.10.0", + "web3-providers-ws": "1.10.0" + } + }, + "web3-core-subscriptions": { + "version": "1.10.0", + "resolved": "https://registry.npmjs.org/web3-core-subscriptions/-/web3-core-subscriptions-1.10.0.tgz", + "integrity": "sha512-HGm1PbDqsxejI075gxBc5OSkwymilRWZufIy9zEpnWKNmfbuv5FfHgW1/chtJP6aP3Uq2vHkvTDl3smQBb8l+g==", + "dev": true, + "requires": { + "eventemitter3": "4.0.4", + "web3-core-helpers": "1.10.0" + } + }, + "web3-eth": { + "version": "1.10.0", + "resolved": "https://registry.npmjs.org/web3-eth/-/web3-eth-1.10.0.tgz", + "integrity": "sha512-Z5vT6slNMLPKuwRyKGbqeGYC87OAy8bOblaqRTgg94CXcn/mmqU7iPIlG4506YdcdK3x6cfEDG7B6w+jRxypKA==", + "dev": true, + "requires": { + "web3-core": "1.10.0", + "web3-core-helpers": "1.10.0", + "web3-core-method": "1.10.0", + "web3-core-subscriptions": "1.10.0", + "web3-eth-abi": "1.10.0", + "web3-eth-accounts": "1.10.0", + "web3-eth-contract": "1.10.0", + "web3-eth-ens": "1.10.0", + "web3-eth-iban": "1.10.0", + "web3-eth-personal": "1.10.0", + "web3-net": "1.10.0", + "web3-utils": "1.10.0" + } + }, + "web3-eth-abi": { + "version": "1.10.0", + "resolved": "https://registry.npmjs.org/web3-eth-abi/-/web3-eth-abi-1.10.0.tgz", + "integrity": "sha512-cwS+qRBWpJ43aI9L3JS88QYPfFcSJJ3XapxOQ4j40v6mk7ATpA8CVK1vGTzpihNlOfMVRBkR95oAj7oL6aiDOg==", + "dev": true, + "requires": { + "@ethersproject/abi": "^5.6.3", + "web3-utils": "1.10.0" + } + }, + "web3-eth-accounts": { + "version": "1.10.0", + "resolved": "https://registry.npmjs.org/web3-eth-accounts/-/web3-eth-accounts-1.10.0.tgz", + "integrity": "sha512-wiq39Uc3mOI8rw24wE2n15hboLE0E9BsQLdlmsL4Zua9diDS6B5abXG0XhFcoNsXIGMWXVZz4TOq3u4EdpXF/Q==", + "dev": true, + "requires": { + "@ethereumjs/common": "2.5.0", + "@ethereumjs/tx": "3.3.2", + "eth-lib": "0.2.8", + "ethereumjs-util": "^7.1.5", + "scrypt-js": "^3.0.1", + "uuid": "^9.0.0", + "web3-core": "1.10.0", + "web3-core-helpers": "1.10.0", + "web3-core-method": "1.10.0", + "web3-utils": "1.10.0" + }, + "dependencies": { + "eth-lib": { + "version": "0.2.8", + "resolved": "https://registry.npmjs.org/eth-lib/-/eth-lib-0.2.8.tgz", + "integrity": "sha512-ArJ7x1WcWOlSpzdoTBX8vkwlkSQ85CjjifSZtV4co64vWxSV8geWfPI9x4SVYu3DSxnX4yWFVTtGL+j9DUFLNw==", + "dev": true, + "requires": { + "bn.js": "^4.11.6", + "elliptic": "^6.4.0", + "xhr-request-promise": "^0.1.2" + } + }, + "uuid": { + "version": "9.0.0", + "resolved": "https://registry.npmjs.org/uuid/-/uuid-9.0.0.tgz", + "integrity": "sha512-MXcSTerfPa4uqyzStbRoTgt5XIe3x5+42+q1sDuy3R5MDk66URdLMOZe5aPX/SQd+kuYAh0FdP/pO28IkQyTeg==", + "dev": true + } + } + }, + "web3-eth-contract": { + "version": "1.10.0", + "resolved": "https://registry.npmjs.org/web3-eth-contract/-/web3-eth-contract-1.10.0.tgz", + "integrity": "sha512-MIC5FOzP/+2evDksQQ/dpcXhSqa/2hFNytdl/x61IeWxhh6vlFeSjq0YVTAyIzdjwnL7nEmZpjfI6y6/Ufhy7w==", + "dev": true, + "requires": { + "@types/bn.js": "^5.1.1", + "web3-core": "1.10.0", + "web3-core-helpers": "1.10.0", + "web3-core-method": "1.10.0", + "web3-core-promievent": "1.10.0", + "web3-core-subscriptions": "1.10.0", + "web3-eth-abi": "1.10.0", + "web3-utils": "1.10.0" + } + }, + "web3-eth-ens": { + "version": "1.10.0", + "resolved": "https://registry.npmjs.org/web3-eth-ens/-/web3-eth-ens-1.10.0.tgz", + "integrity": "sha512-3hpGgzX3qjgxNAmqdrC2YUQMTfnZbs4GeLEmy8aCWziVwogbuqQZ+Gzdfrym45eOZodk+lmXyLuAdqkNlvkc1g==", + "dev": true, + "requires": { + "content-hash": "^2.5.2", + "eth-ens-namehash": "2.0.8", + "web3-core": "1.10.0", + "web3-core-helpers": "1.10.0", + "web3-core-promievent": "1.10.0", + "web3-eth-abi": "1.10.0", + "web3-eth-contract": "1.10.0", + "web3-utils": "1.10.0" + } + }, + "web3-eth-iban": { + "version": "1.10.0", + "resolved": "https://registry.npmjs.org/web3-eth-iban/-/web3-eth-iban-1.10.0.tgz", + "integrity": "sha512-0l+SP3IGhInw7Q20LY3IVafYEuufo4Dn75jAHT7c2aDJsIolvf2Lc6ugHkBajlwUneGfbRQs/ccYPQ9JeMUbrg==", + "dev": true, + "requires": { + "bn.js": "^5.2.1", + "web3-utils": "1.10.0" + }, + "dependencies": { + "bn.js": { + "version": "5.2.1", + "resolved": "https://registry.npmjs.org/bn.js/-/bn.js-5.2.1.tgz", + "integrity": "sha512-eXRvHzWyYPBuB4NBy0cmYQjGitUrtqwbvlzP3G6VFnNRbsZQIxQ10PbKKHt8gZ/HW/D/747aDl+QkDqg3KQLMQ==", + "dev": true + } + } + }, + "web3-eth-personal": { + "version": "1.10.0", + "resolved": "https://registry.npmjs.org/web3-eth-personal/-/web3-eth-personal-1.10.0.tgz", + "integrity": "sha512-anseKn98w/d703eWq52uNuZi7GhQeVjTC5/svrBWEKob0WZ5kPdo+EZoFN0sp5a5ubbrk/E0xSl1/M5yORMtpg==", + "dev": true, + "requires": { + "@types/node": "^12.12.6", + "web3-core": "1.10.0", + "web3-core-helpers": "1.10.0", + "web3-core-method": "1.10.0", + "web3-net": "1.10.0", + "web3-utils": "1.10.0" + } + }, + "web3-net": { + "version": "1.10.0", + "resolved": "https://registry.npmjs.org/web3-net/-/web3-net-1.10.0.tgz", + "integrity": "sha512-NLH/N3IshYWASpxk4/18Ge6n60GEvWBVeM8inx2dmZJVmRI6SJIlUxbL8jySgiTn3MMZlhbdvrGo8fpUW7a1GA==", + "dev": true, + "requires": { + "web3-core": "1.10.0", + "web3-core-method": "1.10.0", + "web3-utils": "1.10.0" + } + }, + "web3-providers-http": { + "version": "1.10.0", + "resolved": "https://registry.npmjs.org/web3-providers-http/-/web3-providers-http-1.10.0.tgz", + "integrity": "sha512-eNr965YB8a9mLiNrkjAWNAPXgmQWfpBfkkn7tpEFlghfww0u3I0tktMZiaToJVcL2+Xq+81cxbkpeWJ5XQDwOA==", + "dev": true, + "requires": { + "abortcontroller-polyfill": "^1.7.3", + "cross-fetch": "^3.1.4", + "es6-promise": "^4.2.8", + "web3-core-helpers": "1.10.0" + } + }, + "web3-providers-ipc": { + "version": "1.10.0", + "resolved": "https://registry.npmjs.org/web3-providers-ipc/-/web3-providers-ipc-1.10.0.tgz", + "integrity": "sha512-OfXG1aWN8L1OUqppshzq8YISkWrYHaATW9H8eh0p89TlWMc1KZOL9vttBuaBEi96D/n0eYDn2trzt22bqHWfXA==", + "dev": true, + "requires": { + "oboe": "2.1.5", + "web3-core-helpers": "1.10.0" + } + }, + "web3-providers-ws": { + "version": "1.10.0", + "resolved": "https://registry.npmjs.org/web3-providers-ws/-/web3-providers-ws-1.10.0.tgz", + "integrity": "sha512-sK0fNcglW36yD5xjnjtSGBnEtf59cbw4vZzJ+CmOWIKGIR96mP5l684g0WD0Eo+f4NQc2anWWXG74lRc9OVMCQ==", + "dev": true, + "requires": { + "eventemitter3": "4.0.4", + "web3-core-helpers": "1.10.0", + "websocket": "^1.0.32" + } + }, + "web3-shh": { + "version": "1.10.0", + "resolved": "https://registry.npmjs.org/web3-shh/-/web3-shh-1.10.0.tgz", + "integrity": "sha512-uNUUuNsO2AjX41GJARV9zJibs11eq6HtOe6Wr0FtRUcj8SN6nHeYIzwstAvJ4fXA53gRqFMTxdntHEt9aXVjpg==", + "dev": true, + "requires": { + "web3-core": "1.10.0", + "web3-core-method": "1.10.0", + "web3-core-subscriptions": "1.10.0", + "web3-net": "1.10.0" + } + }, + "web3-utils": { + "version": "1.10.0", + "resolved": "https://registry.npmjs.org/web3-utils/-/web3-utils-1.10.0.tgz", + "integrity": "sha512-kSaCM0uMcZTNUSmn5vMEhlo02RObGNRRCkdX0V9UTAU0+lrvn0HSaudyCo6CQzuXUsnuY2ERJGCGPfeWmv19Rg==", + "dev": true, + "requires": { + "bn.js": "^5.2.1", + "ethereum-bloom-filters": "^1.0.6", + "ethereumjs-util": "^7.1.0", + "ethjs-unit": "0.1.6", + "number-to-bn": "1.7.0", + "randombytes": "^2.1.0", + "utf8": "3.0.0" + }, + "dependencies": { + "bn.js": { + "version": "5.2.1", + "resolved": "https://registry.npmjs.org/bn.js/-/bn.js-5.2.1.tgz", + "integrity": "sha512-eXRvHzWyYPBuB4NBy0cmYQjGitUrtqwbvlzP3G6VFnNRbsZQIxQ10PbKKHt8gZ/HW/D/747aDl+QkDqg3KQLMQ==", + "dev": true + } + } + }, + "webidl-conversions": { + "version": "3.0.1", + "resolved": "https://registry.npmjs.org/webidl-conversions/-/webidl-conversions-3.0.1.tgz", + "integrity": "sha512-2JAn3z8AR6rjK8Sm8orRC0h/bcl/DqL7tRPdGZ4I1CjdF+EaMLmYxBHyXuKL849eucPFhvBoxMsflfOb8kxaeQ==", + "dev": true + }, + "websocket": { + "version": "1.0.34", + "resolved": "https://registry.npmjs.org/websocket/-/websocket-1.0.34.tgz", + "integrity": "sha512-PRDso2sGwF6kM75QykIesBijKSVceR6jL2G8NGYyq2XrItNC2P5/qL5XeR056GhA+Ly7JMFvJb9I312mJfmqnQ==", + "dev": true, + "requires": { + "bufferutil": "^4.0.1", + "debug": "^2.2.0", + "es5-ext": "^0.10.50", + "typedarray-to-buffer": "^3.1.5", + "utf-8-validate": "^5.0.2", + "yaeti": "^0.0.6" + }, + "dependencies": { + "debug": { + "version": "2.6.9", + "resolved": "https://registry.npmjs.org/debug/-/debug-2.6.9.tgz", + "integrity": "sha512-bC7ElrdJaJnPbAP+1EotYvqZsb3ecl5wi6Bfi6BJTUcNowp6cvspg0jXznRTKDjm/E7AdgFBVeAPVMNcKGsHMA==", + "dev": true, + "requires": { + "ms": "2.0.0" + } + }, + "ms": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/ms/-/ms-2.0.0.tgz", + "integrity": "sha512-Tpp60P6IUJDTuOq/5Z8cdskzJujfwqfOTkrwIwj7IRISpnkJnT6SyJ4PCPnGMoFjC9ddhal5KVIYtAt97ix05A==", + "dev": true + } + } + }, + "whatwg-url": { + "version": "5.0.0", + "resolved": "https://registry.npmjs.org/whatwg-url/-/whatwg-url-5.0.0.tgz", + "integrity": "sha512-saE57nupxk6v3HY35+jzBwYa0rKSy0XR8JSxZPwgLr7ys0IBzhGviA1/TUGJLmSVqs8pb9AnvICXEuOHLprYTw==", + "dev": true, + "requires": { + "tr46": "~0.0.3", + "webidl-conversions": "^3.0.0" + } + }, + "which": { + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/which/-/which-2.0.2.tgz", + "integrity": "sha512-BLI3Tl1TW3Pvl70l3yq3Y64i+awpwXqsGBYWkkqMtnbXgrMD+yj7rhW0kuEDxzJaYXGjEW5ogapKNMEKNMjibA==", + "dev": true, + "requires": { + "isexe": "^2.0.0" + } + }, + "which-boxed-primitive": { + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/which-boxed-primitive/-/which-boxed-primitive-1.0.2.tgz", + "integrity": "sha512-bwZdv0AKLpplFY2KZRX6TvyuN7ojjr7lwkg6ml0roIy9YeuSr7JS372qlNW18UQYzgYK9ziGcerWqZOmEn9VNg==", + "dev": true, + "requires": { + "is-bigint": "^1.0.1", + "is-boolean-object": "^1.1.0", + "is-number-object": "^1.0.4", + "is-string": "^1.0.5", + "is-symbol": "^1.0.3" + } + }, + "which-module": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/which-module/-/which-module-2.0.1.tgz", + "integrity": "sha512-iBdZ57RDvnOR9AGBhML2vFZf7h8vmBjhoaZqODJBFWHVtKkDmKuHai3cx5PgVMrX5YDNp27AofYbAwctSS+vhQ==", + "dev": true + }, + "which-pm": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/which-pm/-/which-pm-2.0.0.tgz", + "integrity": "sha512-Lhs9Pmyph0p5n5Z3mVnN0yWcbQYUAD7rbQUiMsQxOJ3T57k7RFe35SUwWMf7dsbDZks1uOmw4AecB/JMDj3v/w==", + "dev": true, + "requires": { + "load-yaml-file": "^0.2.0", + "path-exists": "^4.0.0" + } + }, + "which-typed-array": { + "version": "1.1.9", + "resolved": "https://registry.npmjs.org/which-typed-array/-/which-typed-array-1.1.9.tgz", + "integrity": "sha512-w9c4xkx6mPidwp7180ckYWfMmvxpjlZuIudNtDf4N/tTAUB8VJbX25qZoAsrtGuYNnGw3pa0AXgbGKRB8/EceA==", + "dev": true, + "requires": { + "available-typed-arrays": "^1.0.5", + "call-bind": "^1.0.2", + "for-each": "^0.3.3", + "gopd": "^1.0.1", + "has-tostringtag": "^1.0.0", + "is-typed-array": "^1.1.10" + } + }, + "wide-align": { + "version": "1.1.3", + "resolved": "https://registry.npmjs.org/wide-align/-/wide-align-1.1.3.tgz", + "integrity": "sha512-QGkOQc8XL6Bt5PwnsExKBPuMKBxnGxWWW3fU55Xt4feHozMUhdUMaBCk290qpm/wG5u/RSKzwdAC4i51YigihA==", + "dev": true, + "requires": { + "string-width": "^1.0.2 || 2" + } + }, + "window-size": { + "version": "0.2.0", + "resolved": "https://registry.npmjs.org/window-size/-/window-size-0.2.0.tgz", + "integrity": "sha512-UD7d8HFA2+PZsbKyaOCEy8gMh1oDtHgJh1LfgjQ4zVXmYjAT/kvz3PueITKuqDiIXQe7yzpPnxX3lNc+AhQMyw==", + "dev": true + }, + "word-wrap": { + "version": "1.2.4", + "resolved": "https://registry.npmjs.org/word-wrap/-/word-wrap-1.2.4.tgz", + "integrity": "sha512-2V81OA4ugVo5pRo46hAoD2ivUJx8jXmWXfUkY4KFNw0hEptvN0QfH3K4nHiwzGeKl5rFKedV48QVoqYavy4YpA==", + "dev": true + }, + "wordwrap": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/wordwrap/-/wordwrap-1.0.0.tgz", + "integrity": "sha512-gvVzJFlPycKc5dZN4yPkP8w7Dc37BtP1yczEneOb4uq34pXZcvrtRTmWV8W+Ume+XCxKgbjM+nevkyFPMybd4Q==", + "dev": true + }, + "workerpool": { + "version": "6.2.1", + "resolved": "https://registry.npmjs.org/workerpool/-/workerpool-6.2.1.tgz", + "integrity": "sha512-ILEIE97kDZvF9Wb9f6h5aXK4swSlKGUcOEGiIYb2OOu/IrDU9iwj0fD//SsA6E5ibwJxpEvhullJY4Sl4GcpAw==", + "dev": true + }, + "wrap-ansi": { + "version": "7.0.0", + "resolved": "https://registry.npmjs.org/wrap-ansi/-/wrap-ansi-7.0.0.tgz", + "integrity": "sha512-YVGIj2kamLSTxw6NsZjoBxfSwsn0ycdesmc4p+Q21c5zPuZ1pl+NfxVdxPtdHvmNVOQ6XSYG4AUtyt/Fi7D16Q==", + "dev": true, + "requires": { + "ansi-styles": "^4.0.0", + "string-width": "^4.1.0", + "strip-ansi": "^6.0.0" + }, + "dependencies": { + "ansi-regex": { + "version": "5.0.1", + "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-5.0.1.tgz", + "integrity": "sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ==", + "dev": true + }, + "ansi-styles": { + "version": "4.3.0", + "resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-4.3.0.tgz", + "integrity": "sha512-zbB9rCJAT1rbjiVDb2hqKFHNYLxgtk8NURxZ3IZwD3F6NtxbXZQCnnSi1Lkx+IDohdPlFp222wVALIheZJQSEg==", + "dev": true, + "requires": { + "color-convert": "^2.0.1" + } + }, + "color-convert": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/color-convert/-/color-convert-2.0.1.tgz", + "integrity": "sha512-RRECPsj7iu/xb5oKYcsFHSppFNnsj/52OVTRKb4zP5onXwVF3zVmmToNcOfGC+CRDpfK/U584fMg38ZHCaElKQ==", + "dev": true, + "requires": { + "color-name": "~1.1.4" + } + }, + "color-name": { + "version": "1.1.4", + "resolved": "https://registry.npmjs.org/color-name/-/color-name-1.1.4.tgz", + "integrity": "sha512-dOy+3AuW3a2wNbZHIuMZpTcgjGuLU/uBL/ubcZF9OXbDo8ff4O8yVp5Bf0efS8uEoYo5q4Fx7dY9OgQGXgAsQA==", + "dev": true + }, + "is-fullwidth-code-point": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/is-fullwidth-code-point/-/is-fullwidth-code-point-3.0.0.tgz", + "integrity": "sha512-zymm5+u+sCsSWyD9qNaejV3DFvhCKclKdizYaJUuHA83RLjb7nSuGnddCHGv0hk+KY7BMAlsWeK4Ueg6EV6XQg==", + "dev": true + }, + "string-width": { + "version": "4.2.3", + "resolved": "https://registry.npmjs.org/string-width/-/string-width-4.2.3.tgz", + "integrity": "sha512-wKyQRQpjJ0sIp62ErSZdGsjMJWsap5oRNihHhu6G7JVO/9jIB6UyevL+tXuOqrng8j/cxKTWyWUwvSTriiZz/g==", + "dev": true, + "requires": { + "emoji-regex": "^8.0.0", + "is-fullwidth-code-point": "^3.0.0", + "strip-ansi": "^6.0.1" + } + }, + "strip-ansi": { + "version": "6.0.1", + "resolved": "https://registry.npmjs.org/strip-ansi/-/strip-ansi-6.0.1.tgz", + "integrity": "sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A==", + "dev": true, + "requires": { + "ansi-regex": "^5.0.1" + } + } + } + }, + "wrappy": { + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/wrappy/-/wrappy-1.0.2.tgz", + "integrity": "sha512-l4Sp/DRseor9wL6EvV2+TuQn63dMkPjZ/sp9XkghTEbV9KlPS1xUsZ3u7/IQO4wxtcFB4bgpQPRcR3QCvezPcQ==", + "dev": true + }, + "ws": { + "version": "7.5.9", + "resolved": "https://registry.npmjs.org/ws/-/ws-7.5.9.tgz", + "integrity": "sha512-F+P9Jil7UiSKSkppIiD94dN07AwvFixvLIj1Og1Rl9GGMuNipJnV9JzjD6XuqmAeiswGvUmNLjr5cFuXwNS77Q==", + "dev": true, + "requires": {} + }, + "xhr": { + "version": "2.6.0", + "resolved": "https://registry.npmjs.org/xhr/-/xhr-2.6.0.tgz", + "integrity": "sha512-/eCGLb5rxjx5e3mF1A7s+pLlR6CGyqWN91fv1JgER5mVWg1MZmlhBvy9kjcsOdRk8RrIujotWyJamfyrp+WIcA==", + "dev": true, + "requires": { + "global": "~4.4.0", + "is-function": "^1.0.1", + "parse-headers": "^2.0.0", + "xtend": "^4.0.0" + } + }, + "xhr-request": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/xhr-request/-/xhr-request-1.1.0.tgz", + "integrity": "sha512-Y7qzEaR3FDtL3fP30k9wO/e+FBnBByZeybKOhASsGP30NIkRAAkKD/sCnLvgEfAIEC1rcmK7YG8f4oEnIrrWzA==", + "dev": true, + "requires": { + "buffer-to-arraybuffer": "^0.0.5", + "object-assign": "^4.1.1", + "query-string": "^5.0.1", + "simple-get": "^2.7.0", + "timed-out": "^4.0.1", + "url-set-query": "^1.0.0", + "xhr": "^2.0.4" + } + }, + "xhr-request-promise": { + "version": "0.1.3", + "resolved": "https://registry.npmjs.org/xhr-request-promise/-/xhr-request-promise-0.1.3.tgz", + "integrity": "sha512-YUBytBsuwgitWtdRzXDDkWAXzhdGB8bYm0sSzMPZT7Z2MBjMSTHFsyCT1yCRATY+XC69DUrQraRAEgcoCRaIPg==", + "dev": true, + "requires": { + "xhr-request": "^1.1.0" + } + }, + "xmlhttprequest": { + "version": "1.8.0", + "resolved": "https://registry.npmjs.org/xmlhttprequest/-/xmlhttprequest-1.8.0.tgz", + "integrity": "sha512-58Im/U0mlVBLM38NdZjHyhuMtCqa61469k2YP/AaPbvCoV9aQGUpbJBj1QRm2ytRiVQBD/fsw7L2bJGDVQswBA==", + "dev": true + }, + "xtend": { + "version": "4.0.2", + "resolved": "https://registry.npmjs.org/xtend/-/xtend-4.0.2.tgz", + "integrity": "sha512-LKYU1iAXJXUgAXn9URjiu+MWhyUXHsvfp7mcuYm9dSUKK0/CjtrUwFAxD82/mCWbtLsGjFIad0wIsod4zrTAEQ==", + "dev": true + }, + "y18n": { + "version": "5.0.8", + "resolved": "https://registry.npmjs.org/y18n/-/y18n-5.0.8.tgz", + "integrity": "sha512-0pfFzegeDWJHJIAmTLRP2DwHjdF5s7jo9tuztdQxAhINCdvS+3nGINqPd00AphqJR/0LhANUS6/+7SCb98YOfA==", + "dev": true + }, + "yaeti": { + "version": "0.0.6", + "resolved": "https://registry.npmjs.org/yaeti/-/yaeti-0.0.6.tgz", + "integrity": "sha512-MvQa//+KcZCUkBTIC9blM+CU9J2GzuTytsOUwf2lidtvkx/6gnEp1QvJv34t9vdjhFmha/mUiNDbN0D0mJWdug==", + "dev": true + }, + "yallist": { + "version": "3.1.1", + "resolved": "https://registry.npmjs.org/yallist/-/yallist-3.1.1.tgz", + "integrity": "sha512-a4UGQaWPH59mOXUYnAG2ewncQS4i4F43Tv3JoAM+s2VDAmS9NsK8GpDMLrCHPksFT7h3K6TOoUNn2pb7RoXx4g==", + "dev": true + }, + "yargs": { + "version": "17.7.2", + "resolved": "https://registry.npmjs.org/yargs/-/yargs-17.7.2.tgz", + "integrity": "sha512-7dSzzRQ++CKnNI/krKnYRV7JKKPUXMEh61soaHKg9mrWEhzFWhFnxPxGl+69cD1Ou63C13NUPCnmIcrvqCuM6w==", + "dev": true, + "requires": { + "cliui": "^8.0.1", + "escalade": "^3.1.1", + "get-caller-file": "^2.0.5", + "require-directory": "^2.1.1", + "string-width": "^4.2.3", + "y18n": "^5.0.5", + "yargs-parser": "^21.1.1" + }, + "dependencies": { + "ansi-regex": { + "version": "5.0.1", + "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-5.0.1.tgz", + "integrity": "sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ==", + "dev": true + }, + "is-fullwidth-code-point": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/is-fullwidth-code-point/-/is-fullwidth-code-point-3.0.0.tgz", + "integrity": "sha512-zymm5+u+sCsSWyD9qNaejV3DFvhCKclKdizYaJUuHA83RLjb7nSuGnddCHGv0hk+KY7BMAlsWeK4Ueg6EV6XQg==", + "dev": true + }, + "string-width": { + "version": "4.2.3", + "resolved": "https://registry.npmjs.org/string-width/-/string-width-4.2.3.tgz", + "integrity": "sha512-wKyQRQpjJ0sIp62ErSZdGsjMJWsap5oRNihHhu6G7JVO/9jIB6UyevL+tXuOqrng8j/cxKTWyWUwvSTriiZz/g==", + "dev": true, + "requires": { + "emoji-regex": "^8.0.0", + "is-fullwidth-code-point": "^3.0.0", + "strip-ansi": "^6.0.1" + } + }, + "strip-ansi": { + "version": "6.0.1", + "resolved": "https://registry.npmjs.org/strip-ansi/-/strip-ansi-6.0.1.tgz", + "integrity": "sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A==", + "dev": true, + "requires": { + "ansi-regex": "^5.0.1" + } + }, + "yargs-parser": { + "version": "21.1.1", + "resolved": "https://registry.npmjs.org/yargs-parser/-/yargs-parser-21.1.1.tgz", + "integrity": "sha512-tVpsJW7DdjecAiFpbIB1e3qxIQsE6NoPc5/eTdrbbIC4h0LVsWhnoa3g+m2HclBIujHzsxZ4VJVA+GUuc2/LBw==", + "dev": true + } + } + }, + "yargs-parser": { + "version": "18.1.3", + "resolved": "https://registry.npmjs.org/yargs-parser/-/yargs-parser-18.1.3.tgz", + "integrity": "sha512-o50j0JeToy/4K6OZcaQmW6lyXXKhq7csREXcDwk2omFPJEwUNOVtJKvmDr9EI1fAJZUyZcRF7kxGBWmRXudrCQ==", + "dev": true, + "requires": { + "camelcase": "^5.0.0", + "decamelize": "^1.2.0" + }, + "dependencies": { + "camelcase": { + "version": "5.3.1", + "resolved": "https://registry.npmjs.org/camelcase/-/camelcase-5.3.1.tgz", + "integrity": "sha512-L28STB170nwWS63UjtlEOE3dldQApaJXZkOI1uMFfzf3rRuPegHaHesyee+YxQ+W6SvRDQV6UrdOdRiR153wJg==", + "dev": true + } + } + }, + "yargs-unparser": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/yargs-unparser/-/yargs-unparser-2.0.0.tgz", + "integrity": "sha512-7pRTIA9Qc1caZ0bZ6RYRGbHJthJWuakf+WmHK0rVeLkNrrGhfoabBNdue6kdINI6r4if7ocq9aD/n7xwKOdzOA==", + "dev": true, + "requires": { + "camelcase": "^6.0.0", + "decamelize": "^4.0.0", + "flat": "^5.0.2", + "is-plain-obj": "^2.1.0" + }, + "dependencies": { + "camelcase": { + "version": "6.3.0", + "resolved": "https://registry.npmjs.org/camelcase/-/camelcase-6.3.0.tgz", + "integrity": "sha512-Gmy6FhYlCY7uOElZUSbxo2UCDH8owEk996gkbrpsgGtrJLM3J7jGxl9Ic7Qwwj4ivOE5AWZWRMecDdF7hqGjFA==", + "dev": true + }, + "decamelize": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/decamelize/-/decamelize-4.0.0.tgz", + "integrity": "sha512-9iE1PgSik9HeIIw2JO94IidnE3eBoQrFJ3w7sFuzSX4DpmZ3v5sZpUiV5Swcf6mQEF+Y0ru8Neo+p+nyh2J+hQ==", + "dev": true + }, + "is-plain-obj": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/is-plain-obj/-/is-plain-obj-2.1.0.tgz", + "integrity": "sha512-YWnfyRwxL/+SsrWYfOpUtz5b3YD+nyfkHvjbcanzk8zgyO4ASD67uVMRt8k5bM4lLMDnXfriRhOpemw+NfT1eA==", + "dev": true + } + } + }, + "yocto-queue": { + "version": "0.1.0", + "resolved": "https://registry.npmjs.org/yocto-queue/-/yocto-queue-0.1.0.tgz", + "integrity": "sha512-rVksvsnNCdJ/ohGc6xgPwyN8eheCxsiLM8mxuE/t/mOVqJewPuO1miLpTHQiRgTKCLexL4MeAFVagts7HmNZ2Q==", + "dev": true + } + } +} diff --git a/package.json b/package.json new file mode 100644 index 000000000..e0dddef55 --- /dev/null +++ b/package.json @@ -0,0 +1,95 @@ +{ + "name": "openzeppelin-solidity", + "description": "Secure Smart Contract library for Solidity", + "version": "5.0.0-rc.0", + "files": [ + "/contracts/**/*.sol", + "/build/contracts/*.json", + "!/contracts/mocks/**/*" + ], + "scripts": { + "compile": "hardhat compile", + "coverage": "env COVERAGE=true hardhat coverage", + "docs": "npm run prepare-docs && oz-docs", + "docs:watch": "oz-docs watch contracts docs/templates docs/config.js", + "prepare-docs": "scripts/prepare-docs.sh", + "lint": "npm run lint:js && npm run lint:sol", + "lint:fix": "npm run lint:js:fix && npm run lint:sol:fix", + "lint:js": "prettier --log-level warn --ignore-path .gitignore '**/*.{js,ts}' --check && eslint --ignore-path .gitignore .", + "lint:js:fix": "prettier --log-level warn --ignore-path .gitignore '**/*.{js,ts}' --write && eslint --ignore-path .gitignore . --fix", + "lint:sol": "prettier --log-level warn --ignore-path .gitignore '{contracts,test}/**/*.sol' --check && solhint '{contracts,test}/**/*.sol'", + "lint:sol:fix": "prettier --log-level warn --ignore-path .gitignore '{contracts,test}/**/*.sol' --write", + "clean": "hardhat clean && rimraf build contracts/build", + "prepare": "scripts/prepare.sh", + "prepack": "scripts/prepack.sh", + "generate": "scripts/generate/run.js", + "release": "scripts/release/release.sh", + "version": "scripts/release/version.sh", + "test": "hardhat test", + "test:inheritance": "scripts/checks/inheritance-ordering.js artifacts/build-info/*", + "test:generation": "scripts/checks/generation.sh", + "gas-report": "env ENABLE_GAS_REPORT=true npm run test", + "slither": "npm run clean && slither ." + }, + "repository": { + "type": "git", + "url": "https://github.com/OpenZeppelin/openzeppelin-contracts.git" + }, + "keywords": [ + "solidity", + "ethereum", + "smart", + "contracts", + "security", + "zeppelin" + ], + "author": "OpenZeppelin Community ", + "license": "MIT", + "bugs": { + "url": "https://github.com/OpenZeppelin/openzeppelin-contracts/issues" + }, + "homepage": "https://openzeppelin.com/contracts/", + "devDependencies": { + "@changesets/changelog-github": "^0.4.8", + "@changesets/cli": "^2.26.0", + "@changesets/pre": "^1.0.14", + "@changesets/read": "^0.5.9", + "@nomicfoundation/hardhat-network-helpers": "^1.0.3", + "@nomiclabs/hardhat-truffle5": "^2.0.5", + "@nomiclabs/hardhat-web3": "^2.0.0", + "@openzeppelin/docs-utils": "^0.1.4", + "@openzeppelin/test-helpers": "^0.5.13", + "@openzeppelin/upgrades-core": "^1.20.6", + "array.prototype.at": "^1.1.1", + "chai": "^4.2.0", + "eslint": "^8.30.0", + "eslint-config-prettier": "^9.0.0", + "eth-sig-util": "^3.0.0", + "ethereumjs-util": "^7.0.7", + "ethereumjs-wallet": "^1.0.1", + "glob": "^8.0.3", + "graphlib": "^2.1.8", + "hardhat": "^2.9.1", + "hardhat-exposed": "^0.3.11", + "hardhat-gas-reporter": "^1.0.4", + "hardhat-ignore-warnings": "^0.2.0", + "keccak256": "^1.0.2", + "lodash.startcase": "^4.4.0", + "lodash.zip": "^4.2.0", + "merkletreejs": "^0.2.13", + "micromatch": "^4.0.2", + "p-limit": "^3.1.0", + "prettier": "^3.0.0", + "prettier-plugin-solidity": "^1.1.0", + "rimraf": "^3.0.2", + "semver": "^7.3.5", + "solhint": "^3.3.6", + "solhint-plugin-openzeppelin": "file:scripts/solhint-custom", + "solidity-ast": "^0.4.50", + "solidity-coverage": "^0.8.0", + "solidity-docgen": "^0.6.0-beta.29", + "undici": "^5.22.1", + "web3": "^1.3.0", + "yargs": "^17.0.0" + } +} diff --git a/remappings.txt b/remappings.txt new file mode 100644 index 000000000..304d1386a --- /dev/null +++ b/remappings.txt @@ -0,0 +1 @@ +@openzeppelin/contracts/=contracts/ diff --git a/renovate.json b/renovate.json new file mode 100644 index 000000000..c0b97d8d7 --- /dev/null +++ b/renovate.json @@ -0,0 +1,4 @@ +{ + "extends": ["github>OpenZeppelin/configs"], + "labels": ["ignore-changeset"] +} diff --git a/requirements.txt b/requirements.txt new file mode 100644 index 000000000..fd0ec3019 --- /dev/null +++ b/requirements.txt @@ -0,0 +1 @@ +certora-cli==4.8.0 diff --git a/scripts/checks/compare-layout.js b/scripts/checks/compare-layout.js new file mode 100644 index 000000000..4368b77fb --- /dev/null +++ b/scripts/checks/compare-layout.js @@ -0,0 +1,20 @@ +const fs = require('fs'); +const { getStorageUpgradeReport } = require('@openzeppelin/upgrades-core/dist/storage'); + +const { ref, head } = require('yargs').argv; + +const oldLayout = JSON.parse(fs.readFileSync(ref)); +const newLayout = JSON.parse(fs.readFileSync(head)); + +for (const name in oldLayout) { + if (name in newLayout) { + const report = getStorageUpgradeReport(oldLayout[name], newLayout[name], {}); + if (!report.ok) { + console.log(`Storage layout incompatilibity found in ${name}:`); + console.log(report.explain()); + process.exitCode = 1; + } + } else { + console.log(`WARNING: ${name} is missing from the current branch`); + } +} diff --git a/scripts/checks/compareGasReports.js b/scripts/checks/compareGasReports.js new file mode 100755 index 000000000..160c8cc52 --- /dev/null +++ b/scripts/checks/compareGasReports.js @@ -0,0 +1,243 @@ +#!/usr/bin/env node + +const fs = require('fs'); +const chalk = require('chalk'); +const { argv } = require('yargs') + .env() + .options({ + style: { + type: 'string', + choices: ['shell', 'markdown'], + default: 'shell', + }, + hideEqual: { + type: 'boolean', + default: true, + }, + strictTesting: { + type: 'boolean', + default: false, + }, + }); + +// Deduce base tx cost from the percentage denominator +const BASE_TX_COST = 21000; + +// Utilities +function sum(...args) { + return args.reduce((a, b) => a + b, 0); +} + +function average(...args) { + return sum(...args) / args.length; +} + +function variation(current, previous, offset = 0) { + return { + value: current, + delta: current - previous, + prcnt: (100 * (current - previous)) / (previous - offset), + }; +} + +// Report class +class Report { + // Read report file + static load(filepath) { + return JSON.parse(fs.readFileSync(filepath, 'utf8')); + } + + // Compare two reports + static compare(update, ref, opts = { hideEqual: true, strictTesting: false }) { + if (JSON.stringify(update.config.metadata) !== JSON.stringify(ref.config.metadata)) { + throw new Error('Reports produced with non matching metadata'); + } + + const deployments = update.info.deployments + .map(contract => + Object.assign(contract, { previousVersion: ref.info.deployments.find(({ name }) => name === contract.name) }), + ) + .filter(contract => contract.gasData?.length && contract.previousVersion?.gasData?.length) + .flatMap(contract => [ + { + contract: contract.name, + method: '[bytecode length]', + avg: variation(contract.bytecode.length / 2 - 1, contract.previousVersion.bytecode.length / 2 - 1), + }, + { + contract: contract.name, + method: '[construction cost]', + avg: variation( + ...[contract.gasData, contract.previousVersion.gasData].map(x => Math.round(average(...x))), + BASE_TX_COST, + ), + }, + ]) + .sort((a, b) => `${a.contract}:${a.method}`.localeCompare(`${b.contract}:${b.method}`)); + + const methods = Object.keys(update.info.methods) + .filter(key => ref.info.methods[key]) + .filter(key => update.info.methods[key].numberOfCalls > 0) + .filter( + key => !opts.strictTesting || update.info.methods[key].numberOfCalls === ref.info.methods[key].numberOfCalls, + ) + .map(key => ({ + contract: ref.info.methods[key].contract, + method: ref.info.methods[key].fnSig, + min: variation(...[update, ref].map(x => Math.min(...x.info.methods[key].gasData)), BASE_TX_COST), + max: variation(...[update, ref].map(x => Math.max(...x.info.methods[key].gasData)), BASE_TX_COST), + avg: variation(...[update, ref].map(x => Math.round(average(...x.info.methods[key].gasData))), BASE_TX_COST), + })) + .sort((a, b) => `${a.contract}:${a.method}`.localeCompare(`${b.contract}:${b.method}`)); + + return [] + .concat(deployments, methods) + .filter(row => !opts.hideEqual || row.min?.delta || row.max?.delta || row.avg?.delta); + } +} + +// Display +function center(text, length) { + return text.padStart((text.length + length) / 2).padEnd(length); +} + +function plusSign(num) { + return num > 0 ? '+' : ''; +} + +function formatCellShell(cell) { + const format = chalk[cell?.delta > 0 ? 'red' : cell?.delta < 0 ? 'green' : 'reset']; + return [ + format((!isFinite(cell?.value) ? '-' : cell.value.toString()).padStart(8)), + format((!isFinite(cell?.delta) ? '-' : plusSign(cell.delta) + cell.delta.toString()).padStart(8)), + format((!isFinite(cell?.prcnt) ? '-' : plusSign(cell.prcnt) + cell.prcnt.toFixed(2) + '%').padStart(8)), + ]; +} + +function formatCmpShell(rows) { + const contractLength = Math.max(8, ...rows.map(({ contract }) => contract.length)); + const methodLength = Math.max(7, ...rows.map(({ method }) => method.length)); + + const COLS = [ + { txt: '', length: 0 }, + { txt: 'Contract', length: contractLength }, + { txt: 'Method', length: methodLength }, + { txt: 'Min', length: 30 }, + { txt: 'Max', length: 30 }, + { txt: 'Avg', length: 30 }, + { txt: '', length: 0 }, + ]; + const HEADER = COLS.map(entry => chalk.bold(center(entry.txt, entry.length || 0))) + .join(' | ') + .trim(); + const SEPARATOR = COLS.map(({ length }) => (length > 0 ? '-'.repeat(length + 2) : '')) + .join('|') + .trim(); + + return [ + '', + HEADER, + ...rows.map(entry => + [ + '', + chalk.grey(entry.contract.padEnd(contractLength)), + entry.method.padEnd(methodLength), + ...formatCellShell(entry.min), + ...formatCellShell(entry.max), + ...formatCellShell(entry.avg), + '', + ] + .join(' | ') + .trim(), + ), + '', + ] + .join(`\n${SEPARATOR}\n`) + .trim(); +} + +function alignPattern(align) { + switch (align) { + case 'left': + case undefined: + return ':-'; + case 'right': + return '-:'; + case 'center': + return ':-:'; + } +} + +function trend(value) { + return value > 0 ? ':x:' : value < 0 ? ':heavy_check_mark:' : ':heavy_minus_sign:'; +} + +function formatCellMarkdown(cell) { + return [ + !isFinite(cell?.value) ? '-' : cell.value.toString(), + !isFinite(cell?.delta) ? '-' : plusSign(cell.delta) + cell.delta.toString(), + !isFinite(cell?.prcnt) ? '-' : plusSign(cell.prcnt) + cell.prcnt.toFixed(2) + '%' + trend(cell.delta), + ]; +} + +function formatCmpMarkdown(rows) { + const COLS = [ + { txt: '' }, + { txt: 'Contract', align: 'left' }, + { txt: 'Method', align: 'left' }, + { txt: 'Min', align: 'right' }, + { txt: '(+/-)', align: 'right' }, + { txt: '%', align: 'right' }, + { txt: 'Max', align: 'right' }, + { txt: '(+/-)', align: 'right' }, + { txt: '%', align: 'right' }, + { txt: 'Avg', align: 'right' }, + { txt: '(+/-)', align: 'right' }, + { txt: '%', align: 'right' }, + { txt: '' }, + ]; + const HEADER = COLS.map(entry => entry.txt) + .join(' | ') + .trim(); + const SEPARATOR = COLS.map(entry => (entry.txt ? alignPattern(entry.align) : '')) + .join('|') + .trim(); + + return [ + '# Changes to gas costs', + '', + HEADER, + SEPARATOR, + rows + .map(entry => + [ + '', + entry.contract, + entry.method, + ...formatCellMarkdown(entry.min), + ...formatCellMarkdown(entry.max), + ...formatCellMarkdown(entry.avg), + '', + ] + .join(' | ') + .trim(), + ) + .join('\n'), + '', + ] + .join('\n') + .trim(); +} + +// MAIN +const report = Report.compare(Report.load(argv._[0]), Report.load(argv._[1]), argv); + +switch (argv.style) { + case 'markdown': + console.log(formatCmpMarkdown(report)); + break; + case 'shell': + default: + console.log(formatCmpShell(report)); + break; +} diff --git a/scripts/checks/extract-layout.js b/scripts/checks/extract-layout.js new file mode 100644 index 000000000..d0c9cf36b --- /dev/null +++ b/scripts/checks/extract-layout.js @@ -0,0 +1,40 @@ +const fs = require('fs'); +const { findAll } = require('solidity-ast/utils'); +const { astDereferencer } = require('@openzeppelin/upgrades-core/dist/ast-dereferencer'); +const { solcInputOutputDecoder } = require('@openzeppelin/upgrades-core/dist/src-decoder'); +const { extractStorageLayout } = require('@openzeppelin/upgrades-core/dist/storage/extract'); + +const { _ } = require('yargs').argv; + +const skipPath = ['contracts/mocks/', 'contracts-exposed/']; +const skipKind = ['interface', 'library']; + +function extractLayouts(path) { + const layout = {}; + const { input, output } = JSON.parse(fs.readFileSync(path)); + + const decoder = solcInputOutputDecoder(input, output); + const deref = astDereferencer(output); + + for (const src in output.contracts) { + if (skipPath.some(prefix => src.startsWith(prefix))) { + continue; + } + + for (const contractDef of findAll('ContractDefinition', output.sources[src].ast)) { + if (skipKind.includes(contractDef.contractKind)) { + continue; + } + + layout[contractDef.name] = extractStorageLayout( + contractDef, + decoder, + deref, + output.contracts[src][contractDef.name].storageLayout, + ); + } + } + return layout; +} + +console.log(JSON.stringify(Object.assign(..._.map(extractLayouts)))); diff --git a/scripts/checks/generation.sh b/scripts/checks/generation.sh new file mode 100755 index 000000000..00d609f94 --- /dev/null +++ b/scripts/checks/generation.sh @@ -0,0 +1,6 @@ +#!/usr/bin/env bash + +set -euo pipefail + +npm run generate +git diff -R --exit-code diff --git a/scripts/checks/inheritance-ordering.js b/scripts/checks/inheritance-ordering.js new file mode 100755 index 000000000..72aa37ef7 --- /dev/null +++ b/scripts/checks/inheritance-ordering.js @@ -0,0 +1,54 @@ +#!/usr/bin/env node + +const path = require('path'); +const graphlib = require('graphlib'); +const { findAll } = require('solidity-ast/utils'); +const { _: artifacts } = require('yargs').argv; + +for (const artifact of artifacts) { + const { output: solcOutput } = require(path.resolve(__dirname, '../..', artifact)); + + const graph = new graphlib.Graph({ directed: true }); + const names = {}; + const linearized = []; + + for (const source in solcOutput.contracts) { + if (['contracts-exposed/', 'contracts/mocks/'].some(pattern => source.startsWith(pattern))) { + continue; + } + + for (const contractDef of findAll('ContractDefinition', solcOutput.sources[source].ast)) { + names[contractDef.id] = contractDef.name; + linearized.push(contractDef.linearizedBaseContracts); + + contractDef.linearizedBaseContracts.forEach((c1, i, contracts) => + contracts.slice(i + 1).forEach(c2 => { + graph.setEdge(c1, c2); + }), + ); + } + } + + /// graphlib.alg.findCycles will not find minimal cycles. + /// We are only interested int cycles of lengths 2 (needs proof) + graph.nodes().forEach((x, i, nodes) => + nodes + .slice(i + 1) + .filter(y => graph.hasEdge(x, y) && graph.hasEdge(y, x)) + .forEach(y => { + console.log(`Conflict between ${names[x]} and ${names[y]} detected in the following dependency chains:`); + linearized + .filter(chain => chain.includes(parseInt(x)) && chain.includes(parseInt(y))) + .forEach(chain => { + const comp = chain.indexOf(parseInt(x)) < chain.indexOf(parseInt(y)) ? '>' : '<'; + console.log(`- ${names[x]} ${comp} ${names[y]} in ${names[chain.find(Boolean)]}`); + // console.log(`- ${names[x]} ${comp} ${names[y]}: ${chain.reverse().map(id => names[id]).join(', ')}`); + }); + process.exitCode = 1; + }), + ); +} + +if (!process.exitCode) { + console.log('Contract ordering is consistent.'); +} diff --git a/scripts/gen-nav.js b/scripts/gen-nav.js new file mode 100644 index 000000000..de3d0daba --- /dev/null +++ b/scripts/gen-nav.js @@ -0,0 +1,41 @@ +#!/usr/bin/env node + +const path = require('path'); +const glob = require('glob'); +const startCase = require('lodash.startcase'); + +const baseDir = process.argv[2]; + +const files = glob.sync(baseDir + '/**/*.adoc').map(f => path.relative(baseDir, f)); + +console.log('.API'); + +function getPageTitle(directory) { + switch (directory) { + case 'metatx': + return 'Meta Transactions'; + case 'common': + return 'Common (Tokens)'; + default: + return startCase(directory); + } +} + +const links = files.map(file => { + const doc = file.replace(baseDir, ''); + const title = path.parse(file).name; + + return { + xref: `* xref:${doc}[${getPageTitle(title)}]`, + title, + }; +}); + +// Case-insensitive sort based on titles (so 'token/ERC20' gets sorted as 'erc20') +const sortedLinks = links.sort(function (a, b) { + return a.title.toLowerCase().localeCompare(b.title.toLowerCase(), undefined, { numeric: true }); +}); + +for (const link of sortedLinks) { + console.log(link.xref); +} diff --git a/scripts/generate/format-lines.js b/scripts/generate/format-lines.js new file mode 100644 index 000000000..fa3d6b120 --- /dev/null +++ b/scripts/generate/format-lines.js @@ -0,0 +1,16 @@ +function formatLines(...lines) { + return [...indentEach(0, lines)].join('\n') + '\n'; +} + +function* indentEach(indent, lines) { + for (const line of lines) { + if (Array.isArray(line)) { + yield* indentEach(indent + 1, line); + } else { + const padding = ' '.repeat(indent); + yield* line.split('\n').map(subline => (subline === '' ? '' : padding + subline)); + } + } +} + +module.exports = formatLines; diff --git a/scripts/generate/run.js b/scripts/generate/run.js new file mode 100755 index 000000000..53589455a --- /dev/null +++ b/scripts/generate/run.js @@ -0,0 +1,49 @@ +#!/usr/bin/env node + +const cp = require('child_process'); +const fs = require('fs'); +const path = require('path'); +const format = require('./format-lines'); + +function getVersion(path) { + try { + return fs.readFileSync(path, 'utf8').match(/\/\/ OpenZeppelin Contracts \(last updated v[^)]+\)/)[0]; + } catch (err) { + return null; + } +} + +function generateFromTemplate(file, template, outputPrefix = '') { + const script = path.relative(path.join(__dirname, '../..'), __filename); + const input = path.join(path.dirname(script), template); + const output = path.join(outputPrefix, file); + const version = getVersion(output); + const content = format( + '// SPDX-License-Identifier: MIT', + ...(version ? [version + ` (${file})`] : []), + `// This file was procedurally generated from ${input}.`, + '', + require(template), + ); + + fs.writeFileSync(output, content); + cp.execFileSync('prettier', ['--write', output]); +} + +// Contracts +for (const [file, template] of Object.entries({ + 'utils/math/SafeCast.sol': './templates/SafeCast.js', + 'utils/structs/EnumerableSet.sol': './templates/EnumerableSet.js', + 'utils/structs/EnumerableMap.sol': './templates/EnumerableMap.js', + 'utils/structs/Checkpoints.sol': './templates/Checkpoints.js', + 'utils/StorageSlot.sol': './templates/StorageSlot.js', +})) { + generateFromTemplate(file, template, './contracts/'); +} + +// Tests +for (const [file, template] of Object.entries({ + 'utils/structs/Checkpoints.t.sol': './templates/Checkpoints.t.js', +})) { + generateFromTemplate(file, template, './test/'); +} diff --git a/scripts/generate/templates/Checkpoints.js b/scripts/generate/templates/Checkpoints.js new file mode 100644 index 000000000..321a77489 --- /dev/null +++ b/scripts/generate/templates/Checkpoints.js @@ -0,0 +1,247 @@ +const format = require('../format-lines'); +const { OPTS } = require('./Checkpoints.opts.js'); + +// TEMPLATE +const header = `\ +pragma solidity ^0.8.20; + +import {Math} from "../math/Math.sol"; + +/** + * @dev This library defines the \`Trace*\` struct, for checkpointing values as they change at different points in + * time, and later looking up past values by block number. See {Votes} as an example. + * + * To create a history of checkpoints define a variable type \`Checkpoints.Trace*\` in your contract, and store a new + * checkpoint for the current transaction block using the {push} function. + */ +`; + +const errors = `\ + /** + * @dev A value was attempted to be inserted on a past checkpoint. + */ + error CheckpointUnorderedInsertion(); +`; + +const template = opts => `\ +struct ${opts.historyTypeName} { + ${opts.checkpointTypeName}[] ${opts.checkpointFieldName}; +} + +struct ${opts.checkpointTypeName} { + ${opts.keyTypeName} ${opts.keyFieldName}; + ${opts.valueTypeName} ${opts.valueFieldName}; +} + +/** + * @dev Pushes a (\`key\`, \`value\`) pair into a ${opts.historyTypeName} so that it is stored as the checkpoint. + * + * Returns previous value and new value. + * + * IMPORTANT: Never accept \`key\` as a user input, since an arbitrary \`type(${opts.keyTypeName}).max\` key set will disable the + * library. + */ +function push( + ${opts.historyTypeName} storage self, + ${opts.keyTypeName} key, + ${opts.valueTypeName} value +) internal returns (${opts.valueTypeName}, ${opts.valueTypeName}) { + return _insert(self.${opts.checkpointFieldName}, key, value); +} + +/** + * @dev Returns the value in the first (oldest) checkpoint with key greater or equal than the search key, or zero if + * there is none. + */ +function lowerLookup(${opts.historyTypeName} storage self, ${opts.keyTypeName} key) internal view returns (${opts.valueTypeName}) { + uint256 len = self.${opts.checkpointFieldName}.length; + uint256 pos = _lowerBinaryLookup(self.${opts.checkpointFieldName}, key, 0, len); + return pos == len ? 0 : _unsafeAccess(self.${opts.checkpointFieldName}, pos).${opts.valueFieldName}; +} + +/** + * @dev Returns the value in the last (most recent) checkpoint with key lower or equal than the search key, or zero + * if there is none. + */ +function upperLookup(${opts.historyTypeName} storage self, ${opts.keyTypeName} key) internal view returns (${opts.valueTypeName}) { + uint256 len = self.${opts.checkpointFieldName}.length; + uint256 pos = _upperBinaryLookup(self.${opts.checkpointFieldName}, key, 0, len); + return pos == 0 ? 0 : _unsafeAccess(self.${opts.checkpointFieldName}, pos - 1).${opts.valueFieldName}; +} + +/** + * @dev Returns the value in the last (most recent) checkpoint with key lower or equal than the search key, or zero + * if there is none. + * + * NOTE: This is a variant of {upperLookup} that is optimised to find "recent" checkpoint (checkpoints with high + * keys). + */ +function upperLookupRecent(${opts.historyTypeName} storage self, ${opts.keyTypeName} key) internal view returns (${opts.valueTypeName}) { + uint256 len = self.${opts.checkpointFieldName}.length; + + uint256 low = 0; + uint256 high = len; + + if (len > 5) { + uint256 mid = len - Math.sqrt(len); + if (key < _unsafeAccess(self.${opts.checkpointFieldName}, mid)._key) { + high = mid; + } else { + low = mid + 1; + } + } + + uint256 pos = _upperBinaryLookup(self.${opts.checkpointFieldName}, key, low, high); + + return pos == 0 ? 0 : _unsafeAccess(self.${opts.checkpointFieldName}, pos - 1).${opts.valueFieldName}; +} + +/** + * @dev Returns the value in the most recent checkpoint, or zero if there are no checkpoints. + */ +function latest(${opts.historyTypeName} storage self) internal view returns (${opts.valueTypeName}) { + uint256 pos = self.${opts.checkpointFieldName}.length; + return pos == 0 ? 0 : _unsafeAccess(self.${opts.checkpointFieldName}, pos - 1).${opts.valueFieldName}; +} + +/** + * @dev Returns whether there is a checkpoint in the structure (i.e. it is not empty), and if so the key and value + * in the most recent checkpoint. + */ +function latestCheckpoint(${opts.historyTypeName} storage self) + internal + view + returns ( + bool exists, + ${opts.keyTypeName} ${opts.keyFieldName}, + ${opts.valueTypeName} ${opts.valueFieldName} + ) +{ + uint256 pos = self.${opts.checkpointFieldName}.length; + if (pos == 0) { + return (false, 0, 0); + } else { + ${opts.checkpointTypeName} memory ckpt = _unsafeAccess(self.${opts.checkpointFieldName}, pos - 1); + return (true, ckpt.${opts.keyFieldName}, ckpt.${opts.valueFieldName}); + } +} + +/** + * @dev Returns the number of checkpoint. + */ +function length(${opts.historyTypeName} storage self) internal view returns (uint256) { + return self.${opts.checkpointFieldName}.length; +} + +/** + * @dev Returns checkpoint at given position. + */ +function at(${opts.historyTypeName} storage self, uint32 pos) internal view returns (${opts.checkpointTypeName} memory) { + return self.${opts.checkpointFieldName}[pos]; +} + +/** + * @dev Pushes a (\`key\`, \`value\`) pair into an ordered list of checkpoints, either by inserting a new checkpoint, + * or by updating the last one. + */ +function _insert( + ${opts.checkpointTypeName}[] storage self, + ${opts.keyTypeName} key, + ${opts.valueTypeName} value +) private returns (${opts.valueTypeName}, ${opts.valueTypeName}) { + uint256 pos = self.length; + + if (pos > 0) { + // Copying to memory is important here. + ${opts.checkpointTypeName} memory last = _unsafeAccess(self, pos - 1); + + // Checkpoint keys must be non-decreasing. + if(last.${opts.keyFieldName} > key) { + revert CheckpointUnorderedInsertion(); + } + + // Update or push new checkpoint + if (last.${opts.keyFieldName} == key) { + _unsafeAccess(self, pos - 1).${opts.valueFieldName} = value; + } else { + self.push(${opts.checkpointTypeName}({${opts.keyFieldName}: key, ${opts.valueFieldName}: value})); + } + return (last.${opts.valueFieldName}, value); + } else { + self.push(${opts.checkpointTypeName}({${opts.keyFieldName}: key, ${opts.valueFieldName}: value})); + return (0, value); + } +} + +/** + * @dev Return the index of the last (most recent) checkpoint with key lower or equal than the search key, or \`high\` + * if there is none. \`low\` and \`high\` define a section where to do the search, with inclusive \`low\` and exclusive + * \`high\`. + * + * WARNING: \`high\` should not be greater than the array's length. + */ +function _upperBinaryLookup( + ${opts.checkpointTypeName}[] storage self, + ${opts.keyTypeName} key, + uint256 low, + uint256 high +) private view returns (uint256) { + while (low < high) { + uint256 mid = Math.average(low, high); + if (_unsafeAccess(self, mid).${opts.keyFieldName} > key) { + high = mid; + } else { + low = mid + 1; + } + } + return high; +} + +/** + * @dev Return the index of the first (oldest) checkpoint with key is greater or equal than the search key, or + * \`high\` if there is none. \`low\` and \`high\` define a section where to do the search, with inclusive \`low\` and + * exclusive \`high\`. + * + * WARNING: \`high\` should not be greater than the array's length. + */ +function _lowerBinaryLookup( + ${opts.checkpointTypeName}[] storage self, + ${opts.keyTypeName} key, + uint256 low, + uint256 high +) private view returns (uint256) { + while (low < high) { + uint256 mid = Math.average(low, high); + if (_unsafeAccess(self, mid).${opts.keyFieldName} < key) { + low = mid + 1; + } else { + high = mid; + } + } + return high; +} + +/** + * @dev Access an element of the array without performing bounds check. The position is assumed to be within bounds. + */ +function _unsafeAccess(${opts.checkpointTypeName}[] storage self, uint256 pos) + private + pure + returns (${opts.checkpointTypeName} storage result) +{ + assembly { + mstore(0, self.slot) + result.slot := add(keccak256(0, 0x20), pos) + } +} +`; +/* eslint-enable max-len */ + +// GENERATE +module.exports = format( + header.trimEnd(), + 'library Checkpoints {', + errors, + OPTS.flatMap(opts => template(opts)), + '}', +); diff --git a/scripts/generate/templates/Checkpoints.opts.js b/scripts/generate/templates/Checkpoints.opts.js new file mode 100644 index 000000000..08b7b910b --- /dev/null +++ b/scripts/generate/templates/Checkpoints.opts.js @@ -0,0 +1,17 @@ +// OPTIONS +const VALUE_SIZES = [224, 208, 160]; + +const defaultOpts = size => ({ + historyTypeName: `Trace${size}`, + checkpointTypeName: `Checkpoint${size}`, + checkpointFieldName: '_checkpoints', + keyTypeName: `uint${256 - size}`, + keyFieldName: '_key', + valueTypeName: `uint${size}`, + valueFieldName: '_value', +}); + +module.exports = { + VALUE_SIZES, + OPTS: VALUE_SIZES.map(size => defaultOpts(size)), +}; diff --git a/scripts/generate/templates/Checkpoints.t.js b/scripts/generate/templates/Checkpoints.t.js new file mode 100644 index 000000000..d21beb53e --- /dev/null +++ b/scripts/generate/templates/Checkpoints.t.js @@ -0,0 +1,146 @@ +const format = require('../format-lines'); +const { capitalize } = require('../../helpers'); +const { OPTS } = require('./Checkpoints.opts.js'); + +// TEMPLATE +const header = `\ +pragma solidity ^0.8.20; + +import {Test} from "forge-std/Test.sol"; +import {SafeCast} from "../../../contracts/utils/math/SafeCast.sol"; +import {Checkpoints} from "../../../contracts/utils/structs/Checkpoints.sol"; +`; + +/* eslint-disable max-len */ +const template = opts => `\ +using Checkpoints for Checkpoints.${opts.historyTypeName}; + +// Maximum gap between keys used during the fuzzing tests: the \`_prepareKeys\` function with make sure that +// key#n+1 is in the [key#n, key#n + _KEY_MAX_GAP] range. +uint8 internal constant _KEY_MAX_GAP = 64; + +Checkpoints.${opts.historyTypeName} internal _ckpts; + +// helpers +function _bound${capitalize(opts.keyTypeName)}( + ${opts.keyTypeName} x, + ${opts.keyTypeName} min, + ${opts.keyTypeName} max +) internal view returns (${opts.keyTypeName}) { + return SafeCast.to${capitalize(opts.keyTypeName)}(bound(uint256(x), uint256(min), uint256(max))); +} + +function _prepareKeys( + ${opts.keyTypeName}[] memory keys, + ${opts.keyTypeName} maxSpread +) internal view { + ${opts.keyTypeName} lastKey = 0; + for (uint256 i = 0; i < keys.length; ++i) { + ${opts.keyTypeName} key = _bound${capitalize(opts.keyTypeName)}(keys[i], lastKey, lastKey + maxSpread); + keys[i] = key; + lastKey = key; + } +} + +function _assertLatestCheckpoint( + bool exist, + ${opts.keyTypeName} key, + ${opts.valueTypeName} value +) internal { + (bool _exist, ${opts.keyTypeName} _key, ${opts.valueTypeName} _value) = _ckpts.latestCheckpoint(); + assertEq(_exist, exist); + assertEq(_key, key); + assertEq(_value, value); +} + +// tests +function testPush( + ${opts.keyTypeName}[] memory keys, + ${opts.valueTypeName}[] memory values, + ${opts.keyTypeName} pastKey +) public { + vm.assume(values.length > 0 && values.length <= keys.length); + _prepareKeys(keys, _KEY_MAX_GAP); + + // initial state + assertEq(_ckpts.length(), 0); + assertEq(_ckpts.latest(), 0); + _assertLatestCheckpoint(false, 0, 0); + + uint256 duplicates = 0; + for (uint256 i = 0; i < keys.length; ++i) { + ${opts.keyTypeName} key = keys[i]; + ${opts.valueTypeName} value = values[i % values.length]; + if (i > 0 && key == keys[i-1]) ++duplicates; + + // push + _ckpts.push(key, value); + + // check length & latest + assertEq(_ckpts.length(), i + 1 - duplicates); + assertEq(_ckpts.latest(), value); + _assertLatestCheckpoint(true, key, value); + } + + if (keys.length > 0) { + ${opts.keyTypeName} lastKey = keys[keys.length - 1]; + if (lastKey > 0) { + pastKey = _bound${capitalize(opts.keyTypeName)}(pastKey, 0, lastKey - 1); + + vm.expectRevert(); + this.push(pastKey, values[keys.length % values.length]); + } + } +} + +// used to test reverts +function push(${opts.keyTypeName} key, ${opts.valueTypeName} value) external { + _ckpts.push(key, value); +} + +function testLookup( + ${opts.keyTypeName}[] memory keys, + ${opts.valueTypeName}[] memory values, + ${opts.keyTypeName} lookup +) public { + vm.assume(values.length > 0 && values.length <= keys.length); + _prepareKeys(keys, _KEY_MAX_GAP); + + ${opts.keyTypeName} lastKey = keys.length == 0 ? 0 : keys[keys.length - 1]; + lookup = _bound${capitalize(opts.keyTypeName)}(lookup, 0, lastKey + _KEY_MAX_GAP); + + ${opts.valueTypeName} upper = 0; + ${opts.valueTypeName} lower = 0; + ${opts.keyTypeName} lowerKey = type(${opts.keyTypeName}).max; + for (uint256 i = 0; i < keys.length; ++i) { + ${opts.keyTypeName} key = keys[i]; + ${opts.valueTypeName} value = values[i % values.length]; + + // push + _ckpts.push(key, value); + + // track expected result of lookups + if (key <= lookup) { + upper = value; + } + // find the first key that is not smaller than the lookup key + if (key >= lookup && (i == 0 || keys[i-1] < lookup)) { + lowerKey = key; + } + if (key == lowerKey) { + lower = value; + } + } + + // check lookup + assertEq(_ckpts.lowerLookup(lookup), lower); + assertEq(_ckpts.upperLookup(lookup), upper); + assertEq(_ckpts.upperLookupRecent(lookup), upper); +} +`; + +// GENERATE +module.exports = format( + header, + ...OPTS.flatMap(opts => [`contract Checkpoints${opts.historyTypeName}Test is Test {`, [template(opts)], '}']), +); diff --git a/scripts/generate/templates/EnumerableMap.js b/scripts/generate/templates/EnumerableMap.js new file mode 100644 index 000000000..7dbe6ca7f --- /dev/null +++ b/scripts/generate/templates/EnumerableMap.js @@ -0,0 +1,283 @@ +const format = require('../format-lines'); +const { fromBytes32, toBytes32 } = require('./conversion'); + +const TYPES = [ + { name: 'UintToUintMap', keyType: 'uint256', valueType: 'uint256' }, + { name: 'UintToAddressMap', keyType: 'uint256', valueType: 'address' }, + { name: 'AddressToUintMap', keyType: 'address', valueType: 'uint256' }, + { name: 'Bytes32ToUintMap', keyType: 'bytes32', valueType: 'uint256' }, +]; + +/* eslint-disable max-len */ +const header = `\ +pragma solidity ^0.8.20; + +import {EnumerableSet} from "./EnumerableSet.sol"; + +/** + * @dev Library for managing an enumerable variant of Solidity's + * https://solidity.readthedocs.io/en/latest/types.html#mapping-types[\`mapping\`] + * type. + * + * Maps have the following properties: + * + * - Entries are added, removed, and checked for existence in constant time + * (O(1)). + * - Entries are enumerated in O(n). No guarantees are made on the ordering. + * + * \`\`\`solidity + * contract Example { + * // Add the library methods + * using EnumerableMap for EnumerableMap.UintToAddressMap; + * + * // Declare a set state variable + * EnumerableMap.UintToAddressMap private myMap; + * } + * \`\`\` + * + * The following map types are supported: + * + * - \`uint256 -> address\` (\`UintToAddressMap\`) since v3.0.0 + * - \`address -> uint256\` (\`AddressToUintMap\`) since v4.6.0 + * - \`bytes32 -> bytes32\` (\`Bytes32ToBytes32Map\`) since v4.6.0 + * - \`uint256 -> uint256\` (\`UintToUintMap\`) since v4.7.0 + * - \`bytes32 -> uint256\` (\`Bytes32ToUintMap\`) since v4.7.0 + * + * [WARNING] + * ==== + * Trying to delete such a structure from storage will likely result in data corruption, rendering the structure + * unusable. + * See https://github.com/ethereum/solidity/pull/11843[ethereum/solidity#11843] for more info. + * + * In order to clean an EnumerableMap, you can either remove all elements one by one or create a fresh instance using an + * array of EnumerableMap. + * ==== + */ +`; +/* eslint-enable max-len */ + +const defaultMap = () => `\ +// To implement this library for multiple types with as little code repetition as possible, we write it in +// terms of a generic Map type with bytes32 keys and values. The Map implementation uses private functions, +// and user-facing implementations such as \`UintToAddressMap\` are just wrappers around the underlying Map. +// This means that we can only create new EnumerableMaps for types that fit in bytes32. + +/** + * @dev Query for a nonexistent map key. + */ +error EnumerableMapNonexistentKey(bytes32 key); + +struct Bytes32ToBytes32Map { + // Storage of keys + EnumerableSet.Bytes32Set _keys; + mapping(bytes32 key => bytes32) _values; +} + +/** + * @dev Adds a key-value pair to a map, or updates the value for an existing + * key. O(1). + * + * Returns true if the key was added to the map, that is if it was not + * already present. + */ +function set( + Bytes32ToBytes32Map storage map, + bytes32 key, + bytes32 value +) internal returns (bool) { + map._values[key] = value; + return map._keys.add(key); +} + +/** + * @dev Removes a key-value pair from a map. O(1). + * + * Returns true if the key was removed from the map, that is if it was present. + */ +function remove(Bytes32ToBytes32Map storage map, bytes32 key) internal returns (bool) { + delete map._values[key]; + return map._keys.remove(key); +} + +/** + * @dev Returns true if the key is in the map. O(1). + */ +function contains(Bytes32ToBytes32Map storage map, bytes32 key) internal view returns (bool) { + return map._keys.contains(key); +} + +/** + * @dev Returns the number of key-value pairs in the map. O(1). + */ +function length(Bytes32ToBytes32Map storage map) internal view returns (uint256) { + return map._keys.length(); +} + +/** + * @dev Returns the key-value pair stored at position \`index\` in the map. O(1). + * + * Note that there are no guarantees on the ordering of entries inside the + * array, and it may change when more entries are added or removed. + * + * Requirements: + * + * - \`index\` must be strictly less than {length}. + */ +function at(Bytes32ToBytes32Map storage map, uint256 index) internal view returns (bytes32, bytes32) { + bytes32 key = map._keys.at(index); + return (key, map._values[key]); +} + +/** + * @dev Tries to returns the value associated with \`key\`. O(1). + * Does not revert if \`key\` is not in the map. + */ +function tryGet(Bytes32ToBytes32Map storage map, bytes32 key) internal view returns (bool, bytes32) { + bytes32 value = map._values[key]; + if (value == bytes32(0)) { + return (contains(map, key), bytes32(0)); + } else { + return (true, value); + } +} + +/** + * @dev Returns the value associated with \`key\`. O(1). + * + * Requirements: + * + * - \`key\` must be in the map. + */ +function get(Bytes32ToBytes32Map storage map, bytes32 key) internal view returns (bytes32) { + bytes32 value = map._values[key]; + if(value == 0 && !contains(map, key)) { + revert EnumerableMapNonexistentKey(key); + } + return value; +} + +/** + * @dev Return the an array containing all the keys + * + * WARNING: This operation will copy the entire storage to memory, which can be quite expensive. This is designed + * to mostly be used by view accessors that are queried without any gas fees. Developers should keep in mind that + * this function has an unbounded cost, and using it as part of a state-changing function may render the function + * uncallable if the map grows to a point where copying to memory consumes too much gas to fit in a block. + */ +function keys(Bytes32ToBytes32Map storage map) internal view returns (bytes32[] memory) { + return map._keys.values(); +} +`; + +const customMap = ({ name, keyType, valueType }) => `\ +// ${name} + +struct ${name} { + Bytes32ToBytes32Map _inner; +} + +/** + * @dev Adds a key-value pair to a map, or updates the value for an existing + * key. O(1). + * + * Returns true if the key was added to the map, that is if it was not + * already present. + */ +function set( + ${name} storage map, + ${keyType} key, + ${valueType} value +) internal returns (bool) { + return set(map._inner, ${toBytes32(keyType, 'key')}, ${toBytes32(valueType, 'value')}); +} + +/** + * @dev Removes a value from a map. O(1). + * + * Returns true if the key was removed from the map, that is if it was present. + */ +function remove(${name} storage map, ${keyType} key) internal returns (bool) { + return remove(map._inner, ${toBytes32(keyType, 'key')}); +} + +/** + * @dev Returns true if the key is in the map. O(1). + */ +function contains(${name} storage map, ${keyType} key) internal view returns (bool) { + return contains(map._inner, ${toBytes32(keyType, 'key')}); +} + +/** + * @dev Returns the number of elements in the map. O(1). + */ +function length(${name} storage map) internal view returns (uint256) { + return length(map._inner); +} + +/** + * @dev Returns the element stored at position \`index\` in the map. O(1). + * Note that there are no guarantees on the ordering of values inside the + * array, and it may change when more values are added or removed. + * + * Requirements: + * + * - \`index\` must be strictly less than {length}. + */ +function at(${name} storage map, uint256 index) internal view returns (${keyType}, ${valueType}) { + (bytes32 key, bytes32 value) = at(map._inner, index); + return (${fromBytes32(keyType, 'key')}, ${fromBytes32(valueType, 'value')}); +} + +/** + * @dev Tries to returns the value associated with \`key\`. O(1). + * Does not revert if \`key\` is not in the map. + */ +function tryGet(${name} storage map, ${keyType} key) internal view returns (bool, ${valueType}) { + (bool success, bytes32 value) = tryGet(map._inner, ${toBytes32(keyType, 'key')}); + return (success, ${fromBytes32(valueType, 'value')}); +} + +/** + * @dev Returns the value associated with \`key\`. O(1). + * + * Requirements: + * + * - \`key\` must be in the map. + */ +function get(${name} storage map, ${keyType} key) internal view returns (${valueType}) { + return ${fromBytes32(valueType, `get(map._inner, ${toBytes32(keyType, 'key')})`)}; +} + +/** + * @dev Return the an array containing all the keys + * + * WARNING: This operation will copy the entire storage to memory, which can be quite expensive. This is designed + * to mostly be used by view accessors that are queried without any gas fees. Developers should keep in mind that + * this function has an unbounded cost, and using it as part of a state-changing function may render the function + * uncallable if the map grows to a point where copying to memory consumes too much gas to fit in a block. + */ +function keys(${name} storage map) internal view returns (${keyType}[] memory) { + bytes32[] memory store = keys(map._inner); + ${keyType}[] memory result; + + /// @solidity memory-safe-assembly + assembly { + result := store + } + + return result; +} +`; + +// GENERATE +module.exports = format( + header.trimEnd(), + 'library EnumerableMap {', + [ + 'using EnumerableSet for EnumerableSet.Bytes32Set;', + '', + defaultMap(), + TYPES.map(details => customMap(details).trimEnd()).join('\n\n'), + ], + '}', +); diff --git a/scripts/generate/templates/EnumerableSet.js b/scripts/generate/templates/EnumerableSet.js new file mode 100644 index 000000000..cb9bffb2c --- /dev/null +++ b/scripts/generate/templates/EnumerableSet.js @@ -0,0 +1,250 @@ +const format = require('../format-lines'); +const { fromBytes32, toBytes32 } = require('./conversion'); + +const TYPES = [ + { name: 'Bytes32Set', type: 'bytes32' }, + { name: 'AddressSet', type: 'address' }, + { name: 'UintSet', type: 'uint256' }, +]; + +/* eslint-disable max-len */ +const header = `\ +pragma solidity ^0.8.20; + +/** + * @dev Library for managing + * https://en.wikipedia.org/wiki/Set_(abstract_data_type)[sets] of primitive + * types. + * + * Sets have the following properties: + * + * - Elements are added, removed, and checked for existence in constant time + * (O(1)). + * - Elements are enumerated in O(n). No guarantees are made on the ordering. + * + * \`\`\`solidity + * contract Example { + * // Add the library methods + * using EnumerableSet for EnumerableSet.AddressSet; + * + * // Declare a set state variable + * EnumerableSet.AddressSet private mySet; + * } + * \`\`\` + * + * As of v3.3.0, sets of type \`bytes32\` (\`Bytes32Set\`), \`address\` (\`AddressSet\`) + * and \`uint256\` (\`UintSet\`) are supported. + * + * [WARNING] + * ==== + * Trying to delete such a structure from storage will likely result in data corruption, rendering the structure + * unusable. + * See https://github.com/ethereum/solidity/pull/11843[ethereum/solidity#11843] for more info. + * + * In order to clean an EnumerableSet, you can either remove all elements one by one or create a fresh instance using an + * array of EnumerableSet. + * ==== + */ +`; +/* eslint-enable max-len */ + +const defaultSet = () => `\ +// To implement this library for multiple types with as little code +// repetition as possible, we write it in terms of a generic Set type with +// bytes32 values. +// The Set implementation uses private functions, and user-facing +// implementations (such as AddressSet) are just wrappers around the +// underlying Set. +// This means that we can only create new EnumerableSets for types that fit +// in bytes32. + +struct Set { + // Storage of set values + bytes32[] _values; + // Position is the index of the value in the \`values\` array plus 1. + // Position 0 is used to mean a value is not in the set. + mapping(bytes32 value => uint256) _positions; +} + +/** + * @dev Add a value to a set. O(1). + * + * Returns true if the value was added to the set, that is if it was not + * already present. + */ +function _add(Set storage set, bytes32 value) private returns (bool) { + if (!_contains(set, value)) { + set._values.push(value); + // The value is stored at length-1, but we add 1 to all indexes + // and use 0 as a sentinel value + set._positions[value] = set._values.length; + return true; + } else { + return false; + } +} + +/** + * @dev Removes a value from a set. O(1). + * + * Returns true if the value was removed from the set, that is if it was + * present. + */ +function _remove(Set storage set, bytes32 value) private returns (bool) { + // We cache the value's position to prevent multiple reads from the same storage slot + uint256 position = set._positions[value]; + + if (position != 0) { + // Equivalent to contains(set, value) + // To delete an element from the _values array in O(1), we swap the element to delete with the last one in + // the array, and then remove the last element (sometimes called as 'swap and pop'). + // This modifies the order of the array, as noted in {at}. + + uint256 valueIndex = position - 1; + uint256 lastIndex = set._values.length - 1; + + if (valueIndex != lastIndex) { + bytes32 lastValue = set._values[lastIndex]; + + // Move the lastValue to the index where the value to delete is + set._values[valueIndex] = lastValue; + // Update the tracked position of the lastValue (that was just moved) + set._positions[lastValue] = position; + } + + // Delete the slot where the moved value was stored + set._values.pop(); + + // Delete the tracked position for the deleted slot + delete set._positions[value]; + + return true; + } else { + return false; + } +} + +/** + * @dev Returns true if the value is in the set. O(1). + */ +function _contains(Set storage set, bytes32 value) private view returns (bool) { + return set._positions[value] != 0; +} + +/** + * @dev Returns the number of values on the set. O(1). + */ +function _length(Set storage set) private view returns (uint256) { + return set._values.length; +} + +/** + * @dev Returns the value stored at position \`index\` in the set. O(1). + * + * Note that there are no guarantees on the ordering of values inside the + * array, and it may change when more values are added or removed. + * + * Requirements: + * + * - \`index\` must be strictly less than {length}. + */ +function _at(Set storage set, uint256 index) private view returns (bytes32) { + return set._values[index]; +} + +/** + * @dev Return the entire set in an array + * + * WARNING: This operation will copy the entire storage to memory, which can be quite expensive. This is designed + * to mostly be used by view accessors that are queried without any gas fees. Developers should keep in mind that + * this function has an unbounded cost, and using it as part of a state-changing function may render the function + * uncallable if the set grows to a point where copying to memory consumes too much gas to fit in a block. + */ +function _values(Set storage set) private view returns (bytes32[] memory) { + return set._values; +} +`; + +const customSet = ({ name, type }) => `\ +// ${name} + +struct ${name} { + Set _inner; +} + +/** + * @dev Add a value to a set. O(1). + * + * Returns true if the value was added to the set, that is if it was not + * already present. + */ +function add(${name} storage set, ${type} value) internal returns (bool) { + return _add(set._inner, ${toBytes32(type, 'value')}); +} + +/** + * @dev Removes a value from a set. O(1). + * + * Returns true if the value was removed from the set, that is if it was + * present. + */ +function remove(${name} storage set, ${type} value) internal returns (bool) { + return _remove(set._inner, ${toBytes32(type, 'value')}); +} + +/** + * @dev Returns true if the value is in the set. O(1). + */ +function contains(${name} storage set, ${type} value) internal view returns (bool) { + return _contains(set._inner, ${toBytes32(type, 'value')}); +} + +/** + * @dev Returns the number of values in the set. O(1). + */ +function length(${name} storage set) internal view returns (uint256) { + return _length(set._inner); +} + +/** + * @dev Returns the value stored at position \`index\` in the set. O(1). + * + * Note that there are no guarantees on the ordering of values inside the + * array, and it may change when more values are added or removed. + * + * Requirements: + * + * - \`index\` must be strictly less than {length}. + */ +function at(${name} storage set, uint256 index) internal view returns (${type}) { + return ${fromBytes32(type, '_at(set._inner, index)')}; +} + +/** + * @dev Return the entire set in an array + * + * WARNING: This operation will copy the entire storage to memory, which can be quite expensive. This is designed + * to mostly be used by view accessors that are queried without any gas fees. Developers should keep in mind that + * this function has an unbounded cost, and using it as part of a state-changing function may render the function + * uncallable if the set grows to a point where copying to memory consumes too much gas to fit in a block. + */ +function values(${name} storage set) internal view returns (${type}[] memory) { + bytes32[] memory store = _values(set._inner); + ${type}[] memory result; + + /// @solidity memory-safe-assembly + assembly { + result := store + } + + return result; +} +`; + +// GENERATE +module.exports = format( + header.trimEnd(), + 'library EnumerableSet {', + [defaultSet(), TYPES.map(details => customSet(details).trimEnd()).join('\n\n')], + '}', +); diff --git a/scripts/generate/templates/SafeCast.js b/scripts/generate/templates/SafeCast.js new file mode 100644 index 000000000..f1954a753 --- /dev/null +++ b/scripts/generate/templates/SafeCast.js @@ -0,0 +1,126 @@ +const format = require('../format-lines'); +const { range } = require('../../helpers'); + +const LENGTHS = range(8, 256, 8).reverse(); // 248 → 8 (in steps of 8) + +const header = `\ +pragma solidity ^0.8.20; + +/** + * @dev Wrappers over Solidity's uintXX/intXX casting operators with added overflow + * checks. + * + * Downcasting from uint256/int256 in Solidity does not revert on overflow. This can + * easily result in undesired exploitation or bugs, since developers usually + * assume that overflows raise errors. \`SafeCast\` restores this intuition by + * reverting the transaction when such an operation overflows. + * + * Using this library instead of the unchecked operations eliminates an entire + * class of bugs, so it's recommended to use it always. + */ +`; + +const errors = `\ + /** + * @dev Value doesn't fit in an uint of \`bits\` size. + */ + error SafeCastOverflowedUintDowncast(uint8 bits, uint256 value); + + /** + * @dev An int value doesn't fit in an uint of \`bits\` size. + */ + error SafeCastOverflowedIntToUint(int256 value); + + /** + * @dev Value doesn't fit in an int of \`bits\` size. + */ + error SafeCastOverflowedIntDowncast(uint8 bits, int256 value); + + /** + * @dev An uint value doesn't fit in an int of \`bits\` size. + */ + error SafeCastOverflowedUintToInt(uint256 value); +`; + +const toUintDownCast = length => `\ +/** + * @dev Returns the downcasted uint${length} from uint256, reverting on + * overflow (when the input is greater than largest uint${length}). + * + * Counterpart to Solidity's \`uint${length}\` operator. + * + * Requirements: + * + * - input must fit into ${length} bits + */ +function toUint${length}(uint256 value) internal pure returns (uint${length}) { + if (value > type(uint${length}).max) { + revert SafeCastOverflowedUintDowncast(${length}, value); + } + return uint${length}(value); +} +`; + +/* eslint-disable max-len */ +const toIntDownCast = length => `\ +/** + * @dev Returns the downcasted int${length} from int256, reverting on + * overflow (when the input is less than smallest int${length} or + * greater than largest int${length}). + * + * Counterpart to Solidity's \`int${length}\` operator. + * + * Requirements: + * + * - input must fit into ${length} bits + */ +function toInt${length}(int256 value) internal pure returns (int${length} downcasted) { + downcasted = int${length}(value); + if (downcasted != value) { + revert SafeCastOverflowedIntDowncast(${length}, value); + } +} +`; +/* eslint-enable max-len */ + +const toInt = length => `\ +/** + * @dev Converts an unsigned uint${length} into a signed int${length}. + * + * Requirements: + * + * - input must be less than or equal to maxInt${length}. + */ +function toInt${length}(uint${length} value) internal pure returns (int${length}) { + // Note: Unsafe cast below is okay because \`type(int${length}).max\` is guaranteed to be positive + if (value > uint${length}(type(int${length}).max)) { + revert SafeCastOverflowedUintToInt(value); + } + return int${length}(value); +} +`; + +const toUint = length => `\ +/** + * @dev Converts a signed int${length} into an unsigned uint${length}. + * + * Requirements: + * + * - input must be greater than or equal to 0. + */ +function toUint${length}(int${length} value) internal pure returns (uint${length}) { + if (value < 0) { + revert SafeCastOverflowedIntToUint(value); + } + return uint${length}(value); +} +`; + +// GENERATE +module.exports = format( + header.trimEnd(), + 'library SafeCast {', + errors, + [...LENGTHS.map(toUintDownCast), toUint(256), ...LENGTHS.map(toIntDownCast), toInt(256)], + '}', +); diff --git a/scripts/generate/templates/StorageSlot.js b/scripts/generate/templates/StorageSlot.js new file mode 100644 index 000000000..1c90b5e75 --- /dev/null +++ b/scripts/generate/templates/StorageSlot.js @@ -0,0 +1,78 @@ +const format = require('../format-lines'); +const { capitalize } = require('../../helpers'); + +const TYPES = [ + { type: 'address', isValueType: true }, + { type: 'bool', isValueType: true, name: 'Boolean' }, + { type: 'bytes32', isValueType: true }, + { type: 'uint256', isValueType: true }, + { type: 'string', isValueType: false }, + { type: 'bytes', isValueType: false }, +].map(type => Object.assign(type, { struct: (type.name ?? capitalize(type.type)) + 'Slot' })); + +const header = `\ +pragma solidity ^0.8.20; + +/** + * @dev Library for reading and writing primitive types to specific storage slots. + * + * Storage slots are often used to avoid storage conflict when dealing with upgradeable contracts. + * This library helps with reading and writing to such slots without the need for inline assembly. + * + * The functions in this library return Slot structs that contain a \`value\` member that can be used to read or write. + * + * Example usage to set ERC1967 implementation slot: + * \`\`\`solidity + * contract ERC1967 { + * bytes32 internal constant _IMPLEMENTATION_SLOT = 0x360894a13ba1a3210667c828492db98dca3e2076cc3735a920a3ca505d382bbc; + * + * function _getImplementation() internal view returns (address) { + * return StorageSlot.getAddressSlot(_IMPLEMENTATION_SLOT).value; + * } + * + * function _setImplementation(address newImplementation) internal { + * require(newImplementation.code.length > 0); + * StorageSlot.getAddressSlot(_IMPLEMENTATION_SLOT).value = newImplementation; + * } + * } + * \`\`\` + */ +`; + +const struct = type => `\ +struct ${type.struct} { + ${type.type} value; +} +`; + +const get = type => `\ +/** + * @dev Returns an \`${type.struct}\` with member \`value\` located at \`slot\`. + */ +function get${type.struct}(bytes32 slot) internal pure returns (${type.struct} storage r) { + /// @solidity memory-safe-assembly + assembly { + r.slot := slot + } +} +`; + +const getStorage = type => `\ +/** + * @dev Returns an \`${type.struct}\` representation of the ${type.type} storage pointer \`store\`. + */ +function get${type.struct}(${type.type} storage store) internal pure returns (${type.struct} storage r) { + /// @solidity memory-safe-assembly + assembly { + r.slot := store.slot + } +} +`; + +// GENERATE +module.exports = format( + header.trimEnd(), + 'library StorageSlot {', + [...TYPES.map(struct), ...TYPES.flatMap(type => [get(type), type.isValueType ? '' : getStorage(type)])], + '}', +); diff --git a/scripts/generate/templates/conversion.js b/scripts/generate/templates/conversion.js new file mode 100644 index 000000000..9221f7c21 --- /dev/null +++ b/scripts/generate/templates/conversion.js @@ -0,0 +1,30 @@ +function toBytes32(type, value) { + switch (type) { + case 'bytes32': + return value; + case 'uint256': + return `bytes32(${value})`; + case 'address': + return `bytes32(uint256(uint160(${value})))`; + default: + throw new Error(`Conversion from ${type} to bytes32 not supported`); + } +} + +function fromBytes32(type, value) { + switch (type) { + case 'bytes32': + return value; + case 'uint256': + return `uint256(${value})`; + case 'address': + return `address(uint160(uint256(${value})))`; + default: + throw new Error(`Conversion from bytes32 to ${type} not supported`); + } +} + +module.exports = { + toBytes32, + fromBytes32, +}; diff --git a/scripts/git-user-config.sh b/scripts/git-user-config.sh new file mode 100644 index 000000000..e7b81c3eb --- /dev/null +++ b/scripts/git-user-config.sh @@ -0,0 +1,6 @@ +#!/usr/bin/env bash + +set -euo pipefail -x + +git config user.name 'github-actions' +git config user.email '41898282+github-actions[bot]@users.noreply.github.com' diff --git a/scripts/helpers.js b/scripts/helpers.js new file mode 100644 index 000000000..fb9aad4fc --- /dev/null +++ b/scripts/helpers.js @@ -0,0 +1,37 @@ +function chunk(array, size = 1) { + return Array.range(Math.ceil(array.length / size)).map(i => array.slice(i * size, i * size + size)); +} + +function range(start, stop = undefined, step = 1) { + if (!stop) { + stop = start; + start = 0; + } + return start < stop + ? Array(Math.ceil((stop - start) / step)) + .fill() + .map((_, i) => start + i * step) + : []; +} + +function unique(array, op = x => x) { + return array.filter((obj, i) => array.findIndex(entry => op(obj) === op(entry)) === i); +} + +function zip(...args) { + return Array(Math.max(...args.map(arg => arg.length))) + .fill(null) + .map((_, i) => args.map(arg => arg[i])); +} + +function capitalize(str) { + return str.charAt(0).toUpperCase() + str.slice(1); +} + +module.exports = { + chunk, + range, + unique, + zip, + capitalize, +}; diff --git a/scripts/prepack.sh b/scripts/prepack.sh new file mode 100755 index 000000000..6f1bd4c32 --- /dev/null +++ b/scripts/prepack.sh @@ -0,0 +1,12 @@ +#!/usr/bin/env bash + +set -euo pipefail +shopt -s globstar + +# cross platform `mkdir -p` +node -e 'fs.mkdirSync("build/contracts", { recursive: true })' + +cp artifacts/contracts/**/*.json build/contracts +rm build/contracts/*.dbg.json + +node scripts/remove-ignored-artifacts.js diff --git a/scripts/prepare-contracts-package.sh b/scripts/prepare-contracts-package.sh new file mode 100755 index 000000000..3f62fd419 --- /dev/null +++ b/scripts/prepare-contracts-package.sh @@ -0,0 +1,15 @@ +#!/usr/bin/env bash + +# cd to the root of the repo +cd "$(git rev-parse --show-toplevel)" + +# avoids re-compilation during publishing of both packages +if [[ ! -v ALREADY_COMPILED ]]; then + npm run clean + npm run prepare + npm run prepack +fi + +cp README.md contracts/ +mkdir contracts/build contracts/build/contracts +cp -r build/contracts/*.json contracts/build/contracts diff --git a/scripts/prepare-docs.sh b/scripts/prepare-docs.sh new file mode 100755 index 000000000..d1317b092 --- /dev/null +++ b/scripts/prepare-docs.sh @@ -0,0 +1,26 @@ +#!/usr/bin/env bash + +set -euo pipefail +shopt -s globstar + +OUTDIR="$(node -p 'require("./docs/config.js").outputDir')" + +if [ ! -d node_modules ]; then + npm ci +fi + +rm -rf "$OUTDIR" + +hardhat docgen + +# copy examples and adjust imports +examples_source_dir="contracts/mocks/docs" +examples_target_dir="docs/modules/api/examples" + +for f in "$examples_source_dir"/**/*.sol; do + name="${f/#"$examples_source_dir/"/}" + mkdir -p "$examples_target_dir/$(dirname "$name")" + sed -Ee '/^import/s|"(\.\./)+|"@openzeppelin/contracts/|' "$f" > "$examples_target_dir/$name" +done + +node scripts/gen-nav.js "$OUTDIR" > "$OUTDIR/../nav.adoc" diff --git a/scripts/prepare.sh b/scripts/prepare.sh new file mode 100755 index 000000000..7014a7076 --- /dev/null +++ b/scripts/prepare.sh @@ -0,0 +1,10 @@ +#!/usr/bin/env bash + +set -euo pipefail + +if [ "${SKIP_COMPILE:-}" == true ]; then + exit +fi + +npm run clean +env COMPILE_MODE=production npm run compile diff --git a/scripts/release/format-changelog.js b/scripts/release/format-changelog.js new file mode 100755 index 000000000..b8bcc8c71 --- /dev/null +++ b/scripts/release/format-changelog.js @@ -0,0 +1,33 @@ +#!/usr/bin/env node + +// Adjusts the format of the changelog that changesets generates. +// This is run automatically when npm version is run. + +const fs = require('fs'); +const changelog = fs.readFileSync('CHANGELOG.md', 'utf8'); + +// Groups: +// - 1: Pull Request Number and URL +// - 2: Changeset entry +const RELEASE_LINE_REGEX = /^- (\[#.*?\]\(.*?\))?.*?! - (.*)$/gm; + +// Captures vX.Y.Z or vX.Y.Z-rc.W +const VERSION_TITLE_REGEX = /^## (\d+\.\d+\.\d+(-rc\.\d+)?)$/gm; + +const isPrerelease = process.env.PRERELEASE === 'true'; + +const formatted = changelog + // Remove titles + .replace(/^### Major Changes\n\n/gm, '') + .replace(/^### Minor Changes\n\n/gm, '') + .replace(/^### Patch Changes\n\n/gm, '') + // Remove extra whitespace between items + .replace(/^(- \[.*\n)\n(?=-)/gm, '$1') + // Format each release line + .replace(RELEASE_LINE_REGEX, (_, pr, entry) => (pr ? `- ${entry} (${pr})` : `- ${entry}`)) + // Add date to new version + .replace(VERSION_TITLE_REGEX, `\n## $1 (${new Date().toISOString().split('T')[0]})`) + // Conditionally allow vX.Y.Z.rc-.W sections only in prerelease + .replace(/^## \d\.\d\.\d-rc\S+[^]+?(?=^#)/gm, section => (isPrerelease ? section : '')); + +fs.writeFileSync('CHANGELOG.md', formatted); diff --git a/scripts/release/synchronize-versions.js b/scripts/release/synchronize-versions.js new file mode 100755 index 000000000..15aa25993 --- /dev/null +++ b/scripts/release/synchronize-versions.js @@ -0,0 +1,15 @@ +#!/usr/bin/env node + +// Synchronizes the version in contracts/package.json with the one in package.json. +// This is run automatically when npm version is run. + +const fs = require('fs'); + +setVersion('package.json', 'contracts/package.json'); + +function setVersion(from, to) { + const fromJson = JSON.parse(fs.readFileSync(from)); + const toJson = JSON.parse(fs.readFileSync(to)); + toJson.version = fromJson.version; + fs.writeFileSync(to, JSON.stringify(toJson, null, 2) + '\n'); +} diff --git a/scripts/release/update-comment.js b/scripts/release/update-comment.js new file mode 100755 index 000000000..9d6df2694 --- /dev/null +++ b/scripts/release/update-comment.js @@ -0,0 +1,34 @@ +#!/usr/bin/env node +const fs = require('fs'); +const proc = require('child_process'); +const semver = require('semver'); +const run = (cmd, ...args) => proc.execFileSync(cmd, args, { encoding: 'utf8' }).trim(); + +const gitStatus = run('git', 'status', '--porcelain', '-uno', 'contracts/**/*.sol'); +if (gitStatus.length > 0) { + console.error('Contracts directory is not clean'); + process.exit(1); +} + +const { version } = require('../../package.json'); + +// Get latest tag according to semver. +const [tag] = run('git', 'tag') + .split(/\r?\n/) + .filter(semver.coerce) // check version can be processed + .filter(v => semver.satisfies(v, `< ${version}`)) // ignores prereleases unless currently a prerelease + .sort(semver.rcompare); + +// Ordering tag → HEAD is important here. +const files = run('git', 'diff', tag, 'HEAD', '--name-only', 'contracts/**/*.sol') + .split(/\r?\n/) + .filter(file => file && !file.match(/mock/i) && fs.existsSync(file)); + +for (const file of files) { + const current = fs.readFileSync(file, 'utf8'); + const updated = current.replace( + /(\/\/ SPDX-License-Identifier:.*)$(\n\/\/ OpenZeppelin Contracts .*$)?/m, + `$1\n// OpenZeppelin Contracts (last updated v${version}) (${file.replace('contracts/', '')})`, + ); + fs.writeFileSync(file, updated); +} diff --git a/scripts/release/version.sh b/scripts/release/version.sh new file mode 100755 index 000000000..7b0ddead3 --- /dev/null +++ b/scripts/release/version.sh @@ -0,0 +1,11 @@ +#!/usr/bin/env bash + +set -euo pipefail + +changeset version + +scripts/release/format-changelog.js +scripts/release/synchronize-versions.js +scripts/release/update-comment.js + +oz-docs update-version diff --git a/scripts/release/workflow/exit-prerelease.sh b/scripts/release/workflow/exit-prerelease.sh new file mode 100644 index 000000000..bcf9b9ae9 --- /dev/null +++ b/scripts/release/workflow/exit-prerelease.sh @@ -0,0 +1,8 @@ +#!/usr/bin/env bash + +set -euo pipefail + +npx changeset pre exit rc +git add . +git commit -m "Exit release candidate" +git push origin diff --git a/scripts/release/workflow/github-release.js b/scripts/release/workflow/github-release.js new file mode 100644 index 000000000..92a47d9d7 --- /dev/null +++ b/scripts/release/workflow/github-release.js @@ -0,0 +1,47 @@ +const { readFileSync } = require('fs'); +const { join } = require('path'); +const { version } = require(join(__dirname, '../../../package.json')); + +module.exports = async ({ github, context }) => { + const changelog = readFileSync('CHANGELOG.md', 'utf8'); + + await github.rest.repos.createRelease({ + owner: context.repo.owner, + repo: context.repo.repo, + tag_name: `v${version}`, + body: extractSection(changelog, version), + prerelease: process.env.PRERELEASE === 'true', + }); +}; + +// From https://github.com/frangio/extract-changelog/blob/master/src/utils/word-regexp.ts +function makeWordRegExp(word) { + const start = word.length > 0 && /\b/.test(word[0]) ? '\\b' : ''; + const end = word.length > 0 && /\b/.test(word[word.length - 1]) ? '\\b' : ''; + return new RegExp(start + [...word].map(c => (/[a-z0-9]/i.test(c) ? c : '\\' + c)).join('') + end); +} + +// From https://github.com/frangio/extract-changelog/blob/master/src/core.ts +function extractSection(document, wantedHeading) { + // ATX Headings as defined in GitHub Flavored Markdown (https://github.github.com/gfm/#atx-headings) + const heading = /^ {0,3}(?#{1,6})(?: [ \t\v\f]*(?.*?)[ \t\v\f]*)?(?:[\n\r]+|$)/gm; + + const wantedHeadingRe = makeWordRegExp(wantedHeading); + + let start, end; + + for (const m of document.matchAll(heading)) { + if (!start) { + if (m.groups.text.search(wantedHeadingRe) === 0) { + start = m; + } + } else if (m.groups.lead.length <= start.groups.lead.length) { + end = m; + break; + } + } + + if (start) { + return document.slice(start.index + start[0].length, end?.index); + } +} diff --git a/scripts/release/workflow/integrity-check.sh b/scripts/release/workflow/integrity-check.sh new file mode 100644 index 000000000..86e99f929 --- /dev/null +++ b/scripts/release/workflow/integrity-check.sh @@ -0,0 +1,20 @@ +#!/usr/bin/env bash + +set -euo pipefail + +CHECKSUMS="$RUNNER_TEMP/checksums.txt" + +# Extract tarball content into a tmp directory +tar xf "$TARBALL" -C "$RUNNER_TEMP" + +# Move to extracted directory +cd "$RUNNER_TEMP/package" + +# Checksum all Solidity files +find . -type f -name "*.sol" | xargs shasum > "$CHECKSUMS" + +# Back to directory with git contents +cd "$GITHUB_WORKSPACE/contracts" + +# Check against tarball contents +shasum -c "$CHECKSUMS" diff --git a/scripts/release/workflow/pack.sh b/scripts/release/workflow/pack.sh new file mode 100644 index 000000000..ce30712f8 --- /dev/null +++ b/scripts/release/workflow/pack.sh @@ -0,0 +1,26 @@ +#!/usr/bin/env bash + +set -euo pipefail + +dist_tag() { + PACKAGE_JSON_NAME="$(jq -r .name ./package.json)" + LATEST_NPM_VERSION="$(npm info "$PACKAGE_JSON_NAME" version)" + PACKAGE_JSON_VERSION="$(jq -r .version ./package.json)" + + if [ "$PRERELEASE" = "true" ]; then + echo "next" + elif npx semver -r ">$LATEST_NPM_VERSION" "$PACKAGE_JSON_VERSION" > /dev/null; then + echo "latest" + else + # This is a patch for an older version + # npm can't publish without a tag + echo "tmp" + fi +} + +cd contracts +TARBALL="$(npm pack | tee /dev/stderr | tail -1)" +echo "tarball_name=$TARBALL" >> $GITHUB_OUTPUT +echo "tarball=$(pwd)/$TARBALL" >> $GITHUB_OUTPUT +echo "tag=$(dist_tag)" >> $GITHUB_OUTPUT +cd .. diff --git a/scripts/release/workflow/publish.sh b/scripts/release/workflow/publish.sh new file mode 100644 index 000000000..e490e5d00 --- /dev/null +++ b/scripts/release/workflow/publish.sh @@ -0,0 +1,26 @@ +#!/usr/bin/env bash + +set -euo pipefail + +PACKAGE_JSON_NAME="$(tar xfO "$TARBALL" package/package.json | jq -r .name)" +PACKAGE_JSON_VERSION="$(tar xfO "$TARBALL" package/package.json | jq -r .version)" + +# Intentionally escape $ to avoid interpolation and writing the token to disk +echo "//registry.npmjs.org/:_authToken=\${NPM_TOKEN}" > .npmrc + +# Actual publish +npm publish "$TARBALL" --tag "$TAG" + +# Clean up tags +delete_tag() { + npm dist-tag rm "$PACKAGE_JSON_NAME" "$1" +} + +if [ "$TAG" = tmp ]; then + delete_tag "$TAG" +elif [ "$TAG" = latest ]; then + # Delete the next tag if it exists and is a prerelease for what is currently being published + if npm dist-tag ls "$PACKAGE_JSON_NAME" | grep -q "next: $PACKAGE_JSON_VERSION"; then + delete_tag next + fi +fi diff --git a/scripts/release/workflow/rerun.js b/scripts/release/workflow/rerun.js new file mode 100644 index 000000000..f48ce6ea2 --- /dev/null +++ b/scripts/release/workflow/rerun.js @@ -0,0 +1,7 @@ +module.exports = ({ github, context }) => + github.rest.actions.createWorkflowDispatch({ + owner: context.repo.owner, + repo: context.repo.repo, + workflow_id: 'release-cycle.yml', + ref: process.env.REF || process.env.GITHUB_REF_NAME, + }); diff --git a/scripts/release/workflow/set-changesets-pr-title.js b/scripts/release/workflow/set-changesets-pr-title.js new file mode 100644 index 000000000..59b03b22a --- /dev/null +++ b/scripts/release/workflow/set-changesets-pr-title.js @@ -0,0 +1,17 @@ +const { coerce, inc, rsort } = require('semver'); +const { join } = require('path'); +const { version } = require(join(__dirname, '../../../package.json')); + +module.exports = async ({ core }) => { + // Variables not in the context + const refName = process.env.GITHUB_REF_NAME; + + // Compare package.json version's next patch vs. first version patch + // A recently opened branch will give the next patch for the previous minor + // So, we get the max against the patch 0 of the release branch's version + const branchPatch0 = coerce(refName.replace('release-v', '')).version; + const packageJsonNextPatch = inc(version, 'patch'); + const [nextVersion] = rsort([branchPatch0, packageJsonNextPatch], false); + + core.exportVariable('TITLE', `Release v${nextVersion}`); +}; diff --git a/scripts/release/workflow/start.sh b/scripts/release/workflow/start.sh new file mode 100644 index 000000000..7683ec5bc --- /dev/null +++ b/scripts/release/workflow/start.sh @@ -0,0 +1,35 @@ +#!/usr/bin/env bash + +set -euo pipefail + +# Set changeset status location +# This is needed because `changeset status --output` only works with relative routes +CHANGESETS_STATUS_JSON="$(realpath --relative-to=. "$RUNNER_TEMP/status.json")" + +# Save changeset status to temp file +npx changeset status --output="$CHANGESETS_STATUS_JSON" + +# Defensive assertion. SHOULD NOT BE REACHED +if [ "$(jq '.releases | length' "$CHANGESETS_STATUS_JSON")" != 1 ]; then + echo "::error file=$CHANGESETS_STATUS_JSON::The status doesn't contain only 1 release" + exit 1; +fi; + +# Create branch +BRANCH_SUFFIX="$(jq -r '.releases[0].newVersion | gsub("\\.\\d+$"; "")' $CHANGESETS_STATUS_JSON)" +RELEASE_BRANCH="release-v$BRANCH_SUFFIX" +git checkout -b "$RELEASE_BRANCH" + +# Output branch +echo "branch=$RELEASE_BRANCH" >> $GITHUB_OUTPUT + +# Enter in prerelease state +npx changeset pre enter rc +git add . +git commit -m "Start release candidate" + +# Push branch +if ! git push origin "$RELEASE_BRANCH"; then + echo "::error file=scripts/release/start.sh::Can't push $RELEASE_BRANCH. Did you forget to run this workflow from $RELEASE_BRANCH?" + exit 1 +fi diff --git a/scripts/release/workflow/state.js b/scripts/release/workflow/state.js new file mode 100644 index 000000000..914e8de02 --- /dev/null +++ b/scripts/release/workflow/state.js @@ -0,0 +1,112 @@ +const { readPreState } = require('@changesets/pre'); +const { default: readChangesets } = require('@changesets/read'); +const { join } = require('path'); +const { fetch } = require('undici'); +const { version, name: packageName } = require(join(__dirname, '../../../contracts/package.json')); + +module.exports = async ({ github, context, core }) => { + const state = await getState({ github, context, core }); + + function setOutput(key, value) { + core.info(`State ${key} = ${value}`); + core.setOutput(key, value); + } + + // Jobs to trigger + setOutput('start', shouldRunStart(state)); + setOutput('promote', shouldRunPromote(state)); + setOutput('changesets', shouldRunChangesets(state)); + setOutput('publish', shouldRunPublish(state)); + setOutput('merge', shouldRunMerge(state)); + + // Global Variables + setOutput('is_prerelease', state.prerelease); +}; + +function shouldRunStart({ isMaster, isWorkflowDispatch, botRun }) { + return isMaster && isWorkflowDispatch && !botRun; +} + +function shouldRunPromote({ isReleaseBranch, isWorkflowDispatch, botRun }) { + return isReleaseBranch && isWorkflowDispatch && !botRun; +} + +function shouldRunChangesets({ isReleaseBranch, isPush, isWorkflowDispatch, botRun }) { + return (isReleaseBranch && isPush) || (isReleaseBranch && isWorkflowDispatch && botRun); +} + +function shouldRunPublish({ isReleaseBranch, isPush, hasPendingChangesets, isPublishedOnNpm }) { + return isReleaseBranch && isPush && !hasPendingChangesets && !isPublishedOnNpm; +} + +function shouldRunMerge({ + isReleaseBranch, + isPush, + prerelease, + isCurrentFinalVersion, + hasPendingChangesets, + prBackExists, +}) { + return isReleaseBranch && isPush && !prerelease && isCurrentFinalVersion && !hasPendingChangesets && !prBackExists; +} + +async function getState({ github, context, core }) { + // Variables not in the context + const refName = process.env.GITHUB_REF_NAME; + const botRun = process.env.TRIGGERING_ACTOR === 'github-actions[bot]'; + + const { changesets, preState } = await readChangesetState(); + + // Static vars + const state = { + refName, + hasPendingChangesets: changesets.length > 0, + prerelease: preState?.mode === 'pre', + isMaster: refName === 'master', + isReleaseBranch: refName.startsWith('release-v'), + isWorkflowDispatch: context.eventName === 'workflow_dispatch', + isPush: context.eventName === 'push', + isCurrentFinalVersion: !version.includes('-rc.'), + botRun, + }; + + // Async vars + const { data: prs } = await github.rest.pulls.list({ + owner: context.repo.owner, + repo: context.repo.repo, + head: `${context.repo.owner}:merge/${state.refName}`, + base: 'master', + state: 'open', + }); + + state.prBackExists = prs.length !== 0; + + state.isPublishedOnNpm = await isPublishedOnNpm(packageName, version); + + // Log every state value in debug mode + if (core.isDebug()) for (const [key, value] of Object.entries(state)) core.debug(`${key}: ${value}`); + + return state; +} + +// From https://github.com/changesets/action/blob/v1.4.1/src/readChangesetState.ts +async function readChangesetState(cwd = process.cwd()) { + const preState = await readPreState(cwd); + const isInPreMode = preState !== undefined && preState.mode === 'pre'; + + let changesets = await readChangesets(cwd); + + if (isInPreMode) { + changesets = changesets.filter(x => !preState.changesets.includes(x.id)); + } + + return { + preState: isInPreMode ? preState : undefined, + changesets, + }; +} + +async function isPublishedOnNpm(package, version) { + const res = await fetch(`https://registry.npmjs.com/${package}/${version}`); + return res.ok; +} diff --git a/scripts/remove-ignored-artifacts.js b/scripts/remove-ignored-artifacts.js new file mode 100644 index 000000000..f3e45b8d1 --- /dev/null +++ b/scripts/remove-ignored-artifacts.js @@ -0,0 +1,45 @@ +#!/usr/bin/env node + +// This script removes the build artifacts of ignored contracts. + +const fs = require('fs'); +const path = require('path'); +const match = require('micromatch'); + +function readJSON(path) { + return JSON.parse(fs.readFileSync(path)); +} + +const pkgFiles = readJSON('package.json').files; + +// Get only negated patterns. +const ignorePatterns = pkgFiles + .filter(pat => pat.startsWith('!')) + // Remove the negation part. Makes micromatch usage more intuitive. + .map(pat => pat.slice(1)); + +const ignorePatternsSubtrees = ignorePatterns + // Add **/* to ignore all files contained in the directories. + .concat(ignorePatterns.map(pat => path.join(pat, '**/*'))) + .map(p => p.replace(/^\//, '')); + +const artifactsDir = 'build/contracts'; +const buildinfo = 'artifacts/build-info'; +const filenames = fs.readdirSync(buildinfo); + +let n = 0; + +for (const filename of filenames) { + const solcOutput = readJSON(path.join(buildinfo, filename)).output; + for (const sourcePath in solcOutput.contracts) { + const ignore = match.any(sourcePath, ignorePatternsSubtrees); + if (ignore) { + for (const contract in solcOutput.contracts[sourcePath]) { + fs.unlinkSync(path.join(artifactsDir, contract + '.json')); + n += 1; + } + } + } +} + +console.error(`Removed ${n} mock artifacts`); diff --git a/scripts/solhint-custom/index.js b/scripts/solhint-custom/index.js new file mode 100644 index 000000000..9625027ee --- /dev/null +++ b/scripts/solhint-custom/index.js @@ -0,0 +1,84 @@ +const path = require('path'); +const minimatch = require('minimatch'); + +// Files matching these patterns will be ignored unless a rule has `static global = true` +const ignore = ['contracts/mocks/**/*', 'test/**/*']; + +class Base { + constructor(reporter, config, source, fileName) { + this.reporter = reporter; + this.ignored = this.constructor.global || ignore.some(p => minimatch(path.normalize(fileName), p)); + this.ruleId = this.constructor.ruleId; + if (this.ruleId === undefined) { + throw Error('missing ruleId static property'); + } + } + + error(node, message) { + if (!this.ignored) { + this.reporter.error(node, this.ruleId, message); + } + } +} + +module.exports = [ + class extends Base { + static ruleId = 'interface-names'; + + ContractDefinition(node) { + if (node.kind === 'interface' && !/^I[A-Z]/.test(node.name)) { + this.error(node, 'Interface names should have a capital I prefix'); + } + } + }, + + class extends Base { + static ruleId = 'private-variables'; + + VariableDeclaration(node) { + const constantOrImmutable = node.isDeclaredConst || node.isImmutable; + if (node.isStateVar && !constantOrImmutable && node.visibility !== 'private') { + this.error(node, 'State variables must be private'); + } + } + }, + + class extends Base { + static ruleId = 'leading-underscore'; + + VariableDeclaration(node) { + if (node.isDeclaredConst) { + // TODO: expand visibility and fix + if (node.visibility === 'private' && /^_/.test(node.name)) { + this.error(node, 'Constant variables should not have leading underscore'); + } + } else if (node.visibility === 'private' && !/^_/.test(node.name)) { + this.error(node, 'Non-constant private variables must have leading underscore'); + } + } + + FunctionDefinition(node) { + if (node.visibility === 'private' || (node.visibility === 'internal' && node.parent.kind !== 'library')) { + if (!/^_/.test(node.name)) { + this.error(node, 'Private and internal functions must have leading underscore'); + } + } + if (node.visibility === 'internal' && node.parent.kind === 'library') { + if (/^_/.test(node.name)) { + this.error(node, 'Library internal functions should not have leading underscore'); + } + } + } + }, + + // TODO: re-enable and fix + // class extends Base { + // static ruleId = 'no-external-virtual'; + // + // FunctionDefinition(node) { + // if (node.visibility == 'external' && node.isVirtual) { + // this.error(node, 'Functions should not be external and virtual'); + // } + // } + // }, +]; diff --git a/scripts/solhint-custom/package.json b/scripts/solhint-custom/package.json new file mode 100644 index 000000000..d91e327a4 --- /dev/null +++ b/scripts/solhint-custom/package.json @@ -0,0 +1,4 @@ +{ + "name": "solhint-plugin-openzeppelin", + "private": true +} diff --git a/scripts/update-docs-branch.js b/scripts/update-docs-branch.js new file mode 100644 index 000000000..26922ec49 --- /dev/null +++ b/scripts/update-docs-branch.js @@ -0,0 +1,58 @@ +const proc = require('child_process'); +const read = cmd => proc.execSync(cmd, { encoding: 'utf8' }).trim(); +const run = cmd => { + proc.execSync(cmd, { stdio: 'inherit' }); +}; +const tryRead = cmd => { + try { + return read(cmd); + } catch (e) { + return undefined; + } +}; + +const releaseBranchRegex = /^release-v(?(?\d+)\.(?\d+)(?:\.(?\d+))?)$/; + +const currentBranch = read('git rev-parse --abbrev-ref HEAD'); +const match = currentBranch.match(releaseBranchRegex); + +if (!match) { + console.error('Not currently on a release branch'); + process.exit(1); +} + +const current = match.groups; +const docsBranch = `docs-v${current.major}.x`; + +// Fetch remotes and find the docs branch if it exists +run('git fetch --all --no-tags'); +const matchingDocsBranches = tryRead(`git rev-parse --glob='*/${docsBranch}'`); + +if (!matchingDocsBranches) { + // Create the branch + run(`git checkout --orphan ${docsBranch}`); +} else { + const [publishedRef, ...others] = new Set(matchingDocsBranches.split('\n')); + if (others.length > 0) { + console.error( + `Found conflicting ${docsBranch} branches.\n` + + 'Either local branch is outdated or there are multiple matching remote branches.', + ); + process.exit(1); + } + const publishedVersion = JSON.parse(read(`git show ${publishedRef}:package.json`)).version; + const publishedMinor = publishedVersion.match(/\d+\.(?\d+)\.\d+/).groups.minor; + if (current.minor < publishedMinor) { + console.error('Refusing to update docs: newer version is published'); + process.exit(0); + } + + run('git checkout --quiet --detach'); + run(`git reset --soft ${publishedRef}`); + run(`git checkout ${docsBranch}`); +} + +run('npm run prepare-docs'); +run('git add -f docs'); // --force needed because generated docs files are gitignored +run('git commit -m "Update docs"'); +run(`git checkout ${currentBranch}`); diff --git a/scripts/upgradeable/README.md b/scripts/upgradeable/README.md new file mode 100644 index 000000000..2309f9e10 --- /dev/null +++ b/scripts/upgradeable/README.md @@ -0,0 +1,21 @@ +The upgradeable variant of OpenZeppelin Contracts is automatically generated from the original Solidity code. We call this process "transpilation" and it is implemented by our [Upgradeability Transpiler](https://github.com/OpenZeppelin/openzeppelin-transpiler/). + +When the `master` branch or `release-v*` branches are updated, the code is transpiled and pushed to [OpenZeppelin/openzeppelin-contracts-upgradeable](https://github.com/OpenZeppelin/openzeppelin-contracts-upgradeable) by the `upgradeable.yml` workflow. + +## `transpile.sh` + +Applies patches and invokes the transpiler with the command line flags we need for our requirements (for example, excluding certain files). + +## `transpile-onto.sh` + +``` +bash scripts/upgradeable/transpile-onto.sh [] +``` + +Transpiles the contents of the current git branch and commits the result as a new commit on branch ``. If branch `` doesn't exist, it will copy the commit history of `[]` (this is used in GitHub Actions, but is usually not necessary locally). + +## `patch-apply.sh` & `patch-save.sh` + +Some of the upgradeable contract variants require ad-hoc changes that are not implemented by the transpiler. These changes are implemented by patches stored in `upgradeable.patch` in this directory. `patch-apply.sh` applies these patches. + +If the patches fail to apply due to changes in the repo, the conflicts have to be resolved manually. Once fixed, `patch-save.sh` will take the changes staged in Git and update `upgradeable.patch` to match. diff --git a/scripts/upgradeable/patch-apply.sh b/scripts/upgradeable/patch-apply.sh new file mode 100755 index 000000000..d9e17589b --- /dev/null +++ b/scripts/upgradeable/patch-apply.sh @@ -0,0 +1,19 @@ +#!/usr/bin/env bash + +set -euo pipefail + +DIRNAME="$(dirname -- "${BASH_SOURCE[0]}")" +PATCH="$DIRNAME/upgradeable.patch" + +error() { + echo Error: "$*" >&2 + exit 1 +} + +if ! git diff-files --quiet ":!$PATCH" || ! git diff-index --quiet HEAD ":!$PATCH"; then + error "Repository must have no staged or unstaged changes" +fi + +if ! git apply -3 "$PATCH"; then + error "Fix conflicts and run $DIRNAME/patch-save.sh" +fi diff --git a/scripts/upgradeable/patch-save.sh b/scripts/upgradeable/patch-save.sh new file mode 100755 index 000000000..111e6f157 --- /dev/null +++ b/scripts/upgradeable/patch-save.sh @@ -0,0 +1,18 @@ +#!/usr/bin/env bash + +set -euo pipefail + +DIRNAME="$(dirname -- "${BASH_SOURCE[0]}")" +PATCH="$DIRNAME/upgradeable.patch" + +error() { + echo Error: "$*" >&2 + exit 1 +} + +if ! git diff-files --quiet ":!$PATCH"; then + error "Unstaged changes. Stage to include in patch or temporarily stash." +fi + +git diff-index --cached --patch --output="$PATCH" HEAD +git restore --staged --worktree ":!$PATCH" diff --git a/scripts/upgradeable/transpile-onto.sh b/scripts/upgradeable/transpile-onto.sh new file mode 100644 index 000000000..a966a9b9a --- /dev/null +++ b/scripts/upgradeable/transpile-onto.sh @@ -0,0 +1,44 @@ +#!/usr/bin/env bash + +set -euo pipefail + +if [ $# -lt 1 ]; then + echo "usage: bash $0 []" >&2 + exit 1 +fi + +set -x + +target="$1" +base="${2-}" + +bash scripts/upgradeable/transpile.sh + +commit="$(git rev-parse --short HEAD)" +branch="$(git rev-parse --abbrev-ref HEAD)" + +git add contracts + +# detach from the current branch to avoid making changes to it +git checkout --quiet --detach + +# switch to the target branch, creating it if necessary +if git rev-parse -q --verify "$target"; then + # if the branch exists, make it the current HEAD without checking out its contents + git reset --soft "$target" + git checkout "$target" +else + # if the branch doesn't exist, create it as an orphan and check it out + git checkout --orphan "$target" + if [ -n "$base" ] && git rev-parse -q --verify "$base"; then + # if base was specified and it exists, set it as the branch history + git reset --soft "$base" + fi +fi + +# commit if there are changes to commit +if ! git diff --quiet --cached; then + git commit -m "Transpile $commit" +fi + +git checkout "$branch" diff --git a/scripts/upgradeable/transpile.sh b/scripts/upgradeable/transpile.sh new file mode 100644 index 000000000..05de96d34 --- /dev/null +++ b/scripts/upgradeable/transpile.sh @@ -0,0 +1,42 @@ +#!/usr/bin/env bash + +set -euo pipefail -x + +DIRNAME="$(dirname -- "${BASH_SOURCE[0]}")" + +bash "$DIRNAME/patch-apply.sh" + +npm run clean +npm run compile + +build_info=($(jq -r '.input.sources | keys | if any(test("^contracts/mocks/.*\\bunreachable\\b")) then empty else input_filename end' artifacts/build-info/*)) +build_info_num=${#build_info[@]} + +if [ $build_info_num -ne 1 ]; then + echo "found $build_info_num relevant build info files but expected just 1" + exit 1 +fi + +# -D: delete original and excluded files +# -b: use this build info file +# -i: use included Initializable +# -x: exclude proxy-related contracts with a few exceptions +# -p: emit public initializer +# -n: use namespaces +# -N: exclude from namespaces transformation +npx @openzeppelin/upgrade-safe-transpiler@latest -D \ + -b "$build_info" \ + -i contracts/proxy/utils/Initializable.sol \ + -x 'contracts-exposed/**/*' \ + -x 'contracts/proxy/**/*' \ + -x '!contracts/proxy/Clones.sol' \ + -x '!contracts/proxy/ERC1967/ERC1967Storage.sol' \ + -x '!contracts/proxy/ERC1967/ERC1967Utils.sol' \ + -x '!contracts/proxy/utils/UUPSUpgradeable.sol' \ + -x '!contracts/proxy/beacon/IBeacon.sol' \ + -p 'contracts/**/presets/**/*' \ + -n \ + -N 'contracts/mocks/**/*' + +# delete compilation artifacts of vanilla code +npm run clean diff --git a/scripts/upgradeable/upgradeable.patch b/scripts/upgradeable/upgradeable.patch new file mode 100644 index 000000000..125272a25 --- /dev/null +++ b/scripts/upgradeable/upgradeable.patch @@ -0,0 +1,342 @@ +diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md +deleted file mode 100644 +index 2797a088..00000000 +--- a/.github/ISSUE_TEMPLATE/bug_report.md ++++ /dev/null +@@ -1,21 +0,0 @@ +---- +-name: Bug report +-about: Report a bug in OpenZeppelin Contracts +- +---- +- +- +- +- +- +-**💻 Environment** +- +- +- +-**📝 Details** +- +- +- +-**🔢 Code to reproduce bug** +- +- +diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml +index 4018cef2..d343a53d 100644 +--- a/.github/ISSUE_TEMPLATE/config.yml ++++ b/.github/ISSUE_TEMPLATE/config.yml +@@ -1,4 +1,8 @@ ++blank_issues_enabled: false + contact_links: ++ - name: Bug Reports & Feature Requests ++ url: https://github.com/OpenZeppelin/openzeppelin-contracts/issues/new/choose ++ about: Visit the OpenZeppelin Contracts repository + - name: Questions & Support Requests + url: https://forum.openzeppelin.com/c/support/contracts/18 + about: Ask in the OpenZeppelin Forum +diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md +deleted file mode 100644 +index ff596b0c..00000000 +--- a/.github/ISSUE_TEMPLATE/feature_request.md ++++ /dev/null +@@ -1,14 +0,0 @@ +---- +-name: Feature request +-about: Suggest an idea for OpenZeppelin Contracts +- +---- +- +-**🧐 Motivation** +- +- +-**📝 Details** +- +- +- +- +diff --git a/README.md b/README.md +index 38197f3a..bc934d1c 100644 +--- a/README.md ++++ b/README.md +@@ -19,6 +19,9 @@ + + :building_construction: **Want to scale your decentralized application?** Check out [OpenZeppelin Defender](https://openzeppelin.com/defender) — a secure platform for automating and monitoring your operations. + ++> **Note** ++> You are looking at the upgradeable variant of OpenZeppelin Contracts. Be sure to review the documentation on [Using OpenZeppelin Contracts with Upgrades](https://docs.openzeppelin.com/contracts/4.x/upgradeable). ++ + ## Overview + + ### Installation +@@ -26,7 +29,7 @@ + #### Hardhat, Truffle (npm) + + ``` +-$ npm install @openzeppelin/contracts ++$ npm install @openzeppelin/contracts-upgradeable + ``` + + OpenZeppelin Contracts features a [stable API](https://docs.openzeppelin.com/contracts/releases-stability#api-stability), which means that your contracts won't break unexpectedly when upgrading to a newer minor version. +@@ -38,10 +41,10 @@ OpenZeppelin Contracts features a [stable API](https://docs.openzeppelin.com/con + > **Warning** Foundry installs the latest version initially, but subsequent `forge update` commands will use the `master` branch. + + ``` +-$ forge install OpenZeppelin/openzeppelin-contracts ++$ forge install OpenZeppelin/openzeppelin-contracts-upgradeable + ``` + +-Add `@openzeppelin/contracts/=lib/openzeppelin-contracts/contracts/` in `remappings.txt.` ++Add `@openzeppelin/contracts-upgradeable/=lib/openzeppelin-contracts-upgradeable/contracts/` in `remappings.txt.` + + ### Usage + +@@ -50,10 +53,11 @@ Once installed, you can use the contracts in the library by importing them: + ```solidity + pragma solidity ^0.8.20; + +-import {ERC721} from "@openzeppelin/contracts/token/ERC721/ERC721.sol"; ++import {ERC721Upgradeable} from "@openzeppelin/contracts-upgradeable/token/ERC721/ERC721Upgradeable.sol"; + +-contract MyCollectible is ERC721 { +- constructor() ERC721("MyCollectible", "MCO") { ++contract MyCollectible is ERC721Upgradeable { ++ function initialize() initializer public { ++ __ERC721_init("MyCollectible", "MCO"); + } + } + ``` +diff --git a/contracts/package.json b/contracts/package.json +index df141192..1cf90ad1 100644 +--- a/contracts/package.json ++++ b/contracts/package.json +@@ -1,5 +1,5 @@ + { +- "name": "@openzeppelin/contracts", ++ "name": "@openzeppelin/contracts-upgradeable", + "description": "Secure Smart Contract library for Solidity", + "version": "4.9.2", + "files": [ +@@ -13,7 +13,7 @@ + }, + "repository": { + "type": "git", +- "url": "https://github.com/OpenZeppelin/openzeppelin-contracts.git" ++ "url": "https://github.com/OpenZeppelin/openzeppelin-contracts-upgradeable.git" + }, + "keywords": [ + "solidity", +diff --git a/contracts/utils/cryptography/EIP712.sol b/contracts/utils/cryptography/EIP712.sol +index 3800804a..90c1db78 100644 +--- a/contracts/utils/cryptography/EIP712.sol ++++ b/contracts/utils/cryptography/EIP712.sol +@@ -4,7 +4,6 @@ + pragma solidity ^0.8.20; + + import {MessageHashUtils} from "./MessageHashUtils.sol"; +-import {ShortStrings, ShortString} from "../ShortStrings.sol"; + import {IERC5267} from "../../interfaces/IERC5267.sol"; + + /** +@@ -28,28 +27,18 @@ import {IERC5267} from "../../interfaces/IERC5267.sol"; + * NOTE: In the upgradeable version of this contract, the cached values will correspond to the address, and the domain + * separator of the implementation contract. This will cause the {_domainSeparatorV4} function to always rebuild the + * separator from the immutable values, which is cheaper than accessing a cached version in cold storage. +- * +- * @custom:oz-upgrades-unsafe-allow state-variable-immutable + */ + abstract contract EIP712 is IERC5267 { +- using ShortStrings for *; +- + bytes32 private constant TYPE_HASH = + keccak256("EIP712Domain(string name,string version,uint256 chainId,address verifyingContract)"); + +- // Cache the domain separator as an immutable value, but also store the chain id that it corresponds to, in order to +- // invalidate the cached domain separator if the chain id changes. +- bytes32 private immutable _cachedDomainSeparator; +- uint256 private immutable _cachedChainId; +- address private immutable _cachedThis; +- ++ /// @custom:oz-renamed-from _HASHED_NAME + bytes32 private immutable _hashedName; ++ /// @custom:oz-renamed-from _HASHED_VERSION + bytes32 private immutable _hashedVersion; + +- ShortString private immutable _name; +- ShortString private immutable _version; +- string private _nameFallback; +- string private _versionFallback; ++ string private _name; ++ string private _version; + + /** + * @dev Initializes the domain separator and parameter caches. +@@ -64,29 +53,23 @@ abstract contract EIP712 is IERC5267 { + * contract upgrade]. + */ + constructor(string memory name, string memory version) { +- _name = name.toShortStringWithFallback(_nameFallback); +- _version = version.toShortStringWithFallback(_versionFallback); +- _hashedName = keccak256(bytes(name)); +- _hashedVersion = keccak256(bytes(version)); +- +- _cachedChainId = block.chainid; +- _cachedDomainSeparator = _buildDomainSeparator(); +- _cachedThis = address(this); ++ _name = name; ++ _version = version; ++ ++ // Reset prior values in storage if upgrading ++ _hashedName = 0; ++ _hashedVersion = 0; + } + + /** + * @dev Returns the domain separator for the current chain. + */ + function _domainSeparatorV4() internal view returns (bytes32) { +- if (address(this) == _cachedThis && block.chainid == _cachedChainId) { +- return _cachedDomainSeparator; +- } else { +- return _buildDomainSeparator(); +- } ++ return _buildDomainSeparator(); + } + + function _buildDomainSeparator() private view returns (bytes32) { +- return keccak256(abi.encode(TYPE_HASH, _hashedName, _hashedVersion, block.chainid, address(this))); ++ return keccak256(abi.encode(TYPE_HASH, _EIP712NameHash(), _EIP712VersionHash(), block.chainid, address(this))); + } + + /** +@@ -125,6 +108,10 @@ abstract contract EIP712 is IERC5267 { + uint256[] memory extensions + ) + { ++ // If the hashed name and version in storage are non-zero, the contract hasn't been properly initialized ++ // and the EIP712 domain is not reliable, as it will be missing name and version. ++ require(_hashedName == 0 && _hashedVersion == 0, "EIP712: Uninitialized"); ++ + return ( + hex"0f", // 01111 + _EIP712Name(), +@@ -139,22 +126,62 @@ abstract contract EIP712 is IERC5267 { + /** + * @dev The name parameter for the EIP712 domain. + * +- * NOTE: By default this function reads _name which is an immutable value. +- * It only reads from storage if necessary (in case the value is too large to fit in a ShortString). ++ * NOTE: This function reads from storage by default, but can be redefined to return a constant value if gas costs ++ * are a concern. + */ +- // solhint-disable-next-line func-name-mixedcase +- function _EIP712Name() internal view returns (string memory) { +- return _name.toStringWithFallback(_nameFallback); ++ function _EIP712Name() internal view virtual returns (string memory) { ++ return _name; + } + + /** + * @dev The version parameter for the EIP712 domain. + * +- * NOTE: By default this function reads _version which is an immutable value. +- * It only reads from storage if necessary (in case the value is too large to fit in a ShortString). ++ * NOTE: This function reads from storage by default, but can be redefined to return a constant value if gas costs ++ * are a concern. + */ +- // solhint-disable-next-line func-name-mixedcase +- function _EIP712Version() internal view returns (string memory) { +- return _version.toStringWithFallback(_versionFallback); ++ function _EIP712Version() internal view virtual returns (string memory) { ++ return _version; ++ } ++ ++ /** ++ * @dev The hash of the name parameter for the EIP712 domain. ++ * ++ * NOTE: In previous versions this function was virtual. In this version you should override `_EIP712Name` instead. ++ */ ++ function _EIP712NameHash() internal view returns (bytes32) { ++ string memory name = _EIP712Name(); ++ if (bytes(name).length > 0) { ++ return keccak256(bytes(name)); ++ } else { ++ // If the name is empty, the contract may have been upgraded without initializing the new storage. ++ // We return the name hash in storage if non-zero, otherwise we assume the name is empty by design. ++ bytes32 hashedName = _hashedName; ++ if (hashedName != 0) { ++ return hashedName; ++ } else { ++ return keccak256(""); ++ } ++ } ++ } ++ ++ /** ++ * @dev The hash of the version parameter for the EIP712 domain. ++ * ++ * NOTE: In previous versions this function was virtual. In this version you should override `_EIP712Version` instead. ++ */ ++ function _EIP712VersionHash() internal view returns (bytes32) { ++ string memory version = _EIP712Version(); ++ if (bytes(version).length > 0) { ++ return keccak256(bytes(version)); ++ } else { ++ // If the version is empty, the contract may have been upgraded without initializing the new storage. ++ // We return the version hash in storage if non-zero, otherwise we assume the version is empty by design. ++ bytes32 hashedVersion = _hashedVersion; ++ if (hashedVersion != 0) { ++ return hashedVersion; ++ } else { ++ return keccak256(""); ++ } ++ } + } + } +diff --git a/package.json b/package.json +index ffa868ac..e254d962 100644 +--- a/package.json ++++ b/package.json +@@ -33,7 +33,7 @@ + }, + "repository": { + "type": "git", +- "url": "https://github.com/OpenZeppelin/openzeppelin-contracts.git" ++ "url": "https://github.com/OpenZeppelin/openzeppelin-contracts-upgradeable.git" + }, + "keywords": [ + "solidity", +diff --git a/test/utils/cryptography/EIP712.test.js b/test/utils/cryptography/EIP712.test.js +index 7ea535b7..32e3a370 100644 +--- a/test/utils/cryptography/EIP712.test.js ++++ b/test/utils/cryptography/EIP712.test.js +@@ -47,26 +47,6 @@ contract('EIP712', function (accounts) { + const rebuildDomain = await getDomain(this.eip712); + expect(mapValues(rebuildDomain, String)).to.be.deep.equal(mapValues(this.domain, String)); + }); +- +- if (shortOrLong === 'short') { +- // Long strings are in storage, and the proxy will not be properly initialized unless +- // the upgradeable contract variant is used and the initializer is invoked. +- +- it('adjusts when behind proxy', async function () { +- const factory = await Clones.new(); +- const cloneReceipt = await factory.$clone(this.eip712.address); +- const cloneAddress = cloneReceipt.logs.find(({ event }) => event === 'return$clone').args.instance; +- const clone = new EIP712Verifier(cloneAddress); +- +- const cloneDomain = { ...this.domain, verifyingContract: clone.address }; +- +- const reportedDomain = await getDomain(clone); +- expect(mapValues(reportedDomain, String)).to.be.deep.equal(mapValues(cloneDomain, String)); +- +- const expectedSeparator = await domainSeparator(cloneDomain); +- expect(await clone.$_domainSeparatorV4()).to.equal(expectedSeparator); +- }); +- } + }); + + it('hash digest', async function () { diff --git a/slither.config.json b/slither.config.json new file mode 100644 index 000000000..069da1f3a --- /dev/null +++ b/slither.config.json @@ -0,0 +1,5 @@ +{ + "detectors_to_run": "arbitrary-send-erc20,array-by-reference,incorrect-shift,name-reused,rtlo,suicidal,uninitialized-state,uninitialized-storage,arbitrary-send-erc20-permit,controlled-array-length,controlled-delegatecall,delegatecall-loop,msg-value-loop,reentrancy-eth,unchecked-transfer,weak-prng,domain-separator-collision,erc20-interface,erc721-interface,locked-ether,mapping-deletion,shadowing-abstract,tautology,write-after-write,boolean-cst,reentrancy-no-eth,reused-constructor,tx-origin,unchecked-lowlevel,unchecked-send,variable-scope,void-cst,events-access,events-maths,incorrect-unary,boolean-equal,cyclomatic-complexity,deprecated-standards,erc20-indexed,function-init-state,pragma,unused-state,reentrancy-unlimited-gas,constable-states,immutable-states,var-read-using-this", + "filter_paths": "contracts/mocks,contracts-exposed", + "compile_force_framework": "hardhat" +} diff --git a/solhint.config.js b/solhint.config.js new file mode 100644 index 000000000..123ff91fa --- /dev/null +++ b/solhint.config.js @@ -0,0 +1,20 @@ +const customRules = require('./scripts/solhint-custom'); + +const rules = [ + 'no-unused-vars', + 'const-name-snakecase', + 'contract-name-camelcase', + 'event-name-camelcase', + 'func-name-mixedcase', + 'func-param-name-mixedcase', + 'modifier-name-mixedcase', + 'var-name-mixedcase', + 'imports-on-top', + 'no-global-import', + ...customRules.map(r => `openzeppelin/${r.ruleId}`), +]; + +module.exports = { + plugins: ['openzeppelin'], + rules: Object.fromEntries(rules.map(r => [r, 'error'])), +}; diff --git a/test/TESTING.md b/test/TESTING.md new file mode 100644 index 000000000..a5ee9323f --- /dev/null +++ b/test/TESTING.md @@ -0,0 +1,3 @@ +## Testing + +Unit test are critical to OpenZeppelin Contracts. They help ensure code quality and mitigate against security vulnerabilities. The directory structure within the `/test` directory corresponds to the `/contracts` directory. diff --git a/test/access/AccessControl.behavior.js b/test/access/AccessControl.behavior.js new file mode 100644 index 000000000..cc3e8d63f --- /dev/null +++ b/test/access/AccessControl.behavior.js @@ -0,0 +1,909 @@ +const { expectEvent, constants, BN } = require('@openzeppelin/test-helpers'); +const { expectRevertCustomError } = require('../helpers/customError'); +const { expect } = require('chai'); + +const { time } = require('@nomicfoundation/hardhat-network-helpers'); + +const { shouldSupportInterfaces } = require('../utils/introspection/SupportsInterface.behavior'); +const { network } = require('hardhat'); +const { ZERO_ADDRESS } = require('@openzeppelin/test-helpers/src/constants'); + +const DEFAULT_ADMIN_ROLE = '0x0000000000000000000000000000000000000000000000000000000000000000'; +const ROLE = web3.utils.soliditySha3('ROLE'); +const OTHER_ROLE = web3.utils.soliditySha3('OTHER_ROLE'); +const ZERO = web3.utils.toBN(0); + +function shouldBehaveLikeAccessControl(admin, authorized, other, otherAdmin) { + shouldSupportInterfaces(['AccessControl']); + + describe('default admin', function () { + it('deployer has default admin role', async function () { + expect(await this.accessControl.hasRole(DEFAULT_ADMIN_ROLE, admin)).to.equal(true); + }); + + it("other roles's admin is the default admin role", async function () { + expect(await this.accessControl.getRoleAdmin(ROLE)).to.equal(DEFAULT_ADMIN_ROLE); + }); + + it("default admin role's admin is itself", async function () { + expect(await this.accessControl.getRoleAdmin(DEFAULT_ADMIN_ROLE)).to.equal(DEFAULT_ADMIN_ROLE); + }); + }); + + describe('granting', function () { + beforeEach(async function () { + await this.accessControl.grantRole(ROLE, authorized, { from: admin }); + }); + + it('non-admin cannot grant role to other accounts', async function () { + await expectRevertCustomError( + this.accessControl.grantRole(ROLE, authorized, { from: other }), + 'AccessControlUnauthorizedAccount', + [other, DEFAULT_ADMIN_ROLE], + ); + }); + + it('accounts can be granted a role multiple times', async function () { + await this.accessControl.grantRole(ROLE, authorized, { from: admin }); + const receipt = await this.accessControl.grantRole(ROLE, authorized, { from: admin }); + expectEvent.notEmitted(receipt, 'RoleGranted'); + }); + }); + + describe('revoking', function () { + it('roles that are not had can be revoked', async function () { + expect(await this.accessControl.hasRole(ROLE, authorized)).to.equal(false); + + const receipt = await this.accessControl.revokeRole(ROLE, authorized, { from: admin }); + expectEvent.notEmitted(receipt, 'RoleRevoked'); + }); + + context('with granted role', function () { + beforeEach(async function () { + await this.accessControl.grantRole(ROLE, authorized, { from: admin }); + }); + + it('admin can revoke role', async function () { + const receipt = await this.accessControl.revokeRole(ROLE, authorized, { from: admin }); + expectEvent(receipt, 'RoleRevoked', { account: authorized, role: ROLE, sender: admin }); + + expect(await this.accessControl.hasRole(ROLE, authorized)).to.equal(false); + }); + + it('non-admin cannot revoke role', async function () { + await expectRevertCustomError( + this.accessControl.revokeRole(ROLE, authorized, { from: other }), + 'AccessControlUnauthorizedAccount', + [other, DEFAULT_ADMIN_ROLE], + ); + }); + + it('a role can be revoked multiple times', async function () { + await this.accessControl.revokeRole(ROLE, authorized, { from: admin }); + + const receipt = await this.accessControl.revokeRole(ROLE, authorized, { from: admin }); + expectEvent.notEmitted(receipt, 'RoleRevoked'); + }); + }); + }); + + describe('renouncing', function () { + it('roles that are not had can be renounced', async function () { + const receipt = await this.accessControl.renounceRole(ROLE, authorized, { from: authorized }); + expectEvent.notEmitted(receipt, 'RoleRevoked'); + }); + + context('with granted role', function () { + beforeEach(async function () { + await this.accessControl.grantRole(ROLE, authorized, { from: admin }); + }); + + it('bearer can renounce role', async function () { + const receipt = await this.accessControl.renounceRole(ROLE, authorized, { from: authorized }); + expectEvent(receipt, 'RoleRevoked', { account: authorized, role: ROLE, sender: authorized }); + + expect(await this.accessControl.hasRole(ROLE, authorized)).to.equal(false); + }); + + it('only the sender can renounce their roles', async function () { + await expectRevertCustomError( + this.accessControl.renounceRole(ROLE, authorized, { from: admin }), + 'AccessControlBadConfirmation', + [], + ); + }); + + it('a role can be renounced multiple times', async function () { + await this.accessControl.renounceRole(ROLE, authorized, { from: authorized }); + + const receipt = await this.accessControl.renounceRole(ROLE, authorized, { from: authorized }); + expectEvent.notEmitted(receipt, 'RoleRevoked'); + }); + }); + }); + + describe('setting role admin', function () { + beforeEach(async function () { + const receipt = await this.accessControl.$_setRoleAdmin(ROLE, OTHER_ROLE); + expectEvent(receipt, 'RoleAdminChanged', { + role: ROLE, + previousAdminRole: DEFAULT_ADMIN_ROLE, + newAdminRole: OTHER_ROLE, + }); + + await this.accessControl.grantRole(OTHER_ROLE, otherAdmin, { from: admin }); + }); + + it("a role's admin role can be changed", async function () { + expect(await this.accessControl.getRoleAdmin(ROLE)).to.equal(OTHER_ROLE); + }); + + it('the new admin can grant roles', async function () { + const receipt = await this.accessControl.grantRole(ROLE, authorized, { from: otherAdmin }); + expectEvent(receipt, 'RoleGranted', { account: authorized, role: ROLE, sender: otherAdmin }); + }); + + it('the new admin can revoke roles', async function () { + await this.accessControl.grantRole(ROLE, authorized, { from: otherAdmin }); + const receipt = await this.accessControl.revokeRole(ROLE, authorized, { from: otherAdmin }); + expectEvent(receipt, 'RoleRevoked', { account: authorized, role: ROLE, sender: otherAdmin }); + }); + + it("a role's previous admins no longer grant roles", async function () { + await expectRevertCustomError( + this.accessControl.grantRole(ROLE, authorized, { from: admin }), + 'AccessControlUnauthorizedAccount', + [admin.toLowerCase(), OTHER_ROLE], + ); + }); + + it("a role's previous admins no longer revoke roles", async function () { + await expectRevertCustomError( + this.accessControl.revokeRole(ROLE, authorized, { from: admin }), + 'AccessControlUnauthorizedAccount', + [admin.toLowerCase(), OTHER_ROLE], + ); + }); + }); + + describe('onlyRole modifier', function () { + beforeEach(async function () { + await this.accessControl.grantRole(ROLE, authorized, { from: admin }); + }); + + it('do not revert if sender has role', async function () { + await this.accessControl.methods['$_checkRole(bytes32)'](ROLE, { from: authorized }); + }); + + it("revert if sender doesn't have role #1", async function () { + await expectRevertCustomError( + this.accessControl.methods['$_checkRole(bytes32)'](ROLE, { from: other }), + 'AccessControlUnauthorizedAccount', + [other, ROLE], + ); + }); + + it("revert if sender doesn't have role #2", async function () { + await expectRevertCustomError( + this.accessControl.methods['$_checkRole(bytes32)'](OTHER_ROLE, { from: authorized }), + 'AccessControlUnauthorizedAccount', + [authorized.toLowerCase(), OTHER_ROLE], + ); + }); + }); + + describe('internal functions', function () { + describe('_grantRole', function () { + it('return true if the account does not have the role', async function () { + const receipt = await this.accessControl.$_grantRole(ROLE, authorized); + expectEvent(receipt, 'return$_grantRole', { ret0: true }); + }); + + it('return false if the account has the role', async function () { + await this.accessControl.$_grantRole(ROLE, authorized); + + const receipt = await this.accessControl.$_grantRole(ROLE, authorized); + expectEvent(receipt, 'return$_grantRole', { ret0: false }); + }); + }); + + describe('_revokeRole', function () { + it('return true if the account has the role', async function () { + await this.accessControl.$_grantRole(ROLE, authorized); + + const receipt = await this.accessControl.$_revokeRole(ROLE, authorized); + expectEvent(receipt, 'return$_revokeRole', { ret0: true }); + }); + + it('return false if the account does not have the role', async function () { + const receipt = await this.accessControl.$_revokeRole(ROLE, authorized); + expectEvent(receipt, 'return$_revokeRole', { ret0: false }); + }); + }); + }); +} + +function shouldBehaveLikeAccessControlEnumerable(admin, authorized, other, otherAdmin, otherAuthorized) { + shouldSupportInterfaces(['AccessControlEnumerable']); + + describe('enumerating', function () { + it('role bearers can be enumerated', async function () { + await this.accessControl.grantRole(ROLE, authorized, { from: admin }); + await this.accessControl.grantRole(ROLE, other, { from: admin }); + await this.accessControl.grantRole(ROLE, otherAuthorized, { from: admin }); + await this.accessControl.revokeRole(ROLE, other, { from: admin }); + + const memberCount = await this.accessControl.getRoleMemberCount(ROLE); + expect(memberCount).to.bignumber.equal('2'); + + const bearers = []; + for (let i = 0; i < memberCount; ++i) { + bearers.push(await this.accessControl.getRoleMember(ROLE, i)); + } + + expect(bearers).to.have.members([authorized, otherAuthorized]); + }); + it('role enumeration should be in sync after renounceRole call', async function () { + expect(await this.accessControl.getRoleMemberCount(ROLE)).to.bignumber.equal('0'); + await this.accessControl.grantRole(ROLE, admin, { from: admin }); + expect(await this.accessControl.getRoleMemberCount(ROLE)).to.bignumber.equal('1'); + await this.accessControl.renounceRole(ROLE, admin, { from: admin }); + expect(await this.accessControl.getRoleMemberCount(ROLE)).to.bignumber.equal('0'); + }); + }); +} + +function shouldBehaveLikeAccessControlDefaultAdminRules(delay, defaultAdmin, newDefaultAdmin, other) { + shouldSupportInterfaces(['AccessControlDefaultAdminRules']); + + for (const getter of ['owner', 'defaultAdmin']) { + describe(`${getter}()`, function () { + it('has a default set to the initial default admin', async function () { + const value = await this.accessControl[getter](); + expect(value).to.equal(defaultAdmin); + expect(await this.accessControl.hasRole(DEFAULT_ADMIN_ROLE, value)).to.be.true; + }); + + it('changes if the default admin changes', async function () { + // Starts an admin transfer + await this.accessControl.beginDefaultAdminTransfer(newDefaultAdmin, { from: defaultAdmin }); + + // Wait for acceptance + const acceptSchedule = web3.utils.toBN(await time.latest()).add(delay); + await time.setNextBlockTimestamp(acceptSchedule.addn(1)); + await this.accessControl.acceptDefaultAdminTransfer({ from: newDefaultAdmin }); + + const value = await this.accessControl[getter](); + expect(value).to.equal(newDefaultAdmin); + }); + }); + } + + describe('pendingDefaultAdmin()', function () { + it('returns 0 if no pending default admin transfer', async function () { + const { newAdmin, schedule } = await this.accessControl.pendingDefaultAdmin(); + expect(newAdmin).to.eq(ZERO_ADDRESS); + expect(schedule).to.be.bignumber.eq(ZERO); + }); + + describe('when there is a scheduled default admin transfer', function () { + beforeEach('begins admin transfer', async function () { + await this.accessControl.beginDefaultAdminTransfer(newDefaultAdmin, { from: defaultAdmin }); + }); + + for (const [fromSchedule, tag] of [ + [-1, 'before'], + [0, 'exactly when'], + [1, 'after'], + ]) { + it(`returns pending admin and schedule ${tag} it passes if not accepted`, async function () { + // Wait until schedule + fromSchedule + const { schedule: firstSchedule } = await this.accessControl.pendingDefaultAdmin(); + await time.setNextBlockTimestamp(firstSchedule.toNumber() + fromSchedule); + await network.provider.send('evm_mine'); // Mine a block to force the timestamp + + const { newAdmin, schedule } = await this.accessControl.pendingDefaultAdmin(); + expect(newAdmin).to.eq(newDefaultAdmin); + expect(schedule).to.be.bignumber.eq(firstSchedule); + }); + } + + it('returns 0 after schedule passes and the transfer was accepted', async function () { + // Wait after schedule + const { schedule: firstSchedule } = await this.accessControl.pendingDefaultAdmin(); + await time.setNextBlockTimestamp(firstSchedule.addn(1)); + + // Accepts + await this.accessControl.acceptDefaultAdminTransfer({ from: newDefaultAdmin }); + + const { newAdmin, schedule } = await this.accessControl.pendingDefaultAdmin(); + expect(newAdmin).to.eq(ZERO_ADDRESS); + expect(schedule).to.be.bignumber.eq(ZERO); + }); + }); + }); + + describe('defaultAdminDelay()', function () { + it('returns the current delay', async function () { + expect(await this.accessControl.defaultAdminDelay()).to.be.bignumber.eq(delay); + }); + + describe('when there is a scheduled delay change', function () { + const newDelay = web3.utils.toBN(0xdead); // Any change + + beforeEach('begins delay change', async function () { + await this.accessControl.changeDefaultAdminDelay(newDelay, { from: defaultAdmin }); + }); + + for (const [fromSchedule, tag, expectedDelay, delayTag] of [ + [-1, 'before', delay, 'old'], + [0, 'exactly when', delay, 'old'], + [1, 'after', newDelay, 'new'], + ]) { + it(`returns ${delayTag} delay ${tag} delay schedule passes`, async function () { + // Wait until schedule + fromSchedule + const { schedule } = await this.accessControl.pendingDefaultAdminDelay(); + await time.setNextBlockTimestamp(schedule.toNumber() + fromSchedule); + await network.provider.send('evm_mine'); // Mine a block to force the timestamp + + const currentDelay = await this.accessControl.defaultAdminDelay(); + expect(currentDelay).to.be.bignumber.eq(expectedDelay); + }); + } + }); + }); + + describe('pendingDefaultAdminDelay()', function () { + it('returns 0 if not set', async function () { + const { newDelay, schedule } = await this.accessControl.pendingDefaultAdminDelay(); + expect(newDelay).to.be.bignumber.eq(ZERO); + expect(schedule).to.be.bignumber.eq(ZERO); + }); + + describe('when there is a scheduled delay change', function () { + const newDelay = web3.utils.toBN(0xdead); // Any change + + beforeEach('begins admin transfer', async function () { + await this.accessControl.changeDefaultAdminDelay(newDelay, { from: defaultAdmin }); + }); + + for (const [fromSchedule, tag, expectedDelay, delayTag, expectZeroSchedule] of [ + [-1, 'before', newDelay, 'new'], + [0, 'exactly when', newDelay, 'new'], + [1, 'after', ZERO, 'zero', true], + ]) { + it(`returns ${delayTag} delay ${tag} delay schedule passes`, async function () { + // Wait until schedule + fromSchedule + const { schedule: firstSchedule } = await this.accessControl.pendingDefaultAdminDelay(); + await time.setNextBlockTimestamp(firstSchedule.toNumber() + fromSchedule); + await network.provider.send('evm_mine'); // Mine a block to force the timestamp + + const { newDelay, schedule } = await this.accessControl.pendingDefaultAdminDelay(); + expect(newDelay).to.be.bignumber.eq(expectedDelay); + expect(schedule).to.be.bignumber.eq(expectZeroSchedule ? ZERO : firstSchedule); + }); + } + }); + }); + + describe('defaultAdminDelayIncreaseWait()', function () { + it('should return 5 days (default)', async function () { + expect(await this.accessControl.defaultAdminDelayIncreaseWait()).to.be.bignumber.eq( + web3.utils.toBN(time.duration.days(5)), + ); + }); + }); + + it('should revert if granting default admin role', async function () { + await expectRevertCustomError( + this.accessControl.grantRole(DEFAULT_ADMIN_ROLE, defaultAdmin, { from: defaultAdmin }), + 'AccessControlEnforcedDefaultAdminRules', + [], + ); + }); + + it('should revert if revoking default admin role', async function () { + await expectRevertCustomError( + this.accessControl.revokeRole(DEFAULT_ADMIN_ROLE, defaultAdmin, { from: defaultAdmin }), + 'AccessControlEnforcedDefaultAdminRules', + [], + ); + }); + + it("should revert if defaultAdmin's admin is changed", async function () { + await expectRevertCustomError( + this.accessControl.$_setRoleAdmin(DEFAULT_ADMIN_ROLE, OTHER_ROLE), + 'AccessControlEnforcedDefaultAdminRules', + [], + ); + }); + + it('should not grant the default admin role twice', async function () { + await expectRevertCustomError( + this.accessControl.$_grantRole(DEFAULT_ADMIN_ROLE, defaultAdmin), + 'AccessControlEnforcedDefaultAdminRules', + [], + ); + }); + + describe('begins a default admin transfer', function () { + let receipt; + let acceptSchedule; + + it('reverts if called by non default admin accounts', async function () { + await expectRevertCustomError( + this.accessControl.beginDefaultAdminTransfer(newDefaultAdmin, { from: other }), + 'AccessControlUnauthorizedAccount', + [other, DEFAULT_ADMIN_ROLE], + ); + }); + + describe('when there is no pending delay nor pending admin transfer', function () { + beforeEach('begins admin transfer', async function () { + receipt = await this.accessControl.beginDefaultAdminTransfer(newDefaultAdmin, { from: defaultAdmin }); + acceptSchedule = web3.utils.toBN(await time.latest()).add(delay); + }); + + it('should set pending default admin and schedule', async function () { + const { newAdmin, schedule } = await this.accessControl.pendingDefaultAdmin(); + expect(newAdmin).to.equal(newDefaultAdmin); + expect(schedule).to.be.bignumber.equal(acceptSchedule); + expectEvent(receipt, 'DefaultAdminTransferScheduled', { + newAdmin, + acceptSchedule, + }); + }); + }); + + describe('when there is a pending admin transfer', function () { + beforeEach('sets a pending default admin transfer', async function () { + await this.accessControl.beginDefaultAdminTransfer(newDefaultAdmin, { from: defaultAdmin }); + acceptSchedule = web3.utils.toBN(await time.latest()).add(delay); + }); + + for (const [fromSchedule, tag] of [ + [-1, 'before'], + [0, 'exactly when'], + [1, 'after'], + ]) { + it(`should be able to begin a transfer again ${tag} acceptSchedule passes`, async function () { + // Wait until schedule + fromSchedule + await time.setNextBlockTimestamp(acceptSchedule.toNumber() + fromSchedule); + + // defaultAdmin changes its mind and begin again to another address + const receipt = await this.accessControl.beginDefaultAdminTransfer(other, { from: defaultAdmin }); + const newSchedule = web3.utils.toBN(await time.latest()).add(delay); + const { newAdmin, schedule } = await this.accessControl.pendingDefaultAdmin(); + expect(newAdmin).to.equal(other); + expect(schedule).to.be.bignumber.equal(newSchedule); + + // Cancellation is always emitted since it was never accepted + expectEvent(receipt, 'DefaultAdminTransferCanceled'); + }); + } + + it('should not emit a cancellation event if the new default admin accepted', async function () { + // Wait until the acceptSchedule has passed + await time.setNextBlockTimestamp(acceptSchedule.addn(1)); + + // Accept and restart + await this.accessControl.acceptDefaultAdminTransfer({ from: newDefaultAdmin }); + const receipt = await this.accessControl.beginDefaultAdminTransfer(other, { from: newDefaultAdmin }); + + expectEvent.notEmitted(receipt, 'DefaultAdminTransferCanceled'); + }); + }); + + describe('when there is a pending delay', function () { + const newDelay = web3.utils.toBN(time.duration.hours(3)); + + beforeEach('schedule a delay change', async function () { + await this.accessControl.changeDefaultAdminDelay(newDelay, { from: defaultAdmin }); + const pendingDefaultAdminDelay = await this.accessControl.pendingDefaultAdminDelay(); + acceptSchedule = pendingDefaultAdminDelay.schedule; + }); + + for (const [fromSchedule, schedulePassed, expectedDelay, delayTag] of [ + [-1, 'before', delay, 'old'], + [0, 'exactly when', delay, 'old'], + [1, 'after', newDelay, 'new'], + ]) { + it(`should set the ${delayTag} delay and apply it to next default admin transfer schedule ${schedulePassed} acceptSchedule passed`, async function () { + // Wait until the expected fromSchedule time + await time.setNextBlockTimestamp(acceptSchedule.toNumber() + fromSchedule); + + // Start the new default admin transfer and get its schedule + const receipt = await this.accessControl.beginDefaultAdminTransfer(newDefaultAdmin, { from: defaultAdmin }); + const expectedAcceptSchedule = web3.utils.toBN(await time.latest()).add(expectedDelay); + + // Check that the schedule corresponds with the new delay + const { newAdmin, schedule: transferSchedule } = await this.accessControl.pendingDefaultAdmin(); + expect(newAdmin).to.equal(newDefaultAdmin); + expect(transferSchedule).to.be.bignumber.equal(expectedAcceptSchedule); + + expectEvent(receipt, 'DefaultAdminTransferScheduled', { + newAdmin, + acceptSchedule: expectedAcceptSchedule, + }); + }); + } + }); + }); + + describe('accepts transfer admin', function () { + let acceptSchedule; + + beforeEach(async function () { + await this.accessControl.beginDefaultAdminTransfer(newDefaultAdmin, { from: defaultAdmin }); + acceptSchedule = web3.utils.toBN(await time.latest()).add(delay); + }); + + it('should revert if caller is not pending default admin', async function () { + await time.setNextBlockTimestamp(acceptSchedule.addn(1)); + await expectRevertCustomError( + this.accessControl.acceptDefaultAdminTransfer({ from: other }), + 'AccessControlInvalidDefaultAdmin', + [other], + ); + }); + + describe('when caller is pending default admin and delay has passed', function () { + beforeEach(async function () { + await time.setNextBlockTimestamp(acceptSchedule.addn(1)); + }); + + it('accepts a transfer and changes default admin', async function () { + const receipt = await this.accessControl.acceptDefaultAdminTransfer({ from: newDefaultAdmin }); + + // Storage changes + expect(await this.accessControl.hasRole(DEFAULT_ADMIN_ROLE, defaultAdmin)).to.be.false; + expect(await this.accessControl.hasRole(DEFAULT_ADMIN_ROLE, newDefaultAdmin)).to.be.true; + expect(await this.accessControl.owner()).to.equal(newDefaultAdmin); + + // Emit events + expectEvent(receipt, 'RoleRevoked', { + role: DEFAULT_ADMIN_ROLE, + account: defaultAdmin, + }); + expectEvent(receipt, 'RoleGranted', { + role: DEFAULT_ADMIN_ROLE, + account: newDefaultAdmin, + }); + + // Resets pending default admin and schedule + const { newAdmin, schedule } = await this.accessControl.pendingDefaultAdmin(); + expect(newAdmin).to.equal(constants.ZERO_ADDRESS); + expect(schedule).to.be.bignumber.equal(ZERO); + }); + }); + + describe('schedule not passed', function () { + for (const [fromSchedule, tag] of [ + [-1, 'less'], + [0, 'equal'], + ]) { + it(`should revert if block.timestamp is ${tag} to schedule`, async function () { + await time.setNextBlockTimestamp(acceptSchedule.toNumber() + fromSchedule); + await expectRevertCustomError( + this.accessControl.acceptDefaultAdminTransfer({ from: newDefaultAdmin }), + 'AccessControlEnforcedDefaultAdminDelay', + [acceptSchedule], + ); + }); + } + }); + }); + + describe('cancels a default admin transfer', function () { + it('reverts if called by non default admin accounts', async function () { + await expectRevertCustomError( + this.accessControl.cancelDefaultAdminTransfer({ from: other }), + 'AccessControlUnauthorizedAccount', + [other, DEFAULT_ADMIN_ROLE], + ); + }); + + describe('when there is a pending default admin transfer', function () { + let acceptSchedule; + + beforeEach(async function () { + await this.accessControl.beginDefaultAdminTransfer(newDefaultAdmin, { from: defaultAdmin }); + acceptSchedule = web3.utils.toBN(await time.latest()).add(delay); + }); + + for (const [fromSchedule, tag] of [ + [-1, 'before'], + [0, 'exactly when'], + [1, 'after'], + ]) { + it(`resets pending default admin and schedule ${tag} transfer schedule passes`, async function () { + // Advance until passed delay + await time.setNextBlockTimestamp(acceptSchedule.toNumber() + fromSchedule); + + const receipt = await this.accessControl.cancelDefaultAdminTransfer({ from: defaultAdmin }); + + const { newAdmin, schedule } = await this.accessControl.pendingDefaultAdmin(); + expect(newAdmin).to.equal(constants.ZERO_ADDRESS); + expect(schedule).to.be.bignumber.equal(ZERO); + + expectEvent(receipt, 'DefaultAdminTransferCanceled'); + }); + } + + it('should revert if the previous default admin tries to accept', async function () { + await this.accessControl.cancelDefaultAdminTransfer({ from: defaultAdmin }); + + // Advance until passed delay + await time.setNextBlockTimestamp(acceptSchedule.addn(1)); + + // Previous pending default admin should not be able to accept after cancellation. + await expectRevertCustomError( + this.accessControl.acceptDefaultAdminTransfer({ from: newDefaultAdmin }), + 'AccessControlInvalidDefaultAdmin', + [newDefaultAdmin], + ); + }); + }); + + describe('when there is no pending default admin transfer', async function () { + it('should succeed without changes', async function () { + const receipt = await this.accessControl.cancelDefaultAdminTransfer({ from: defaultAdmin }); + + const { newAdmin, schedule } = await this.accessControl.pendingDefaultAdmin(); + expect(newAdmin).to.equal(constants.ZERO_ADDRESS); + expect(schedule).to.be.bignumber.equal(ZERO); + + expectEvent.notEmitted(receipt, 'DefaultAdminTransferCanceled'); + }); + }); + }); + + describe('renounces admin', function () { + let expectedSchedule; + let delayPassed; + let delayNotPassed; + + beforeEach(async function () { + await this.accessControl.beginDefaultAdminTransfer(constants.ZERO_ADDRESS, { from: defaultAdmin }); + expectedSchedule = web3.utils.toBN(await time.latest()).add(delay); + delayNotPassed = expectedSchedule; + delayPassed = expectedSchedule.addn(1); + }); + + it('reverts if caller is not default admin', async function () { + await time.setNextBlockTimestamp(delayPassed); + await expectRevertCustomError( + this.accessControl.renounceRole(DEFAULT_ADMIN_ROLE, other, { from: defaultAdmin }), + 'AccessControlBadConfirmation', + [], + ); + }); + + it("renouncing the admin role when not an admin doesn't affect the schedule", async function () { + await time.setNextBlockTimestamp(delayPassed); + await this.accessControl.renounceRole(DEFAULT_ADMIN_ROLE, other, { from: other }); + + const { newAdmin, schedule } = await this.accessControl.pendingDefaultAdmin(); + expect(newAdmin).to.equal(constants.ZERO_ADDRESS); + expect(schedule).to.be.bignumber.equal(expectedSchedule); + }); + + it('keeps defaultAdmin consistent with hasRole if another non-defaultAdmin user renounces the DEFAULT_ADMIN_ROLE', async function () { + await time.setNextBlockTimestamp(delayPassed); + + // This passes because it's a noop + await this.accessControl.renounceRole(DEFAULT_ADMIN_ROLE, other, { from: other }); + + expect(await this.accessControl.hasRole(DEFAULT_ADMIN_ROLE, defaultAdmin)).to.be.true; + expect(await this.accessControl.defaultAdmin()).to.be.equal(defaultAdmin); + }); + + it('renounces role', async function () { + await time.setNextBlockTimestamp(delayPassed); + const receipt = await this.accessControl.renounceRole(DEFAULT_ADMIN_ROLE, defaultAdmin, { from: defaultAdmin }); + + expect(await this.accessControl.hasRole(DEFAULT_ADMIN_ROLE, defaultAdmin)).to.be.false; + expect(await this.accessControl.defaultAdmin()).to.be.equal(constants.ZERO_ADDRESS); + expectEvent(receipt, 'RoleRevoked', { + role: DEFAULT_ADMIN_ROLE, + account: defaultAdmin, + }); + expect(await this.accessControl.owner()).to.equal(constants.ZERO_ADDRESS); + const { newAdmin, schedule } = await this.accessControl.pendingDefaultAdmin(); + expect(newAdmin).to.eq(ZERO_ADDRESS); + expect(schedule).to.be.bignumber.eq(ZERO); + }); + + it('allows to recover access using the internal _grantRole', async function () { + await time.setNextBlockTimestamp(delayPassed); + await this.accessControl.renounceRole(DEFAULT_ADMIN_ROLE, defaultAdmin, { from: defaultAdmin }); + + const grantRoleReceipt = await this.accessControl.$_grantRole(DEFAULT_ADMIN_ROLE, other); + expectEvent(grantRoleReceipt, 'RoleGranted', { + role: DEFAULT_ADMIN_ROLE, + account: other, + }); + }); + + describe('schedule not passed', function () { + for (const [fromSchedule, tag] of [ + [-1, 'less'], + [0, 'equal'], + ]) { + it(`reverts if block.timestamp is ${tag} to schedule`, async function () { + await time.setNextBlockTimestamp(delayNotPassed.toNumber() + fromSchedule); + await expectRevertCustomError( + this.accessControl.renounceRole(DEFAULT_ADMIN_ROLE, defaultAdmin, { from: defaultAdmin }), + 'AccessControlEnforcedDefaultAdminDelay', + [expectedSchedule], + ); + }); + } + }); + }); + + describe('changes delay', function () { + it('reverts if called by non default admin accounts', async function () { + await expectRevertCustomError( + this.accessControl.changeDefaultAdminDelay(time.duration.hours(4), { + from: other, + }), + 'AccessControlUnauthorizedAccount', + [other, DEFAULT_ADMIN_ROLE], + ); + }); + + for (const [newDefaultAdminDelay, delayChangeType] of [ + [web3.utils.toBN(delay).subn(time.duration.hours(1)), 'decreased'], + [web3.utils.toBN(delay).addn(time.duration.hours(1)), 'increased'], + [web3.utils.toBN(delay).addn(time.duration.days(5)), 'increased to more than 5 days'], + ]) { + describe(`when the delay is ${delayChangeType}`, function () { + it('begins the delay change to the new delay', async function () { + // Begins the change + const receipt = await this.accessControl.changeDefaultAdminDelay(newDefaultAdminDelay, { + from: defaultAdmin, + }); + + // Calculate expected values + const cap = await this.accessControl.defaultAdminDelayIncreaseWait(); + const changeDelay = newDefaultAdminDelay.lte(delay) + ? delay.sub(newDefaultAdminDelay) + : BN.min(newDefaultAdminDelay, cap); + const timestamp = web3.utils.toBN(await time.latest()); + const effectSchedule = timestamp.add(changeDelay); + + // Assert + const { newDelay, schedule } = await this.accessControl.pendingDefaultAdminDelay(); + expect(newDelay).to.be.bignumber.eq(newDefaultAdminDelay); + expect(schedule).to.be.bignumber.eq(effectSchedule); + expectEvent(receipt, 'DefaultAdminDelayChangeScheduled', { + newDelay, + effectSchedule, + }); + }); + + describe('scheduling again', function () { + beforeEach('schedule once', async function () { + await this.accessControl.changeDefaultAdminDelay(newDefaultAdminDelay, { from: defaultAdmin }); + }); + + for (const [fromSchedule, tag] of [ + [-1, 'before'], + [0, 'exactly when'], + [1, 'after'], + ]) { + const passed = fromSchedule > 0; + + it(`succeeds ${tag} the delay schedule passes`, async function () { + // Wait until schedule + fromSchedule + const { schedule: firstSchedule } = await this.accessControl.pendingDefaultAdminDelay(); + await time.setNextBlockTimestamp(firstSchedule.toNumber() + fromSchedule); + + // Default admin changes its mind and begins another delay change + const anotherNewDefaultAdminDelay = newDefaultAdminDelay.addn(time.duration.hours(2)); + const receipt = await this.accessControl.changeDefaultAdminDelay(anotherNewDefaultAdminDelay, { + from: defaultAdmin, + }); + + // Calculate expected values + const cap = await this.accessControl.defaultAdminDelayIncreaseWait(); + const timestamp = web3.utils.toBN(await time.latest()); + const effectSchedule = timestamp.add(BN.min(cap, anotherNewDefaultAdminDelay)); + + // Assert + const { newDelay, schedule } = await this.accessControl.pendingDefaultAdminDelay(); + expect(newDelay).to.be.bignumber.eq(anotherNewDefaultAdminDelay); + expect(schedule).to.be.bignumber.eq(effectSchedule); + expectEvent(receipt, 'DefaultAdminDelayChangeScheduled', { + newDelay, + effectSchedule, + }); + }); + + const emit = passed ? 'not emit' : 'emit'; + it(`should ${emit} a cancellation event ${tag} the delay schedule passes`, async function () { + // Wait until schedule + fromSchedule + const { schedule: firstSchedule } = await this.accessControl.pendingDefaultAdminDelay(); + await time.setNextBlockTimestamp(firstSchedule.toNumber() + fromSchedule); + + // Default admin changes its mind and begins another delay change + const anotherNewDefaultAdminDelay = newDefaultAdminDelay.addn(time.duration.hours(2)); + const receipt = await this.accessControl.changeDefaultAdminDelay(anotherNewDefaultAdminDelay, { + from: defaultAdmin, + }); + + const eventMatcher = passed ? expectEvent.notEmitted : expectEvent; + eventMatcher(receipt, 'DefaultAdminDelayChangeCanceled'); + }); + } + }); + }); + } + }); + + describe('rollbacks a delay change', function () { + it('reverts if called by non default admin accounts', async function () { + await expectRevertCustomError( + this.accessControl.rollbackDefaultAdminDelay({ from: other }), + 'AccessControlUnauthorizedAccount', + [other, DEFAULT_ADMIN_ROLE], + ); + }); + + describe('when there is a pending delay', function () { + beforeEach('set pending delay', async function () { + await this.accessControl.changeDefaultAdminDelay(time.duration.hours(12), { from: defaultAdmin }); + }); + + for (const [fromSchedule, tag] of [ + [-1, 'before'], + [0, 'exactly when'], + [1, 'after'], + ]) { + const passed = fromSchedule > 0; + + it(`resets pending delay and schedule ${tag} delay change schedule passes`, async function () { + // Wait until schedule + fromSchedule + const { schedule: firstSchedule } = await this.accessControl.pendingDefaultAdminDelay(); + await time.setNextBlockTimestamp(firstSchedule.toNumber() + fromSchedule); + + await this.accessControl.rollbackDefaultAdminDelay({ from: defaultAdmin }); + + const { newDelay, schedule } = await this.accessControl.pendingDefaultAdminDelay(); + expect(newDelay).to.be.bignumber.eq(ZERO); + expect(schedule).to.be.bignumber.eq(ZERO); + }); + + const emit = passed ? 'not emit' : 'emit'; + it(`should ${emit} a cancellation event ${tag} the delay schedule passes`, async function () { + // Wait until schedule + fromSchedule + const { schedule: firstSchedule } = await this.accessControl.pendingDefaultAdminDelay(); + await time.setNextBlockTimestamp(firstSchedule.toNumber() + fromSchedule); + + const receipt = await this.accessControl.rollbackDefaultAdminDelay({ from: defaultAdmin }); + + const eventMatcher = passed ? expectEvent.notEmitted : expectEvent; + eventMatcher(receipt, 'DefaultAdminDelayChangeCanceled'); + }); + } + }); + + describe('when there is no pending delay', function () { + it('succeeds without changes', async function () { + await this.accessControl.rollbackDefaultAdminDelay({ from: defaultAdmin }); + + const { newDelay, schedule } = await this.accessControl.pendingDefaultAdminDelay(); + expect(newDelay).to.be.bignumber.eq(ZERO); + expect(schedule).to.be.bignumber.eq(ZERO); + }); + }); + }); +} + +module.exports = { + DEFAULT_ADMIN_ROLE, + shouldBehaveLikeAccessControl, + shouldBehaveLikeAccessControlEnumerable, + shouldBehaveLikeAccessControlDefaultAdminRules, +}; diff --git a/test/access/AccessControl.test.js b/test/access/AccessControl.test.js new file mode 100644 index 000000000..14463b505 --- /dev/null +++ b/test/access/AccessControl.test.js @@ -0,0 +1,12 @@ +const { DEFAULT_ADMIN_ROLE, shouldBehaveLikeAccessControl } = require('./AccessControl.behavior.js'); + +const AccessControl = artifacts.require('$AccessControl'); + +contract('AccessControl', function (accounts) { + beforeEach(async function () { + this.accessControl = await AccessControl.new({ from: accounts[0] }); + await this.accessControl.$_grantRole(DEFAULT_ADMIN_ROLE, accounts[0]); + }); + + shouldBehaveLikeAccessControl(...accounts); +}); diff --git a/test/access/Ownable.test.js b/test/access/Ownable.test.js new file mode 100644 index 000000000..f85daec5d --- /dev/null +++ b/test/access/Ownable.test.js @@ -0,0 +1,72 @@ +const { constants, expectEvent } = require('@openzeppelin/test-helpers'); +const { expectRevertCustomError } = require('../helpers/customError'); + +const { ZERO_ADDRESS } = constants; + +const { expect } = require('chai'); + +const Ownable = artifacts.require('$Ownable'); + +contract('Ownable', function (accounts) { + const [owner, other] = accounts; + + beforeEach(async function () { + this.ownable = await Ownable.new(owner); + }); + + it('rejects zero address for initialOwner', async function () { + await expectRevertCustomError(Ownable.new(constants.ZERO_ADDRESS), 'OwnableInvalidOwner', [constants.ZERO_ADDRESS]); + }); + + it('has an owner', async function () { + expect(await this.ownable.owner()).to.equal(owner); + }); + + describe('transfer ownership', function () { + it('changes owner after transfer', async function () { + const receipt = await this.ownable.transferOwnership(other, { from: owner }); + expectEvent(receipt, 'OwnershipTransferred'); + + expect(await this.ownable.owner()).to.equal(other); + }); + + it('prevents non-owners from transferring', async function () { + await expectRevertCustomError( + this.ownable.transferOwnership(other, { from: other }), + 'OwnableUnauthorizedAccount', + [other], + ); + }); + + it('guards ownership against stuck state', async function () { + await expectRevertCustomError( + this.ownable.transferOwnership(ZERO_ADDRESS, { from: owner }), + 'OwnableInvalidOwner', + [ZERO_ADDRESS], + ); + }); + }); + + describe('renounce ownership', function () { + it('loses ownership after renouncement', async function () { + const receipt = await this.ownable.renounceOwnership({ from: owner }); + expectEvent(receipt, 'OwnershipTransferred'); + + expect(await this.ownable.owner()).to.equal(ZERO_ADDRESS); + }); + + it('prevents non-owners from renouncement', async function () { + await expectRevertCustomError(this.ownable.renounceOwnership({ from: other }), 'OwnableUnauthorizedAccount', [ + other, + ]); + }); + + it('allows to recover access using the internal _transferOwnership', async function () { + await this.ownable.renounceOwnership({ from: owner }); + const receipt = await this.ownable.$_transferOwnership(other); + expectEvent(receipt, 'OwnershipTransferred'); + + expect(await this.ownable.owner()).to.equal(other); + }); + }); +}); diff --git a/test/access/Ownable2Step.test.js b/test/access/Ownable2Step.test.js new file mode 100644 index 000000000..bdbac48fa --- /dev/null +++ b/test/access/Ownable2Step.test.js @@ -0,0 +1,70 @@ +const { constants, expectEvent } = require('@openzeppelin/test-helpers'); +const { ZERO_ADDRESS } = constants; +const { expect } = require('chai'); +const { expectRevertCustomError } = require('../helpers/customError'); + +const Ownable2Step = artifacts.require('$Ownable2Step'); + +contract('Ownable2Step', function (accounts) { + const [owner, accountA, accountB] = accounts; + + beforeEach(async function () { + this.ownable2Step = await Ownable2Step.new(owner); + }); + + describe('transfer ownership', function () { + it('starting a transfer does not change owner', async function () { + const receipt = await this.ownable2Step.transferOwnership(accountA, { from: owner }); + expectEvent(receipt, 'OwnershipTransferStarted', { previousOwner: owner, newOwner: accountA }); + expect(await this.ownable2Step.owner()).to.equal(owner); + expect(await this.ownable2Step.pendingOwner()).to.equal(accountA); + }); + + it('changes owner after transfer', async function () { + await this.ownable2Step.transferOwnership(accountA, { from: owner }); + const receipt = await this.ownable2Step.acceptOwnership({ from: accountA }); + expectEvent(receipt, 'OwnershipTransferred', { previousOwner: owner, newOwner: accountA }); + expect(await this.ownable2Step.owner()).to.equal(accountA); + expect(await this.ownable2Step.pendingOwner()).to.not.equal(accountA); + }); + + it('guards transfer against invalid user', async function () { + await this.ownable2Step.transferOwnership(accountA, { from: owner }); + await expectRevertCustomError( + this.ownable2Step.acceptOwnership({ from: accountB }), + 'OwnableUnauthorizedAccount', + [accountB], + ); + }); + }); + + describe('renouncing ownership', async function () { + it('changes owner after renouncing ownership', async function () { + await this.ownable2Step.renounceOwnership({ from: owner }); + // If renounceOwnership is removed from parent an alternative is needed ... + // without it is difficult to cleanly renounce with the two step process + // see: https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3620#discussion_r957930388 + expect(await this.ownable2Step.owner()).to.equal(ZERO_ADDRESS); + }); + + it('pending owner resets after renouncing ownership', async function () { + await this.ownable2Step.transferOwnership(accountA, { from: owner }); + expect(await this.ownable2Step.pendingOwner()).to.equal(accountA); + await this.ownable2Step.renounceOwnership({ from: owner }); + expect(await this.ownable2Step.pendingOwner()).to.equal(ZERO_ADDRESS); + await expectRevertCustomError( + this.ownable2Step.acceptOwnership({ from: accountA }), + 'OwnableUnauthorizedAccount', + [accountA], + ); + }); + + it('allows to recover access using the internal _transferOwnership', async function () { + await this.ownable2Step.renounceOwnership({ from: owner }); + const receipt = await this.ownable2Step.$_transferOwnership(accountA); + expectEvent(receipt, 'OwnershipTransferred'); + + expect(await this.ownable2Step.owner()).to.equal(accountA); + }); + }); +}); diff --git a/test/access/extensions/AccessControlDefaultAdminRules.test.js b/test/access/extensions/AccessControlDefaultAdminRules.test.js new file mode 100644 index 000000000..af34143f1 --- /dev/null +++ b/test/access/extensions/AccessControlDefaultAdminRules.test.js @@ -0,0 +1,26 @@ +const { time, constants, expectRevert } = require('@openzeppelin/test-helpers'); +const { + shouldBehaveLikeAccessControl, + shouldBehaveLikeAccessControlDefaultAdminRules, +} = require('../AccessControl.behavior.js'); + +const AccessControlDefaultAdminRules = artifacts.require('$AccessControlDefaultAdminRules'); + +contract('AccessControlDefaultAdminRules', function (accounts) { + const delay = web3.utils.toBN(time.duration.hours(10)); + + beforeEach(async function () { + this.accessControl = await AccessControlDefaultAdminRules.new(delay, accounts[0], { from: accounts[0] }); + }); + + it('initial admin not zero', async function () { + await expectRevert( + AccessControlDefaultAdminRules.new(delay, constants.ZERO_ADDRESS), + 'AccessControlInvalidDefaultAdmin', + [constants.ZERO_ADDRESS], + ); + }); + + shouldBehaveLikeAccessControl(...accounts); + shouldBehaveLikeAccessControlDefaultAdminRules(delay, ...accounts); +}); diff --git a/test/access/extensions/AccessControlEnumerable.test.js b/test/access/extensions/AccessControlEnumerable.test.js new file mode 100644 index 000000000..7dfb0bce8 --- /dev/null +++ b/test/access/extensions/AccessControlEnumerable.test.js @@ -0,0 +1,17 @@ +const { + DEFAULT_ADMIN_ROLE, + shouldBehaveLikeAccessControl, + shouldBehaveLikeAccessControlEnumerable, +} = require('../AccessControl.behavior.js'); + +const AccessControlEnumerable = artifacts.require('$AccessControlEnumerable'); + +contract('AccessControlEnumerable', function (accounts) { + beforeEach(async function () { + this.accessControl = await AccessControlEnumerable.new({ from: accounts[0] }); + await this.accessControl.$_grantRole(DEFAULT_ADMIN_ROLE, accounts[0]); + }); + + shouldBehaveLikeAccessControl(...accounts); + shouldBehaveLikeAccessControlEnumerable(...accounts); +}); diff --git a/test/access/manager/AccessManager.test.js b/test/access/manager/AccessManager.test.js new file mode 100644 index 000000000..1da7b3ced --- /dev/null +++ b/test/access/manager/AccessManager.test.js @@ -0,0 +1,1161 @@ +const { web3 } = require('hardhat'); +const { constants, expectEvent, time } = require('@openzeppelin/test-helpers'); +const { expectRevertCustomError } = require('../../helpers/customError'); +const { selector } = require('../../helpers/methods'); +const { clockFromReceipt } = require('../../helpers/time'); +const { product } = require('../../helpers/iterate'); +const helpers = require('@nomicfoundation/hardhat-network-helpers'); + +const AccessManager = artifacts.require('$AccessManager'); +const AccessManagedTarget = artifacts.require('$AccessManagedTarget'); +const Ownable = artifacts.require('$Ownable'); + +const MAX_UINT64 = web3.utils.toBN((2n ** 64n - 1n).toString()); + +const ROLES = { + ADMIN: web3.utils.toBN(0), + SOME_ADMIN: web3.utils.toBN(17), + SOME: web3.utils.toBN(42), + PUBLIC: MAX_UINT64, +}; +Object.assign(ROLES, Object.fromEntries(Object.entries(ROLES).map(([key, value]) => [value, key]))); + +const executeDelay = web3.utils.toBN(10); +const grantDelay = web3.utils.toBN(10); +const MINSETBACK = time.duration.days(5); + +const formatAccess = access => [access[0], access[1].toString()]; + +contract('AccessManager', function (accounts) { + const [admin, manager, member, user, other] = accounts; + + beforeEach(async function () { + this.manager = await AccessManager.new(admin); + + // add member to role + await this.manager.$_setRoleAdmin(ROLES.SOME, ROLES.SOME_ADMIN); + await this.manager.$_setRoleGuardian(ROLES.SOME, ROLES.SOME_ADMIN); + await this.manager.$_grantRole(ROLES.SOME_ADMIN, manager, 0, 0); + await this.manager.$_grantRole(ROLES.SOME, member, 0, 0); + }); + + it('rejects zero address for initialAdmin', async function () { + await expectRevertCustomError(AccessManager.new(constants.ZERO_ADDRESS), 'AccessManagerInvalidInitialAdmin', [ + constants.ZERO_ADDRESS, + ]); + }); + + it('default minsetback is 1 day', async function () { + expect(await this.manager.minSetback()).to.be.bignumber.equal(MINSETBACK); + }); + + it('roles are correctly initialized', async function () { + // role admin + expect(await this.manager.getRoleAdmin(ROLES.ADMIN)).to.be.bignumber.equal(ROLES.ADMIN); + expect(await this.manager.getRoleAdmin(ROLES.SOME_ADMIN)).to.be.bignumber.equal(ROLES.ADMIN); + expect(await this.manager.getRoleAdmin(ROLES.SOME)).to.be.bignumber.equal(ROLES.SOME_ADMIN); + expect(await this.manager.getRoleAdmin(ROLES.PUBLIC)).to.be.bignumber.equal(ROLES.ADMIN); + // role guardian + expect(await this.manager.getRoleGuardian(ROLES.ADMIN)).to.be.bignumber.equal(ROLES.ADMIN); + expect(await this.manager.getRoleGuardian(ROLES.SOME_ADMIN)).to.be.bignumber.equal(ROLES.ADMIN); + expect(await this.manager.getRoleGuardian(ROLES.SOME)).to.be.bignumber.equal(ROLES.SOME_ADMIN); + expect(await this.manager.getRoleGuardian(ROLES.PUBLIC)).to.be.bignumber.equal(ROLES.ADMIN); + // role members + expect(await this.manager.hasRole(ROLES.ADMIN, admin).then(formatAccess)).to.be.deep.equal([true, '0']); + expect(await this.manager.hasRole(ROLES.ADMIN, manager).then(formatAccess)).to.be.deep.equal([false, '0']); + expect(await this.manager.hasRole(ROLES.ADMIN, member).then(formatAccess)).to.be.deep.equal([false, '0']); + expect(await this.manager.hasRole(ROLES.ADMIN, user).then(formatAccess)).to.be.deep.equal([false, '0']); + expect(await this.manager.hasRole(ROLES.SOME_ADMIN, admin).then(formatAccess)).to.be.deep.equal([false, '0']); + expect(await this.manager.hasRole(ROLES.SOME_ADMIN, manager).then(formatAccess)).to.be.deep.equal([true, '0']); + expect(await this.manager.hasRole(ROLES.SOME_ADMIN, member).then(formatAccess)).to.be.deep.equal([false, '0']); + expect(await this.manager.hasRole(ROLES.SOME_ADMIN, user).then(formatAccess)).to.be.deep.equal([false, '0']); + expect(await this.manager.hasRole(ROLES.SOME, admin).then(formatAccess)).to.be.deep.equal([false, '0']); + expect(await this.manager.hasRole(ROLES.SOME, manager).then(formatAccess)).to.be.deep.equal([false, '0']); + expect(await this.manager.hasRole(ROLES.SOME, member).then(formatAccess)).to.be.deep.equal([true, '0']); + expect(await this.manager.hasRole(ROLES.SOME, user).then(formatAccess)).to.be.deep.equal([false, '0']); + expect(await this.manager.hasRole(ROLES.PUBLIC, admin).then(formatAccess)).to.be.deep.equal([true, '0']); + expect(await this.manager.hasRole(ROLES.PUBLIC, manager).then(formatAccess)).to.be.deep.equal([true, '0']); + expect(await this.manager.hasRole(ROLES.PUBLIC, member).then(formatAccess)).to.be.deep.equal([true, '0']); + expect(await this.manager.hasRole(ROLES.PUBLIC, user).then(formatAccess)).to.be.deep.equal([true, '0']); + }); + + describe('Roles management', function () { + describe('label role', function () { + it('admin can emit a label event', async function () { + expectEvent(await this.manager.labelRole(ROLES.SOME, 'Some label', { from: admin }), 'RoleLabel', { + roleId: ROLES.SOME, + label: 'Some label', + }); + }); + + it('admin can re-emit a label event', async function () { + await this.manager.labelRole(ROLES.SOME, 'Some label', { from: admin }); + + expectEvent(await this.manager.labelRole(ROLES.SOME, 'Updated label', { from: admin }), 'RoleLabel', { + roleId: ROLES.SOME, + label: 'Updated label', + }); + }); + + it('emitting a label is restricted', async function () { + await expectRevertCustomError( + this.manager.labelRole(ROLES.SOME, 'Invalid label', { from: other }), + 'AccessManagerUnauthorizedAccount', + [other, ROLES.ADMIN], + ); + }); + }); + + describe('grant role', function () { + describe('without a grant delay', function () { + it('without an execute delay', async function () { + expect(await this.manager.hasRole(ROLES.SOME, user).then(formatAccess)).to.be.deep.equal([false, '0']); + + const { receipt } = await this.manager.grantRole(ROLES.SOME, user, 0, { from: manager }); + const timestamp = await clockFromReceipt.timestamp(receipt).then(web3.utils.toBN); + expectEvent(receipt, 'RoleGranted', { + roleId: ROLES.SOME, + account: user, + since: timestamp, + delay: '0', + newMember: true, + }); + + expect(await this.manager.hasRole(ROLES.SOME, user).then(formatAccess)).to.be.deep.equal([true, '0']); + + const access = await this.manager.getAccess(ROLES.SOME, user); + expect(access[0]).to.be.bignumber.equal(timestamp); // inRoleSince + expect(access[1]).to.be.bignumber.equal('0'); // currentDelay + expect(access[2]).to.be.bignumber.equal('0'); // pendingDelay + expect(access[3]).to.be.bignumber.equal('0'); // effect + }); + + it('with an execute delay', async function () { + expect(await this.manager.hasRole(ROLES.SOME, user).then(formatAccess)).to.be.deep.equal([false, '0']); + + const { receipt } = await this.manager.grantRole(ROLES.SOME, user, executeDelay, { from: manager }); + const timestamp = await clockFromReceipt.timestamp(receipt).then(web3.utils.toBN); + expectEvent(receipt, 'RoleGranted', { + roleId: ROLES.SOME, + account: user, + since: timestamp, + delay: executeDelay, + newMember: true, + }); + + expect(await this.manager.hasRole(ROLES.SOME, user).then(formatAccess)).to.be.deep.equal([ + true, + executeDelay.toString(), + ]); + + const access = await this.manager.getAccess(ROLES.SOME, user); + expect(access[0]).to.be.bignumber.equal(timestamp); // inRoleSince + expect(access[1]).to.be.bignumber.equal(executeDelay); // currentDelay + expect(access[2]).to.be.bignumber.equal('0'); // pendingDelay + expect(access[3]).to.be.bignumber.equal('0'); // effect + }); + + it('to a user that is already in the role', async function () { + expect(await this.manager.hasRole(ROLES.SOME, member).then(formatAccess)).to.be.deep.equal([true, '0']); + await this.manager.grantRole(ROLES.SOME, member, 0, { from: manager }); + expect(await this.manager.hasRole(ROLES.SOME, member).then(formatAccess)).to.be.deep.equal([true, '0']); + }); + + it('to a user that is scheduled for joining the role', async function () { + await this.manager.$_grantRole(ROLES.SOME, user, 10, 0); // grant delay 10 + expect(await this.manager.hasRole(ROLES.SOME, user).then(formatAccess)).to.be.deep.equal([false, '0']); + await this.manager.grantRole(ROLES.SOME, user, 0, { from: manager }); + expect(await this.manager.hasRole(ROLES.SOME, user).then(formatAccess)).to.be.deep.equal([false, '0']); + }); + + it('grant role is restricted', async function () { + await expectRevertCustomError( + this.manager.grantRole(ROLES.SOME, user, 0, { from: other }), + 'AccessManagerUnauthorizedAccount', + [other, ROLES.SOME_ADMIN], + ); + }); + }); + + describe('with a grant delay', function () { + beforeEach(async function () { + await this.manager.$_setGrantDelay(ROLES.SOME, grantDelay); + await time.increase(MINSETBACK); + }); + + it('granted role is not active immediately', async function () { + const { receipt } = await this.manager.grantRole(ROLES.SOME, user, 0, { from: manager }); + const timestamp = await clockFromReceipt.timestamp(receipt).then(web3.utils.toBN); + expectEvent(receipt, 'RoleGranted', { + roleId: ROLES.SOME, + account: user, + since: timestamp.add(grantDelay), + delay: '0', + newMember: true, + }); + + expect(await this.manager.hasRole(ROLES.SOME, user).then(formatAccess)).to.be.deep.equal([false, '0']); + + const access = await this.manager.getAccess(ROLES.SOME, user); + expect(access[0]).to.be.bignumber.equal(timestamp.add(grantDelay)); // inRoleSince + expect(access[1]).to.be.bignumber.equal('0'); // currentDelay + expect(access[2]).to.be.bignumber.equal('0'); // pendingDelay + expect(access[3]).to.be.bignumber.equal('0'); // effect + }); + + it('granted role is active after the delay', async function () { + const { receipt } = await this.manager.grantRole(ROLES.SOME, user, 0, { from: manager }); + const timestamp = await clockFromReceipt.timestamp(receipt).then(web3.utils.toBN); + expectEvent(receipt, 'RoleGranted', { + roleId: ROLES.SOME, + account: user, + since: timestamp.add(grantDelay), + delay: '0', + newMember: true, + }); + + await time.increase(grantDelay); + + expect(await this.manager.hasRole(ROLES.SOME, user).then(formatAccess)).to.be.deep.equal([true, '0']); + + const access = await this.manager.getAccess(ROLES.SOME, user); + expect(access[0]).to.be.bignumber.equal(timestamp.add(grantDelay)); // inRoleSince + expect(access[1]).to.be.bignumber.equal('0'); // currentDelay + expect(access[2]).to.be.bignumber.equal('0'); // pendingDelay + expect(access[3]).to.be.bignumber.equal('0'); // effect + }); + }); + + it('cannot grant public role', async function () { + await expectRevertCustomError( + this.manager.$_grantRole(ROLES.PUBLIC, other, 0, executeDelay, { from: manager }), + 'AccessManagerLockedRole', + [ROLES.PUBLIC], + ); + }); + }); + + describe('revoke role', function () { + it('from a user that is already in the role', async function () { + expect(await this.manager.hasRole(ROLES.SOME, member).then(formatAccess)).to.be.deep.equal([true, '0']); + + const { receipt } = await this.manager.revokeRole(ROLES.SOME, member, { from: manager }); + expectEvent(receipt, 'RoleRevoked', { roleId: ROLES.SOME, account: member }); + + expect(await this.manager.hasRole(ROLES.SOME, member).then(formatAccess)).to.be.deep.equal([false, '0']); + + const access = await this.manager.getAccess(ROLES.SOME, user); + expect(access[0]).to.be.bignumber.equal('0'); // inRoleSince + expect(access[1]).to.be.bignumber.equal('0'); // currentDelay + expect(access[2]).to.be.bignumber.equal('0'); // pendingDelay + expect(access[3]).to.be.bignumber.equal('0'); // effect + }); + + it('from a user that is scheduled for joining the role', async function () { + await this.manager.$_grantRole(ROLES.SOME, user, 10, 0); // grant delay 10 + + expect(await this.manager.hasRole(ROLES.SOME, user).then(formatAccess)).to.be.deep.equal([false, '0']); + + const { receipt } = await this.manager.revokeRole(ROLES.SOME, user, { from: manager }); + expectEvent(receipt, 'RoleRevoked', { roleId: ROLES.SOME, account: user }); + + expect(await this.manager.hasRole(ROLES.SOME, user).then(formatAccess)).to.be.deep.equal([false, '0']); + + const access = await this.manager.getAccess(ROLES.SOME, user); + expect(access[0]).to.be.bignumber.equal('0'); // inRoleSince + expect(access[1]).to.be.bignumber.equal('0'); // currentDelay + expect(access[2]).to.be.bignumber.equal('0'); // pendingDelay + expect(access[3]).to.be.bignumber.equal('0'); // effect + }); + + it('from a user that is not in the role', async function () { + expect(await this.manager.hasRole(ROLES.SOME, user).then(formatAccess)).to.be.deep.equal([false, '0']); + await this.manager.revokeRole(ROLES.SOME, user, { from: manager }); + expect(await this.manager.hasRole(ROLES.SOME, user).then(formatAccess)).to.be.deep.equal([false, '0']); + }); + + it('revoke role is restricted', async function () { + await expectRevertCustomError( + this.manager.revokeRole(ROLES.SOME, member, { from: other }), + 'AccessManagerUnauthorizedAccount', + [other, ROLES.SOME_ADMIN], + ); + }); + }); + + describe('renounce role', function () { + it('for a user that is already in the role', async function () { + expect(await this.manager.hasRole(ROLES.SOME, member).then(formatAccess)).to.be.deep.equal([true, '0']); + + const { receipt } = await this.manager.renounceRole(ROLES.SOME, member, { from: member }); + expectEvent(receipt, 'RoleRevoked', { roleId: ROLES.SOME, account: member }); + + expect(await this.manager.hasRole(ROLES.SOME, member).then(formatAccess)).to.be.deep.equal([false, '0']); + + const access = await this.manager.getAccess(ROLES.SOME, member); + expect(access[0]).to.be.bignumber.equal('0'); // inRoleSince + expect(access[1]).to.be.bignumber.equal('0'); // currentDelay + expect(access[2]).to.be.bignumber.equal('0'); // pendingDelay + expect(access[3]).to.be.bignumber.equal('0'); // effect + }); + + it('for a user that is schedule for joining the role', async function () { + await this.manager.$_grantRole(ROLES.SOME, user, 10, 0); // grant delay 10 + + expect(await this.manager.hasRole(ROLES.SOME, user).then(formatAccess)).to.be.deep.equal([false, '0']); + + const { receipt } = await this.manager.renounceRole(ROLES.SOME, user, { from: user }); + expectEvent(receipt, 'RoleRevoked', { roleId: ROLES.SOME, account: user }); + + expect(await this.manager.hasRole(ROLES.SOME, user).then(formatAccess)).to.be.deep.equal([false, '0']); + + const access = await this.manager.getAccess(ROLES.SOME, user); + expect(access[0]).to.be.bignumber.equal('0'); // inRoleSince + expect(access[1]).to.be.bignumber.equal('0'); // currentDelay + expect(access[2]).to.be.bignumber.equal('0'); // pendingDelay + expect(access[3]).to.be.bignumber.equal('0'); // effect + }); + + it('for a user that is not in the role', async function () { + await this.manager.renounceRole(ROLES.SOME, user, { from: user }); + }); + + it('bad user confirmation', async function () { + await expectRevertCustomError( + this.manager.renounceRole(ROLES.SOME, member, { from: user }), + 'AccessManagerBadConfirmation', + [], + ); + }); + }); + + describe('change role admin', function () { + it("admin can set any role's admin", async function () { + expect(await this.manager.getRoleAdmin(ROLES.SOME)).to.be.bignumber.equal(ROLES.SOME_ADMIN); + + const { receipt } = await this.manager.setRoleAdmin(ROLES.SOME, ROLES.ADMIN, { from: admin }); + expectEvent(receipt, 'RoleAdminChanged', { roleId: ROLES.SOME, admin: ROLES.ADMIN }); + + expect(await this.manager.getRoleAdmin(ROLES.SOME)).to.be.bignumber.equal(ROLES.ADMIN); + }); + + it("setting a role's admin is restricted", async function () { + await expectRevertCustomError( + this.manager.setRoleAdmin(ROLES.SOME, ROLES.SOME, { from: manager }), + 'AccessManagerUnauthorizedAccount', + [manager, ROLES.ADMIN], + ); + }); + }); + + describe('change role guardian', function () { + it("admin can set any role's admin", async function () { + expect(await this.manager.getRoleGuardian(ROLES.SOME)).to.be.bignumber.equal(ROLES.SOME_ADMIN); + + const { receipt } = await this.manager.setRoleGuardian(ROLES.SOME, ROLES.ADMIN, { from: admin }); + expectEvent(receipt, 'RoleGuardianChanged', { roleId: ROLES.SOME, guardian: ROLES.ADMIN }); + + expect(await this.manager.getRoleGuardian(ROLES.SOME)).to.be.bignumber.equal(ROLES.ADMIN); + }); + + it("setting a role's admin is restricted", async function () { + await expectRevertCustomError( + this.manager.setRoleGuardian(ROLES.SOME, ROLES.SOME, { from: other }), + 'AccessManagerUnauthorizedAccount', + [other, ROLES.ADMIN], + ); + }); + }); + + describe('change execution delay', function () { + it('increasing the delay has immediate effect', async function () { + const oldDelay = web3.utils.toBN(10); + const newDelay = web3.utils.toBN(100); + + // role is already granted (with no delay) in the initial setup. this update takes time. + await this.manager.$_grantRole(ROLES.SOME, member, 0, oldDelay); + + const accessBefore = await this.manager.getAccess(ROLES.SOME, member); + expect(accessBefore[1]).to.be.bignumber.equal(oldDelay); // currentDelay + expect(accessBefore[2]).to.be.bignumber.equal('0'); // pendingDelay + expect(accessBefore[3]).to.be.bignumber.equal('0'); // effect + + const { receipt } = await this.manager.grantRole(ROLES.SOME, member, newDelay, { + from: manager, + }); + const timestamp = await clockFromReceipt.timestamp(receipt).then(web3.utils.toBN); + + expectEvent(receipt, 'RoleGranted', { + roleId: ROLES.SOME, + account: member, + since: timestamp, + delay: newDelay, + newMember: false, + }); + + // immediate effect + const accessAfter = await this.manager.getAccess(ROLES.SOME, member); + expect(accessAfter[1]).to.be.bignumber.equal(newDelay); // currentDelay + expect(accessAfter[2]).to.be.bignumber.equal('0'); // pendingDelay + expect(accessAfter[3]).to.be.bignumber.equal('0'); // effect + }); + + it('decreasing the delay takes time', async function () { + const oldDelay = web3.utils.toBN(100); + const newDelay = web3.utils.toBN(10); + + // role is already granted (with no delay) in the initial setup. this update takes time. + await this.manager.$_grantRole(ROLES.SOME, member, 0, oldDelay); + + const accessBefore = await this.manager.getAccess(ROLES.SOME, member); + expect(accessBefore[1]).to.be.bignumber.equal(oldDelay); // currentDelay + expect(accessBefore[2]).to.be.bignumber.equal('0'); // pendingDelay + expect(accessBefore[3]).to.be.bignumber.equal('0'); // effect + + const { receipt } = await this.manager.grantRole(ROLES.SOME, member, newDelay, { + from: manager, + }); + const timestamp = await clockFromReceipt.timestamp(receipt).then(web3.utils.toBN); + const setback = oldDelay.sub(newDelay); + + expectEvent(receipt, 'RoleGranted', { + roleId: ROLES.SOME, + account: member, + since: timestamp.add(setback), + delay: newDelay, + newMember: false, + }); + + // no immediate effect + const accessAfter = await this.manager.getAccess(ROLES.SOME, member); + expect(accessAfter[1]).to.be.bignumber.equal(oldDelay); // currentDelay + expect(accessAfter[2]).to.be.bignumber.equal(newDelay); // pendingDelay + expect(accessAfter[3]).to.be.bignumber.equal(timestamp.add(setback)); // effect + + // delayed effect + await time.increase(setback); + const accessAfterSetback = await this.manager.getAccess(ROLES.SOME, member); + expect(accessAfterSetback[1]).to.be.bignumber.equal(newDelay); // currentDelay + expect(accessAfterSetback[2]).to.be.bignumber.equal('0'); // pendingDelay + expect(accessAfterSetback[3]).to.be.bignumber.equal('0'); // effect + }); + + it('can set a user execution delay during the grant delay', async function () { + await this.manager.$_grantRole(ROLES.SOME, other, 10, 0); + // here: "other" is pending to get the role, but doesn't yet have it. + + const { receipt } = await this.manager.grantRole(ROLES.SOME, other, executeDelay, { from: manager }); + const timestamp = await clockFromReceipt.timestamp(receipt).then(web3.utils.toBN); + + // increasing the execution delay from 0 to executeDelay is immediate + expectEvent(receipt, 'RoleGranted', { + roleId: ROLES.SOME, + account: other, + since: timestamp, + delay: executeDelay, + newMember: false, + }); + }); + }); + + describe('change grant delay', function () { + it('increasing the delay has immediate effect', async function () { + const oldDelay = web3.utils.toBN(10); + const newDelay = web3.utils.toBN(100); + + await this.manager.$_setGrantDelay(ROLES.SOME, oldDelay); + await time.increase(MINSETBACK); + + expect(await this.manager.getRoleGrantDelay(ROLES.SOME)).to.be.bignumber.equal(oldDelay); + + const { receipt } = await this.manager.setGrantDelay(ROLES.SOME, newDelay, { from: admin }); + const timestamp = await clockFromReceipt.timestamp(receipt).then(web3.utils.toBN); + const setback = web3.utils.BN.max(MINSETBACK, oldDelay.sub(newDelay)); + + expect(setback).to.be.bignumber.equal(MINSETBACK); + expectEvent(receipt, 'RoleGrantDelayChanged', { + roleId: ROLES.SOME, + delay: newDelay, + since: timestamp.add(setback), + }); + + expect(await this.manager.getRoleGrantDelay(ROLES.SOME)).to.be.bignumber.equal(oldDelay); + await time.increase(setback); + expect(await this.manager.getRoleGrantDelay(ROLES.SOME)).to.be.bignumber.equal(newDelay); + }); + + it('increasing the delay has delay effect #1', async function () { + const oldDelay = web3.utils.toBN(100); + const newDelay = web3.utils.toBN(10); + + await this.manager.$_setGrantDelay(ROLES.SOME, oldDelay); + await time.increase(MINSETBACK); + + expect(await this.manager.getRoleGrantDelay(ROLES.SOME)).to.be.bignumber.equal(oldDelay); + + const { receipt } = await this.manager.setGrantDelay(ROLES.SOME, newDelay, { from: admin }); + const timestamp = await clockFromReceipt.timestamp(receipt).then(web3.utils.toBN); + const setback = web3.utils.BN.max(MINSETBACK, oldDelay.sub(newDelay)); + + expect(setback).to.be.bignumber.equal(MINSETBACK); + expectEvent(receipt, 'RoleGrantDelayChanged', { + roleId: ROLES.SOME, + delay: newDelay, + since: timestamp.add(setback), + }); + + expect(await this.manager.getRoleGrantDelay(ROLES.SOME)).to.be.bignumber.equal(oldDelay); + await time.increase(setback); + expect(await this.manager.getRoleGrantDelay(ROLES.SOME)).to.be.bignumber.equal(newDelay); + }); + + it('increasing the delay has delay effect #2', async function () { + const oldDelay = time.duration.days(30); // more than the minsetback + const newDelay = web3.utils.toBN(10); + + await this.manager.$_setGrantDelay(ROLES.SOME, oldDelay); + await time.increase(MINSETBACK); + + expect(await this.manager.getRoleGrantDelay(ROLES.SOME)).to.be.bignumber.equal(oldDelay); + + const { receipt } = await this.manager.setGrantDelay(ROLES.SOME, newDelay, { from: admin }); + const timestamp = await clockFromReceipt.timestamp(receipt).then(web3.utils.toBN); + const setback = web3.utils.BN.max(MINSETBACK, oldDelay.sub(newDelay)); + + expect(setback).to.be.bignumber.gt(MINSETBACK); + expectEvent(receipt, 'RoleGrantDelayChanged', { + roleId: ROLES.SOME, + delay: newDelay, + since: timestamp.add(setback), + }); + + expect(await this.manager.getRoleGrantDelay(ROLES.SOME)).to.be.bignumber.equal(oldDelay); + await time.increase(setback); + expect(await this.manager.getRoleGrantDelay(ROLES.SOME)).to.be.bignumber.equal(newDelay); + }); + + it('changing the grant delay is restricted', async function () { + await expectRevertCustomError( + this.manager.setGrantDelay(ROLES.SOME, grantDelay, { from: other }), + 'AccessManagerUnauthorizedAccount', + [ROLES.ADMIN, other], + ); + }); + }); + }); + + describe('with AccessManaged target contract', function () { + beforeEach('deploy target contract', async function () { + this.target = await AccessManagedTarget.new(this.manager.address); + // helpers for indirect calls + this.callData = selector('fnRestricted()'); + this.call = [this.target.address, this.callData]; + this.opId = web3.utils.keccak256( + web3.eth.abi.encodeParameters(['address', 'address', 'bytes'], [user, ...this.call]), + ); + this.direct = (opts = {}) => this.target.fnRestricted({ from: user, ...opts }); + this.schedule = (opts = {}) => this.manager.schedule(...this.call, 0, { from: user, ...opts }); + this.execute = (opts = {}) => this.manager.execute(...this.call, { from: user, ...opts }); + this.cancel = (opts = {}) => this.manager.cancel(user, ...this.call, { from: user, ...opts }); + }); + + describe('Change function permissions', function () { + const sigs = ['someFunction()', 'someOtherFunction(uint256)', 'oneMoreFunction(address,uint8)'].map(selector); + + it('admin can set function role', async function () { + for (const sig of sigs) { + expect(await this.manager.getTargetFunctionRole(this.target.address, sig)).to.be.bignumber.equal(ROLES.ADMIN); + } + + const { receipt: receipt1 } = await this.manager.setTargetFunctionRole(this.target.address, sigs, ROLES.SOME, { + from: admin, + }); + + for (const sig of sigs) { + expectEvent(receipt1, 'TargetFunctionRoleUpdated', { + target: this.target.address, + selector: sig, + roleId: ROLES.SOME, + }); + expect(await this.manager.getTargetFunctionRole(this.target.address, sig)).to.be.bignumber.equal(ROLES.SOME); + } + + const { receipt: receipt2 } = await this.manager.setTargetFunctionRole( + this.target.address, + [sigs[1]], + ROLES.SOME_ADMIN, + { + from: admin, + }, + ); + expectEvent(receipt2, 'TargetFunctionRoleUpdated', { + target: this.target.address, + selector: sigs[1], + roleId: ROLES.SOME_ADMIN, + }); + + for (const sig of sigs) { + expect(await this.manager.getTargetFunctionRole(this.target.address, sig)).to.be.bignumber.equal( + sig == sigs[1] ? ROLES.SOME_ADMIN : ROLES.SOME, + ); + } + }); + + it('non-admin cannot set function role', async function () { + await expectRevertCustomError( + this.manager.setTargetFunctionRole(this.target.address, sigs, ROLES.SOME, { from: other }), + 'AccessManagerUnauthorizedAccount', + [other, ROLES.ADMIN], + ); + }); + }); + + // WIP + describe('Calling restricted & unrestricted functions', function () { + for (const [callerRoles, fnRole, closed, delay] of product( + [[], [ROLES.SOME]], + [undefined, ROLES.ADMIN, ROLES.SOME, ROLES.PUBLIC], + [false, true], + [null, executeDelay], + )) { + // can we call with a delay ? + const indirectSuccess = (fnRole == ROLES.PUBLIC || callerRoles.includes(fnRole)) && !closed; + + // can we call without a delay ? + const directSuccess = (fnRole == ROLES.PUBLIC || (callerRoles.includes(fnRole) && !delay)) && !closed; + + const description = [ + 'Caller in roles', + '[' + (callerRoles ?? []).map(roleId => ROLES[roleId]).join(', ') + ']', + delay ? 'with a delay' : 'without a delay', + '+', + 'functions open to roles', + '[' + (ROLES[fnRole] ?? '') + ']', + closed ? `(closed)` : '', + ].join(' '); + + describe(description, function () { + beforeEach(async function () { + // setup + await Promise.all([ + this.manager.$_setTargetClosed(this.target.address, closed), + fnRole && this.manager.$_setTargetFunctionRole(this.target.address, selector('fnRestricted()'), fnRole), + fnRole && this.manager.$_setTargetFunctionRole(this.target.address, selector('fnUnrestricted()'), fnRole), + ...callerRoles + .filter(roleId => roleId != ROLES.PUBLIC) + .map(roleId => this.manager.$_grantRole(roleId, user, 0, delay ?? 0)), + ]); + + // post setup checks + expect(await this.manager.isTargetClosed(this.target.address)).to.be.equal(closed); + + if (fnRole) { + expect( + await this.manager.getTargetFunctionRole(this.target.address, selector('fnRestricted()')), + ).to.be.bignumber.equal(fnRole); + expect( + await this.manager.getTargetFunctionRole(this.target.address, selector('fnUnrestricted()')), + ).to.be.bignumber.equal(fnRole); + } + + for (const roleId of callerRoles) { + const access = await this.manager.getAccess(roleId, user); + if (roleId == ROLES.PUBLIC) { + expect(access[0]).to.be.bignumber.equal('0'); // inRoleSince + expect(access[1]).to.be.bignumber.equal('0'); // currentDelay + expect(access[2]).to.be.bignumber.equal('0'); // pendingDelay + expect(access[3]).to.be.bignumber.equal('0'); // effect + } else { + expect(access[0]).to.be.bignumber.gt('0'); // inRoleSince + expect(access[1]).to.be.bignumber.eq(String(delay ?? 0)); // currentDelay + expect(access[2]).to.be.bignumber.equal('0'); // pendingDelay + expect(access[3]).to.be.bignumber.equal('0'); // effect + } + } + }); + + it('canCall', async function () { + const result = await this.manager.canCall(user, this.target.address, selector('fnRestricted()')); + expect(result[0]).to.be.equal(directSuccess); + expect(result[1]).to.be.bignumber.equal(!directSuccess && indirectSuccess ? delay ?? '0' : '0'); + }); + + it('Calling a non restricted function never revert', async function () { + expectEvent(await this.target.fnUnrestricted({ from: user }), 'CalledUnrestricted', { + caller: user, + }); + }); + + it(`Calling a restricted function directly should ${ + directSuccess ? 'succeed' : 'revert' + }`, async function () { + const promise = this.direct(); + + if (directSuccess) { + expectEvent(await promise, 'CalledRestricted', { caller: user }); + } else if (indirectSuccess) { + await expectRevertCustomError(promise, 'AccessManagerNotScheduled', [this.opId]); + } else { + await expectRevertCustomError(promise, 'AccessManagedUnauthorized', [user]); + } + }); + + it('Calling indirectly: only execute', async function () { + // execute without schedule + if (directSuccess) { + const nonceBefore = await this.manager.getNonce(this.opId); + const { receipt, tx } = await this.execute(); + + expectEvent.notEmitted(receipt, 'OperationExecuted', { operationId: this.opId }); + await expectEvent.inTransaction(tx, this.target, 'CalledRestricted', { caller: this.manager.address }); + + // nonce is not modified + expect(await this.manager.getNonce(this.opId)).to.be.bignumber.equal(nonceBefore); + } else if (indirectSuccess) { + await expectRevertCustomError(this.execute(), 'AccessManagerNotScheduled', [this.opId]); + } else { + await expectRevertCustomError(this.execute(), 'AccessManagerUnauthorizedCall', [user, ...this.call]); + } + }); + + it('Calling indirectly: schedule and execute', async function () { + if (directSuccess || indirectSuccess) { + const nonceBefore = await this.manager.getNonce(this.opId); + const { receipt } = await this.schedule(); + const timestamp = await clockFromReceipt.timestamp(receipt).then(web3.utils.toBN); + + expectEvent(receipt, 'OperationScheduled', { + operationId: this.opId, + caller: user, + target: this.call[0], + data: this.call[1], + }); + + // if can call directly, delay should be 0. Otherwise, the delay should be applied + expect(await this.manager.getSchedule(this.opId)).to.be.bignumber.equal( + timestamp.add(directSuccess ? web3.utils.toBN(0) : delay), + ); + + // nonce is incremented + expect(await this.manager.getNonce(this.opId)).to.be.bignumber.equal(nonceBefore.addn(1)); + + // execute without wait + if (directSuccess) { + const { receipt, tx } = await this.execute(); + + await expectEvent.inTransaction(tx, this.target, 'CalledRestricted', { caller: this.manager.address }); + if (delay && fnRole !== ROLES.PUBLIC) { + expectEvent(receipt, 'OperationExecuted', { operationId: this.opId }); + expect(await this.manager.getSchedule(this.opId)).to.be.bignumber.equal('0'); + } + + // nonce is not modified by execute + expect(await this.manager.getNonce(this.opId)).to.be.bignumber.equal(nonceBefore.addn(1)); + } else if (indirectSuccess) { + await expectRevertCustomError(this.execute(), 'AccessManagerNotReady', [this.opId]); + } else { + await expectRevertCustomError(this.execute(), 'AccessManagerUnauthorizedCall', [user, ...this.call]); + } + } else { + await expectRevertCustomError(this.schedule(), 'AccessManagerUnauthorizedCall', [user, ...this.call]); + } + }); + + it('Calling indirectly: schedule wait and execute', async function () { + if (directSuccess || indirectSuccess) { + const nonceBefore = await this.manager.getNonce(this.opId); + const { receipt } = await this.schedule(); + const timestamp = await clockFromReceipt.timestamp(receipt).then(web3.utils.toBN); + + expectEvent(receipt, 'OperationScheduled', { + operationId: this.opId, + caller: user, + target: this.call[0], + data: this.call[1], + }); + + // if can call directly, delay should be 0. Otherwise, the delay should be applied + expect(await this.manager.getSchedule(this.opId)).to.be.bignumber.equal( + timestamp.add(directSuccess ? web3.utils.toBN(0) : delay), + ); + + // nonce is incremented + expect(await this.manager.getNonce(this.opId)).to.be.bignumber.equal(nonceBefore.addn(1)); + + // wait + await time.increase(delay ?? 0); + + // execute without wait + if (directSuccess || indirectSuccess) { + const { receipt, tx } = await this.execute(); + + await expectEvent.inTransaction(tx, this.target, 'CalledRestricted', { caller: this.manager.address }); + if (delay && fnRole !== ROLES.PUBLIC) { + expectEvent(receipt, 'OperationExecuted', { operationId: this.opId }); + expect(await this.manager.getSchedule(this.opId)).to.be.bignumber.equal('0'); + } + + // nonce is not modified by execute + expect(await this.manager.getNonce(this.opId)).to.be.bignumber.equal(nonceBefore.addn(1)); + } else { + await expectRevertCustomError(this.execute(), 'AccessManagerUnauthorizedCall', [user, ...this.call]); + } + } else { + await expectRevertCustomError(this.schedule(), 'AccessManagerUnauthorizedCall', [user, ...this.call]); + } + }); + + it('Calling directly: schedule and call', async function () { + if (directSuccess || indirectSuccess) { + const nonceBefore = await this.manager.getNonce(this.opId); + const { receipt } = await this.schedule(); + const timestamp = await clockFromReceipt.timestamp(receipt).then(web3.utils.toBN); + + expectEvent(receipt, 'OperationScheduled', { + operationId: this.opId, + caller: user, + target: this.call[0], + data: this.call[1], + }); + + // if can call directly, delay should be 0. Otherwise, the delay should be applied + const schedule = timestamp.add(directSuccess ? web3.utils.toBN(0) : delay); + expect(await this.manager.getSchedule(this.opId)).to.be.bignumber.equal(schedule); + + // nonce is incremented + expect(await this.manager.getNonce(this.opId)).to.be.bignumber.equal(nonceBefore.addn(1)); + + // execute without wait + const promise = this.direct(); + if (directSuccess) { + expectEvent(await promise, 'CalledRestricted', { caller: user }); + + // schedule is not reset + expect(await this.manager.getSchedule(this.opId)).to.be.bignumber.equal(schedule); + + // nonce is not modified by execute + expect(await this.manager.getNonce(this.opId)).to.be.bignumber.equal(nonceBefore.addn(1)); + } else if (indirectSuccess) { + await expectRevertCustomError(promise, 'AccessManagerNotReady', [this.opId]); + } else { + await expectRevertCustomError(promise, 'AccessManagerUnauthorizedCall', [user, ...this.call]); + } + } else { + await expectRevertCustomError(this.schedule(), 'AccessManagerUnauthorizedCall', [user, ...this.call]); + } + }); + + it('Calling directly: schedule wait and call', async function () { + if (directSuccess || indirectSuccess) { + const nonceBefore = await this.manager.getNonce(this.opId); + const { receipt } = await this.schedule(); + const timestamp = await clockFromReceipt.timestamp(receipt).then(web3.utils.toBN); + + expectEvent(receipt, 'OperationScheduled', { + operationId: this.opId, + caller: user, + target: this.call[0], + data: this.call[1], + }); + + // if can call directly, delay should be 0. Otherwise, the delay should be applied + const schedule = timestamp.add(directSuccess ? web3.utils.toBN(0) : delay); + expect(await this.manager.getSchedule(this.opId)).to.be.bignumber.equal(schedule); + + // nonce is incremented + expect(await this.manager.getNonce(this.opId)).to.be.bignumber.equal(nonceBefore.addn(1)); + + // wait + await time.increase(delay ?? 0); + + // execute without wait + const promise = await this.direct(); + if (directSuccess) { + expectEvent(await promise, 'CalledRestricted', { caller: user }); + + // schedule is not reset + expect(await this.manager.getSchedule(this.opId)).to.be.bignumber.equal(schedule); + + // nonce is not modified by execute + expect(await this.manager.getNonce(this.opId)).to.be.bignumber.equal(nonceBefore.addn(1)); + } else if (indirectSuccess) { + const receipt = await promise; + + expectEvent(receipt, 'CalledRestricted', { caller: user }); + await expectEvent.inTransaction(receipt.tx, this.manager, 'OperationExecuted', { + operationId: this.opId, + }); + + // schedule is reset + expect(await this.manager.getSchedule(this.opId)).to.be.bignumber.equal('0'); + + // nonce is not modified by execute + expect(await this.manager.getNonce(this.opId)).to.be.bignumber.equal(nonceBefore.addn(1)); + } else { + await expectRevertCustomError(this.direct(), 'AccessManagerUnauthorizedCall', [user, ...this.call]); + } + } else { + await expectRevertCustomError(this.schedule(), 'AccessManagerUnauthorizedCall', [user, ...this.call]); + } + }); + + it('Scheduling for later than needed'); // TODO + }); + } + }); + + describe('Indirect execution corner-cases', async function () { + beforeEach(async function () { + await this.manager.$_setTargetFunctionRole(this.target.address, this.callData, ROLES.SOME); + await this.manager.$_grantRole(ROLES.SOME, user, 0, executeDelay); + }); + + it('Checking canCall when caller is the manager depend on the _executionId', async function () { + const result = await this.manager.canCall(this.manager.address, this.target.address, '0x00000000'); + expect(result[0]).to.be.false; + expect(result[1]).to.be.bignumber.equal('0'); + }); + + it('Cannot execute earlier', async function () { + const { receipt } = await this.schedule(); + const timestamp = await clockFromReceipt.timestamp(receipt).then(web3.utils.toBN); + + expect(await this.manager.getSchedule(this.opId)).to.be.bignumber.equal(timestamp.add(executeDelay)); + + // too early + await helpers.time.setNextBlockTimestamp(timestamp.add(executeDelay).subn(1)); + await expectRevertCustomError(this.execute(), 'AccessManagerNotReady', [this.opId]); + + // the revert happened one second before the execution delay expired + expect(await time.latest()).to.be.bignumber.equal(timestamp.add(executeDelay).subn(1)); + + // ok + await helpers.time.setNextBlockTimestamp(timestamp.add(executeDelay)); + await this.execute(); + + // the success happened when the delay was reached (earliest possible) + expect(await time.latest()).to.be.bignumber.equal(timestamp.add(executeDelay)); + }); + + it('Cannot schedule an already scheduled operation', async function () { + const { receipt } = await this.schedule(); + expectEvent(receipt, 'OperationScheduled', { + operationId: this.opId, + caller: user, + target: this.call[0], + data: this.call[1], + }); + + await expectRevertCustomError(this.schedule(), 'AccessManagerAlreadyScheduled', [this.opId]); + }); + + it('Cannot cancel an operation that is not scheduled', async function () { + await expectRevertCustomError(this.cancel(), 'AccessManagerNotScheduled', [this.opId]); + }); + + it('Cannot cancel an operation that is already executed', async function () { + await this.schedule(); + await time.increase(executeDelay); + await this.execute(); + + await expectRevertCustomError(this.cancel(), 'AccessManagerNotScheduled', [this.opId]); + }); + + it('Scheduler can cancel', async function () { + await this.schedule(); + + expect(await this.manager.getSchedule(this.opId)).to.not.be.bignumber.equal('0'); + + expectEvent(await this.cancel({ from: manager }), 'OperationCanceled', { operationId: this.opId }); + + expect(await this.manager.getSchedule(this.opId)).to.be.bignumber.equal('0'); + }); + + it('Guardian can cancel', async function () { + await this.schedule(); + + expect(await this.manager.getSchedule(this.opId)).to.not.be.bignumber.equal('0'); + + expectEvent(await this.cancel({ from: manager }), 'OperationCanceled', { operationId: this.opId }); + + expect(await this.manager.getSchedule(this.opId)).to.be.bignumber.equal('0'); + }); + + it('Cancel is restricted', async function () { + await this.schedule(); + + expect(await this.manager.getSchedule(this.opId)).to.not.be.bignumber.equal('0'); + + await expectRevertCustomError(this.cancel({ from: other }), 'AccessManagerUnauthorizedCancel', [ + other, + user, + ...this.call, + ]); + + expect(await this.manager.getSchedule(this.opId)).to.not.be.bignumber.equal('0'); + }); + + it('Can re-schedule after execution', async function () { + await this.schedule(); + await time.increase(executeDelay); + await this.execute(); + + // reschedule + const { receipt } = await this.schedule(); + expectEvent(receipt, 'OperationScheduled', { + operationId: this.opId, + caller: user, + target: this.call[0], + data: this.call[1], + }); + }); + + it('Can re-schedule after cancel', async function () { + await this.schedule(); + await this.cancel(); + + // reschedule + const { receipt } = await this.schedule(); + expectEvent(receipt, 'OperationScheduled', { + operationId: this.opId, + caller: user, + target: this.call[0], + data: this.call[1], + }); + }); + }); + }); + + describe('with Ownable target contract', function () { + const roleId = web3.utils.toBN(1); + + beforeEach(async function () { + this.ownable = await Ownable.new(this.manager.address); + + // add user to role + await this.manager.$_grantRole(roleId, user, 0, 0); + }); + + it('initial state', async function () { + expect(await this.ownable.owner()).to.be.equal(this.manager.address); + }); + + describe('Contract is closed', function () { + beforeEach(async function () { + await this.manager.$_setTargetClosed(this.ownable.address, true); + }); + + it('directly call: reverts', async function () { + await expectRevertCustomError(this.ownable.$_checkOwner({ from: user }), 'OwnableUnauthorizedAccount', [user]); + }); + + it('relayed call (with role): reverts', async function () { + await expectRevertCustomError( + this.manager.execute(this.ownable.address, selector('$_checkOwner()'), { from: user }), + 'AccessManagerUnauthorizedCall', + [user, this.ownable.address, selector('$_checkOwner()')], + ); + }); + + it('relayed call (without role): reverts', async function () { + await expectRevertCustomError( + this.manager.execute(this.ownable.address, selector('$_checkOwner()'), { from: other }), + 'AccessManagerUnauthorizedCall', + [other, this.ownable.address, selector('$_checkOwner()')], + ); + }); + }); + + describe('Contract is managed', function () { + describe('function is open to specific role', function () { + beforeEach(async function () { + await this.manager.$_setTargetFunctionRole(this.ownable.address, selector('$_checkOwner()'), roleId); + }); + + it('directly call: reverts', async function () { + await expectRevertCustomError(this.ownable.$_checkOwner({ from: user }), 'OwnableUnauthorizedAccount', [ + user, + ]); + }); + + it('relayed call (with role): success', async function () { + await this.manager.execute(this.ownable.address, selector('$_checkOwner()'), { from: user }); + }); + + it('relayed call (without role): reverts', async function () { + await expectRevertCustomError( + this.manager.execute(this.ownable.address, selector('$_checkOwner()'), { from: other }), + 'AccessManagerUnauthorizedCall', + [other, this.ownable.address, selector('$_checkOwner()')], + ); + }); + }); + + describe('function is open to public role', function () { + beforeEach(async function () { + await this.manager.$_setTargetFunctionRole(this.ownable.address, selector('$_checkOwner()'), ROLES.PUBLIC); + }); + + it('directly call: reverts', async function () { + await expectRevertCustomError(this.ownable.$_checkOwner({ from: user }), 'OwnableUnauthorizedAccount', [ + user, + ]); + }); + + it('relayed call (with role): success', async function () { + await this.manager.execute(this.ownable.address, selector('$_checkOwner()'), { from: user }); + }); + + it('relayed call (without role): success', async function () { + await this.manager.execute(this.ownable.address, selector('$_checkOwner()'), { from: other }); + }); + }); + }); + }); + + describe('authority update', function () { + beforeEach(async function () { + this.newManager = await AccessManager.new(admin); + this.target = await AccessManagedTarget.new(this.manager.address); + }); + + it('admin can change authority', async function () { + expect(await this.target.authority()).to.be.equal(this.manager.address); + + const { tx } = await this.manager.updateAuthority(this.target.address, this.newManager.address, { from: admin }); + await expectEvent.inTransaction(tx, this.target, 'AuthorityUpdated', { authority: this.newManager.address }); + + expect(await this.target.authority()).to.be.equal(this.newManager.address); + }); + + it('cannot set an address without code as the authority', async function () { + await expectRevertCustomError( + this.manager.updateAuthority(this.target.address, user, { from: admin }), + 'AccessManagedInvalidAuthority', + [user], + ); + }); + + it('updateAuthority is restricted on manager', async function () { + await expectRevertCustomError( + this.manager.updateAuthority(this.target.address, this.newManager.address, { from: other }), + 'AccessManagerUnauthorizedAccount', + [other, ROLES.ADMIN], + ); + }); + + it('setAuthority is restricted on AccessManaged', async function () { + await expectRevertCustomError( + this.target.setAuthority(this.newManager.address, { from: admin }), + 'AccessManagedUnauthorized', + [admin], + ); + }); + }); + + // TODO: + // - check opening/closing a contract + // - check updating the contract delay + // - check the delay applies to admin function + describe.skip('contract modes', function () {}); +}); diff --git a/test/finance/VestingWallet.behavior.js b/test/finance/VestingWallet.behavior.js new file mode 100644 index 000000000..afd4c0495 --- /dev/null +++ b/test/finance/VestingWallet.behavior.js @@ -0,0 +1,59 @@ +const { time } = require('@nomicfoundation/hardhat-network-helpers'); +const { expectEvent } = require('@openzeppelin/test-helpers'); +const { expect } = require('chai'); + +function releasedEvent(token, amount) { + return token ? ['ERC20Released', { token: token.address, amount }] : ['EtherReleased', { amount }]; +} + +function shouldBehaveLikeVesting(beneficiary) { + it('check vesting schedule', async function () { + const [vestedAmount, releasable, ...args] = this.token + ? ['vestedAmount(address,uint64)', 'releasable(address)', this.token.address] + : ['vestedAmount(uint64)', 'releasable()']; + + for (const timestamp of this.schedule) { + await time.increaseTo(timestamp); + const vesting = this.vestingFn(timestamp); + + expect(await this.mock.methods[vestedAmount](...args, timestamp)).to.be.bignumber.equal(vesting); + + expect(await this.mock.methods[releasable](...args)).to.be.bignumber.equal(vesting); + } + }); + + it('execute vesting schedule', async function () { + const [release, ...args] = this.token ? ['release(address)', this.token.address] : ['release()']; + + let released = web3.utils.toBN(0); + const before = await this.getBalance(beneficiary); + + { + const receipt = await this.mock.methods[release](...args); + + await expectEvent.inTransaction(receipt.tx, this.mock, ...releasedEvent(this.token, '0')); + + await this.checkRelease(receipt, beneficiary, '0'); + + expect(await this.getBalance(beneficiary)).to.be.bignumber.equal(before); + } + + for (const timestamp of this.schedule) { + await time.setNextBlockTimestamp(timestamp); + const vested = this.vestingFn(timestamp); + + const receipt = await this.mock.methods[release](...args); + await expectEvent.inTransaction(receipt.tx, this.mock, ...releasedEvent(this.token, vested.sub(released))); + + await this.checkRelease(receipt, beneficiary, vested.sub(released)); + + expect(await this.getBalance(beneficiary)).to.be.bignumber.equal(before.add(vested)); + + released = vested; + } + }); +} + +module.exports = { + shouldBehaveLikeVesting, +}; diff --git a/test/finance/VestingWallet.test.js b/test/finance/VestingWallet.test.js new file mode 100644 index 000000000..918e56345 --- /dev/null +++ b/test/finance/VestingWallet.test.js @@ -0,0 +1,69 @@ +const { constants, expectEvent, time } = require('@openzeppelin/test-helpers'); +const { web3 } = require('@openzeppelin/test-helpers/src/setup'); +const { expect } = require('chai'); +const { BNmin } = require('../helpers/math'); +const { expectRevertCustomError } = require('../helpers/customError'); + +const VestingWallet = artifacts.require('VestingWallet'); +const ERC20 = artifacts.require('$ERC20'); + +const { shouldBehaveLikeVesting } = require('./VestingWallet.behavior'); + +contract('VestingWallet', function (accounts) { + const [sender, beneficiary] = accounts; + + const amount = web3.utils.toBN(web3.utils.toWei('100')); + const duration = web3.utils.toBN(4 * 365 * 86400); // 4 years + + beforeEach(async function () { + this.start = (await time.latest()).addn(3600); // in 1 hour + this.mock = await VestingWallet.new(beneficiary, this.start, duration); + }); + + it('rejects zero address for beneficiary', async function () { + await expectRevertCustomError( + VestingWallet.new(constants.ZERO_ADDRESS, this.start, duration), + 'OwnableInvalidOwner', + [constants.ZERO_ADDRESS], + ); + }); + + it('check vesting contract', async function () { + expect(await this.mock.owner()).to.be.equal(beneficiary); + expect(await this.mock.start()).to.be.bignumber.equal(this.start); + expect(await this.mock.duration()).to.be.bignumber.equal(duration); + expect(await this.mock.end()).to.be.bignumber.equal(this.start.add(duration)); + }); + + describe('vesting schedule', function () { + beforeEach(async function () { + this.schedule = Array(64) + .fill() + .map((_, i) => web3.utils.toBN(i).mul(duration).divn(60).add(this.start)); + this.vestingFn = timestamp => BNmin(amount, amount.mul(timestamp.sub(this.start)).div(duration)); + }); + + describe('Eth vesting', function () { + beforeEach(async function () { + await web3.eth.sendTransaction({ from: sender, to: this.mock.address, value: amount }); + this.getBalance = account => web3.eth.getBalance(account).then(web3.utils.toBN); + this.checkRelease = () => {}; + }); + + shouldBehaveLikeVesting(beneficiary); + }); + + describe('ERC20 vesting', function () { + beforeEach(async function () { + this.token = await ERC20.new('Name', 'Symbol'); + this.getBalance = account => this.token.balanceOf(account); + this.checkRelease = (receipt, to, value) => + expectEvent.inTransaction(receipt.tx, this.token, 'Transfer', { from: this.mock.address, to, value }); + + await this.token.$_mint(this.mock.address, amount); + }); + + shouldBehaveLikeVesting(beneficiary); + }); + }); +}); diff --git a/test/governance/Governor.t.sol b/test/governance/Governor.t.sol new file mode 100644 index 000000000..f63124536 --- /dev/null +++ b/test/governance/Governor.t.sol @@ -0,0 +1,55 @@ +// SPDX-License-Identifier: MIT + +pragma solidity ^0.8.20; + +import {Test} from "forge-std/Test.sol"; +import {Strings} from "@openzeppelin/contracts/utils/Strings.sol"; +import {Governor} from "@openzeppelin/contracts/governance/Governor.sol"; + +contract GovernorInternalTest is Test, Governor { + constructor() Governor("") {} + + function testValidDescriptionForProposer(string memory description, address proposer, bool includeProposer) public { + if (includeProposer) { + description = string.concat(description, "#proposer=", Strings.toHexString(proposer)); + } + assertTrue(_isValidDescriptionForProposer(proposer, description)); + } + + function testInvalidDescriptionForProposer( + string memory description, + address commitProposer, + address actualProposer + ) public { + vm.assume(commitProposer != actualProposer); + description = string.concat(description, "#proposer=", Strings.toHexString(commitProposer)); + assertFalse(_isValidDescriptionForProposer(actualProposer, description)); + } + + // We don't need to truly implement implement the missing functions because we are just testing + // internal helpers. + + function clock() public pure override returns (uint48) {} + + // solhint-disable-next-line func-name-mixedcase + function CLOCK_MODE() public pure override returns (string memory) {} + + // solhint-disable-next-line func-name-mixedcase + function COUNTING_MODE() public pure virtual override returns (string memory) {} + + function votingDelay() public pure virtual override returns (uint256) {} + + function votingPeriod() public pure virtual override returns (uint256) {} + + function quorum(uint256) public pure virtual override returns (uint256) {} + + function hasVoted(uint256, address) public pure virtual override returns (bool) {} + + function _quorumReached(uint256) internal pure virtual override returns (bool) {} + + function _voteSucceeded(uint256) internal pure virtual override returns (bool) {} + + function _getVotes(address, uint256, bytes memory) internal pure virtual override returns (uint256) {} + + function _countVote(uint256, address, uint8, uint256, bytes memory) internal virtual override {} +} diff --git a/test/governance/Governor.test.js b/test/governance/Governor.test.js new file mode 100644 index 000000000..45cceba9a --- /dev/null +++ b/test/governance/Governor.test.js @@ -0,0 +1,1024 @@ +const { constants, expectEvent, expectRevert } = require('@openzeppelin/test-helpers'); +const { expect } = require('chai'); +const ethSigUtil = require('eth-sig-util'); +const Wallet = require('ethereumjs-wallet').default; + +const Enums = require('../helpers/enums'); +const { getDomain, domainType } = require('../helpers/eip712'); +const { GovernorHelper, proposalStatesToBitMap } = require('../helpers/governance'); +const { clockFromReceipt } = require('../helpers/time'); +const { expectRevertCustomError } = require('../helpers/customError'); + +const { shouldSupportInterfaces } = require('../utils/introspection/SupportsInterface.behavior'); +const { shouldBehaveLikeEIP6372 } = require('./utils/EIP6372.behavior'); +const { ZERO_BYTES32 } = require('@openzeppelin/test-helpers/src/constants'); + +const Governor = artifacts.require('$GovernorMock'); +const CallReceiver = artifacts.require('CallReceiverMock'); +const ERC721 = artifacts.require('$ERC721'); +const ERC1155 = artifacts.require('$ERC1155'); +const ERC1271WalletMock = artifacts.require('ERC1271WalletMock'); + +const TOKENS = [ + { Token: artifacts.require('$ERC20Votes'), mode: 'blocknumber' }, + { Token: artifacts.require('$ERC20VotesTimestampMock'), mode: 'timestamp' }, + { Token: artifacts.require('$ERC20VotesLegacyMock'), mode: 'blocknumber' }, +]; + +contract('Governor', function (accounts) { + const [owner, proposer, voter1, voter2, voter3, voter4] = accounts; + + const name = 'OZ-Governor'; + const version = '1'; + const tokenName = 'MockToken'; + const tokenSymbol = 'MTKN'; + const tokenSupply = web3.utils.toWei('100'); + const votingDelay = web3.utils.toBN(4); + const votingPeriod = web3.utils.toBN(16); + const value = web3.utils.toWei('1'); + + for (const { mode, Token } of TOKENS) { + describe(`using ${Token._json.contractName}`, function () { + beforeEach(async function () { + this.chainId = await web3.eth.getChainId(); + try { + this.token = await Token.new(tokenName, tokenSymbol, tokenName, version); + } catch { + // ERC20VotesLegacyMock has a different construction that uses version='1' by default. + this.token = await Token.new(tokenName, tokenSymbol, tokenName); + } + this.mock = await Governor.new( + name, // name + votingDelay, // initialVotingDelay + votingPeriod, // initialVotingPeriod + 0, // initialProposalThreshold + this.token.address, // tokenAddress + 10, // quorumNumeratorValue + ); + this.receiver = await CallReceiver.new(); + + this.helper = new GovernorHelper(this.mock, mode); + + await web3.eth.sendTransaction({ from: owner, to: this.mock.address, value }); + + await this.token.$_mint(owner, tokenSupply); + await this.helper.delegate({ token: this.token, to: voter1, value: web3.utils.toWei('10') }, { from: owner }); + await this.helper.delegate({ token: this.token, to: voter2, value: web3.utils.toWei('7') }, { from: owner }); + await this.helper.delegate({ token: this.token, to: voter3, value: web3.utils.toWei('5') }, { from: owner }); + await this.helper.delegate({ token: this.token, to: voter4, value: web3.utils.toWei('2') }, { from: owner }); + + this.proposal = this.helper.setProposal( + [ + { + target: this.receiver.address, + data: this.receiver.contract.methods.mockFunction().encodeABI(), + value, + }, + ], + '', + ); + }); + + shouldSupportInterfaces(['ERC165', 'ERC1155Receiver', 'Governor']); + shouldBehaveLikeEIP6372(mode); + + it('deployment check', async function () { + expect(await this.mock.name()).to.be.equal(name); + expect(await this.mock.token()).to.be.equal(this.token.address); + expect(await this.mock.votingDelay()).to.be.bignumber.equal(votingDelay); + expect(await this.mock.votingPeriod()).to.be.bignumber.equal(votingPeriod); + expect(await this.mock.quorum(0)).to.be.bignumber.equal('0'); + expect(await this.mock.COUNTING_MODE()).to.be.equal('support=bravo&quorum=for,abstain'); + }); + + it('nominal workflow', async function () { + // Before + expect(await this.mock.proposalProposer(this.proposal.id)).to.be.equal(constants.ZERO_ADDRESS); + expect(await this.mock.hasVoted(this.proposal.id, owner)).to.be.equal(false); + expect(await this.mock.hasVoted(this.proposal.id, voter1)).to.be.equal(false); + expect(await this.mock.hasVoted(this.proposal.id, voter2)).to.be.equal(false); + expect(await web3.eth.getBalance(this.mock.address)).to.be.bignumber.equal(value); + expect(await web3.eth.getBalance(this.receiver.address)).to.be.bignumber.equal('0'); + + expect(await this.mock.proposalEta(this.proposal.id)).to.be.bignumber.equal('0'); + expect(await this.mock.proposalNeedsQueuing(this.proposal.id)).to.be.equal(false); + + // Run proposal + const txPropose = await this.helper.propose({ from: proposer }); + + expectEvent(txPropose, 'ProposalCreated', { + proposalId: this.proposal.id, + proposer, + targets: this.proposal.targets, + // values: this.proposal.values, + signatures: this.proposal.signatures, + calldatas: this.proposal.data, + voteStart: web3.utils.toBN(await clockFromReceipt[mode](txPropose.receipt)).add(votingDelay), + voteEnd: web3.utils + .toBN(await clockFromReceipt[mode](txPropose.receipt)) + .add(votingDelay) + .add(votingPeriod), + description: this.proposal.description, + }); + + await this.helper.waitForSnapshot(); + + expectEvent( + await this.helper.vote({ support: Enums.VoteType.For, reason: 'This is nice' }, { from: voter1 }), + 'VoteCast', + { + voter: voter1, + support: Enums.VoteType.For, + reason: 'This is nice', + weight: web3.utils.toWei('10'), + }, + ); + + expectEvent(await this.helper.vote({ support: Enums.VoteType.For }, { from: voter2 }), 'VoteCast', { + voter: voter2, + support: Enums.VoteType.For, + weight: web3.utils.toWei('7'), + }); + + expectEvent(await this.helper.vote({ support: Enums.VoteType.Against }, { from: voter3 }), 'VoteCast', { + voter: voter3, + support: Enums.VoteType.Against, + weight: web3.utils.toWei('5'), + }); + + expectEvent(await this.helper.vote({ support: Enums.VoteType.Abstain }, { from: voter4 }), 'VoteCast', { + voter: voter4, + support: Enums.VoteType.Abstain, + weight: web3.utils.toWei('2'), + }); + + await this.helper.waitForDeadline(); + + const txExecute = await this.helper.execute(); + + expectEvent(txExecute, 'ProposalExecuted', { proposalId: this.proposal.id }); + + await expectEvent.inTransaction(txExecute.tx, this.receiver, 'MockFunctionCalled'); + + // After + expect(await this.mock.proposalProposer(this.proposal.id)).to.be.equal(proposer); + expect(await this.mock.hasVoted(this.proposal.id, owner)).to.be.equal(false); + expect(await this.mock.hasVoted(this.proposal.id, voter1)).to.be.equal(true); + expect(await this.mock.hasVoted(this.proposal.id, voter2)).to.be.equal(true); + expect(await web3.eth.getBalance(this.mock.address)).to.be.bignumber.equal('0'); + expect(await web3.eth.getBalance(this.receiver.address)).to.be.bignumber.equal(value); + + expect(await this.mock.proposalEta(this.proposal.id)).to.be.bignumber.equal('0'); + expect(await this.mock.proposalNeedsQueuing(this.proposal.id)).to.be.equal(false); + }); + + it('send ethers', async function () { + const empty = web3.utils.toChecksumAddress(web3.utils.randomHex(20)); + + this.proposal = this.helper.setProposal( + [ + { + target: empty, + value, + }, + ], + '', + ); + + // Before + expect(await web3.eth.getBalance(this.mock.address)).to.be.bignumber.equal(value); + expect(await web3.eth.getBalance(empty)).to.be.bignumber.equal('0'); + + // Run proposal + await this.helper.propose(); + await this.helper.waitForSnapshot(); + await this.helper.vote({ support: Enums.VoteType.For }, { from: voter1 }); + await this.helper.waitForDeadline(); + await this.helper.execute(); + + // After + expect(await web3.eth.getBalance(this.mock.address)).to.be.bignumber.equal('0'); + expect(await web3.eth.getBalance(empty)).to.be.bignumber.equal(value); + }); + + describe('vote with signature', function () { + const sign = privateKey => async (contract, message) => { + const domain = await getDomain(contract); + return ethSigUtil.signTypedMessage(privateKey, { + data: { + primaryType: 'Ballot', + types: { + EIP712Domain: domainType(domain), + Ballot: [ + { name: 'proposalId', type: 'uint256' }, + { name: 'support', type: 'uint8' }, + { name: 'voter', type: 'address' }, + { name: 'nonce', type: 'uint256' }, + ], + }, + domain, + message, + }, + }); + }; + + afterEach('no other votes are cast for proposalId', async function () { + expect(await this.mock.hasVoted(this.proposal.id, owner)).to.be.equal(false); + expect(await this.mock.hasVoted(this.proposal.id, voter1)).to.be.equal(false); + expect(await this.mock.hasVoted(this.proposal.id, voter2)).to.be.equal(false); + }); + + it('votes with an EOA signature', async function () { + const voterBySig = Wallet.generate(); + const voterBySigAddress = web3.utils.toChecksumAddress(voterBySig.getAddressString()); + + await this.token.delegate(voterBySigAddress, { from: voter1 }); + + const nonce = await this.mock.nonces(voterBySigAddress); + + // Run proposal + await this.helper.propose(); + await this.helper.waitForSnapshot(); + expectEvent( + await this.helper.vote({ + support: Enums.VoteType.For, + voter: voterBySigAddress, + nonce, + signature: sign(voterBySig.getPrivateKey()), + }), + 'VoteCast', + { + voter: voterBySigAddress, + support: Enums.VoteType.For, + }, + ); + await this.helper.waitForDeadline(); + await this.helper.execute(); + + // After + expect(await this.mock.hasVoted(this.proposal.id, voterBySigAddress)).to.be.equal(true); + expect(await this.mock.nonces(voterBySigAddress)).to.be.bignumber.equal(nonce.addn(1)); + }); + + it('votes with a valid EIP-1271 signature', async function () { + const ERC1271WalletOwner = Wallet.generate(); + ERC1271WalletOwner.address = web3.utils.toChecksumAddress(ERC1271WalletOwner.getAddressString()); + + const wallet = await ERC1271WalletMock.new(ERC1271WalletOwner.address); + + await this.token.delegate(wallet.address, { from: voter1 }); + + const nonce = await this.mock.nonces(wallet.address); + + // Run proposal + await this.helper.propose(); + await this.helper.waitForSnapshot(); + expectEvent( + await this.helper.vote({ + support: Enums.VoteType.For, + voter: wallet.address, + nonce, + signature: sign(ERC1271WalletOwner.getPrivateKey()), + }), + 'VoteCast', + { + voter: wallet.address, + support: Enums.VoteType.For, + }, + ); + await this.helper.waitForDeadline(); + await this.helper.execute(); + + // After + expect(await this.mock.hasVoted(this.proposal.id, wallet.address)).to.be.equal(true); + expect(await this.mock.nonces(wallet.address)).to.be.bignumber.equal(nonce.addn(1)); + }); + + afterEach('no other votes are cast', async function () { + expect(await this.mock.hasVoted(this.proposal.id, owner)).to.be.equal(false); + expect(await this.mock.hasVoted(this.proposal.id, voter1)).to.be.equal(false); + expect(await this.mock.hasVoted(this.proposal.id, voter2)).to.be.equal(false); + }); + }); + + describe('should revert', function () { + describe('on propose', function () { + it('if proposal already exists', async function () { + await this.helper.propose(); + await expectRevertCustomError(this.helper.propose(), 'GovernorUnexpectedProposalState', [ + this.proposal.id, + Enums.ProposalState.Pending, + ZERO_BYTES32, + ]); + }); + + it('if proposer has below threshold votes', async function () { + const votes = web3.utils.toWei('10'); + const threshold = web3.utils.toWei('1000'); + await this.mock.$_setProposalThreshold(threshold); + await expectRevertCustomError(this.helper.propose({ from: voter1 }), 'GovernorInsufficientProposerVotes', [ + voter1, + votes, + threshold, + ]); + }); + }); + + describe('on vote', function () { + it('if proposal does not exist', async function () { + await expectRevertCustomError( + this.helper.vote({ support: Enums.VoteType.For }, { from: voter1 }), + 'GovernorNonexistentProposal', + [this.proposal.id], + ); + }); + + it('if voting has not started', async function () { + await this.helper.propose(); + await expectRevertCustomError( + this.helper.vote({ support: Enums.VoteType.For }, { from: voter1 }), + 'GovernorUnexpectedProposalState', + [this.proposal.id, Enums.ProposalState.Pending, proposalStatesToBitMap([Enums.ProposalState.Active])], + ); + }); + + it('if support value is invalid', async function () { + await this.helper.propose(); + await this.helper.waitForSnapshot(); + await expectRevertCustomError( + this.helper.vote({ support: web3.utils.toBN('255') }), + 'GovernorInvalidVoteType', + [], + ); + }); + + it('if vote was already casted', async function () { + await this.helper.propose(); + await this.helper.waitForSnapshot(); + await this.helper.vote({ support: Enums.VoteType.For }, { from: voter1 }); + await expectRevertCustomError( + this.helper.vote({ support: Enums.VoteType.For }, { from: voter1 }), + 'GovernorAlreadyCastVote', + [voter1], + ); + }); + + it('if voting is over', async function () { + await this.helper.propose(); + await this.helper.waitForDeadline(); + await expectRevertCustomError( + this.helper.vote({ support: Enums.VoteType.For }, { from: voter1 }), + 'GovernorUnexpectedProposalState', + [this.proposal.id, Enums.ProposalState.Defeated, proposalStatesToBitMap([Enums.ProposalState.Active])], + ); + }); + }); + + describe('on vote by signature', function () { + beforeEach(async function () { + this.voterBySig = Wallet.generate(); + this.voterBySig.address = web3.utils.toChecksumAddress(this.voterBySig.getAddressString()); + + this.data = (contract, message) => + getDomain(contract).then(domain => ({ + primaryType: 'Ballot', + types: { + EIP712Domain: domainType(domain), + Ballot: [ + { name: 'proposalId', type: 'uint256' }, + { name: 'support', type: 'uint8' }, + { name: 'voter', type: 'address' }, + { name: 'nonce', type: 'uint256' }, + ], + }, + domain, + message, + })); + + this.signature = (contract, message) => + this.data(contract, message).then(data => + ethSigUtil.signTypedMessage(this.voterBySig.getPrivateKey(), { data }), + ); + + await this.token.delegate(this.voterBySig.address, { from: voter1 }); + + // Run proposal + await this.helper.propose(); + await this.helper.waitForSnapshot(); + }); + + it('if signature does not match signer', async function () { + const nonce = await this.mock.nonces(this.voterBySig.address); + + const voteParams = { + support: Enums.VoteType.For, + voter: this.voterBySig.address, + nonce, + signature: async (...params) => { + const sig = await this.signature(...params); + const tamperedSig = web3.utils.hexToBytes(sig); + tamperedSig[42] ^= 0xff; + return web3.utils.bytesToHex(tamperedSig); + }, + }; + + await expectRevertCustomError(this.helper.vote(voteParams), 'GovernorInvalidSignature', [voteParams.voter]); + }); + + it('if vote nonce is incorrect', async function () { + const nonce = await this.mock.nonces(this.voterBySig.address); + + const voteParams = { + support: Enums.VoteType.For, + voter: this.voterBySig.address, + nonce: nonce.addn(1), + signature: this.signature, + }; + + await expectRevertCustomError( + this.helper.vote(voteParams), + // The signature check implies the nonce can't be tampered without changing the signer + 'GovernorInvalidSignature', + [voteParams.voter], + ); + }); + }); + + describe('on queue', function () { + it('always', async function () { + await this.helper.propose({ from: proposer }); + await this.helper.waitForSnapshot(); + await this.helper.vote({ support: Enums.VoteType.For }, { from: voter1 }); + await this.helper.waitForDeadline(); + await expectRevertCustomError(this.helper.queue(), 'GovernorQueueNotImplemented', []); + }); + }); + + describe('on execute', function () { + it('if proposal does not exist', async function () { + await expectRevertCustomError(this.helper.execute(), 'GovernorNonexistentProposal', [this.proposal.id]); + }); + + it('if quorum is not reached', async function () { + await this.helper.propose(); + await this.helper.waitForSnapshot(); + await this.helper.vote({ support: Enums.VoteType.For }, { from: voter3 }); + await expectRevertCustomError(this.helper.execute(), 'GovernorUnexpectedProposalState', [ + this.proposal.id, + Enums.ProposalState.Active, + proposalStatesToBitMap([Enums.ProposalState.Succeeded, Enums.ProposalState.Queued]), + ]); + }); + + it('if score not reached', async function () { + await this.helper.propose(); + await this.helper.waitForSnapshot(); + await this.helper.vote({ support: Enums.VoteType.Against }, { from: voter1 }); + await expectRevertCustomError(this.helper.execute(), 'GovernorUnexpectedProposalState', [ + this.proposal.id, + Enums.ProposalState.Active, + proposalStatesToBitMap([Enums.ProposalState.Succeeded, Enums.ProposalState.Queued]), + ]); + }); + + it('if voting is not over', async function () { + await this.helper.propose(); + await this.helper.waitForSnapshot(); + await this.helper.vote({ support: Enums.VoteType.For }, { from: voter1 }); + await expectRevertCustomError(this.helper.execute(), 'GovernorUnexpectedProposalState', [ + this.proposal.id, + Enums.ProposalState.Active, + proposalStatesToBitMap([Enums.ProposalState.Succeeded, Enums.ProposalState.Queued]), + ]); + }); + + it('if receiver revert without reason', async function () { + this.helper.setProposal( + [ + { + target: this.receiver.address, + data: this.receiver.contract.methods.mockFunctionRevertsNoReason().encodeABI(), + }, + ], + '', + ); + + await this.helper.propose(); + await this.helper.waitForSnapshot(); + await this.helper.vote({ support: Enums.VoteType.For }, { from: voter1 }); + await this.helper.waitForDeadline(); + await expectRevertCustomError(this.helper.execute(), 'FailedInnerCall', []); + }); + + it('if receiver revert with reason', async function () { + this.helper.setProposal( + [ + { + target: this.receiver.address, + data: this.receiver.contract.methods.mockFunctionRevertsReason().encodeABI(), + }, + ], + '', + ); + + await this.helper.propose(); + await this.helper.waitForSnapshot(); + await this.helper.vote({ support: Enums.VoteType.For }, { from: voter1 }); + await this.helper.waitForDeadline(); + await expectRevert(this.helper.execute(), 'CallReceiverMock: reverting'); + }); + + it('if proposal was already executed', async function () { + await this.helper.propose(); + await this.helper.waitForSnapshot(); + await this.helper.vote({ support: Enums.VoteType.For }, { from: voter1 }); + await this.helper.waitForDeadline(); + await this.helper.execute(); + await expectRevertCustomError(this.helper.execute(), 'GovernorUnexpectedProposalState', [ + this.proposal.id, + Enums.ProposalState.Executed, + proposalStatesToBitMap([Enums.ProposalState.Succeeded, Enums.ProposalState.Queued]), + ]); + }); + }); + }); + + describe('state', function () { + it('Unset', async function () { + await expectRevertCustomError(this.mock.state(this.proposal.id), 'GovernorNonexistentProposal', [ + this.proposal.id, + ]); + }); + + it('Pending & Active', async function () { + await this.helper.propose(); + expect(await this.mock.state(this.proposal.id)).to.be.bignumber.equal(Enums.ProposalState.Pending); + await this.helper.waitForSnapshot(); + expect(await this.mock.state(this.proposal.id)).to.be.bignumber.equal(Enums.ProposalState.Pending); + await this.helper.waitForSnapshot(+1); + expect(await this.mock.state(this.proposal.id)).to.be.bignumber.equal(Enums.ProposalState.Active); + }); + + it('Defeated', async function () { + await this.helper.propose(); + await this.helper.waitForDeadline(); + expect(await this.mock.state(this.proposal.id)).to.be.bignumber.equal(Enums.ProposalState.Active); + await this.helper.waitForDeadline(+1); + expect(await this.mock.state(this.proposal.id)).to.be.bignumber.equal(Enums.ProposalState.Defeated); + }); + + it('Succeeded', async function () { + await this.helper.propose(); + await this.helper.waitForSnapshot(); + await this.helper.vote({ support: Enums.VoteType.For }, { from: voter1 }); + await this.helper.waitForDeadline(); + expect(await this.mock.state(this.proposal.id)).to.be.bignumber.equal(Enums.ProposalState.Active); + await this.helper.waitForDeadline(+1); + expect(await this.mock.state(this.proposal.id)).to.be.bignumber.equal(Enums.ProposalState.Succeeded); + }); + + it('Executed', async function () { + await this.helper.propose(); + await this.helper.waitForSnapshot(); + await this.helper.vote({ support: Enums.VoteType.For }, { from: voter1 }); + await this.helper.waitForDeadline(); + await this.helper.execute(); + expect(await this.mock.state(this.proposal.id)).to.be.bignumber.equal(Enums.ProposalState.Executed); + }); + }); + + describe('cancel', function () { + describe('internal', function () { + it('before proposal', async function () { + await expectRevertCustomError(this.helper.cancel('internal'), 'GovernorNonexistentProposal', [ + this.proposal.id, + ]); + }); + + it('after proposal', async function () { + await this.helper.propose(); + + await this.helper.cancel('internal'); + expect(await this.mock.state(this.proposal.id)).to.be.bignumber.equal(Enums.ProposalState.Canceled); + + await this.helper.waitForSnapshot(); + await expectRevertCustomError( + this.helper.vote({ support: Enums.VoteType.For }, { from: voter1 }), + 'GovernorUnexpectedProposalState', + [this.proposal.id, Enums.ProposalState.Canceled, proposalStatesToBitMap([Enums.ProposalState.Active])], + ); + }); + + it('after vote', async function () { + await this.helper.propose(); + await this.helper.waitForSnapshot(); + await this.helper.vote({ support: Enums.VoteType.For }, { from: voter1 }); + + await this.helper.cancel('internal'); + expect(await this.mock.state(this.proposal.id)).to.be.bignumber.equal(Enums.ProposalState.Canceled); + + await this.helper.waitForDeadline(); + await expectRevertCustomError(this.helper.execute(), 'GovernorUnexpectedProposalState', [ + this.proposal.id, + Enums.ProposalState.Canceled, + proposalStatesToBitMap([Enums.ProposalState.Succeeded, Enums.ProposalState.Queued]), + ]); + }); + + it('after deadline', async function () { + await this.helper.propose(); + await this.helper.waitForSnapshot(); + await this.helper.vote({ support: Enums.VoteType.For }, { from: voter1 }); + await this.helper.waitForDeadline(); + + await this.helper.cancel('internal'); + expect(await this.mock.state(this.proposal.id)).to.be.bignumber.equal(Enums.ProposalState.Canceled); + + await expectRevertCustomError(this.helper.execute(), 'GovernorUnexpectedProposalState', [ + this.proposal.id, + Enums.ProposalState.Canceled, + proposalStatesToBitMap([Enums.ProposalState.Succeeded, Enums.ProposalState.Queued]), + ]); + }); + + it('after execution', async function () { + await this.helper.propose(); + await this.helper.waitForSnapshot(); + await this.helper.vote({ support: Enums.VoteType.For }, { from: voter1 }); + await this.helper.waitForDeadline(); + await this.helper.execute(); + + await expectRevertCustomError(this.helper.cancel('internal'), 'GovernorUnexpectedProposalState', [ + this.proposal.id, + Enums.ProposalState.Executed, + proposalStatesToBitMap( + [Enums.ProposalState.Canceled, Enums.ProposalState.Expired, Enums.ProposalState.Executed], + { inverted: true }, + ), + ]); + }); + }); + + describe('public', function () { + it('before proposal', async function () { + await expectRevertCustomError(this.helper.cancel('external'), 'GovernorNonexistentProposal', [ + this.proposal.id, + ]); + }); + + it('after proposal', async function () { + await this.helper.propose(); + + await this.helper.cancel('external'); + }); + + it('after proposal - restricted to proposer', async function () { + await this.helper.propose(); + + await expectRevertCustomError(this.helper.cancel('external', { from: owner }), 'GovernorOnlyProposer', [ + owner, + ]); + }); + + it('after vote started', async function () { + await this.helper.propose(); + await this.helper.waitForSnapshot(1); // snapshot + 1 block + + await expectRevertCustomError(this.helper.cancel('external'), 'GovernorUnexpectedProposalState', [ + this.proposal.id, + Enums.ProposalState.Active, + proposalStatesToBitMap([Enums.ProposalState.Pending]), + ]); + }); + + it('after vote', async function () { + await this.helper.propose(); + await this.helper.waitForSnapshot(); + await this.helper.vote({ support: Enums.VoteType.For }, { from: voter1 }); + + await expectRevertCustomError(this.helper.cancel('external'), 'GovernorUnexpectedProposalState', [ + this.proposal.id, + Enums.ProposalState.Active, + proposalStatesToBitMap([Enums.ProposalState.Pending]), + ]); + }); + + it('after deadline', async function () { + await this.helper.propose(); + await this.helper.waitForSnapshot(); + await this.helper.vote({ support: Enums.VoteType.For }, { from: voter1 }); + await this.helper.waitForDeadline(); + + await expectRevertCustomError(this.helper.cancel('external'), 'GovernorUnexpectedProposalState', [ + this.proposal.id, + Enums.ProposalState.Succeeded, + proposalStatesToBitMap([Enums.ProposalState.Pending]), + ]); + }); + + it('after execution', async function () { + await this.helper.propose(); + await this.helper.waitForSnapshot(); + await this.helper.vote({ support: Enums.VoteType.For }, { from: voter1 }); + await this.helper.waitForDeadline(); + await this.helper.execute(); + + await expectRevertCustomError(this.helper.cancel('external'), 'GovernorUnexpectedProposalState', [ + this.proposal.id, + Enums.ProposalState.Executed, + proposalStatesToBitMap([Enums.ProposalState.Pending]), + ]); + }); + }); + }); + + describe('proposal length', function () { + it('empty', async function () { + this.helper.setProposal([], ''); + await expectRevertCustomError(this.helper.propose(), 'GovernorInvalidProposalLength', [0, 0, 0]); + }); + + it('mismatch #1', async function () { + this.helper.setProposal( + { + targets: [], + values: [web3.utils.toWei('0')], + data: [this.receiver.contract.methods.mockFunction().encodeABI()], + }, + '', + ); + await expectRevertCustomError(this.helper.propose(), 'GovernorInvalidProposalLength', [0, 1, 1]); + }); + + it('mismatch #2', async function () { + this.helper.setProposal( + { + targets: [this.receiver.address], + values: [], + data: [this.receiver.contract.methods.mockFunction().encodeABI()], + }, + '', + ); + await expectRevertCustomError(this.helper.propose(), 'GovernorInvalidProposalLength', [1, 1, 0]); + }); + + it('mismatch #3', async function () { + this.helper.setProposal( + { + targets: [this.receiver.address], + values: [web3.utils.toWei('0')], + data: [], + }, + '', + ); + await expectRevertCustomError(this.helper.propose(), 'GovernorInvalidProposalLength', [1, 0, 1]); + }); + }); + + describe('frontrun protection using description suffix', function () { + describe('without protection', function () { + describe('without suffix', function () { + it('proposer can propose', async function () { + expectEvent(await this.helper.propose({ from: proposer }), 'ProposalCreated'); + }); + + it('someone else can propose', async function () { + expectEvent(await this.helper.propose({ from: voter1 }), 'ProposalCreated'); + }); + }); + + describe('with different suffix', function () { + beforeEach(async function () { + this.proposal = this.helper.setProposal( + [ + { + target: this.receiver.address, + data: this.receiver.contract.methods.mockFunction().encodeABI(), + value, + }, + ], + `#wrong-suffix=${proposer}`, + ); + }); + + it('proposer can propose', async function () { + expectEvent(await this.helper.propose({ from: proposer }), 'ProposalCreated'); + }); + + it('someone else can propose', async function () { + expectEvent(await this.helper.propose({ from: voter1 }), 'ProposalCreated'); + }); + }); + + describe('with proposer suffix but bad address part', function () { + beforeEach(async function () { + this.proposal = this.helper.setProposal( + [ + { + target: this.receiver.address, + data: this.receiver.contract.methods.mockFunction().encodeABI(), + value, + }, + ], + `#proposer=0x3C44CdDdB6a900fa2b585dd299e03d12FA429XYZ`, // XYZ are not a valid hex char + ); + }); + + it('propose can propose', async function () { + expectEvent(await this.helper.propose({ from: proposer }), 'ProposalCreated'); + }); + + it('someone else can propose', async function () { + expectEvent(await this.helper.propose({ from: voter1 }), 'ProposalCreated'); + }); + }); + }); + + describe('with protection via proposer suffix', function () { + beforeEach(async function () { + this.proposal = this.helper.setProposal( + [ + { + target: this.receiver.address, + data: this.receiver.contract.methods.mockFunction().encodeABI(), + value, + }, + ], + `#proposer=${proposer}`, + ); + }); + + it('proposer can propose', async function () { + expectEvent(await this.helper.propose({ from: proposer }), 'ProposalCreated'); + }); + + it('someone else cannot propose', async function () { + await expectRevertCustomError(this.helper.propose({ from: voter1 }), 'GovernorRestrictedProposer', [ + voter1, + ]); + }); + }); + }); + + describe('onlyGovernance updates', function () { + it('setVotingDelay is protected', async function () { + await expectRevertCustomError(this.mock.setVotingDelay('0', { from: owner }), 'GovernorOnlyExecutor', [ + owner, + ]); + }); + + it('setVotingPeriod is protected', async function () { + await expectRevertCustomError(this.mock.setVotingPeriod('32', { from: owner }), 'GovernorOnlyExecutor', [ + owner, + ]); + }); + + it('setProposalThreshold is protected', async function () { + await expectRevertCustomError( + this.mock.setProposalThreshold('1000000000000000000', { from: owner }), + 'GovernorOnlyExecutor', + [owner], + ); + }); + + it('can setVotingDelay through governance', async function () { + this.helper.setProposal( + [ + { + target: this.mock.address, + data: this.mock.contract.methods.setVotingDelay('0').encodeABI(), + }, + ], + '', + ); + + await this.helper.propose(); + await this.helper.waitForSnapshot(); + await this.helper.vote({ support: Enums.VoteType.For }, { from: voter1 }); + await this.helper.waitForDeadline(); + + expectEvent(await this.helper.execute(), 'VotingDelaySet', { oldVotingDelay: '4', newVotingDelay: '0' }); + + expect(await this.mock.votingDelay()).to.be.bignumber.equal('0'); + }); + + it('can setVotingPeriod through governance', async function () { + this.helper.setProposal( + [ + { + target: this.mock.address, + data: this.mock.contract.methods.setVotingPeriod('32').encodeABI(), + }, + ], + '', + ); + + await this.helper.propose(); + await this.helper.waitForSnapshot(); + await this.helper.vote({ support: Enums.VoteType.For }, { from: voter1 }); + await this.helper.waitForDeadline(); + + expectEvent(await this.helper.execute(), 'VotingPeriodSet', { oldVotingPeriod: '16', newVotingPeriod: '32' }); + + expect(await this.mock.votingPeriod()).to.be.bignumber.equal('32'); + }); + + it('cannot setVotingPeriod to 0 through governance', async function () { + const votingPeriod = 0; + this.helper.setProposal( + [ + { + target: this.mock.address, + data: this.mock.contract.methods.setVotingPeriod(votingPeriod).encodeABI(), + }, + ], + '', + ); + + await this.helper.propose(); + await this.helper.waitForSnapshot(); + await this.helper.vote({ support: Enums.VoteType.For }, { from: voter1 }); + await this.helper.waitForDeadline(); + + await expectRevertCustomError(this.helper.execute(), 'GovernorInvalidVotingPeriod', [votingPeriod]); + }); + + it('can setProposalThreshold to 0 through governance', async function () { + this.helper.setProposal( + [ + { + target: this.mock.address, + data: this.mock.contract.methods.setProposalThreshold('1000000000000000000').encodeABI(), + }, + ], + '', + ); + + await this.helper.propose(); + await this.helper.waitForSnapshot(); + await this.helper.vote({ support: Enums.VoteType.For }, { from: voter1 }); + await this.helper.waitForDeadline(); + + expectEvent(await this.helper.execute(), 'ProposalThresholdSet', { + oldProposalThreshold: '0', + newProposalThreshold: '1000000000000000000', + }); + + expect(await this.mock.proposalThreshold()).to.be.bignumber.equal('1000000000000000000'); + }); + }); + + describe('safe receive', function () { + describe('ERC721', function () { + const name = 'Non Fungible Token'; + const symbol = 'NFT'; + const tokenId = web3.utils.toBN(1); + + beforeEach(async function () { + this.token = await ERC721.new(name, symbol); + await this.token.$_mint(owner, tokenId); + }); + + it('can receive an ERC721 safeTransfer', async function () { + await this.token.safeTransferFrom(owner, this.mock.address, tokenId, { from: owner }); + }); + }); + + describe('ERC1155', function () { + const uri = 'https://token-cdn-domain/{id}.json'; + const tokenIds = { + 1: web3.utils.toBN(1000), + 2: web3.utils.toBN(2000), + 3: web3.utils.toBN(3000), + }; + + beforeEach(async function () { + this.token = await ERC1155.new(uri); + await this.token.$_mintBatch(owner, Object.keys(tokenIds), Object.values(tokenIds), '0x'); + }); + + it('can receive ERC1155 safeTransfer', async function () { + await this.token.safeTransferFrom( + owner, + this.mock.address, + ...Object.entries(tokenIds)[0], // id + amount + '0x', + { from: owner }, + ); + }); + + it('can receive ERC1155 safeBatchTransfer', async function () { + await this.token.safeBatchTransferFrom( + owner, + this.mock.address, + Object.keys(tokenIds), + Object.values(tokenIds), + '0x', + { from: owner }, + ); + }); + }); + }); + }); + } +}); diff --git a/test/governance/TimelockController.test.js b/test/governance/TimelockController.test.js new file mode 100644 index 000000000..ce051e787 --- /dev/null +++ b/test/governance/TimelockController.test.js @@ -0,0 +1,1286 @@ +const { BN, constants, expectEvent, expectRevert, time } = require('@openzeppelin/test-helpers'); +const { ZERO_ADDRESS, ZERO_BYTES32 } = constants; +const { proposalStatesToBitMap } = require('../helpers/governance'); + +const { expect } = require('chai'); + +const { shouldSupportInterfaces } = require('../utils/introspection/SupportsInterface.behavior'); +const { expectRevertCustomError } = require('../helpers/customError'); +const { OperationState } = require('../helpers/enums'); + +const TimelockController = artifacts.require('TimelockController'); +const CallReceiverMock = artifacts.require('CallReceiverMock'); +const Implementation2 = artifacts.require('Implementation2'); +const ERC721 = artifacts.require('$ERC721'); +const ERC1155 = artifacts.require('$ERC1155'); +const TimelockReentrant = artifacts.require('$TimelockReentrant'); + +const MINDELAY = time.duration.days(1); + +const salt = '0x025e7b0be353a74631ad648c667493c0e1cd31caa4cc2d3520fdc171ea0cc726'; // a random value + +function genOperation(target, value, data, predecessor, salt) { + const id = web3.utils.keccak256( + web3.eth.abi.encodeParameters( + ['address', 'uint256', 'bytes', 'uint256', 'bytes32'], + [target, value, data, predecessor, salt], + ), + ); + return { id, target, value, data, predecessor, salt }; +} + +function genOperationBatch(targets, values, payloads, predecessor, salt) { + const id = web3.utils.keccak256( + web3.eth.abi.encodeParameters( + ['address[]', 'uint256[]', 'bytes[]', 'uint256', 'bytes32'], + [targets, values, payloads, predecessor, salt], + ), + ); + return { id, targets, values, payloads, predecessor, salt }; +} + +contract('TimelockController', function (accounts) { + const [, admin, proposer, canceller, executor, other] = accounts; + + const DEFAULT_ADMIN_ROLE = '0x0000000000000000000000000000000000000000000000000000000000000000'; + const PROPOSER_ROLE = web3.utils.soliditySha3('PROPOSER_ROLE'); + const EXECUTOR_ROLE = web3.utils.soliditySha3('EXECUTOR_ROLE'); + const CANCELLER_ROLE = web3.utils.soliditySha3('CANCELLER_ROLE'); + + beforeEach(async function () { + // Deploy new timelock + this.mock = await TimelockController.new(MINDELAY, [proposer], [executor], admin); + + expect(await this.mock.hasRole(CANCELLER_ROLE, proposer)).to.be.equal(true); + await this.mock.revokeRole(CANCELLER_ROLE, proposer, { from: admin }); + await this.mock.grantRole(CANCELLER_ROLE, canceller, { from: admin }); + + // Mocks + this.callreceivermock = await CallReceiverMock.new({ from: admin }); + this.implementation2 = await Implementation2.new({ from: admin }); + }); + + shouldSupportInterfaces(['ERC1155Receiver']); + + it('initial state', async function () { + expect(await this.mock.getMinDelay()).to.be.bignumber.equal(MINDELAY); + + expect(await this.mock.DEFAULT_ADMIN_ROLE()).to.be.equal(DEFAULT_ADMIN_ROLE); + expect(await this.mock.PROPOSER_ROLE()).to.be.equal(PROPOSER_ROLE); + expect(await this.mock.EXECUTOR_ROLE()).to.be.equal(EXECUTOR_ROLE); + expect(await this.mock.CANCELLER_ROLE()).to.be.equal(CANCELLER_ROLE); + + expect( + await Promise.all([PROPOSER_ROLE, CANCELLER_ROLE, EXECUTOR_ROLE].map(role => this.mock.hasRole(role, proposer))), + ).to.be.deep.equal([true, false, false]); + + expect( + await Promise.all([PROPOSER_ROLE, CANCELLER_ROLE, EXECUTOR_ROLE].map(role => this.mock.hasRole(role, canceller))), + ).to.be.deep.equal([false, true, false]); + + expect( + await Promise.all([PROPOSER_ROLE, CANCELLER_ROLE, EXECUTOR_ROLE].map(role => this.mock.hasRole(role, executor))), + ).to.be.deep.equal([false, false, true]); + }); + + it('optional admin', async function () { + const mock = await TimelockController.new(MINDELAY, [proposer], [executor], ZERO_ADDRESS, { from: other }); + + expect(await mock.hasRole(DEFAULT_ADMIN_ROLE, admin)).to.be.equal(false); + expect(await mock.hasRole(DEFAULT_ADMIN_ROLE, mock.address)).to.be.equal(true); + }); + + describe('methods', function () { + describe('operation hashing', function () { + it('hashOperation', async function () { + this.operation = genOperation( + '0x29cebefe301c6ce1bb36b58654fea275e1cacc83', + '0xf94fdd6e21da21d2', + '0xa3bc5104', + '0xba41db3be0a9929145cfe480bd0f1f003689104d275ae912099f925df424ef94', + '0x60d9109846ab510ed75c15f979ae366a8a2ace11d34ba9788c13ac296db50e6e', + ); + expect( + await this.mock.hashOperation( + this.operation.target, + this.operation.value, + this.operation.data, + this.operation.predecessor, + this.operation.salt, + ), + ).to.be.equal(this.operation.id); + }); + + it('hashOperationBatch', async function () { + this.operation = genOperationBatch( + Array(8).fill('0x2d5f21620e56531c1d59c2df9b8e95d129571f71'), + Array(8).fill('0x2b993cfce932ccee'), + Array(8).fill('0xcf51966b'), + '0xce8f45069cc71d25f71ba05062de1a3974f9849b004de64a70998bca9d29c2e7', + '0x8952d74c110f72bfe5accdf828c74d53a7dfb71235dfa8a1e8c75d8576b372ff', + ); + expect( + await this.mock.hashOperationBatch( + this.operation.targets, + this.operation.values, + this.operation.payloads, + this.operation.predecessor, + this.operation.salt, + ), + ).to.be.equal(this.operation.id); + }); + }); + describe('simple', function () { + describe('schedule', function () { + beforeEach(async function () { + this.operation = genOperation( + '0x31754f590B97fD975Eb86938f18Cc304E264D2F2', + 0, + '0x3bf92ccc', + ZERO_BYTES32, + salt, + ); + }); + + it('proposer can schedule', async function () { + const receipt = await this.mock.schedule( + this.operation.target, + this.operation.value, + this.operation.data, + this.operation.predecessor, + this.operation.salt, + MINDELAY, + { from: proposer }, + ); + expectEvent(receipt, 'CallScheduled', { + id: this.operation.id, + index: web3.utils.toBN(0), + target: this.operation.target, + value: web3.utils.toBN(this.operation.value), + data: this.operation.data, + predecessor: this.operation.predecessor, + delay: MINDELAY, + }); + + expectEvent(receipt, 'CallSalt', { + id: this.operation.id, + salt: this.operation.salt, + }); + + const block = await web3.eth.getBlock(receipt.receipt.blockHash); + + expect(await this.mock.getTimestamp(this.operation.id)).to.be.bignumber.equal( + web3.utils.toBN(block.timestamp).add(MINDELAY), + ); + }); + + it('prevent overwriting active operation', async function () { + await this.mock.schedule( + this.operation.target, + this.operation.value, + this.operation.data, + this.operation.predecessor, + this.operation.salt, + MINDELAY, + { from: proposer }, + ); + + await expectRevertCustomError( + this.mock.schedule( + this.operation.target, + this.operation.value, + this.operation.data, + this.operation.predecessor, + this.operation.salt, + MINDELAY, + { from: proposer }, + ), + 'TimelockUnexpectedOperationState', + [this.operation.id, proposalStatesToBitMap(OperationState.Unset)], + ); + }); + + it('prevent non-proposer from committing', async function () { + await expectRevertCustomError( + this.mock.schedule( + this.operation.target, + this.operation.value, + this.operation.data, + this.operation.predecessor, + this.operation.salt, + MINDELAY, + { from: other }, + ), + `AccessControlUnauthorizedAccount`, + [other, PROPOSER_ROLE], + ); + }); + + it('enforce minimum delay', async function () { + await expectRevertCustomError( + this.mock.schedule( + this.operation.target, + this.operation.value, + this.operation.data, + this.operation.predecessor, + this.operation.salt, + MINDELAY - 1, + { from: proposer }, + ), + 'TimelockInsufficientDelay', + [MINDELAY, MINDELAY - 1], + ); + }); + + it('schedule operation with salt zero', async function () { + const { receipt } = await this.mock.schedule( + this.operation.target, + this.operation.value, + this.operation.data, + this.operation.predecessor, + ZERO_BYTES32, + MINDELAY, + { from: proposer }, + ); + expectEvent.notEmitted(receipt, 'CallSalt'); + }); + }); + + describe('execute', function () { + beforeEach(async function () { + this.operation = genOperation( + '0xAe22104DCD970750610E6FE15E623468A98b15f7', + 0, + '0x13e414de', + ZERO_BYTES32, + '0xc1059ed2dc130227aa1d1d539ac94c641306905c020436c636e19e3fab56fc7f', + ); + }); + + it('revert if operation is not scheduled', async function () { + await expectRevertCustomError( + this.mock.execute( + this.operation.target, + this.operation.value, + this.operation.data, + this.operation.predecessor, + this.operation.salt, + { from: executor }, + ), + 'TimelockUnexpectedOperationState', + [this.operation.id, proposalStatesToBitMap(OperationState.Ready)], + ); + }); + + describe('with scheduled operation', function () { + beforeEach(async function () { + ({ receipt: this.receipt, logs: this.logs } = await this.mock.schedule( + this.operation.target, + this.operation.value, + this.operation.data, + this.operation.predecessor, + this.operation.salt, + MINDELAY, + { from: proposer }, + )); + }); + + it('revert if execution comes too early 1/2', async function () { + await expectRevertCustomError( + this.mock.execute( + this.operation.target, + this.operation.value, + this.operation.data, + this.operation.predecessor, + this.operation.salt, + { from: executor }, + ), + 'TimelockUnexpectedOperationState', + [this.operation.id, proposalStatesToBitMap(OperationState.Ready)], + ); + }); + + it('revert if execution comes too early 2/2', async function () { + const timestamp = await this.mock.getTimestamp(this.operation.id); + await time.increaseTo(timestamp - 5); // -1 is too tight, test sometime fails + + await expectRevertCustomError( + this.mock.execute( + this.operation.target, + this.operation.value, + this.operation.data, + this.operation.predecessor, + this.operation.salt, + { from: executor }, + ), + 'TimelockUnexpectedOperationState', + [this.operation.id, proposalStatesToBitMap(OperationState.Ready)], + ); + }); + + describe('on time', function () { + beforeEach(async function () { + const timestamp = await this.mock.getTimestamp(this.operation.id); + await time.increaseTo(timestamp); + }); + + it('executor can reveal', async function () { + const receipt = await this.mock.execute( + this.operation.target, + this.operation.value, + this.operation.data, + this.operation.predecessor, + this.operation.salt, + { from: executor }, + ); + expectEvent(receipt, 'CallExecuted', { + id: this.operation.id, + index: web3.utils.toBN(0), + target: this.operation.target, + value: web3.utils.toBN(this.operation.value), + data: this.operation.data, + }); + }); + + it('prevent non-executor from revealing', async function () { + await expectRevertCustomError( + this.mock.execute( + this.operation.target, + this.operation.value, + this.operation.data, + this.operation.predecessor, + this.operation.salt, + { from: other }, + ), + `AccessControlUnauthorizedAccount`, + [other, EXECUTOR_ROLE], + ); + }); + + it('prevents reentrancy execution', async function () { + // Create operation + const reentrant = await TimelockReentrant.new(); + const reentrantOperation = genOperation( + reentrant.address, + 0, + reentrant.contract.methods.reenter().encodeABI(), + ZERO_BYTES32, + salt, + ); + + // Schedule so it can be executed + await this.mock.schedule( + reentrantOperation.target, + reentrantOperation.value, + reentrantOperation.data, + reentrantOperation.predecessor, + reentrantOperation.salt, + MINDELAY, + { from: proposer }, + ); + + // Advance on time to make the operation executable + const timestamp = await this.mock.getTimestamp(reentrantOperation.id); + await time.increaseTo(timestamp); + + // Grant executor role to the reentrant contract + await this.mock.grantRole(EXECUTOR_ROLE, reentrant.address, { from: admin }); + + // Prepare reenter + const data = this.mock.contract.methods + .execute( + reentrantOperation.target, + reentrantOperation.value, + reentrantOperation.data, + reentrantOperation.predecessor, + reentrantOperation.salt, + ) + .encodeABI(); + await reentrant.enableRentrancy(this.mock.address, data); + + // Expect to fail + await expectRevertCustomError( + this.mock.execute( + reentrantOperation.target, + reentrantOperation.value, + reentrantOperation.data, + reentrantOperation.predecessor, + reentrantOperation.salt, + { from: executor }, + ), + 'TimelockUnexpectedOperationState', + [reentrantOperation.id, proposalStatesToBitMap(OperationState.Ready)], + ); + + // Disable reentrancy + await reentrant.disableReentrancy(); + const nonReentrantOperation = reentrantOperation; // Not anymore + + // Try again successfully + const receipt = await this.mock.execute( + nonReentrantOperation.target, + nonReentrantOperation.value, + nonReentrantOperation.data, + nonReentrantOperation.predecessor, + nonReentrantOperation.salt, + { from: executor }, + ); + expectEvent(receipt, 'CallExecuted', { + id: nonReentrantOperation.id, + index: web3.utils.toBN(0), + target: nonReentrantOperation.target, + value: web3.utils.toBN(nonReentrantOperation.value), + data: nonReentrantOperation.data, + }); + }); + }); + }); + }); + }); + + describe('batch', function () { + describe('schedule', function () { + beforeEach(async function () { + this.operation = genOperationBatch( + Array(8).fill('0xEd912250835c812D4516BBD80BdaEA1bB63a293C'), + Array(8).fill(0), + Array(8).fill('0x2fcb7a88'), + ZERO_BYTES32, + '0x6cf9d042ade5de78bed9ffd075eb4b2a4f6b1736932c2dc8af517d6e066f51f5', + ); + }); + + it('proposer can schedule', async function () { + const receipt = await this.mock.scheduleBatch( + this.operation.targets, + this.operation.values, + this.operation.payloads, + this.operation.predecessor, + this.operation.salt, + MINDELAY, + { from: proposer }, + ); + for (const i in this.operation.targets) { + expectEvent(receipt, 'CallScheduled', { + id: this.operation.id, + index: web3.utils.toBN(i), + target: this.operation.targets[i], + value: web3.utils.toBN(this.operation.values[i]), + data: this.operation.payloads[i], + predecessor: this.operation.predecessor, + delay: MINDELAY, + }); + + expectEvent(receipt, 'CallSalt', { + id: this.operation.id, + salt: this.operation.salt, + }); + } + + const block = await web3.eth.getBlock(receipt.receipt.blockHash); + + expect(await this.mock.getTimestamp(this.operation.id)).to.be.bignumber.equal( + web3.utils.toBN(block.timestamp).add(MINDELAY), + ); + }); + + it('prevent overwriting active operation', async function () { + await this.mock.scheduleBatch( + this.operation.targets, + this.operation.values, + this.operation.payloads, + this.operation.predecessor, + this.operation.salt, + MINDELAY, + { from: proposer }, + ); + + await expectRevertCustomError( + this.mock.scheduleBatch( + this.operation.targets, + this.operation.values, + this.operation.payloads, + this.operation.predecessor, + this.operation.salt, + MINDELAY, + { from: proposer }, + ), + 'TimelockUnexpectedOperationState', + [this.operation.id, proposalStatesToBitMap(OperationState.Unset)], + ); + }); + + it('length of batch parameter must match #1', async function () { + await expectRevertCustomError( + this.mock.scheduleBatch( + this.operation.targets, + [], + this.operation.payloads, + this.operation.predecessor, + this.operation.salt, + MINDELAY, + { from: proposer }, + ), + 'TimelockInvalidOperationLength', + [this.operation.targets.length, this.operation.payloads.length, 0], + ); + }); + + it('length of batch parameter must match #1', async function () { + await expectRevertCustomError( + this.mock.scheduleBatch( + this.operation.targets, + this.operation.values, + [], + this.operation.predecessor, + this.operation.salt, + MINDELAY, + { from: proposer }, + ), + 'TimelockInvalidOperationLength', + [this.operation.targets.length, 0, this.operation.payloads.length], + ); + }); + + it('prevent non-proposer from committing', async function () { + await expectRevertCustomError( + this.mock.scheduleBatch( + this.operation.targets, + this.operation.values, + this.operation.payloads, + this.operation.predecessor, + this.operation.salt, + MINDELAY, + { from: other }, + ), + `AccessControlUnauthorizedAccount`, + [other, PROPOSER_ROLE], + ); + }); + + it('enforce minimum delay', async function () { + await expectRevertCustomError( + this.mock.scheduleBatch( + this.operation.targets, + this.operation.values, + this.operation.payloads, + this.operation.predecessor, + this.operation.salt, + MINDELAY - 1, + { from: proposer }, + ), + 'TimelockInsufficientDelay', + [MINDELAY, MINDELAY - 1], + ); + }); + }); + + describe('execute', function () { + beforeEach(async function () { + this.operation = genOperationBatch( + Array(8).fill('0x76E53CcEb05131Ef5248553bEBDb8F70536830b1'), + Array(8).fill(0), + Array(8).fill('0x58a60f63'), + ZERO_BYTES32, + '0x9545eeabc7a7586689191f78a5532443698538e54211b5bd4d7dc0fc0102b5c7', + ); + }); + + it('revert if operation is not scheduled', async function () { + await expectRevertCustomError( + this.mock.executeBatch( + this.operation.targets, + this.operation.values, + this.operation.payloads, + this.operation.predecessor, + this.operation.salt, + { from: executor }, + ), + 'TimelockUnexpectedOperationState', + [this.operation.id, proposalStatesToBitMap(OperationState.Ready)], + ); + }); + + describe('with scheduled operation', function () { + beforeEach(async function () { + ({ receipt: this.receipt, logs: this.logs } = await this.mock.scheduleBatch( + this.operation.targets, + this.operation.values, + this.operation.payloads, + this.operation.predecessor, + this.operation.salt, + MINDELAY, + { from: proposer }, + )); + }); + + it('revert if execution comes too early 1/2', async function () { + await expectRevertCustomError( + this.mock.executeBatch( + this.operation.targets, + this.operation.values, + this.operation.payloads, + this.operation.predecessor, + this.operation.salt, + { from: executor }, + ), + 'TimelockUnexpectedOperationState', + [this.operation.id, proposalStatesToBitMap(OperationState.Ready)], + ); + }); + + it('revert if execution comes too early 2/2', async function () { + const timestamp = await this.mock.getTimestamp(this.operation.id); + await time.increaseTo(timestamp - 5); // -1 is to tight, test sometime fails + + await expectRevertCustomError( + this.mock.executeBatch( + this.operation.targets, + this.operation.values, + this.operation.payloads, + this.operation.predecessor, + this.operation.salt, + { from: executor }, + ), + 'TimelockUnexpectedOperationState', + [this.operation.id, proposalStatesToBitMap(OperationState.Ready)], + ); + }); + + describe('on time', function () { + beforeEach(async function () { + const timestamp = await this.mock.getTimestamp(this.operation.id); + await time.increaseTo(timestamp); + }); + + it('executor can reveal', async function () { + const receipt = await this.mock.executeBatch( + this.operation.targets, + this.operation.values, + this.operation.payloads, + this.operation.predecessor, + this.operation.salt, + { from: executor }, + ); + for (const i in this.operation.targets) { + expectEvent(receipt, 'CallExecuted', { + id: this.operation.id, + index: web3.utils.toBN(i), + target: this.operation.targets[i], + value: web3.utils.toBN(this.operation.values[i]), + data: this.operation.payloads[i], + }); + } + }); + + it('prevent non-executor from revealing', async function () { + await expectRevertCustomError( + this.mock.executeBatch( + this.operation.targets, + this.operation.values, + this.operation.payloads, + this.operation.predecessor, + this.operation.salt, + { from: other }, + ), + `AccessControlUnauthorizedAccount`, + [other, EXECUTOR_ROLE], + ); + }); + + it('length mismatch #1', async function () { + await expectRevertCustomError( + this.mock.executeBatch( + [], + this.operation.values, + this.operation.payloads, + this.operation.predecessor, + this.operation.salt, + { from: executor }, + ), + 'TimelockInvalidOperationLength', + [0, this.operation.payloads.length, this.operation.values.length], + ); + }); + + it('length mismatch #2', async function () { + await expectRevertCustomError( + this.mock.executeBatch( + this.operation.targets, + [], + this.operation.payloads, + this.operation.predecessor, + this.operation.salt, + { from: executor }, + ), + 'TimelockInvalidOperationLength', + [this.operation.targets.length, this.operation.payloads.length, 0], + ); + }); + + it('length mismatch #3', async function () { + await expectRevertCustomError( + this.mock.executeBatch( + this.operation.targets, + this.operation.values, + [], + this.operation.predecessor, + this.operation.salt, + { from: executor }, + ), + 'TimelockInvalidOperationLength', + [this.operation.targets.length, 0, this.operation.values.length], + ); + }); + + it('prevents reentrancy execution', async function () { + // Create operation + const reentrant = await TimelockReentrant.new(); + const reentrantBatchOperation = genOperationBatch( + [reentrant.address], + [0], + [reentrant.contract.methods.reenter().encodeABI()], + ZERO_BYTES32, + salt, + ); + + // Schedule so it can be executed + await this.mock.scheduleBatch( + reentrantBatchOperation.targets, + reentrantBatchOperation.values, + reentrantBatchOperation.payloads, + reentrantBatchOperation.predecessor, + reentrantBatchOperation.salt, + MINDELAY, + { from: proposer }, + ); + + // Advance on time to make the operation executable + const timestamp = await this.mock.getTimestamp(reentrantBatchOperation.id); + await time.increaseTo(timestamp); + + // Grant executor role to the reentrant contract + await this.mock.grantRole(EXECUTOR_ROLE, reentrant.address, { from: admin }); + + // Prepare reenter + const data = this.mock.contract.methods + .executeBatch( + reentrantBatchOperation.targets, + reentrantBatchOperation.values, + reentrantBatchOperation.payloads, + reentrantBatchOperation.predecessor, + reentrantBatchOperation.salt, + ) + .encodeABI(); + await reentrant.enableRentrancy(this.mock.address, data); + + // Expect to fail + await expectRevertCustomError( + this.mock.executeBatch( + reentrantBatchOperation.targets, + reentrantBatchOperation.values, + reentrantBatchOperation.payloads, + reentrantBatchOperation.predecessor, + reentrantBatchOperation.salt, + { from: executor }, + ), + 'TimelockUnexpectedOperationState', + [reentrantBatchOperation.id, proposalStatesToBitMap(OperationState.Ready)], + ); + + // Disable reentrancy + await reentrant.disableReentrancy(); + const nonReentrantBatchOperation = reentrantBatchOperation; // Not anymore + + // Try again successfully + const receipt = await this.mock.executeBatch( + nonReentrantBatchOperation.targets, + nonReentrantBatchOperation.values, + nonReentrantBatchOperation.payloads, + nonReentrantBatchOperation.predecessor, + nonReentrantBatchOperation.salt, + { from: executor }, + ); + for (const i in nonReentrantBatchOperation.targets) { + expectEvent(receipt, 'CallExecuted', { + id: nonReentrantBatchOperation.id, + index: web3.utils.toBN(i), + target: nonReentrantBatchOperation.targets[i], + value: web3.utils.toBN(nonReentrantBatchOperation.values[i]), + data: nonReentrantBatchOperation.payloads[i], + }); + } + }); + }); + }); + + it('partial execution', async function () { + const operation = genOperationBatch( + [this.callreceivermock.address, this.callreceivermock.address, this.callreceivermock.address], + [0, 0, 0], + [ + this.callreceivermock.contract.methods.mockFunction().encodeABI(), + this.callreceivermock.contract.methods.mockFunctionRevertsNoReason().encodeABI(), + this.callreceivermock.contract.methods.mockFunction().encodeABI(), + ], + ZERO_BYTES32, + '0x8ac04aa0d6d66b8812fb41d39638d37af0a9ab11da507afd65c509f8ed079d3e', + ); + + await this.mock.scheduleBatch( + operation.targets, + operation.values, + operation.payloads, + operation.predecessor, + operation.salt, + MINDELAY, + { from: proposer }, + ); + await time.increase(MINDELAY); + await expectRevertCustomError( + this.mock.executeBatch( + operation.targets, + operation.values, + operation.payloads, + operation.predecessor, + operation.salt, + { from: executor }, + ), + 'FailedInnerCall', + [], + ); + }); + }); + }); + + describe('cancel', function () { + beforeEach(async function () { + this.operation = genOperation( + '0xC6837c44AA376dbe1d2709F13879E040CAb653ca', + 0, + '0x296e58dd', + ZERO_BYTES32, + '0xa2485763600634800df9fc9646fb2c112cf98649c55f63dd1d9c7d13a64399d9', + ); + ({ receipt: this.receipt, logs: this.logs } = await this.mock.schedule( + this.operation.target, + this.operation.value, + this.operation.data, + this.operation.predecessor, + this.operation.salt, + MINDELAY, + { from: proposer }, + )); + }); + + it('canceller can cancel', async function () { + const receipt = await this.mock.cancel(this.operation.id, { from: canceller }); + expectEvent(receipt, 'Cancelled', { id: this.operation.id }); + }); + + it('cannot cancel invalid operation', async function () { + await expectRevertCustomError( + this.mock.cancel(constants.ZERO_BYTES32, { from: canceller }), + 'TimelockUnexpectedOperationState', + [constants.ZERO_BYTES32, proposalStatesToBitMap([OperationState.Waiting, OperationState.Ready])], + ); + }); + + it('prevent non-canceller from canceling', async function () { + await expectRevertCustomError( + this.mock.cancel(this.operation.id, { from: other }), + `AccessControlUnauthorizedAccount`, + [other, CANCELLER_ROLE], + ); + }); + }); + }); + + describe('maintenance', function () { + it('prevent unauthorized maintenance', async function () { + await expectRevertCustomError(this.mock.updateDelay(0, { from: other }), 'TimelockUnauthorizedCaller', [other]); + }); + + it('timelock scheduled maintenance', async function () { + const newDelay = time.duration.hours(6); + const operation = genOperation( + this.mock.address, + 0, + this.mock.contract.methods.updateDelay(newDelay.toString()).encodeABI(), + ZERO_BYTES32, + '0xf8e775b2c5f4d66fb5c7fa800f35ef518c262b6014b3c0aee6ea21bff157f108', + ); + + await this.mock.schedule( + operation.target, + operation.value, + operation.data, + operation.predecessor, + operation.salt, + MINDELAY, + { from: proposer }, + ); + await time.increase(MINDELAY); + const receipt = await this.mock.execute( + operation.target, + operation.value, + operation.data, + operation.predecessor, + operation.salt, + { from: executor }, + ); + expectEvent(receipt, 'MinDelayChange', { newDuration: newDelay.toString(), oldDuration: MINDELAY }); + + expect(await this.mock.getMinDelay()).to.be.bignumber.equal(newDelay); + }); + }); + + describe('dependency', function () { + beforeEach(async function () { + this.operation1 = genOperation( + '0xdE66bD4c97304200A95aE0AadA32d6d01A867E39', + 0, + '0x01dc731a', + ZERO_BYTES32, + '0x64e932133c7677402ead2926f86205e2ca4686aebecf5a8077627092b9bb2feb', + ); + this.operation2 = genOperation( + '0x3c7944a3F1ee7fc8c5A5134ba7c79D11c3A1FCa3', + 0, + '0x8f531849', + this.operation1.id, + '0x036e1311cac523f9548e6461e29fb1f8f9196b91910a41711ea22f5de48df07d', + ); + await this.mock.schedule( + this.operation1.target, + this.operation1.value, + this.operation1.data, + this.operation1.predecessor, + this.operation1.salt, + MINDELAY, + { from: proposer }, + ); + await this.mock.schedule( + this.operation2.target, + this.operation2.value, + this.operation2.data, + this.operation2.predecessor, + this.operation2.salt, + MINDELAY, + { from: proposer }, + ); + await time.increase(MINDELAY); + }); + + it('cannot execute before dependency', async function () { + await expectRevertCustomError( + this.mock.execute( + this.operation2.target, + this.operation2.value, + this.operation2.data, + this.operation2.predecessor, + this.operation2.salt, + { from: executor }, + ), + 'TimelockUnexecutedPredecessor', + [this.operation1.id], + ); + }); + + it('can execute after dependency', async function () { + await this.mock.execute( + this.operation1.target, + this.operation1.value, + this.operation1.data, + this.operation1.predecessor, + this.operation1.salt, + { from: executor }, + ); + await this.mock.execute( + this.operation2.target, + this.operation2.value, + this.operation2.data, + this.operation2.predecessor, + this.operation2.salt, + { from: executor }, + ); + }); + }); + + describe('usage scenario', function () { + this.timeout(10000); + + it('call', async function () { + const operation = genOperation( + this.implementation2.address, + 0, + this.implementation2.contract.methods.setValue(42).encodeABI(), + ZERO_BYTES32, + '0x8043596363daefc89977b25f9d9b4d06c3910959ef0c4d213557a903e1b555e2', + ); + + await this.mock.schedule( + operation.target, + operation.value, + operation.data, + operation.predecessor, + operation.salt, + MINDELAY, + { from: proposer }, + ); + await time.increase(MINDELAY); + await this.mock.execute( + operation.target, + operation.value, + operation.data, + operation.predecessor, + operation.salt, + { from: executor }, + ); + + expect(await this.implementation2.getValue()).to.be.bignumber.equal(web3.utils.toBN(42)); + }); + + it('call reverting', async function () { + const operation = genOperation( + this.callreceivermock.address, + 0, + this.callreceivermock.contract.methods.mockFunctionRevertsNoReason().encodeABI(), + ZERO_BYTES32, + '0xb1b1b276fdf1a28d1e00537ea73b04d56639128b08063c1a2f70a52e38cba693', + ); + + await this.mock.schedule( + operation.target, + operation.value, + operation.data, + operation.predecessor, + operation.salt, + MINDELAY, + { from: proposer }, + ); + await time.increase(MINDELAY); + await expectRevertCustomError( + this.mock.execute(operation.target, operation.value, operation.data, operation.predecessor, operation.salt, { + from: executor, + }), + 'FailedInnerCall', + [], + ); + }); + + it('call throw', async function () { + const operation = genOperation( + this.callreceivermock.address, + 0, + this.callreceivermock.contract.methods.mockFunctionThrows().encodeABI(), + ZERO_BYTES32, + '0xe5ca79f295fc8327ee8a765fe19afb58f4a0cbc5053642bfdd7e73bc68e0fc67', + ); + + await this.mock.schedule( + operation.target, + operation.value, + operation.data, + operation.predecessor, + operation.salt, + MINDELAY, + { from: proposer }, + ); + await time.increase(MINDELAY); + // Targeted function reverts with a panic code (0x1) + the timelock bubble the panic code + await expectRevert.unspecified( + this.mock.execute(operation.target, operation.value, operation.data, operation.predecessor, operation.salt, { + from: executor, + }), + ); + }); + + it('call out of gas', async function () { + const operation = genOperation( + this.callreceivermock.address, + 0, + this.callreceivermock.contract.methods.mockFunctionOutOfGas().encodeABI(), + ZERO_BYTES32, + '0xf3274ce7c394c5b629d5215723563a744b817e1730cca5587c567099a14578fd', + ); + + await this.mock.schedule( + operation.target, + operation.value, + operation.data, + operation.predecessor, + operation.salt, + MINDELAY, + { from: proposer }, + ); + await time.increase(MINDELAY); + await expectRevertCustomError( + this.mock.execute(operation.target, operation.value, operation.data, operation.predecessor, operation.salt, { + from: executor, + gas: '100000', + }), + 'FailedInnerCall', + [], + ); + }); + + it('call payable with eth', async function () { + const operation = genOperation( + this.callreceivermock.address, + 1, + this.callreceivermock.contract.methods.mockFunction().encodeABI(), + ZERO_BYTES32, + '0x5ab73cd33477dcd36c1e05e28362719d0ed59a7b9ff14939de63a43073dc1f44', + ); + + await this.mock.schedule( + operation.target, + operation.value, + operation.data, + operation.predecessor, + operation.salt, + MINDELAY, + { from: proposer }, + ); + await time.increase(MINDELAY); + + expect(await web3.eth.getBalance(this.mock.address)).to.be.bignumber.equal(web3.utils.toBN(0)); + expect(await web3.eth.getBalance(this.callreceivermock.address)).to.be.bignumber.equal(web3.utils.toBN(0)); + + await this.mock.execute( + operation.target, + operation.value, + operation.data, + operation.predecessor, + operation.salt, + { from: executor, value: 1 }, + ); + + expect(await web3.eth.getBalance(this.mock.address)).to.be.bignumber.equal(web3.utils.toBN(0)); + expect(await web3.eth.getBalance(this.callreceivermock.address)).to.be.bignumber.equal(web3.utils.toBN(1)); + }); + + it('call nonpayable with eth', async function () { + const operation = genOperation( + this.callreceivermock.address, + 1, + this.callreceivermock.contract.methods.mockFunctionNonPayable().encodeABI(), + ZERO_BYTES32, + '0xb78edbd920c7867f187e5aa6294ae5a656cfbf0dea1ccdca3751b740d0f2bdf8', + ); + + await this.mock.schedule( + operation.target, + operation.value, + operation.data, + operation.predecessor, + operation.salt, + MINDELAY, + { from: proposer }, + ); + await time.increase(MINDELAY); + + expect(await web3.eth.getBalance(this.mock.address)).to.be.bignumber.equal(web3.utils.toBN(0)); + expect(await web3.eth.getBalance(this.callreceivermock.address)).to.be.bignumber.equal(web3.utils.toBN(0)); + + await expectRevertCustomError( + this.mock.execute(operation.target, operation.value, operation.data, operation.predecessor, operation.salt, { + from: executor, + }), + 'FailedInnerCall', + [], + ); + + expect(await web3.eth.getBalance(this.mock.address)).to.be.bignumber.equal(web3.utils.toBN(0)); + expect(await web3.eth.getBalance(this.callreceivermock.address)).to.be.bignumber.equal(web3.utils.toBN(0)); + }); + + it('call reverting with eth', async function () { + const operation = genOperation( + this.callreceivermock.address, + 1, + this.callreceivermock.contract.methods.mockFunctionRevertsNoReason().encodeABI(), + ZERO_BYTES32, + '0xdedb4563ef0095db01d81d3f2decf57cf83e4a72aa792af14c43a792b56f4de6', + ); + + await this.mock.schedule( + operation.target, + operation.value, + operation.data, + operation.predecessor, + operation.salt, + MINDELAY, + { from: proposer }, + ); + await time.increase(MINDELAY); + + expect(await web3.eth.getBalance(this.mock.address)).to.be.bignumber.equal(web3.utils.toBN(0)); + expect(await web3.eth.getBalance(this.callreceivermock.address)).to.be.bignumber.equal(web3.utils.toBN(0)); + + await expectRevertCustomError( + this.mock.execute(operation.target, operation.value, operation.data, operation.predecessor, operation.salt, { + from: executor, + }), + 'FailedInnerCall', + [], + ); + + expect(await web3.eth.getBalance(this.mock.address)).to.be.bignumber.equal(web3.utils.toBN(0)); + expect(await web3.eth.getBalance(this.callreceivermock.address)).to.be.bignumber.equal(web3.utils.toBN(0)); + }); + }); + + describe('safe receive', function () { + describe('ERC721', function () { + const name = 'Non Fungible Token'; + const symbol = 'NFT'; + const tokenId = new BN(1); + + beforeEach(async function () { + this.token = await ERC721.new(name, symbol); + await this.token.$_mint(other, tokenId); + }); + + it('can receive an ERC721 safeTransfer', async function () { + await this.token.safeTransferFrom(other, this.mock.address, tokenId, { from: other }); + }); + }); + + describe('ERC1155', function () { + const uri = 'https://token-cdn-domain/{id}.json'; + const tokenIds = { + 1: new BN(1000), + 2: new BN(2000), + 3: new BN(3000), + }; + + beforeEach(async function () { + this.token = await ERC1155.new(uri); + await this.token.$_mintBatch(other, Object.keys(tokenIds), Object.values(tokenIds), '0x'); + }); + + it('can receive ERC1155 safeTransfer', async function () { + await this.token.safeTransferFrom( + other, + this.mock.address, + ...Object.entries(tokenIds)[0], // id + amount + '0x', + { from: other }, + ); + }); + + it('can receive ERC1155 safeBatchTransfer', async function () { + await this.token.safeBatchTransferFrom( + other, + this.mock.address, + Object.keys(tokenIds), + Object.values(tokenIds), + '0x', + { from: other }, + ); + }); + }); + }); +}); diff --git a/test/governance/extensions/GovernorERC721.test.js b/test/governance/extensions/GovernorERC721.test.js new file mode 100644 index 000000000..22265cc25 --- /dev/null +++ b/test/governance/extensions/GovernorERC721.test.js @@ -0,0 +1,116 @@ +const { expectEvent } = require('@openzeppelin/test-helpers'); +const { expect } = require('chai'); + +const Enums = require('../../helpers/enums'); +const { GovernorHelper } = require('../../helpers/governance'); + +const Governor = artifacts.require('$GovernorVoteMocks'); +const CallReceiver = artifacts.require('CallReceiverMock'); + +const TOKENS = [ + { Token: artifacts.require('$ERC721Votes'), mode: 'blocknumber' }, + { Token: artifacts.require('$ERC721VotesTimestampMock'), mode: 'timestamp' }, +]; + +contract('GovernorERC721', function (accounts) { + const [owner, voter1, voter2, voter3, voter4] = accounts; + + const name = 'OZ-Governor'; + const version = '1'; + const tokenName = 'MockNFToken'; + const tokenSymbol = 'MTKN'; + const NFT0 = web3.utils.toBN(0); + const NFT1 = web3.utils.toBN(1); + const NFT2 = web3.utils.toBN(2); + const NFT3 = web3.utils.toBN(3); + const NFT4 = web3.utils.toBN(4); + const votingDelay = web3.utils.toBN(4); + const votingPeriod = web3.utils.toBN(16); + const value = web3.utils.toWei('1'); + + for (const { mode, Token } of TOKENS) { + describe(`using ${Token._json.contractName}`, function () { + beforeEach(async function () { + this.owner = owner; + this.token = await Token.new(tokenName, tokenSymbol, tokenName, version); + this.mock = await Governor.new(name, this.token.address); + this.receiver = await CallReceiver.new(); + + this.helper = new GovernorHelper(this.mock, mode); + + await web3.eth.sendTransaction({ from: owner, to: this.mock.address, value }); + + await Promise.all([NFT0, NFT1, NFT2, NFT3, NFT4].map(tokenId => this.token.$_mint(owner, tokenId))); + await this.helper.delegate({ token: this.token, to: voter1, tokenId: NFT0 }, { from: owner }); + await this.helper.delegate({ token: this.token, to: voter2, tokenId: NFT1 }, { from: owner }); + await this.helper.delegate({ token: this.token, to: voter2, tokenId: NFT2 }, { from: owner }); + await this.helper.delegate({ token: this.token, to: voter3, tokenId: NFT3 }, { from: owner }); + await this.helper.delegate({ token: this.token, to: voter4, tokenId: NFT4 }, { from: owner }); + + // default proposal + this.proposal = this.helper.setProposal( + [ + { + target: this.receiver.address, + value, + data: this.receiver.contract.methods.mockFunction().encodeABI(), + }, + ], + '', + ); + }); + + it('deployment check', async function () { + expect(await this.mock.name()).to.be.equal(name); + expect(await this.mock.token()).to.be.equal(this.token.address); + expect(await this.mock.votingDelay()).to.be.bignumber.equal(votingDelay); + expect(await this.mock.votingPeriod()).to.be.bignumber.equal(votingPeriod); + expect(await this.mock.quorum(0)).to.be.bignumber.equal('0'); + }); + + it('voting with ERC721 token', async function () { + await this.helper.propose(); + await this.helper.waitForSnapshot(); + + expectEvent(await this.helper.vote({ support: Enums.VoteType.For }, { from: voter1 }), 'VoteCast', { + voter: voter1, + support: Enums.VoteType.For, + weight: '1', + }); + + expectEvent(await this.helper.vote({ support: Enums.VoteType.For }, { from: voter2 }), 'VoteCast', { + voter: voter2, + support: Enums.VoteType.For, + weight: '2', + }); + + expectEvent(await this.helper.vote({ support: Enums.VoteType.Against }, { from: voter3 }), 'VoteCast', { + voter: voter3, + support: Enums.VoteType.Against, + weight: '1', + }); + + expectEvent(await this.helper.vote({ support: Enums.VoteType.Abstain }, { from: voter4 }), 'VoteCast', { + voter: voter4, + support: Enums.VoteType.Abstain, + weight: '1', + }); + + await this.helper.waitForDeadline(); + await this.helper.execute(); + + expect(await this.mock.hasVoted(this.proposal.id, owner)).to.be.equal(false); + expect(await this.mock.hasVoted(this.proposal.id, voter1)).to.be.equal(true); + expect(await this.mock.hasVoted(this.proposal.id, voter2)).to.be.equal(true); + expect(await this.mock.hasVoted(this.proposal.id, voter3)).to.be.equal(true); + expect(await this.mock.hasVoted(this.proposal.id, voter4)).to.be.equal(true); + + await this.mock.proposalVotes(this.proposal.id).then(results => { + expect(results.forVotes).to.be.bignumber.equal('3'); + expect(results.againstVotes).to.be.bignumber.equal('1'); + expect(results.abstainVotes).to.be.bignumber.equal('1'); + }); + }); + }); + } +}); diff --git a/test/governance/extensions/GovernorPreventLateQuorum.test.js b/test/governance/extensions/GovernorPreventLateQuorum.test.js new file mode 100644 index 000000000..17ae05a73 --- /dev/null +++ b/test/governance/extensions/GovernorPreventLateQuorum.test.js @@ -0,0 +1,195 @@ +const { expectEvent } = require('@openzeppelin/test-helpers'); +const { expect } = require('chai'); + +const Enums = require('../../helpers/enums'); +const { GovernorHelper } = require('../../helpers/governance'); +const { clockFromReceipt } = require('../../helpers/time'); +const { expectRevertCustomError } = require('../../helpers/customError'); + +const Governor = artifacts.require('$GovernorPreventLateQuorumMock'); +const CallReceiver = artifacts.require('CallReceiverMock'); + +const TOKENS = [ + { Token: artifacts.require('$ERC20Votes'), mode: 'blocknumber' }, + { Token: artifacts.require('$ERC20VotesTimestampMock'), mode: 'timestamp' }, +]; + +contract('GovernorPreventLateQuorum', function (accounts) { + const [owner, proposer, voter1, voter2, voter3, voter4] = accounts; + + const name = 'OZ-Governor'; + const version = '1'; + const tokenName = 'MockToken'; + const tokenSymbol = 'MTKN'; + const tokenSupply = web3.utils.toWei('100'); + const votingDelay = web3.utils.toBN(4); + const votingPeriod = web3.utils.toBN(16); + const lateQuorumVoteExtension = web3.utils.toBN(8); + const quorum = web3.utils.toWei('1'); + const value = web3.utils.toWei('1'); + + for (const { mode, Token } of TOKENS) { + describe(`using ${Token._json.contractName}`, function () { + beforeEach(async function () { + this.owner = owner; + this.token = await Token.new(tokenName, tokenSymbol, tokenName, version); + this.mock = await Governor.new( + name, + votingDelay, + votingPeriod, + 0, + this.token.address, + lateQuorumVoteExtension, + quorum, + ); + this.receiver = await CallReceiver.new(); + + this.helper = new GovernorHelper(this.mock, mode); + + await web3.eth.sendTransaction({ from: owner, to: this.mock.address, value }); + + await this.token.$_mint(owner, tokenSupply); + await this.helper.delegate({ token: this.token, to: voter1, value: web3.utils.toWei('10') }, { from: owner }); + await this.helper.delegate({ token: this.token, to: voter2, value: web3.utils.toWei('7') }, { from: owner }); + await this.helper.delegate({ token: this.token, to: voter3, value: web3.utils.toWei('5') }, { from: owner }); + await this.helper.delegate({ token: this.token, to: voter4, value: web3.utils.toWei('2') }, { from: owner }); + + // default proposal + this.proposal = this.helper.setProposal( + [ + { + target: this.receiver.address, + value, + data: this.receiver.contract.methods.mockFunction().encodeABI(), + }, + ], + '', + ); + }); + + it('deployment check', async function () { + expect(await this.mock.name()).to.be.equal(name); + expect(await this.mock.token()).to.be.equal(this.token.address); + expect(await this.mock.votingDelay()).to.be.bignumber.equal(votingDelay); + expect(await this.mock.votingPeriod()).to.be.bignumber.equal(votingPeriod); + expect(await this.mock.quorum(0)).to.be.bignumber.equal(quorum); + expect(await this.mock.lateQuorumVoteExtension()).to.be.bignumber.equal(lateQuorumVoteExtension); + }); + + it('nominal workflow unaffected', async function () { + const txPropose = await this.helper.propose({ from: proposer }); + await this.helper.waitForSnapshot(); + await this.helper.vote({ support: Enums.VoteType.For }, { from: voter1 }); + await this.helper.vote({ support: Enums.VoteType.For }, { from: voter2 }); + await this.helper.vote({ support: Enums.VoteType.Against }, { from: voter3 }); + await this.helper.vote({ support: Enums.VoteType.Abstain }, { from: voter4 }); + await this.helper.waitForDeadline(); + await this.helper.execute(); + + expect(await this.mock.hasVoted(this.proposal.id, owner)).to.be.equal(false); + expect(await this.mock.hasVoted(this.proposal.id, voter1)).to.be.equal(true); + expect(await this.mock.hasVoted(this.proposal.id, voter2)).to.be.equal(true); + expect(await this.mock.hasVoted(this.proposal.id, voter3)).to.be.equal(true); + expect(await this.mock.hasVoted(this.proposal.id, voter4)).to.be.equal(true); + + await this.mock.proposalVotes(this.proposal.id).then(results => { + expect(results.forVotes).to.be.bignumber.equal(web3.utils.toWei('17')); + expect(results.againstVotes).to.be.bignumber.equal(web3.utils.toWei('5')); + expect(results.abstainVotes).to.be.bignumber.equal(web3.utils.toWei('2')); + }); + + const voteStart = web3.utils.toBN(await clockFromReceipt[mode](txPropose.receipt)).add(votingDelay); + const voteEnd = web3.utils + .toBN(await clockFromReceipt[mode](txPropose.receipt)) + .add(votingDelay) + .add(votingPeriod); + expect(await this.mock.proposalSnapshot(this.proposal.id)).to.be.bignumber.equal(voteStart); + expect(await this.mock.proposalDeadline(this.proposal.id)).to.be.bignumber.equal(voteEnd); + + expectEvent(txPropose, 'ProposalCreated', { + proposalId: this.proposal.id, + proposer, + targets: this.proposal.targets, + // values: this.proposal.values.map(value => web3.utils.toBN(value)), + signatures: this.proposal.signatures, + calldatas: this.proposal.data, + voteStart, + voteEnd, + description: this.proposal.description, + }); + }); + + it('Delay is extended to prevent last minute take-over', async function () { + const txPropose = await this.helper.propose({ from: proposer }); + + // compute original schedule + const startBlock = web3.utils.toBN(await clockFromReceipt[mode](txPropose.receipt)).add(votingDelay); + const endBlock = web3.utils + .toBN(await clockFromReceipt[mode](txPropose.receipt)) + .add(votingDelay) + .add(votingPeriod); + expect(await this.mock.proposalSnapshot(this.proposal.id)).to.be.bignumber.equal(startBlock); + expect(await this.mock.proposalDeadline(this.proposal.id)).to.be.bignumber.equal(endBlock); + + // wait for the last minute to vote + await this.helper.waitForDeadline(-1); + const txVote = await this.helper.vote({ support: Enums.VoteType.For }, { from: voter2 }); + + // cannot execute yet + expect(await this.mock.state(this.proposal.id)).to.be.bignumber.equal(Enums.ProposalState.Active); + + // compute new extended schedule + const extendedDeadline = web3.utils + .toBN(await clockFromReceipt[mode](txVote.receipt)) + .add(lateQuorumVoteExtension); + expect(await this.mock.proposalSnapshot(this.proposal.id)).to.be.bignumber.equal(startBlock); + expect(await this.mock.proposalDeadline(this.proposal.id)).to.be.bignumber.equal(extendedDeadline); + + // still possible to vote + await this.helper.vote({ support: Enums.VoteType.Against }, { from: voter1 }); + + await this.helper.waitForDeadline(); + expect(await this.mock.state(this.proposal.id)).to.be.bignumber.equal(Enums.ProposalState.Active); + await this.helper.waitForDeadline(+1); + expect(await this.mock.state(this.proposal.id)).to.be.bignumber.equal(Enums.ProposalState.Defeated); + + // check extension event + expectEvent(txVote, 'ProposalExtended', { proposalId: this.proposal.id, extendedDeadline }); + }); + + describe('onlyGovernance updates', function () { + it('setLateQuorumVoteExtension is protected', async function () { + await expectRevertCustomError( + this.mock.setLateQuorumVoteExtension(0, { from: owner }), + 'GovernorOnlyExecutor', + [owner], + ); + }); + + it('can setLateQuorumVoteExtension through governance', async function () { + this.helper.setProposal( + [ + { + target: this.mock.address, + data: this.mock.contract.methods.setLateQuorumVoteExtension('0').encodeABI(), + }, + ], + '', + ); + + await this.helper.propose(); + await this.helper.waitForSnapshot(); + await this.helper.vote({ support: Enums.VoteType.For }, { from: voter1 }); + await this.helper.waitForDeadline(); + + expectEvent(await this.helper.execute(), 'LateQuorumVoteExtensionSet', { + oldVoteExtension: lateQuorumVoteExtension, + newVoteExtension: '0', + }); + + expect(await this.mock.lateQuorumVoteExtension()).to.be.bignumber.equal('0'); + }); + }); + }); + } +}); diff --git a/test/governance/extensions/GovernorStorage.test.js b/test/governance/extensions/GovernorStorage.test.js new file mode 100644 index 000000000..99a97886c --- /dev/null +++ b/test/governance/extensions/GovernorStorage.test.js @@ -0,0 +1,150 @@ +const { constants, expectEvent, expectRevert } = require('@openzeppelin/test-helpers'); +const { expect } = require('chai'); + +const { expectRevertCustomError } = require('../../helpers/customError'); +const Enums = require('../../helpers/enums'); +const { GovernorHelper, timelockSalt } = require('../../helpers/governance'); + +const Timelock = artifacts.require('TimelockController'); +const Governor = artifacts.require('$GovernorStorageMock'); +const CallReceiver = artifacts.require('CallReceiverMock'); + +const TOKENS = [ + { Token: artifacts.require('$ERC20Votes'), mode: 'blocknumber' }, + { Token: artifacts.require('$ERC20VotesTimestampMock'), mode: 'timestamp' }, +]; + +contract('GovernorStorage', function (accounts) { + const [owner, voter1, voter2, voter3, voter4] = accounts; + + const DEFAULT_ADMIN_ROLE = '0x0000000000000000000000000000000000000000000000000000000000000000'; + const PROPOSER_ROLE = web3.utils.soliditySha3('PROPOSER_ROLE'); + const EXECUTOR_ROLE = web3.utils.soliditySha3('EXECUTOR_ROLE'); + const CANCELLER_ROLE = web3.utils.soliditySha3('CANCELLER_ROLE'); + + const name = 'OZ-Governor'; + const version = '1'; + const tokenName = 'MockToken'; + const tokenSymbol = 'MTKN'; + const tokenSupply = web3.utils.toWei('100'); + const votingDelay = web3.utils.toBN(4); + const votingPeriod = web3.utils.toBN(16); + const value = web3.utils.toWei('1'); + + for (const { mode, Token } of TOKENS) { + describe(`using ${Token._json.contractName}`, function () { + beforeEach(async function () { + const [deployer] = await web3.eth.getAccounts(); + + this.token = await Token.new(tokenName, tokenSymbol, tokenName, version); + this.timelock = await Timelock.new(3600, [], [], deployer); + this.mock = await Governor.new( + name, + votingDelay, + votingPeriod, + 0, + this.timelock.address, + this.token.address, + 0, + ); + this.receiver = await CallReceiver.new(); + + this.helper = new GovernorHelper(this.mock, mode); + + await web3.eth.sendTransaction({ from: owner, to: this.timelock.address, value }); + + // normal setup: governor is proposer, everyone is executor, timelock is its own admin + await this.timelock.grantRole(PROPOSER_ROLE, this.mock.address); + await this.timelock.grantRole(PROPOSER_ROLE, owner); + await this.timelock.grantRole(CANCELLER_ROLE, this.mock.address); + await this.timelock.grantRole(CANCELLER_ROLE, owner); + await this.timelock.grantRole(EXECUTOR_ROLE, constants.ZERO_ADDRESS); + await this.timelock.revokeRole(DEFAULT_ADMIN_ROLE, deployer); + + await this.token.$_mint(owner, tokenSupply); + await this.helper.delegate({ token: this.token, to: voter1, value: web3.utils.toWei('10') }, { from: owner }); + await this.helper.delegate({ token: this.token, to: voter2, value: web3.utils.toWei('7') }, { from: owner }); + await this.helper.delegate({ token: this.token, to: voter3, value: web3.utils.toWei('5') }, { from: owner }); + await this.helper.delegate({ token: this.token, to: voter4, value: web3.utils.toWei('2') }, { from: owner }); + + // default proposal + this.proposal = this.helper.setProposal( + [ + { + target: this.receiver.address, + value, + data: this.receiver.contract.methods.mockFunction().encodeABI(), + }, + ], + '', + ); + this.proposal.timelockid = await this.timelock.hashOperationBatch( + ...this.proposal.shortProposal.slice(0, 3), + '0x0', + timelockSalt(this.mock.address, this.proposal.shortProposal[3]), + ); + }); + + describe('proposal indexing', function () { + it('before propose', async function () { + expect(await this.mock.proposalCount()).to.be.bignumber.equal('0'); + + // panic code 0x32 (out-of-bound) + await expectRevert.unspecified(this.mock.proposalDetailsAt(0)); + + await expectRevertCustomError(this.mock.proposalDetails(this.proposal.id), 'GovernorNonexistentProposal', [ + this.proposal.id, + ]); + }); + + it('after propose', async function () { + await this.helper.propose(); + + expect(await this.mock.proposalCount()).to.be.bignumber.equal('1'); + + const proposalDetailsAt0 = await this.mock.proposalDetailsAt(0); + expect(proposalDetailsAt0[0]).to.be.bignumber.equal(this.proposal.id); + expect(proposalDetailsAt0[1]).to.be.deep.equal(this.proposal.targets); + expect(proposalDetailsAt0[2].map(x => x.toString())).to.be.deep.equal(this.proposal.values); + expect(proposalDetailsAt0[3]).to.be.deep.equal(this.proposal.fulldata); + expect(proposalDetailsAt0[4]).to.be.equal(this.proposal.descriptionHash); + + const proposalDetailsForId = await this.mock.proposalDetails(this.proposal.id); + expect(proposalDetailsForId[0]).to.be.deep.equal(this.proposal.targets); + expect(proposalDetailsForId[1].map(x => x.toString())).to.be.deep.equal(this.proposal.values); + expect(proposalDetailsForId[2]).to.be.deep.equal(this.proposal.fulldata); + expect(proposalDetailsForId[3]).to.be.equal(this.proposal.descriptionHash); + }); + }); + + it('queue and execute by id', async function () { + await this.helper.propose(); + await this.helper.waitForSnapshot(); + await this.helper.vote({ support: Enums.VoteType.For }, { from: voter1 }); + await this.helper.vote({ support: Enums.VoteType.For }, { from: voter2 }); + await this.helper.vote({ support: Enums.VoteType.Against }, { from: voter3 }); + await this.helper.vote({ support: Enums.VoteType.Abstain }, { from: voter4 }); + await this.helper.waitForDeadline(); + const txQueue = await this.mock.queue(this.proposal.id); + await this.helper.waitForEta(); + const txExecute = await this.mock.execute(this.proposal.id); + + expectEvent(txQueue, 'ProposalQueued', { proposalId: this.proposal.id }); + await expectEvent.inTransaction(txQueue.tx, this.timelock, 'CallScheduled', { id: this.proposal.timelockid }); + await expectEvent.inTransaction(txQueue.tx, this.timelock, 'CallSalt', { + id: this.proposal.timelockid, + }); + + expectEvent(txExecute, 'ProposalExecuted', { proposalId: this.proposal.id }); + await expectEvent.inTransaction(txExecute.tx, this.timelock, 'CallExecuted', { id: this.proposal.timelockid }); + await expectEvent.inTransaction(txExecute.tx, this.receiver, 'MockFunctionCalled'); + }); + + it('cancel by id', async function () { + await this.helper.propose(); + const txCancel = await this.mock.cancel(this.proposal.id); + expectEvent(txCancel, 'ProposalCanceled', { proposalId: this.proposal.id }); + }); + }); + } +}); diff --git a/test/governance/extensions/GovernorTimelockAccess.test.js b/test/governance/extensions/GovernorTimelockAccess.test.js new file mode 100644 index 000000000..59ddf6dac --- /dev/null +++ b/test/governance/extensions/GovernorTimelockAccess.test.js @@ -0,0 +1,407 @@ +const { expectEvent } = require('@openzeppelin/test-helpers'); +const { expect } = require('chai'); + +const Enums = require('../../helpers/enums'); +const { GovernorHelper, proposalStatesToBitMap } = require('../../helpers/governance'); +const { expectRevertCustomError } = require('../../helpers/customError'); +const { clockFromReceipt } = require('../../helpers/time'); +const { selector } = require('../../helpers/methods'); + +const AccessManager = artifacts.require('$AccessManager'); +const Governor = artifacts.require('$GovernorTimelockAccessMock'); +const AccessManagedTarget = artifacts.require('$AccessManagedTarget'); + +const TOKENS = [ + // { Token: artifacts.require('$ERC20Votes'), mode: 'blocknumber' }, + { Token: artifacts.require('$ERC20VotesTimestampMock'), mode: 'timestamp' }, +]; + +const hashOperation = (caller, target, data) => + web3.utils.keccak256(web3.eth.abi.encodeParameters(['address', 'address', 'bytes'], [caller, target, data])); + +contract('GovernorTimelockAccess', function (accounts) { + const [admin, voter1, voter2, voter3, voter4] = accounts; + + const name = 'OZ-Governor'; + const version = '1'; + const tokenName = 'MockToken'; + const tokenSymbol = 'MTKN'; + const tokenSupply = web3.utils.toWei('100'); + const votingDelay = web3.utils.toBN(4); + const votingPeriod = web3.utils.toBN(16); + const value = web3.utils.toWei('1'); + + for (const { mode, Token } of TOKENS) { + describe(`using ${Token._json.contractName}`, function () { + beforeEach(async function () { + this.token = await Token.new(tokenName, tokenSymbol, tokenName, version); + this.manager = await AccessManager.new(admin); + this.mock = await Governor.new( + name, + votingDelay, + votingPeriod, + 0, // proposal threshold + this.manager.address, + 0, // base delay + this.token.address, + 0, // quorum + ); + this.receiver = await AccessManagedTarget.new(this.manager.address); + + this.helper = new GovernorHelper(this.mock, mode); + + await web3.eth.sendTransaction({ from: admin, to: this.mock.address, value }); + + await this.token.$_mint(admin, tokenSupply); + await this.helper.delegate({ token: this.token, to: voter1, value: web3.utils.toWei('10') }, { from: admin }); + await this.helper.delegate({ token: this.token, to: voter2, value: web3.utils.toWei('7') }, { from: admin }); + await this.helper.delegate({ token: this.token, to: voter3, value: web3.utils.toWei('5') }, { from: admin }); + await this.helper.delegate({ token: this.token, to: voter4, value: web3.utils.toWei('2') }, { from: admin }); + + // default proposals + this.restricted = {}; + this.restricted.selector = this.receiver.contract.methods.fnRestricted().encodeABI(); + this.restricted.operation = { + target: this.receiver.address, + value: '0', + data: this.restricted.selector, + }; + this.restricted.operationId = hashOperation( + this.mock.address, + this.restricted.operation.target, + this.restricted.operation.data, + ); + + this.unrestricted = {}; + this.unrestricted.selector = this.receiver.contract.methods.fnUnrestricted().encodeABI(); + this.unrestricted.operation = { + target: this.receiver.address, + value: '0', + data: this.unrestricted.selector, + }; + this.unrestricted.operationId = hashOperation( + this.mock.address, + this.unrestricted.operation.target, + this.unrestricted.operation.data, + ); + }); + + it('accepts ether transfers', async function () { + await web3.eth.sendTransaction({ from: admin, to: this.mock.address, value: 1 }); + }); + + it('post deployment check', async function () { + expect(await this.mock.name()).to.be.equal(name); + expect(await this.mock.token()).to.be.equal(this.token.address); + expect(await this.mock.votingDelay()).to.be.bignumber.equal(votingDelay); + expect(await this.mock.votingPeriod()).to.be.bignumber.equal(votingPeriod); + expect(await this.mock.quorum(0)).to.be.bignumber.equal('0'); + + expect(await this.mock.accessManager()).to.be.equal(this.manager.address); + }); + + describe('base delay only', function () { + for (const [delay, queue] of [ + [0, true], + [0, false], + [1000, true], + ]) { + it(`delay ${delay}, ${queue ? 'with' : 'without'} queuing`, async function () { + await this.mock.$_setBaseDelaySeconds(delay); + + this.proposal = await this.helper.setProposal([this.unrestricted.operation], 'descr'); + + await this.helper.propose(); + await this.helper.waitForSnapshot(); + await this.helper.vote({ support: Enums.VoteType.For }, { from: voter1 }); + await this.helper.waitForDeadline(); + if (queue) { + const txQueue = await this.helper.queue(); + expectEvent(txQueue, 'ProposalQueued', { proposalId: this.proposal.id }); + } + if (delay > 0) { + await this.helper.waitForEta(); + } + const txExecute = await this.helper.execute(); + expectEvent(txExecute, 'ProposalExecuted', { proposalId: this.proposal.id }); + expectEvent.inTransaction(txExecute, this.receiver, 'CalledUnrestricted'); + }); + } + }); + + it('single operation with access manager delay', async function () { + const delay = 1000; + const roleId = '1'; + + await this.manager.setTargetFunctionRole(this.receiver.address, [this.restricted.selector], roleId, { + from: admin, + }); + await this.manager.grantRole(roleId, this.mock.address, delay, { from: admin }); + + this.proposal = await this.helper.setProposal([this.restricted.operation], 'descr'); + + await this.helper.propose(); + await this.helper.waitForSnapshot(); + await this.helper.vote({ support: Enums.VoteType.For }, { from: voter1 }); + await this.helper.waitForDeadline(); + const txQueue = await this.helper.queue(); + await this.helper.waitForEta(); + const txExecute = await this.helper.execute(); + + expectEvent(txQueue, 'ProposalQueued', { proposalId: this.proposal.id }); + await expectEvent.inTransaction(txQueue.tx, this.manager, 'OperationScheduled', { + operationId: this.restricted.operationId, + nonce: '1', + schedule: web3.utils.toBN(await clockFromReceipt.timestamp(txQueue.receipt)).addn(delay), + caller: this.mock.address, + target: this.restricted.operation.target, + data: this.restricted.operation.data, + }); + + expectEvent(txExecute, 'ProposalExecuted', { proposalId: this.proposal.id }); + await expectEvent.inTransaction(txExecute.tx, this.manager, 'OperationExecuted', { + operationId: this.restricted.operationId, + nonce: '1', + }); + await expectEvent.inTransaction(txExecute.tx, this.receiver, 'CalledRestricted'); + }); + + it('bundle of varied operations', async function () { + const managerDelay = 1000; + const roleId = '1'; + + const baseDelay = managerDelay * 2; + + await this.mock.$_setBaseDelaySeconds(baseDelay); + + await this.manager.setTargetFunctionRole(this.receiver.address, [this.restricted.selector], roleId, { + from: admin, + }); + await this.manager.grantRole(roleId, this.mock.address, managerDelay, { from: admin }); + + this.proposal = await this.helper.setProposal( + [this.restricted.operation, this.unrestricted.operation], + 'descr', + ); + + await this.helper.propose(); + await this.helper.waitForSnapshot(); + await this.helper.vote({ support: Enums.VoteType.For }, { from: voter1 }); + await this.helper.waitForDeadline(); + const txQueue = await this.helper.queue(); + await this.helper.waitForEta(); + const txExecute = await this.helper.execute(); + + expectEvent(txQueue, 'ProposalQueued', { proposalId: this.proposal.id }); + await expectEvent.inTransaction(txQueue.tx, this.manager, 'OperationScheduled', { + operationId: this.restricted.operationId, + nonce: '1', + schedule: web3.utils.toBN(await clockFromReceipt.timestamp(txQueue.receipt)).addn(baseDelay), + caller: this.mock.address, + target: this.restricted.operation.target, + data: this.restricted.operation.data, + }); + + expectEvent(txExecute, 'ProposalExecuted', { proposalId: this.proposal.id }); + await expectEvent.inTransaction(txExecute.tx, this.manager, 'OperationExecuted', { + operationId: this.restricted.operationId, + nonce: '1', + }); + await expectEvent.inTransaction(txExecute.tx, this.receiver, 'CalledRestricted'); + await expectEvent.inTransaction(txExecute.tx, this.receiver, 'CalledUnrestricted'); + }); + + describe('cancel', function () { + const delay = 1000; + const roleId = '1'; + + beforeEach(async function () { + await this.manager.setTargetFunctionRole(this.receiver.address, [this.restricted.selector], roleId, { + from: admin, + }); + await this.manager.grantRole(roleId, this.mock.address, delay, { from: admin }); + }); + + it('cancellation after queue (internal)', async function () { + this.proposal = await this.helper.setProposal([this.restricted.operation], 'descr'); + + await this.helper.propose(); + await this.helper.waitForSnapshot(); + await this.helper.vote({ support: Enums.VoteType.For }, { from: voter1 }); + await this.helper.waitForDeadline(); + await this.helper.queue(); + + const txCancel = await this.helper.cancel('internal'); + expectEvent(txCancel, 'ProposalCanceled', { proposalId: this.proposal.id }); + await expectEvent.inTransaction(txCancel.tx, this.manager, 'OperationCanceled', { + operationId: this.restricted.operationId, + nonce: '1', + }); + + await this.helper.waitForEta(); + await expectRevertCustomError(this.helper.execute(), 'GovernorUnexpectedProposalState', [ + this.proposal.id, + Enums.ProposalState.Canceled, + proposalStatesToBitMap([Enums.ProposalState.Succeeded, Enums.ProposalState.Queued]), + ]); + }); + + it('cancel calls already canceled by guardian', async function () { + const operationA = { target: this.receiver.address, data: this.restricted.selector + '00' }; + const operationB = { target: this.receiver.address, data: this.restricted.selector + '01' }; + const operationC = { target: this.receiver.address, data: this.restricted.selector + '02' }; + const operationAId = hashOperation(this.mock.address, operationA.target, operationA.data); + const operationBId = hashOperation(this.mock.address, operationB.target, operationB.data); + + const proposal1 = new GovernorHelper(this.mock, mode); + const proposal2 = new GovernorHelper(this.mock, mode); + proposal1.setProposal([operationA, operationB], 'proposal A+B'); + proposal2.setProposal([operationA, operationC], 'proposal A+C'); + + for (const p of [proposal1, proposal2]) { + await p.propose(); + await p.waitForSnapshot(); + await p.vote({ support: Enums.VoteType.For }, { from: voter1 }); + await p.waitForDeadline(); + } + + // Can queue the first proposal + await proposal1.queue(); + + // Cannot queue the second proposal: operation A already scheduled with delay + await expectRevertCustomError(proposal2.queue(), 'AccessManagerAlreadyScheduled', [operationAId]); + + // Admin cancels operation B on the manager + await this.manager.cancel(this.mock.address, operationB.target, operationB.data, { from: admin }); + + // Still cannot queue the second proposal: operation A already scheduled with delay + await expectRevertCustomError(proposal2.queue(), 'AccessManagerAlreadyScheduled', [operationAId]); + + await proposal1.waitForEta(); + + // Cannot execute first proposal: operation B has been canceled + await expectRevertCustomError(proposal1.execute(), 'AccessManagerNotScheduled', [operationBId]); + + // Cancel the first proposal to release operation A + await proposal1.cancel('internal'); + + // can finally queue the second proposal + await proposal2.queue(); + + await proposal2.waitForEta(); + + // Can execute second proposal + await proposal2.execute(); + }); + }); + + describe('ignore AccessManager', function () { + it('defaults', async function () { + expect(await this.mock.isAccessManagerIgnored(this.receiver.address, this.restricted.selector)).to.equal( + false, + ); + expect(await this.mock.isAccessManagerIgnored(this.mock.address, '0x12341234')).to.equal(true); + }); + + it('internal setter', async function () { + const p1 = { target: this.receiver.address, selector: this.restricted.selector, ignored: true }; + const tx1 = await this.mock.$_setAccessManagerIgnored(p1.target, p1.selector, p1.ignored); + expect(await this.mock.isAccessManagerIgnored(p1.target, p1.selector)).to.equal(p1.ignored); + expectEvent(tx1, 'AccessManagerIgnoredSet', p1); + + const p2 = { target: this.mock.address, selector: '0x12341234', ignored: false }; + const tx2 = await this.mock.$_setAccessManagerIgnored(p2.target, p2.selector, p2.ignored); + expect(await this.mock.isAccessManagerIgnored(p2.target, p2.selector)).to.equal(p2.ignored); + expectEvent(tx2, 'AccessManagerIgnoredSet', p2); + }); + + it('external setter', async function () { + const setAccessManagerIgnored = (...args) => + this.mock.contract.methods.setAccessManagerIgnored(...args).encodeABI(); + + await this.helper.setProposal( + [ + { + target: this.mock.address, + data: setAccessManagerIgnored( + this.receiver.address, + [this.restricted.selector, this.unrestricted.selector], + true, + ), + value: '0', + }, + { + target: this.mock.address, + data: setAccessManagerIgnored(this.mock.address, ['0x12341234', '0x67896789'], false), + value: '0', + }, + ], + 'descr', + ); + + await this.helper.propose(); + await this.helper.waitForSnapshot(); + await this.helper.vote({ support: Enums.VoteType.For }, { from: voter1 }); + await this.helper.waitForDeadline(); + const tx = await this.helper.execute(); + + expectEvent(tx, 'AccessManagerIgnoredSet'); + + expect(await this.mock.isAccessManagerIgnored(this.receiver.address, this.restricted.selector)).to.equal( + true, + ); + expect(await this.mock.isAccessManagerIgnored(this.receiver.address, this.unrestricted.selector)).to.equal( + true, + ); + + expect(await this.mock.isAccessManagerIgnored(this.mock.address, '0x12341234')).to.equal(false); + expect(await this.mock.isAccessManagerIgnored(this.mock.address, '0x67896789')).to.equal(false); + }); + + it('locked function', async function () { + const setAccessManagerIgnored = selector('setAccessManagerIgnored(address,bytes4[],bool)'); + await expectRevertCustomError( + this.mock.$_setAccessManagerIgnored(this.mock.address, setAccessManagerIgnored, true), + 'GovernorLockedIgnore', + [], + ); + await this.mock.$_setAccessManagerIgnored(this.receiver.address, setAccessManagerIgnored, true); + }); + + it('ignores access manager', async function () { + const amount = 100; + + const target = this.token.address; + const data = this.token.contract.methods.transfer(voter4, amount).encodeABI(); + const selector = data.slice(0, 10); + await this.token.$_mint(this.mock.address, amount); + + const roleId = '1'; + await this.manager.setTargetFunctionRole(target, [selector], roleId, { from: admin }); + await this.manager.grantRole(roleId, this.mock.address, 0, { from: admin }); + + await this.helper.setProposal([{ target, data, value: '0' }], '1'); + await this.helper.propose(); + await this.helper.waitForSnapshot(); + await this.helper.vote({ support: Enums.VoteType.For }, { from: voter1 }); + await this.helper.waitForDeadline(); + await expectRevertCustomError(this.helper.execute(), 'ERC20InsufficientBalance', [ + this.manager.address, + 0, + amount, + ]); + + await this.mock.$_setAccessManagerIgnored(target, selector, true); + + await this.helper.setProposal([{ target, data, value: '0' }], '2'); + await this.helper.propose(); + await this.helper.waitForSnapshot(); + await this.helper.vote({ support: Enums.VoteType.For }, { from: voter1 }); + await this.helper.waitForDeadline(); + const tx = await this.helper.execute(); + expectEvent.inTransaction(tx, this.token, 'Transfer', { from: this.mock.address }); + }); + }); + }); + } +}); diff --git a/test/governance/extensions/GovernorTimelockCompound.test.js b/test/governance/extensions/GovernorTimelockCompound.test.js new file mode 100644 index 000000000..e9d6f8373 --- /dev/null +++ b/test/governance/extensions/GovernorTimelockCompound.test.js @@ -0,0 +1,441 @@ +const { constants, expectEvent, expectRevert } = require('@openzeppelin/test-helpers'); +const { expect } = require('chai'); + +const Enums = require('../../helpers/enums'); +const { GovernorHelper, proposalStatesToBitMap } = require('../../helpers/governance'); +const { expectRevertCustomError } = require('../../helpers/customError'); +const { computeCreateAddress } = require('../../helpers/create'); +const { clockFromReceipt } = require('../../helpers/time'); + +const Timelock = artifacts.require('CompTimelock'); +const Governor = artifacts.require('$GovernorTimelockCompoundMock'); +const CallReceiver = artifacts.require('CallReceiverMock'); +const ERC721 = artifacts.require('$ERC721'); +const ERC1155 = artifacts.require('$ERC1155'); + +const TOKENS = [ + { Token: artifacts.require('$ERC20Votes'), mode: 'blocknumber' }, + { Token: artifacts.require('$ERC20VotesTimestampMock'), mode: 'timestamp' }, +]; + +contract('GovernorTimelockCompound', function (accounts) { + const [owner, voter1, voter2, voter3, voter4, other] = accounts; + + const name = 'OZ-Governor'; + const version = '1'; + const tokenName = 'MockToken'; + const tokenSymbol = 'MTKN'; + const tokenSupply = web3.utils.toWei('100'); + const votingDelay = web3.utils.toBN(4); + const votingPeriod = web3.utils.toBN(16); + const value = web3.utils.toWei('1'); + + const defaultDelay = 2 * 86400; + + for (const { mode, Token } of TOKENS) { + describe(`using ${Token._json.contractName}`, function () { + beforeEach(async function () { + const [deployer] = await web3.eth.getAccounts(); + + this.token = await Token.new(tokenName, tokenSymbol, tokenName, version); + + // Need to predict governance address to set it as timelock admin with a delayed transfer + const nonce = await web3.eth.getTransactionCount(deployer); + const predictGovernor = computeCreateAddress(deployer, nonce + 1); + + this.timelock = await Timelock.new(predictGovernor, defaultDelay); + this.mock = await Governor.new( + name, + votingDelay, + votingPeriod, + 0, + this.timelock.address, + this.token.address, + 0, + ); + this.receiver = await CallReceiver.new(); + + this.helper = new GovernorHelper(this.mock, mode); + + await web3.eth.sendTransaction({ from: owner, to: this.timelock.address, value }); + + await this.token.$_mint(owner, tokenSupply); + await this.helper.delegate({ token: this.token, to: voter1, value: web3.utils.toWei('10') }, { from: owner }); + await this.helper.delegate({ token: this.token, to: voter2, value: web3.utils.toWei('7') }, { from: owner }); + await this.helper.delegate({ token: this.token, to: voter3, value: web3.utils.toWei('5') }, { from: owner }); + await this.helper.delegate({ token: this.token, to: voter4, value: web3.utils.toWei('2') }, { from: owner }); + + // default proposal + this.proposal = this.helper.setProposal( + [ + { + target: this.receiver.address, + value, + data: this.receiver.contract.methods.mockFunction().encodeABI(), + }, + ], + '', + ); + }); + + it("doesn't accept ether transfers", async function () { + await expectRevert.unspecified(web3.eth.sendTransaction({ from: owner, to: this.mock.address, value: 1 })); + }); + + it('post deployment check', async function () { + expect(await this.mock.name()).to.be.equal(name); + expect(await this.mock.token()).to.be.equal(this.token.address); + expect(await this.mock.votingDelay()).to.be.bignumber.equal(votingDelay); + expect(await this.mock.votingPeriod()).to.be.bignumber.equal(votingPeriod); + expect(await this.mock.quorum(0)).to.be.bignumber.equal('0'); + + expect(await this.mock.timelock()).to.be.equal(this.timelock.address); + expect(await this.timelock.admin()).to.be.equal(this.mock.address); + }); + + it('nominal', async function () { + expect(await this.mock.proposalEta(this.proposal.id)).to.be.bignumber.equal('0'); + expect(await this.mock.proposalNeedsQueuing(this.proposal.id)).to.be.equal(true); + + await this.helper.propose(); + await this.helper.waitForSnapshot(); + await this.helper.vote({ support: Enums.VoteType.For }, { from: voter1 }); + await this.helper.vote({ support: Enums.VoteType.For }, { from: voter2 }); + await this.helper.vote({ support: Enums.VoteType.Against }, { from: voter3 }); + await this.helper.vote({ support: Enums.VoteType.Abstain }, { from: voter4 }); + await this.helper.waitForDeadline(); + const txQueue = await this.helper.queue(); + + const eta = web3.utils.toBN(await clockFromReceipt.timestamp(txQueue.receipt)).addn(defaultDelay); + expect(await this.mock.proposalEta(this.proposal.id)).to.be.bignumber.equal(eta); + expect(await this.mock.proposalNeedsQueuing(this.proposal.id)).to.be.equal(true); + + await this.helper.waitForEta(); + const txExecute = await this.helper.execute(); + + expectEvent(txQueue, 'ProposalQueued', { proposalId: this.proposal.id }); + await expectEvent.inTransaction(txQueue.tx, this.timelock, 'QueueTransaction', { eta }); + + expectEvent(txExecute, 'ProposalExecuted', { proposalId: this.proposal.id }); + await expectEvent.inTransaction(txExecute.tx, this.timelock, 'ExecuteTransaction', { eta }); + await expectEvent.inTransaction(txExecute.tx, this.receiver, 'MockFunctionCalled'); + }); + + describe('should revert', function () { + describe('on queue', function () { + it('if already queued', async function () { + await this.helper.propose(); + await this.helper.waitForSnapshot(); + await this.helper.vote({ support: Enums.VoteType.For }, { from: voter1 }); + await this.helper.waitForDeadline(); + await this.helper.queue(); + await expectRevertCustomError(this.helper.queue(), 'GovernorUnexpectedProposalState', [ + this.proposal.id, + Enums.ProposalState.Queued, + proposalStatesToBitMap([Enums.ProposalState.Succeeded]), + ]); + }); + + it('if proposal contains duplicate calls', async function () { + const action = { + target: this.token.address, + data: this.token.contract.methods.approve(this.receiver.address, constants.MAX_UINT256).encodeABI(), + }; + const { id } = this.helper.setProposal([action, action], ''); + + await this.helper.propose(); + await this.helper.waitForSnapshot(); + await this.helper.vote({ support: Enums.VoteType.For }, { from: voter1 }); + await this.helper.waitForDeadline(); + await expectRevertCustomError(this.helper.queue(), 'GovernorAlreadyQueuedProposal', [id]); + await expectRevertCustomError(this.helper.execute(), 'GovernorNotQueuedProposal', [id]); + }); + }); + + describe('on execute', function () { + it('if not queued', async function () { + await this.helper.propose(); + await this.helper.waitForSnapshot(); + await this.helper.vote({ support: Enums.VoteType.For }, { from: voter1 }); + await this.helper.waitForDeadline(+1); + + expect(await this.mock.state(this.proposal.id)).to.be.bignumber.equal(Enums.ProposalState.Succeeded); + + await expectRevertCustomError(this.helper.execute(), 'GovernorNotQueuedProposal', [this.proposal.id]); + }); + + it('if too early', async function () { + await this.helper.propose(); + await this.helper.waitForSnapshot(); + await this.helper.vote({ support: Enums.VoteType.For }, { from: voter1 }); + await this.helper.waitForDeadline(); + await this.helper.queue(); + + expect(await this.mock.state(this.proposal.id)).to.be.bignumber.equal(Enums.ProposalState.Queued); + + await expectRevert( + this.helper.execute(), + "Timelock::executeTransaction: Transaction hasn't surpassed time lock", + ); + }); + + it('if too late', async function () { + await this.helper.propose(); + await this.helper.waitForSnapshot(); + await this.helper.vote({ support: Enums.VoteType.For }, { from: voter1 }); + await this.helper.waitForDeadline(); + await this.helper.queue(); + await this.helper.waitForEta(+30 * 86400); + + expect(await this.mock.state(this.proposal.id)).to.be.bignumber.equal(Enums.ProposalState.Expired); + + await expectRevertCustomError(this.helper.execute(), 'GovernorUnexpectedProposalState', [ + this.proposal.id, + Enums.ProposalState.Expired, + proposalStatesToBitMap([Enums.ProposalState.Succeeded, Enums.ProposalState.Queued]), + ]); + }); + + it('if already executed', async function () { + await this.helper.propose(); + await this.helper.waitForSnapshot(); + await this.helper.vote({ support: Enums.VoteType.For }, { from: voter1 }); + await this.helper.waitForDeadline(); + await this.helper.queue(); + await this.helper.waitForEta(); + await this.helper.execute(); + await expectRevertCustomError(this.helper.execute(), 'GovernorUnexpectedProposalState', [ + this.proposal.id, + Enums.ProposalState.Executed, + proposalStatesToBitMap([Enums.ProposalState.Succeeded, Enums.ProposalState.Queued]), + ]); + }); + }); + + describe('on safe receive', function () { + describe('ERC721', function () { + const name = 'Non Fungible Token'; + const symbol = 'NFT'; + const tokenId = web3.utils.toBN(1); + + beforeEach(async function () { + this.token = await ERC721.new(name, symbol); + await this.token.$_mint(owner, tokenId); + }); + + it("can't receive an ERC721 safeTransfer", async function () { + await expectRevertCustomError( + this.token.safeTransferFrom(owner, this.mock.address, tokenId, { from: owner }), + 'GovernorDisabledDeposit', + [], + ); + }); + }); + + describe('ERC1155', function () { + const uri = 'https://token-cdn-domain/{id}.json'; + const tokenIds = { + 1: web3.utils.toBN(1000), + 2: web3.utils.toBN(2000), + 3: web3.utils.toBN(3000), + }; + + beforeEach(async function () { + this.token = await ERC1155.new(uri); + await this.token.$_mintBatch(owner, Object.keys(tokenIds), Object.values(tokenIds), '0x'); + }); + + it("can't receive ERC1155 safeTransfer", async function () { + await expectRevertCustomError( + this.token.safeTransferFrom( + owner, + this.mock.address, + ...Object.entries(tokenIds)[0], // id + amount + '0x', + { from: owner }, + ), + 'GovernorDisabledDeposit', + [], + ); + }); + + it("can't receive ERC1155 safeBatchTransfer", async function () { + await expectRevertCustomError( + this.token.safeBatchTransferFrom( + owner, + this.mock.address, + Object.keys(tokenIds), + Object.values(tokenIds), + '0x', + { from: owner }, + ), + 'GovernorDisabledDeposit', + [], + ); + }); + }); + }); + }); + + describe('cancel', function () { + it('cancel before queue prevents scheduling', async function () { + await this.helper.propose(); + await this.helper.waitForSnapshot(); + await this.helper.vote({ support: Enums.VoteType.For }, { from: voter1 }); + await this.helper.waitForDeadline(); + + expectEvent(await this.helper.cancel('internal'), 'ProposalCanceled', { proposalId: this.proposal.id }); + + expect(await this.mock.state(this.proposal.id)).to.be.bignumber.equal(Enums.ProposalState.Canceled); + await expectRevertCustomError(this.helper.queue(), 'GovernorUnexpectedProposalState', [ + this.proposal.id, + Enums.ProposalState.Canceled, + proposalStatesToBitMap([Enums.ProposalState.Succeeded]), + ]); + }); + + it('cancel after queue prevents executing', async function () { + await this.helper.propose(); + await this.helper.waitForSnapshot(); + await this.helper.vote({ support: Enums.VoteType.For }, { from: voter1 }); + await this.helper.waitForDeadline(); + await this.helper.queue(); + + expectEvent(await this.helper.cancel('internal'), 'ProposalCanceled', { proposalId: this.proposal.id }); + + expect(await this.mock.state(this.proposal.id)).to.be.bignumber.equal(Enums.ProposalState.Canceled); + await expectRevertCustomError(this.helper.execute(), 'GovernorUnexpectedProposalState', [ + this.proposal.id, + Enums.ProposalState.Canceled, + proposalStatesToBitMap([Enums.ProposalState.Succeeded, Enums.ProposalState.Queued]), + ]); + }); + }); + + describe('onlyGovernance', function () { + describe('relay', function () { + beforeEach(async function () { + await this.token.$_mint(this.mock.address, 1); + }); + + it('is protected', async function () { + await expectRevertCustomError( + this.mock.relay(this.token.address, 0, this.token.contract.methods.transfer(other, 1).encodeABI(), { + from: owner, + }), + 'GovernorOnlyExecutor', + [owner], + ); + }); + + it('can be executed through governance', async function () { + this.helper.setProposal( + [ + { + target: this.mock.address, + data: this.mock.contract.methods + .relay(this.token.address, 0, this.token.contract.methods.transfer(other, 1).encodeABI()) + .encodeABI(), + }, + ], + '', + ); + + expect(await this.token.balanceOf(this.mock.address), 1); + expect(await this.token.balanceOf(other), 0); + + await this.helper.propose(); + await this.helper.waitForSnapshot(); + await this.helper.vote({ support: Enums.VoteType.For }, { from: voter1 }); + await this.helper.waitForDeadline(); + await this.helper.queue(); + await this.helper.waitForEta(); + const txExecute = await this.helper.execute(); + + expect(await this.token.balanceOf(this.mock.address), 0); + expect(await this.token.balanceOf(other), 1); + + await expectEvent.inTransaction(txExecute.tx, this.token, 'Transfer', { + from: this.mock.address, + to: other, + value: '1', + }); + }); + }); + + describe('updateTimelock', function () { + beforeEach(async function () { + this.newTimelock = await Timelock.new(this.mock.address, 7 * 86400); + }); + + it('is protected', async function () { + await expectRevertCustomError( + this.mock.updateTimelock(this.newTimelock.address, { from: owner }), + 'GovernorOnlyExecutor', + [owner], + ); + }); + + it('can be executed through governance to', async function () { + this.helper.setProposal( + [ + { + target: this.timelock.address, + data: this.timelock.contract.methods.setPendingAdmin(owner).encodeABI(), + }, + { + target: this.mock.address, + data: this.mock.contract.methods.updateTimelock(this.newTimelock.address).encodeABI(), + }, + ], + '', + ); + + await this.helper.propose(); + await this.helper.waitForSnapshot(); + await this.helper.vote({ support: Enums.VoteType.For }, { from: voter1 }); + await this.helper.waitForDeadline(); + await this.helper.queue(); + await this.helper.waitForEta(); + const txExecute = await this.helper.execute(); + + expectEvent(txExecute, 'TimelockChange', { + oldTimelock: this.timelock.address, + newTimelock: this.newTimelock.address, + }); + + expect(await this.mock.timelock()).to.be.bignumber.equal(this.newTimelock.address); + }); + }); + + it('can transfer timelock to new governor', async function () { + const newGovernor = await Governor.new(name, 8, 32, 0, this.timelock.address, this.token.address, 0); + this.helper.setProposal( + [ + { + target: this.timelock.address, + data: this.timelock.contract.methods.setPendingAdmin(newGovernor.address).encodeABI(), + }, + ], + '', + ); + + await this.helper.propose(); + await this.helper.waitForSnapshot(); + await this.helper.vote({ support: Enums.VoteType.For }, { from: voter1 }); + await this.helper.waitForDeadline(); + await this.helper.queue(); + await this.helper.waitForEta(); + const txExecute = await this.helper.execute(); + + await expectEvent.inTransaction(txExecute.tx, this.timelock, 'NewPendingAdmin', { + newPendingAdmin: newGovernor.address, + }); + + await newGovernor.__acceptAdmin(); + expect(await this.timelock.admin()).to.be.bignumber.equal(newGovernor.address); + }); + }); + }); + } +}); diff --git a/test/governance/extensions/GovernorTimelockControl.test.js b/test/governance/extensions/GovernorTimelockControl.test.js new file mode 100644 index 000000000..ec03d6144 --- /dev/null +++ b/test/governance/extensions/GovernorTimelockControl.test.js @@ -0,0 +1,515 @@ +const { constants, expectEvent, expectRevert, time } = require('@openzeppelin/test-helpers'); +const { expect } = require('chai'); + +const Enums = require('../../helpers/enums'); +const { GovernorHelper, proposalStatesToBitMap, timelockSalt } = require('../../helpers/governance'); +const { expectRevertCustomError } = require('../../helpers/customError'); +const { clockFromReceipt } = require('../../helpers/time'); + +const Timelock = artifacts.require('TimelockController'); +const Governor = artifacts.require('$GovernorTimelockControlMock'); +const CallReceiver = artifacts.require('CallReceiverMock'); +const ERC721 = artifacts.require('$ERC721'); +const ERC1155 = artifacts.require('$ERC1155'); + +const TOKENS = [ + { Token: artifacts.require('$ERC20Votes'), mode: 'blocknumber' }, + { Token: artifacts.require('$ERC20VotesTimestampMock'), mode: 'timestamp' }, +]; + +contract('GovernorTimelockControl', function (accounts) { + const [owner, voter1, voter2, voter3, voter4, other] = accounts; + + const DEFAULT_ADMIN_ROLE = '0x0000000000000000000000000000000000000000000000000000000000000000'; + const PROPOSER_ROLE = web3.utils.soliditySha3('PROPOSER_ROLE'); + const EXECUTOR_ROLE = web3.utils.soliditySha3('EXECUTOR_ROLE'); + const CANCELLER_ROLE = web3.utils.soliditySha3('CANCELLER_ROLE'); + + const name = 'OZ-Governor'; + const version = '1'; + const tokenName = 'MockToken'; + const tokenSymbol = 'MTKN'; + const tokenSupply = web3.utils.toWei('100'); + const votingDelay = web3.utils.toBN(4); + const votingPeriod = web3.utils.toBN(16); + const value = web3.utils.toWei('1'); + + const delay = 3600; + + for (const { mode, Token } of TOKENS) { + describe(`using ${Token._json.contractName}`, function () { + beforeEach(async function () { + const [deployer] = await web3.eth.getAccounts(); + + this.token = await Token.new(tokenName, tokenSymbol, tokenName, version); + this.timelock = await Timelock.new(delay, [], [], deployer); + this.mock = await Governor.new( + name, + votingDelay, + votingPeriod, + 0, + this.timelock.address, + this.token.address, + 0, + ); + this.receiver = await CallReceiver.new(); + + this.helper = new GovernorHelper(this.mock, mode); + + this.PROPOSER_ROLE = await this.timelock.PROPOSER_ROLE(); + this.EXECUTOR_ROLE = await this.timelock.EXECUTOR_ROLE(); + this.CANCELLER_ROLE = await this.timelock.CANCELLER_ROLE(); + + await web3.eth.sendTransaction({ from: owner, to: this.timelock.address, value }); + + // normal setup: governor is proposer, everyone is executor, timelock is its own admin + await this.timelock.grantRole(PROPOSER_ROLE, this.mock.address); + await this.timelock.grantRole(PROPOSER_ROLE, owner); + await this.timelock.grantRole(CANCELLER_ROLE, this.mock.address); + await this.timelock.grantRole(CANCELLER_ROLE, owner); + await this.timelock.grantRole(EXECUTOR_ROLE, constants.ZERO_ADDRESS); + await this.timelock.revokeRole(DEFAULT_ADMIN_ROLE, deployer); + + await this.token.$_mint(owner, tokenSupply); + await this.helper.delegate({ token: this.token, to: voter1, value: web3.utils.toWei('10') }, { from: owner }); + await this.helper.delegate({ token: this.token, to: voter2, value: web3.utils.toWei('7') }, { from: owner }); + await this.helper.delegate({ token: this.token, to: voter3, value: web3.utils.toWei('5') }, { from: owner }); + await this.helper.delegate({ token: this.token, to: voter4, value: web3.utils.toWei('2') }, { from: owner }); + + // default proposal + this.proposal = this.helper.setProposal( + [ + { + target: this.receiver.address, + value, + data: this.receiver.contract.methods.mockFunction().encodeABI(), + }, + ], + '', + ); + + this.proposal.timelockid = await this.timelock.hashOperationBatch( + ...this.proposal.shortProposal.slice(0, 3), + '0x0', + timelockSalt(this.mock.address, this.proposal.shortProposal[3]), + ); + }); + + it("doesn't accept ether transfers", async function () { + await expectRevert.unspecified(web3.eth.sendTransaction({ from: owner, to: this.mock.address, value: 1 })); + }); + + it('post deployment check', async function () { + expect(await this.mock.name()).to.be.equal(name); + expect(await this.mock.token()).to.be.equal(this.token.address); + expect(await this.mock.votingDelay()).to.be.bignumber.equal(votingDelay); + expect(await this.mock.votingPeriod()).to.be.bignumber.equal(votingPeriod); + expect(await this.mock.quorum(0)).to.be.bignumber.equal('0'); + + expect(await this.mock.timelock()).to.be.equal(this.timelock.address); + }); + + it('nominal', async function () { + expect(await this.mock.proposalEta(this.proposal.id)).to.be.bignumber.equal('0'); + expect(await this.mock.proposalNeedsQueuing(this.proposal.id)).to.be.equal(true); + + await this.helper.propose(); + await this.helper.waitForSnapshot(); + await this.helper.vote({ support: Enums.VoteType.For }, { from: voter1 }); + await this.helper.vote({ support: Enums.VoteType.For }, { from: voter2 }); + await this.helper.vote({ support: Enums.VoteType.Against }, { from: voter3 }); + await this.helper.vote({ support: Enums.VoteType.Abstain }, { from: voter4 }); + await this.helper.waitForDeadline(); + const txQueue = await this.helper.queue(); + await this.helper.waitForEta(); + + const eta = web3.utils.toBN(await clockFromReceipt.timestamp(txQueue.receipt)).addn(delay); + expect(await this.mock.proposalEta(this.proposal.id)).to.be.bignumber.equal(eta); + expect(await this.mock.proposalNeedsQueuing(this.proposal.id)).to.be.equal(true); + + const txExecute = await this.helper.execute(); + + expectEvent(txQueue, 'ProposalQueued', { proposalId: this.proposal.id }); + await expectEvent.inTransaction(txQueue.tx, this.timelock, 'CallScheduled', { id: this.proposal.timelockid }); + await expectEvent.inTransaction(txQueue.tx, this.timelock, 'CallSalt', { + id: this.proposal.timelockid, + }); + + expectEvent(txExecute, 'ProposalExecuted', { proposalId: this.proposal.id }); + await expectEvent.inTransaction(txExecute.tx, this.timelock, 'CallExecuted', { id: this.proposal.timelockid }); + await expectEvent.inTransaction(txExecute.tx, this.receiver, 'MockFunctionCalled'); + }); + + describe('should revert', function () { + describe('on queue', function () { + it('if already queued', async function () { + await this.helper.propose(); + await this.helper.waitForSnapshot(); + await this.helper.vote({ support: Enums.VoteType.For }, { from: voter1 }); + await this.helper.waitForDeadline(); + await this.helper.queue(); + await expectRevertCustomError(this.helper.queue(), 'GovernorUnexpectedProposalState', [ + this.proposal.id, + Enums.ProposalState.Queued, + proposalStatesToBitMap([Enums.ProposalState.Succeeded]), + ]); + }); + }); + + describe('on execute', function () { + it('if not queued', async function () { + await this.helper.propose(); + await this.helper.waitForSnapshot(); + await this.helper.vote({ support: Enums.VoteType.For }, { from: voter1 }); + await this.helper.waitForDeadline(+1); + + expect(await this.mock.state(this.proposal.id)).to.be.bignumber.equal(Enums.ProposalState.Succeeded); + + await expectRevertCustomError(this.helper.execute(), 'TimelockUnexpectedOperationState', [ + this.proposal.timelockid, + proposalStatesToBitMap(Enums.OperationState.Ready), + ]); + }); + + it('if too early', async function () { + await this.helper.propose(); + await this.helper.waitForSnapshot(); + await this.helper.vote({ support: Enums.VoteType.For }, { from: voter1 }); + await this.helper.waitForDeadline(); + await this.helper.queue(); + + expect(await this.mock.state(this.proposal.id)).to.be.bignumber.equal(Enums.ProposalState.Queued); + + await expectRevertCustomError(this.helper.execute(), 'TimelockUnexpectedOperationState', [ + this.proposal.timelockid, + proposalStatesToBitMap(Enums.OperationState.Ready), + ]); + }); + + it('if already executed', async function () { + await this.helper.propose(); + await this.helper.waitForSnapshot(); + await this.helper.vote({ support: Enums.VoteType.For }, { from: voter1 }); + await this.helper.waitForDeadline(); + await this.helper.queue(); + await this.helper.waitForEta(); + await this.helper.execute(); + await expectRevertCustomError(this.helper.execute(), 'GovernorUnexpectedProposalState', [ + this.proposal.id, + Enums.ProposalState.Executed, + proposalStatesToBitMap([Enums.ProposalState.Succeeded, Enums.ProposalState.Queued]), + ]); + }); + + it('if already executed by another proposer', async function () { + await this.helper.propose(); + await this.helper.waitForSnapshot(); + await this.helper.vote({ support: Enums.VoteType.For }, { from: voter1 }); + await this.helper.waitForDeadline(); + await this.helper.queue(); + await this.helper.waitForEta(); + + await this.timelock.executeBatch( + ...this.proposal.shortProposal.slice(0, 3), + '0x0', + timelockSalt(this.mock.address, this.proposal.shortProposal[3]), + ); + + await expectRevertCustomError(this.helper.execute(), 'GovernorUnexpectedProposalState', [ + this.proposal.id, + Enums.ProposalState.Executed, + proposalStatesToBitMap([Enums.ProposalState.Succeeded, Enums.ProposalState.Queued]), + ]); + }); + }); + }); + + describe('cancel', function () { + it('cancel before queue prevents scheduling', async function () { + await this.helper.propose(); + await this.helper.waitForSnapshot(); + await this.helper.vote({ support: Enums.VoteType.For }, { from: voter1 }); + await this.helper.waitForDeadline(); + + expectEvent(await this.helper.cancel('internal'), 'ProposalCanceled', { proposalId: this.proposal.id }); + + expect(await this.mock.state(this.proposal.id)).to.be.bignumber.equal(Enums.ProposalState.Canceled); + await expectRevertCustomError(this.helper.queue(), 'GovernorUnexpectedProposalState', [ + this.proposal.id, + Enums.ProposalState.Canceled, + proposalStatesToBitMap([Enums.ProposalState.Succeeded]), + ]); + }); + + it('cancel after queue prevents executing', async function () { + await this.helper.propose(); + await this.helper.waitForSnapshot(); + await this.helper.vote({ support: Enums.VoteType.For }, { from: voter1 }); + await this.helper.waitForDeadline(); + await this.helper.queue(); + + expectEvent(await this.helper.cancel('internal'), 'ProposalCanceled', { proposalId: this.proposal.id }); + + expect(await this.mock.state(this.proposal.id)).to.be.bignumber.equal(Enums.ProposalState.Canceled); + await expectRevertCustomError(this.helper.execute(), 'GovernorUnexpectedProposalState', [ + this.proposal.id, + Enums.ProposalState.Canceled, + proposalStatesToBitMap([Enums.ProposalState.Succeeded, Enums.ProposalState.Queued]), + ]); + }); + + it('cancel on timelock is reflected on governor', async function () { + await this.helper.propose(); + await this.helper.waitForSnapshot(); + await this.helper.vote({ support: Enums.VoteType.For }, { from: voter1 }); + await this.helper.waitForDeadline(); + await this.helper.queue(); + + expect(await this.mock.state(this.proposal.id)).to.be.bignumber.equal(Enums.ProposalState.Queued); + + expectEvent(await this.timelock.cancel(this.proposal.timelockid, { from: owner }), 'Cancelled', { + id: this.proposal.timelockid, + }); + + expect(await this.mock.state(this.proposal.id)).to.be.bignumber.equal(Enums.ProposalState.Canceled); + }); + }); + + describe('onlyGovernance', function () { + describe('relay', function () { + beforeEach(async function () { + await this.token.$_mint(this.mock.address, 1); + }); + + it('is protected', async function () { + await expectRevertCustomError( + this.mock.relay(this.token.address, 0, this.token.contract.methods.transfer(other, 1).encodeABI(), { + from: owner, + }), + 'GovernorOnlyExecutor', + [owner], + ); + }); + + it('can be executed through governance', async function () { + this.helper.setProposal( + [ + { + target: this.mock.address, + data: this.mock.contract.methods + .relay(this.token.address, 0, this.token.contract.methods.transfer(other, 1).encodeABI()) + .encodeABI(), + }, + ], + '', + ); + + expect(await this.token.balanceOf(this.mock.address), 1); + expect(await this.token.balanceOf(other), 0); + + await this.helper.propose(); + await this.helper.waitForSnapshot(); + await this.helper.vote({ support: Enums.VoteType.For }, { from: voter1 }); + await this.helper.waitForDeadline(); + await this.helper.queue(); + await this.helper.waitForEta(); + const txExecute = await this.helper.execute(); + + expect(await this.token.balanceOf(this.mock.address), 0); + expect(await this.token.balanceOf(other), 1); + + await expectEvent.inTransaction(txExecute.tx, this.token, 'Transfer', { + from: this.mock.address, + to: other, + value: '1', + }); + }); + + it('is payable and can transfer eth to EOA', async function () { + const t2g = web3.utils.toBN(128); // timelock to governor + const g2o = web3.utils.toBN(100); // governor to eoa (other) + + this.helper.setProposal( + [ + { + target: this.mock.address, + value: t2g, + data: this.mock.contract.methods.relay(other, g2o, '0x').encodeABI(), + }, + ], + '', + ); + + expect(await web3.eth.getBalance(this.mock.address)).to.be.bignumber.equal(web3.utils.toBN(0)); + const timelockBalance = await web3.eth.getBalance(this.timelock.address).then(web3.utils.toBN); + const otherBalance = await web3.eth.getBalance(other).then(web3.utils.toBN); + + await this.helper.propose(); + await this.helper.waitForSnapshot(); + await this.helper.vote({ support: Enums.VoteType.For }, { from: voter1 }); + await this.helper.waitForDeadline(); + await this.helper.queue(); + await this.helper.waitForEta(); + await this.helper.execute(); + + expect(await web3.eth.getBalance(this.timelock.address)).to.be.bignumber.equal(timelockBalance.sub(t2g)); + expect(await web3.eth.getBalance(this.mock.address)).to.be.bignumber.equal(t2g.sub(g2o)); + expect(await web3.eth.getBalance(other)).to.be.bignumber.equal(otherBalance.add(g2o)); + }); + + it('protected against other proposers', async function () { + const target = this.mock.address; + const value = web3.utils.toWei('0'); + const data = this.mock.contract.methods.relay(constants.ZERO_ADDRESS, 0, '0x').encodeABI(); + const predecessor = constants.ZERO_BYTES32; + const salt = constants.ZERO_BYTES32; + + await this.timelock.schedule(target, value, data, predecessor, salt, delay, { from: owner }); + + await time.increase(delay); + + await expectRevertCustomError( + this.timelock.execute(target, value, data, predecessor, salt, { from: owner }), + 'QueueEmpty', // Bubbled up from Governor + [], + ); + }); + }); + + describe('updateTimelock', function () { + beforeEach(async function () { + this.newTimelock = await Timelock.new( + delay, + [this.mock.address], + [this.mock.address], + constants.ZERO_ADDRESS, + ); + }); + + it('is protected', async function () { + await expectRevertCustomError( + this.mock.updateTimelock(this.newTimelock.address, { from: owner }), + 'GovernorOnlyExecutor', + [owner], + ); + }); + + it('can be executed through governance to', async function () { + this.helper.setProposal( + [ + { + target: this.mock.address, + data: this.mock.contract.methods.updateTimelock(this.newTimelock.address).encodeABI(), + }, + ], + '', + ); + + await this.helper.propose(); + await this.helper.waitForSnapshot(); + await this.helper.vote({ support: Enums.VoteType.For }, { from: voter1 }); + await this.helper.waitForDeadline(); + await this.helper.queue(); + await this.helper.waitForEta(); + const txExecute = await this.helper.execute(); + + expectEvent(txExecute, 'TimelockChange', { + oldTimelock: this.timelock.address, + newTimelock: this.newTimelock.address, + }); + + expect(await this.mock.timelock()).to.be.bignumber.equal(this.newTimelock.address); + }); + }); + + describe('on safe receive', function () { + describe('ERC721', function () { + const name = 'Non Fungible Token'; + const symbol = 'NFT'; + const tokenId = web3.utils.toBN(1); + + beforeEach(async function () { + this.token = await ERC721.new(name, symbol); + await this.token.$_mint(owner, tokenId); + }); + + it("can't receive an ERC721 safeTransfer", async function () { + await expectRevertCustomError( + this.token.safeTransferFrom(owner, this.mock.address, tokenId, { from: owner }), + 'GovernorDisabledDeposit', + [], + ); + }); + }); + + describe('ERC1155', function () { + const uri = 'https://token-cdn-domain/{id}.json'; + const tokenIds = { + 1: web3.utils.toBN(1000), + 2: web3.utils.toBN(2000), + 3: web3.utils.toBN(3000), + }; + + beforeEach(async function () { + this.token = await ERC1155.new(uri); + await this.token.$_mintBatch(owner, Object.keys(tokenIds), Object.values(tokenIds), '0x'); + }); + + it("can't receive ERC1155 safeTransfer", async function () { + await expectRevertCustomError( + this.token.safeTransferFrom( + owner, + this.mock.address, + ...Object.entries(tokenIds)[0], // id + amount + '0x', + { from: owner }, + ), + 'GovernorDisabledDeposit', + [], + ); + }); + + it("can't receive ERC1155 safeBatchTransfer", async function () { + await expectRevertCustomError( + this.token.safeBatchTransferFrom( + owner, + this.mock.address, + Object.keys(tokenIds), + Object.values(tokenIds), + '0x', + { from: owner }, + ), + 'GovernorDisabledDeposit', + [], + ); + }); + }); + }); + }); + + it('clear queue of pending governor calls', async function () { + this.helper.setProposal( + [ + { + target: this.mock.address, + data: this.mock.contract.methods.nonGovernanceFunction().encodeABI(), + }, + ], + '', + ); + + await this.helper.propose(); + await this.helper.waitForSnapshot(); + await this.helper.vote({ support: Enums.VoteType.For }, { from: voter1 }); + await this.helper.waitForDeadline(); + await this.helper.queue(); + await this.helper.waitForEta(); + await this.helper.execute(); + + // This path clears _governanceCall as part of the afterExecute call, + // but we have not way to check that the cleanup actually happened other + // then coverage reports. + }); + }); + } +}); diff --git a/test/governance/extensions/GovernorVotesQuorumFraction.test.js b/test/governance/extensions/GovernorVotesQuorumFraction.test.js new file mode 100644 index 000000000..ece9c78d6 --- /dev/null +++ b/test/governance/extensions/GovernorVotesQuorumFraction.test.js @@ -0,0 +1,167 @@ +const { expectEvent, time } = require('@openzeppelin/test-helpers'); +const { expect } = require('chai'); + +const Enums = require('../../helpers/enums'); +const { GovernorHelper, proposalStatesToBitMap } = require('../../helpers/governance'); +const { clock } = require('../../helpers/time'); +const { expectRevertCustomError } = require('../../helpers/customError'); + +const Governor = artifacts.require('$GovernorMock'); +const CallReceiver = artifacts.require('CallReceiverMock'); + +const TOKENS = [ + { Token: artifacts.require('$ERC20Votes'), mode: 'blocknumber' }, + { Token: artifacts.require('$ERC20VotesTimestampMock'), mode: 'timestamp' }, +]; + +contract('GovernorVotesQuorumFraction', function (accounts) { + const [owner, voter1, voter2, voter3, voter4] = accounts; + + const name = 'OZ-Governor'; + const version = '1'; + const tokenName = 'MockToken'; + const tokenSymbol = 'MTKN'; + const tokenSupply = web3.utils.toBN(web3.utils.toWei('100')); + const ratio = web3.utils.toBN(8); // percents + const newRatio = web3.utils.toBN(6); // percents + const votingDelay = web3.utils.toBN(4); + const votingPeriod = web3.utils.toBN(16); + const value = web3.utils.toWei('1'); + + for (const { mode, Token } of TOKENS) { + describe(`using ${Token._json.contractName}`, function () { + beforeEach(async function () { + this.owner = owner; + this.token = await Token.new(tokenName, tokenSymbol, tokenName, version); + this.mock = await Governor.new(name, votingDelay, votingPeriod, 0, this.token.address, ratio); + this.receiver = await CallReceiver.new(); + + this.helper = new GovernorHelper(this.mock, mode); + + await web3.eth.sendTransaction({ from: owner, to: this.mock.address, value }); + + await this.token.$_mint(owner, tokenSupply); + await this.helper.delegate({ token: this.token, to: voter1, value: web3.utils.toWei('10') }, { from: owner }); + await this.helper.delegate({ token: this.token, to: voter2, value: web3.utils.toWei('7') }, { from: owner }); + await this.helper.delegate({ token: this.token, to: voter3, value: web3.utils.toWei('5') }, { from: owner }); + await this.helper.delegate({ token: this.token, to: voter4, value: web3.utils.toWei('2') }, { from: owner }); + + // default proposal + this.proposal = this.helper.setProposal( + [ + { + target: this.receiver.address, + value, + data: this.receiver.contract.methods.mockFunction().encodeABI(), + }, + ], + '', + ); + }); + + it('deployment check', async function () { + expect(await this.mock.name()).to.be.equal(name); + expect(await this.mock.token()).to.be.equal(this.token.address); + expect(await this.mock.votingDelay()).to.be.bignumber.equal(votingDelay); + expect(await this.mock.votingPeriod()).to.be.bignumber.equal(votingPeriod); + expect(await this.mock.quorum(0)).to.be.bignumber.equal('0'); + expect(await this.mock.quorumNumerator()).to.be.bignumber.equal(ratio); + expect(await this.mock.quorumDenominator()).to.be.bignumber.equal('100'); + expect(await clock[mode]().then(timepoint => this.mock.quorum(timepoint - 1))).to.be.bignumber.equal( + tokenSupply.mul(ratio).divn(100), + ); + }); + + it('quroum reached', async function () { + await this.helper.propose(); + await this.helper.waitForSnapshot(); + await this.helper.vote({ support: Enums.VoteType.For }, { from: voter1 }); + await this.helper.waitForDeadline(); + await this.helper.execute(); + }); + + it('quroum not reached', async function () { + await this.helper.propose(); + await this.helper.waitForSnapshot(); + await this.helper.vote({ support: Enums.VoteType.For }, { from: voter2 }); + await this.helper.waitForDeadline(); + await expectRevertCustomError(this.helper.execute(), 'GovernorUnexpectedProposalState', [ + this.proposal.id, + Enums.ProposalState.Defeated, + proposalStatesToBitMap([Enums.ProposalState.Succeeded, Enums.ProposalState.Queued]), + ]); + }); + + describe('onlyGovernance updates', function () { + it('updateQuorumNumerator is protected', async function () { + await expectRevertCustomError( + this.mock.updateQuorumNumerator(newRatio, { from: owner }), + 'GovernorOnlyExecutor', + [owner], + ); + }); + + it('can updateQuorumNumerator through governance', async function () { + this.helper.setProposal( + [ + { + target: this.mock.address, + data: this.mock.contract.methods.updateQuorumNumerator(newRatio).encodeABI(), + }, + ], + '', + ); + + await this.helper.propose(); + await this.helper.waitForSnapshot(); + await this.helper.vote({ support: Enums.VoteType.For }, { from: voter1 }); + await this.helper.waitForDeadline(); + + expectEvent(await this.helper.execute(), 'QuorumNumeratorUpdated', { + oldQuorumNumerator: ratio, + newQuorumNumerator: newRatio, + }); + + expect(await this.mock.quorumNumerator()).to.be.bignumber.equal(newRatio); + expect(await this.mock.quorumDenominator()).to.be.bignumber.equal('100'); + + // it takes one block for the new quorum to take effect + expect(await clock[mode]().then(blockNumber => this.mock.quorum(blockNumber - 1))).to.be.bignumber.equal( + tokenSupply.mul(ratio).divn(100), + ); + + await time.advanceBlock(); + + expect(await clock[mode]().then(blockNumber => this.mock.quorum(blockNumber - 1))).to.be.bignumber.equal( + tokenSupply.mul(newRatio).divn(100), + ); + }); + + it('cannot updateQuorumNumerator over the maximum', async function () { + const quorumNumerator = 101; + this.helper.setProposal( + [ + { + target: this.mock.address, + data: this.mock.contract.methods.updateQuorumNumerator(quorumNumerator).encodeABI(), + }, + ], + '', + ); + + await this.helper.propose(); + await this.helper.waitForSnapshot(); + await this.helper.vote({ support: Enums.VoteType.For }, { from: voter1 }); + await this.helper.waitForDeadline(); + + const quorumDenominator = await this.mock.quorumDenominator(); + + await expectRevertCustomError(this.helper.execute(), 'GovernorInvalidQuorumFraction', [ + quorumNumerator, + quorumDenominator, + ]); + }); + }); + }); + } +}); diff --git a/test/governance/extensions/GovernorWithParams.test.js b/test/governance/extensions/GovernorWithParams.test.js new file mode 100644 index 000000000..35da3a0f3 --- /dev/null +++ b/test/governance/extensions/GovernorWithParams.test.js @@ -0,0 +1,277 @@ +const { expectEvent } = require('@openzeppelin/test-helpers'); +const { expect } = require('chai'); +const ethSigUtil = require('eth-sig-util'); +const Wallet = require('ethereumjs-wallet').default; + +const Enums = require('../../helpers/enums'); +const { getDomain, domainType } = require('../../helpers/eip712'); +const { GovernorHelper } = require('../../helpers/governance'); +const { expectRevertCustomError } = require('../../helpers/customError'); + +const Governor = artifacts.require('$GovernorWithParamsMock'); +const CallReceiver = artifacts.require('CallReceiverMock'); +const ERC1271WalletMock = artifacts.require('ERC1271WalletMock'); + +const rawParams = { + uintParam: web3.utils.toBN('42'), + strParam: 'These are my params', +}; + +const encodedParams = web3.eth.abi.encodeParameters(['uint256', 'string'], Object.values(rawParams)); + +const TOKENS = [ + { Token: artifacts.require('$ERC20Votes'), mode: 'blocknumber' }, + { Token: artifacts.require('$ERC20VotesTimestampMock'), mode: 'timestamp' }, +]; + +contract('GovernorWithParams', function (accounts) { + const [owner, proposer, voter1, voter2, voter3, voter4] = accounts; + + const name = 'OZ-Governor'; + const version = '1'; + const tokenName = 'MockToken'; + const tokenSymbol = 'MTKN'; + const tokenSupply = web3.utils.toWei('100'); + const votingDelay = web3.utils.toBN(4); + const votingPeriod = web3.utils.toBN(16); + const value = web3.utils.toWei('1'); + + for (const { mode, Token } of TOKENS) { + describe(`using ${Token._json.contractName}`, function () { + beforeEach(async function () { + this.chainId = await web3.eth.getChainId(); + this.token = await Token.new(tokenName, tokenSymbol, tokenName, version); + this.mock = await Governor.new(name, this.token.address); + this.receiver = await CallReceiver.new(); + + this.helper = new GovernorHelper(this.mock, mode); + + await web3.eth.sendTransaction({ from: owner, to: this.mock.address, value }); + + await this.token.$_mint(owner, tokenSupply); + await this.helper.delegate({ token: this.token, to: voter1, value: web3.utils.toWei('10') }, { from: owner }); + await this.helper.delegate({ token: this.token, to: voter2, value: web3.utils.toWei('7') }, { from: owner }); + await this.helper.delegate({ token: this.token, to: voter3, value: web3.utils.toWei('5') }, { from: owner }); + await this.helper.delegate({ token: this.token, to: voter4, value: web3.utils.toWei('2') }, { from: owner }); + + // default proposal + this.proposal = this.helper.setProposal( + [ + { + target: this.receiver.address, + value, + data: this.receiver.contract.methods.mockFunction().encodeABI(), + }, + ], + '', + ); + }); + + it('deployment check', async function () { + expect(await this.mock.name()).to.be.equal(name); + expect(await this.mock.token()).to.be.equal(this.token.address); + expect(await this.mock.votingDelay()).to.be.bignumber.equal(votingDelay); + expect(await this.mock.votingPeriod()).to.be.bignumber.equal(votingPeriod); + }); + + it('nominal is unaffected', async function () { + await this.helper.propose({ from: proposer }); + await this.helper.waitForSnapshot(); + await this.helper.vote({ support: Enums.VoteType.For, reason: 'This is nice' }, { from: voter1 }); + await this.helper.vote({ support: Enums.VoteType.For }, { from: voter2 }); + await this.helper.vote({ support: Enums.VoteType.Against }, { from: voter3 }); + await this.helper.vote({ support: Enums.VoteType.Abstain }, { from: voter4 }); + await this.helper.waitForDeadline(); + await this.helper.execute(); + + expect(await this.mock.hasVoted(this.proposal.id, owner)).to.be.equal(false); + expect(await this.mock.hasVoted(this.proposal.id, voter1)).to.be.equal(true); + expect(await this.mock.hasVoted(this.proposal.id, voter2)).to.be.equal(true); + expect(await web3.eth.getBalance(this.mock.address)).to.be.bignumber.equal('0'); + expect(await web3.eth.getBalance(this.receiver.address)).to.be.bignumber.equal(value); + }); + + it('Voting with params is properly supported', async function () { + await this.helper.propose({ from: proposer }); + await this.helper.waitForSnapshot(); + + const weight = web3.utils.toBN(web3.utils.toWei('7')).sub(rawParams.uintParam); + + const tx = await this.helper.vote( + { + support: Enums.VoteType.For, + reason: 'no particular reason', + params: encodedParams, + }, + { from: voter2 }, + ); + + expectEvent(tx, 'CountParams', { ...rawParams }); + expectEvent(tx, 'VoteCastWithParams', { + voter: voter2, + proposalId: this.proposal.id, + support: Enums.VoteType.For, + weight, + reason: 'no particular reason', + params: encodedParams, + }); + + const votes = await this.mock.proposalVotes(this.proposal.id); + expect(votes.forVotes).to.be.bignumber.equal(weight); + }); + + describe('voting by signature', function () { + beforeEach(async function () { + this.voterBySig = Wallet.generate(); + this.voterBySig.address = web3.utils.toChecksumAddress(this.voterBySig.getAddressString()); + + this.data = (contract, message) => + getDomain(contract).then(domain => ({ + primaryType: 'ExtendedBallot', + types: { + EIP712Domain: domainType(domain), + ExtendedBallot: [ + { name: 'proposalId', type: 'uint256' }, + { name: 'support', type: 'uint8' }, + { name: 'voter', type: 'address' }, + { name: 'nonce', type: 'uint256' }, + { name: 'reason', type: 'string' }, + { name: 'params', type: 'bytes' }, + ], + }, + domain, + message, + })); + + this.sign = privateKey => async (contract, message) => + ethSigUtil.signTypedMessage(privateKey, { data: await this.data(contract, message) }); + }); + + it('supports EOA signatures', async function () { + await this.token.delegate(this.voterBySig.address, { from: voter2 }); + + const weight = web3.utils.toBN(web3.utils.toWei('7')).sub(rawParams.uintParam); + + const nonce = await this.mock.nonces(this.voterBySig.address); + + // Run proposal + await this.helper.propose(); + await this.helper.waitForSnapshot(); + const tx = await this.helper.vote({ + support: Enums.VoteType.For, + voter: this.voterBySig.address, + nonce, + reason: 'no particular reason', + params: encodedParams, + signature: this.sign(this.voterBySig.getPrivateKey()), + }); + + expectEvent(tx, 'CountParams', { ...rawParams }); + expectEvent(tx, 'VoteCastWithParams', { + voter: this.voterBySig.address, + proposalId: this.proposal.id, + support: Enums.VoteType.For, + weight, + reason: 'no particular reason', + params: encodedParams, + }); + + const votes = await this.mock.proposalVotes(this.proposal.id); + expect(votes.forVotes).to.be.bignumber.equal(weight); + expect(await this.mock.nonces(this.voterBySig.address)).to.be.bignumber.equal(nonce.addn(1)); + }); + + it('supports EIP-1271 signature signatures', async function () { + const ERC1271WalletOwner = Wallet.generate(); + ERC1271WalletOwner.address = web3.utils.toChecksumAddress(ERC1271WalletOwner.getAddressString()); + + const wallet = await ERC1271WalletMock.new(ERC1271WalletOwner.address); + + await this.token.delegate(wallet.address, { from: voter2 }); + + const weight = web3.utils.toBN(web3.utils.toWei('7')).sub(rawParams.uintParam); + + const nonce = await this.mock.nonces(wallet.address); + + // Run proposal + await this.helper.propose(); + await this.helper.waitForSnapshot(); + const tx = await this.helper.vote({ + support: Enums.VoteType.For, + voter: wallet.address, + nonce, + reason: 'no particular reason', + params: encodedParams, + signature: this.sign(ERC1271WalletOwner.getPrivateKey()), + }); + + expectEvent(tx, 'CountParams', { ...rawParams }); + expectEvent(tx, 'VoteCastWithParams', { + voter: wallet.address, + proposalId: this.proposal.id, + support: Enums.VoteType.For, + weight, + reason: 'no particular reason', + params: encodedParams, + }); + + const votes = await this.mock.proposalVotes(this.proposal.id); + expect(votes.forVotes).to.be.bignumber.equal(weight); + expect(await this.mock.nonces(wallet.address)).to.be.bignumber.equal(nonce.addn(1)); + }); + + it('reverts if signature does not match signer', async function () { + await this.token.delegate(this.voterBySig.address, { from: voter2 }); + + const nonce = await this.mock.nonces(this.voterBySig.address); + + const signature = this.sign(this.voterBySig.getPrivateKey()); + + // Run proposal + await this.helper.propose(); + await this.helper.waitForSnapshot(); + const voteParams = { + support: Enums.VoteType.For, + voter: this.voterBySig.address, + nonce, + signature: async (...params) => { + const sig = await signature(...params); + const tamperedSig = web3.utils.hexToBytes(sig); + tamperedSig[42] ^= 0xff; + return web3.utils.bytesToHex(tamperedSig); + }, + reason: 'no particular reason', + params: encodedParams, + }; + + await expectRevertCustomError(this.helper.vote(voteParams), 'GovernorInvalidSignature', [voteParams.voter]); + }); + + it('reverts if vote nonce is incorrect', async function () { + await this.token.delegate(this.voterBySig.address, { from: voter2 }); + + const nonce = await this.mock.nonces(this.voterBySig.address); + + // Run proposal + await this.helper.propose(); + await this.helper.waitForSnapshot(); + const voteParams = { + support: Enums.VoteType.For, + voter: this.voterBySig.address, + nonce: nonce.addn(1), + signature: this.sign(this.voterBySig.getPrivateKey()), + reason: 'no particular reason', + params: encodedParams, + }; + + await expectRevertCustomError( + this.helper.vote(voteParams), + // The signature check implies the nonce can't be tampered without changing the signer + 'GovernorInvalidSignature', + [voteParams.voter], + ); + }); + }); + }); + } +}); diff --git a/test/governance/utils/EIP6372.behavior.js b/test/governance/utils/EIP6372.behavior.js new file mode 100644 index 000000000..022ec3568 --- /dev/null +++ b/test/governance/utils/EIP6372.behavior.js @@ -0,0 +1,23 @@ +const { clock } = require('../../helpers/time'); + +function shouldBehaveLikeEIP6372(mode = 'blocknumber') { + describe('should implement EIP6372', function () { + beforeEach(async function () { + this.mock = this.mock ?? this.token ?? this.votes; + }); + + it('clock is correct', async function () { + expect(await this.mock.clock()).to.be.bignumber.equal(await clock[mode]().then(web3.utils.toBN)); + }); + + it('CLOCK_MODE is correct', async function () { + const params = new URLSearchParams(await this.mock.CLOCK_MODE()); + expect(params.get('mode')).to.be.equal(mode); + expect(params.get('from')).to.be.equal(mode == 'blocknumber' ? 'default' : null); + }); + }); +} + +module.exports = { + shouldBehaveLikeEIP6372, +}; diff --git a/test/governance/utils/Votes.behavior.js b/test/governance/utils/Votes.behavior.js new file mode 100644 index 000000000..5836cc351 --- /dev/null +++ b/test/governance/utils/Votes.behavior.js @@ -0,0 +1,360 @@ +const { constants, expectEvent, time } = require('@openzeppelin/test-helpers'); + +const { MAX_UINT256, ZERO_ADDRESS } = constants; + +const { fromRpcSig } = require('ethereumjs-util'); +const ethSigUtil = require('eth-sig-util'); +const Wallet = require('ethereumjs-wallet').default; + +const { shouldBehaveLikeEIP6372 } = require('./EIP6372.behavior'); +const { getDomain, domainType } = require('../../helpers/eip712'); +const { clockFromReceipt } = require('../../helpers/time'); +const { expectRevertCustomError } = require('../../helpers/customError'); + +const Delegation = [ + { name: 'delegatee', type: 'address' }, + { name: 'nonce', type: 'uint256' }, + { name: 'expiry', type: 'uint256' }, +]; + +const buildAndSignDelegation = (contract, message, pk) => + getDomain(contract) + .then(domain => ({ + primaryType: 'Delegation', + types: { EIP712Domain: domainType(domain), Delegation }, + domain, + message, + })) + .then(data => fromRpcSig(ethSigUtil.signTypedMessage(pk, { data }))); + +function shouldBehaveLikeVotes(accounts, tokens, { mode = 'blocknumber', fungible = true }) { + shouldBehaveLikeEIP6372(mode); + + const getWeight = token => web3.utils.toBN(fungible ? token : 1); + + describe('run votes workflow', function () { + it('initial nonce is 0', async function () { + expect(await this.votes.nonces(accounts[0])).to.be.bignumber.equal('0'); + }); + + describe('delegation with signature', function () { + const token = tokens[0]; + + it('delegation without tokens', async function () { + expect(await this.votes.delegates(accounts[1])).to.be.equal(ZERO_ADDRESS); + + const { receipt } = await this.votes.delegate(accounts[1], { from: accounts[1] }); + expectEvent(receipt, 'DelegateChanged', { + delegator: accounts[1], + fromDelegate: ZERO_ADDRESS, + toDelegate: accounts[1], + }); + expectEvent.notEmitted(receipt, 'DelegateVotesChanged'); + + expect(await this.votes.delegates(accounts[1])).to.be.equal(accounts[1]); + }); + + it('delegation with tokens', async function () { + await this.votes.$_mint(accounts[1], token); + const weight = getWeight(token); + + expect(await this.votes.delegates(accounts[1])).to.be.equal(ZERO_ADDRESS); + + const { receipt } = await this.votes.delegate(accounts[1], { from: accounts[1] }); + const timepoint = await clockFromReceipt[mode](receipt); + + expectEvent(receipt, 'DelegateChanged', { + delegator: accounts[1], + fromDelegate: ZERO_ADDRESS, + toDelegate: accounts[1], + }); + expectEvent(receipt, 'DelegateVotesChanged', { + delegate: accounts[1], + previousVotes: '0', + newVotes: weight, + }); + + expect(await this.votes.delegates(accounts[1])).to.be.equal(accounts[1]); + expect(await this.votes.getVotes(accounts[1])).to.be.bignumber.equal(weight); + expect(await this.votes.getPastVotes(accounts[1], timepoint - 1)).to.be.bignumber.equal('0'); + await time.advanceBlock(); + expect(await this.votes.getPastVotes(accounts[1], timepoint)).to.be.bignumber.equal(weight); + }); + + it('delegation update', async function () { + await this.votes.delegate(accounts[1], { from: accounts[1] }); + await this.votes.$_mint(accounts[1], token); + const weight = getWeight(token); + + expect(await this.votes.delegates(accounts[1])).to.be.equal(accounts[1]); + expect(await this.votes.getVotes(accounts[1])).to.be.bignumber.equal(weight); + expect(await this.votes.getVotes(accounts[2])).to.be.bignumber.equal('0'); + + const { receipt } = await this.votes.delegate(accounts[2], { from: accounts[1] }); + const timepoint = await clockFromReceipt[mode](receipt); + + expectEvent(receipt, 'DelegateChanged', { + delegator: accounts[1], + fromDelegate: accounts[1], + toDelegate: accounts[2], + }); + expectEvent(receipt, 'DelegateVotesChanged', { + delegate: accounts[1], + previousVotes: weight, + newVotes: '0', + }); + expectEvent(receipt, 'DelegateVotesChanged', { + delegate: accounts[2], + previousVotes: '0', + newVotes: weight, + }); + + expect(await this.votes.delegates(accounts[1])).to.be.equal(accounts[2]); + expect(await this.votes.getVotes(accounts[1])).to.be.bignumber.equal('0'); + expect(await this.votes.getVotes(accounts[2])).to.be.bignumber.equal(weight); + + expect(await this.votes.getPastVotes(accounts[1], timepoint - 1)).to.be.bignumber.equal(weight); + expect(await this.votes.getPastVotes(accounts[2], timepoint - 1)).to.be.bignumber.equal('0'); + await time.advanceBlock(); + expect(await this.votes.getPastVotes(accounts[1], timepoint)).to.be.bignumber.equal('0'); + expect(await this.votes.getPastVotes(accounts[2], timepoint)).to.be.bignumber.equal(weight); + }); + + describe('with signature', function () { + const delegator = Wallet.generate(); + const [delegatee, other] = accounts; + const nonce = 0; + delegator.address = web3.utils.toChecksumAddress(delegator.getAddressString()); + + it('accept signed delegation', async function () { + await this.votes.$_mint(delegator.address, token); + const weight = getWeight(token); + + const { v, r, s } = await buildAndSignDelegation( + this.votes, + { + delegatee, + nonce, + expiry: MAX_UINT256, + }, + delegator.getPrivateKey(), + ); + + expect(await this.votes.delegates(delegator.address)).to.be.equal(ZERO_ADDRESS); + + const { receipt } = await this.votes.delegateBySig(delegatee, nonce, MAX_UINT256, v, r, s); + const timepoint = await clockFromReceipt[mode](receipt); + + expectEvent(receipt, 'DelegateChanged', { + delegator: delegator.address, + fromDelegate: ZERO_ADDRESS, + toDelegate: delegatee, + }); + expectEvent(receipt, 'DelegateVotesChanged', { + delegate: delegatee, + previousVotes: '0', + newVotes: weight, + }); + + expect(await this.votes.delegates(delegator.address)).to.be.equal(delegatee); + expect(await this.votes.getVotes(delegator.address)).to.be.bignumber.equal('0'); + expect(await this.votes.getVotes(delegatee)).to.be.bignumber.equal(weight); + expect(await this.votes.getPastVotes(delegatee, timepoint - 1)).to.be.bignumber.equal('0'); + await time.advanceBlock(); + expect(await this.votes.getPastVotes(delegatee, timepoint)).to.be.bignumber.equal(weight); + }); + + it('rejects reused signature', async function () { + const { v, r, s } = await buildAndSignDelegation( + this.votes, + { + delegatee, + nonce, + expiry: MAX_UINT256, + }, + delegator.getPrivateKey(), + ); + + await this.votes.delegateBySig(delegatee, nonce, MAX_UINT256, v, r, s); + + await expectRevertCustomError( + this.votes.delegateBySig(delegatee, nonce, MAX_UINT256, v, r, s), + 'InvalidAccountNonce', + [delegator.address, nonce + 1], + ); + }); + + it('rejects bad delegatee', async function () { + const { v, r, s } = await buildAndSignDelegation( + this.votes, + { + delegatee, + nonce, + expiry: MAX_UINT256, + }, + delegator.getPrivateKey(), + ); + + const receipt = await this.votes.delegateBySig(other, nonce, MAX_UINT256, v, r, s); + const { args } = receipt.logs.find(({ event }) => event === 'DelegateChanged'); + expect(args.delegator).to.not.be.equal(delegator.address); + expect(args.fromDelegate).to.be.equal(ZERO_ADDRESS); + expect(args.toDelegate).to.be.equal(other); + }); + + it('rejects bad nonce', async function () { + const { v, r, s } = await buildAndSignDelegation( + this.votes, + { + delegatee, + nonce: nonce + 1, + expiry: MAX_UINT256, + }, + delegator.getPrivateKey(), + ); + + await expectRevertCustomError( + this.votes.delegateBySig(delegatee, nonce + 1, MAX_UINT256, v, r, s), + 'InvalidAccountNonce', + [delegator.address, 0], + ); + }); + + it('rejects expired permit', async function () { + const expiry = (await time.latest()) - time.duration.weeks(1); + const { v, r, s } = await buildAndSignDelegation( + this.votes, + { + delegatee, + nonce, + expiry, + }, + delegator.getPrivateKey(), + ); + + await expectRevertCustomError( + this.votes.delegateBySig(delegatee, nonce, expiry, v, r, s), + 'VotesExpiredSignature', + [expiry], + ); + }); + }); + }); + + describe('getPastTotalSupply', function () { + beforeEach(async function () { + await this.votes.delegate(accounts[1], { from: accounts[1] }); + }); + + it('reverts if block number >= current block', async function () { + const timepoint = 5e10; + const clock = await this.votes.clock(); + await expectRevertCustomError(this.votes.getPastTotalSupply(timepoint), 'ERC5805FutureLookup', [ + timepoint, + clock, + ]); + }); + + it('returns 0 if there are no checkpoints', async function () { + expect(await this.votes.getPastTotalSupply(0)).to.be.bignumber.equal('0'); + }); + + it('returns the correct checkpointed total supply', async function () { + const weight = tokens.map(token => getWeight(token)); + + // t0 = mint #0 + const t0 = await this.votes.$_mint(accounts[1], tokens[0]); + await time.advanceBlock(); + // t1 = mint #1 + const t1 = await this.votes.$_mint(accounts[1], tokens[1]); + await time.advanceBlock(); + // t2 = burn #1 + const t2 = await this.votes.$_burn(...(fungible ? [accounts[1]] : []), tokens[1]); + await time.advanceBlock(); + // t3 = mint #2 + const t3 = await this.votes.$_mint(accounts[1], tokens[2]); + await time.advanceBlock(); + // t4 = burn #0 + const t4 = await this.votes.$_burn(...(fungible ? [accounts[1]] : []), tokens[0]); + await time.advanceBlock(); + // t5 = burn #2 + const t5 = await this.votes.$_burn(...(fungible ? [accounts[1]] : []), tokens[2]); + await time.advanceBlock(); + + t0.timepoint = await clockFromReceipt[mode](t0.receipt); + t1.timepoint = await clockFromReceipt[mode](t1.receipt); + t2.timepoint = await clockFromReceipt[mode](t2.receipt); + t3.timepoint = await clockFromReceipt[mode](t3.receipt); + t4.timepoint = await clockFromReceipt[mode](t4.receipt); + t5.timepoint = await clockFromReceipt[mode](t5.receipt); + + expect(await this.votes.getPastTotalSupply(t0.timepoint - 1)).to.be.bignumber.equal('0'); + expect(await this.votes.getPastTotalSupply(t0.timepoint)).to.be.bignumber.equal(weight[0]); + expect(await this.votes.getPastTotalSupply(t0.timepoint + 1)).to.be.bignumber.equal(weight[0]); + expect(await this.votes.getPastTotalSupply(t1.timepoint)).to.be.bignumber.equal(weight[0].add(weight[1])); + expect(await this.votes.getPastTotalSupply(t1.timepoint + 1)).to.be.bignumber.equal(weight[0].add(weight[1])); + expect(await this.votes.getPastTotalSupply(t2.timepoint)).to.be.bignumber.equal(weight[0]); + expect(await this.votes.getPastTotalSupply(t2.timepoint + 1)).to.be.bignumber.equal(weight[0]); + expect(await this.votes.getPastTotalSupply(t3.timepoint)).to.be.bignumber.equal(weight[0].add(weight[2])); + expect(await this.votes.getPastTotalSupply(t3.timepoint + 1)).to.be.bignumber.equal(weight[0].add(weight[2])); + expect(await this.votes.getPastTotalSupply(t4.timepoint)).to.be.bignumber.equal(weight[2]); + expect(await this.votes.getPastTotalSupply(t4.timepoint + 1)).to.be.bignumber.equal(weight[2]); + expect(await this.votes.getPastTotalSupply(t5.timepoint)).to.be.bignumber.equal('0'); + await expectRevertCustomError(this.votes.getPastTotalSupply(t5.timepoint + 1), 'ERC5805FutureLookup', [ + t5.timepoint + 1, // timepoint + t5.timepoint + 1, // clock + ]); + }); + }); + + // The following tests are an adaptation of + // https://github.com/compound-finance/compound-protocol/blob/master/tests/Governance/CompTest.js. + describe('Compound test suite', function () { + beforeEach(async function () { + await this.votes.$_mint(accounts[1], tokens[0]); + await this.votes.$_mint(accounts[1], tokens[1]); + await this.votes.$_mint(accounts[1], tokens[2]); + }); + + describe('getPastVotes', function () { + it('reverts if block number >= current block', async function () { + const clock = await this.votes.clock(); + const timepoint = 5e10; // far in the future + await expectRevertCustomError(this.votes.getPastVotes(accounts[2], timepoint), 'ERC5805FutureLookup', [ + timepoint, + clock, + ]); + }); + + it('returns 0 if there are no checkpoints', async function () { + expect(await this.votes.getPastVotes(accounts[2], 0)).to.be.bignumber.equal('0'); + }); + + it('returns the latest block if >= last checkpoint block', async function () { + const { receipt } = await this.votes.delegate(accounts[2], { from: accounts[1] }); + const timepoint = await clockFromReceipt[mode](receipt); + await time.advanceBlock(); + await time.advanceBlock(); + + const latest = await this.votes.getVotes(accounts[2]); + expect(await this.votes.getPastVotes(accounts[2], timepoint)).to.be.bignumber.equal(latest); + expect(await this.votes.getPastVotes(accounts[2], timepoint + 1)).to.be.bignumber.equal(latest); + }); + + it('returns zero if < first checkpoint block', async function () { + await time.advanceBlock(); + const { receipt } = await this.votes.delegate(accounts[2], { from: accounts[1] }); + const timepoint = await clockFromReceipt[mode](receipt); + await time.advanceBlock(); + await time.advanceBlock(); + + expect(await this.votes.getPastVotes(accounts[2], timepoint - 1)).to.be.bignumber.equal('0'); + }); + }); + }); + }); +} + +module.exports = { + shouldBehaveLikeVotes, +}; diff --git a/test/governance/utils/Votes.test.js b/test/governance/utils/Votes.test.js new file mode 100644 index 000000000..b2b80f9fe --- /dev/null +++ b/test/governance/utils/Votes.test.js @@ -0,0 +1,92 @@ +const { constants } = require('@openzeppelin/test-helpers'); +const { expect } = require('chai'); +const { clockFromReceipt } = require('../../helpers/time'); +const { BNsum } = require('../../helpers/math'); +const { expectRevertCustomError } = require('../../helpers/customError'); + +require('array.prototype.at/auto'); + +const { shouldBehaveLikeVotes } = require('./Votes.behavior'); + +const MODES = { + blocknumber: artifacts.require('$VotesMock'), + timestamp: artifacts.require('$VotesTimestampMock'), +}; + +contract('Votes', function (accounts) { + const [account1, account2, account3] = accounts; + const amounts = { + [account1]: web3.utils.toBN('10000000000000000000000000'), + [account2]: web3.utils.toBN('10'), + [account3]: web3.utils.toBN('20'), + }; + + const name = 'My Vote'; + const version = '1'; + + for (const [mode, artifact] of Object.entries(MODES)) { + describe(`vote with ${mode}`, function () { + beforeEach(async function () { + this.votes = await artifact.new(name, version); + }); + + shouldBehaveLikeVotes(accounts, Object.values(amounts), { mode, fungible: true }); + + it('starts with zero votes', async function () { + expect(await this.votes.getTotalSupply()).to.be.bignumber.equal('0'); + }); + + describe('performs voting operations', function () { + beforeEach(async function () { + this.txs = []; + for (const [account, amount] of Object.entries(amounts)) { + this.txs.push(await this.votes.$_mint(account, amount)); + } + }); + + it('reverts if block number >= current block', async function () { + const lastTxTimepoint = await clockFromReceipt[mode](this.txs.at(-1).receipt); + const clock = await this.votes.clock(); + await expectRevertCustomError(this.votes.getPastTotalSupply(lastTxTimepoint + 1), 'ERC5805FutureLookup', [ + lastTxTimepoint + 1, + clock, + ]); + }); + + it('delegates', async function () { + expect(await this.votes.getVotes(account1)).to.be.bignumber.equal('0'); + expect(await this.votes.getVotes(account2)).to.be.bignumber.equal('0'); + expect(await this.votes.delegates(account1)).to.be.equal(constants.ZERO_ADDRESS); + expect(await this.votes.delegates(account2)).to.be.equal(constants.ZERO_ADDRESS); + + await this.votes.delegate(account1, account1); + + expect(await this.votes.getVotes(account1)).to.be.bignumber.equal(amounts[account1]); + expect(await this.votes.getVotes(account2)).to.be.bignumber.equal('0'); + expect(await this.votes.delegates(account1)).to.be.equal(account1); + expect(await this.votes.delegates(account2)).to.be.equal(constants.ZERO_ADDRESS); + + await this.votes.delegate(account2, account1); + + expect(await this.votes.getVotes(account1)).to.be.bignumber.equal(amounts[account1].add(amounts[account2])); + expect(await this.votes.getVotes(account2)).to.be.bignumber.equal('0'); + expect(await this.votes.delegates(account1)).to.be.equal(account1); + expect(await this.votes.delegates(account2)).to.be.equal(account1); + }); + + it('cross delegates', async function () { + await this.votes.delegate(account1, account2); + await this.votes.delegate(account2, account1); + + expect(await this.votes.getVotes(account1)).to.be.bignumber.equal(amounts[account2]); + expect(await this.votes.getVotes(account2)).to.be.bignumber.equal(amounts[account1]); + }); + + it('returns total amount of votes', async function () { + const totalSupply = BNsum(...Object.values(amounts)); + expect(await this.votes.getTotalSupply()).to.be.bignumber.equal(totalSupply); + }); + }); + }); + } +}); diff --git a/test/helpers/account.js b/test/helpers/account.js new file mode 100644 index 000000000..1b01a7214 --- /dev/null +++ b/test/helpers/account.js @@ -0,0 +1,14 @@ +const { web3 } = require('hardhat'); +const { impersonateAccount, setBalance } = require('@nomicfoundation/hardhat-network-helpers'); + +// Hardhat default balance +const DEFAULT_BALANCE = web3.utils.toBN('10000000000000000000000'); + +async function impersonate(account, balance = DEFAULT_BALANCE) { + await impersonateAccount(account); + await setBalance(account, balance); +} + +module.exports = { + impersonate, +}; diff --git a/test/helpers/chainid.js b/test/helpers/chainid.js new file mode 100644 index 000000000..58757eb80 --- /dev/null +++ b/test/helpers/chainid.js @@ -0,0 +1,10 @@ +const hre = require('hardhat'); + +async function getChainId() { + const chainIdHex = await hre.network.provider.send('eth_chainId', []); + return new hre.web3.utils.BN(chainIdHex, 'hex'); +} + +module.exports = { + getChainId, +}; diff --git a/test/helpers/constants.js b/test/helpers/constants.js new file mode 100644 index 000000000..0f4d028cf --- /dev/null +++ b/test/helpers/constants.js @@ -0,0 +1,7 @@ +const MAX_UINT48 = web3.utils.toBN(1).shln(48).subn(1).toString(); +const MAX_UINT64 = web3.utils.toBN(1).shln(64).subn(1).toString(); + +module.exports = { + MAX_UINT48, + MAX_UINT64, +}; diff --git a/test/helpers/create.js b/test/helpers/create.js new file mode 100644 index 000000000..98a0d4c47 --- /dev/null +++ b/test/helpers/create.js @@ -0,0 +1,22 @@ +const RLP = require('rlp'); + +function computeCreateAddress(deployer, nonce) { + return web3.utils.toChecksumAddress(web3.utils.sha3(RLP.encode([deployer.address ?? deployer, nonce])).slice(-40)); +} + +function computeCreate2Address(saltHex, bytecode, deployer) { + return web3.utils.toChecksumAddress( + web3.utils + .sha3( + `0x${['ff', deployer.address ?? deployer, saltHex, web3.utils.soliditySha3(bytecode)] + .map(x => x.replace(/0x/, '')) + .join('')}`, + ) + .slice(-40), + ); +} + +module.exports = { + computeCreateAddress, + computeCreate2Address, +}; diff --git a/test/helpers/customError.js b/test/helpers/customError.js new file mode 100644 index 000000000..ea5c36820 --- /dev/null +++ b/test/helpers/customError.js @@ -0,0 +1,43 @@ +const { expect } = require('chai'); + +/** Revert handler that supports custom errors. */ +async function expectRevertCustomError(promise, expectedErrorName, args) { + if (!Array.isArray(args)) { + expect.fail('Expected 3rd array parameter for error arguments'); + } + + await promise.then( + () => expect.fail("Expected promise to throw but it didn't"), + ({ message }) => { + // The revert message for custom errors looks like: + // VM Exception while processing transaction: + // reverted with custom error 'InvalidAccountNonce("0x70997970C51812dc3A010C7d01b50e0d17dc79C8", 0)' + + // Attempt to parse as a custom error + const match = message.match(/custom error '(?\w+)\((?.*)\)'/); + if (!match) { + expect.fail(`Could not parse as custom error. ${message}`); + } + // Extract the error name and parameters + const errorName = match.groups.name; + const argMatches = [...match.groups.args.matchAll(/-?\w+/g)]; + + // Assert error name + expect(errorName).to.be.equal( + expectedErrorName, + `Unexpected custom error name (with found args: [${argMatches.map(([a]) => a)}])`, + ); + + // Coerce to string for comparison since `arg` can be either a number or hex. + const sanitizedExpected = args.map(arg => arg.toString().toLowerCase()); + const sanitizedActual = argMatches.map(([arg]) => arg.toString().toLowerCase()); + + // Assert argument equality + expect(sanitizedActual).to.have.members(sanitizedExpected, `Unexpected ${errorName} arguments`); + }, + ); +} + +module.exports = { + expectRevertCustomError, +}; diff --git a/test/helpers/eip712.js b/test/helpers/eip712.js new file mode 100644 index 000000000..b12a6233e --- /dev/null +++ b/test/helpers/eip712.js @@ -0,0 +1,67 @@ +const ethSigUtil = require('eth-sig-util'); +const keccak256 = require('keccak256'); + +const EIP712Domain = [ + { name: 'name', type: 'string' }, + { name: 'version', type: 'string' }, + { name: 'chainId', type: 'uint256' }, + { name: 'verifyingContract', type: 'address' }, + { name: 'salt', type: 'bytes32' }, +]; + +const Permit = [ + { name: 'owner', type: 'address' }, + { name: 'spender', type: 'address' }, + { name: 'value', type: 'uint256' }, + { name: 'nonce', type: 'uint256' }, + { name: 'deadline', type: 'uint256' }, +]; + +function bufferToHexString(buffer) { + return '0x' + buffer.toString('hex'); +} + +function hexStringToBuffer(hexstr) { + return Buffer.from(hexstr.replace(/^0x/, ''), 'hex'); +} + +async function getDomain(contract) { + const { fields, name, version, chainId, verifyingContract, salt, extensions } = await contract.eip712Domain(); + + if (extensions.length > 0) { + throw Error('Extensions not implemented'); + } + + const domain = { name, version, chainId, verifyingContract, salt }; + for (const [i, { name }] of EIP712Domain.entries()) { + if (!(fields & (1 << i))) { + delete domain[name]; + } + } + + return domain; +} + +function domainType(domain) { + return EIP712Domain.filter(({ name }) => domain[name] !== undefined); +} + +function domainSeparator(domain) { + return bufferToHexString( + ethSigUtil.TypedDataUtils.hashStruct('EIP712Domain', domain, { EIP712Domain: domainType(domain) }), + ); +} + +function hashTypedData(domain, structHash) { + return bufferToHexString( + keccak256(Buffer.concat(['0x1901', domainSeparator(domain), structHash].map(str => hexStringToBuffer(str)))), + ); +} + +module.exports = { + Permit, + getDomain, + domainType, + domainSeparator, + hashTypedData, +}; diff --git a/test/helpers/enums.js b/test/helpers/enums.js new file mode 100644 index 000000000..6280e0f31 --- /dev/null +++ b/test/helpers/enums.js @@ -0,0 +1,11 @@ +function Enum(...options) { + return Object.fromEntries(options.map((key, i) => [key, web3.utils.toBN(i)])); +} + +module.exports = { + Enum, + ProposalState: Enum('Pending', 'Active', 'Canceled', 'Defeated', 'Succeeded', 'Queued', 'Expired', 'Executed'), + VoteType: Enum('Against', 'For', 'Abstain'), + Rounding: Enum('Floor', 'Ceil', 'Trunc', 'Expand'), + OperationState: Enum('Unset', 'Waiting', 'Ready', 'Done'), +}; diff --git a/test/helpers/erc1967.js b/test/helpers/erc1967.js new file mode 100644 index 000000000..4ad92c55c --- /dev/null +++ b/test/helpers/erc1967.js @@ -0,0 +1,43 @@ +const { getStorageAt, setStorageAt } = require('@nomicfoundation/hardhat-network-helpers'); + +const ImplementationLabel = 'eip1967.proxy.implementation'; +const AdminLabel = 'eip1967.proxy.admin'; +const BeaconLabel = 'eip1967.proxy.beacon'; + +function labelToSlot(label) { + return '0x' + web3.utils.toBN(web3.utils.keccak256(label)).subn(1).toString(16); +} + +function getSlot(address, slot) { + return getStorageAt( + web3.utils.isAddress(address) ? address : address.address, + web3.utils.isHex(slot) ? slot : labelToSlot(slot), + ); +} + +function setSlot(address, slot, value) { + const hexValue = web3.utils.isHex(value) ? value : web3.utils.toHex(value); + + return setStorageAt( + web3.utils.isAddress(address) ? address : address.address, + web3.utils.isHex(slot) ? slot : labelToSlot(slot), + web3.utils.padLeft(hexValue, 64), + ); +} + +async function getAddressInSlot(address, slot) { + const slotValue = await getSlot(address, slot); + return web3.utils.toChecksumAddress(slotValue.substring(slotValue.length - 40)); +} + +module.exports = { + ImplementationLabel, + AdminLabel, + BeaconLabel, + ImplementationSlot: labelToSlot(ImplementationLabel), + AdminSlot: labelToSlot(AdminLabel), + BeaconSlot: labelToSlot(BeaconLabel), + setSlot, + getSlot, + getAddressInSlot, +}; diff --git a/test/helpers/governance.js b/test/helpers/governance.js new file mode 100644 index 000000000..fc4e30095 --- /dev/null +++ b/test/helpers/governance.js @@ -0,0 +1,253 @@ +const { web3 } = require('hardhat'); +const { forward } = require('../helpers/time'); +const { ProposalState } = require('./enums'); + +function zip(...args) { + return Array(Math.max(...args.map(array => array.length))) + .fill() + .map((_, i) => args.map(array => array[i])); +} + +function concatHex(...args) { + return web3.utils.bytesToHex([].concat(...args.map(h => web3.utils.hexToBytes(h || '0x')))); +} + +function concatOpts(args, opts = null) { + return opts ? args.concat(opts) : args; +} + +const timelockSalt = (address, descriptionHash) => + '0x' + web3.utils.toBN(address).shln(96).xor(web3.utils.toBN(descriptionHash)).toString(16, 64); + +class GovernorHelper { + constructor(governor, mode = 'blocknumber') { + this.governor = governor; + this.mode = mode; + } + + delegate(delegation = {}, opts = null) { + return Promise.all([ + delegation.token.delegate(delegation.to, { from: delegation.to }), + delegation.value && delegation.token.transfer(...concatOpts([delegation.to, delegation.value]), opts), + delegation.tokenId && + delegation.token + .ownerOf(delegation.tokenId) + .then(owner => + delegation.token.transferFrom(...concatOpts([owner, delegation.to, delegation.tokenId], opts)), + ), + ]); + } + + propose(opts = null) { + const proposal = this.currentProposal; + + return this.governor.methods[ + proposal.useCompatibilityInterface + ? 'propose(address[],uint256[],string[],bytes[],string)' + : 'propose(address[],uint256[],bytes[],string)' + ](...concatOpts(proposal.fullProposal, opts)); + } + + queue(opts = null) { + const proposal = this.currentProposal; + + return proposal.useCompatibilityInterface + ? this.governor.methods['queue(uint256)'](...concatOpts([proposal.id], opts)) + : this.governor.methods['queue(address[],uint256[],bytes[],bytes32)']( + ...concatOpts(proposal.shortProposal, opts), + ); + } + + execute(opts = null) { + const proposal = this.currentProposal; + + return proposal.useCompatibilityInterface + ? this.governor.methods['execute(uint256)'](...concatOpts([proposal.id], opts)) + : this.governor.methods['execute(address[],uint256[],bytes[],bytes32)']( + ...concatOpts(proposal.shortProposal, opts), + ); + } + + cancel(visibility = 'external', opts = null) { + const proposal = this.currentProposal; + + switch (visibility) { + case 'external': + if (proposal.useCompatibilityInterface) { + return this.governor.methods['cancel(uint256)'](...concatOpts([proposal.id], opts)); + } else { + return this.governor.methods['cancel(address[],uint256[],bytes[],bytes32)']( + ...concatOpts(proposal.shortProposal, opts), + ); + } + case 'internal': + return this.governor.methods['$_cancel(address[],uint256[],bytes[],bytes32)']( + ...concatOpts(proposal.shortProposal, opts), + ); + default: + throw new Error(`unsupported visibility "${visibility}"`); + } + } + + vote(vote = {}, opts = null) { + const proposal = this.currentProposal; + + return vote.signature + ? // if signature, and either params or reason → + vote.params || vote.reason + ? this.sign(vote).then(signature => + this.governor.castVoteWithReasonAndParamsBySig( + ...concatOpts( + [proposal.id, vote.support, vote.voter, vote.reason || '', vote.params || '', signature], + opts, + ), + ), + ) + : this.sign(vote).then(signature => + this.governor.castVoteBySig(...concatOpts([proposal.id, vote.support, vote.voter, signature], opts)), + ) + : vote.params + ? // otherwise if params + this.governor.castVoteWithReasonAndParams( + ...concatOpts([proposal.id, vote.support, vote.reason || '', vote.params], opts), + ) + : vote.reason + ? // otherwise if reason + this.governor.castVoteWithReason(...concatOpts([proposal.id, vote.support, vote.reason], opts)) + : this.governor.castVote(...concatOpts([proposal.id, vote.support], opts)); + } + + sign(vote = {}) { + return vote.signature(this.governor, this.forgeMessage(vote)); + } + + forgeMessage(vote = {}) { + const proposal = this.currentProposal; + + const message = { proposalId: proposal.id, support: vote.support, voter: vote.voter, nonce: vote.nonce }; + + if (vote.params || vote.reason) { + message.reason = vote.reason || ''; + message.params = vote.params || ''; + } + + return message; + } + + async waitForSnapshot(offset = 0) { + const proposal = this.currentProposal; + const timepoint = await this.governor.proposalSnapshot(proposal.id); + return forward[this.mode](timepoint.addn(offset)); + } + + async waitForDeadline(offset = 0) { + const proposal = this.currentProposal; + const timepoint = await this.governor.proposalDeadline(proposal.id); + return forward[this.mode](timepoint.addn(offset)); + } + + async waitForEta(offset = 0) { + const proposal = this.currentProposal; + const timestamp = await this.governor.proposalEta(proposal.id); + return forward.timestamp(timestamp.addn(offset)); + } + + /** + * Specify a proposal either as + * 1) an array of objects [{ target, value, data, signature? }] + * 2) an object of arrays { targets: [], values: [], data: [], signatures?: [] } + */ + setProposal(actions, description) { + let targets, values, signatures, data, useCompatibilityInterface; + + if (Array.isArray(actions)) { + useCompatibilityInterface = actions.some(a => 'signature' in a); + targets = actions.map(a => a.target); + values = actions.map(a => a.value || '0'); + signatures = actions.map(a => a.signature || ''); + data = actions.map(a => a.data || '0x'); + } else { + useCompatibilityInterface = Array.isArray(actions.signatures); + ({ targets, values, signatures = [], data } = actions); + } + + const fulldata = zip( + signatures.map(s => s && web3.eth.abi.encodeFunctionSignature(s)), + data, + ).map(hexs => concatHex(...hexs)); + + const descriptionHash = web3.utils.keccak256(description); + + // condensed version for queueing end executing + const shortProposal = [targets, values, fulldata, descriptionHash]; + + // full version for proposing + const fullProposal = [targets, values, ...(useCompatibilityInterface ? [signatures] : []), data, description]; + + // proposal id + const id = web3.utils.toBN( + web3.utils.keccak256( + web3.eth.abi.encodeParameters(['address[]', 'uint256[]', 'bytes[]', 'bytes32'], shortProposal), + ), + ); + + this.currentProposal = { + id, + targets, + values, + signatures, + data, + fulldata, + description, + descriptionHash, + shortProposal, + fullProposal, + useCompatibilityInterface, + }; + + return this.currentProposal; + } +} + +/** + * Encodes a list ProposalStates into a bytes32 representation where each bit enabled corresponds to + * the underlying position in the `ProposalState` enum. For example: + * + * 0x000...10000 + * ^^^^^^------ ... + * ^----- Succeeded + * ^---- Defeated + * ^--- Canceled + * ^-- Active + * ^- Pending + */ +function proposalStatesToBitMap(proposalStates, options = {}) { + if (!Array.isArray(proposalStates)) { + proposalStates = [proposalStates]; + } + const statesCount = Object.keys(ProposalState).length; + let result = 0; + + const uniqueProposalStates = new Set(proposalStates.map(bn => bn.toNumber())); // Remove duplicates + for (const state of uniqueProposalStates) { + if (state < 0 || state >= statesCount) { + expect.fail(`ProposalState ${state} out of possible states (0...${statesCount}-1)`); + } else { + result |= 1 << state; + } + } + + if (options.inverted) { + const mask = 2 ** statesCount - 1; + result = result ^ mask; + } + + const hex = web3.utils.numberToHex(result); + return web3.utils.padLeft(hex, 64); +} + +module.exports = { + GovernorHelper, + proposalStatesToBitMap, + timelockSalt, +}; diff --git a/test/helpers/iterate.js b/test/helpers/iterate.js new file mode 100644 index 000000000..7f6e0e678 --- /dev/null +++ b/test/helpers/iterate.js @@ -0,0 +1,16 @@ +// Map values in an object +const mapValues = (obj, fn) => Object.fromEntries(Object.entries(obj).map(([k, v]) => [k, fn(v)])); + +// Array of number or bigint +const max = (...values) => values.slice(1).reduce((x, y) => (x > y ? x : y), values[0]); +const min = (...values) => values.slice(1).reduce((x, y) => (x < y ? x : y), values[0]); + +// Cartesian product of a list of arrays +const product = (...arrays) => arrays.reduce((a, b) => a.flatMap(ai => b.map(bi => [...ai, bi])), [[]]); + +module.exports = { + mapValues, + max, + min, + product, +}; diff --git a/test/helpers/math.js b/test/helpers/math.js new file mode 100644 index 000000000..2bc654c51 --- /dev/null +++ b/test/helpers/math.js @@ -0,0 +1,11 @@ +module.exports = { + // sum of integer / bignumber + sum: (...args) => args.reduce((acc, n) => acc + n, 0), + BNsum: (...args) => args.reduce((acc, n) => acc.add(n), web3.utils.toBN(0)), + // min of integer / bignumber + min: (...args) => args.slice(1).reduce((x, y) => (x < y ? x : y), args[0]), + BNmin: (...args) => args.slice(1).reduce((x, y) => (x.lt(y) ? x : y), args[0]), + // max of integer / bignumber + max: (...args) => args.slice(1).reduce((x, y) => (x > y ? x : y), args[0]), + BNmax: (...args) => args.slice(1).reduce((x, y) => (x.gt(y) ? x : y), args[0]), +}; diff --git a/test/helpers/methods.js b/test/helpers/methods.js new file mode 100644 index 000000000..cb30d8727 --- /dev/null +++ b/test/helpers/methods.js @@ -0,0 +1,5 @@ +const { soliditySha3 } = require('web3-utils'); + +module.exports = { + selector: signature => soliditySha3(signature).substring(0, 10), +}; diff --git a/test/helpers/sign.js b/test/helpers/sign.js new file mode 100644 index 000000000..d537116bb --- /dev/null +++ b/test/helpers/sign.js @@ -0,0 +1,63 @@ +function toEthSignedMessageHash(messageHex) { + const messageBuffer = Buffer.from(messageHex.substring(2), 'hex'); + const prefix = Buffer.from(`\u0019Ethereum Signed Message:\n${messageBuffer.length}`); + return web3.utils.sha3(Buffer.concat([prefix, messageBuffer])); +} + +/** + * Create a signed data with intended validator according to the version 0 of EIP-191 + * @param validatorAddress The address of the validator + * @param dataHex The data to be concatenated with the prefix and signed + */ +function toDataWithIntendedValidatorHash(validatorAddress, dataHex) { + const validatorBuffer = Buffer.from(web3.utils.hexToBytes(validatorAddress)); + const dataBuffer = Buffer.from(web3.utils.hexToBytes(dataHex)); + const preambleBuffer = Buffer.from('\x19'); + const versionBuffer = Buffer.from('\x00'); + const ethMessage = Buffer.concat([preambleBuffer, versionBuffer, validatorBuffer, dataBuffer]); + + return web3.utils.sha3(ethMessage); +} + +/** + * Create a signer between a contract and a signer for a voucher of method, args, and redeemer + * Note that `method` is the web3 method, not the truffle-contract method + * @param contract TruffleContract + * @param signer address + * @param redeemer address + * @param methodName string + * @param methodArgs any[] + */ +const getSignFor = + (contract, signer) => + (redeemer, methodName, methodArgs = []) => { + const parts = [contract.address, redeemer]; + + const REAL_SIGNATURE_SIZE = 2 * 65; // 65 bytes in hexadecimal string length + const PADDED_SIGNATURE_SIZE = 2 * 96; // 96 bytes in hexadecimal string length + const DUMMY_SIGNATURE = `0x${web3.utils.padLeft('', REAL_SIGNATURE_SIZE)}`; + + // if we have a method, add it to the parts that we're signing + if (methodName) { + if (methodArgs.length > 0) { + parts.push( + contract.contract.methods[methodName](...methodArgs.concat([DUMMY_SIGNATURE])) + .encodeABI() + .slice(0, -1 * PADDED_SIGNATURE_SIZE), + ); + } else { + const abi = contract.abi.find(abi => abi.name === methodName); + parts.push(abi.signature); + } + } + + // return the signature of the "Ethereum Signed Message" hash of the hash of `parts` + const messageHex = web3.utils.soliditySha3(...parts); + return web3.eth.sign(messageHex, signer); + }; + +module.exports = { + toEthSignedMessageHash, + toDataWithIntendedValidatorHash, + getSignFor, +}; diff --git a/test/helpers/time.js b/test/helpers/time.js new file mode 100644 index 000000000..30df8dc32 --- /dev/null +++ b/test/helpers/time.js @@ -0,0 +1,17 @@ +const ozHelpers = require('@openzeppelin/test-helpers'); +const helpers = require('@nomicfoundation/hardhat-network-helpers'); + +module.exports = { + clock: { + blocknumber: () => helpers.time.latestBlock(), + timestamp: () => helpers.time.latest(), + }, + clockFromReceipt: { + blocknumber: receipt => Promise.resolve(receipt.blockNumber), + timestamp: receipt => web3.eth.getBlock(receipt.blockNumber).then(block => block.timestamp), + }, + forward: { + blocknumber: ozHelpers.time.advanceBlockTo, + timestamp: helpers.time.increaseTo, + }, +}; diff --git a/test/helpers/txpool.js b/test/helpers/txpool.js new file mode 100644 index 000000000..ecdba5462 --- /dev/null +++ b/test/helpers/txpool.js @@ -0,0 +1,38 @@ +const { network } = require('hardhat'); +const { promisify } = require('util'); + +const queue = promisify(setImmediate); + +async function countPendingTransactions() { + return parseInt(await network.provider.send('eth_getBlockTransactionCountByNumber', ['pending'])); +} + +async function batchInBlock(txs) { + try { + // disable auto-mining + await network.provider.send('evm_setAutomine', [false]); + // send all transactions + const promises = txs.map(fn => fn()); + // wait for node to have all pending transactions + while (txs.length > (await countPendingTransactions())) { + await queue(); + } + // mine one block + await network.provider.send('evm_mine'); + // fetch receipts + const receipts = await Promise.all(promises); + // Sanity check, all tx should be in the same block + const minedBlocks = new Set(receipts.map(({ receipt }) => receipt.blockNumber)); + expect(minedBlocks.size).to.equal(1); + + return receipts; + } finally { + // enable auto-mining + await network.provider.send('evm_setAutomine', [true]); + } +} + +module.exports = { + countPendingTransactions, + batchInBlock, +}; diff --git a/test/metatx/ERC2771Context.test.js b/test/metatx/ERC2771Context.test.js new file mode 100644 index 000000000..b0ebccca8 --- /dev/null +++ b/test/metatx/ERC2771Context.test.js @@ -0,0 +1,134 @@ +const ethSigUtil = require('eth-sig-util'); +const Wallet = require('ethereumjs-wallet').default; +const { getDomain, domainType } = require('../helpers/eip712'); +const { MAX_UINT48 } = require('../helpers/constants'); + +const { expectEvent } = require('@openzeppelin/test-helpers'); +const { expect } = require('chai'); + +const ERC2771ContextMock = artifacts.require('ERC2771ContextMock'); +const ERC2771Forwarder = artifacts.require('ERC2771Forwarder'); +const ContextMockCaller = artifacts.require('ContextMockCaller'); + +const { shouldBehaveLikeRegularContext } = require('../utils/Context.behavior'); + +contract('ERC2771Context', function (accounts) { + const [, trustedForwarder] = accounts; + + beforeEach(async function () { + this.forwarder = await ERC2771Forwarder.new('ERC2771Forwarder'); + this.recipient = await ERC2771ContextMock.new(this.forwarder.address); + + this.domain = await getDomain(this.forwarder); + this.types = { + EIP712Domain: domainType(this.domain), + ForwardRequest: [ + { name: 'from', type: 'address' }, + { name: 'to', type: 'address' }, + { name: 'value', type: 'uint256' }, + { name: 'gas', type: 'uint256' }, + { name: 'nonce', type: 'uint256' }, + { name: 'deadline', type: 'uint48' }, + { name: 'data', type: 'bytes' }, + ], + }; + }); + + it('recognize trusted forwarder', async function () { + expect(await this.recipient.isTrustedForwarder(this.forwarder.address)).to.equal(true); + }); + + it('returns the trusted forwarder', async function () { + expect(await this.recipient.trustedForwarder()).to.equal(this.forwarder.address); + }); + + context('when called directly', function () { + beforeEach(async function () { + this.context = this.recipient; // The Context behavior expects the contract in this.context + this.caller = await ContextMockCaller.new(); + }); + + shouldBehaveLikeRegularContext(...accounts); + }); + + context('when receiving a relayed call', function () { + beforeEach(async function () { + this.wallet = Wallet.generate(); + this.sender = web3.utils.toChecksumAddress(this.wallet.getAddressString()); + this.data = { + types: this.types, + domain: this.domain, + primaryType: 'ForwardRequest', + }; + }); + + describe('msgSender', function () { + it('returns the relayed transaction original sender', async function () { + const data = this.recipient.contract.methods.msgSender().encodeABI(); + + const req = { + from: this.sender, + to: this.recipient.address, + value: '0', + gas: '100000', + nonce: (await this.forwarder.nonces(this.sender)).toString(), + deadline: MAX_UINT48, + data, + }; + + req.signature = ethSigUtil.signTypedMessage(this.wallet.getPrivateKey(), { + data: { ...this.data, message: req }, + }); + expect(await this.forwarder.verify(req)).to.equal(true); + + const { tx } = await this.forwarder.execute(req); + await expectEvent.inTransaction(tx, ERC2771ContextMock, 'Sender', { sender: this.sender }); + }); + + it('returns the original sender when calldata length is less than 20 bytes (address length)', async function () { + // The forwarder doesn't produce calls with calldata length less than 20 bytes + const recipient = await ERC2771ContextMock.new(trustedForwarder); + + const { receipt } = await recipient.msgSender({ from: trustedForwarder }); + + await expectEvent(receipt, 'Sender', { sender: trustedForwarder }); + }); + }); + + describe('msgData', function () { + it('returns the relayed transaction original data', async function () { + const integerValue = '42'; + const stringValue = 'OpenZeppelin'; + const data = this.recipient.contract.methods.msgData(integerValue, stringValue).encodeABI(); + + const req = { + from: this.sender, + to: this.recipient.address, + value: '0', + gas: '100000', + nonce: (await this.forwarder.nonces(this.sender)).toString(), + deadline: MAX_UINT48, + data, + }; + + req.signature = ethSigUtil.signTypedMessage(this.wallet.getPrivateKey(), { + data: { ...this.data, message: req }, + }); + expect(await this.forwarder.verify(req)).to.equal(true); + + const { tx } = await this.forwarder.execute(req); + await expectEvent.inTransaction(tx, ERC2771ContextMock, 'Data', { data, integerValue, stringValue }); + }); + }); + + it('returns the full original data when calldata length is less than 20 bytes (address length)', async function () { + // The forwarder doesn't produce calls with calldata length less than 20 bytes + const recipient = await ERC2771ContextMock.new(trustedForwarder); + + const { receipt } = await recipient.msgDataShort({ from: trustedForwarder }); + + const data = recipient.contract.methods.msgDataShort().encodeABI(); + await expectEvent(receipt, 'DataShort', { data }); + }); + }); +}); diff --git a/test/metatx/ERC2771Forwarder.t.sol b/test/metatx/ERC2771Forwarder.t.sol new file mode 100644 index 000000000..d69b4750a --- /dev/null +++ b/test/metatx/ERC2771Forwarder.t.sol @@ -0,0 +1,165 @@ +// SPDX-License-Identifier: MIT + +pragma solidity ^0.8.20; + +import {Test} from "forge-std/Test.sol"; +import {ERC2771Forwarder} from "@openzeppelin/contracts/metatx/ERC2771Forwarder.sol"; +import {CallReceiverMockTrustingForwarder, CallReceiverMock} from "@openzeppelin/contracts/mocks/CallReceiverMock.sol"; + +struct ForwardRequest { + address from; + address to; + uint256 value; + uint256 gas; + uint256 nonce; + uint48 deadline; + bytes data; +} + +contract ERC2771ForwarderMock is ERC2771Forwarder { + constructor(string memory name) ERC2771Forwarder(name) {} + + function structHash(ForwardRequest calldata request) external view returns (bytes32) { + return + _hashTypedDataV4( + keccak256( + abi.encode( + _FORWARD_REQUEST_TYPEHASH, + request.from, + request.to, + request.value, + request.gas, + request.nonce, + request.deadline, + keccak256(request.data) + ) + ) + ); + } +} + +contract ERC2771ForwarderTest is Test { + ERC2771ForwarderMock internal _erc2771Forwarder; + CallReceiverMockTrustingForwarder internal _receiver; + + uint256 internal _signerPrivateKey; + uint256 internal _relayerPrivateKey; + + address internal _signer; + address internal _relayer; + + uint256 internal constant _MAX_ETHER = 10_000_000; // To avoid overflow + + function setUp() public { + _erc2771Forwarder = new ERC2771ForwarderMock("ERC2771Forwarder"); + _receiver = new CallReceiverMockTrustingForwarder(address(_erc2771Forwarder)); + + _signerPrivateKey = 0xA11CE; + _relayerPrivateKey = 0xB0B; + + _signer = vm.addr(_signerPrivateKey); + _relayer = vm.addr(_relayerPrivateKey); + } + + function _forgeRequestData( + uint256 value, + uint256 nonce, + uint48 deadline, + bytes memory data + ) private view returns (ERC2771Forwarder.ForwardRequestData memory) { + ForwardRequest memory request = ForwardRequest({ + from: _signer, + to: address(_receiver), + value: value, + gas: 30000, + nonce: nonce, + deadline: deadline, + data: data + }); + + bytes32 digest = _erc2771Forwarder.structHash(request); + (uint8 v, bytes32 r, bytes32 s) = vm.sign(_signerPrivateKey, digest); + bytes memory signature = abi.encodePacked(r, s, v); + + return + ERC2771Forwarder.ForwardRequestData({ + from: request.from, + to: request.to, + value: request.value, + gas: request.gas, + deadline: request.deadline, + data: request.data, + signature: signature + }); + } + + function testExecuteAvoidsETHStuck(uint256 initialBalance, uint256 value, bool targetReverts) public { + initialBalance = bound(initialBalance, 0, _MAX_ETHER); + value = bound(value, 0, _MAX_ETHER); + + vm.deal(address(_erc2771Forwarder), initialBalance); + + uint256 nonce = _erc2771Forwarder.nonces(_signer); + + vm.deal(address(this), value); + + ERC2771Forwarder.ForwardRequestData memory requestData = _forgeRequestData({ + value: value, + nonce: nonce, + deadline: uint48(block.timestamp + 1), + data: targetReverts + ? abi.encodeCall(CallReceiverMock.mockFunctionRevertsNoReason, ()) + : abi.encodeCall(CallReceiverMock.mockFunction, ()) + }); + + if (targetReverts) { + vm.expectRevert(); + } + + _erc2771Forwarder.execute{value: value}(requestData); + assertEq(address(_erc2771Forwarder).balance, initialBalance); + } + + function testExecuteBatchAvoidsETHStuck(uint256 initialBalance, uint256 batchSize, uint256 value) public { + batchSize = bound(batchSize, 1, 10); + initialBalance = bound(initialBalance, 0, _MAX_ETHER); + value = bound(value, 0, _MAX_ETHER); + + vm.deal(address(_erc2771Forwarder), initialBalance); + uint256 nonce = _erc2771Forwarder.nonces(_signer); + + ERC2771Forwarder.ForwardRequestData[] memory batchRequestDatas = new ERC2771Forwarder.ForwardRequestData[]( + batchSize + ); + + uint256 expectedRefund; + + for (uint256 i = 0; i < batchSize; ++i) { + bytes memory data; + bool succeed = uint256(keccak256(abi.encodePacked(initialBalance, i))) % 2 == 0; + + if (succeed) { + data = abi.encodeCall(CallReceiverMock.mockFunction, ()); + } else { + expectedRefund += value; + data = abi.encodeCall(CallReceiverMock.mockFunctionRevertsNoReason, ()); + } + + batchRequestDatas[i] = _forgeRequestData({ + value: value, + nonce: nonce + i, + deadline: uint48(block.timestamp + 1), + data: data + }); + } + + address payable refundReceiver = payable(address(0xebe)); + uint256 totalValue = value * batchSize; + + vm.deal(address(this), totalValue); + _erc2771Forwarder.executeBatch{value: totalValue}(batchRequestDatas, refundReceiver); + + assertEq(address(_erc2771Forwarder).balance, initialBalance); + assertEq(refundReceiver.balance, expectedRefund); + } +} diff --git a/test/metatx/ERC2771Forwarder.test.js b/test/metatx/ERC2771Forwarder.test.js new file mode 100644 index 000000000..209c84b2f --- /dev/null +++ b/test/metatx/ERC2771Forwarder.test.js @@ -0,0 +1,542 @@ +const ethSigUtil = require('eth-sig-util'); +const Wallet = require('ethereumjs-wallet').default; +const { getDomain, domainType } = require('../helpers/eip712'); +const { expectRevertCustomError } = require('../helpers/customError'); + +const { constants, expectRevert, expectEvent, time } = require('@openzeppelin/test-helpers'); +const { expect } = require('chai'); + +const ERC2771Forwarder = artifacts.require('ERC2771Forwarder'); +const CallReceiverMockTrustingForwarder = artifacts.require('CallReceiverMockTrustingForwarder'); + +contract('ERC2771Forwarder', function (accounts) { + const [, refundReceiver, another] = accounts; + + const tamperedValues = { + from: another, + value: web3.utils.toWei('0.5'), + data: '0x1742', + deadline: 0xdeadbeef, + }; + + beforeEach(async function () { + this.forwarder = await ERC2771Forwarder.new('ERC2771Forwarder'); + + this.domain = await getDomain(this.forwarder); + this.types = { + EIP712Domain: domainType(this.domain), + ForwardRequest: [ + { name: 'from', type: 'address' }, + { name: 'to', type: 'address' }, + { name: 'value', type: 'uint256' }, + { name: 'gas', type: 'uint256' }, + { name: 'nonce', type: 'uint256' }, + { name: 'deadline', type: 'uint48' }, + { name: 'data', type: 'bytes' }, + ], + }; + + this.alice = Wallet.generate(); + this.alice.address = web3.utils.toChecksumAddress(this.alice.getAddressString()); + + this.timestamp = await time.latest(); + this.receiver = await CallReceiverMockTrustingForwarder.new(this.forwarder.address); + this.request = { + from: this.alice.address, + to: this.receiver.address, + value: '0', + gas: '100000', + data: this.receiver.contract.methods.mockFunction().encodeABI(), + deadline: this.timestamp.toNumber() + 60, // 1 minute + }; + this.requestData = { + ...this.request, + nonce: (await this.forwarder.nonces(this.alice.address)).toString(), + }; + + this.forgeData = request => ({ + types: this.types, + domain: this.domain, + primaryType: 'ForwardRequest', + message: { ...this.requestData, ...request }, + }); + this.sign = (privateKey, request) => + ethSigUtil.signTypedMessage(privateKey, { + data: this.forgeData(request), + }); + this.estimateRequest = request => + web3.eth.estimateGas({ + from: this.forwarder.address, + to: request.to, + data: web3.utils.encodePacked({ value: request.data, type: 'bytes' }, { value: request.from, type: 'address' }), + value: request.value, + gas: request.gas, + }); + + this.requestData.signature = this.sign(this.alice.getPrivateKey()); + }); + + context('verify', function () { + context('with valid signature', function () { + it('returns true without altering the nonce', async function () { + expect(await this.forwarder.nonces(this.requestData.from)).to.be.bignumber.equal( + web3.utils.toBN(this.requestData.nonce), + ); + expect(await this.forwarder.verify(this.requestData)).to.be.equal(true); + expect(await this.forwarder.nonces(this.requestData.from)).to.be.bignumber.equal( + web3.utils.toBN(this.requestData.nonce), + ); + }); + }); + + context('with tampered values', function () { + for (const [key, value] of Object.entries(tamperedValues)) { + it(`returns false with tampered ${key}`, async function () { + expect(await this.forwarder.verify(this.forgeData({ [key]: value }).message)).to.be.equal(false); + }); + } + + it('returns false with an untrustful to', async function () { + expect(await this.forwarder.verify(this.forgeData({ to: another }).message)).to.be.equal(false); + }); + + it('returns false with tampered signature', async function () { + const tamperedsign = web3.utils.hexToBytes(this.requestData.signature); + tamperedsign[42] ^= 0xff; + this.requestData.signature = web3.utils.bytesToHex(tamperedsign); + expect(await this.forwarder.verify(this.requestData)).to.be.equal(false); + }); + + it('returns false with valid signature for non-current nonce', async function () { + const req = { + ...this.requestData, + nonce: this.requestData.nonce + 1, + }; + req.signature = this.sign(this.alice.getPrivateKey(), req); + expect(await this.forwarder.verify(req)).to.be.equal(false); + }); + + it('returns false with valid signature for expired deadline', async function () { + const req = { + ...this.requestData, + deadline: this.timestamp - 1, + }; + req.signature = this.sign(this.alice.getPrivateKey(), req); + expect(await this.forwarder.verify(req)).to.be.equal(false); + }); + }); + }); + + context('execute', function () { + context('with valid requests', function () { + beforeEach(async function () { + expect(await this.forwarder.nonces(this.requestData.from)).to.be.bignumber.equal( + web3.utils.toBN(this.requestData.nonce), + ); + }); + + it('emits an event and consumes nonce for a successful request', async function () { + const receipt = await this.forwarder.execute(this.requestData); + await expectEvent.inTransaction(receipt.tx, this.receiver, 'MockFunctionCalled'); + await expectEvent.inTransaction(receipt.tx, this.forwarder, 'ExecutedForwardRequest', { + signer: this.requestData.from, + nonce: web3.utils.toBN(this.requestData.nonce), + success: true, + }); + expect(await this.forwarder.nonces(this.requestData.from)).to.be.bignumber.equal( + web3.utils.toBN(this.requestData.nonce + 1), + ); + }); + + it('reverts with an unsuccessful request', async function () { + const req = { + ...this.requestData, + data: this.receiver.contract.methods.mockFunctionRevertsNoReason().encodeABI(), + }; + req.signature = this.sign(this.alice.getPrivateKey(), req); + await expectRevertCustomError(this.forwarder.execute(req), 'FailedInnerCall', []); + }); + }); + + context('with tampered request', function () { + for (const [key, value] of Object.entries(tamperedValues)) { + it(`reverts with tampered ${key}`, async function () { + const data = this.forgeData({ [key]: value }); + await expectRevertCustomError( + this.forwarder.execute(data.message, { + value: key == 'value' ? value : 0, // To avoid MismatchedValue error + }), + 'ERC2771ForwarderInvalidSigner', + [ethSigUtil.recoverTypedSignature({ data, sig: this.requestData.signature }), data.message.from], + ); + }); + } + + it('reverts with an untrustful to', async function () { + const data = this.forgeData({ to: another }); + await expectRevertCustomError(this.forwarder.execute(data.message), 'ERC2771UntrustfulTarget', [ + data.message.to, + this.forwarder.address, + ]); + }); + + it('reverts with tampered signature', async function () { + const tamperedSig = web3.utils.hexToBytes(this.requestData.signature); + tamperedSig[42] ^= 0xff; + this.requestData.signature = web3.utils.bytesToHex(tamperedSig); + await expectRevertCustomError(this.forwarder.execute(this.requestData), 'ERC2771ForwarderInvalidSigner', [ + ethSigUtil.recoverTypedSignature({ data: this.forgeData(), sig: tamperedSig }), + this.requestData.from, + ]); + }); + + it('reverts with valid signature for non-current nonce', async function () { + // Execute first a request + await this.forwarder.execute(this.requestData); + + // And then fail due to an already used nonce + await expectRevertCustomError(this.forwarder.execute(this.requestData), 'ERC2771ForwarderInvalidSigner', [ + ethSigUtil.recoverTypedSignature({ + data: this.forgeData({ ...this.requestData, nonce: this.requestData.nonce + 1 }), + sig: this.requestData.signature, + }), + this.requestData.from, + ]); + }); + + it('reverts with valid signature for expired deadline', async function () { + const req = { + ...this.requestData, + deadline: this.timestamp - 1, + }; + req.signature = this.sign(this.alice.getPrivateKey(), req); + await expectRevertCustomError(this.forwarder.execute(req), 'ERC2771ForwarderExpiredRequest', [ + this.timestamp - 1, + ]); + }); + + it('reverts with valid signature but mismatched value', async function () { + const value = 100; + const req = { + ...this.requestData, + value, + }; + req.signature = this.sign(this.alice.getPrivateKey(), req); + await expectRevertCustomError(this.forwarder.execute(req), 'ERC2771ForwarderMismatchedValue', [0, value]); + }); + }); + + it('bubbles out of gas', async function () { + this.requestData.data = this.receiver.contract.methods.mockFunctionOutOfGas().encodeABI(); + this.requestData.gas = 1_000_000; + this.requestData.signature = this.sign(this.alice.getPrivateKey()); + + const gasAvailable = 100_000; + await expectRevert.assertion(this.forwarder.execute(this.requestData, { gas: gasAvailable })); + + const { transactions } = await web3.eth.getBlock('latest'); + const { gasUsed } = await web3.eth.getTransactionReceipt(transactions[0]); + + expect(gasUsed).to.be.equal(gasAvailable); + }); + + it('bubbles out of gas forced by the relayer', async function () { + // If there's an incentive behind executing requests, a malicious relayer could grief + // the forwarder by executing requests and providing a top-level call gas limit that + // is too low to successfully finish the request after the 63/64 rule. + + // We set the baseline to the gas limit consumed by a successful request if it was executed + // normally. Note this includes the 21000 buffer that also the relayer will be charged to + // start a request execution. + const estimate = await this.estimateRequest(this.request); + + // Because the relayer call consumes gas until the `CALL` opcode, the gas left after failing + // the subcall won't enough to finish the top level call (after testing), so we add a + // moderated buffer. + const gasAvailable = estimate + 2_000; + + // The subcall out of gas should be caught by the contract and then bubbled up consuming + // the available gas with an `invalid` opcode. + await expectRevert.outOfGas(this.forwarder.execute(this.requestData, { gas: gasAvailable })); + + const { transactions } = await web3.eth.getBlock('latest'); + const { gasUsed } = await web3.eth.getTransactionReceipt(transactions[0]); + + // We assert that indeed the gas was totally consumed. + expect(gasUsed).to.be.equal(gasAvailable); + }); + }); + + context('executeBatch', function () { + const batchValue = requestDatas => requestDatas.reduce((value, request) => value + Number(request.value), 0); + + beforeEach(async function () { + this.bob = Wallet.generate(); + this.bob.address = web3.utils.toChecksumAddress(this.bob.getAddressString()); + + this.eve = Wallet.generate(); + this.eve.address = web3.utils.toChecksumAddress(this.eve.getAddressString()); + + this.signers = [this.alice, this.bob, this.eve]; + + this.requestDatas = await Promise.all( + this.signers.map(async ({ address }) => ({ + ...this.requestData, + from: address, + nonce: (await this.forwarder.nonces(address)).toString(), + value: web3.utils.toWei('10', 'gwei'), + })), + ); + + this.requestDatas = this.requestDatas.map((requestData, i) => ({ + ...requestData, + signature: this.sign(this.signers[i].getPrivateKey(), requestData), + })); + + this.msgValue = batchValue(this.requestDatas); + + this.gasUntil = async reqIdx => { + const gas = 0; + const estimations = await Promise.all( + new Array(reqIdx + 1).fill().map((_, idx) => this.estimateRequest(this.requestDatas[idx])), + ); + return estimations.reduce((acc, estimation) => acc + estimation, gas); + }; + }); + + context('with valid requests', function () { + beforeEach(async function () { + for (const request of this.requestDatas) { + expect(await this.forwarder.verify(request)).to.be.equal(true); + } + + this.receipt = await this.forwarder.executeBatch(this.requestDatas, another, { value: this.msgValue }); + }); + + it('emits events', async function () { + for (const request of this.requestDatas) { + await expectEvent.inTransaction(this.receipt.tx, this.receiver, 'MockFunctionCalled'); + await expectEvent.inTransaction(this.receipt.tx, this.forwarder, 'ExecutedForwardRequest', { + signer: request.from, + nonce: web3.utils.toBN(request.nonce), + success: true, + }); + } + }); + + it('increase nonces', async function () { + for (const request of this.requestDatas) { + expect(await this.forwarder.nonces(request.from)).to.be.bignumber.eq(web3.utils.toBN(request.nonce + 1)); + } + }); + }); + + context('with tampered requests', function () { + beforeEach(async function () { + this.idx = 1; // Tampered idx + }); + + it('reverts with mismatched value', async function () { + this.requestDatas[this.idx].value = 100; + this.requestDatas[this.idx].signature = this.sign( + this.signers[this.idx].getPrivateKey(), + this.requestDatas[this.idx], + ); + await expectRevertCustomError( + this.forwarder.executeBatch(this.requestDatas, another, { value: this.msgValue }), + 'ERC2771ForwarderMismatchedValue', + [batchValue(this.requestDatas), this.msgValue], + ); + }); + + context('when the refund receiver is the zero address', function () { + beforeEach(function () { + this.refundReceiver = constants.ZERO_ADDRESS; + }); + + for (const [key, value] of Object.entries(tamperedValues)) { + it(`reverts with at least one tampered request ${key}`, async function () { + const data = this.forgeData({ ...this.requestDatas[this.idx], [key]: value }); + + this.requestDatas[this.idx] = data.message; + + await expectRevertCustomError( + this.forwarder.executeBatch(this.requestDatas, this.refundReceiver, { value: this.msgValue }), + 'ERC2771ForwarderInvalidSigner', + [ + ethSigUtil.recoverTypedSignature({ data, sig: this.requestDatas[this.idx].signature }), + data.message.from, + ], + ); + }); + } + + it('reverts with at least one untrustful to', async function () { + const data = this.forgeData({ ...this.requestDatas[this.idx], to: another }); + + this.requestDatas[this.idx] = data.message; + + await expectRevertCustomError( + this.forwarder.executeBatch(this.requestDatas, this.refundReceiver, { value: this.msgValue }), + 'ERC2771UntrustfulTarget', + [this.requestDatas[this.idx].to, this.forwarder.address], + ); + }); + + it('reverts with at least one tampered request signature', async function () { + const tamperedSig = web3.utils.hexToBytes(this.requestDatas[this.idx].signature); + tamperedSig[42] ^= 0xff; + + this.requestDatas[this.idx].signature = web3.utils.bytesToHex(tamperedSig); + + await expectRevertCustomError( + this.forwarder.executeBatch(this.requestDatas, this.refundReceiver, { value: this.msgValue }), + 'ERC2771ForwarderInvalidSigner', + [ + ethSigUtil.recoverTypedSignature({ + data: this.forgeData(this.requestDatas[this.idx]), + sig: this.requestDatas[this.idx].signature, + }), + this.requestDatas[this.idx].from, + ], + ); + }); + + it('reverts with at least one valid signature for non-current nonce', async function () { + // Execute first a request + await this.forwarder.execute(this.requestDatas[this.idx], { value: this.requestDatas[this.idx].value }); + + // And then fail due to an already used nonce + await expectRevertCustomError( + this.forwarder.executeBatch(this.requestDatas, this.refundReceiver, { value: this.msgValue }), + 'ERC2771ForwarderInvalidSigner', + [ + ethSigUtil.recoverTypedSignature({ + data: this.forgeData({ ...this.requestDatas[this.idx], nonce: this.requestDatas[this.idx].nonce + 1 }), + sig: this.requestDatas[this.idx].signature, + }), + this.requestDatas[this.idx].from, + ], + ); + }); + + it('reverts with at least one valid signature for expired deadline', async function () { + this.requestDatas[this.idx].deadline = this.timestamp.toNumber() - 1; + this.requestDatas[this.idx].signature = this.sign( + this.signers[this.idx].getPrivateKey(), + this.requestDatas[this.idx], + ); + await expectRevertCustomError( + this.forwarder.executeBatch(this.requestDatas, this.refundReceiver, { value: this.msgValue }), + 'ERC2771ForwarderExpiredRequest', + [this.timestamp.toNumber() - 1], + ); + }); + }); + + context('when the refund receiver is a known address', function () { + beforeEach(async function () { + this.refundReceiver = refundReceiver; + this.initialRefundReceiverBalance = web3.utils.toBN(await web3.eth.getBalance(this.refundReceiver)); + this.initialTamperedRequestNonce = await this.forwarder.nonces(this.requestDatas[this.idx].from); + }); + + for (const [key, value] of Object.entries(tamperedValues)) { + it(`ignores a request with tampered ${key} and refunds its value`, async function () { + const data = this.forgeData({ ...this.requestDatas[this.idx], [key]: value }); + + this.requestDatas[this.idx] = data.message; + + const receipt = await this.forwarder.executeBatch(this.requestDatas, this.refundReceiver, { + value: batchValue(this.requestDatas), + }); + expect(receipt.logs.filter(({ event }) => event === 'ExecutedForwardRequest').length).to.be.equal(2); + }); + } + + it('ignores a request with a valid signature for non-current nonce', async function () { + // Execute first a request + await this.forwarder.execute(this.requestDatas[this.idx], { value: this.requestDatas[this.idx].value }); + this.initialTamperedRequestNonce++; // Should be already incremented by the individual `execute` + + // And then ignore the same request in a batch due to an already used nonce + const receipt = await this.forwarder.executeBatch(this.requestDatas, this.refundReceiver, { + value: this.msgValue, + }); + expect(receipt.logs.filter(({ event }) => event === 'ExecutedForwardRequest').length).to.be.equal(2); + }); + + it('ignores a request with a valid signature for expired deadline', async function () { + this.requestDatas[this.idx].deadline = this.timestamp.toNumber() - 1; + this.requestDatas[this.idx].signature = this.sign( + this.signers[this.idx].getPrivateKey(), + this.requestDatas[this.idx], + ); + + const receipt = await this.forwarder.executeBatch(this.requestDatas, this.refundReceiver, { + value: this.msgValue, + }); + expect(receipt.logs.filter(({ event }) => event === 'ExecutedForwardRequest').length).to.be.equal(2); + }); + + afterEach(async function () { + // The invalid request value was refunded + expect(await web3.eth.getBalance(this.refundReceiver)).to.be.bignumber.equal( + this.initialRefundReceiverBalance.add(web3.utils.toBN(this.requestDatas[this.idx].value)), + ); + + // The invalid request from's nonce was not incremented + expect(await this.forwarder.nonces(this.requestDatas[this.idx].from)).to.be.bignumber.eq( + web3.utils.toBN(this.initialTamperedRequestNonce), + ); + }); + }); + + it('bubbles out of gas', async function () { + this.requestDatas[this.idx].data = this.receiver.contract.methods.mockFunctionOutOfGas().encodeABI(); + this.requestDatas[this.idx].gas = 1_000_000; + this.requestDatas[this.idx].signature = this.sign( + this.signers[this.idx].getPrivateKey(), + this.requestDatas[this.idx], + ); + + const gasAvailable = 300_000; + await expectRevert.assertion( + this.forwarder.executeBatch(this.requestDatas, constants.ZERO_ADDRESS, { + gas: gasAvailable, + value: this.requestDatas.reduce((acc, { value }) => acc + Number(value), 0), + }), + ); + + const { transactions } = await web3.eth.getBlock('latest'); + const { gasUsed } = await web3.eth.getTransactionReceipt(transactions[0]); + + expect(gasUsed).to.be.equal(gasAvailable); + }); + + it('bubbles out of gas forced by the relayer', async function () { + // Similarly to the single execute, a malicious relayer could grief requests. + + // We estimate until the selected request as if they were executed normally + const estimate = await this.gasUntil(this.requestDatas, this.idx); + + // We add a Buffer to account for all the gas that's used before the selected call. + // Note is slightly bigger because the selected request is not the index 0 and it affects + // the buffer needed. + const gasAvailable = estimate + 10_000; + + // The subcall out of gas should be caught by the contract and then bubbled up consuming + // the available gas with an `invalid` opcode. + await expectRevert.outOfGas( + this.forwarder.executeBatch(this.requestDatas, constants.ZERO_ADDRESS, { gas: gasAvailable }), + ); + + const { transactions } = await web3.eth.getBlock('latest'); + const { gasUsed } = await web3.eth.getTransactionReceipt(transactions[0]); + + // We assert that indeed the gas was totally consumed. + expect(gasUsed).to.be.equal(gasAvailable); + }); + }); + }); +}); diff --git a/test/proxy/Clones.behaviour.js b/test/proxy/Clones.behaviour.js new file mode 100644 index 000000000..b5fd3c51b --- /dev/null +++ b/test/proxy/Clones.behaviour.js @@ -0,0 +1,136 @@ +const { expectRevert } = require('@openzeppelin/test-helpers'); + +const { expect } = require('chai'); + +const DummyImplementation = artifacts.require('DummyImplementation'); + +module.exports = function shouldBehaveLikeClone(createClone) { + before('deploy implementation', async function () { + this.implementation = web3.utils.toChecksumAddress((await DummyImplementation.new()).address); + }); + + const assertProxyInitialization = function ({ value, balance }) { + it('initializes the proxy', async function () { + const dummy = new DummyImplementation(this.proxy); + expect(await dummy.value()).to.be.bignumber.equal(value.toString()); + }); + + it('has expected balance', async function () { + expect(await web3.eth.getBalance(this.proxy)).to.be.bignumber.equal(balance.toString()); + }); + }; + + describe('initialization without parameters', function () { + describe('non payable', function () { + const expectedInitializedValue = 10; + const initializeData = new DummyImplementation('').contract.methods['initializeNonPayable()']().encodeABI(); + + describe('when not sending balance', function () { + beforeEach('creating proxy', async function () { + this.proxy = (await createClone(this.implementation, initializeData)).address; + }); + + assertProxyInitialization({ + value: expectedInitializedValue, + balance: 0, + }); + }); + + describe('when sending some balance', function () { + const value = 10e5; + + it('reverts', async function () { + await expectRevert.unspecified(createClone(this.implementation, initializeData, { value })); + }); + }); + }); + + describe('payable', function () { + const expectedInitializedValue = 100; + const initializeData = new DummyImplementation('').contract.methods['initializePayable()']().encodeABI(); + + describe('when not sending balance', function () { + beforeEach('creating proxy', async function () { + this.proxy = (await createClone(this.implementation, initializeData)).address; + }); + + assertProxyInitialization({ + value: expectedInitializedValue, + balance: 0, + }); + }); + + describe('when sending some balance', function () { + const value = 10e5; + + beforeEach('creating proxy', async function () { + this.proxy = (await createClone(this.implementation, initializeData, { value })).address; + }); + + assertProxyInitialization({ + value: expectedInitializedValue, + balance: value, + }); + }); + }); + }); + + describe('initialization with parameters', function () { + describe('non payable', function () { + const expectedInitializedValue = 10; + const initializeData = new DummyImplementation('').contract.methods + .initializeNonPayableWithValue(expectedInitializedValue) + .encodeABI(); + + describe('when not sending balance', function () { + beforeEach('creating proxy', async function () { + this.proxy = (await createClone(this.implementation, initializeData)).address; + }); + + assertProxyInitialization({ + value: expectedInitializedValue, + balance: 0, + }); + }); + + describe('when sending some balance', function () { + const value = 10e5; + + it('reverts', async function () { + await expectRevert.unspecified(createClone(this.implementation, initializeData, { value })); + }); + }); + }); + + describe('payable', function () { + const expectedInitializedValue = 42; + const initializeData = new DummyImplementation('').contract.methods + .initializePayableWithValue(expectedInitializedValue) + .encodeABI(); + + describe('when not sending balance', function () { + beforeEach('creating proxy', async function () { + this.proxy = (await createClone(this.implementation, initializeData)).address; + }); + + assertProxyInitialization({ + value: expectedInitializedValue, + balance: 0, + }); + }); + + describe('when sending some balance', function () { + const value = 10e5; + + beforeEach('creating proxy', async function () { + this.proxy = (await createClone(this.implementation, initializeData, { value })).address; + }); + + assertProxyInitialization({ + value: expectedInitializedValue, + balance: value, + }); + }); + }); + }); +}; diff --git a/test/proxy/Clones.test.js b/test/proxy/Clones.test.js new file mode 100644 index 000000000..0862778f7 --- /dev/null +++ b/test/proxy/Clones.test.js @@ -0,0 +1,62 @@ +const { expectEvent } = require('@openzeppelin/test-helpers'); +const { expect } = require('chai'); +const { computeCreate2Address } = require('../helpers/create'); +const { expectRevertCustomError } = require('../helpers/customError'); + +const shouldBehaveLikeClone = require('./Clones.behaviour'); + +const Clones = artifacts.require('$Clones'); + +contract('Clones', function (accounts) { + const [deployer] = accounts; + + describe('clone', function () { + shouldBehaveLikeClone(async (implementation, initData, opts = {}) => { + const factory = await Clones.new(); + const receipt = await factory.$clone(implementation); + const address = receipt.logs.find(({ event }) => event === 'return$clone').args.instance; + await web3.eth.sendTransaction({ from: deployer, to: address, value: opts.value, data: initData }); + return { address }; + }); + }); + + describe('cloneDeterministic', function () { + shouldBehaveLikeClone(async (implementation, initData, opts = {}) => { + const salt = web3.utils.randomHex(32); + const factory = await Clones.new(); + const receipt = await factory.$cloneDeterministic(implementation, salt); + const address = receipt.logs.find(({ event }) => event === 'return$cloneDeterministic').args.instance; + await web3.eth.sendTransaction({ from: deployer, to: address, value: opts.value, data: initData }); + return { address }; + }); + + it('address already used', async function () { + const implementation = web3.utils.randomHex(20); + const salt = web3.utils.randomHex(32); + const factory = await Clones.new(); + // deploy once + expectEvent(await factory.$cloneDeterministic(implementation, salt), 'return$cloneDeterministic'); + // deploy twice + await expectRevertCustomError(factory.$cloneDeterministic(implementation, salt), 'ERC1167FailedCreateClone', []); + }); + + it('address prediction', async function () { + const implementation = web3.utils.randomHex(20); + const salt = web3.utils.randomHex(32); + const factory = await Clones.new(); + const predicted = await factory.$predictDeterministicAddress(implementation, salt); + + const creationCode = [ + '0x3d602d80600a3d3981f3363d3d373d3d3d363d73', + implementation.replace(/0x/, '').toLowerCase(), + '5af43d82803e903d91602b57fd5bf3', + ].join(''); + + expect(computeCreate2Address(salt, creationCode, factory.address)).to.be.equal(predicted); + + expectEvent(await factory.$cloneDeterministic(implementation, salt), 'return$cloneDeterministic', { + instance: predicted, + }); + }); + }); +}); diff --git a/test/proxy/ERC1967/ERC1967Proxy.test.js b/test/proxy/ERC1967/ERC1967Proxy.test.js new file mode 100644 index 000000000..81cc43507 --- /dev/null +++ b/test/proxy/ERC1967/ERC1967Proxy.test.js @@ -0,0 +1,12 @@ +const shouldBehaveLikeProxy = require('../Proxy.behaviour'); + +const ERC1967Proxy = artifacts.require('ERC1967Proxy'); + +contract('ERC1967Proxy', function (accounts) { + // `undefined`, `null` and other false-ish opts will not be forwarded. + const createProxy = async function (implementation, initData, opts) { + return ERC1967Proxy.new(implementation, initData, ...[opts].filter(Boolean)); + }; + + shouldBehaveLikeProxy(createProxy, accounts); +}); diff --git a/test/proxy/ERC1967/ERC1967Utils.test.js b/test/proxy/ERC1967/ERC1967Utils.test.js new file mode 100644 index 000000000..975b08d81 --- /dev/null +++ b/test/proxy/ERC1967/ERC1967Utils.test.js @@ -0,0 +1,172 @@ +const { expectEvent, constants } = require('@openzeppelin/test-helpers'); +const { expectRevertCustomError } = require('../../helpers/customError'); +const { getAddressInSlot, setSlot, ImplementationSlot, AdminSlot, BeaconSlot } = require('../../helpers/erc1967'); + +const { ZERO_ADDRESS } = constants; + +const ERC1967Utils = artifacts.require('$ERC1967Utils'); + +const V1 = artifacts.require('DummyImplementation'); +const V2 = artifacts.require('CallReceiverMock'); +const UpgradeableBeaconMock = artifacts.require('UpgradeableBeaconMock'); +const UpgradeableBeaconReentrantMock = artifacts.require('UpgradeableBeaconReentrantMock'); + +contract('ERC1967Utils', function (accounts) { + const [, admin, anotherAccount] = accounts; + const EMPTY_DATA = '0x'; + + beforeEach('setup', async function () { + this.utils = await ERC1967Utils.new(); + this.v1 = await V1.new(); + this.v2 = await V2.new(); + }); + + describe('IMPLEMENTATION_SLOT', function () { + beforeEach('set v1 implementation', async function () { + await setSlot(this.utils, ImplementationSlot, this.v1.address); + }); + + describe('getImplementation', function () { + it('returns current implementation and matches implementation slot value', async function () { + expect(await this.utils.$getImplementation()).to.equal(this.v1.address); + expect(await getAddressInSlot(this.utils.address, ImplementationSlot)).to.equal(this.v1.address); + }); + }); + + describe('upgradeToAndCall', function () { + it('sets implementation in storage and emits event', async function () { + const newImplementation = this.v2.address; + const receipt = await this.utils.$upgradeToAndCall(newImplementation, EMPTY_DATA); + + expect(await getAddressInSlot(this.utils.address, ImplementationSlot)).to.equal(newImplementation); + expectEvent(receipt, 'Upgraded', { implementation: newImplementation }); + }); + + it('reverts when implementation does not contain code', async function () { + await expectRevertCustomError( + this.utils.$upgradeToAndCall(anotherAccount, EMPTY_DATA), + 'ERC1967InvalidImplementation', + [anotherAccount], + ); + }); + + describe('when data is empty', function () { + it('reverts when value is sent', async function () { + await expectRevertCustomError( + this.utils.$upgradeToAndCall(this.v2.address, EMPTY_DATA, { value: 1 }), + 'ERC1967NonPayable', + [], + ); + }); + }); + + describe('when data is not empty', function () { + it('delegates a call to the new implementation', async function () { + const initializeData = this.v2.contract.methods.mockFunction().encodeABI(); + const receipt = await this.utils.$upgradeToAndCall(this.v2.address, initializeData); + await expectEvent.inTransaction(receipt.tx, await V2.at(this.utils.address), 'MockFunctionCalled'); + }); + }); + }); + }); + + describe('ADMIN_SLOT', function () { + beforeEach('set admin', async function () { + await setSlot(this.utils, AdminSlot, admin); + }); + + describe('getAdmin', function () { + it('returns current admin and matches admin slot value', async function () { + expect(await this.utils.$getAdmin()).to.equal(admin); + expect(await getAddressInSlot(this.utils.address, AdminSlot)).to.equal(admin); + }); + }); + + describe('changeAdmin', function () { + it('sets admin in storage and emits event', async function () { + const newAdmin = anotherAccount; + const receipt = await this.utils.$changeAdmin(newAdmin); + + expect(await getAddressInSlot(this.utils.address, AdminSlot)).to.equal(newAdmin); + expectEvent(receipt, 'AdminChanged', { previousAdmin: admin, newAdmin: newAdmin }); + }); + + it('reverts when setting the address zero as admin', async function () { + await expectRevertCustomError(this.utils.$changeAdmin(ZERO_ADDRESS), 'ERC1967InvalidAdmin', [ZERO_ADDRESS]); + }); + }); + }); + + describe('BEACON_SLOT', function () { + beforeEach('set beacon', async function () { + this.beacon = await UpgradeableBeaconMock.new(this.v1.address); + await setSlot(this.utils, BeaconSlot, this.beacon.address); + }); + + describe('getBeacon', function () { + it('returns current beacon and matches beacon slot value', async function () { + expect(await this.utils.$getBeacon()).to.equal(this.beacon.address); + expect(await getAddressInSlot(this.utils.address, BeaconSlot)).to.equal(this.beacon.address); + }); + }); + + describe('upgradeBeaconToAndCall', function () { + it('sets beacon in storage and emits event', async function () { + const newBeacon = await UpgradeableBeaconMock.new(this.v2.address); + const receipt = await this.utils.$upgradeBeaconToAndCall(newBeacon.address, EMPTY_DATA); + + expect(await getAddressInSlot(this.utils.address, BeaconSlot)).to.equal(newBeacon.address); + expectEvent(receipt, 'BeaconUpgraded', { beacon: newBeacon.address }); + }); + + it('reverts when beacon does not contain code', async function () { + await expectRevertCustomError( + this.utils.$upgradeBeaconToAndCall(anotherAccount, EMPTY_DATA), + 'ERC1967InvalidBeacon', + [anotherAccount], + ); + }); + + it("reverts when beacon's implementation does not contain code", async function () { + const newBeacon = await UpgradeableBeaconMock.new(anotherAccount); + + await expectRevertCustomError( + this.utils.$upgradeBeaconToAndCall(newBeacon.address, EMPTY_DATA), + 'ERC1967InvalidImplementation', + [anotherAccount], + ); + }); + + describe('when data is empty', function () { + it('reverts when value is sent', async function () { + const newBeacon = await UpgradeableBeaconMock.new(this.v2.address); + await expectRevertCustomError( + this.utils.$upgradeBeaconToAndCall(newBeacon.address, EMPTY_DATA, { value: 1 }), + 'ERC1967NonPayable', + [], + ); + }); + }); + + describe('when data is not empty', function () { + it('delegates a call to the new implementation', async function () { + const initializeData = this.v2.contract.methods.mockFunction().encodeABI(); + const newBeacon = await UpgradeableBeaconMock.new(this.v2.address); + const receipt = await this.utils.$upgradeBeaconToAndCall(newBeacon.address, initializeData); + await expectEvent.inTransaction(receipt.tx, await V2.at(this.utils.address), 'MockFunctionCalled'); + }); + }); + + describe('reentrant beacon implementation() call', function () { + it('sees the new beacon implementation', async function () { + const newBeacon = await UpgradeableBeaconReentrantMock.new(); + await expectRevertCustomError( + this.utils.$upgradeBeaconToAndCall(newBeacon.address, '0x'), + 'BeaconProxyBeaconSlotAddress', + [newBeacon.address], + ); + }); + }); + }); + }); +}); diff --git a/test/proxy/Proxy.behaviour.js b/test/proxy/Proxy.behaviour.js new file mode 100644 index 000000000..acce6d188 --- /dev/null +++ b/test/proxy/Proxy.behaviour.js @@ -0,0 +1,182 @@ +const { expectRevert } = require('@openzeppelin/test-helpers'); +const { getSlot, ImplementationSlot } = require('../helpers/erc1967'); + +const { expect } = require('chai'); +const { expectRevertCustomError } = require('../helpers/customError'); + +const DummyImplementation = artifacts.require('DummyImplementation'); + +module.exports = function shouldBehaveLikeProxy(createProxy, accounts) { + it('cannot be initialized with a non-contract address', async function () { + const nonContractAddress = accounts[0]; + const initializeData = Buffer.from(''); + await expectRevert.unspecified(createProxy(nonContractAddress, initializeData)); + }); + + before('deploy implementation', async function () { + this.implementation = web3.utils.toChecksumAddress((await DummyImplementation.new()).address); + }); + + const assertProxyInitialization = function ({ value, balance }) { + it('sets the implementation address', async function () { + const implementationSlot = await getSlot(this.proxy, ImplementationSlot); + const implementationAddress = web3.utils.toChecksumAddress(implementationSlot.substr(-40)); + expect(implementationAddress).to.be.equal(this.implementation); + }); + + it('initializes the proxy', async function () { + const dummy = new DummyImplementation(this.proxy); + expect(await dummy.value()).to.be.bignumber.equal(value.toString()); + }); + + it('has expected balance', async function () { + expect(await web3.eth.getBalance(this.proxy)).to.be.bignumber.equal(balance.toString()); + }); + }; + + describe('without initialization', function () { + const initializeData = Buffer.from(''); + + describe('when not sending balance', function () { + beforeEach('creating proxy', async function () { + this.proxy = (await createProxy(this.implementation, initializeData)).address; + }); + + assertProxyInitialization({ value: 0, balance: 0 }); + }); + + describe('when sending some balance', function () { + const value = 10e5; + + it('reverts', async function () { + await expectRevertCustomError( + createProxy(this.implementation, initializeData, { value }), + 'ERC1967NonPayable', + [], + ); + }); + }); + }); + + describe('initialization without parameters', function () { + describe('non payable', function () { + const expectedInitializedValue = 10; + const initializeData = new DummyImplementation('').contract.methods['initializeNonPayable()']().encodeABI(); + + describe('when not sending balance', function () { + beforeEach('creating proxy', async function () { + this.proxy = (await createProxy(this.implementation, initializeData)).address; + }); + + assertProxyInitialization({ + value: expectedInitializedValue, + balance: 0, + }); + }); + + describe('when sending some balance', function () { + const value = 10e5; + + it('reverts', async function () { + await expectRevert.unspecified(createProxy(this.implementation, initializeData, { value })); + }); + }); + }); + + describe('payable', function () { + const expectedInitializedValue = 100; + const initializeData = new DummyImplementation('').contract.methods['initializePayable()']().encodeABI(); + + describe('when not sending balance', function () { + beforeEach('creating proxy', async function () { + this.proxy = (await createProxy(this.implementation, initializeData)).address; + }); + + assertProxyInitialization({ + value: expectedInitializedValue, + balance: 0, + }); + }); + + describe('when sending some balance', function () { + const value = 10e5; + + beforeEach('creating proxy', async function () { + this.proxy = (await createProxy(this.implementation, initializeData, { value })).address; + }); + + assertProxyInitialization({ + value: expectedInitializedValue, + balance: value, + }); + }); + }); + }); + + describe('initialization with parameters', function () { + describe('non payable', function () { + const expectedInitializedValue = 10; + const initializeData = new DummyImplementation('').contract.methods + .initializeNonPayableWithValue(expectedInitializedValue) + .encodeABI(); + + describe('when not sending balance', function () { + beforeEach('creating proxy', async function () { + this.proxy = (await createProxy(this.implementation, initializeData)).address; + }); + + assertProxyInitialization({ + value: expectedInitializedValue, + balance: 0, + }); + }); + + describe('when sending some balance', function () { + const value = 10e5; + + it('reverts', async function () { + await expectRevert.unspecified(createProxy(this.implementation, initializeData, { value })); + }); + }); + }); + + describe('payable', function () { + const expectedInitializedValue = 42; + const initializeData = new DummyImplementation('').contract.methods + .initializePayableWithValue(expectedInitializedValue) + .encodeABI(); + + describe('when not sending balance', function () { + beforeEach('creating proxy', async function () { + this.proxy = (await createProxy(this.implementation, initializeData)).address; + }); + + assertProxyInitialization({ + value: expectedInitializedValue, + balance: 0, + }); + }); + + describe('when sending some balance', function () { + const value = 10e5; + + beforeEach('creating proxy', async function () { + this.proxy = (await createProxy(this.implementation, initializeData, { value })).address; + }); + + assertProxyInitialization({ + value: expectedInitializedValue, + balance: value, + }); + }); + }); + + describe('reverting initialization', function () { + const initializeData = new DummyImplementation('').contract.methods.reverts().encodeABI(); + + it('reverts', async function () { + await expectRevert(createProxy(this.implementation, initializeData), 'DummyImplementation reverted'); + }); + }); + }); +}; diff --git a/test/proxy/beacon/BeaconProxy.test.js b/test/proxy/beacon/BeaconProxy.test.js new file mode 100644 index 000000000..d583d0ffb --- /dev/null +++ b/test/proxy/beacon/BeaconProxy.test.js @@ -0,0 +1,152 @@ +const { expectRevert } = require('@openzeppelin/test-helpers'); +const { getSlot, BeaconSlot } = require('../../helpers/erc1967'); + +const { expectRevertCustomError } = require('../../helpers/customError'); + +const { expect } = require('chai'); + +const UpgradeableBeacon = artifacts.require('UpgradeableBeacon'); +const BeaconProxy = artifacts.require('BeaconProxy'); +const DummyImplementation = artifacts.require('DummyImplementation'); +const DummyImplementationV2 = artifacts.require('DummyImplementationV2'); +const BadBeaconNoImpl = artifacts.require('BadBeaconNoImpl'); +const BadBeaconNotContract = artifacts.require('BadBeaconNotContract'); + +contract('BeaconProxy', function (accounts) { + const [upgradeableBeaconAdmin, anotherAccount] = accounts; + + describe('bad beacon is not accepted', async function () { + it('non-contract beacon', async function () { + await expectRevertCustomError(BeaconProxy.new(anotherAccount, '0x'), 'ERC1967InvalidBeacon', [anotherAccount]); + }); + + it('non-compliant beacon', async function () { + const beacon = await BadBeaconNoImpl.new(); + await expectRevert.unspecified(BeaconProxy.new(beacon.address, '0x')); + }); + + it('non-contract implementation', async function () { + const beacon = await BadBeaconNotContract.new(); + const implementation = await beacon.implementation(); + await expectRevertCustomError(BeaconProxy.new(beacon.address, '0x'), 'ERC1967InvalidImplementation', [ + implementation, + ]); + }); + }); + + before('deploy implementation', async function () { + this.implementationV0 = await DummyImplementation.new(); + this.implementationV1 = await DummyImplementationV2.new(); + }); + + describe('initialization', function () { + before(function () { + this.assertInitialized = async ({ value, balance }) => { + const beaconSlot = await getSlot(this.proxy, BeaconSlot); + const beaconAddress = web3.utils.toChecksumAddress(beaconSlot.substr(-40)); + expect(beaconAddress).to.equal(this.beacon.address); + + const dummy = new DummyImplementation(this.proxy.address); + expect(await dummy.value()).to.bignumber.eq(value); + + expect(await web3.eth.getBalance(this.proxy.address)).to.bignumber.eq(balance); + }; + }); + + beforeEach('deploy beacon', async function () { + this.beacon = await UpgradeableBeacon.new(this.implementationV0.address, upgradeableBeaconAdmin); + }); + + it('no initialization', async function () { + const data = Buffer.from(''); + this.proxy = await BeaconProxy.new(this.beacon.address, data); + await this.assertInitialized({ value: '0', balance: '0' }); + }); + + it('non-payable initialization', async function () { + const value = '55'; + const data = this.implementationV0.contract.methods.initializeNonPayableWithValue(value).encodeABI(); + this.proxy = await BeaconProxy.new(this.beacon.address, data); + await this.assertInitialized({ value, balance: '0' }); + }); + + it('payable initialization', async function () { + const value = '55'; + const data = this.implementationV0.contract.methods.initializePayableWithValue(value).encodeABI(); + const balance = '100'; + this.proxy = await BeaconProxy.new(this.beacon.address, data, { value: balance }); + await this.assertInitialized({ value, balance }); + }); + + it('reverting initialization due to value', async function () { + const data = Buffer.from(''); + await expectRevertCustomError( + BeaconProxy.new(this.beacon.address, data, { value: '1' }), + 'ERC1967NonPayable', + [], + ); + }); + + it('reverting initialization function', async function () { + const data = this.implementationV0.contract.methods.reverts().encodeABI(); + await expectRevert(BeaconProxy.new(this.beacon.address, data), 'DummyImplementation reverted'); + }); + }); + + it('upgrade a proxy by upgrading its beacon', async function () { + const beacon = await UpgradeableBeacon.new(this.implementationV0.address, upgradeableBeaconAdmin); + + const value = '10'; + const data = this.implementationV0.contract.methods.initializeNonPayableWithValue(value).encodeABI(); + const proxy = await BeaconProxy.new(beacon.address, data); + + const dummy = new DummyImplementation(proxy.address); + + // test initial values + expect(await dummy.value()).to.bignumber.eq(value); + + // test initial version + expect(await dummy.version()).to.eq('V1'); + + // upgrade beacon + await beacon.upgradeTo(this.implementationV1.address, { from: upgradeableBeaconAdmin }); + + // test upgraded version + expect(await dummy.version()).to.eq('V2'); + }); + + it('upgrade 2 proxies by upgrading shared beacon', async function () { + const value1 = '10'; + const value2 = '42'; + + const beacon = await UpgradeableBeacon.new(this.implementationV0.address, upgradeableBeaconAdmin); + + const proxy1InitializeData = this.implementationV0.contract.methods + .initializeNonPayableWithValue(value1) + .encodeABI(); + const proxy1 = await BeaconProxy.new(beacon.address, proxy1InitializeData); + + const proxy2InitializeData = this.implementationV0.contract.methods + .initializeNonPayableWithValue(value2) + .encodeABI(); + const proxy2 = await BeaconProxy.new(beacon.address, proxy2InitializeData); + + const dummy1 = new DummyImplementation(proxy1.address); + const dummy2 = new DummyImplementation(proxy2.address); + + // test initial values + expect(await dummy1.value()).to.bignumber.eq(value1); + expect(await dummy2.value()).to.bignumber.eq(value2); + + // test initial version + expect(await dummy1.version()).to.eq('V1'); + expect(await dummy2.version()).to.eq('V1'); + + // upgrade beacon + await beacon.upgradeTo(this.implementationV1.address, { from: upgradeableBeaconAdmin }); + + // test upgraded version + expect(await dummy1.version()).to.eq('V2'); + expect(await dummy2.version()).to.eq('V2'); + }); +}); diff --git a/test/proxy/beacon/UpgradeableBeacon.test.js b/test/proxy/beacon/UpgradeableBeacon.test.js new file mode 100644 index 000000000..0737f6fdf --- /dev/null +++ b/test/proxy/beacon/UpgradeableBeacon.test.js @@ -0,0 +1,54 @@ +const { expectEvent } = require('@openzeppelin/test-helpers'); +const { expect } = require('chai'); + +const { expectRevertCustomError } = require('../../helpers/customError'); + +const UpgradeableBeacon = artifacts.require('UpgradeableBeacon'); +const Implementation1 = artifacts.require('Implementation1'); +const Implementation2 = artifacts.require('Implementation2'); + +contract('UpgradeableBeacon', function (accounts) { + const [owner, other] = accounts; + + it('cannot be created with non-contract implementation', async function () { + await expectRevertCustomError(UpgradeableBeacon.new(other, owner), 'BeaconInvalidImplementation', [other]); + }); + + context('once deployed', async function () { + beforeEach('deploying beacon', async function () { + this.v1 = await Implementation1.new(); + this.beacon = await UpgradeableBeacon.new(this.v1.address, owner); + }); + + it('emits Upgraded event to the first implementation', async function () { + const beacon = await UpgradeableBeacon.new(this.v1.address, owner); + await expectEvent.inTransaction(beacon.contract.transactionHash, beacon, 'Upgraded', { + implementation: this.v1.address, + }); + }); + + it('returns implementation', async function () { + expect(await this.beacon.implementation()).to.equal(this.v1.address); + }); + + it('can be upgraded by the owner', async function () { + const v2 = await Implementation2.new(); + const receipt = await this.beacon.upgradeTo(v2.address, { from: owner }); + expectEvent(receipt, 'Upgraded', { implementation: v2.address }); + expect(await this.beacon.implementation()).to.equal(v2.address); + }); + + it('cannot be upgraded to a non-contract', async function () { + await expectRevertCustomError(this.beacon.upgradeTo(other, { from: owner }), 'BeaconInvalidImplementation', [ + other, + ]); + }); + + it('cannot be upgraded by other account', async function () { + const v2 = await Implementation2.new(); + await expectRevertCustomError(this.beacon.upgradeTo(v2.address, { from: other }), 'OwnableUnauthorizedAccount', [ + other, + ]); + }); + }); +}); diff --git a/test/proxy/transparent/ProxyAdmin.test.js b/test/proxy/transparent/ProxyAdmin.test.js new file mode 100644 index 000000000..4d1a54f6a --- /dev/null +++ b/test/proxy/transparent/ProxyAdmin.test.js @@ -0,0 +1,103 @@ +const { expectRevert } = require('@openzeppelin/test-helpers'); +const { expect } = require('chai'); +const ImplV1 = artifacts.require('DummyImplementation'); +const ImplV2 = artifacts.require('DummyImplementationV2'); +const ProxyAdmin = artifacts.require('ProxyAdmin'); +const TransparentUpgradeableProxy = artifacts.require('TransparentUpgradeableProxy'); +const ITransparentUpgradeableProxy = artifacts.require('ITransparentUpgradeableProxy'); + +const { getAddressInSlot, ImplementationSlot } = require('../../helpers/erc1967'); +const { expectRevertCustomError } = require('../../helpers/customError'); +const { computeCreateAddress } = require('../../helpers/create'); + +contract('ProxyAdmin', function (accounts) { + const [proxyAdminOwner, anotherAccount] = accounts; + + before('set implementations', async function () { + this.implementationV1 = await ImplV1.new(); + this.implementationV2 = await ImplV2.new(); + }); + + beforeEach(async function () { + const initializeData = Buffer.from(''); + const proxy = await TransparentUpgradeableProxy.new(this.implementationV1.address, proxyAdminOwner, initializeData); + + const proxyNonce = await web3.eth.getTransactionCount(proxy.address); + const proxyAdminAddress = computeCreateAddress(proxy.address, proxyNonce - 1); // Nonce already used + this.proxyAdmin = await ProxyAdmin.at(proxyAdminAddress); + + this.proxy = await ITransparentUpgradeableProxy.at(proxy.address); + }); + + it('has an owner', async function () { + expect(await this.proxyAdmin.owner()).to.equal(proxyAdminOwner); + }); + + it('has an interface version', async function () { + expect(await this.proxyAdmin.UPGRADE_INTERFACE_VERSION()).to.equal('5.0.0'); + }); + + describe('without data', function () { + context('with unauthorized account', function () { + it('fails to upgrade', async function () { + await expectRevertCustomError( + this.proxyAdmin.upgradeAndCall(this.proxy.address, this.implementationV2.address, '0x', { + from: anotherAccount, + }), + 'OwnableUnauthorizedAccount', + [anotherAccount], + ); + }); + }); + + context('with authorized account', function () { + it('upgrades implementation', async function () { + await this.proxyAdmin.upgradeAndCall(this.proxy.address, this.implementationV2.address, '0x', { + from: proxyAdminOwner, + }); + + const implementationAddress = await getAddressInSlot(this.proxy, ImplementationSlot); + expect(implementationAddress).to.be.equal(this.implementationV2.address); + }); + }); + }); + + describe('with data', function () { + context('with unauthorized account', function () { + it('fails to upgrade', async function () { + const callData = new ImplV1('').contract.methods.initializeNonPayableWithValue(1337).encodeABI(); + await expectRevertCustomError( + this.proxyAdmin.upgradeAndCall(this.proxy.address, this.implementationV2.address, callData, { + from: anotherAccount, + }), + 'OwnableUnauthorizedAccount', + [anotherAccount], + ); + }); + }); + + context('with authorized account', function () { + context('with invalid callData', function () { + it('fails to upgrade', async function () { + const callData = '0x12345678'; + await expectRevert.unspecified( + this.proxyAdmin.upgradeAndCall(this.proxy.address, this.implementationV2.address, callData, { + from: proxyAdminOwner, + }), + ); + }); + }); + + context('with valid callData', function () { + it('upgrades implementation', async function () { + const callData = new ImplV1('').contract.methods.initializeNonPayableWithValue(1337).encodeABI(); + await this.proxyAdmin.upgradeAndCall(this.proxy.address, this.implementationV2.address, callData, { + from: proxyAdminOwner, + }); + const implementationAddress = await getAddressInSlot(this.proxy, ImplementationSlot); + expect(implementationAddress).to.be.equal(this.implementationV2.address); + }); + }); + }); + }); +}); diff --git a/test/proxy/transparent/TransparentUpgradeableProxy.behaviour.js b/test/proxy/transparent/TransparentUpgradeableProxy.behaviour.js new file mode 100644 index 000000000..103af7fc3 --- /dev/null +++ b/test/proxy/transparent/TransparentUpgradeableProxy.behaviour.js @@ -0,0 +1,413 @@ +const { BN, expectRevert, expectEvent, constants } = require('@openzeppelin/test-helpers'); +const { ZERO_ADDRESS } = constants; +const { getAddressInSlot, ImplementationSlot, AdminSlot } = require('../../helpers/erc1967'); +const { expectRevertCustomError } = require('../../helpers/customError'); + +const { expect } = require('chai'); +const { web3 } = require('hardhat'); +const { computeCreateAddress } = require('../../helpers/create'); +const { impersonate } = require('../../helpers/account'); + +const Implementation1 = artifacts.require('Implementation1'); +const Implementation2 = artifacts.require('Implementation2'); +const Implementation3 = artifacts.require('Implementation3'); +const Implementation4 = artifacts.require('Implementation4'); +const MigratableMockV1 = artifacts.require('MigratableMockV1'); +const MigratableMockV2 = artifacts.require('MigratableMockV2'); +const MigratableMockV3 = artifacts.require('MigratableMockV3'); +const InitializableMock = artifacts.require('InitializableMock'); +const DummyImplementation = artifacts.require('DummyImplementation'); +const ClashingImplementation = artifacts.require('ClashingImplementation'); +const Ownable = artifacts.require('Ownable'); + +module.exports = function shouldBehaveLikeTransparentUpgradeableProxy(createProxy, initialOwner, accounts) { + const [anotherAccount] = accounts; + + async function createProxyWithImpersonatedProxyAdmin(logic, initData, opts = undefined) { + const proxy = await createProxy(logic, initData, opts); + + // Expect proxy admin to be the first and only contract created by the proxy + const proxyAdminAddress = computeCreateAddress(proxy.address, 1); + await impersonate(proxyAdminAddress); + + return { + proxy, + proxyAdminAddress, + }; + } + + before(async function () { + this.implementationV0 = (await DummyImplementation.new()).address; + this.implementationV1 = (await DummyImplementation.new()).address; + }); + + beforeEach(async function () { + const initializeData = Buffer.from(''); + const { proxy, proxyAdminAddress } = await createProxyWithImpersonatedProxyAdmin( + this.implementationV0, + initializeData, + ); + this.proxy = proxy; + this.proxyAdminAddress = proxyAdminAddress; + }); + + describe('implementation', function () { + it('returns the current implementation address', async function () { + const implementationAddress = await getAddressInSlot(this.proxy, ImplementationSlot); + expect(implementationAddress).to.be.equal(this.implementationV0); + }); + + it('delegates to the implementation', async function () { + const dummy = new DummyImplementation(this.proxy.address); + const value = await dummy.get(); + + expect(value).to.equal(true); + }); + }); + + describe('proxy admin', function () { + it('emits AdminChanged event during construction', async function () { + await expectEvent.inConstruction(this.proxy, 'AdminChanged', { + previousAdmin: ZERO_ADDRESS, + newAdmin: this.proxyAdminAddress, + }); + }); + + it('sets the proxy admin in storage with the correct initial owner', async function () { + expect(await getAddressInSlot(this.proxy, AdminSlot)).to.be.equal(this.proxyAdminAddress); + const proxyAdmin = await Ownable.at(this.proxyAdminAddress); + expect(await proxyAdmin.owner()).to.be.equal(initialOwner); + }); + + it('can overwrite the admin by the implementation', async function () { + const dummy = new DummyImplementation(this.proxy.address); + await dummy.unsafeOverrideAdmin(anotherAccount); + const ERC1967AdminSlotValue = await getAddressInSlot(this.proxy, AdminSlot); + expect(ERC1967AdminSlotValue).to.be.equal(anotherAccount); + + // Still allows previous admin to execute admin operations + expect(ERC1967AdminSlotValue).to.not.equal(this.proxyAdminAddress); + expectEvent( + await this.proxy.upgradeToAndCall(this.implementationV1, '0x', { from: this.proxyAdminAddress }), + 'Upgraded', + { + implementation: this.implementationV1, + }, + ); + }); + }); + + describe('upgradeToAndCall', function () { + describe('without migrations', function () { + beforeEach(async function () { + this.behavior = await InitializableMock.new(); + }); + + describe('when the call does not fail', function () { + const initializeData = new InitializableMock('').contract.methods['initializeWithX(uint256)'](42).encodeABI(); + + describe('when the sender is the admin', function () { + const value = 1e5; + + beforeEach(async function () { + this.receipt = await this.proxy.upgradeToAndCall(this.behavior.address, initializeData, { + from: this.proxyAdminAddress, + value, + }); + }); + + it('upgrades to the requested implementation', async function () { + const implementationAddress = await getAddressInSlot(this.proxy, ImplementationSlot); + expect(implementationAddress).to.be.equal(this.behavior.address); + }); + + it('emits an event', function () { + expectEvent(this.receipt, 'Upgraded', { implementation: this.behavior.address }); + }); + + it('calls the initializer function', async function () { + const migratable = new InitializableMock(this.proxy.address); + const x = await migratable.x(); + expect(x).to.be.bignumber.equal('42'); + }); + + it('sends given value to the proxy', async function () { + const balance = await web3.eth.getBalance(this.proxy.address); + expect(balance.toString()).to.be.bignumber.equal(value.toString()); + }); + + it('uses the storage of the proxy', async function () { + // storage layout should look as follows: + // - 0: Initializable storage ++ initializerRan ++ onlyInitializingRan + // - 1: x + const storedValue = await web3.eth.getStorageAt(this.proxy.address, 1); + expect(parseInt(storedValue)).to.eq(42); + }); + }); + + describe('when the sender is not the admin', function () { + it('reverts', async function () { + await expectRevert.unspecified( + this.proxy.upgradeToAndCall(this.behavior.address, initializeData, { from: anotherAccount }), + ); + }); + }); + }); + + describe('when the call does fail', function () { + const initializeData = new InitializableMock('').contract.methods.fail().encodeABI(); + + it('reverts', async function () { + await expectRevert.unspecified( + this.proxy.upgradeToAndCall(this.behavior.address, initializeData, { from: this.proxyAdminAddress }), + ); + }); + }); + }); + + describe('with migrations', function () { + describe('when the sender is the admin', function () { + const value = 1e5; + + describe('when upgrading to V1', function () { + const v1MigrationData = new MigratableMockV1('').contract.methods.initialize(42).encodeABI(); + + beforeEach(async function () { + this.behaviorV1 = await MigratableMockV1.new(); + this.balancePreviousV1 = new BN(await web3.eth.getBalance(this.proxy.address)); + this.receipt = await this.proxy.upgradeToAndCall(this.behaviorV1.address, v1MigrationData, { + from: this.proxyAdminAddress, + value, + }); + }); + + it('upgrades to the requested version and emits an event', async function () { + const implementation = await getAddressInSlot(this.proxy, ImplementationSlot); + expect(implementation).to.be.equal(this.behaviorV1.address); + expectEvent(this.receipt, 'Upgraded', { implementation: this.behaviorV1.address }); + }); + + it("calls the 'initialize' function and sends given value to the proxy", async function () { + const migratable = new MigratableMockV1(this.proxy.address); + + const x = await migratable.x(); + expect(x).to.be.bignumber.equal('42'); + + const balance = await web3.eth.getBalance(this.proxy.address); + expect(new BN(balance)).to.be.bignumber.equal(this.balancePreviousV1.addn(value)); + }); + + describe('when upgrading to V2', function () { + const v2MigrationData = new MigratableMockV2('').contract.methods.migrate(10, 42).encodeABI(); + + beforeEach(async function () { + this.behaviorV2 = await MigratableMockV2.new(); + this.balancePreviousV2 = new BN(await web3.eth.getBalance(this.proxy.address)); + this.receipt = await this.proxy.upgradeToAndCall(this.behaviorV2.address, v2MigrationData, { + from: this.proxyAdminAddress, + value, + }); + }); + + it('upgrades to the requested version and emits an event', async function () { + const implementation = await getAddressInSlot(this.proxy, ImplementationSlot); + expect(implementation).to.be.equal(this.behaviorV2.address); + expectEvent(this.receipt, 'Upgraded', { implementation: this.behaviorV2.address }); + }); + + it("calls the 'migrate' function and sends given value to the proxy", async function () { + const migratable = new MigratableMockV2(this.proxy.address); + + const x = await migratable.x(); + expect(x).to.be.bignumber.equal('10'); + + const y = await migratable.y(); + expect(y).to.be.bignumber.equal('42'); + + const balance = new BN(await web3.eth.getBalance(this.proxy.address)); + expect(balance).to.be.bignumber.equal(this.balancePreviousV2.addn(value)); + }); + + describe('when upgrading to V3', function () { + const v3MigrationData = new MigratableMockV3('').contract.methods['migrate()']().encodeABI(); + + beforeEach(async function () { + this.behaviorV3 = await MigratableMockV3.new(); + this.balancePreviousV3 = new BN(await web3.eth.getBalance(this.proxy.address)); + this.receipt = await this.proxy.upgradeToAndCall(this.behaviorV3.address, v3MigrationData, { + from: this.proxyAdminAddress, + value, + }); + }); + + it('upgrades to the requested version and emits an event', async function () { + const implementation = await getAddressInSlot(this.proxy, ImplementationSlot); + expect(implementation).to.be.equal(this.behaviorV3.address); + expectEvent(this.receipt, 'Upgraded', { implementation: this.behaviorV3.address }); + }); + + it("calls the 'migrate' function and sends given value to the proxy", async function () { + const migratable = new MigratableMockV3(this.proxy.address); + + const x = await migratable.x(); + expect(x).to.be.bignumber.equal('42'); + + const y = await migratable.y(); + expect(y).to.be.bignumber.equal('10'); + + const balance = new BN(await web3.eth.getBalance(this.proxy.address)); + expect(balance).to.be.bignumber.equal(this.balancePreviousV3.addn(value)); + }); + }); + }); + }); + }); + + describe('when the sender is not the admin', function () { + const from = anotherAccount; + + it('reverts', async function () { + const behaviorV1 = await MigratableMockV1.new(); + const v1MigrationData = new MigratableMockV1('').contract.methods.initialize(42).encodeABI(); + await expectRevert.unspecified(this.proxy.upgradeToAndCall(behaviorV1.address, v1MigrationData, { from })); + }); + }); + }); + }); + + describe('transparent proxy', function () { + beforeEach('creating proxy', async function () { + const initializeData = Buffer.from(''); + this.clashingImplV0 = (await ClashingImplementation.new()).address; + this.clashingImplV1 = (await ClashingImplementation.new()).address; + const { proxy, proxyAdminAddress } = await createProxyWithImpersonatedProxyAdmin( + this.clashingImplV0, + initializeData, + ); + this.proxy = proxy; + this.proxyAdminAddress = proxyAdminAddress; + this.clashing = new ClashingImplementation(this.proxy.address); + }); + + it('proxy admin cannot call delegated functions', async function () { + await expectRevertCustomError( + this.clashing.delegatedFunction({ from: this.proxyAdminAddress }), + 'ProxyDeniedAdminAccess', + [], + ); + }); + + describe('when function names clash', function () { + it('executes the proxy function if the sender is the admin', async function () { + const receipt = await this.proxy.upgradeToAndCall(this.clashingImplV1, '0x', { + from: this.proxyAdminAddress, + }); + expectEvent(receipt, 'Upgraded', { implementation: this.clashingImplV1 }); + }); + + it('delegates the call to implementation when sender is not the admin', async function () { + const receipt = await this.proxy.upgradeToAndCall(this.clashingImplV1, '0x', { + from: anotherAccount, + }); + expectEvent.notEmitted(receipt, 'Upgraded'); + expectEvent.inTransaction(receipt.tx, this.clashing, 'ClashingImplementationCall'); + }); + }); + }); + + describe('regression', () => { + const initializeData = Buffer.from(''); + + it('should add new function', async () => { + const instance1 = await Implementation1.new(); + const { proxy, proxyAdminAddress } = await createProxyWithImpersonatedProxyAdmin( + instance1.address, + initializeData, + ); + + const proxyInstance1 = new Implementation1(proxy.address); + await proxyInstance1.setValue(42); + + const instance2 = await Implementation2.new(); + await proxy.upgradeToAndCall(instance2.address, '0x', { from: proxyAdminAddress }); + + const proxyInstance2 = new Implementation2(proxy.address); + const res = await proxyInstance2.getValue(); + expect(res.toString()).to.eq('42'); + }); + + it('should remove function', async () => { + const instance2 = await Implementation2.new(); + const { proxy, proxyAdminAddress } = await createProxyWithImpersonatedProxyAdmin( + instance2.address, + initializeData, + ); + + const proxyInstance2 = new Implementation2(proxy.address); + await proxyInstance2.setValue(42); + const res = await proxyInstance2.getValue(); + expect(res.toString()).to.eq('42'); + + const instance1 = await Implementation1.new(); + await proxy.upgradeToAndCall(instance1.address, '0x', { from: proxyAdminAddress }); + + const proxyInstance1 = new Implementation2(proxy.address); + await expectRevert.unspecified(proxyInstance1.getValue()); + }); + + it('should change function signature', async () => { + const instance1 = await Implementation1.new(); + const { proxy, proxyAdminAddress } = await createProxyWithImpersonatedProxyAdmin( + instance1.address, + initializeData, + ); + + const proxyInstance1 = new Implementation1(proxy.address); + await proxyInstance1.setValue(42); + + const instance3 = await Implementation3.new(); + await proxy.upgradeToAndCall(instance3.address, '0x', { from: proxyAdminAddress }); + const proxyInstance3 = new Implementation3(proxy.address); + + const res = await proxyInstance3.getValue(8); + expect(res.toString()).to.eq('50'); + }); + + it('should add fallback function', async () => { + const initializeData = Buffer.from(''); + const instance1 = await Implementation1.new(); + const { proxy, proxyAdminAddress } = await createProxyWithImpersonatedProxyAdmin( + instance1.address, + initializeData, + ); + + const instance4 = await Implementation4.new(); + await proxy.upgradeToAndCall(instance4.address, '0x', { from: proxyAdminAddress }); + const proxyInstance4 = new Implementation4(proxy.address); + + const data = '0x'; + await web3.eth.sendTransaction({ to: proxy.address, from: anotherAccount, data }); + + const res = await proxyInstance4.getValue(); + expect(res.toString()).to.eq('1'); + }); + + it('should remove fallback function', async () => { + const instance4 = await Implementation4.new(); + const { proxy, proxyAdminAddress } = await createProxyWithImpersonatedProxyAdmin( + instance4.address, + initializeData, + ); + + const instance2 = await Implementation2.new(); + await proxy.upgradeToAndCall(instance2.address, '0x', { from: proxyAdminAddress }); + + const data = '0x'; + await expectRevert.unspecified(web3.eth.sendTransaction({ to: proxy.address, from: anotherAccount, data })); + + const proxyInstance2 = new Implementation2(proxy.address); + const res = await proxyInstance2.getValue(); + expect(res.toString()).to.eq('0'); + }); + }); +}; diff --git a/test/proxy/transparent/TransparentUpgradeableProxy.test.js b/test/proxy/transparent/TransparentUpgradeableProxy.test.js new file mode 100644 index 000000000..f45e392f6 --- /dev/null +++ b/test/proxy/transparent/TransparentUpgradeableProxy.test.js @@ -0,0 +1,24 @@ +const shouldBehaveLikeProxy = require('../Proxy.behaviour'); +const shouldBehaveLikeTransparentUpgradeableProxy = require('./TransparentUpgradeableProxy.behaviour'); + +const TransparentUpgradeableProxy = artifacts.require('TransparentUpgradeableProxy'); +const ITransparentUpgradeableProxy = artifacts.require('ITransparentUpgradeableProxy'); + +contract('TransparentUpgradeableProxy', function (accounts) { + const [owner, ...otherAccounts] = accounts; + + // `undefined`, `null` and other false-ish opts will not be forwarded. + const createProxy = async function (logic, initData, opts = undefined) { + const { address, transactionHash } = await TransparentUpgradeableProxy.new( + logic, + owner, + initData, + ...[opts].filter(Boolean), + ); + const instance = await ITransparentUpgradeableProxy.at(address); + return { ...instance, transactionHash }; + }; + + shouldBehaveLikeProxy(createProxy, otherAccounts); + shouldBehaveLikeTransparentUpgradeableProxy(createProxy, owner, otherAccounts); +}); diff --git a/test/proxy/utils/Initializable.test.js b/test/proxy/utils/Initializable.test.js new file mode 100644 index 000000000..b9ff3b052 --- /dev/null +++ b/test/proxy/utils/Initializable.test.js @@ -0,0 +1,220 @@ +const { expectEvent } = require('@openzeppelin/test-helpers'); +const { expect } = require('chai'); +const { expectRevertCustomError } = require('../../helpers/customError'); +const { MAX_UINT64 } = require('../../helpers/constants'); + +const InitializableMock = artifacts.require('InitializableMock'); +const ConstructorInitializableMock = artifacts.require('ConstructorInitializableMock'); +const ChildConstructorInitializableMock = artifacts.require('ChildConstructorInitializableMock'); +const ReinitializerMock = artifacts.require('ReinitializerMock'); +const SampleChild = artifacts.require('SampleChild'); +const DisableBad1 = artifacts.require('DisableBad1'); +const DisableBad2 = artifacts.require('DisableBad2'); +const DisableOk = artifacts.require('DisableOk'); + +contract('Initializable', function () { + describe('basic testing without inheritance', function () { + beforeEach('deploying', async function () { + this.contract = await InitializableMock.new(); + }); + + describe('before initialize', function () { + it('initializer has not run', async function () { + expect(await this.contract.initializerRan()).to.equal(false); + }); + + it('_initializing returns false before initialization', async function () { + expect(await this.contract.isInitializing()).to.equal(false); + }); + }); + + describe('after initialize', function () { + beforeEach('initializing', async function () { + await this.contract.initialize(); + }); + + it('initializer has run', async function () { + expect(await this.contract.initializerRan()).to.equal(true); + }); + + it('_initializing returns false after initialization', async function () { + expect(await this.contract.isInitializing()).to.equal(false); + }); + + it('initializer does not run again', async function () { + await expectRevertCustomError(this.contract.initialize(), 'InvalidInitialization', []); + }); + }); + + describe('nested under an initializer', function () { + it('initializer modifier reverts', async function () { + await expectRevertCustomError(this.contract.initializerNested(), 'InvalidInitialization', []); + }); + + it('onlyInitializing modifier succeeds', async function () { + await this.contract.onlyInitializingNested(); + expect(await this.contract.onlyInitializingRan()).to.equal(true); + }); + }); + + it('cannot call onlyInitializable function outside the scope of an initializable function', async function () { + await expectRevertCustomError(this.contract.initializeOnlyInitializing(), 'NotInitializing', []); + }); + }); + + it('nested initializer can run during construction', async function () { + const contract2 = await ConstructorInitializableMock.new(); + expect(await contract2.initializerRan()).to.equal(true); + expect(await contract2.onlyInitializingRan()).to.equal(true); + }); + + it('multiple constructor levels can be initializers', async function () { + const contract2 = await ChildConstructorInitializableMock.new(); + expect(await contract2.initializerRan()).to.equal(true); + expect(await contract2.childInitializerRan()).to.equal(true); + expect(await contract2.onlyInitializingRan()).to.equal(true); + }); + + describe('reinitialization', function () { + beforeEach('deploying', async function () { + this.contract = await ReinitializerMock.new(); + }); + + it('can reinitialize', async function () { + expect(await this.contract.counter()).to.be.bignumber.equal('0'); + await this.contract.initialize(); + expect(await this.contract.counter()).to.be.bignumber.equal('1'); + await this.contract.reinitialize(2); + expect(await this.contract.counter()).to.be.bignumber.equal('2'); + await this.contract.reinitialize(3); + expect(await this.contract.counter()).to.be.bignumber.equal('3'); + }); + + it('can jump multiple steps', async function () { + expect(await this.contract.counter()).to.be.bignumber.equal('0'); + await this.contract.initialize(); + expect(await this.contract.counter()).to.be.bignumber.equal('1'); + await this.contract.reinitialize(128); + expect(await this.contract.counter()).to.be.bignumber.equal('2'); + }); + + it('cannot nest reinitializers', async function () { + expect(await this.contract.counter()).to.be.bignumber.equal('0'); + await expectRevertCustomError(this.contract.nestedReinitialize(2, 2), 'InvalidInitialization', []); + await expectRevertCustomError(this.contract.nestedReinitialize(2, 3), 'InvalidInitialization', []); + await expectRevertCustomError(this.contract.nestedReinitialize(3, 2), 'InvalidInitialization', []); + }); + + it('can chain reinitializers', async function () { + expect(await this.contract.counter()).to.be.bignumber.equal('0'); + await this.contract.chainReinitialize(2, 3); + expect(await this.contract.counter()).to.be.bignumber.equal('2'); + }); + + it('_getInitializedVersion returns right version', async function () { + await this.contract.initialize(); + expect(await this.contract.getInitializedVersion()).to.be.bignumber.equal('1'); + await this.contract.reinitialize(12); + expect(await this.contract.getInitializedVersion()).to.be.bignumber.equal('12'); + }); + + describe('contract locking', function () { + it('prevents initialization', async function () { + await this.contract.disableInitializers(); + await expectRevertCustomError(this.contract.initialize(), 'InvalidInitialization', []); + }); + + it('prevents re-initialization', async function () { + await this.contract.disableInitializers(); + await expectRevertCustomError(this.contract.reinitialize(255), 'InvalidInitialization', []); + }); + + it('can lock contract after initialization', async function () { + await this.contract.initialize(); + await this.contract.disableInitializers(); + await expectRevertCustomError(this.contract.reinitialize(255), 'InvalidInitialization', []); + }); + }); + }); + + describe('events', function () { + it('constructor initialization emits event', async function () { + const contract = await ConstructorInitializableMock.new(); + + await expectEvent.inTransaction(contract.transactionHash, contract, 'Initialized', { version: '1' }); + }); + + it('initialization emits event', async function () { + const contract = await ReinitializerMock.new(); + + const { receipt } = await contract.initialize(); + expect(receipt.logs.filter(({ event }) => event === 'Initialized').length).to.be.equal(1); + expectEvent(receipt, 'Initialized', { version: '1' }); + }); + + it('reinitialization emits event', async function () { + const contract = await ReinitializerMock.new(); + + const { receipt } = await contract.reinitialize(128); + expect(receipt.logs.filter(({ event }) => event === 'Initialized').length).to.be.equal(1); + expectEvent(receipt, 'Initialized', { version: '128' }); + }); + + it('chained reinitialization emits multiple events', async function () { + const contract = await ReinitializerMock.new(); + + const { receipt } = await contract.chainReinitialize(2, 3); + expect(receipt.logs.filter(({ event }) => event === 'Initialized').length).to.be.equal(2); + expectEvent(receipt, 'Initialized', { version: '2' }); + expectEvent(receipt, 'Initialized', { version: '3' }); + }); + }); + + describe('complex testing with inheritance', function () { + const mother = '12'; + const gramps = '56'; + const father = '34'; + const child = '78'; + + beforeEach('deploying', async function () { + this.contract = await SampleChild.new(); + }); + + beforeEach('initializing', async function () { + await this.contract.initialize(mother, gramps, father, child); + }); + + it('initializes human', async function () { + expect(await this.contract.isHuman()).to.be.equal(true); + }); + + it('initializes mother', async function () { + expect(await this.contract.mother()).to.be.bignumber.equal(mother); + }); + + it('initializes gramps', async function () { + expect(await this.contract.gramps()).to.be.bignumber.equal(gramps); + }); + + it('initializes father', async function () { + expect(await this.contract.father()).to.be.bignumber.equal(father); + }); + + it('initializes child', async function () { + expect(await this.contract.child()).to.be.bignumber.equal(child); + }); + }); + + describe('disabling initialization', function () { + it('old and new patterns in bad sequence', async function () { + await expectRevertCustomError(DisableBad1.new(), 'InvalidInitialization', []); + await expectRevertCustomError(DisableBad2.new(), 'InvalidInitialization', []); + }); + + it('old and new patterns in good sequence', async function () { + const ok = await DisableOk.new(); + await expectEvent.inConstruction(ok, 'Initialized', { version: '1' }); + await expectEvent.inConstruction(ok, 'Initialized', { version: MAX_UINT64 }); + }); + }); +}); diff --git a/test/proxy/utils/UUPSUpgradeable.test.js b/test/proxy/utils/UUPSUpgradeable.test.js new file mode 100644 index 000000000..0baa90520 --- /dev/null +++ b/test/proxy/utils/UUPSUpgradeable.test.js @@ -0,0 +1,131 @@ +const { expectEvent } = require('@openzeppelin/test-helpers'); +const { getAddressInSlot, ImplementationSlot } = require('../../helpers/erc1967'); +const { expectRevertCustomError } = require('../../helpers/customError'); + +const ERC1967Proxy = artifacts.require('ERC1967Proxy'); +const UUPSUpgradeableMock = artifacts.require('UUPSUpgradeableMock'); +const UUPSUpgradeableUnsafeMock = artifacts.require('UUPSUpgradeableUnsafeMock'); +const NonUpgradeableMock = artifacts.require('NonUpgradeableMock'); +const UUPSUnsupportedProxiableUUID = artifacts.require('UUPSUnsupportedProxiableUUID'); +const Clones = artifacts.require('$Clones'); + +contract('UUPSUpgradeable', function () { + before(async function () { + this.implInitial = await UUPSUpgradeableMock.new(); + this.implUpgradeOk = await UUPSUpgradeableMock.new(); + this.implUpgradeUnsafe = await UUPSUpgradeableUnsafeMock.new(); + this.implUpgradeNonUUPS = await NonUpgradeableMock.new(); + this.implUnsupportedUUID = await UUPSUnsupportedProxiableUUID.new(); + // Used for testing non ERC1967 compliant proxies (clones are proxies that don't use the ERC1967 implementation slot) + this.cloneFactory = await Clones.new(); + }); + + beforeEach(async function () { + const { address } = await ERC1967Proxy.new(this.implInitial.address, '0x'); + this.instance = await UUPSUpgradeableMock.at(address); + }); + + it('has an interface version', async function () { + expect(await this.instance.UPGRADE_INTERFACE_VERSION()).to.equal('5.0.0'); + }); + + it('upgrade to upgradeable implementation', async function () { + const { receipt } = await this.instance.upgradeToAndCall(this.implUpgradeOk.address, '0x'); + expect(receipt.logs.filter(({ event }) => event === 'Upgraded').length).to.be.equal(1); + expectEvent(receipt, 'Upgraded', { implementation: this.implUpgradeOk.address }); + expect(await getAddressInSlot(this.instance, ImplementationSlot)).to.be.equal(this.implUpgradeOk.address); + }); + + it('upgrade to upgradeable implementation with call', async function () { + expect(await this.instance.current()).to.be.bignumber.equal('0'); + + const { receipt } = await this.instance.upgradeToAndCall( + this.implUpgradeOk.address, + this.implUpgradeOk.contract.methods.increment().encodeABI(), + ); + expect(receipt.logs.filter(({ event }) => event === 'Upgraded').length).to.be.equal(1); + expectEvent(receipt, 'Upgraded', { implementation: this.implUpgradeOk.address }); + expect(await getAddressInSlot(this.instance, ImplementationSlot)).to.be.equal(this.implUpgradeOk.address); + + expect(await this.instance.current()).to.be.bignumber.equal('1'); + }); + + it('calling upgradeTo on the implementation reverts', async function () { + await expectRevertCustomError( + this.implInitial.upgradeToAndCall(this.implUpgradeOk.address, '0x'), + 'UUPSUnauthorizedCallContext', + [], + ); + }); + + it('calling upgradeToAndCall on the implementation reverts', async function () { + await expectRevertCustomError( + this.implInitial.upgradeToAndCall( + this.implUpgradeOk.address, + this.implUpgradeOk.contract.methods.increment().encodeABI(), + ), + 'UUPSUnauthorizedCallContext', + [], + ); + }); + + it('calling upgradeTo from a contract that is not an ERC1967 proxy (with the right implementation) reverts', async function () { + const receipt = await this.cloneFactory.$clone(this.implUpgradeOk.address); + const instance = await UUPSUpgradeableMock.at( + receipt.logs.find(({ event }) => event === 'return$clone').args.instance, + ); + + await expectRevertCustomError( + instance.upgradeToAndCall(this.implUpgradeUnsafe.address, '0x'), + 'UUPSUnauthorizedCallContext', + [], + ); + }); + + it('calling upgradeToAndCall from a contract that is not an ERC1967 proxy (with the right implementation) reverts', async function () { + const receipt = await this.cloneFactory.$clone(this.implUpgradeOk.address); + const instance = await UUPSUpgradeableMock.at( + receipt.logs.find(({ event }) => event === 'return$clone').args.instance, + ); + + await expectRevertCustomError( + instance.upgradeToAndCall(this.implUpgradeUnsafe.address, '0x'), + 'UUPSUnauthorizedCallContext', + [], + ); + }); + + it('rejects upgrading to an unsupported UUID', async function () { + await expectRevertCustomError( + this.instance.upgradeToAndCall(this.implUnsupportedUUID.address, '0x'), + 'UUPSUnsupportedProxiableUUID', + [web3.utils.keccak256('invalid UUID')], + ); + }); + + it('upgrade to and unsafe upgradeable implementation', async function () { + const { receipt } = await this.instance.upgradeToAndCall(this.implUpgradeUnsafe.address, '0x'); + expectEvent(receipt, 'Upgraded', { implementation: this.implUpgradeUnsafe.address }); + expect(await getAddressInSlot(this.instance, ImplementationSlot)).to.be.equal(this.implUpgradeUnsafe.address); + }); + + // delegate to a non existing upgradeTo function causes a low level revert + it('reject upgrade to non uups implementation', async function () { + await expectRevertCustomError( + this.instance.upgradeToAndCall(this.implUpgradeNonUUPS.address, '0x'), + 'ERC1967InvalidImplementation', + [this.implUpgradeNonUUPS.address], + ); + }); + + it('reject proxy address as implementation', async function () { + const { address } = await ERC1967Proxy.new(this.implInitial.address, '0x'); + const otherInstance = await UUPSUpgradeableMock.at(address); + + await expectRevertCustomError( + this.instance.upgradeToAndCall(otherInstance.address, '0x'), + 'ERC1967InvalidImplementation', + [otherInstance.address], + ); + }); +}); diff --git a/test/token/ERC1155/ERC1155.behavior.js b/test/token/ERC1155/ERC1155.behavior.js new file mode 100644 index 000000000..8df30a814 --- /dev/null +++ b/test/token/ERC1155/ERC1155.behavior.js @@ -0,0 +1,905 @@ +const { BN, constants, expectEvent, expectRevert } = require('@openzeppelin/test-helpers'); +const { expect } = require('chai'); +const { ZERO_ADDRESS } = constants; + +const { shouldSupportInterfaces } = require('../../utils/introspection/SupportsInterface.behavior'); +const { expectRevertCustomError } = require('../../helpers/customError'); +const { Enum } = require('../../helpers/enums'); + +const ERC1155ReceiverMock = artifacts.require('ERC1155ReceiverMock'); +const RevertType = Enum('None', 'RevertWithoutMessage', 'RevertWithMessage', 'RevertWithCustomError', 'Panic'); + +function shouldBehaveLikeERC1155([minter, firstTokenHolder, secondTokenHolder, multiTokenHolder, recipient, proxy]) { + const firstTokenId = new BN(1); + const secondTokenId = new BN(2); + const unknownTokenId = new BN(3); + + const firstTokenValue = new BN(1000); + const secondTokenValue = new BN(2000); + + const RECEIVER_SINGLE_MAGIC_VALUE = '0xf23a6e61'; + const RECEIVER_BATCH_MAGIC_VALUE = '0xbc197c81'; + + describe('like an ERC1155', function () { + describe('balanceOf', function () { + it('should return 0 when queried about the zero address', async function () { + expect(await this.token.balanceOf(ZERO_ADDRESS, firstTokenId)).to.be.bignumber.equal('0'); + }); + + context("when accounts don't own tokens", function () { + it('returns zero for given addresses', async function () { + expect(await this.token.balanceOf(firstTokenHolder, firstTokenId)).to.be.bignumber.equal('0'); + + expect(await this.token.balanceOf(secondTokenHolder, secondTokenId)).to.be.bignumber.equal('0'); + + expect(await this.token.balanceOf(firstTokenHolder, unknownTokenId)).to.be.bignumber.equal('0'); + }); + }); + + context('when accounts own some tokens', function () { + beforeEach(async function () { + await this.token.$_mint(firstTokenHolder, firstTokenId, firstTokenValue, '0x', { + from: minter, + }); + await this.token.$_mint(secondTokenHolder, secondTokenId, secondTokenValue, '0x', { + from: minter, + }); + }); + + it('returns the amount of tokens owned by the given addresses', async function () { + expect(await this.token.balanceOf(firstTokenHolder, firstTokenId)).to.be.bignumber.equal(firstTokenValue); + + expect(await this.token.balanceOf(secondTokenHolder, secondTokenId)).to.be.bignumber.equal(secondTokenValue); + + expect(await this.token.balanceOf(firstTokenHolder, unknownTokenId)).to.be.bignumber.equal('0'); + }); + }); + }); + + describe('balanceOfBatch', function () { + it("reverts when input arrays don't match up", async function () { + const accounts1 = [firstTokenHolder, secondTokenHolder, firstTokenHolder, secondTokenHolder]; + const ids1 = [firstTokenId, secondTokenId, unknownTokenId]; + await expectRevertCustomError(this.token.balanceOfBatch(accounts1, ids1), 'ERC1155InvalidArrayLength', [ + accounts1.length, + ids1.length, + ]); + + const accounts2 = [firstTokenHolder, secondTokenHolder]; + const ids2 = [firstTokenId, secondTokenId, unknownTokenId]; + await expectRevertCustomError(this.token.balanceOfBatch(accounts2, ids2), 'ERC1155InvalidArrayLength', [ + accounts2.length, + ids2.length, + ]); + }); + + it('should return 0 as the balance when one of the addresses is the zero address', async function () { + const result = await this.token.balanceOfBatch( + [firstTokenHolder, secondTokenHolder, ZERO_ADDRESS], + [firstTokenId, secondTokenId, unknownTokenId], + ); + expect(result).to.be.an('array'); + expect(result[0]).to.be.a.bignumber.equal('0'); + expect(result[1]).to.be.a.bignumber.equal('0'); + expect(result[2]).to.be.a.bignumber.equal('0'); + }); + + context("when accounts don't own tokens", function () { + it('returns zeros for each account', async function () { + const result = await this.token.balanceOfBatch( + [firstTokenHolder, secondTokenHolder, firstTokenHolder], + [firstTokenId, secondTokenId, unknownTokenId], + ); + expect(result).to.be.an('array'); + expect(result[0]).to.be.a.bignumber.equal('0'); + expect(result[1]).to.be.a.bignumber.equal('0'); + expect(result[2]).to.be.a.bignumber.equal('0'); + }); + }); + + context('when accounts own some tokens', function () { + beforeEach(async function () { + await this.token.$_mint(firstTokenHolder, firstTokenId, firstTokenValue, '0x', { + from: minter, + }); + await this.token.$_mint(secondTokenHolder, secondTokenId, secondTokenValue, '0x', { + from: minter, + }); + }); + + it('returns amounts owned by each account in order passed', async function () { + const result = await this.token.balanceOfBatch( + [secondTokenHolder, firstTokenHolder, firstTokenHolder], + [secondTokenId, firstTokenId, unknownTokenId], + ); + expect(result).to.be.an('array'); + expect(result[0]).to.be.a.bignumber.equal(secondTokenValue); + expect(result[1]).to.be.a.bignumber.equal(firstTokenValue); + expect(result[2]).to.be.a.bignumber.equal('0'); + }); + + it('returns multiple times the balance of the same address when asked', async function () { + const result = await this.token.balanceOfBatch( + [firstTokenHolder, secondTokenHolder, firstTokenHolder], + [firstTokenId, secondTokenId, firstTokenId], + ); + expect(result).to.be.an('array'); + expect(result[0]).to.be.a.bignumber.equal(result[2]); + expect(result[0]).to.be.a.bignumber.equal(firstTokenValue); + expect(result[1]).to.be.a.bignumber.equal(secondTokenValue); + expect(result[2]).to.be.a.bignumber.equal(firstTokenValue); + }); + }); + }); + + describe('setApprovalForAll', function () { + let receipt; + beforeEach(async function () { + receipt = await this.token.setApprovalForAll(proxy, true, { from: multiTokenHolder }); + }); + + it('sets approval status which can be queried via isApprovedForAll', async function () { + expect(await this.token.isApprovedForAll(multiTokenHolder, proxy)).to.be.equal(true); + }); + + it('emits an ApprovalForAll log', function () { + expectEvent(receipt, 'ApprovalForAll', { account: multiTokenHolder, operator: proxy, approved: true }); + }); + + it('can unset approval for an operator', async function () { + await this.token.setApprovalForAll(proxy, false, { from: multiTokenHolder }); + expect(await this.token.isApprovedForAll(multiTokenHolder, proxy)).to.be.equal(false); + }); + + it('reverts if attempting to approve zero address as an operator', async function () { + await expectRevertCustomError( + this.token.setApprovalForAll(constants.ZERO_ADDRESS, true, { from: multiTokenHolder }), + 'ERC1155InvalidOperator', + [constants.ZERO_ADDRESS], + ); + }); + }); + + describe('safeTransferFrom', function () { + beforeEach(async function () { + await this.token.$_mint(multiTokenHolder, firstTokenId, firstTokenValue, '0x', { + from: minter, + }); + await this.token.$_mint(multiTokenHolder, secondTokenId, secondTokenValue, '0x', { + from: minter, + }); + }); + + it('reverts when transferring more than balance', async function () { + await expectRevertCustomError( + this.token.safeTransferFrom(multiTokenHolder, recipient, firstTokenId, firstTokenValue.addn(1), '0x', { + from: multiTokenHolder, + }), + 'ERC1155InsufficientBalance', + [multiTokenHolder, firstTokenValue, firstTokenValue.addn(1), firstTokenId], + ); + }); + + it('reverts when transferring to zero address', async function () { + await expectRevertCustomError( + this.token.safeTransferFrom(multiTokenHolder, ZERO_ADDRESS, firstTokenId, firstTokenValue, '0x', { + from: multiTokenHolder, + }), + 'ERC1155InvalidReceiver', + [ZERO_ADDRESS], + ); + }); + + function transferWasSuccessful({ operator, from, id, value }) { + it('debits transferred balance from sender', async function () { + const newBalance = await this.token.balanceOf(from, id); + expect(newBalance).to.be.a.bignumber.equal('0'); + }); + + it('credits transferred balance to receiver', async function () { + const newBalance = await this.token.balanceOf(this.toWhom, id); + expect(newBalance).to.be.a.bignumber.equal(value); + }); + + it('emits a TransferSingle log', function () { + expectEvent(this.transferLogs, 'TransferSingle', { + operator, + from, + to: this.toWhom, + id, + value, + }); + }); + } + + context('when called by the multiTokenHolder', async function () { + beforeEach(async function () { + this.toWhom = recipient; + this.transferLogs = await this.token.safeTransferFrom( + multiTokenHolder, + recipient, + firstTokenId, + firstTokenValue, + '0x', + { + from: multiTokenHolder, + }, + ); + }); + + transferWasSuccessful.call(this, { + operator: multiTokenHolder, + from: multiTokenHolder, + id: firstTokenId, + value: firstTokenValue, + }); + + it('preserves existing balances which are not transferred by multiTokenHolder', async function () { + const balance1 = await this.token.balanceOf(multiTokenHolder, secondTokenId); + expect(balance1).to.be.a.bignumber.equal(secondTokenValue); + + const balance2 = await this.token.balanceOf(recipient, secondTokenId); + expect(balance2).to.be.a.bignumber.equal('0'); + }); + }); + + context('when called by an operator on behalf of the multiTokenHolder', function () { + context('when operator is not approved by multiTokenHolder', function () { + beforeEach(async function () { + await this.token.setApprovalForAll(proxy, false, { from: multiTokenHolder }); + }); + + it('reverts', async function () { + await expectRevertCustomError( + this.token.safeTransferFrom(multiTokenHolder, recipient, firstTokenId, firstTokenValue, '0x', { + from: proxy, + }), + 'ERC1155MissingApprovalForAll', + [proxy, multiTokenHolder], + ); + }); + }); + + context('when operator is approved by multiTokenHolder', function () { + beforeEach(async function () { + this.toWhom = recipient; + await this.token.setApprovalForAll(proxy, true, { from: multiTokenHolder }); + this.transferLogs = await this.token.safeTransferFrom( + multiTokenHolder, + recipient, + firstTokenId, + firstTokenValue, + '0x', + { + from: proxy, + }, + ); + }); + + transferWasSuccessful.call(this, { + operator: proxy, + from: multiTokenHolder, + id: firstTokenId, + value: firstTokenValue, + }); + + it("preserves operator's balances not involved in the transfer", async function () { + const balance1 = await this.token.balanceOf(proxy, firstTokenId); + expect(balance1).to.be.a.bignumber.equal('0'); + + const balance2 = await this.token.balanceOf(proxy, secondTokenId); + expect(balance2).to.be.a.bignumber.equal('0'); + }); + }); + }); + + context('when sending to a valid receiver', function () { + beforeEach(async function () { + this.receiver = await ERC1155ReceiverMock.new( + RECEIVER_SINGLE_MAGIC_VALUE, + RECEIVER_BATCH_MAGIC_VALUE, + RevertType.None, + ); + }); + + context('without data', function () { + beforeEach(async function () { + this.toWhom = this.receiver.address; + this.transferReceipt = await this.token.safeTransferFrom( + multiTokenHolder, + this.receiver.address, + firstTokenId, + firstTokenValue, + '0x', + { from: multiTokenHolder }, + ); + this.transferLogs = this.transferReceipt; + }); + + transferWasSuccessful.call(this, { + operator: multiTokenHolder, + from: multiTokenHolder, + id: firstTokenId, + value: firstTokenValue, + }); + + it('calls onERC1155Received', async function () { + await expectEvent.inTransaction(this.transferReceipt.tx, ERC1155ReceiverMock, 'Received', { + operator: multiTokenHolder, + from: multiTokenHolder, + id: firstTokenId, + value: firstTokenValue, + data: null, + }); + }); + }); + + context('with data', function () { + const data = '0xf00dd00d'; + beforeEach(async function () { + this.toWhom = this.receiver.address; + this.transferReceipt = await this.token.safeTransferFrom( + multiTokenHolder, + this.receiver.address, + firstTokenId, + firstTokenValue, + data, + { from: multiTokenHolder }, + ); + this.transferLogs = this.transferReceipt; + }); + + transferWasSuccessful.call(this, { + operator: multiTokenHolder, + from: multiTokenHolder, + id: firstTokenId, + value: firstTokenValue, + }); + + it('calls onERC1155Received', async function () { + await expectEvent.inTransaction(this.transferReceipt.tx, ERC1155ReceiverMock, 'Received', { + operator: multiTokenHolder, + from: multiTokenHolder, + id: firstTokenId, + value: firstTokenValue, + data, + }); + }); + }); + }); + + context('to a receiver contract returning unexpected value', function () { + beforeEach(async function () { + this.receiver = await ERC1155ReceiverMock.new('0x00c0ffee', RECEIVER_BATCH_MAGIC_VALUE, RevertType.None); + }); + + it('reverts', async function () { + await expectRevertCustomError( + this.token.safeTransferFrom(multiTokenHolder, this.receiver.address, firstTokenId, firstTokenValue, '0x', { + from: multiTokenHolder, + }), + 'ERC1155InvalidReceiver', + [this.receiver.address], + ); + }); + }); + + context('to a receiver contract that reverts', function () { + context('with a revert string', function () { + beforeEach(async function () { + this.receiver = await ERC1155ReceiverMock.new( + RECEIVER_SINGLE_MAGIC_VALUE, + RECEIVER_BATCH_MAGIC_VALUE, + RevertType.RevertWithMessage, + ); + }); + + it('reverts', async function () { + await expectRevert( + this.token.safeTransferFrom( + multiTokenHolder, + this.receiver.address, + firstTokenId, + firstTokenValue, + '0x', + { + from: multiTokenHolder, + }, + ), + 'ERC1155ReceiverMock: reverting on receive', + ); + }); + }); + + context('without a revert string', function () { + beforeEach(async function () { + this.receiver = await ERC1155ReceiverMock.new( + RECEIVER_SINGLE_MAGIC_VALUE, + RECEIVER_BATCH_MAGIC_VALUE, + RevertType.RevertWithoutMessage, + ); + }); + + it('reverts', async function () { + await expectRevertCustomError( + this.token.safeTransferFrom( + multiTokenHolder, + this.receiver.address, + firstTokenId, + firstTokenValue, + '0x', + { + from: multiTokenHolder, + }, + ), + 'ERC1155InvalidReceiver', + [this.receiver.address], + ); + }); + }); + + context('with a custom error', function () { + beforeEach(async function () { + this.receiver = await ERC1155ReceiverMock.new( + RECEIVER_SINGLE_MAGIC_VALUE, + RECEIVER_BATCH_MAGIC_VALUE, + RevertType.RevertWithCustomError, + ); + }); + + it('reverts', async function () { + await expectRevertCustomError( + this.token.safeTransferFrom( + multiTokenHolder, + this.receiver.address, + firstTokenId, + firstTokenValue, + '0x', + { + from: multiTokenHolder, + }, + ), + 'CustomError', + [RECEIVER_SINGLE_MAGIC_VALUE], + ); + }); + }); + + context('with a panic', function () { + beforeEach(async function () { + this.receiver = await ERC1155ReceiverMock.new( + RECEIVER_SINGLE_MAGIC_VALUE, + RECEIVER_BATCH_MAGIC_VALUE, + RevertType.Panic, + ); + }); + + it('reverts', async function () { + await expectRevert.unspecified( + this.token.safeTransferFrom( + multiTokenHolder, + this.receiver.address, + firstTokenId, + firstTokenValue, + '0x', + { + from: multiTokenHolder, + }, + ), + ); + }); + }); + }); + + context('to a contract that does not implement the required function', function () { + it('reverts', async function () { + const invalidReceiver = this.token; + await expectRevert.unspecified( + this.token.safeTransferFrom( + multiTokenHolder, + invalidReceiver.address, + firstTokenId, + firstTokenValue, + '0x', + { + from: multiTokenHolder, + }, + ), + ); + }); + }); + }); + + describe('safeBatchTransferFrom', function () { + beforeEach(async function () { + await this.token.$_mint(multiTokenHolder, firstTokenId, firstTokenValue, '0x', { + from: minter, + }); + await this.token.$_mint(multiTokenHolder, secondTokenId, secondTokenValue, '0x', { + from: minter, + }); + }); + + it('reverts when transferring value more than any of balances', async function () { + await expectRevertCustomError( + this.token.safeBatchTransferFrom( + multiTokenHolder, + recipient, + [firstTokenId, secondTokenId], + [firstTokenValue, secondTokenValue.addn(1)], + '0x', + { from: multiTokenHolder }, + ), + 'ERC1155InsufficientBalance', + [multiTokenHolder, secondTokenValue, secondTokenValue.addn(1), secondTokenId], + ); + }); + + it("reverts when ids array length doesn't match values array length", async function () { + const ids1 = [firstTokenId]; + const tokenValues1 = [firstTokenValue, secondTokenValue]; + + await expectRevertCustomError( + this.token.safeBatchTransferFrom(multiTokenHolder, recipient, ids1, tokenValues1, '0x', { + from: multiTokenHolder, + }), + 'ERC1155InvalidArrayLength', + [ids1.length, tokenValues1.length], + ); + + const ids2 = [firstTokenId, secondTokenId]; + const tokenValues2 = [firstTokenValue]; + await expectRevertCustomError( + this.token.safeBatchTransferFrom(multiTokenHolder, recipient, ids2, tokenValues2, '0x', { + from: multiTokenHolder, + }), + 'ERC1155InvalidArrayLength', + [ids2.length, tokenValues2.length], + ); + }); + + it('reverts when transferring to zero address', async function () { + await expectRevertCustomError( + this.token.safeBatchTransferFrom( + multiTokenHolder, + ZERO_ADDRESS, + [firstTokenId, secondTokenId], + [firstTokenValue, secondTokenValue], + '0x', + { from: multiTokenHolder }, + ), + 'ERC1155InvalidReceiver', + [ZERO_ADDRESS], + ); + }); + + it('reverts when transferring from zero address', async function () { + await expectRevertCustomError( + this.token.$_safeBatchTransferFrom(ZERO_ADDRESS, multiTokenHolder, [firstTokenId], [firstTokenValue], '0x'), + 'ERC1155InvalidSender', + [ZERO_ADDRESS], + ); + }); + + function batchTransferWasSuccessful({ operator, from, ids, values }) { + it('debits transferred balances from sender', async function () { + const newBalances = await this.token.balanceOfBatch(new Array(ids.length).fill(from), ids); + for (const newBalance of newBalances) { + expect(newBalance).to.be.a.bignumber.equal('0'); + } + }); + + it('credits transferred balances to receiver', async function () { + const newBalances = await this.token.balanceOfBatch(new Array(ids.length).fill(this.toWhom), ids); + for (let i = 0; i < newBalances.length; i++) { + expect(newBalances[i]).to.be.a.bignumber.equal(values[i]); + } + }); + + it('emits a TransferBatch log', function () { + expectEvent(this.transferLogs, 'TransferBatch', { + operator, + from, + to: this.toWhom, + // ids, + // values, + }); + }); + } + + context('when called by the multiTokenHolder', async function () { + beforeEach(async function () { + this.toWhom = recipient; + this.transferLogs = await this.token.safeBatchTransferFrom( + multiTokenHolder, + recipient, + [firstTokenId, secondTokenId], + [firstTokenValue, secondTokenValue], + '0x', + { from: multiTokenHolder }, + ); + }); + + batchTransferWasSuccessful.call(this, { + operator: multiTokenHolder, + from: multiTokenHolder, + ids: [firstTokenId, secondTokenId], + values: [firstTokenValue, secondTokenValue], + }); + }); + + context('when called by an operator on behalf of the multiTokenHolder', function () { + context('when operator is not approved by multiTokenHolder', function () { + beforeEach(async function () { + await this.token.setApprovalForAll(proxy, false, { from: multiTokenHolder }); + }); + + it('reverts', async function () { + await expectRevertCustomError( + this.token.safeBatchTransferFrom( + multiTokenHolder, + recipient, + [firstTokenId, secondTokenId], + [firstTokenValue, secondTokenValue], + '0x', + { from: proxy }, + ), + 'ERC1155MissingApprovalForAll', + [proxy, multiTokenHolder], + ); + }); + }); + + context('when operator is approved by multiTokenHolder', function () { + beforeEach(async function () { + this.toWhom = recipient; + await this.token.setApprovalForAll(proxy, true, { from: multiTokenHolder }); + this.transferLogs = await this.token.safeBatchTransferFrom( + multiTokenHolder, + recipient, + [firstTokenId, secondTokenId], + [firstTokenValue, secondTokenValue], + '0x', + { from: proxy }, + ); + }); + + batchTransferWasSuccessful.call(this, { + operator: proxy, + from: multiTokenHolder, + ids: [firstTokenId, secondTokenId], + values: [firstTokenValue, secondTokenValue], + }); + + it("preserves operator's balances not involved in the transfer", async function () { + const balance1 = await this.token.balanceOf(proxy, firstTokenId); + expect(balance1).to.be.a.bignumber.equal('0'); + const balance2 = await this.token.balanceOf(proxy, secondTokenId); + expect(balance2).to.be.a.bignumber.equal('0'); + }); + }); + }); + + context('when sending to a valid receiver', function () { + beforeEach(async function () { + this.receiver = await ERC1155ReceiverMock.new( + RECEIVER_SINGLE_MAGIC_VALUE, + RECEIVER_BATCH_MAGIC_VALUE, + RevertType.None, + ); + }); + + context('without data', function () { + beforeEach(async function () { + this.toWhom = this.receiver.address; + this.transferReceipt = await this.token.safeBatchTransferFrom( + multiTokenHolder, + this.receiver.address, + [firstTokenId, secondTokenId], + [firstTokenValue, secondTokenValue], + '0x', + { from: multiTokenHolder }, + ); + this.transferLogs = this.transferReceipt; + }); + + batchTransferWasSuccessful.call(this, { + operator: multiTokenHolder, + from: multiTokenHolder, + ids: [firstTokenId, secondTokenId], + values: [firstTokenValue, secondTokenValue], + }); + + it('calls onERC1155BatchReceived', async function () { + await expectEvent.inTransaction(this.transferReceipt.tx, ERC1155ReceiverMock, 'BatchReceived', { + operator: multiTokenHolder, + from: multiTokenHolder, + // ids: [firstTokenId, secondTokenId], + // values: [firstTokenValue, secondTokenValue], + data: null, + }); + }); + }); + + context('with data', function () { + const data = '0xf00dd00d'; + beforeEach(async function () { + this.toWhom = this.receiver.address; + this.transferReceipt = await this.token.safeBatchTransferFrom( + multiTokenHolder, + this.receiver.address, + [firstTokenId, secondTokenId], + [firstTokenValue, secondTokenValue], + data, + { from: multiTokenHolder }, + ); + this.transferLogs = this.transferReceipt; + }); + + batchTransferWasSuccessful.call(this, { + operator: multiTokenHolder, + from: multiTokenHolder, + ids: [firstTokenId, secondTokenId], + values: [firstTokenValue, secondTokenValue], + }); + + it('calls onERC1155Received', async function () { + await expectEvent.inTransaction(this.transferReceipt.tx, ERC1155ReceiverMock, 'BatchReceived', { + operator: multiTokenHolder, + from: multiTokenHolder, + // ids: [firstTokenId, secondTokenId], + // values: [firstTokenValue, secondTokenValue], + data, + }); + }); + }); + }); + + context('to a receiver contract returning unexpected value', function () { + beforeEach(async function () { + this.receiver = await ERC1155ReceiverMock.new( + RECEIVER_SINGLE_MAGIC_VALUE, + RECEIVER_SINGLE_MAGIC_VALUE, + RevertType.None, + ); + }); + + it('reverts', async function () { + await expectRevertCustomError( + this.token.safeBatchTransferFrom( + multiTokenHolder, + this.receiver.address, + [firstTokenId, secondTokenId], + [firstTokenValue, secondTokenValue], + '0x', + { from: multiTokenHolder }, + ), + 'ERC1155InvalidReceiver', + [this.receiver.address], + ); + }); + }); + + context('to a receiver contract that reverts', function () { + context('with a revert string', function () { + beforeEach(async function () { + this.receiver = await ERC1155ReceiverMock.new( + RECEIVER_SINGLE_MAGIC_VALUE, + RECEIVER_BATCH_MAGIC_VALUE, + RevertType.RevertWithMessage, + ); + }); + + it('reverts', async function () { + await expectRevert( + this.token.safeBatchTransferFrom( + multiTokenHolder, + this.receiver.address, + [firstTokenId, secondTokenId], + [firstTokenValue, secondTokenValue], + '0x', + { from: multiTokenHolder }, + ), + 'ERC1155ReceiverMock: reverting on batch receive', + ); + }); + }); + + context('without a revert string', function () { + beforeEach(async function () { + this.receiver = await ERC1155ReceiverMock.new( + RECEIVER_SINGLE_MAGIC_VALUE, + RECEIVER_BATCH_MAGIC_VALUE, + RevertType.RevertWithoutMessage, + ); + }); + + it('reverts', async function () { + await expectRevertCustomError( + this.token.safeBatchTransferFrom( + multiTokenHolder, + this.receiver.address, + [firstTokenId, secondTokenId], + [firstTokenValue, secondTokenValue], + '0x', + { from: multiTokenHolder }, + ), + 'ERC1155InvalidReceiver', + [this.receiver.address], + ); + }); + }); + + context('with a custom error', function () { + beforeEach(async function () { + this.receiver = await ERC1155ReceiverMock.new( + RECEIVER_SINGLE_MAGIC_VALUE, + RECEIVER_BATCH_MAGIC_VALUE, + RevertType.RevertWithCustomError, + ); + }); + + it('reverts', async function () { + await expectRevertCustomError( + this.token.safeBatchTransferFrom( + multiTokenHolder, + this.receiver.address, + [firstTokenId, secondTokenId], + [firstTokenValue, secondTokenValue], + '0x', + { from: multiTokenHolder }, + ), + 'CustomError', + [RECEIVER_SINGLE_MAGIC_VALUE], + ); + }); + }); + + context('with a panic', function () { + beforeEach(async function () { + this.receiver = await ERC1155ReceiverMock.new( + RECEIVER_SINGLE_MAGIC_VALUE, + RECEIVER_BATCH_MAGIC_VALUE, + RevertType.Panic, + ); + }); + + it('reverts', async function () { + await expectRevert.unspecified( + this.token.safeBatchTransferFrom( + multiTokenHolder, + this.receiver.address, + [firstTokenId, secondTokenId], + [firstTokenValue, secondTokenValue], + '0x', + { from: multiTokenHolder }, + ), + ); + }); + }); + }); + + context('to a contract that does not implement the required function', function () { + it('reverts', async function () { + const invalidReceiver = this.token; + await expectRevert.unspecified( + this.token.safeBatchTransferFrom( + multiTokenHolder, + invalidReceiver.address, + [firstTokenId, secondTokenId], + [firstTokenValue, secondTokenValue], + '0x', + { from: multiTokenHolder }, + ), + ); + }); + }); + }); + + shouldSupportInterfaces(['ERC165', 'ERC1155']); + }); +} + +module.exports = { + shouldBehaveLikeERC1155, +}; diff --git a/test/token/ERC1155/ERC1155.test.js b/test/token/ERC1155/ERC1155.test.js new file mode 100644 index 000000000..58d747a4b --- /dev/null +++ b/test/token/ERC1155/ERC1155.test.js @@ -0,0 +1,252 @@ +const { BN, constants, expectEvent } = require('@openzeppelin/test-helpers'); +const { ZERO_ADDRESS } = constants; + +const { expect } = require('chai'); + +const { expectRevertCustomError } = require('../../helpers/customError'); + +const { shouldBehaveLikeERC1155 } = require('./ERC1155.behavior'); +const ERC1155Mock = artifacts.require('$ERC1155'); + +contract('ERC1155', function (accounts) { + const [operator, tokenHolder, tokenBatchHolder, ...otherAccounts] = accounts; + + const initialURI = 'https://token-cdn-domain/{id}.json'; + + beforeEach(async function () { + this.token = await ERC1155Mock.new(initialURI); + }); + + shouldBehaveLikeERC1155(otherAccounts); + + describe('internal functions', function () { + const tokenId = new BN(1990); + const mintValue = new BN(9001); + const burnValue = new BN(3000); + + const tokenBatchIds = [new BN(2000), new BN(2010), new BN(2020)]; + const mintValues = [new BN(5000), new BN(10000), new BN(42195)]; + const burnValues = [new BN(5000), new BN(9001), new BN(195)]; + + const data = '0x12345678'; + + describe('_mint', function () { + it('reverts with a zero destination address', async function () { + await expectRevertCustomError( + this.token.$_mint(ZERO_ADDRESS, tokenId, mintValue, data), + 'ERC1155InvalidReceiver', + [ZERO_ADDRESS], + ); + }); + + context('with minted tokens', function () { + beforeEach(async function () { + this.receipt = await this.token.$_mint(tokenHolder, tokenId, mintValue, data, { from: operator }); + }); + + it('emits a TransferSingle event', function () { + expectEvent(this.receipt, 'TransferSingle', { + operator, + from: ZERO_ADDRESS, + to: tokenHolder, + id: tokenId, + value: mintValue, + }); + }); + + it('credits the minted token value', async function () { + expect(await this.token.balanceOf(tokenHolder, tokenId)).to.be.bignumber.equal(mintValue); + }); + }); + }); + + describe('_mintBatch', function () { + it('reverts with a zero destination address', async function () { + await expectRevertCustomError( + this.token.$_mintBatch(ZERO_ADDRESS, tokenBatchIds, mintValues, data), + 'ERC1155InvalidReceiver', + [ZERO_ADDRESS], + ); + }); + + it('reverts if length of inputs do not match', async function () { + await expectRevertCustomError( + this.token.$_mintBatch(tokenBatchHolder, tokenBatchIds, mintValues.slice(1), data), + 'ERC1155InvalidArrayLength', + [tokenBatchIds.length, mintValues.length - 1], + ); + + await expectRevertCustomError( + this.token.$_mintBatch(tokenBatchHolder, tokenBatchIds.slice(1), mintValues, data), + 'ERC1155InvalidArrayLength', + [tokenBatchIds.length - 1, mintValues.length], + ); + }); + + context('with minted batch of tokens', function () { + beforeEach(async function () { + this.receipt = await this.token.$_mintBatch(tokenBatchHolder, tokenBatchIds, mintValues, data, { + from: operator, + }); + }); + + it('emits a TransferBatch event', function () { + expectEvent(this.receipt, 'TransferBatch', { + operator, + from: ZERO_ADDRESS, + to: tokenBatchHolder, + }); + }); + + it('credits the minted batch of tokens', async function () { + const holderBatchBalances = await this.token.balanceOfBatch( + new Array(tokenBatchIds.length).fill(tokenBatchHolder), + tokenBatchIds, + ); + + for (let i = 0; i < holderBatchBalances.length; i++) { + expect(holderBatchBalances[i]).to.be.bignumber.equal(mintValues[i]); + } + }); + }); + }); + + describe('_burn', function () { + it("reverts when burning the zero account's tokens", async function () { + await expectRevertCustomError(this.token.$_burn(ZERO_ADDRESS, tokenId, mintValue), 'ERC1155InvalidSender', [ + ZERO_ADDRESS, + ]); + }); + + it('reverts when burning a non-existent token id', async function () { + await expectRevertCustomError( + this.token.$_burn(tokenHolder, tokenId, mintValue), + 'ERC1155InsufficientBalance', + [tokenHolder, 0, mintValue, tokenId], + ); + }); + + it('reverts when burning more than available tokens', async function () { + await this.token.$_mint(tokenHolder, tokenId, mintValue, data, { from: operator }); + + await expectRevertCustomError( + this.token.$_burn(tokenHolder, tokenId, mintValue.addn(1)), + 'ERC1155InsufficientBalance', + [tokenHolder, mintValue, mintValue.addn(1), tokenId], + ); + }); + + context('with minted-then-burnt tokens', function () { + beforeEach(async function () { + await this.token.$_mint(tokenHolder, tokenId, mintValue, data); + this.receipt = await this.token.$_burn(tokenHolder, tokenId, burnValue, { from: operator }); + }); + + it('emits a TransferSingle event', function () { + expectEvent(this.receipt, 'TransferSingle', { + operator, + from: tokenHolder, + to: ZERO_ADDRESS, + id: tokenId, + value: burnValue, + }); + }); + + it('accounts for both minting and burning', async function () { + expect(await this.token.balanceOf(tokenHolder, tokenId)).to.be.bignumber.equal(mintValue.sub(burnValue)); + }); + }); + }); + + describe('_burnBatch', function () { + it("reverts when burning the zero account's tokens", async function () { + await expectRevertCustomError( + this.token.$_burnBatch(ZERO_ADDRESS, tokenBatchIds, burnValues), + 'ERC1155InvalidSender', + [ZERO_ADDRESS], + ); + }); + + it('reverts if length of inputs do not match', async function () { + await expectRevertCustomError( + this.token.$_burnBatch(tokenBatchHolder, tokenBatchIds, burnValues.slice(1)), + 'ERC1155InvalidArrayLength', + [tokenBatchIds.length, burnValues.length - 1], + ); + + await expectRevertCustomError( + this.token.$_burnBatch(tokenBatchHolder, tokenBatchIds.slice(1), burnValues), + 'ERC1155InvalidArrayLength', + [tokenBatchIds.length - 1, burnValues.length], + ); + }); + + it('reverts when burning a non-existent token id', async function () { + await expectRevertCustomError( + this.token.$_burnBatch(tokenBatchHolder, tokenBatchIds, burnValues), + 'ERC1155InsufficientBalance', + [tokenBatchHolder, 0, tokenBatchIds[0], burnValues[0]], + ); + }); + + context('with minted-then-burnt tokens', function () { + beforeEach(async function () { + await this.token.$_mintBatch(tokenBatchHolder, tokenBatchIds, mintValues, data); + this.receipt = await this.token.$_burnBatch(tokenBatchHolder, tokenBatchIds, burnValues, { from: operator }); + }); + + it('emits a TransferBatch event', function () { + expectEvent(this.receipt, 'TransferBatch', { + operator, + from: tokenBatchHolder, + to: ZERO_ADDRESS, + // ids: tokenBatchIds, + // values: burnValues, + }); + }); + + it('accounts for both minting and burning', async function () { + const holderBatchBalances = await this.token.balanceOfBatch( + new Array(tokenBatchIds.length).fill(tokenBatchHolder), + tokenBatchIds, + ); + + for (let i = 0; i < holderBatchBalances.length; i++) { + expect(holderBatchBalances[i]).to.be.bignumber.equal(mintValues[i].sub(burnValues[i])); + } + }); + }); + }); + }); + + describe('ERC1155MetadataURI', function () { + const firstTokenID = new BN('42'); + const secondTokenID = new BN('1337'); + + it('emits no URI event in constructor', async function () { + await expectEvent.notEmitted.inConstruction(this.token, 'URI'); + }); + + it('sets the initial URI for all token types', async function () { + expect(await this.token.uri(firstTokenID)).to.be.equal(initialURI); + expect(await this.token.uri(secondTokenID)).to.be.equal(initialURI); + }); + + describe('_setURI', function () { + const newURI = 'https://token-cdn-domain/{locale}/{id}.json'; + + it('emits no URI event', async function () { + const receipt = await this.token.$_setURI(newURI); + + expectEvent.notEmitted(receipt, 'URI'); + }); + + it('sets the new URI for all token types', async function () { + await this.token.$_setURI(newURI); + + expect(await this.token.uri(firstTokenID)).to.be.equal(newURI); + expect(await this.token.uri(secondTokenID)).to.be.equal(newURI); + }); + }); + }); +}); diff --git a/test/token/ERC1155/extensions/ERC1155Burnable.test.js b/test/token/ERC1155/extensions/ERC1155Burnable.test.js new file mode 100644 index 000000000..fc94db052 --- /dev/null +++ b/test/token/ERC1155/extensions/ERC1155Burnable.test.js @@ -0,0 +1,71 @@ +const { BN } = require('@openzeppelin/test-helpers'); + +const { expect } = require('chai'); + +const { expectRevertCustomError } = require('../../../helpers/customError'); + +const ERC1155Burnable = artifacts.require('$ERC1155Burnable'); + +contract('ERC1155Burnable', function (accounts) { + const [holder, operator, other] = accounts; + + const uri = 'https://token.com'; + + const tokenIds = [new BN('42'), new BN('1137')]; + const values = [new BN('3000'), new BN('9902')]; + + beforeEach(async function () { + this.token = await ERC1155Burnable.new(uri); + + await this.token.$_mint(holder, tokenIds[0], values[0], '0x'); + await this.token.$_mint(holder, tokenIds[1], values[1], '0x'); + }); + + describe('burn', function () { + it('holder can burn their tokens', async function () { + await this.token.burn(holder, tokenIds[0], values[0].subn(1), { from: holder }); + + expect(await this.token.balanceOf(holder, tokenIds[0])).to.be.bignumber.equal('1'); + }); + + it("approved operators can burn the holder's tokens", async function () { + await this.token.setApprovalForAll(operator, true, { from: holder }); + await this.token.burn(holder, tokenIds[0], values[0].subn(1), { from: operator }); + + expect(await this.token.balanceOf(holder, tokenIds[0])).to.be.bignumber.equal('1'); + }); + + it("unapproved accounts cannot burn the holder's tokens", async function () { + await expectRevertCustomError( + this.token.burn(holder, tokenIds[0], values[0].subn(1), { from: other }), + 'ERC1155MissingApprovalForAll', + [other, holder], + ); + }); + }); + + describe('burnBatch', function () { + it('holder can burn their tokens', async function () { + await this.token.burnBatch(holder, tokenIds, [values[0].subn(1), values[1].subn(2)], { from: holder }); + + expect(await this.token.balanceOf(holder, tokenIds[0])).to.be.bignumber.equal('1'); + expect(await this.token.balanceOf(holder, tokenIds[1])).to.be.bignumber.equal('2'); + }); + + it("approved operators can burn the holder's tokens", async function () { + await this.token.setApprovalForAll(operator, true, { from: holder }); + await this.token.burnBatch(holder, tokenIds, [values[0].subn(1), values[1].subn(2)], { from: operator }); + + expect(await this.token.balanceOf(holder, tokenIds[0])).to.be.bignumber.equal('1'); + expect(await this.token.balanceOf(holder, tokenIds[1])).to.be.bignumber.equal('2'); + }); + + it("unapproved accounts cannot burn the holder's tokens", async function () { + await expectRevertCustomError( + this.token.burnBatch(holder, tokenIds, [values[0].subn(1), values[1].subn(2)], { from: other }), + 'ERC1155MissingApprovalForAll', + [other, holder], + ); + }); + }); +}); diff --git a/test/token/ERC1155/extensions/ERC1155Pausable.test.js b/test/token/ERC1155/extensions/ERC1155Pausable.test.js new file mode 100644 index 000000000..248ea5684 --- /dev/null +++ b/test/token/ERC1155/extensions/ERC1155Pausable.test.js @@ -0,0 +1,113 @@ +const { BN } = require('@openzeppelin/test-helpers'); + +const { expect } = require('chai'); +const { expectRevertCustomError } = require('../../../helpers/customError'); + +const ERC1155Pausable = artifacts.require('$ERC1155Pausable'); + +contract('ERC1155Pausable', function (accounts) { + const [holder, operator, receiver, other] = accounts; + + const uri = 'https://token.com'; + + beforeEach(async function () { + this.token = await ERC1155Pausable.new(uri); + }); + + context('when token is paused', function () { + const firstTokenId = new BN('37'); + const firstTokenValue = new BN('42'); + + const secondTokenId = new BN('19842'); + const secondTokenValue = new BN('23'); + + beforeEach(async function () { + await this.token.setApprovalForAll(operator, true, { from: holder }); + await this.token.$_mint(holder, firstTokenId, firstTokenValue, '0x'); + + await this.token.$_pause(); + }); + + it('reverts when trying to safeTransferFrom from holder', async function () { + await expectRevertCustomError( + this.token.safeTransferFrom(holder, receiver, firstTokenId, firstTokenValue, '0x', { from: holder }), + 'EnforcedPause', + [], + ); + }); + + it('reverts when trying to safeTransferFrom from operator', async function () { + await expectRevertCustomError( + this.token.safeTransferFrom(holder, receiver, firstTokenId, firstTokenValue, '0x', { from: operator }), + 'EnforcedPause', + [], + ); + }); + + it('reverts when trying to safeBatchTransferFrom from holder', async function () { + await expectRevertCustomError( + this.token.safeBatchTransferFrom(holder, receiver, [firstTokenId], [firstTokenValue], '0x', { from: holder }), + 'EnforcedPause', + [], + ); + }); + + it('reverts when trying to safeBatchTransferFrom from operator', async function () { + await expectRevertCustomError( + this.token.safeBatchTransferFrom(holder, receiver, [firstTokenId], [firstTokenValue], '0x', { + from: operator, + }), + 'EnforcedPause', + [], + ); + }); + + it('reverts when trying to mint', async function () { + await expectRevertCustomError( + this.token.$_mint(holder, secondTokenId, secondTokenValue, '0x'), + 'EnforcedPause', + [], + ); + }); + + it('reverts when trying to mintBatch', async function () { + await expectRevertCustomError( + this.token.$_mintBatch(holder, [secondTokenId], [secondTokenValue], '0x'), + 'EnforcedPause', + [], + ); + }); + + it('reverts when trying to burn', async function () { + await expectRevertCustomError(this.token.$_burn(holder, firstTokenId, firstTokenValue), 'EnforcedPause', []); + }); + + it('reverts when trying to burnBatch', async function () { + await expectRevertCustomError( + this.token.$_burnBatch(holder, [firstTokenId], [firstTokenValue]), + 'EnforcedPause', + [], + ); + }); + + describe('setApprovalForAll', function () { + it('approves an operator', async function () { + await this.token.setApprovalForAll(other, true, { from: holder }); + expect(await this.token.isApprovedForAll(holder, other)).to.equal(true); + }); + }); + + describe('balanceOf', function () { + it('returns the token value owned by the given address', async function () { + const balance = await this.token.balanceOf(holder, firstTokenId); + expect(balance).to.be.bignumber.equal(firstTokenValue); + }); + }); + + describe('isApprovedForAll', function () { + it('returns the approval of the operator', async function () { + expect(await this.token.isApprovedForAll(holder, operator)).to.equal(true); + }); + }); + }); +}); diff --git a/test/token/ERC1155/extensions/ERC1155Supply.test.js b/test/token/ERC1155/extensions/ERC1155Supply.test.js new file mode 100644 index 000000000..bf86920f6 --- /dev/null +++ b/test/token/ERC1155/extensions/ERC1155Supply.test.js @@ -0,0 +1,116 @@ +const { BN, constants } = require('@openzeppelin/test-helpers'); + +const { expect } = require('chai'); + +const { ZERO_ADDRESS } = constants; + +const ERC1155Supply = artifacts.require('$ERC1155Supply'); + +contract('ERC1155Supply', function (accounts) { + const [holder] = accounts; + + const uri = 'https://token.com'; + + const firstTokenId = new BN('37'); + const firstTokenValue = new BN('42'); + + const secondTokenId = new BN('19842'); + const secondTokenValue = new BN('23'); + + beforeEach(async function () { + this.token = await ERC1155Supply.new(uri); + }); + + context('before mint', function () { + it('exist', async function () { + expect(await this.token.exists(firstTokenId)).to.be.equal(false); + }); + + it('totalSupply', async function () { + expect(await this.token.methods['totalSupply(uint256)'](firstTokenId)).to.be.bignumber.equal('0'); + expect(await this.token.methods['totalSupply()']()).to.be.bignumber.equal('0'); + }); + }); + + context('after mint', function () { + context('single', function () { + beforeEach(async function () { + await this.token.$_mint(holder, firstTokenId, firstTokenValue, '0x'); + }); + + it('exist', async function () { + expect(await this.token.exists(firstTokenId)).to.be.equal(true); + }); + + it('totalSupply', async function () { + expect(await this.token.methods['totalSupply(uint256)'](firstTokenId)).to.be.bignumber.equal(firstTokenValue); + expect(await this.token.methods['totalSupply()']()).to.be.bignumber.equal(firstTokenValue); + }); + }); + + context('batch', function () { + beforeEach(async function () { + await this.token.$_mintBatch(holder, [firstTokenId, secondTokenId], [firstTokenValue, secondTokenValue], '0x'); + }); + + it('exist', async function () { + expect(await this.token.exists(firstTokenId)).to.be.equal(true); + expect(await this.token.exists(secondTokenId)).to.be.equal(true); + }); + + it('totalSupply', async function () { + expect(await this.token.methods['totalSupply(uint256)'](firstTokenId)).to.be.bignumber.equal(firstTokenValue); + expect(await this.token.methods['totalSupply(uint256)'](secondTokenId)).to.be.bignumber.equal(secondTokenValue); + expect(await this.token.methods['totalSupply()']()).to.be.bignumber.equal( + firstTokenValue.add(secondTokenValue), + ); + }); + }); + }); + + context('after burn', function () { + context('single', function () { + beforeEach(async function () { + await this.token.$_mint(holder, firstTokenId, firstTokenValue, '0x'); + await this.token.$_burn(holder, firstTokenId, firstTokenValue); + }); + + it('exist', async function () { + expect(await this.token.exists(firstTokenId)).to.be.equal(false); + }); + + it('totalSupply', async function () { + expect(await this.token.methods['totalSupply(uint256)'](firstTokenId)).to.be.bignumber.equal('0'); + expect(await this.token.methods['totalSupply()']()).to.be.bignumber.equal('0'); + }); + }); + + context('batch', function () { + beforeEach(async function () { + await this.token.$_mintBatch(holder, [firstTokenId, secondTokenId], [firstTokenValue, secondTokenValue], '0x'); + await this.token.$_burnBatch(holder, [firstTokenId, secondTokenId], [firstTokenValue, secondTokenValue]); + }); + + it('exist', async function () { + expect(await this.token.exists(firstTokenId)).to.be.equal(false); + expect(await this.token.exists(secondTokenId)).to.be.equal(false); + }); + + it('totalSupply', async function () { + expect(await this.token.methods['totalSupply(uint256)'](firstTokenId)).to.be.bignumber.equal('0'); + expect(await this.token.methods['totalSupply(uint256)'](secondTokenId)).to.be.bignumber.equal('0'); + expect(await this.token.methods['totalSupply()']()).to.be.bignumber.equal('0'); + }); + }); + }); + + context('other', function () { + it('supply unaffected by no-op', async function () { + this.token.safeTransferFrom(ZERO_ADDRESS, ZERO_ADDRESS, firstTokenId, firstTokenValue, '0x', { + from: ZERO_ADDRESS, + }); + expect(await this.token.methods['totalSupply(uint256)'](firstTokenId)).to.be.bignumber.equal('0'); + expect(await this.token.methods['totalSupply()']()).to.be.bignumber.equal('0'); + }); + }); +}); diff --git a/test/token/ERC1155/extensions/ERC1155URIStorage.test.js b/test/token/ERC1155/extensions/ERC1155URIStorage.test.js new file mode 100644 index 000000000..58ac67bc6 --- /dev/null +++ b/test/token/ERC1155/extensions/ERC1155URIStorage.test.js @@ -0,0 +1,66 @@ +const { BN, expectEvent } = require('@openzeppelin/test-helpers'); + +const { expect } = require('chai'); +const { artifacts } = require('hardhat'); + +const ERC1155URIStorage = artifacts.require('$ERC1155URIStorage'); + +contract(['ERC1155URIStorage'], function (accounts) { + const [holder] = accounts; + + const erc1155Uri = 'https://token.com/nfts/'; + const baseUri = 'https://token.com/'; + + const tokenId = new BN('1'); + const value = new BN('3000'); + + describe('with base uri set', function () { + beforeEach(async function () { + this.token = await ERC1155URIStorage.new(erc1155Uri); + await this.token.$_setBaseURI(baseUri); + + await this.token.$_mint(holder, tokenId, value, '0x'); + }); + + it('can request the token uri, returning the erc1155 uri if no token uri was set', async function () { + const receivedTokenUri = await this.token.uri(tokenId); + + expect(receivedTokenUri).to.be.equal(erc1155Uri); + }); + + it('can request the token uri, returning the concatenated uri if a token uri was set', async function () { + const tokenUri = '1234/'; + const receipt = await this.token.$_setURI(tokenId, tokenUri); + + const receivedTokenUri = await this.token.uri(tokenId); + + const expectedUri = `${baseUri}${tokenUri}`; + expect(receivedTokenUri).to.be.equal(expectedUri); + expectEvent(receipt, 'URI', { value: expectedUri, id: tokenId }); + }); + }); + + describe('with base uri set to the empty string', function () { + beforeEach(async function () { + this.token = await ERC1155URIStorage.new(''); + + await this.token.$_mint(holder, tokenId, value, '0x'); + }); + + it('can request the token uri, returning an empty string if no token uri was set', async function () { + const receivedTokenUri = await this.token.uri(tokenId); + + expect(receivedTokenUri).to.be.equal(''); + }); + + it('can request the token uri, returning the token uri if a token uri was set', async function () { + const tokenUri = 'ipfs://1234/'; + const receipt = await this.token.$_setURI(tokenId, tokenUri); + + const receivedTokenUri = await this.token.uri(tokenId); + + expect(receivedTokenUri).to.be.equal(tokenUri); + expectEvent(receipt, 'URI', { value: tokenUri, id: tokenId }); + }); + }); +}); diff --git a/test/token/ERC1155/utils/ERC1155Holder.test.js b/test/token/ERC1155/utils/ERC1155Holder.test.js new file mode 100644 index 000000000..ee818eae8 --- /dev/null +++ b/test/token/ERC1155/utils/ERC1155Holder.test.js @@ -0,0 +1,64 @@ +const { BN } = require('@openzeppelin/test-helpers'); + +const ERC1155Holder = artifacts.require('$ERC1155Holder'); +const ERC1155 = artifacts.require('$ERC1155'); + +const { expect } = require('chai'); + +const { shouldSupportInterfaces } = require('../../../utils/introspection/SupportsInterface.behavior'); + +contract('ERC1155Holder', function (accounts) { + const [creator] = accounts; + const uri = 'https://token-cdn-domain/{id}.json'; + const multiTokenIds = [new BN(1), new BN(2), new BN(3)]; + const multiTokenValues = [new BN(1000), new BN(2000), new BN(3000)]; + const transferData = '0x12345678'; + + beforeEach(async function () { + this.multiToken = await ERC1155.new(uri); + this.holder = await ERC1155Holder.new(); + await this.multiToken.$_mintBatch(creator, multiTokenIds, multiTokenValues, '0x'); + }); + + shouldSupportInterfaces(['ERC165', 'ERC1155Receiver']); + + it('receives ERC1155 tokens from a single ID', async function () { + await this.multiToken.safeTransferFrom( + creator, + this.holder.address, + multiTokenIds[0], + multiTokenValues[0], + transferData, + { from: creator }, + ); + + expect(await this.multiToken.balanceOf(this.holder.address, multiTokenIds[0])).to.be.bignumber.equal( + multiTokenValues[0], + ); + + for (let i = 1; i < multiTokenIds.length; i++) { + expect(await this.multiToken.balanceOf(this.holder.address, multiTokenIds[i])).to.be.bignumber.equal(new BN(0)); + } + }); + + it('receives ERC1155 tokens from a multiple IDs', async function () { + for (let i = 0; i < multiTokenIds.length; i++) { + expect(await this.multiToken.balanceOf(this.holder.address, multiTokenIds[i])).to.be.bignumber.equal(new BN(0)); + } + + await this.multiToken.safeBatchTransferFrom( + creator, + this.holder.address, + multiTokenIds, + multiTokenValues, + transferData, + { from: creator }, + ); + + for (let i = 0; i < multiTokenIds.length; i++) { + expect(await this.multiToken.balanceOf(this.holder.address, multiTokenIds[i])).to.be.bignumber.equal( + multiTokenValues[i], + ); + } + }); +}); diff --git a/test/token/ERC20/ERC20.behavior.js b/test/token/ERC20/ERC20.behavior.js new file mode 100644 index 000000000..b6f8617b2 --- /dev/null +++ b/test/token/ERC20/ERC20.behavior.js @@ -0,0 +1,340 @@ +const { BN, constants, expectEvent } = require('@openzeppelin/test-helpers'); +const { expect } = require('chai'); +const { ZERO_ADDRESS, MAX_UINT256 } = constants; + +const { expectRevertCustomError } = require('../../helpers/customError'); + +function shouldBehaveLikeERC20(initialSupply, accounts, opts = {}) { + const [initialHolder, recipient, anotherAccount] = accounts; + const { forcedApproval } = opts; + + describe('total supply', function () { + it('returns the total token value', async function () { + expect(await this.token.totalSupply()).to.be.bignumber.equal(initialSupply); + }); + }); + + describe('balanceOf', function () { + describe('when the requested account has no tokens', function () { + it('returns zero', async function () { + expect(await this.token.balanceOf(anotherAccount)).to.be.bignumber.equal('0'); + }); + }); + + describe('when the requested account has some tokens', function () { + it('returns the total token value', async function () { + expect(await this.token.balanceOf(initialHolder)).to.be.bignumber.equal(initialSupply); + }); + }); + }); + + describe('transfer', function () { + shouldBehaveLikeERC20Transfer(initialHolder, recipient, initialSupply, function (from, to, value) { + return this.token.transfer(to, value, { from }); + }); + }); + + describe('transfer from', function () { + const spender = recipient; + + describe('when the token owner is not the zero address', function () { + const tokenOwner = initialHolder; + + describe('when the recipient is not the zero address', function () { + const to = anotherAccount; + + describe('when the spender has enough allowance', function () { + beforeEach(async function () { + await this.token.approve(spender, initialSupply, { from: initialHolder }); + }); + + describe('when the token owner has enough balance', function () { + const value = initialSupply; + + it('transfers the requested value', async function () { + await this.token.transferFrom(tokenOwner, to, value, { from: spender }); + + expect(await this.token.balanceOf(tokenOwner)).to.be.bignumber.equal('0'); + + expect(await this.token.balanceOf(to)).to.be.bignumber.equal(value); + }); + + it('decreases the spender allowance', async function () { + await this.token.transferFrom(tokenOwner, to, value, { from: spender }); + + expect(await this.token.allowance(tokenOwner, spender)).to.be.bignumber.equal('0'); + }); + + it('emits a transfer event', async function () { + expectEvent(await this.token.transferFrom(tokenOwner, to, value, { from: spender }), 'Transfer', { + from: tokenOwner, + to: to, + value: value, + }); + }); + + if (forcedApproval) { + it('emits an approval event', async function () { + expectEvent(await this.token.transferFrom(tokenOwner, to, value, { from: spender }), 'Approval', { + owner: tokenOwner, + spender: spender, + value: await this.token.allowance(tokenOwner, spender), + }); + }); + } else { + it('does not emit an approval event', async function () { + expectEvent.notEmitted( + await this.token.transferFrom(tokenOwner, to, value, { from: spender }), + 'Approval', + ); + }); + } + }); + + describe('when the token owner does not have enough balance', function () { + const value = initialSupply; + + beforeEach('reducing balance', async function () { + await this.token.transfer(to, 1, { from: tokenOwner }); + }); + + it('reverts', async function () { + await expectRevertCustomError( + this.token.transferFrom(tokenOwner, to, value, { from: spender }), + 'ERC20InsufficientBalance', + [tokenOwner, value - 1, value], + ); + }); + }); + }); + + describe('when the spender does not have enough allowance', function () { + const allowance = initialSupply.subn(1); + + beforeEach(async function () { + await this.token.approve(spender, allowance, { from: tokenOwner }); + }); + + describe('when the token owner has enough balance', function () { + const value = initialSupply; + + it('reverts', async function () { + await expectRevertCustomError( + this.token.transferFrom(tokenOwner, to, value, { from: spender }), + 'ERC20InsufficientAllowance', + [spender, allowance, value], + ); + }); + }); + + describe('when the token owner does not have enough balance', function () { + const value = allowance; + + beforeEach('reducing balance', async function () { + await this.token.transfer(to, 2, { from: tokenOwner }); + }); + + it('reverts', async function () { + await expectRevertCustomError( + this.token.transferFrom(tokenOwner, to, value, { from: spender }), + 'ERC20InsufficientBalance', + [tokenOwner, value - 1, value], + ); + }); + }); + }); + + describe('when the spender has unlimited allowance', function () { + beforeEach(async function () { + await this.token.approve(spender, MAX_UINT256, { from: initialHolder }); + }); + + it('does not decrease the spender allowance', async function () { + await this.token.transferFrom(tokenOwner, to, 1, { from: spender }); + + expect(await this.token.allowance(tokenOwner, spender)).to.be.bignumber.equal(MAX_UINT256); + }); + + it('does not emit an approval event', async function () { + expectEvent.notEmitted(await this.token.transferFrom(tokenOwner, to, 1, { from: spender }), 'Approval'); + }); + }); + }); + + describe('when the recipient is the zero address', function () { + const value = initialSupply; + const to = ZERO_ADDRESS; + + beforeEach(async function () { + await this.token.approve(spender, value, { from: tokenOwner }); + }); + + it('reverts', async function () { + await expectRevertCustomError( + this.token.transferFrom(tokenOwner, to, value, { from: spender }), + 'ERC20InvalidReceiver', + [ZERO_ADDRESS], + ); + }); + }); + }); + + describe('when the token owner is the zero address', function () { + const value = 0; + const tokenOwner = ZERO_ADDRESS; + const to = recipient; + + it('reverts', async function () { + await expectRevertCustomError( + this.token.transferFrom(tokenOwner, to, value, { from: spender }), + 'ERC20InvalidApprover', + [ZERO_ADDRESS], + ); + }); + }); + }); + + describe('approve', function () { + shouldBehaveLikeERC20Approve(initialHolder, recipient, initialSupply, function (owner, spender, value) { + return this.token.approve(spender, value, { from: owner }); + }); + }); +} + +function shouldBehaveLikeERC20Transfer(from, to, balance, transfer) { + describe('when the recipient is not the zero address', function () { + describe('when the sender does not have enough balance', function () { + const value = balance.addn(1); + + it('reverts', async function () { + await expectRevertCustomError(transfer.call(this, from, to, value), 'ERC20InsufficientBalance', [ + from, + balance, + value, + ]); + }); + }); + + describe('when the sender transfers all balance', function () { + const value = balance; + + it('transfers the requested value', async function () { + await transfer.call(this, from, to, value); + + expect(await this.token.balanceOf(from)).to.be.bignumber.equal('0'); + + expect(await this.token.balanceOf(to)).to.be.bignumber.equal(value); + }); + + it('emits a transfer event', async function () { + expectEvent(await transfer.call(this, from, to, value), 'Transfer', { from, to, value: value }); + }); + }); + + describe('when the sender transfers zero tokens', function () { + const value = new BN('0'); + + it('transfers the requested value', async function () { + await transfer.call(this, from, to, value); + + expect(await this.token.balanceOf(from)).to.be.bignumber.equal(balance); + + expect(await this.token.balanceOf(to)).to.be.bignumber.equal('0'); + }); + + it('emits a transfer event', async function () { + expectEvent(await transfer.call(this, from, to, value), 'Transfer', { from, to, value: value }); + }); + }); + }); + + describe('when the recipient is the zero address', function () { + it('reverts', async function () { + await expectRevertCustomError(transfer.call(this, from, ZERO_ADDRESS, balance), 'ERC20InvalidReceiver', [ + ZERO_ADDRESS, + ]); + }); + }); +} + +function shouldBehaveLikeERC20Approve(owner, spender, supply, approve) { + describe('when the spender is not the zero address', function () { + describe('when the sender has enough balance', function () { + const value = supply; + + it('emits an approval event', async function () { + expectEvent(await approve.call(this, owner, spender, value), 'Approval', { + owner: owner, + spender: spender, + value: value, + }); + }); + + describe('when there was no approved value before', function () { + it('approves the requested value', async function () { + await approve.call(this, owner, spender, value); + + expect(await this.token.allowance(owner, spender)).to.be.bignumber.equal(value); + }); + }); + + describe('when the spender had an approved value', function () { + beforeEach(async function () { + await approve.call(this, owner, spender, new BN(1)); + }); + + it('approves the requested value and replaces the previous one', async function () { + await approve.call(this, owner, spender, value); + + expect(await this.token.allowance(owner, spender)).to.be.bignumber.equal(value); + }); + }); + }); + + describe('when the sender does not have enough balance', function () { + const value = supply.addn(1); + + it('emits an approval event', async function () { + expectEvent(await approve.call(this, owner, spender, value), 'Approval', { + owner: owner, + spender: spender, + value: value, + }); + }); + + describe('when there was no approved value before', function () { + it('approves the requested value', async function () { + await approve.call(this, owner, spender, value); + + expect(await this.token.allowance(owner, spender)).to.be.bignumber.equal(value); + }); + }); + + describe('when the spender had an approved value', function () { + beforeEach(async function () { + await approve.call(this, owner, spender, new BN(1)); + }); + + it('approves the requested value and replaces the previous one', async function () { + await approve.call(this, owner, spender, value); + + expect(await this.token.allowance(owner, spender)).to.be.bignumber.equal(value); + }); + }); + }); + }); + + describe('when the spender is the zero address', function () { + it('reverts', async function () { + await expectRevertCustomError(approve.call(this, owner, ZERO_ADDRESS, supply), `ERC20InvalidSpender`, [ + ZERO_ADDRESS, + ]); + }); + }); +} + +module.exports = { + shouldBehaveLikeERC20, + shouldBehaveLikeERC20Transfer, + shouldBehaveLikeERC20Approve, +}; diff --git a/test/token/ERC20/ERC20.test.js b/test/token/ERC20/ERC20.test.js new file mode 100644 index 000000000..2191fd8cb --- /dev/null +++ b/test/token/ERC20/ERC20.test.js @@ -0,0 +1,202 @@ +const { BN, constants, expectEvent, expectRevert } = require('@openzeppelin/test-helpers'); +const { expect } = require('chai'); +const { ZERO_ADDRESS } = constants; + +const { + shouldBehaveLikeERC20, + shouldBehaveLikeERC20Transfer, + shouldBehaveLikeERC20Approve, +} = require('./ERC20.behavior'); +const { expectRevertCustomError } = require('../../helpers/customError'); + +const TOKENS = [ + { Token: artifacts.require('$ERC20') }, + { Token: artifacts.require('$ERC20ApprovalMock'), forcedApproval: true }, +]; + +contract('ERC20', function (accounts) { + const [initialHolder, recipient] = accounts; + + const name = 'My Token'; + const symbol = 'MTKN'; + const initialSupply = new BN(100); + + for (const { Token, forcedApproval } of TOKENS) { + describe(`using ${Token._json.contractName}`, function () { + beforeEach(async function () { + this.token = await Token.new(name, symbol); + await this.token.$_mint(initialHolder, initialSupply); + }); + + shouldBehaveLikeERC20(initialSupply, accounts, { forcedApproval }); + + it('has a name', async function () { + expect(await this.token.name()).to.equal(name); + }); + + it('has a symbol', async function () { + expect(await this.token.symbol()).to.equal(symbol); + }); + + it('has 18 decimals', async function () { + expect(await this.token.decimals()).to.be.bignumber.equal('18'); + }); + + describe('_mint', function () { + const value = new BN(50); + it('rejects a null account', async function () { + await expectRevertCustomError(this.token.$_mint(ZERO_ADDRESS, value), 'ERC20InvalidReceiver', [ZERO_ADDRESS]); + }); + + it('rejects overflow', async function () { + const maxUint256 = new BN('2').pow(new BN(256)).subn(1); + await expectRevert( + this.token.$_mint(recipient, maxUint256), + 'reverted with panic code 0x11 (Arithmetic operation underflowed or overflowed outside of an unchecked block)', + ); + }); + + describe('for a non zero account', function () { + beforeEach('minting', async function () { + this.receipt = await this.token.$_mint(recipient, value); + }); + + it('increments totalSupply', async function () { + const expectedSupply = initialSupply.add(value); + expect(await this.token.totalSupply()).to.be.bignumber.equal(expectedSupply); + }); + + it('increments recipient balance', async function () { + expect(await this.token.balanceOf(recipient)).to.be.bignumber.equal(value); + }); + + it('emits Transfer event', async function () { + const event = expectEvent(this.receipt, 'Transfer', { from: ZERO_ADDRESS, to: recipient }); + + expect(event.args.value).to.be.bignumber.equal(value); + }); + }); + }); + + describe('_burn', function () { + it('rejects a null account', async function () { + await expectRevertCustomError(this.token.$_burn(ZERO_ADDRESS, new BN(1)), 'ERC20InvalidSender', [ + ZERO_ADDRESS, + ]); + }); + + describe('for a non zero account', function () { + it('rejects burning more than balance', async function () { + await expectRevertCustomError( + this.token.$_burn(initialHolder, initialSupply.addn(1)), + 'ERC20InsufficientBalance', + [initialHolder, initialSupply, initialSupply.addn(1)], + ); + }); + + const describeBurn = function (description, value) { + describe(description, function () { + beforeEach('burning', async function () { + this.receipt = await this.token.$_burn(initialHolder, value); + }); + + it('decrements totalSupply', async function () { + const expectedSupply = initialSupply.sub(value); + expect(await this.token.totalSupply()).to.be.bignumber.equal(expectedSupply); + }); + + it('decrements initialHolder balance', async function () { + const expectedBalance = initialSupply.sub(value); + expect(await this.token.balanceOf(initialHolder)).to.be.bignumber.equal(expectedBalance); + }); + + it('emits Transfer event', async function () { + const event = expectEvent(this.receipt, 'Transfer', { from: initialHolder, to: ZERO_ADDRESS }); + + expect(event.args.value).to.be.bignumber.equal(value); + }); + }); + }; + + describeBurn('for entire balance', initialSupply); + describeBurn('for less value than balance', initialSupply.subn(1)); + }); + }); + + describe('_update', function () { + const value = new BN(1); + + it('from is the zero address', async function () { + const balanceBefore = await this.token.balanceOf(initialHolder); + const totalSupply = await this.token.totalSupply(); + + expectEvent(await this.token.$_update(ZERO_ADDRESS, initialHolder, value), 'Transfer', { + from: ZERO_ADDRESS, + to: initialHolder, + value: value, + }); + expect(await this.token.totalSupply()).to.be.bignumber.equal(totalSupply.add(value)); + expect(await this.token.balanceOf(initialHolder)).to.be.bignumber.equal(balanceBefore.add(value)); + }); + + it('to is the zero address', async function () { + const balanceBefore = await this.token.balanceOf(initialHolder); + const totalSupply = await this.token.totalSupply(); + + expectEvent(await this.token.$_update(initialHolder, ZERO_ADDRESS, value), 'Transfer', { + from: initialHolder, + to: ZERO_ADDRESS, + value: value, + }); + expect(await this.token.totalSupply()).to.be.bignumber.equal(totalSupply.sub(value)); + expect(await this.token.balanceOf(initialHolder)).to.be.bignumber.equal(balanceBefore.sub(value)); + }); + + it('from and to are the zero address', async function () { + const totalSupply = await this.token.totalSupply(); + + await this.token.$_update(ZERO_ADDRESS, ZERO_ADDRESS, value); + + expect(await this.token.totalSupply()).to.be.bignumber.equal(totalSupply); + expectEvent(await this.token.$_update(ZERO_ADDRESS, ZERO_ADDRESS, value), 'Transfer', { + from: ZERO_ADDRESS, + to: ZERO_ADDRESS, + value: value, + }); + }); + }); + + describe('_transfer', function () { + shouldBehaveLikeERC20Transfer(initialHolder, recipient, initialSupply, function (from, to, value) { + return this.token.$_transfer(from, to, value); + }); + + describe('when the sender is the zero address', function () { + it('reverts', async function () { + await expectRevertCustomError( + this.token.$_transfer(ZERO_ADDRESS, recipient, initialSupply), + 'ERC20InvalidSender', + [ZERO_ADDRESS], + ); + }); + }); + }); + + describe('_approve', function () { + shouldBehaveLikeERC20Approve(initialHolder, recipient, initialSupply, function (owner, spender, value) { + return this.token.$_approve(owner, spender, value); + }); + + describe('when the owner is the zero address', function () { + it('reverts', async function () { + await expectRevertCustomError( + this.token.$_approve(ZERO_ADDRESS, recipient, initialSupply), + 'ERC20InvalidApprover', + [ZERO_ADDRESS], + ); + }); + }); + }); + }); + } +}); diff --git a/test/token/ERC20/extensions/ERC20Burnable.behavior.js b/test/token/ERC20/extensions/ERC20Burnable.behavior.js new file mode 100644 index 000000000..937491bdf --- /dev/null +++ b/test/token/ERC20/extensions/ERC20Burnable.behavior.js @@ -0,0 +1,116 @@ +const { BN, constants, expectEvent } = require('@openzeppelin/test-helpers'); +const { ZERO_ADDRESS } = constants; + +const { expect } = require('chai'); +const { expectRevertCustomError } = require('../../../helpers/customError'); + +function shouldBehaveLikeERC20Burnable(owner, initialBalance, [burner]) { + describe('burn', function () { + describe('when the given value is not greater than balance of the sender', function () { + context('for a zero value', function () { + shouldBurn(new BN(0)); + }); + + context('for a non-zero value', function () { + shouldBurn(new BN(100)); + }); + + function shouldBurn(value) { + beforeEach(async function () { + this.receipt = await this.token.burn(value, { from: owner }); + }); + + it('burns the requested value', async function () { + expect(await this.token.balanceOf(owner)).to.be.bignumber.equal(initialBalance.sub(value)); + }); + + it('emits a transfer event', async function () { + expectEvent(this.receipt, 'Transfer', { + from: owner, + to: ZERO_ADDRESS, + value: value, + }); + }); + } + }); + + describe('when the given value is greater than the balance of the sender', function () { + const value = initialBalance.addn(1); + + it('reverts', async function () { + await expectRevertCustomError(this.token.burn(value, { from: owner }), 'ERC20InsufficientBalance', [ + owner, + initialBalance, + value, + ]); + }); + }); + }); + + describe('burnFrom', function () { + describe('on success', function () { + context('for a zero value', function () { + shouldBurnFrom(new BN(0)); + }); + + context('for a non-zero value', function () { + shouldBurnFrom(new BN(100)); + }); + + function shouldBurnFrom(value) { + const originalAllowance = value.muln(3); + + beforeEach(async function () { + await this.token.approve(burner, originalAllowance, { from: owner }); + this.receipt = await this.token.burnFrom(owner, value, { from: burner }); + }); + + it('burns the requested value', async function () { + expect(await this.token.balanceOf(owner)).to.be.bignumber.equal(initialBalance.sub(value)); + }); + + it('decrements allowance', async function () { + expect(await this.token.allowance(owner, burner)).to.be.bignumber.equal(originalAllowance.sub(value)); + }); + + it('emits a transfer event', async function () { + expectEvent(this.receipt, 'Transfer', { + from: owner, + to: ZERO_ADDRESS, + value: value, + }); + }); + } + }); + + describe('when the given value is greater than the balance of the sender', function () { + const value = initialBalance.addn(1); + + it('reverts', async function () { + await this.token.approve(burner, value, { from: owner }); + await expectRevertCustomError(this.token.burnFrom(owner, value, { from: burner }), 'ERC20InsufficientBalance', [ + owner, + initialBalance, + value, + ]); + }); + }); + + describe('when the given value is greater than the allowance', function () { + const allowance = new BN(100); + + it('reverts', async function () { + await this.token.approve(burner, allowance, { from: owner }); + await expectRevertCustomError( + this.token.burnFrom(owner, allowance.addn(1), { from: burner }), + 'ERC20InsufficientAllowance', + [burner, allowance, allowance.addn(1)], + ); + }); + }); + }); +} + +module.exports = { + shouldBehaveLikeERC20Burnable, +}; diff --git a/test/token/ERC20/extensions/ERC20Burnable.test.js b/test/token/ERC20/extensions/ERC20Burnable.test.js new file mode 100644 index 000000000..00acc81ed --- /dev/null +++ b/test/token/ERC20/extensions/ERC20Burnable.test.js @@ -0,0 +1,20 @@ +const { BN } = require('@openzeppelin/test-helpers'); + +const { shouldBehaveLikeERC20Burnable } = require('./ERC20Burnable.behavior'); +const ERC20Burnable = artifacts.require('$ERC20Burnable'); + +contract('ERC20Burnable', function (accounts) { + const [owner, ...otherAccounts] = accounts; + + const initialBalance = new BN(1000); + + const name = 'My Token'; + const symbol = 'MTKN'; + + beforeEach(async function () { + this.token = await ERC20Burnable.new(name, symbol, { from: owner }); + await this.token.$_mint(owner, initialBalance); + }); + + shouldBehaveLikeERC20Burnable(owner, initialBalance, otherAccounts); +}); diff --git a/test/token/ERC20/extensions/ERC20Capped.behavior.js b/test/token/ERC20/extensions/ERC20Capped.behavior.js new file mode 100644 index 000000000..5af5c3ddc --- /dev/null +++ b/test/token/ERC20/extensions/ERC20Capped.behavior.js @@ -0,0 +1,31 @@ +const { expect } = require('chai'); +const { expectRevertCustomError } = require('../../../helpers/customError'); + +function shouldBehaveLikeERC20Capped(accounts, cap) { + describe('capped token', function () { + const user = accounts[0]; + + it('starts with the correct cap', async function () { + expect(await this.token.cap()).to.be.bignumber.equal(cap); + }); + + it('mints when value is less than cap', async function () { + await this.token.$_mint(user, cap.subn(1)); + expect(await this.token.totalSupply()).to.be.bignumber.equal(cap.subn(1)); + }); + + it('fails to mint if the value exceeds the cap', async function () { + await this.token.$_mint(user, cap.subn(1)); + await expectRevertCustomError(this.token.$_mint(user, 2), 'ERC20ExceededCap', [cap.addn(1), cap]); + }); + + it('fails to mint after cap is reached', async function () { + await this.token.$_mint(user, cap); + await expectRevertCustomError(this.token.$_mint(user, 1), 'ERC20ExceededCap', [cap.addn(1), cap]); + }); + }); +} + +module.exports = { + shouldBehaveLikeERC20Capped, +}; diff --git a/test/token/ERC20/extensions/ERC20Capped.test.js b/test/token/ERC20/extensions/ERC20Capped.test.js new file mode 100644 index 000000000..1f4a2bee3 --- /dev/null +++ b/test/token/ERC20/extensions/ERC20Capped.test.js @@ -0,0 +1,24 @@ +const { ether } = require('@openzeppelin/test-helpers'); +const { shouldBehaveLikeERC20Capped } = require('./ERC20Capped.behavior'); +const { expectRevertCustomError } = require('../../../helpers/customError'); + +const ERC20Capped = artifacts.require('$ERC20Capped'); + +contract('ERC20Capped', function (accounts) { + const cap = ether('1000'); + + const name = 'My Token'; + const symbol = 'MTKN'; + + it('requires a non-zero cap', async function () { + await expectRevertCustomError(ERC20Capped.new(name, symbol, 0), 'ERC20InvalidCap', [0]); + }); + + context('once deployed', async function () { + beforeEach(async function () { + this.token = await ERC20Capped.new(name, symbol, cap); + }); + + shouldBehaveLikeERC20Capped(accounts, cap); + }); +}); diff --git a/test/token/ERC20/extensions/ERC20FlashMint.test.js b/test/token/ERC20/extensions/ERC20FlashMint.test.js new file mode 100644 index 000000000..13d5b3ef4 --- /dev/null +++ b/test/token/ERC20/extensions/ERC20FlashMint.test.js @@ -0,0 +1,210 @@ +/* eslint-disable */ + +const { BN, constants, expectEvent, expectRevert } = require('@openzeppelin/test-helpers'); +const { expect } = require('chai'); +const { expectRevertCustomError } = require('../../../helpers/customError'); +const { MAX_UINT256, ZERO_ADDRESS } = constants; + +const ERC20FlashMintMock = artifacts.require('$ERC20FlashMintMock'); +const ERC3156FlashBorrowerMock = artifacts.require('ERC3156FlashBorrowerMock'); + +contract('ERC20FlashMint', function (accounts) { + const [initialHolder, other, anotherAccount] = accounts; + + const name = 'My Token'; + const symbol = 'MTKN'; + + const initialSupply = new BN(100); + const loanValue = new BN(10000000000000); + + beforeEach(async function () { + this.token = await ERC20FlashMintMock.new(name, symbol); + await this.token.$_mint(initialHolder, initialSupply); + }); + + describe('maxFlashLoan', function () { + it('token match', async function () { + expect(await this.token.maxFlashLoan(this.token.address)).to.be.bignumber.equal(MAX_UINT256.sub(initialSupply)); + }); + + it('token mismatch', async function () { + expect(await this.token.maxFlashLoan(ZERO_ADDRESS)).to.be.bignumber.equal('0'); + }); + }); + + describe('flashFee', function () { + it('token match', async function () { + expect(await this.token.flashFee(this.token.address, loanValue)).to.be.bignumber.equal('0'); + }); + + it('token mismatch', async function () { + await expectRevertCustomError(this.token.flashFee(ZERO_ADDRESS, loanValue), 'ERC3156UnsupportedToken', [ + ZERO_ADDRESS, + ]); + }); + }); + + describe('flashFeeReceiver', function () { + it('default receiver', async function () { + expect(await this.token.$_flashFeeReceiver()).to.be.eq(ZERO_ADDRESS); + }); + }); + + describe('flashLoan', function () { + it('success', async function () { + const receiver = await ERC3156FlashBorrowerMock.new(true, true); + const { tx } = await this.token.flashLoan(receiver.address, this.token.address, loanValue, '0x'); + + await expectEvent.inTransaction(tx, this.token, 'Transfer', { + from: ZERO_ADDRESS, + to: receiver.address, + value: loanValue, + }); + await expectEvent.inTransaction(tx, this.token, 'Transfer', { + from: receiver.address, + to: ZERO_ADDRESS, + value: loanValue, + }); + await expectEvent.inTransaction(tx, receiver, 'BalanceOf', { + token: this.token.address, + account: receiver.address, + value: loanValue, + }); + await expectEvent.inTransaction(tx, receiver, 'TotalSupply', { + token: this.token.address, + value: initialSupply.add(loanValue), + }); + + expect(await this.token.totalSupply()).to.be.bignumber.equal(initialSupply); + expect(await this.token.balanceOf(receiver.address)).to.be.bignumber.equal('0'); + expect(await this.token.allowance(receiver.address, this.token.address)).to.be.bignumber.equal('0'); + }); + + it('missing return value', async function () { + const receiver = await ERC3156FlashBorrowerMock.new(false, true); + await expectRevertCustomError( + this.token.flashLoan(receiver.address, this.token.address, loanValue, '0x'), + 'ERC3156InvalidReceiver', + [receiver.address], + ); + }); + + it('missing approval', async function () { + const receiver = await ERC3156FlashBorrowerMock.new(true, false); + await expectRevertCustomError( + this.token.flashLoan(receiver.address, this.token.address, loanValue, '0x'), + 'ERC20InsufficientAllowance', + [this.token.address, 0, loanValue], + ); + }); + + it('unavailable funds', async function () { + const receiver = await ERC3156FlashBorrowerMock.new(true, true); + const data = this.token.contract.methods.transfer(other, 10).encodeABI(); + await expectRevertCustomError( + this.token.flashLoan(receiver.address, this.token.address, loanValue, data), + 'ERC20InsufficientBalance', + [receiver.address, loanValue - 10, loanValue], + ); + }); + + it('more than maxFlashLoan', async function () { + const receiver = await ERC3156FlashBorrowerMock.new(true, true); + const data = this.token.contract.methods.transfer(other, 10).encodeABI(); + // _mint overflow reverts using a panic code. No reason string. + await expectRevert.unspecified(this.token.flashLoan(receiver.address, this.token.address, MAX_UINT256, data)); + }); + + describe('custom flash fee & custom fee receiver', function () { + const receiverInitialBalance = new BN(200000); + const flashFee = new BN(5000); + + beforeEach('init receiver balance & set flash fee', async function () { + this.receiver = await ERC3156FlashBorrowerMock.new(true, true); + const receipt = await this.token.$_mint(this.receiver.address, receiverInitialBalance); + await expectEvent(receipt, 'Transfer', { + from: ZERO_ADDRESS, + to: this.receiver.address, + value: receiverInitialBalance, + }); + expect(await this.token.balanceOf(this.receiver.address)).to.be.bignumber.equal(receiverInitialBalance); + + await this.token.setFlashFee(flashFee); + expect(await this.token.flashFee(this.token.address, loanValue)).to.be.bignumber.equal(flashFee); + }); + + it('default flash fee receiver', async function () { + const { tx } = await this.token.flashLoan(this.receiver.address, this.token.address, loanValue, '0x'); + await expectEvent.inTransaction(tx, this.token, 'Transfer', { + from: ZERO_ADDRESS, + to: this.receiver.address, + value: loanValue, + }); + await expectEvent.inTransaction(tx, this.token, 'Transfer', { + from: this.receiver.address, + to: ZERO_ADDRESS, + value: loanValue.add(flashFee), + }); + await expectEvent.inTransaction(tx, this.receiver, 'BalanceOf', { + token: this.token.address, + account: this.receiver.address, + value: receiverInitialBalance.add(loanValue), + }); + await expectEvent.inTransaction(tx, this.receiver, 'TotalSupply', { + token: this.token.address, + value: initialSupply.add(receiverInitialBalance).add(loanValue), + }); + + expect(await this.token.totalSupply()).to.be.bignumber.equal( + initialSupply.add(receiverInitialBalance).sub(flashFee), + ); + expect(await this.token.balanceOf(this.receiver.address)).to.be.bignumber.equal( + receiverInitialBalance.sub(flashFee), + ); + expect(await this.token.balanceOf(await this.token.$_flashFeeReceiver())).to.be.bignumber.equal('0'); + expect(await this.token.allowance(this.receiver.address, this.token.address)).to.be.bignumber.equal('0'); + }); + + it('custom flash fee receiver', async function () { + const flashFeeReceiverAddress = anotherAccount; + await this.token.setFlashFeeReceiver(flashFeeReceiverAddress); + expect(await this.token.$_flashFeeReceiver()).to.be.eq(flashFeeReceiverAddress); + + expect(await this.token.balanceOf(flashFeeReceiverAddress)).to.be.bignumber.equal('0'); + + const { tx } = await this.token.flashLoan(this.receiver.address, this.token.address, loanValue, '0x'); + await expectEvent.inTransaction(tx, this.token, 'Transfer', { + from: ZERO_ADDRESS, + to: this.receiver.address, + value: loanValue, + }); + await expectEvent.inTransaction(tx, this.token, 'Transfer', { + from: this.receiver.address, + to: ZERO_ADDRESS, + value: loanValue, + }); + await expectEvent.inTransaction(tx, this.token, 'Transfer', { + from: this.receiver.address, + to: flashFeeReceiverAddress, + value: flashFee, + }); + await expectEvent.inTransaction(tx, this.receiver, 'BalanceOf', { + token: this.token.address, + account: this.receiver.address, + value: receiverInitialBalance.add(loanValue), + }); + await expectEvent.inTransaction(tx, this.receiver, 'TotalSupply', { + token: this.token.address, + value: initialSupply.add(receiverInitialBalance).add(loanValue), + }); + + expect(await this.token.totalSupply()).to.be.bignumber.equal(initialSupply.add(receiverInitialBalance)); + expect(await this.token.balanceOf(this.receiver.address)).to.be.bignumber.equal( + receiverInitialBalance.sub(flashFee), + ); + expect(await this.token.balanceOf(flashFeeReceiverAddress)).to.be.bignumber.equal(flashFee); + expect(await this.token.allowance(this.receiver.address, flashFeeReceiverAddress)).to.be.bignumber.equal('0'); + }); + }); + }); +}); diff --git a/test/token/ERC20/extensions/ERC20Pausable.test.js b/test/token/ERC20/extensions/ERC20Pausable.test.js new file mode 100644 index 000000000..92c90b9b8 --- /dev/null +++ b/test/token/ERC20/extensions/ERC20Pausable.test.js @@ -0,0 +1,136 @@ +const { BN } = require('@openzeppelin/test-helpers'); + +const { expect } = require('chai'); +const { expectRevertCustomError } = require('../../../helpers/customError'); + +const ERC20Pausable = artifacts.require('$ERC20Pausable'); + +contract('ERC20Pausable', function (accounts) { + const [holder, recipient, anotherAccount] = accounts; + + const initialSupply = new BN(100); + + const name = 'My Token'; + const symbol = 'MTKN'; + + beforeEach(async function () { + this.token = await ERC20Pausable.new(name, symbol); + await this.token.$_mint(holder, initialSupply); + }); + + describe('pausable token', function () { + describe('transfer', function () { + it('allows to transfer when unpaused', async function () { + await this.token.transfer(recipient, initialSupply, { from: holder }); + + expect(await this.token.balanceOf(holder)).to.be.bignumber.equal('0'); + expect(await this.token.balanceOf(recipient)).to.be.bignumber.equal(initialSupply); + }); + + it('allows to transfer when paused and then unpaused', async function () { + await this.token.$_pause(); + await this.token.$_unpause(); + + await this.token.transfer(recipient, initialSupply, { from: holder }); + + expect(await this.token.balanceOf(holder)).to.be.bignumber.equal('0'); + expect(await this.token.balanceOf(recipient)).to.be.bignumber.equal(initialSupply); + }); + + it('reverts when trying to transfer when paused', async function () { + await this.token.$_pause(); + + await expectRevertCustomError( + this.token.transfer(recipient, initialSupply, { from: holder }), + 'EnforcedPause', + [], + ); + }); + }); + + describe('transfer from', function () { + const allowance = new BN(40); + + beforeEach(async function () { + await this.token.approve(anotherAccount, allowance, { from: holder }); + }); + + it('allows to transfer from when unpaused', async function () { + await this.token.transferFrom(holder, recipient, allowance, { from: anotherAccount }); + + expect(await this.token.balanceOf(recipient)).to.be.bignumber.equal(allowance); + expect(await this.token.balanceOf(holder)).to.be.bignumber.equal(initialSupply.sub(allowance)); + }); + + it('allows to transfer when paused and then unpaused', async function () { + await this.token.$_pause(); + await this.token.$_unpause(); + + await this.token.transferFrom(holder, recipient, allowance, { from: anotherAccount }); + + expect(await this.token.balanceOf(recipient)).to.be.bignumber.equal(allowance); + expect(await this.token.balanceOf(holder)).to.be.bignumber.equal(initialSupply.sub(allowance)); + }); + + it('reverts when trying to transfer from when paused', async function () { + await this.token.$_pause(); + + await expectRevertCustomError( + this.token.transferFrom(holder, recipient, allowance, { from: anotherAccount }), + 'EnforcedPause', + [], + ); + }); + }); + + describe('mint', function () { + const value = new BN('42'); + + it('allows to mint when unpaused', async function () { + await this.token.$_mint(recipient, value); + + expect(await this.token.balanceOf(recipient)).to.be.bignumber.equal(value); + }); + + it('allows to mint when paused and then unpaused', async function () { + await this.token.$_pause(); + await this.token.$_unpause(); + + await this.token.$_mint(recipient, value); + + expect(await this.token.balanceOf(recipient)).to.be.bignumber.equal(value); + }); + + it('reverts when trying to mint when paused', async function () { + await this.token.$_pause(); + + await expectRevertCustomError(this.token.$_mint(recipient, value), 'EnforcedPause', []); + }); + }); + + describe('burn', function () { + const value = new BN('42'); + + it('allows to burn when unpaused', async function () { + await this.token.$_burn(holder, value); + + expect(await this.token.balanceOf(holder)).to.be.bignumber.equal(initialSupply.sub(value)); + }); + + it('allows to burn when paused and then unpaused', async function () { + await this.token.$_pause(); + await this.token.$_unpause(); + + await this.token.$_burn(holder, value); + + expect(await this.token.balanceOf(holder)).to.be.bignumber.equal(initialSupply.sub(value)); + }); + + it('reverts when trying to burn when paused', async function () { + await this.token.$_pause(); + + await expectRevertCustomError(this.token.$_burn(holder, value), 'EnforcedPause', []); + }); + }); + }); +}); diff --git a/test/token/ERC20/extensions/ERC20Permit.test.js b/test/token/ERC20/extensions/ERC20Permit.test.js new file mode 100644 index 000000000..388716d53 --- /dev/null +++ b/test/token/ERC20/extensions/ERC20Permit.test.js @@ -0,0 +1,118 @@ +/* eslint-disable */ + +const { BN, constants, time } = require('@openzeppelin/test-helpers'); +const { expect } = require('chai'); +const { MAX_UINT256 } = constants; + +const { fromRpcSig } = require('ethereumjs-util'); +const ethSigUtil = require('eth-sig-util'); +const Wallet = require('ethereumjs-wallet').default; + +const ERC20Permit = artifacts.require('$ERC20Permit'); + +const { Permit, getDomain, domainType, domainSeparator } = require('../../../helpers/eip712'); +const { getChainId } = require('../../../helpers/chainid'); +const { expectRevertCustomError } = require('../../../helpers/customError'); + +contract('ERC20Permit', function (accounts) { + const [initialHolder, spender] = accounts; + + const name = 'My Token'; + const symbol = 'MTKN'; + + const initialSupply = new BN(100); + + beforeEach(async function () { + this.chainId = await getChainId(); + + this.token = await ERC20Permit.new(name, symbol, name); + await this.token.$_mint(initialHolder, initialSupply); + }); + + it('initial nonce is 0', async function () { + expect(await this.token.nonces(initialHolder)).to.be.bignumber.equal('0'); + }); + + it('domain separator', async function () { + expect(await this.token.DOMAIN_SEPARATOR()).to.equal(await getDomain(this.token).then(domainSeparator)); + }); + + describe('permit', function () { + const wallet = Wallet.generate(); + + const owner = wallet.getAddressString(); + const value = new BN(42); + const nonce = 0; + const maxDeadline = MAX_UINT256; + + const buildData = (contract, deadline = maxDeadline) => + getDomain(contract).then(domain => ({ + primaryType: 'Permit', + types: { EIP712Domain: domainType(domain), Permit }, + domain, + message: { owner, spender, value, nonce, deadline }, + })); + + it('accepts owner signature', async function () { + const { v, r, s } = await buildData(this.token) + .then(data => ethSigUtil.signTypedMessage(wallet.getPrivateKey(), { data })) + .then(fromRpcSig); + + await this.token.permit(owner, spender, value, maxDeadline, v, r, s); + + expect(await this.token.nonces(owner)).to.be.bignumber.equal('1'); + expect(await this.token.allowance(owner, spender)).to.be.bignumber.equal(value); + }); + + it('rejects reused signature', async function () { + const sig = await buildData(this.token).then(data => + ethSigUtil.signTypedMessage(wallet.getPrivateKey(), { data }), + ); + const { r, s, v } = fromRpcSig(sig); + + await this.token.permit(owner, spender, value, maxDeadline, v, r, s); + + const domain = await getDomain(this.token); + const typedMessage = { + primaryType: 'Permit', + types: { EIP712Domain: domainType(domain), Permit }, + domain, + message: { owner, spender, value, nonce: nonce + 1, deadline: maxDeadline }, + }; + + await expectRevertCustomError( + this.token.permit(owner, spender, value, maxDeadline, v, r, s), + 'ERC2612InvalidSigner', + [ethSigUtil.recoverTypedSignature({ data: typedMessage, sig }), owner], + ); + }); + + it('rejects other signature', async function () { + const otherWallet = Wallet.generate(); + + const { v, r, s } = await buildData(this.token) + .then(data => ethSigUtil.signTypedMessage(otherWallet.getPrivateKey(), { data })) + .then(fromRpcSig); + + await expectRevertCustomError( + this.token.permit(owner, spender, value, maxDeadline, v, r, s), + 'ERC2612InvalidSigner', + [await otherWallet.getAddressString(), owner], + ); + }); + + it('rejects expired permit', async function () { + const deadline = (await time.latest()) - time.duration.weeks(1); + + const { v, r, s } = await buildData(this.token, deadline) + .then(data => ethSigUtil.signTypedMessage(wallet.getPrivateKey(), { data })) + .then(fromRpcSig); + + await expectRevertCustomError( + this.token.permit(owner, spender, value, deadline, v, r, s), + 'ERC2612ExpiredSignature', + [deadline], + ); + }); + }); +}); diff --git a/test/token/ERC20/extensions/ERC20Votes.test.js b/test/token/ERC20/extensions/ERC20Votes.test.js new file mode 100644 index 000000000..faf1a15ad --- /dev/null +++ b/test/token/ERC20/extensions/ERC20Votes.test.js @@ -0,0 +1,593 @@ +/* eslint-disable */ + +const { BN, constants, expectEvent, time } = require('@openzeppelin/test-helpers'); +const { expect } = require('chai'); +const { MAX_UINT256, ZERO_ADDRESS } = constants; + +const { shouldBehaveLikeVotes } = require('../../../governance/utils/Votes.behavior'); +const { fromRpcSig } = require('ethereumjs-util'); +const ethSigUtil = require('eth-sig-util'); +const Wallet = require('ethereumjs-wallet').default; + +const { batchInBlock } = require('../../../helpers/txpool'); +const { getDomain, domainType } = require('../../../helpers/eip712'); +const { clock, clockFromReceipt } = require('../../../helpers/time'); +const { expectRevertCustomError } = require('../../../helpers/customError'); + +const Delegation = [ + { name: 'delegatee', type: 'address' }, + { name: 'nonce', type: 'uint256' }, + { name: 'expiry', type: 'uint256' }, +]; + +const MODES = { + blocknumber: artifacts.require('$ERC20Votes'), + timestamp: artifacts.require('$ERC20VotesTimestampMock'), +}; + +contract('ERC20Votes', function (accounts) { + const [holder, recipient, holderDelegatee, other1, other2] = accounts; + + const name = 'My Token'; + const symbol = 'MTKN'; + const version = '1'; + const supply = new BN('10000000000000000000000000'); + + for (const [mode, artifact] of Object.entries(MODES)) { + describe(`vote with ${mode}`, function () { + beforeEach(async function () { + this.token = await artifact.new(name, symbol, name, version); + this.votes = this.token; + }); + + // includes EIP6372 behavior check + shouldBehaveLikeVotes(accounts, [1, 17, 42], { mode, fungible: true }); + + it('initial nonce is 0', async function () { + expect(await this.token.nonces(holder)).to.be.bignumber.equal('0'); + }); + + it('minting restriction', async function () { + const value = web3.utils.toBN(1).shln(208); + await expectRevertCustomError(this.token.$_mint(holder, value), 'ERC20ExceededSafeSupply', [ + value, + value.subn(1), + ]); + }); + + it('recent checkpoints', async function () { + await this.token.delegate(holder, { from: holder }); + for (let i = 0; i < 6; i++) { + await this.token.$_mint(holder, 1); + } + const timepoint = await clock[mode](); + expect(await this.token.numCheckpoints(holder)).to.be.bignumber.equal('6'); + // recent + expect(await this.token.getPastVotes(holder, timepoint - 1)).to.be.bignumber.equal('5'); + // non-recent + expect(await this.token.getPastVotes(holder, timepoint - 6)).to.be.bignumber.equal('0'); + }); + + describe('set delegation', function () { + describe('call', function () { + it('delegation with balance', async function () { + await this.token.$_mint(holder, supply); + expect(await this.token.delegates(holder)).to.be.equal(ZERO_ADDRESS); + + const { receipt } = await this.token.delegate(holder, { from: holder }); + const timepoint = await clockFromReceipt[mode](receipt); + + expectEvent(receipt, 'DelegateChanged', { + delegator: holder, + fromDelegate: ZERO_ADDRESS, + toDelegate: holder, + }); + expectEvent(receipt, 'DelegateVotesChanged', { + delegate: holder, + previousVotes: '0', + newVotes: supply, + }); + + expect(await this.token.delegates(holder)).to.be.equal(holder); + + expect(await this.token.getVotes(holder)).to.be.bignumber.equal(supply); + expect(await this.token.getPastVotes(holder, timepoint - 1)).to.be.bignumber.equal('0'); + await time.advanceBlock(); + expect(await this.token.getPastVotes(holder, timepoint)).to.be.bignumber.equal(supply); + }); + + it('delegation without balance', async function () { + expect(await this.token.delegates(holder)).to.be.equal(ZERO_ADDRESS); + + const { receipt } = await this.token.delegate(holder, { from: holder }); + expectEvent(receipt, 'DelegateChanged', { + delegator: holder, + fromDelegate: ZERO_ADDRESS, + toDelegate: holder, + }); + expectEvent.notEmitted(receipt, 'DelegateVotesChanged'); + + expect(await this.token.delegates(holder)).to.be.equal(holder); + }); + }); + + describe('with signature', function () { + const delegator = Wallet.generate(); + const delegatorAddress = web3.utils.toChecksumAddress(delegator.getAddressString()); + const nonce = 0; + + const buildData = (contract, message) => + getDomain(contract).then(domain => ({ + primaryType: 'Delegation', + types: { EIP712Domain: domainType(domain), Delegation }, + domain, + message, + })); + + beforeEach(async function () { + await this.token.$_mint(delegatorAddress, supply); + }); + + it('accept signed delegation', async function () { + const { v, r, s } = await buildData(this.token, { + delegatee: delegatorAddress, + nonce, + expiry: MAX_UINT256, + }).then(data => fromRpcSig(ethSigUtil.signTypedMessage(delegator.getPrivateKey(), { data }))); + + expect(await this.token.delegates(delegatorAddress)).to.be.equal(ZERO_ADDRESS); + + const { receipt } = await this.token.delegateBySig(delegatorAddress, nonce, MAX_UINT256, v, r, s); + const timepoint = await clockFromReceipt[mode](receipt); + + expectEvent(receipt, 'DelegateChanged', { + delegator: delegatorAddress, + fromDelegate: ZERO_ADDRESS, + toDelegate: delegatorAddress, + }); + expectEvent(receipt, 'DelegateVotesChanged', { + delegate: delegatorAddress, + previousVotes: '0', + newVotes: supply, + }); + + expect(await this.token.delegates(delegatorAddress)).to.be.equal(delegatorAddress); + + expect(await this.token.getVotes(delegatorAddress)).to.be.bignumber.equal(supply); + expect(await this.token.getPastVotes(delegatorAddress, timepoint - 1)).to.be.bignumber.equal('0'); + await time.advanceBlock(); + expect(await this.token.getPastVotes(delegatorAddress, timepoint)).to.be.bignumber.equal(supply); + }); + + it('rejects reused signature', async function () { + const { v, r, s } = await buildData(this.token, { + delegatee: delegatorAddress, + nonce, + expiry: MAX_UINT256, + }).then(data => fromRpcSig(ethSigUtil.signTypedMessage(delegator.getPrivateKey(), { data }))); + + await this.token.delegateBySig(delegatorAddress, nonce, MAX_UINT256, v, r, s); + + await expectRevertCustomError( + this.token.delegateBySig(delegatorAddress, nonce, MAX_UINT256, v, r, s), + 'InvalidAccountNonce', + [delegatorAddress, nonce + 1], + ); + }); + + it('rejects bad delegatee', async function () { + const { v, r, s } = await buildData(this.token, { + delegatee: delegatorAddress, + nonce, + expiry: MAX_UINT256, + }).then(data => fromRpcSig(ethSigUtil.signTypedMessage(delegator.getPrivateKey(), { data }))); + + const receipt = await this.token.delegateBySig(holderDelegatee, nonce, MAX_UINT256, v, r, s); + const { args } = receipt.logs.find(({ event }) => event == 'DelegateChanged'); + expect(args.delegator).to.not.be.equal(delegatorAddress); + expect(args.fromDelegate).to.be.equal(ZERO_ADDRESS); + expect(args.toDelegate).to.be.equal(holderDelegatee); + }); + + it('rejects bad nonce', async function () { + const sig = await buildData(this.token, { + delegatee: delegatorAddress, + nonce, + expiry: MAX_UINT256, + }).then(data => ethSigUtil.signTypedMessage(delegator.getPrivateKey(), { data })); + const { r, s, v } = fromRpcSig(sig); + + const domain = await getDomain(this.token); + const typedMessage = { + primaryType: 'Delegation', + types: { EIP712Domain: domainType(domain), Delegation }, + domain, + message: { delegatee: delegatorAddress, nonce: nonce + 1, expiry: MAX_UINT256 }, + }; + + await expectRevertCustomError( + this.token.delegateBySig(delegatorAddress, nonce + 1, MAX_UINT256, v, r, s), + 'InvalidAccountNonce', + [ethSigUtil.recoverTypedSignature({ data: typedMessage, sig }), nonce], + ); + }); + + it('rejects expired permit', async function () { + const expiry = (await time.latest()) - time.duration.weeks(1); + const { v, r, s } = await buildData(this.token, { + delegatee: delegatorAddress, + nonce, + expiry, + }).then(data => fromRpcSig(ethSigUtil.signTypedMessage(delegator.getPrivateKey(), { data }))); + + await expectRevertCustomError( + this.token.delegateBySig(delegatorAddress, nonce, expiry, v, r, s), + 'VotesExpiredSignature', + [expiry], + ); + }); + }); + }); + + describe('change delegation', function () { + beforeEach(async function () { + await this.token.$_mint(holder, supply); + await this.token.delegate(holder, { from: holder }); + }); + + it('call', async function () { + expect(await this.token.delegates(holder)).to.be.equal(holder); + + const { receipt } = await this.token.delegate(holderDelegatee, { from: holder }); + const timepoint = await clockFromReceipt[mode](receipt); + + expectEvent(receipt, 'DelegateChanged', { + delegator: holder, + fromDelegate: holder, + toDelegate: holderDelegatee, + }); + expectEvent(receipt, 'DelegateVotesChanged', { + delegate: holder, + previousVotes: supply, + newVotes: '0', + }); + expectEvent(receipt, 'DelegateVotesChanged', { + delegate: holderDelegatee, + previousVotes: '0', + newVotes: supply, + }); + + expect(await this.token.delegates(holder)).to.be.equal(holderDelegatee); + + expect(await this.token.getVotes(holder)).to.be.bignumber.equal('0'); + expect(await this.token.getVotes(holderDelegatee)).to.be.bignumber.equal(supply); + expect(await this.token.getPastVotes(holder, timepoint - 1)).to.be.bignumber.equal(supply); + expect(await this.token.getPastVotes(holderDelegatee, timepoint - 1)).to.be.bignumber.equal('0'); + await time.advanceBlock(); + expect(await this.token.getPastVotes(holder, timepoint)).to.be.bignumber.equal('0'); + expect(await this.token.getPastVotes(holderDelegatee, timepoint)).to.be.bignumber.equal(supply); + }); + }); + + describe('transfers', function () { + beforeEach(async function () { + await this.token.$_mint(holder, supply); + }); + + it('no delegation', async function () { + const { receipt } = await this.token.transfer(recipient, 1, { from: holder }); + expectEvent(receipt, 'Transfer', { from: holder, to: recipient, value: '1' }); + expectEvent.notEmitted(receipt, 'DelegateVotesChanged'); + + this.holderVotes = '0'; + this.recipientVotes = '0'; + }); + + it('sender delegation', async function () { + await this.token.delegate(holder, { from: holder }); + + const { receipt } = await this.token.transfer(recipient, 1, { from: holder }); + expectEvent(receipt, 'Transfer', { from: holder, to: recipient, value: '1' }); + expectEvent(receipt, 'DelegateVotesChanged', { + delegate: holder, + previousVotes: supply, + newVotes: supply.subn(1), + }); + + const { logIndex: transferLogIndex } = receipt.logs.find(({ event }) => event == 'Transfer'); + expect( + receipt.logs + .filter(({ event }) => event == 'DelegateVotesChanged') + .every(({ logIndex }) => transferLogIndex < logIndex), + ).to.be.equal(true); + + this.holderVotes = supply.subn(1); + this.recipientVotes = '0'; + }); + + it('receiver delegation', async function () { + await this.token.delegate(recipient, { from: recipient }); + + const { receipt } = await this.token.transfer(recipient, 1, { from: holder }); + expectEvent(receipt, 'Transfer', { from: holder, to: recipient, value: '1' }); + expectEvent(receipt, 'DelegateVotesChanged', { delegate: recipient, previousVotes: '0', newVotes: '1' }); + + const { logIndex: transferLogIndex } = receipt.logs.find(({ event }) => event == 'Transfer'); + expect( + receipt.logs + .filter(({ event }) => event == 'DelegateVotesChanged') + .every(({ logIndex }) => transferLogIndex < logIndex), + ).to.be.equal(true); + + this.holderVotes = '0'; + this.recipientVotes = '1'; + }); + + it('full delegation', async function () { + await this.token.delegate(holder, { from: holder }); + await this.token.delegate(recipient, { from: recipient }); + + const { receipt } = await this.token.transfer(recipient, 1, { from: holder }); + expectEvent(receipt, 'Transfer', { from: holder, to: recipient, value: '1' }); + expectEvent(receipt, 'DelegateVotesChanged', { + delegate: holder, + previousVotes: supply, + newVotes: supply.subn(1), + }); + expectEvent(receipt, 'DelegateVotesChanged', { delegate: recipient, previousVotes: '0', newVotes: '1' }); + + const { logIndex: transferLogIndex } = receipt.logs.find(({ event }) => event == 'Transfer'); + expect( + receipt.logs + .filter(({ event }) => event == 'DelegateVotesChanged') + .every(({ logIndex }) => transferLogIndex < logIndex), + ).to.be.equal(true); + + this.holderVotes = supply.subn(1); + this.recipientVotes = '1'; + }); + + afterEach(async function () { + expect(await this.token.getVotes(holder)).to.be.bignumber.equal(this.holderVotes); + expect(await this.token.getVotes(recipient)).to.be.bignumber.equal(this.recipientVotes); + + // need to advance 2 blocks to see the effect of a transfer on "getPastVotes" + const timepoint = await clock[mode](); + await time.advanceBlock(); + expect(await this.token.getPastVotes(holder, timepoint)).to.be.bignumber.equal(this.holderVotes); + expect(await this.token.getPastVotes(recipient, timepoint)).to.be.bignumber.equal(this.recipientVotes); + }); + }); + + // The following tests are a adaptation of https://github.com/compound-finance/compound-protocol/blob/master/tests/Governance/CompTest.js. + describe('Compound test suite', function () { + beforeEach(async function () { + await this.token.$_mint(holder, supply); + }); + + describe('balanceOf', function () { + it('grants to initial account', async function () { + expect(await this.token.balanceOf(holder)).to.be.bignumber.equal('10000000000000000000000000'); + }); + }); + + describe('numCheckpoints', function () { + it('returns the number of checkpoints for a delegate', async function () { + await this.token.transfer(recipient, '100', { from: holder }); //give an account a few tokens for readability + expect(await this.token.numCheckpoints(other1)).to.be.bignumber.equal('0'); + + const t1 = await this.token.delegate(other1, { from: recipient }); + t1.timepoint = await clockFromReceipt[mode](t1.receipt); + expect(await this.token.numCheckpoints(other1)).to.be.bignumber.equal('1'); + + const t2 = await this.token.transfer(other2, 10, { from: recipient }); + t2.timepoint = await clockFromReceipt[mode](t2.receipt); + expect(await this.token.numCheckpoints(other1)).to.be.bignumber.equal('2'); + + const t3 = await this.token.transfer(other2, 10, { from: recipient }); + t3.timepoint = await clockFromReceipt[mode](t3.receipt); + expect(await this.token.numCheckpoints(other1)).to.be.bignumber.equal('3'); + + const t4 = await this.token.transfer(recipient, 20, { from: holder }); + t4.timepoint = await clockFromReceipt[mode](t4.receipt); + expect(await this.token.numCheckpoints(other1)).to.be.bignumber.equal('4'); + + expect(await this.token.checkpoints(other1, 0)).to.be.deep.equal([t1.timepoint.toString(), '100']); + expect(await this.token.checkpoints(other1, 1)).to.be.deep.equal([t2.timepoint.toString(), '90']); + expect(await this.token.checkpoints(other1, 2)).to.be.deep.equal([t3.timepoint.toString(), '80']); + expect(await this.token.checkpoints(other1, 3)).to.be.deep.equal([t4.timepoint.toString(), '100']); + + await time.advanceBlock(); + expect(await this.token.getPastVotes(other1, t1.timepoint)).to.be.bignumber.equal('100'); + expect(await this.token.getPastVotes(other1, t2.timepoint)).to.be.bignumber.equal('90'); + expect(await this.token.getPastVotes(other1, t3.timepoint)).to.be.bignumber.equal('80'); + expect(await this.token.getPastVotes(other1, t4.timepoint)).to.be.bignumber.equal('100'); + }); + + it('does not add more than one checkpoint in a block', async function () { + await this.token.transfer(recipient, '100', { from: holder }); + expect(await this.token.numCheckpoints(other1)).to.be.bignumber.equal('0'); + + const [t1, t2, t3] = await batchInBlock([ + () => this.token.delegate(other1, { from: recipient, gas: 200000 }), + () => this.token.transfer(other2, 10, { from: recipient, gas: 200000 }), + () => this.token.transfer(other2, 10, { from: recipient, gas: 200000 }), + ]); + t1.timepoint = await clockFromReceipt[mode](t1.receipt); + t2.timepoint = await clockFromReceipt[mode](t2.receipt); + t3.timepoint = await clockFromReceipt[mode](t3.receipt); + + expect(await this.token.numCheckpoints(other1)).to.be.bignumber.equal('1'); + expect(await this.token.checkpoints(other1, 0)).to.be.deep.equal([t1.timepoint.toString(), '80']); + + const t4 = await this.token.transfer(recipient, 20, { from: holder }); + t4.timepoint = await clockFromReceipt[mode](t4.receipt); + + expect(await this.token.numCheckpoints(other1)).to.be.bignumber.equal('2'); + expect(await this.token.checkpoints(other1, 1)).to.be.deep.equal([t4.timepoint.toString(), '100']); + }); + }); + + describe('getPastVotes', function () { + it('reverts if block number >= current block', async function () { + const clock = await this.token.clock(); + await expectRevertCustomError(this.token.getPastVotes(other1, 5e10), 'ERC5805FutureLookup', [5e10, clock]); + }); + + it('returns 0 if there are no checkpoints', async function () { + expect(await this.token.getPastVotes(other1, 0)).to.be.bignumber.equal('0'); + }); + + it('returns the latest block if >= last checkpoint block', async function () { + const { receipt } = await this.token.delegate(other1, { from: holder }); + const timepoint = await clockFromReceipt[mode](receipt); + await time.advanceBlock(); + await time.advanceBlock(); + + expect(await this.token.getPastVotes(other1, timepoint)).to.be.bignumber.equal( + '10000000000000000000000000', + ); + expect(await this.token.getPastVotes(other1, timepoint + 1)).to.be.bignumber.equal( + '10000000000000000000000000', + ); + }); + + it('returns zero if < first checkpoint block', async function () { + await time.advanceBlock(); + const { receipt } = await this.token.delegate(other1, { from: holder }); + const timepoint = await clockFromReceipt[mode](receipt); + await time.advanceBlock(); + await time.advanceBlock(); + + expect(await this.token.getPastVotes(other1, timepoint - 1)).to.be.bignumber.equal('0'); + expect(await this.token.getPastVotes(other1, timepoint + 1)).to.be.bignumber.equal( + '10000000000000000000000000', + ); + }); + + it('generally returns the voting balance at the appropriate checkpoint', async function () { + const t1 = await this.token.delegate(other1, { from: holder }); + await time.advanceBlock(); + await time.advanceBlock(); + const t2 = await this.token.transfer(other2, 10, { from: holder }); + await time.advanceBlock(); + await time.advanceBlock(); + const t3 = await this.token.transfer(other2, 10, { from: holder }); + await time.advanceBlock(); + await time.advanceBlock(); + const t4 = await this.token.transfer(holder, 20, { from: other2 }); + await time.advanceBlock(); + await time.advanceBlock(); + + t1.timepoint = await clockFromReceipt[mode](t1.receipt); + t2.timepoint = await clockFromReceipt[mode](t2.receipt); + t3.timepoint = await clockFromReceipt[mode](t3.receipt); + t4.timepoint = await clockFromReceipt[mode](t4.receipt); + + expect(await this.token.getPastVotes(other1, t1.timepoint - 1)).to.be.bignumber.equal('0'); + expect(await this.token.getPastVotes(other1, t1.timepoint)).to.be.bignumber.equal( + '10000000000000000000000000', + ); + expect(await this.token.getPastVotes(other1, t1.timepoint + 1)).to.be.bignumber.equal( + '10000000000000000000000000', + ); + expect(await this.token.getPastVotes(other1, t2.timepoint)).to.be.bignumber.equal( + '9999999999999999999999990', + ); + expect(await this.token.getPastVotes(other1, t2.timepoint + 1)).to.be.bignumber.equal( + '9999999999999999999999990', + ); + expect(await this.token.getPastVotes(other1, t3.timepoint)).to.be.bignumber.equal( + '9999999999999999999999980', + ); + expect(await this.token.getPastVotes(other1, t3.timepoint + 1)).to.be.bignumber.equal( + '9999999999999999999999980', + ); + expect(await this.token.getPastVotes(other1, t4.timepoint)).to.be.bignumber.equal( + '10000000000000000000000000', + ); + expect(await this.token.getPastVotes(other1, t4.timepoint + 1)).to.be.bignumber.equal( + '10000000000000000000000000', + ); + }); + }); + }); + + describe('getPastTotalSupply', function () { + beforeEach(async function () { + await this.token.delegate(holder, { from: holder }); + }); + + it('reverts if block number >= current block', async function () { + const clock = await this.token.clock(); + await expectRevertCustomError(this.token.getPastTotalSupply(5e10), 'ERC5805FutureLookup', [5e10, clock]); + }); + + it('returns 0 if there are no checkpoints', async function () { + expect(await this.token.getPastTotalSupply(0)).to.be.bignumber.equal('0'); + }); + + it('returns the latest block if >= last checkpoint block', async function () { + const { receipt } = await this.token.$_mint(holder, supply); + const timepoint = await clockFromReceipt[mode](receipt); + await time.advanceBlock(); + await time.advanceBlock(); + + expect(await this.token.getPastTotalSupply(timepoint)).to.be.bignumber.equal(supply); + expect(await this.token.getPastTotalSupply(timepoint + 1)).to.be.bignumber.equal(supply); + }); + + it('returns zero if < first checkpoint block', async function () { + await time.advanceBlock(); + const { receipt } = await this.token.$_mint(holder, supply); + const timepoint = await clockFromReceipt[mode](receipt); + await time.advanceBlock(); + await time.advanceBlock(); + + expect(await this.token.getPastTotalSupply(timepoint - 1)).to.be.bignumber.equal('0'); + expect(await this.token.getPastTotalSupply(timepoint + 1)).to.be.bignumber.equal( + '10000000000000000000000000', + ); + }); + + it('generally returns the voting balance at the appropriate checkpoint', async function () { + const t1 = await this.token.$_mint(holder, supply); + await time.advanceBlock(); + await time.advanceBlock(); + const t2 = await this.token.$_burn(holder, 10); + await time.advanceBlock(); + await time.advanceBlock(); + const t3 = await this.token.$_burn(holder, 10); + await time.advanceBlock(); + await time.advanceBlock(); + const t4 = await this.token.$_mint(holder, 20); + await time.advanceBlock(); + await time.advanceBlock(); + + t1.timepoint = await clockFromReceipt[mode](t1.receipt); + t2.timepoint = await clockFromReceipt[mode](t2.receipt); + t3.timepoint = await clockFromReceipt[mode](t3.receipt); + t4.timepoint = await clockFromReceipt[mode](t4.receipt); + + expect(await this.token.getPastTotalSupply(t1.timepoint - 1)).to.be.bignumber.equal('0'); + expect(await this.token.getPastTotalSupply(t1.timepoint)).to.be.bignumber.equal('10000000000000000000000000'); + expect(await this.token.getPastTotalSupply(t1.timepoint + 1)).to.be.bignumber.equal( + '10000000000000000000000000', + ); + expect(await this.token.getPastTotalSupply(t2.timepoint)).to.be.bignumber.equal('9999999999999999999999990'); + expect(await this.token.getPastTotalSupply(t2.timepoint + 1)).to.be.bignumber.equal( + '9999999999999999999999990', + ); + expect(await this.token.getPastTotalSupply(t3.timepoint)).to.be.bignumber.equal('9999999999999999999999980'); + expect(await this.token.getPastTotalSupply(t3.timepoint + 1)).to.be.bignumber.equal( + '9999999999999999999999980', + ); + expect(await this.token.getPastTotalSupply(t4.timepoint)).to.be.bignumber.equal('10000000000000000000000000'); + expect(await this.token.getPastTotalSupply(t4.timepoint + 1)).to.be.bignumber.equal( + '10000000000000000000000000', + ); + }); + }); + }); + } +}); diff --git a/test/token/ERC20/extensions/ERC20Wrapper.test.js b/test/token/ERC20/extensions/ERC20Wrapper.test.js new file mode 100644 index 000000000..c54a9e007 --- /dev/null +++ b/test/token/ERC20/extensions/ERC20Wrapper.test.js @@ -0,0 +1,211 @@ +const { BN, constants, expectEvent } = require('@openzeppelin/test-helpers'); +const { expect } = require('chai'); +const { ZERO_ADDRESS, MAX_UINT256 } = constants; + +const { shouldBehaveLikeERC20 } = require('../ERC20.behavior'); +const { expectRevertCustomError } = require('../../../helpers/customError'); + +const NotAnERC20 = artifacts.require('CallReceiverMock'); +const ERC20Decimals = artifacts.require('$ERC20DecimalsMock'); +const ERC20Wrapper = artifacts.require('$ERC20Wrapper'); + +contract('ERC20Wrapper', function (accounts) { + const [initialHolder, receiver] = accounts; + + const name = 'My Token'; + const symbol = 'MTKN'; + + const initialSupply = new BN(100); + + beforeEach(async function () { + this.underlying = await ERC20Decimals.new(name, symbol, 9); + await this.underlying.$_mint(initialHolder, initialSupply); + + this.token = await ERC20Wrapper.new(`Wrapped ${name}`, `W${symbol}`, this.underlying.address); + }); + + afterEach(async function () { + expect(await this.underlying.balanceOf(this.token.address)).to.be.bignumber.equal(await this.token.totalSupply()); + }); + + it('has a name', async function () { + expect(await this.token.name()).to.equal(`Wrapped ${name}`); + }); + + it('has a symbol', async function () { + expect(await this.token.symbol()).to.equal(`W${symbol}`); + }); + + it('has the same decimals as the underlying token', async function () { + expect(await this.token.decimals()).to.be.bignumber.equal('9'); + }); + + it('decimals default back to 18 if token has no metadata', async function () { + const noDecimals = await NotAnERC20.new(); + const otherToken = await ERC20Wrapper.new(`Wrapped ${name}`, `W${symbol}`, noDecimals.address); + expect(await otherToken.decimals()).to.be.bignumber.equal('18'); + }); + + it('has underlying', async function () { + expect(await this.token.underlying()).to.be.bignumber.equal(this.underlying.address); + }); + + describe('deposit', function () { + it('valid', async function () { + await this.underlying.approve(this.token.address, initialSupply, { from: initialHolder }); + const { tx } = await this.token.depositFor(initialHolder, initialSupply, { from: initialHolder }); + await expectEvent.inTransaction(tx, this.underlying, 'Transfer', { + from: initialHolder, + to: this.token.address, + value: initialSupply, + }); + await expectEvent.inTransaction(tx, this.token, 'Transfer', { + from: ZERO_ADDRESS, + to: initialHolder, + value: initialSupply, + }); + }); + + it('missing approval', async function () { + await expectRevertCustomError( + this.token.depositFor(initialHolder, initialSupply, { from: initialHolder }), + 'ERC20InsufficientAllowance', + [this.token.address, 0, initialSupply], + ); + }); + + it('missing balance', async function () { + await this.underlying.approve(this.token.address, MAX_UINT256, { from: initialHolder }); + await expectRevertCustomError( + this.token.depositFor(initialHolder, MAX_UINT256, { from: initialHolder }), + 'ERC20InsufficientBalance', + [initialHolder, initialSupply, MAX_UINT256], + ); + }); + + it('to other account', async function () { + await this.underlying.approve(this.token.address, initialSupply, { from: initialHolder }); + const { tx } = await this.token.depositFor(receiver, initialSupply, { from: initialHolder }); + await expectEvent.inTransaction(tx, this.underlying, 'Transfer', { + from: initialHolder, + to: this.token.address, + value: initialSupply, + }); + await expectEvent.inTransaction(tx, this.token, 'Transfer', { + from: ZERO_ADDRESS, + to: receiver, + value: initialSupply, + }); + }); + + it('reverts minting to the wrapper contract', async function () { + await this.underlying.approve(this.token.address, MAX_UINT256, { from: initialHolder }); + await expectRevertCustomError( + this.token.depositFor(this.token.address, MAX_UINT256, { from: initialHolder }), + 'ERC20InvalidReceiver', + [this.token.address], + ); + }); + }); + + describe('withdraw', function () { + beforeEach(async function () { + await this.underlying.approve(this.token.address, initialSupply, { from: initialHolder }); + await this.token.depositFor(initialHolder, initialSupply, { from: initialHolder }); + }); + + it('missing balance', async function () { + await expectRevertCustomError( + this.token.withdrawTo(initialHolder, MAX_UINT256, { from: initialHolder }), + 'ERC20InsufficientBalance', + [initialHolder, initialSupply, MAX_UINT256], + ); + }); + + it('valid', async function () { + const value = new BN(42); + + const { tx } = await this.token.withdrawTo(initialHolder, value, { from: initialHolder }); + await expectEvent.inTransaction(tx, this.underlying, 'Transfer', { + from: this.token.address, + to: initialHolder, + value: value, + }); + await expectEvent.inTransaction(tx, this.token, 'Transfer', { + from: initialHolder, + to: ZERO_ADDRESS, + value: value, + }); + }); + + it('entire balance', async function () { + const { tx } = await this.token.withdrawTo(initialHolder, initialSupply, { from: initialHolder }); + await expectEvent.inTransaction(tx, this.underlying, 'Transfer', { + from: this.token.address, + to: initialHolder, + value: initialSupply, + }); + await expectEvent.inTransaction(tx, this.token, 'Transfer', { + from: initialHolder, + to: ZERO_ADDRESS, + value: initialSupply, + }); + }); + + it('to other account', async function () { + const { tx } = await this.token.withdrawTo(receiver, initialSupply, { from: initialHolder }); + await expectEvent.inTransaction(tx, this.underlying, 'Transfer', { + from: this.token.address, + to: receiver, + value: initialSupply, + }); + await expectEvent.inTransaction(tx, this.token, 'Transfer', { + from: initialHolder, + to: ZERO_ADDRESS, + value: initialSupply, + }); + }); + + it('reverts withdrawing to the wrapper contract', async function () { + expectRevertCustomError( + this.token.withdrawTo(this.token.address, initialSupply, { from: initialHolder }), + 'ERC20InvalidReceiver', + [this.token.address], + ); + }); + }); + + describe('recover', function () { + it('nothing to recover', async function () { + await this.underlying.approve(this.token.address, initialSupply, { from: initialHolder }); + await this.token.depositFor(initialHolder, initialSupply, { from: initialHolder }); + + const { tx } = await this.token.$_recover(receiver); + await expectEvent.inTransaction(tx, this.token, 'Transfer', { + from: ZERO_ADDRESS, + to: receiver, + value: '0', + }); + }); + + it('something to recover', async function () { + await this.underlying.transfer(this.token.address, initialSupply, { from: initialHolder }); + + const { tx } = await this.token.$_recover(receiver); + await expectEvent.inTransaction(tx, this.token, 'Transfer', { + from: ZERO_ADDRESS, + to: receiver, + value: initialSupply, + }); + }); + }); + + describe('erc20 behaviour', function () { + beforeEach(async function () { + await this.underlying.approve(this.token.address, initialSupply, { from: initialHolder }); + await this.token.depositFor(initialHolder, initialSupply, { from: initialHolder }); + }); + + shouldBehaveLikeERC20(initialSupply, accounts); + }); +}); diff --git a/test/token/ERC20/extensions/ERC4626.t.sol b/test/token/ERC20/extensions/ERC4626.t.sol new file mode 100644 index 000000000..72b0daca1 --- /dev/null +++ b/test/token/ERC20/extensions/ERC4626.t.sol @@ -0,0 +1,41 @@ +// SPDX-License-Identifier: MIT +pragma solidity ^0.8.20; + +import {ERC4626Test} from "erc4626-tests/ERC4626.test.sol"; + +import {ERC20} from "@openzeppelin/contracts/token/ERC20/ERC20.sol"; +import {ERC4626} from "@openzeppelin/contracts/token/ERC20/extensions/ERC4626.sol"; + +import {ERC20Mock} from "@openzeppelin/contracts/mocks/token/ERC20Mock.sol"; +import {ERC4626Mock} from "@openzeppelin/contracts/mocks/token/ERC4626Mock.sol"; +import {ERC4626OffsetMock} from "@openzeppelin/contracts/mocks/token/ERC4626OffsetMock.sol"; + +contract ERC4626VaultOffsetMock is ERC4626OffsetMock { + constructor( + ERC20 underlying_, + uint8 offset_ + ) ERC20("My Token Vault", "MTKNV") ERC4626(underlying_) ERC4626OffsetMock(offset_) {} +} + +contract ERC4626StdTest is ERC4626Test { + ERC20 private _underlying = new ERC20Mock(); + + function setUp() public override { + _underlying_ = address(_underlying); + _vault_ = address(new ERC4626Mock(_underlying_)); + _delta_ = 0; + _vaultMayBeEmpty = true; + _unlimitedAmount = true; + } + + /** + * @dev Check the case where calculated `decimals` value overflows the `uint8` type. + */ + function testFuzzDecimalsOverflow(uint8 offset) public { + /// @dev Remember that the `_underlying` exhibits a `decimals` value of 18. + offset = uint8(bound(uint256(offset), 238, uint256(type(uint8).max))); + ERC4626VaultOffsetMock erc4626VaultOffsetMock = new ERC4626VaultOffsetMock(_underlying, offset); + vm.expectRevert(); + erc4626VaultOffsetMock.decimals(); + } +} diff --git a/test/token/ERC20/extensions/ERC4626.test.js b/test/token/ERC20/extensions/ERC4626.test.js new file mode 100644 index 000000000..499cf0628 --- /dev/null +++ b/test/token/ERC20/extensions/ERC4626.test.js @@ -0,0 +1,1109 @@ +const { constants, expectEvent, expectRevert } = require('@openzeppelin/test-helpers'); +const { expect } = require('chai'); + +const { Enum } = require('../../../helpers/enums'); +const { expectRevertCustomError } = require('../../../helpers/customError'); + +const ERC20Decimals = artifacts.require('$ERC20DecimalsMock'); +const ERC4626 = artifacts.require('$ERC4626'); +const ERC4626LimitsMock = artifacts.require('$ERC4626LimitsMock'); +const ERC4626OffsetMock = artifacts.require('$ERC4626OffsetMock'); +const ERC4626FeesMock = artifacts.require('$ERC4626FeesMock'); +const ERC20ExcessDecimalsMock = artifacts.require('ERC20ExcessDecimalsMock'); +const ERC20Reentrant = artifacts.require('$ERC20Reentrant'); + +contract('ERC4626', function (accounts) { + const [holder, recipient, spender, other, user1, user2] = accounts; + + const name = 'My Token'; + const symbol = 'MTKN'; + const decimals = web3.utils.toBN(18); + + it('inherit decimals if from asset', async function () { + for (const decimals of [0, 9, 12, 18, 36].map(web3.utils.toBN)) { + const token = await ERC20Decimals.new('', '', decimals); + const vault = await ERC4626.new('', '', token.address); + expect(await vault.decimals()).to.be.bignumber.equal(decimals); + } + }); + + it('asset has not yet been created', async function () { + const vault = await ERC4626.new('', '', other); + expect(await vault.decimals()).to.be.bignumber.equal(decimals); + }); + + it('underlying excess decimals', async function () { + const token = await ERC20ExcessDecimalsMock.new(); + const vault = await ERC4626.new('', '', token.address); + expect(await vault.decimals()).to.be.bignumber.equal(decimals); + }); + + it('decimals overflow', async function () { + for (const offset of [243, 250, 255].map(web3.utils.toBN)) { + const token = await ERC20Decimals.new('', '', decimals); + const vault = await ERC4626OffsetMock.new(name + ' Vault', symbol + 'V', token.address, offset); + await expectRevert( + vault.decimals(), + 'reverted with panic code 0x11 (Arithmetic operation underflowed or overflowed outside of an unchecked block)', + ); + } + }); + + describe('reentrancy', async function () { + const reenterType = Enum('No', 'Before', 'After'); + + const value = web3.utils.toBN(1000000000000000000); + const reenterValue = web3.utils.toBN(1000000000); + let token; + let vault; + + beforeEach(async function () { + token = await ERC20Reentrant.new(); + // Use offset 1 so the rate is not 1:1 and we can't possibly confuse assets and shares + vault = await ERC4626OffsetMock.new('', '', token.address, 1); + // Funds and approval for tests + await token.$_mint(holder, value); + await token.$_mint(other, value); + await token.$_approve(holder, vault.address, constants.MAX_UINT256); + await token.$_approve(other, vault.address, constants.MAX_UINT256); + await token.$_approve(token.address, vault.address, constants.MAX_UINT256); + }); + + // During a `_deposit`, the vault does `transferFrom(depositor, vault, assets)` -> `_mint(receiver, shares)` + // such that a reentrancy BEFORE the transfer guarantees the price is kept the same. + // If the order of transfer -> mint is changed to mint -> transfer, the reentrancy could be triggered on an + // intermediate state in which the ratio of assets/shares has been decreased (more shares than assets). + it('correct share price is observed during reentrancy before deposit', async function () { + // mint token for deposit + await token.$_mint(token.address, reenterValue); + + // Schedules a reentrancy from the token contract + await token.scheduleReenter( + reenterType.Before, + vault.address, + vault.contract.methods.deposit(reenterValue, holder).encodeABI(), + ); + + // Initial share price + const sharesForDeposit = await vault.previewDeposit(value, { from: holder }); + const sharesForReenter = await vault.previewDeposit(reenterValue, { from: holder }); + + // Do deposit normally, triggering the _beforeTokenTransfer hook + const receipt = await vault.deposit(value, holder, { from: holder }); + + // Main deposit event + await expectEvent(receipt, 'Deposit', { + sender: holder, + owner: holder, + assets: value, + shares: sharesForDeposit, + }); + // Reentrant deposit event → uses the same price + await expectEvent(receipt, 'Deposit', { + sender: token.address, + owner: holder, + assets: reenterValue, + shares: sharesForReenter, + }); + + // Assert prices is kept + const sharesAfter = await vault.previewDeposit(value, { from: holder }); + expect(sharesForDeposit).to.be.bignumber.eq(sharesAfter); + }); + + // During a `_withdraw`, the vault does `_burn(owner, shares)` -> `transfer(receiver, assets)` + // such that a reentrancy AFTER the transfer guarantees the price is kept the same. + // If the order of burn -> transfer is changed to transfer -> burn, the reentrancy could be triggered on an + // intermediate state in which the ratio of shares/assets has been decreased (more assets than shares). + it('correct share price is observed during reentrancy after withdraw', async function () { + // Deposit into the vault: holder gets `value` share, token.address gets `reenterValue` shares + await vault.deposit(value, holder, { from: holder }); + await vault.deposit(reenterValue, token.address, { from: other }); + + // Schedules a reentrancy from the token contract + await token.scheduleReenter( + reenterType.After, + vault.address, + vault.contract.methods.withdraw(reenterValue, holder, token.address).encodeABI(), + ); + + // Initial share price + const sharesForWithdraw = await vault.previewWithdraw(value, { from: holder }); + const sharesForReenter = await vault.previewWithdraw(reenterValue, { from: holder }); + + // Do withdraw normally, triggering the _afterTokenTransfer hook + const receipt = await vault.withdraw(value, holder, holder, { from: holder }); + + // Main withdraw event + await expectEvent(receipt, 'Withdraw', { + sender: holder, + receiver: holder, + owner: holder, + assets: value, + shares: sharesForWithdraw, + }); + // Reentrant withdraw event → uses the same price + await expectEvent(receipt, 'Withdraw', { + sender: token.address, + receiver: holder, + owner: token.address, + assets: reenterValue, + shares: sharesForReenter, + }); + + // Assert price is kept + const sharesAfter = await vault.previewWithdraw(value, { from: holder }); + expect(sharesForWithdraw).to.be.bignumber.eq(sharesAfter); + }); + + // Donate newly minted tokens to the vault during the reentracy causes the share price to increase. + // Still, the deposit that trigger the reentracy is not affected and get the previewed price. + // Further deposits will get a different price (getting fewer shares for the same value of assets) + it('share price change during reentracy does not affect deposit', async function () { + // Schedules a reentrancy from the token contract that mess up the share price + await token.scheduleReenter( + reenterType.Before, + token.address, + token.contract.methods.$_mint(vault.address, reenterValue).encodeABI(), + ); + + // Price before + const sharesBefore = await vault.previewDeposit(value); + + // Deposit, triggering the _beforeTokenTransfer hook + const receipt = await vault.deposit(value, holder, { from: holder }); + + // Price is as previewed + await expectEvent(receipt, 'Deposit', { + sender: holder, + owner: holder, + assets: value, + shares: sharesBefore, + }); + + // Price was modified during reentrancy + const sharesAfter = await vault.previewDeposit(value); + expect(sharesAfter).to.be.bignumber.lt(sharesBefore); + }); + + // Burn some tokens from the vault during the reentracy causes the share price to drop. + // Still, the withdraw that trigger the reentracy is not affected and get the previewed price. + // Further withdraw will get a different price (needing more shares for the same value of assets) + it('share price change during reentracy does not affect withdraw', async function () { + await vault.deposit(value, other, { from: other }); + await vault.deposit(value, holder, { from: holder }); + + // Schedules a reentrancy from the token contract that mess up the share price + await token.scheduleReenter( + reenterType.After, + token.address, + token.contract.methods.$_burn(vault.address, reenterValue).encodeABI(), + ); + + // Price before + const sharesBefore = await vault.previewWithdraw(value); + + // Withdraw, triggering the _afterTokenTransfer hook + const receipt = await vault.withdraw(value, holder, holder, { from: holder }); + + // Price is as previewed + await expectEvent(receipt, 'Withdraw', { + sender: holder, + receiver: holder, + owner: holder, + assets: value, + shares: sharesBefore, + }); + + // Price was modified during reentrancy + const sharesAfter = await vault.previewWithdraw(value); + expect(sharesAfter).to.be.bignumber.gt(sharesBefore); + }); + }); + + describe('limits', async function () { + beforeEach(async function () { + this.token = await ERC20Decimals.new(name, symbol, decimals); + this.vault = await ERC4626LimitsMock.new(name + ' Vault', symbol + 'V', this.token.address); + }); + + it('reverts on deposit() above max deposit', async function () { + const maxDeposit = await this.vault.maxDeposit(holder); + await expectRevertCustomError(this.vault.deposit(maxDeposit.addn(1), recipient), 'ERC4626ExceededMaxDeposit', [ + recipient, + maxDeposit.addn(1), + maxDeposit, + ]); + }); + + it('reverts on mint() above max mint', async function () { + const maxMint = await this.vault.maxMint(holder); + await expectRevertCustomError(this.vault.mint(maxMint.addn(1), recipient), 'ERC4626ExceededMaxMint', [ + recipient, + maxMint.addn(1), + maxMint, + ]); + }); + + it('reverts on withdraw() above max withdraw', async function () { + const maxWithdraw = await this.vault.maxWithdraw(holder); + await expectRevertCustomError( + this.vault.withdraw(maxWithdraw.addn(1), recipient, holder), + 'ERC4626ExceededMaxWithdraw', + [holder, maxWithdraw.addn(1), maxWithdraw], + ); + }); + + it('reverts on redeem() above max redeem', async function () { + const maxRedeem = await this.vault.maxRedeem(holder); + await expectRevertCustomError( + this.vault.redeem(maxRedeem.addn(1), recipient, holder), + 'ERC4626ExceededMaxRedeem', + [holder, maxRedeem.addn(1), maxRedeem], + ); + }); + }); + + for (const offset of [0, 6, 18].map(web3.utils.toBN)) { + const parseToken = token => web3.utils.toBN(10).pow(decimals).muln(token); + const parseShare = share => web3.utils.toBN(10).pow(decimals.add(offset)).muln(share); + + const virtualAssets = web3.utils.toBN(1); + const virtualShares = web3.utils.toBN(10).pow(offset); + + describe(`offset: ${offset}`, function () { + beforeEach(async function () { + this.token = await ERC20Decimals.new(name, symbol, decimals); + this.vault = await ERC4626OffsetMock.new(name + ' Vault', symbol + 'V', this.token.address, offset); + + await this.token.$_mint(holder, constants.MAX_INT256); // 50% of maximum + await this.token.approve(this.vault.address, constants.MAX_UINT256, { from: holder }); + await this.vault.approve(spender, constants.MAX_UINT256, { from: holder }); + }); + + it('metadata', async function () { + expect(await this.vault.name()).to.be.equal(name + ' Vault'); + expect(await this.vault.symbol()).to.be.equal(symbol + 'V'); + expect(await this.vault.decimals()).to.be.bignumber.equal(decimals.add(offset)); + expect(await this.vault.asset()).to.be.equal(this.token.address); + }); + + describe('empty vault: no assets & no shares', function () { + it('status', async function () { + expect(await this.vault.totalAssets()).to.be.bignumber.equal('0'); + }); + + it('deposit', async function () { + expect(await this.vault.maxDeposit(holder)).to.be.bignumber.equal(constants.MAX_UINT256); + expect(await this.vault.previewDeposit(parseToken(1))).to.be.bignumber.equal(parseShare(1)); + + const { tx } = await this.vault.deposit(parseToken(1), recipient, { from: holder }); + + await expectEvent.inTransaction(tx, this.token, 'Transfer', { + from: holder, + to: this.vault.address, + value: parseToken(1), + }); + + await expectEvent.inTransaction(tx, this.vault, 'Transfer', { + from: constants.ZERO_ADDRESS, + to: recipient, + value: parseShare(1), + }); + + await expectEvent.inTransaction(tx, this.vault, 'Deposit', { + sender: holder, + owner: recipient, + assets: parseToken(1), + shares: parseShare(1), + }); + }); + + it('mint', async function () { + expect(await this.vault.maxMint(holder)).to.be.bignumber.equal(constants.MAX_UINT256); + expect(await this.vault.previewMint(parseShare(1))).to.be.bignumber.equal(parseToken(1)); + + const { tx } = await this.vault.mint(parseShare(1), recipient, { from: holder }); + + await expectEvent.inTransaction(tx, this.token, 'Transfer', { + from: holder, + to: this.vault.address, + value: parseToken(1), + }); + + await expectEvent.inTransaction(tx, this.vault, 'Transfer', { + from: constants.ZERO_ADDRESS, + to: recipient, + value: parseShare(1), + }); + + await expectEvent.inTransaction(tx, this.vault, 'Deposit', { + sender: holder, + owner: recipient, + assets: parseToken(1), + shares: parseShare(1), + }); + }); + + it('withdraw', async function () { + expect(await this.vault.maxWithdraw(holder)).to.be.bignumber.equal('0'); + expect(await this.vault.previewWithdraw('0')).to.be.bignumber.equal('0'); + + const { tx } = await this.vault.withdraw('0', recipient, holder, { from: holder }); + + await expectEvent.inTransaction(tx, this.token, 'Transfer', { + from: this.vault.address, + to: recipient, + value: '0', + }); + + await expectEvent.inTransaction(tx, this.vault, 'Transfer', { + from: holder, + to: constants.ZERO_ADDRESS, + value: '0', + }); + + await expectEvent.inTransaction(tx, this.vault, 'Withdraw', { + sender: holder, + receiver: recipient, + owner: holder, + assets: '0', + shares: '0', + }); + }); + + it('redeem', async function () { + expect(await this.vault.maxRedeem(holder)).to.be.bignumber.equal('0'); + expect(await this.vault.previewRedeem('0')).to.be.bignumber.equal('0'); + + const { tx } = await this.vault.redeem('0', recipient, holder, { from: holder }); + + await expectEvent.inTransaction(tx, this.token, 'Transfer', { + from: this.vault.address, + to: recipient, + value: '0', + }); + + await expectEvent.inTransaction(tx, this.vault, 'Transfer', { + from: holder, + to: constants.ZERO_ADDRESS, + value: '0', + }); + + await expectEvent.inTransaction(tx, this.vault, 'Withdraw', { + sender: holder, + receiver: recipient, + owner: holder, + assets: '0', + shares: '0', + }); + }); + }); + + describe('inflation attack: offset price by direct deposit of assets', function () { + beforeEach(async function () { + // Donate 1 token to the vault to offset the price + await this.token.$_mint(this.vault.address, parseToken(1)); + }); + + it('status', async function () { + expect(await this.vault.totalSupply()).to.be.bignumber.equal('0'); + expect(await this.vault.totalAssets()).to.be.bignumber.equal(parseToken(1)); + }); + + /** + * | offset | deposited assets | redeemable assets | + * |--------|----------------------|----------------------| + * | 0 | 1.000000000000000000 | 0. | + * | 6 | 1.000000000000000000 | 0.999999000000000000 | + * | 18 | 1.000000000000000000 | 0.999999999999999999 | + * + * Attack is possible, but made difficult by the offset. For the attack to be successful + * the attacker needs to frontrun a deposit 10**offset times bigger than what the victim + * was trying to deposit + */ + it('deposit', async function () { + const effectiveAssets = await this.vault.totalAssets().then(x => x.add(virtualAssets)); + const effectiveShares = await this.vault.totalSupply().then(x => x.add(virtualShares)); + + const depositAssets = parseToken(1); + const expectedShares = depositAssets.mul(effectiveShares).div(effectiveAssets); + + expect(await this.vault.maxDeposit(holder)).to.be.bignumber.equal(constants.MAX_UINT256); + expect(await this.vault.previewDeposit(depositAssets)).to.be.bignumber.equal(expectedShares); + + const { tx } = await this.vault.deposit(depositAssets, recipient, { from: holder }); + + await expectEvent.inTransaction(tx, this.token, 'Transfer', { + from: holder, + to: this.vault.address, + value: depositAssets, + }); + + await expectEvent.inTransaction(tx, this.vault, 'Transfer', { + from: constants.ZERO_ADDRESS, + to: recipient, + value: expectedShares, + }); + + await expectEvent.inTransaction(tx, this.vault, 'Deposit', { + sender: holder, + owner: recipient, + assets: depositAssets, + shares: expectedShares, + }); + }); + + /** + * | offset | deposited assets | redeemable assets | + * |--------|----------------------|----------------------| + * | 0 | 1000000000000000001. | 1000000000000000001. | + * | 6 | 1000000000000000001. | 1000000000000000001. | + * | 18 | 1000000000000000001. | 1000000000000000001. | + * + * Using mint protects against inflation attack, but makes minting shares very expensive. + * The ER20 allowance for the underlying asset is needed to protect the user from (too) + * large deposits. + */ + it('mint', async function () { + const effectiveAssets = await this.vault.totalAssets().then(x => x.add(virtualAssets)); + const effectiveShares = await this.vault.totalSupply().then(x => x.add(virtualShares)); + + const mintShares = parseShare(1); + const expectedAssets = mintShares.mul(effectiveAssets).div(effectiveShares); + + expect(await this.vault.maxMint(holder)).to.be.bignumber.equal(constants.MAX_UINT256); + expect(await this.vault.previewMint(mintShares)).to.be.bignumber.equal(expectedAssets); + + const { tx } = await this.vault.mint(mintShares, recipient, { from: holder }); + + await expectEvent.inTransaction(tx, this.token, 'Transfer', { + from: holder, + to: this.vault.address, + value: expectedAssets, + }); + + await expectEvent.inTransaction(tx, this.vault, 'Transfer', { + from: constants.ZERO_ADDRESS, + to: recipient, + value: mintShares, + }); + + await expectEvent.inTransaction(tx, this.vault, 'Deposit', { + sender: holder, + owner: recipient, + assets: expectedAssets, + shares: mintShares, + }); + }); + + it('withdraw', async function () { + expect(await this.vault.maxWithdraw(holder)).to.be.bignumber.equal('0'); + expect(await this.vault.previewWithdraw('0')).to.be.bignumber.equal('0'); + + const { tx } = await this.vault.withdraw('0', recipient, holder, { from: holder }); + + await expectEvent.inTransaction(tx, this.token, 'Transfer', { + from: this.vault.address, + to: recipient, + value: '0', + }); + + await expectEvent.inTransaction(tx, this.vault, 'Transfer', { + from: holder, + to: constants.ZERO_ADDRESS, + value: '0', + }); + + await expectEvent.inTransaction(tx, this.vault, 'Withdraw', { + sender: holder, + receiver: recipient, + owner: holder, + assets: '0', + shares: '0', + }); + }); + + it('redeem', async function () { + expect(await this.vault.maxRedeem(holder)).to.be.bignumber.equal('0'); + expect(await this.vault.previewRedeem('0')).to.be.bignumber.equal('0'); + + const { tx } = await this.vault.redeem('0', recipient, holder, { from: holder }); + + await expectEvent.inTransaction(tx, this.token, 'Transfer', { + from: this.vault.address, + to: recipient, + value: '0', + }); + + await expectEvent.inTransaction(tx, this.vault, 'Transfer', { + from: holder, + to: constants.ZERO_ADDRESS, + value: '0', + }); + + await expectEvent.inTransaction(tx, this.vault, 'Withdraw', { + sender: holder, + receiver: recipient, + owner: holder, + assets: '0', + shares: '0', + }); + }); + }); + + describe('full vault: assets & shares', function () { + beforeEach(async function () { + // Add 1 token of underlying asset and 100 shares to the vault + await this.token.$_mint(this.vault.address, parseToken(1)); + await this.vault.$_mint(holder, parseShare(100)); + }); + + it('status', async function () { + expect(await this.vault.totalSupply()).to.be.bignumber.equal(parseShare(100)); + expect(await this.vault.totalAssets()).to.be.bignumber.equal(parseToken(1)); + }); + + /** + * | offset | deposited assets | redeemable assets | + * |--------|--------------------- |----------------------| + * | 0 | 1.000000000000000000 | 0.999999999999999999 | + * | 6 | 1.000000000000000000 | 0.999999999999999999 | + * | 18 | 1.000000000000000000 | 0.999999999999999999 | + * + * Virtual shares & assets captures part of the value + */ + it('deposit', async function () { + const effectiveAssets = await this.vault.totalAssets().then(x => x.add(virtualAssets)); + const effectiveShares = await this.vault.totalSupply().then(x => x.add(virtualShares)); + + const depositAssets = parseToken(1); + const expectedShares = depositAssets.mul(effectiveShares).div(effectiveAssets); + + expect(await this.vault.maxDeposit(holder)).to.be.bignumber.equal(constants.MAX_UINT256); + expect(await this.vault.previewDeposit(depositAssets)).to.be.bignumber.equal(expectedShares); + + const { tx } = await this.vault.deposit(depositAssets, recipient, { from: holder }); + + await expectEvent.inTransaction(tx, this.token, 'Transfer', { + from: holder, + to: this.vault.address, + value: depositAssets, + }); + + await expectEvent.inTransaction(tx, this.vault, 'Transfer', { + from: constants.ZERO_ADDRESS, + to: recipient, + value: expectedShares, + }); + + await expectEvent.inTransaction(tx, this.vault, 'Deposit', { + sender: holder, + owner: recipient, + assets: depositAssets, + shares: expectedShares, + }); + }); + + /** + * | offset | deposited assets | redeemable assets | + * |--------|--------------------- |----------------------| + * | 0 | 0.010000000000000001 | 0.010000000000000000 | + * | 6 | 0.010000000000000001 | 0.010000000000000000 | + * | 18 | 0.010000000000000001 | 0.010000000000000000 | + * + * Virtual shares & assets captures part of the value + */ + it('mint', async function () { + const effectiveAssets = await this.vault.totalAssets().then(x => x.add(virtualAssets)); + const effectiveShares = await this.vault.totalSupply().then(x => x.add(virtualShares)); + + const mintShares = parseShare(1); + const expectedAssets = mintShares.mul(effectiveAssets).div(effectiveShares).addn(1); // add for the rounding + + expect(await this.vault.maxMint(holder)).to.be.bignumber.equal(constants.MAX_UINT256); + expect(await this.vault.previewMint(mintShares)).to.be.bignumber.equal(expectedAssets); + + const { tx } = await this.vault.mint(mintShares, recipient, { from: holder }); + + await expectEvent.inTransaction(tx, this.token, 'Transfer', { + from: holder, + to: this.vault.address, + value: expectedAssets, + }); + + await expectEvent.inTransaction(tx, this.vault, 'Transfer', { + from: constants.ZERO_ADDRESS, + to: recipient, + value: mintShares, + }); + + await expectEvent.inTransaction(tx, this.vault, 'Deposit', { + sender: holder, + owner: recipient, + assets: expectedAssets, + shares: mintShares, + }); + }); + + it('withdraw', async function () { + const effectiveAssets = await this.vault.totalAssets().then(x => x.add(virtualAssets)); + const effectiveShares = await this.vault.totalSupply().then(x => x.add(virtualShares)); + + const withdrawAssets = parseToken(1); + const expectedShares = withdrawAssets.mul(effectiveShares).div(effectiveAssets).addn(1); // add for the rounding + + expect(await this.vault.maxWithdraw(holder)).to.be.bignumber.equal(withdrawAssets); + expect(await this.vault.previewWithdraw(withdrawAssets)).to.be.bignumber.equal(expectedShares); + + const { tx } = await this.vault.withdraw(withdrawAssets, recipient, holder, { from: holder }); + + await expectEvent.inTransaction(tx, this.token, 'Transfer', { + from: this.vault.address, + to: recipient, + value: withdrawAssets, + }); + + await expectEvent.inTransaction(tx, this.vault, 'Transfer', { + from: holder, + to: constants.ZERO_ADDRESS, + value: expectedShares, + }); + + await expectEvent.inTransaction(tx, this.vault, 'Withdraw', { + sender: holder, + receiver: recipient, + owner: holder, + assets: withdrawAssets, + shares: expectedShares, + }); + }); + + it('withdraw with approval', async function () { + const assets = await this.vault.previewWithdraw(parseToken(1)); + await expectRevertCustomError( + this.vault.withdraw(parseToken(1), recipient, holder, { from: other }), + 'ERC20InsufficientAllowance', + [other, 0, assets], + ); + + await this.vault.withdraw(parseToken(1), recipient, holder, { from: spender }); + }); + + it('redeem', async function () { + const effectiveAssets = await this.vault.totalAssets().then(x => x.add(virtualAssets)); + const effectiveShares = await this.vault.totalSupply().then(x => x.add(virtualShares)); + + const redeemShares = parseShare(100); + const expectedAssets = redeemShares.mul(effectiveAssets).div(effectiveShares); + + expect(await this.vault.maxRedeem(holder)).to.be.bignumber.equal(redeemShares); + expect(await this.vault.previewRedeem(redeemShares)).to.be.bignumber.equal(expectedAssets); + + const { tx } = await this.vault.redeem(redeemShares, recipient, holder, { from: holder }); + + await expectEvent.inTransaction(tx, this.token, 'Transfer', { + from: this.vault.address, + to: recipient, + value: expectedAssets, + }); + + await expectEvent.inTransaction(tx, this.vault, 'Transfer', { + from: holder, + to: constants.ZERO_ADDRESS, + value: redeemShares, + }); + + await expectEvent.inTransaction(tx, this.vault, 'Withdraw', { + sender: holder, + receiver: recipient, + owner: holder, + assets: expectedAssets, + shares: redeemShares, + }); + }); + + it('redeem with approval', async function () { + await expectRevertCustomError( + this.vault.redeem(parseShare(100), recipient, holder, { from: other }), + 'ERC20InsufficientAllowance', + [other, 0, parseShare(100)], + ); + + await this.vault.redeem(parseShare(100), recipient, holder, { from: spender }); + }); + }); + }); + } + + describe('ERC4626Fees', function () { + const feeBasisPoints = web3.utils.toBN(5e3); + const valueWithoutFees = web3.utils.toBN(10000); + const fees = valueWithoutFees.mul(feeBasisPoints).divn(1e4); + const valueWithFees = valueWithoutFees.add(fees); + + describe('input fees', function () { + beforeEach(async function () { + this.token = await ERC20Decimals.new(name, symbol, 18); + this.vault = await ERC4626FeesMock.new( + name + ' Vault', + symbol + 'V', + this.token.address, + feeBasisPoints, + other, + 0, + constants.ZERO_ADDRESS, + ); + + await this.token.$_mint(holder, constants.MAX_INT256); + await this.token.approve(this.vault.address, constants.MAX_INT256, { from: holder }); + }); + + it('deposit', async function () { + expect(await this.vault.previewDeposit(valueWithFees)).to.be.bignumber.equal(valueWithoutFees); + ({ tx: this.tx } = await this.vault.deposit(valueWithFees, recipient, { from: holder })); + }); + + it('mint', async function () { + expect(await this.vault.previewMint(valueWithoutFees)).to.be.bignumber.equal(valueWithFees); + ({ tx: this.tx } = await this.vault.mint(valueWithoutFees, recipient, { from: holder })); + }); + + afterEach(async function () { + // get total + await expectEvent.inTransaction(this.tx, this.token, 'Transfer', { + from: holder, + to: this.vault.address, + value: valueWithFees, + }); + + // redirect fees + await expectEvent.inTransaction(this.tx, this.token, 'Transfer', { + from: this.vault.address, + to: other, + value: fees, + }); + + // mint shares + await expectEvent.inTransaction(this.tx, this.vault, 'Transfer', { + from: constants.ZERO_ADDRESS, + to: recipient, + value: valueWithoutFees, + }); + + // deposit event + await expectEvent.inTransaction(this.tx, this.vault, 'Deposit', { + sender: holder, + owner: recipient, + assets: valueWithFees, + shares: valueWithoutFees, + }); + }); + }); + + describe('output fees', function () { + beforeEach(async function () { + this.token = await ERC20Decimals.new(name, symbol, 18); + this.vault = await ERC4626FeesMock.new( + name + ' Vault', + symbol + 'V', + this.token.address, + 0, + constants.ZERO_ADDRESS, + 5e3, // 5% + other, + ); + + await this.token.$_mint(this.vault.address, constants.MAX_INT256); + await this.vault.$_mint(holder, constants.MAX_INT256); + }); + + it('redeem', async function () { + expect(await this.vault.previewRedeem(valueWithFees)).to.be.bignumber.equal(valueWithoutFees); + ({ tx: this.tx } = await this.vault.redeem(valueWithFees, recipient, holder, { from: holder })); + }); + + it('withdraw', async function () { + expect(await this.vault.previewWithdraw(valueWithoutFees)).to.be.bignumber.equal(valueWithFees); + ({ tx: this.tx } = await this.vault.withdraw(valueWithoutFees, recipient, holder, { from: holder })); + }); + + afterEach(async function () { + // withdraw principal + await expectEvent.inTransaction(this.tx, this.token, 'Transfer', { + from: this.vault.address, + to: recipient, + value: valueWithoutFees, + }); + + // redirect fees + await expectEvent.inTransaction(this.tx, this.token, 'Transfer', { + from: this.vault.address, + to: other, + value: fees, + }); + + // mint shares + await expectEvent.inTransaction(this.tx, this.vault, 'Transfer', { + from: holder, + to: constants.ZERO_ADDRESS, + value: valueWithFees, + }); + + // withdraw event + await expectEvent.inTransaction(this.tx, this.vault, 'Withdraw', { + sender: holder, + receiver: recipient, + owner: holder, + assets: valueWithoutFees, + shares: valueWithFees, + }); + }); + }); + }); + + /// Scenario inspired by solmate ERC4626 tests: + /// https://github.com/transmissions11/solmate/blob/main/src/test/ERC4626.t.sol + it('multiple mint, deposit, redeem & withdrawal', async function () { + // test designed with both asset using similar decimals + this.token = await ERC20Decimals.new(name, symbol, 18); + this.vault = await ERC4626.new(name + ' Vault', symbol + 'V', this.token.address); + + await this.token.$_mint(user1, 4000); + await this.token.$_mint(user2, 7001); + await this.token.approve(this.vault.address, 4000, { from: user1 }); + await this.token.approve(this.vault.address, 7001, { from: user2 }); + + // 1. Alice mints 2000 shares (costs 2000 tokens) + { + const { tx } = await this.vault.mint(2000, user1, { from: user1 }); + await expectEvent.inTransaction(tx, this.token, 'Transfer', { + from: user1, + to: this.vault.address, + value: '2000', + }); + await expectEvent.inTransaction(tx, this.vault, 'Transfer', { + from: constants.ZERO_ADDRESS, + to: user1, + value: '2000', + }); + + expect(await this.vault.previewDeposit(2000)).to.be.bignumber.equal('2000'); + expect(await this.vault.balanceOf(user1)).to.be.bignumber.equal('2000'); + expect(await this.vault.balanceOf(user2)).to.be.bignumber.equal('0'); + expect(await this.vault.convertToAssets(await this.vault.balanceOf(user1))).to.be.bignumber.equal('2000'); + expect(await this.vault.convertToAssets(await this.vault.balanceOf(user2))).to.be.bignumber.equal('0'); + expect(await this.vault.convertToShares(await this.token.balanceOf(this.vault.address))).to.be.bignumber.equal( + '2000', + ); + expect(await this.vault.totalSupply()).to.be.bignumber.equal('2000'); + expect(await this.vault.totalAssets()).to.be.bignumber.equal('2000'); + } + + // 2. Bob deposits 4000 tokens (mints 4000 shares) + { + const { tx } = await this.vault.mint(4000, user2, { from: user2 }); + await expectEvent.inTransaction(tx, this.token, 'Transfer', { + from: user2, + to: this.vault.address, + value: '4000', + }); + await expectEvent.inTransaction(tx, this.vault, 'Transfer', { + from: constants.ZERO_ADDRESS, + to: user2, + value: '4000', + }); + + expect(await this.vault.previewDeposit(4000)).to.be.bignumber.equal('4000'); + expect(await this.vault.balanceOf(user1)).to.be.bignumber.equal('2000'); + expect(await this.vault.balanceOf(user2)).to.be.bignumber.equal('4000'); + expect(await this.vault.convertToAssets(await this.vault.balanceOf(user1))).to.be.bignumber.equal('2000'); + expect(await this.vault.convertToAssets(await this.vault.balanceOf(user2))).to.be.bignumber.equal('4000'); + expect(await this.vault.convertToShares(await this.token.balanceOf(this.vault.address))).to.be.bignumber.equal( + '6000', + ); + expect(await this.vault.totalSupply()).to.be.bignumber.equal('6000'); + expect(await this.vault.totalAssets()).to.be.bignumber.equal('6000'); + } + + // 3. Vault mutates by +3000 tokens (simulated yield returned from strategy) + await this.token.$_mint(this.vault.address, 3000); + + expect(await this.vault.balanceOf(user1)).to.be.bignumber.equal('2000'); + expect(await this.vault.balanceOf(user2)).to.be.bignumber.equal('4000'); + expect(await this.vault.convertToAssets(await this.vault.balanceOf(user1))).to.be.bignumber.equal('2999'); // used to be 3000, but virtual assets/shares captures part of the yield + expect(await this.vault.convertToAssets(await this.vault.balanceOf(user2))).to.be.bignumber.equal('5999'); // used to be 6000, but virtual assets/shares captures part of the yield + expect(await this.vault.convertToShares(await this.token.balanceOf(this.vault.address))).to.be.bignumber.equal( + '6000', + ); + expect(await this.vault.totalSupply()).to.be.bignumber.equal('6000'); + expect(await this.vault.totalAssets()).to.be.bignumber.equal('9000'); + + // 4. Alice deposits 2000 tokens (mints 1333 shares) + { + const { tx } = await this.vault.deposit(2000, user1, { from: user1 }); + await expectEvent.inTransaction(tx, this.token, 'Transfer', { + from: user1, + to: this.vault.address, + value: '2000', + }); + await expectEvent.inTransaction(tx, this.vault, 'Transfer', { + from: constants.ZERO_ADDRESS, + to: user1, + value: '1333', + }); + + expect(await this.vault.balanceOf(user1)).to.be.bignumber.equal('3333'); + expect(await this.vault.balanceOf(user2)).to.be.bignumber.equal('4000'); + expect(await this.vault.convertToAssets(await this.vault.balanceOf(user1))).to.be.bignumber.equal('4999'); + expect(await this.vault.convertToAssets(await this.vault.balanceOf(user2))).to.be.bignumber.equal('6000'); + expect(await this.vault.convertToShares(await this.token.balanceOf(this.vault.address))).to.be.bignumber.equal( + '7333', + ); + expect(await this.vault.totalSupply()).to.be.bignumber.equal('7333'); + expect(await this.vault.totalAssets()).to.be.bignumber.equal('11000'); + } + + // 5. Bob mints 2000 shares (costs 3001 assets) + // NOTE: Bob's assets spent got rounded towards infinity + // NOTE: Alices's vault assets got rounded towards infinity + { + const { tx } = await this.vault.mint(2000, user2, { from: user2 }); + await expectEvent.inTransaction(tx, this.token, 'Transfer', { + from: user2, + to: this.vault.address, + value: '3000', // used to be 3001 + }); + await expectEvent.inTransaction(tx, this.vault, 'Transfer', { + from: constants.ZERO_ADDRESS, + to: user2, + value: '2000', + }); + + expect(await this.vault.balanceOf(user1)).to.be.bignumber.equal('3333'); + expect(await this.vault.balanceOf(user2)).to.be.bignumber.equal('6000'); + expect(await this.vault.convertToAssets(await this.vault.balanceOf(user1))).to.be.bignumber.equal('4999'); // used to be 5000 + expect(await this.vault.convertToAssets(await this.vault.balanceOf(user2))).to.be.bignumber.equal('9000'); + expect(await this.vault.convertToShares(await this.token.balanceOf(this.vault.address))).to.be.bignumber.equal( + '9333', + ); + expect(await this.vault.totalSupply()).to.be.bignumber.equal('9333'); + expect(await this.vault.totalAssets()).to.be.bignumber.equal('14000'); // used to be 14001 + } + + // 6. Vault mutates by +3000 tokens + // NOTE: Vault holds 17001 tokens, but sum of assetsOf() is 17000. + await this.token.$_mint(this.vault.address, 3000); + + expect(await this.vault.balanceOf(user1)).to.be.bignumber.equal('3333'); + expect(await this.vault.balanceOf(user2)).to.be.bignumber.equal('6000'); + expect(await this.vault.convertToAssets(await this.vault.balanceOf(user1))).to.be.bignumber.equal('6070'); // used to be 6071 + expect(await this.vault.convertToAssets(await this.vault.balanceOf(user2))).to.be.bignumber.equal('10928'); // used to be 10929 + expect(await this.vault.convertToShares(await this.token.balanceOf(this.vault.address))).to.be.bignumber.equal( + '9333', + ); + expect(await this.vault.totalSupply()).to.be.bignumber.equal('9333'); + expect(await this.vault.totalAssets()).to.be.bignumber.equal('17000'); // used to be 17001 + + // 7. Alice redeem 1333 shares (2428 assets) + { + const { tx } = await this.vault.redeem(1333, user1, user1, { from: user1 }); + await expectEvent.inTransaction(tx, this.vault, 'Transfer', { + from: user1, + to: constants.ZERO_ADDRESS, + value: '1333', + }); + await expectEvent.inTransaction(tx, this.token, 'Transfer', { + from: this.vault.address, + to: user1, + value: '2427', // used to be 2428 + }); + + expect(await this.vault.balanceOf(user1)).to.be.bignumber.equal('2000'); + expect(await this.vault.balanceOf(user2)).to.be.bignumber.equal('6000'); + expect(await this.vault.convertToAssets(await this.vault.balanceOf(user1))).to.be.bignumber.equal('3643'); + expect(await this.vault.convertToAssets(await this.vault.balanceOf(user2))).to.be.bignumber.equal('10929'); + expect(await this.vault.convertToShares(await this.token.balanceOf(this.vault.address))).to.be.bignumber.equal( + '8000', + ); + expect(await this.vault.totalSupply()).to.be.bignumber.equal('8000'); + expect(await this.vault.totalAssets()).to.be.bignumber.equal('14573'); + } + + // 8. Bob withdraws 2929 assets (1608 shares) + { + const { tx } = await this.vault.withdraw(2929, user2, user2, { from: user2 }); + await expectEvent.inTransaction(tx, this.vault, 'Transfer', { + from: user2, + to: constants.ZERO_ADDRESS, + value: '1608', + }); + await expectEvent.inTransaction(tx, this.token, 'Transfer', { + from: this.vault.address, + to: user2, + value: '2929', + }); + + expect(await this.vault.balanceOf(user1)).to.be.bignumber.equal('2000'); + expect(await this.vault.balanceOf(user2)).to.be.bignumber.equal('4392'); + expect(await this.vault.convertToAssets(await this.vault.balanceOf(user1))).to.be.bignumber.equal('3643'); + expect(await this.vault.convertToAssets(await this.vault.balanceOf(user2))).to.be.bignumber.equal('8000'); + expect(await this.vault.convertToShares(await this.token.balanceOf(this.vault.address))).to.be.bignumber.equal( + '6392', + ); + expect(await this.vault.totalSupply()).to.be.bignumber.equal('6392'); + expect(await this.vault.totalAssets()).to.be.bignumber.equal('11644'); + } + + // 9. Alice withdraws 3643 assets (2000 shares) + // NOTE: Bob's assets have been rounded back towards infinity + { + const { tx } = await this.vault.withdraw(3643, user1, user1, { from: user1 }); + await expectEvent.inTransaction(tx, this.vault, 'Transfer', { + from: user1, + to: constants.ZERO_ADDRESS, + value: '2000', + }); + await expectEvent.inTransaction(tx, this.token, 'Transfer', { + from: this.vault.address, + to: user1, + value: '3643', + }); + + expect(await this.vault.balanceOf(user1)).to.be.bignumber.equal('0'); + expect(await this.vault.balanceOf(user2)).to.be.bignumber.equal('4392'); + expect(await this.vault.convertToAssets(await this.vault.balanceOf(user1))).to.be.bignumber.equal('0'); + expect(await this.vault.convertToAssets(await this.vault.balanceOf(user2))).to.be.bignumber.equal('8000'); // used to be 8001 + expect(await this.vault.convertToShares(await this.token.balanceOf(this.vault.address))).to.be.bignumber.equal( + '4392', + ); + expect(await this.vault.totalSupply()).to.be.bignumber.equal('4392'); + expect(await this.vault.totalAssets()).to.be.bignumber.equal('8001'); + } + + // 10. Bob redeem 4392 shares (8001 tokens) + { + const { tx } = await this.vault.redeem(4392, user2, user2, { from: user2 }); + await expectEvent.inTransaction(tx, this.vault, 'Transfer', { + from: user2, + to: constants.ZERO_ADDRESS, + value: '4392', + }); + await expectEvent.inTransaction(tx, this.token, 'Transfer', { + from: this.vault.address, + to: user2, + value: '8000', // used to be 8001 + }); + + expect(await this.vault.balanceOf(user1)).to.be.bignumber.equal('0'); + expect(await this.vault.balanceOf(user2)).to.be.bignumber.equal('0'); + expect(await this.vault.convertToAssets(await this.vault.balanceOf(user1))).to.be.bignumber.equal('0'); + expect(await this.vault.convertToAssets(await this.vault.balanceOf(user2))).to.be.bignumber.equal('0'); + expect(await this.vault.convertToShares(await this.token.balanceOf(this.vault.address))).to.be.bignumber.equal( + '0', + ); + expect(await this.vault.totalSupply()).to.be.bignumber.equal('0'); + expect(await this.vault.totalAssets()).to.be.bignumber.equal('1'); // used to be 0 + } + }); +}); diff --git a/test/token/ERC20/utils/SafeERC20.test.js b/test/token/ERC20/utils/SafeERC20.test.js new file mode 100644 index 000000000..4ff27f14d --- /dev/null +++ b/test/token/ERC20/utils/SafeERC20.test.js @@ -0,0 +1,240 @@ +const { constants, expectEvent, expectRevert } = require('@openzeppelin/test-helpers'); + +const SafeERC20 = artifacts.require('$SafeERC20'); +const ERC20ReturnFalseMock = artifacts.require('$ERC20ReturnFalseMock'); +const ERC20ReturnTrueMock = artifacts.require('$ERC20'); // default implementation returns true +const ERC20NoReturnMock = artifacts.require('$ERC20NoReturnMock'); +const ERC20ForceApproveMock = artifacts.require('$ERC20ForceApproveMock'); + +const { expectRevertCustomError } = require('../../../helpers/customError'); + +const name = 'ERC20Mock'; +const symbol = 'ERC20Mock'; + +contract('SafeERC20', function (accounts) { + const [hasNoCode, receiver, spender] = accounts; + + before(async function () { + this.mock = await SafeERC20.new(); + }); + + describe('with address that has no contract code', function () { + beforeEach(async function () { + this.token = { address: hasNoCode }; + }); + + it('reverts on transfer', async function () { + await expectRevertCustomError(this.mock.$safeTransfer(this.token.address, receiver, 0), 'AddressEmptyCode', [ + this.token.address, + ]); + }); + + it('reverts on transferFrom', async function () { + await expectRevertCustomError( + this.mock.$safeTransferFrom(this.token.address, this.mock.address, receiver, 0), + 'AddressEmptyCode', + [this.token.address], + ); + }); + + it('reverts on increaseAllowance', async function () { + // Call to 'token.allowance' does not return any data, resulting in a decoding error (revert without reason) + await expectRevert.unspecified(this.mock.$safeIncreaseAllowance(this.token.address, spender, 0)); + }); + + it('reverts on decreaseAllowance', async function () { + // Call to 'token.allowance' does not return any data, resulting in a decoding error (revert without reason) + await expectRevert.unspecified(this.mock.$safeDecreaseAllowance(this.token.address, spender, 0)); + }); + + it('reverts on forceApprove', async function () { + await expectRevertCustomError(this.mock.$forceApprove(this.token.address, spender, 0), 'AddressEmptyCode', [ + this.token.address, + ]); + }); + }); + + describe('with token that returns false on all calls', function () { + beforeEach(async function () { + this.token = await ERC20ReturnFalseMock.new(name, symbol); + }); + + it('reverts on transfer', async function () { + await expectRevertCustomError( + this.mock.$safeTransfer(this.token.address, receiver, 0), + 'SafeERC20FailedOperation', + [this.token.address], + ); + }); + + it('reverts on transferFrom', async function () { + await expectRevertCustomError( + this.mock.$safeTransferFrom(this.token.address, this.mock.address, receiver, 0), + 'SafeERC20FailedOperation', + [this.token.address], + ); + }); + + it('reverts on increaseAllowance', async function () { + await expectRevertCustomError( + this.mock.$safeIncreaseAllowance(this.token.address, spender, 0), + 'SafeERC20FailedOperation', + [this.token.address], + ); + }); + + it('reverts on decreaseAllowance', async function () { + await expectRevertCustomError( + this.mock.$safeDecreaseAllowance(this.token.address, spender, 0), + 'SafeERC20FailedOperation', + [this.token.address], + ); + }); + + it('reverts on forceApprove', async function () { + await expectRevertCustomError( + this.mock.$forceApprove(this.token.address, spender, 0), + 'SafeERC20FailedOperation', + [this.token.address], + ); + }); + }); + + describe('with token that returns true on all calls', function () { + beforeEach(async function () { + this.token = await ERC20ReturnTrueMock.new(name, symbol); + }); + + shouldOnlyRevertOnErrors(accounts); + }); + + describe('with token that returns no boolean values', function () { + beforeEach(async function () { + this.token = await ERC20NoReturnMock.new(name, symbol); + }); + + shouldOnlyRevertOnErrors(accounts); + }); + + describe('with usdt approval beaviour', function () { + const spender = hasNoCode; + + beforeEach(async function () { + this.token = await ERC20ForceApproveMock.new(name, symbol); + }); + + describe('with initial approval', function () { + beforeEach(async function () { + await this.token.$_approve(this.mock.address, spender, 100); + }); + + it('safeIncreaseAllowance works', async function () { + await this.mock.$safeIncreaseAllowance(this.token.address, spender, 10); + expect(this.token.allowance(this.mock.address, spender, 90)); + }); + + it('safeDecreaseAllowance works', async function () { + await this.mock.$safeDecreaseAllowance(this.token.address, spender, 10); + expect(this.token.allowance(this.mock.address, spender, 110)); + }); + + it('forceApprove works', async function () { + await this.mock.$forceApprove(this.token.address, spender, 200); + expect(this.token.allowance(this.mock.address, spender, 200)); + }); + }); + }); +}); + +function shouldOnlyRevertOnErrors([owner, receiver, spender]) { + describe('transfers', function () { + beforeEach(async function () { + await this.token.$_mint(owner, 100); + await this.token.$_mint(this.mock.address, 100); + await this.token.approve(this.mock.address, constants.MAX_UINT256, { from: owner }); + }); + + it("doesn't revert on transfer", async function () { + const { tx } = await this.mock.$safeTransfer(this.token.address, receiver, 10); + await expectEvent.inTransaction(tx, this.token, 'Transfer', { + from: this.mock.address, + to: receiver, + value: '10', + }); + }); + + it("doesn't revert on transferFrom", async function () { + const { tx } = await this.mock.$safeTransferFrom(this.token.address, owner, receiver, 10); + await expectEvent.inTransaction(tx, this.token, 'Transfer', { + from: owner, + to: receiver, + value: '10', + }); + }); + }); + + describe('approvals', function () { + context('with zero allowance', function () { + beforeEach(async function () { + await this.token.$_approve(this.mock.address, spender, 0); + }); + + it("doesn't revert when force approving a non-zero allowance", async function () { + await this.mock.$forceApprove(this.token.address, spender, 100); + expect(await this.token.allowance(this.mock.address, spender)).to.be.bignumber.equal('100'); + }); + + it("doesn't revert when force approving a zero allowance", async function () { + await this.mock.$forceApprove(this.token.address, spender, 0); + expect(await this.token.allowance(this.mock.address, spender)).to.be.bignumber.equal('0'); + }); + + it("doesn't revert when increasing the allowance", async function () { + await this.mock.$safeIncreaseAllowance(this.token.address, spender, 10); + expect(await this.token.allowance(this.mock.address, spender)).to.be.bignumber.equal('10'); + }); + + it('reverts when decreasing the allowance', async function () { + await expectRevertCustomError( + this.mock.$safeDecreaseAllowance(this.token.address, spender, 10), + 'SafeERC20FailedDecreaseAllowance', + [spender, 0, 10], + ); + }); + }); + + context('with non-zero allowance', function () { + beforeEach(async function () { + await this.token.$_approve(this.mock.address, spender, 100); + }); + + it("doesn't revert when force approving a non-zero allowance", async function () { + await this.mock.$forceApprove(this.token.address, spender, 20); + expect(await this.token.allowance(this.mock.address, spender)).to.be.bignumber.equal('20'); + }); + + it("doesn't revert when force approving a zero allowance", async function () { + await this.mock.$forceApprove(this.token.address, spender, 0); + expect(await this.token.allowance(this.mock.address, spender)).to.be.bignumber.equal('0'); + }); + + it("doesn't revert when increasing the allowance", async function () { + await this.mock.$safeIncreaseAllowance(this.token.address, spender, 10); + expect(await this.token.allowance(this.mock.address, spender)).to.be.bignumber.equal('110'); + }); + + it("doesn't revert when decreasing the allowance to a positive value", async function () { + await this.mock.$safeDecreaseAllowance(this.token.address, spender, 50); + expect(await this.token.allowance(this.mock.address, spender)).to.be.bignumber.equal('50'); + }); + + it('reverts when decreasing the allowance to a negative value', async function () { + await expectRevertCustomError( + this.mock.$safeDecreaseAllowance(this.token.address, spender, 200), + 'SafeERC20FailedDecreaseAllowance', + [spender, 100, 200], + ); + }); + }); + }); +} diff --git a/test/token/ERC721/ERC721.behavior.js b/test/token/ERC721/ERC721.behavior.js new file mode 100644 index 000000000..10f848265 --- /dev/null +++ b/test/token/ERC721/ERC721.behavior.js @@ -0,0 +1,978 @@ +const { BN, constants, expectEvent, expectRevert } = require('@openzeppelin/test-helpers'); +const { expect } = require('chai'); +const { ZERO_ADDRESS } = constants; + +const { shouldSupportInterfaces } = require('../../utils/introspection/SupportsInterface.behavior'); +const { expectRevertCustomError } = require('../../helpers/customError'); +const { Enum } = require('../../helpers/enums'); + +const ERC721ReceiverMock = artifacts.require('ERC721ReceiverMock'); +const NonERC721ReceiverMock = artifacts.require('CallReceiverMock'); + +const RevertType = Enum('None', 'RevertWithoutMessage', 'RevertWithMessage', 'RevertWithCustomError', 'Panic'); + +const firstTokenId = new BN('5042'); +const secondTokenId = new BN('79217'); +const nonExistentTokenId = new BN('13'); +const fourthTokenId = new BN(4); +const baseURI = 'https://api.example.com/v1/'; + +const RECEIVER_MAGIC_VALUE = '0x150b7a02'; + +function shouldBehaveLikeERC721(owner, newOwner, approved, anotherApproved, operator, other) { + shouldSupportInterfaces(['ERC165', 'ERC721']); + + context('with minted tokens', function () { + beforeEach(async function () { + await this.token.$_mint(owner, firstTokenId); + await this.token.$_mint(owner, secondTokenId); + this.toWhom = other; // default to other for toWhom in context-dependent tests + }); + + describe('balanceOf', function () { + context('when the given address owns some tokens', function () { + it('returns the amount of tokens owned by the given address', async function () { + expect(await this.token.balanceOf(owner)).to.be.bignumber.equal('2'); + }); + }); + + context('when the given address does not own any tokens', function () { + it('returns 0', async function () { + expect(await this.token.balanceOf(other)).to.be.bignumber.equal('0'); + }); + }); + + context('when querying the zero address', function () { + it('throws', async function () { + await expectRevertCustomError(this.token.balanceOf(ZERO_ADDRESS), 'ERC721InvalidOwner', [ZERO_ADDRESS]); + }); + }); + }); + + describe('ownerOf', function () { + context('when the given token ID was tracked by this token', function () { + const tokenId = firstTokenId; + + it('returns the owner of the given token ID', async function () { + expect(await this.token.ownerOf(tokenId)).to.be.equal(owner); + }); + }); + + context('when the given token ID was not tracked by this token', function () { + const tokenId = nonExistentTokenId; + + it('reverts', async function () { + await expectRevertCustomError(this.token.ownerOf(tokenId), 'ERC721NonexistentToken', [tokenId]); + }); + }); + }); + + describe('transfers', function () { + const tokenId = firstTokenId; + const data = '0x42'; + + let receipt = null; + + beforeEach(async function () { + await this.token.approve(approved, tokenId, { from: owner }); + await this.token.setApprovalForAll(operator, true, { from: owner }); + }); + + const transferWasSuccessful = function ({ owner, tokenId }) { + it('transfers the ownership of the given token ID to the given address', async function () { + expect(await this.token.ownerOf(tokenId)).to.be.equal(this.toWhom); + }); + + it('emits a Transfer event', async function () { + expectEvent(receipt, 'Transfer', { from: owner, to: this.toWhom, tokenId: tokenId }); + }); + + it('clears the approval for the token ID with no event', async function () { + expect(await this.token.getApproved(tokenId)).to.be.equal(ZERO_ADDRESS); + expectEvent.notEmitted(receipt, 'Approval'); + }); + + it('adjusts owners balances', async function () { + expect(await this.token.balanceOf(owner)).to.be.bignumber.equal('1'); + }); + + it('adjusts owners tokens by index', async function () { + if (!this.token.tokenOfOwnerByIndex) return; + + expect(await this.token.tokenOfOwnerByIndex(this.toWhom, 0)).to.be.bignumber.equal(tokenId); + + expect(await this.token.tokenOfOwnerByIndex(owner, 0)).to.be.bignumber.not.equal(tokenId); + }); + }; + + const shouldTransferTokensByUsers = function (transferFunction, opts = {}) { + context('when called by the owner', function () { + beforeEach(async function () { + receipt = await transferFunction.call(this, owner, this.toWhom, tokenId, { from: owner }); + }); + transferWasSuccessful({ owner, tokenId, approved }); + }); + + context('when called by the approved individual', function () { + beforeEach(async function () { + receipt = await transferFunction.call(this, owner, this.toWhom, tokenId, { from: approved }); + }); + transferWasSuccessful({ owner, tokenId, approved }); + }); + + context('when called by the operator', function () { + beforeEach(async function () { + receipt = await transferFunction.call(this, owner, this.toWhom, tokenId, { from: operator }); + }); + transferWasSuccessful({ owner, tokenId, approved }); + }); + + context('when called by the owner without an approved user', function () { + beforeEach(async function () { + await this.token.approve(ZERO_ADDRESS, tokenId, { from: owner }); + receipt = await transferFunction.call(this, owner, this.toWhom, tokenId, { from: operator }); + }); + transferWasSuccessful({ owner, tokenId, approved: null }); + }); + + context('when sent to the owner', function () { + beforeEach(async function () { + receipt = await transferFunction.call(this, owner, owner, tokenId, { from: owner }); + }); + + it('keeps ownership of the token', async function () { + expect(await this.token.ownerOf(tokenId)).to.be.equal(owner); + }); + + it('clears the approval for the token ID', async function () { + expect(await this.token.getApproved(tokenId)).to.be.equal(ZERO_ADDRESS); + }); + + it('emits only a transfer event', async function () { + expectEvent(receipt, 'Transfer', { + from: owner, + to: owner, + tokenId: tokenId, + }); + }); + + it('keeps the owner balance', async function () { + expect(await this.token.balanceOf(owner)).to.be.bignumber.equal('2'); + }); + + it('keeps same tokens by index', async function () { + if (!this.token.tokenOfOwnerByIndex) return; + const tokensListed = await Promise.all([0, 1].map(i => this.token.tokenOfOwnerByIndex(owner, i))); + expect(tokensListed.map(t => t.toNumber())).to.have.members([ + firstTokenId.toNumber(), + secondTokenId.toNumber(), + ]); + }); + }); + + context('when the address of the previous owner is incorrect', function () { + it('reverts', async function () { + await expectRevertCustomError( + transferFunction.call(this, other, other, tokenId, { from: owner }), + 'ERC721IncorrectOwner', + [other, tokenId, owner], + ); + }); + }); + + context('when the sender is not authorized for the token id', function () { + if (opts.unrestricted) { + it('does not revert', async function () { + await transferFunction.call(this, owner, other, tokenId, { from: other }); + }); + } else { + it('reverts', async function () { + await expectRevertCustomError( + transferFunction.call(this, owner, other, tokenId, { from: other }), + 'ERC721InsufficientApproval', + [other, tokenId], + ); + }); + } + }); + + context('when the given token ID does not exist', function () { + it('reverts', async function () { + await expectRevertCustomError( + transferFunction.call(this, owner, other, nonExistentTokenId, { from: owner }), + 'ERC721NonexistentToken', + [nonExistentTokenId], + ); + }); + }); + + context('when the address to transfer the token to is the zero address', function () { + it('reverts', async function () { + await expectRevertCustomError( + transferFunction.call(this, owner, ZERO_ADDRESS, tokenId, { from: owner }), + 'ERC721InvalidReceiver', + [ZERO_ADDRESS], + ); + }); + }); + }; + + const shouldTransferSafely = function (transferFun, data, opts = {}) { + describe('to a user account', function () { + shouldTransferTokensByUsers(transferFun, opts); + }); + + describe('to a valid receiver contract', function () { + beforeEach(async function () { + this.receiver = await ERC721ReceiverMock.new(RECEIVER_MAGIC_VALUE, RevertType.None); + this.toWhom = this.receiver.address; + }); + + shouldTransferTokensByUsers(transferFun, opts); + + it('calls onERC721Received', async function () { + const receipt = await transferFun.call(this, owner, this.receiver.address, tokenId, { from: owner }); + + await expectEvent.inTransaction(receipt.tx, ERC721ReceiverMock, 'Received', { + operator: owner, + from: owner, + tokenId: tokenId, + data: data, + }); + }); + + it('calls onERC721Received from approved', async function () { + const receipt = await transferFun.call(this, owner, this.receiver.address, tokenId, { from: approved }); + + await expectEvent.inTransaction(receipt.tx, ERC721ReceiverMock, 'Received', { + operator: approved, + from: owner, + tokenId: tokenId, + data: data, + }); + }); + + describe('with an invalid token id', function () { + it('reverts', async function () { + await expectRevertCustomError( + transferFun.call(this, owner, this.receiver.address, nonExistentTokenId, { from: owner }), + 'ERC721NonexistentToken', + [nonExistentTokenId], + ); + }); + }); + }); + }; + + for (const { fnName, opts } of [ + { fnName: 'transferFrom', opts: {} }, + { fnName: '$_transfer', opts: { unrestricted: true } }, + ]) { + describe(`via ${fnName}`, function () { + shouldTransferTokensByUsers(function (from, to, tokenId, opts) { + return this.token[fnName](from, to, tokenId, opts); + }, opts); + }); + } + + for (const { fnName, opts } of [ + { fnName: 'safeTransferFrom', opts: {} }, + { fnName: '$_safeTransfer', opts: { unrestricted: true } }, + ]) { + describe(`via ${fnName}`, function () { + const safeTransferFromWithData = function (from, to, tokenId, opts) { + return this.token.methods[fnName + '(address,address,uint256,bytes)'](from, to, tokenId, data, opts); + }; + + const safeTransferFromWithoutData = function (from, to, tokenId, opts) { + return this.token.methods[fnName + '(address,address,uint256)'](from, to, tokenId, opts); + }; + + describe('with data', function () { + shouldTransferSafely(safeTransferFromWithData, data, opts); + }); + + describe('without data', function () { + shouldTransferSafely(safeTransferFromWithoutData, null, opts); + }); + + describe('to a receiver contract returning unexpected value', function () { + it('reverts', async function () { + const invalidReceiver = await ERC721ReceiverMock.new('0x42', RevertType.None); + await expectRevertCustomError( + this.token.methods[fnName + '(address,address,uint256)'](owner, invalidReceiver.address, tokenId, { + from: owner, + }), + 'ERC721InvalidReceiver', + [invalidReceiver.address], + ); + }); + }); + + describe('to a receiver contract that reverts with message', function () { + it('reverts', async function () { + const revertingReceiver = await ERC721ReceiverMock.new( + RECEIVER_MAGIC_VALUE, + RevertType.RevertWithMessage, + ); + await expectRevert( + this.token.methods[fnName + '(address,address,uint256)'](owner, revertingReceiver.address, tokenId, { + from: owner, + }), + 'ERC721ReceiverMock: reverting', + ); + }); + }); + + describe('to a receiver contract that reverts without message', function () { + it('reverts', async function () { + const revertingReceiver = await ERC721ReceiverMock.new( + RECEIVER_MAGIC_VALUE, + RevertType.RevertWithoutMessage, + ); + await expectRevertCustomError( + this.token.methods[fnName + '(address,address,uint256)'](owner, revertingReceiver.address, tokenId, { + from: owner, + }), + 'ERC721InvalidReceiver', + [revertingReceiver.address], + ); + }); + }); + + describe('to a receiver contract that reverts with custom error', function () { + it('reverts', async function () { + const revertingReceiver = await ERC721ReceiverMock.new( + RECEIVER_MAGIC_VALUE, + RevertType.RevertWithCustomError, + ); + await expectRevertCustomError( + this.token.methods[fnName + '(address,address,uint256)'](owner, revertingReceiver.address, tokenId, { + from: owner, + }), + 'CustomError', + [RECEIVER_MAGIC_VALUE], + ); + }); + }); + + describe('to a receiver contract that panics', function () { + it('reverts', async function () { + const revertingReceiver = await ERC721ReceiverMock.new(RECEIVER_MAGIC_VALUE, RevertType.Panic); + await expectRevert.unspecified( + this.token.methods[fnName + '(address,address,uint256)'](owner, revertingReceiver.address, tokenId, { + from: owner, + }), + ); + }); + }); + + describe('to a contract that does not implement the required function', function () { + it('reverts', async function () { + const nonReceiver = await NonERC721ReceiverMock.new(); + await expectRevertCustomError( + this.token.methods[fnName + '(address,address,uint256)'](owner, nonReceiver.address, tokenId, { + from: owner, + }), + 'ERC721InvalidReceiver', + [nonReceiver.address], + ); + }); + }); + }); + } + }); + + describe('safe mint', function () { + const tokenId = fourthTokenId; + const data = '0x42'; + + describe('via safeMint', function () { + // regular minting is tested in ERC721Mintable.test.js and others + it('calls onERC721Received — with data', async function () { + this.receiver = await ERC721ReceiverMock.new(RECEIVER_MAGIC_VALUE, RevertType.None); + const receipt = await this.token.$_safeMint(this.receiver.address, tokenId, data); + + await expectEvent.inTransaction(receipt.tx, ERC721ReceiverMock, 'Received', { + from: ZERO_ADDRESS, + tokenId: tokenId, + data: data, + }); + }); + + it('calls onERC721Received — without data', async function () { + this.receiver = await ERC721ReceiverMock.new(RECEIVER_MAGIC_VALUE, RevertType.None); + const receipt = await this.token.$_safeMint(this.receiver.address, tokenId); + + await expectEvent.inTransaction(receipt.tx, ERC721ReceiverMock, 'Received', { + from: ZERO_ADDRESS, + tokenId: tokenId, + }); + }); + + context('to a receiver contract returning unexpected value', function () { + it('reverts', async function () { + const invalidReceiver = await ERC721ReceiverMock.new('0x42', RevertType.None); + await expectRevertCustomError( + this.token.$_safeMint(invalidReceiver.address, tokenId), + 'ERC721InvalidReceiver', + [invalidReceiver.address], + ); + }); + }); + + context('to a receiver contract that reverts with message', function () { + it('reverts', async function () { + const revertingReceiver = await ERC721ReceiverMock.new(RECEIVER_MAGIC_VALUE, RevertType.RevertWithMessage); + await expectRevert( + this.token.$_safeMint(revertingReceiver.address, tokenId), + 'ERC721ReceiverMock: reverting', + ); + }); + }); + + context('to a receiver contract that reverts without message', function () { + it('reverts', async function () { + const revertingReceiver = await ERC721ReceiverMock.new( + RECEIVER_MAGIC_VALUE, + RevertType.RevertWithoutMessage, + ); + await expectRevertCustomError( + this.token.$_safeMint(revertingReceiver.address, tokenId), + 'ERC721InvalidReceiver', + [revertingReceiver.address], + ); + }); + }); + + context('to a receiver contract that reverts with custom error', function () { + it('reverts', async function () { + const revertingReceiver = await ERC721ReceiverMock.new( + RECEIVER_MAGIC_VALUE, + RevertType.RevertWithCustomError, + ); + await expectRevertCustomError(this.token.$_safeMint(revertingReceiver.address, tokenId), 'CustomError', [ + RECEIVER_MAGIC_VALUE, + ]); + }); + }); + + context('to a receiver contract that panics', function () { + it('reverts', async function () { + const revertingReceiver = await ERC721ReceiverMock.new(RECEIVER_MAGIC_VALUE, RevertType.Panic); + await expectRevert.unspecified(this.token.$_safeMint(revertingReceiver.address, tokenId)); + }); + }); + + context('to a contract that does not implement the required function', function () { + it('reverts', async function () { + const nonReceiver = await NonERC721ReceiverMock.new(); + await expectRevertCustomError( + this.token.$_safeMint(nonReceiver.address, tokenId), + 'ERC721InvalidReceiver', + [nonReceiver.address], + ); + }); + }); + }); + }); + + describe('approve', function () { + const tokenId = firstTokenId; + + let receipt = null; + + const itClearsApproval = function () { + it('clears approval for the token', async function () { + expect(await this.token.getApproved(tokenId)).to.be.equal(ZERO_ADDRESS); + }); + }; + + const itApproves = function (address) { + it('sets the approval for the target address', async function () { + expect(await this.token.getApproved(tokenId)).to.be.equal(address); + }); + }; + + const itEmitsApprovalEvent = function (address) { + it('emits an approval event', async function () { + expectEvent(receipt, 'Approval', { + owner: owner, + approved: address, + tokenId: tokenId, + }); + }); + }; + + context('when clearing approval', function () { + context('when there was no prior approval', function () { + beforeEach(async function () { + receipt = await this.token.approve(ZERO_ADDRESS, tokenId, { from: owner }); + }); + + itClearsApproval(); + itEmitsApprovalEvent(ZERO_ADDRESS); + }); + + context('when there was a prior approval', function () { + beforeEach(async function () { + await this.token.approve(approved, tokenId, { from: owner }); + receipt = await this.token.approve(ZERO_ADDRESS, tokenId, { from: owner }); + }); + + itClearsApproval(); + itEmitsApprovalEvent(ZERO_ADDRESS); + }); + }); + + context('when approving a non-zero address', function () { + context('when there was no prior approval', function () { + beforeEach(async function () { + receipt = await this.token.approve(approved, tokenId, { from: owner }); + }); + + itApproves(approved); + itEmitsApprovalEvent(approved); + }); + + context('when there was a prior approval to the same address', function () { + beforeEach(async function () { + await this.token.approve(approved, tokenId, { from: owner }); + receipt = await this.token.approve(approved, tokenId, { from: owner }); + }); + + itApproves(approved); + itEmitsApprovalEvent(approved); + }); + + context('when there was a prior approval to a different address', function () { + beforeEach(async function () { + await this.token.approve(anotherApproved, tokenId, { from: owner }); + receipt = await this.token.approve(anotherApproved, tokenId, { from: owner }); + }); + + itApproves(anotherApproved); + itEmitsApprovalEvent(anotherApproved); + }); + }); + + context('when the sender does not own the given token ID', function () { + it('reverts', async function () { + await expectRevertCustomError( + this.token.approve(approved, tokenId, { from: other }), + 'ERC721InvalidApprover', + [other], + ); + }); + }); + + context('when the sender is approved for the given token ID', function () { + it('reverts', async function () { + await this.token.approve(approved, tokenId, { from: owner }); + await expectRevertCustomError( + this.token.approve(anotherApproved, tokenId, { from: approved }), + 'ERC721InvalidApprover', + [approved], + ); + }); + }); + + context('when the sender is an operator', function () { + beforeEach(async function () { + await this.token.setApprovalForAll(operator, true, { from: owner }); + receipt = await this.token.approve(approved, tokenId, { from: operator }); + }); + + itApproves(approved); + itEmitsApprovalEvent(approved); + }); + + context('when the given token ID does not exist', function () { + it('reverts', async function () { + await expectRevertCustomError( + this.token.approve(approved, nonExistentTokenId, { from: operator }), + 'ERC721NonexistentToken', + [nonExistentTokenId], + ); + }); + }); + }); + + describe('setApprovalForAll', function () { + context('when the operator willing to approve is not the owner', function () { + context('when there is no operator approval set by the sender', function () { + it('approves the operator', async function () { + await this.token.setApprovalForAll(operator, true, { from: owner }); + + expect(await this.token.isApprovedForAll(owner, operator)).to.equal(true); + }); + + it('emits an approval event', async function () { + const receipt = await this.token.setApprovalForAll(operator, true, { from: owner }); + + expectEvent(receipt, 'ApprovalForAll', { + owner: owner, + operator: operator, + approved: true, + }); + }); + }); + + context('when the operator was set as not approved', function () { + beforeEach(async function () { + await this.token.setApprovalForAll(operator, false, { from: owner }); + }); + + it('approves the operator', async function () { + await this.token.setApprovalForAll(operator, true, { from: owner }); + + expect(await this.token.isApprovedForAll(owner, operator)).to.equal(true); + }); + + it('emits an approval event', async function () { + const receipt = await this.token.setApprovalForAll(operator, true, { from: owner }); + + expectEvent(receipt, 'ApprovalForAll', { + owner: owner, + operator: operator, + approved: true, + }); + }); + + it('can unset the operator approval', async function () { + await this.token.setApprovalForAll(operator, false, { from: owner }); + + expect(await this.token.isApprovedForAll(owner, operator)).to.equal(false); + }); + }); + + context('when the operator was already approved', function () { + beforeEach(async function () { + await this.token.setApprovalForAll(operator, true, { from: owner }); + }); + + it('keeps the approval to the given address', async function () { + await this.token.setApprovalForAll(operator, true, { from: owner }); + + expect(await this.token.isApprovedForAll(owner, operator)).to.equal(true); + }); + + it('emits an approval event', async function () { + const receipt = await this.token.setApprovalForAll(operator, true, { from: owner }); + + expectEvent(receipt, 'ApprovalForAll', { + owner: owner, + operator: operator, + approved: true, + }); + }); + }); + }); + + context('when the operator is address zero', function () { + it('reverts', async function () { + await expectRevertCustomError( + this.token.setApprovalForAll(constants.ZERO_ADDRESS, true, { from: owner }), + 'ERC721InvalidOperator', + [constants.ZERO_ADDRESS], + ); + }); + }); + }); + + describe('getApproved', async function () { + context('when token is not minted', async function () { + it('reverts', async function () { + await expectRevertCustomError(this.token.getApproved(nonExistentTokenId), 'ERC721NonexistentToken', [ + nonExistentTokenId, + ]); + }); + }); + + context('when token has been minted ', async function () { + it('should return the zero address', async function () { + expect(await this.token.getApproved(firstTokenId)).to.be.equal(ZERO_ADDRESS); + }); + + context('when account has been approved', async function () { + beforeEach(async function () { + await this.token.approve(approved, firstTokenId, { from: owner }); + }); + + it('returns approved account', async function () { + expect(await this.token.getApproved(firstTokenId)).to.be.equal(approved); + }); + }); + }); + }); + }); + + describe('_mint(address, uint256)', function () { + it('reverts with a null destination address', async function () { + await expectRevertCustomError(this.token.$_mint(ZERO_ADDRESS, firstTokenId), 'ERC721InvalidReceiver', [ + ZERO_ADDRESS, + ]); + }); + + context('with minted token', async function () { + beforeEach(async function () { + this.receipt = await this.token.$_mint(owner, firstTokenId); + }); + + it('emits a Transfer event', function () { + expectEvent(this.receipt, 'Transfer', { from: ZERO_ADDRESS, to: owner, tokenId: firstTokenId }); + }); + + it('creates the token', async function () { + expect(await this.token.balanceOf(owner)).to.be.bignumber.equal('1'); + expect(await this.token.ownerOf(firstTokenId)).to.equal(owner); + }); + + it('reverts when adding a token id that already exists', async function () { + await expectRevertCustomError(this.token.$_mint(owner, firstTokenId), 'ERC721InvalidSender', [ZERO_ADDRESS]); + }); + }); + }); + + describe('_burn', function () { + it('reverts when burning a non-existent token id', async function () { + await expectRevertCustomError(this.token.$_burn(nonExistentTokenId), 'ERC721NonexistentToken', [ + nonExistentTokenId, + ]); + }); + + context('with minted tokens', function () { + beforeEach(async function () { + await this.token.$_mint(owner, firstTokenId); + await this.token.$_mint(owner, secondTokenId); + }); + + context('with burnt token', function () { + beforeEach(async function () { + this.receipt = await this.token.$_burn(firstTokenId); + }); + + it('emits a Transfer event', function () { + expectEvent(this.receipt, 'Transfer', { from: owner, to: ZERO_ADDRESS, tokenId: firstTokenId }); + }); + + it('deletes the token', async function () { + expect(await this.token.balanceOf(owner)).to.be.bignumber.equal('1'); + await expectRevertCustomError(this.token.ownerOf(firstTokenId), 'ERC721NonexistentToken', [firstTokenId]); + }); + + it('reverts when burning a token id that has been deleted', async function () { + await expectRevertCustomError(this.token.$_burn(firstTokenId), 'ERC721NonexistentToken', [firstTokenId]); + }); + }); + }); + }); +} + +function shouldBehaveLikeERC721Enumerable(owner, newOwner, approved, anotherApproved, operator, other) { + shouldSupportInterfaces(['ERC721Enumerable']); + + context('with minted tokens', function () { + beforeEach(async function () { + await this.token.$_mint(owner, firstTokenId); + await this.token.$_mint(owner, secondTokenId); + this.toWhom = other; // default to other for toWhom in context-dependent tests + }); + + describe('totalSupply', function () { + it('returns total token supply', async function () { + expect(await this.token.totalSupply()).to.be.bignumber.equal('2'); + }); + }); + + describe('tokenOfOwnerByIndex', function () { + describe('when the given index is lower than the amount of tokens owned by the given address', function () { + it('returns the token ID placed at the given index', async function () { + expect(await this.token.tokenOfOwnerByIndex(owner, 0)).to.be.bignumber.equal(firstTokenId); + }); + }); + + describe('when the index is greater than or equal to the total tokens owned by the given address', function () { + it('reverts', async function () { + await expectRevertCustomError(this.token.tokenOfOwnerByIndex(owner, 2), 'ERC721OutOfBoundsIndex', [owner, 2]); + }); + }); + + describe('when the given address does not own any token', function () { + it('reverts', async function () { + await expectRevertCustomError(this.token.tokenOfOwnerByIndex(other, 0), 'ERC721OutOfBoundsIndex', [other, 0]); + }); + }); + + describe('after transferring all tokens to another user', function () { + beforeEach(async function () { + await this.token.transferFrom(owner, other, firstTokenId, { from: owner }); + await this.token.transferFrom(owner, other, secondTokenId, { from: owner }); + }); + + it('returns correct token IDs for target', async function () { + expect(await this.token.balanceOf(other)).to.be.bignumber.equal('2'); + const tokensListed = await Promise.all([0, 1].map(i => this.token.tokenOfOwnerByIndex(other, i))); + expect(tokensListed.map(t => t.toNumber())).to.have.members([ + firstTokenId.toNumber(), + secondTokenId.toNumber(), + ]); + }); + + it('returns empty collection for original owner', async function () { + expect(await this.token.balanceOf(owner)).to.be.bignumber.equal('0'); + await expectRevertCustomError(this.token.tokenOfOwnerByIndex(owner, 0), 'ERC721OutOfBoundsIndex', [owner, 0]); + }); + }); + }); + + describe('tokenByIndex', function () { + it('returns all tokens', async function () { + const tokensListed = await Promise.all([0, 1].map(i => this.token.tokenByIndex(i))); + expect(tokensListed.map(t => t.toNumber())).to.have.members([ + firstTokenId.toNumber(), + secondTokenId.toNumber(), + ]); + }); + + it('reverts if index is greater than supply', async function () { + await expectRevertCustomError(this.token.tokenByIndex(2), 'ERC721OutOfBoundsIndex', [ZERO_ADDRESS, 2]); + }); + + [firstTokenId, secondTokenId].forEach(function (tokenId) { + it(`returns all tokens after burning token ${tokenId} and minting new tokens`, async function () { + const newTokenId = new BN(300); + const anotherNewTokenId = new BN(400); + + await this.token.$_burn(tokenId); + await this.token.$_mint(newOwner, newTokenId); + await this.token.$_mint(newOwner, anotherNewTokenId); + + expect(await this.token.totalSupply()).to.be.bignumber.equal('3'); + + const tokensListed = await Promise.all([0, 1, 2].map(i => this.token.tokenByIndex(i))); + const expectedTokens = [firstTokenId, secondTokenId, newTokenId, anotherNewTokenId].filter( + x => x !== tokenId, + ); + expect(tokensListed.map(t => t.toNumber())).to.have.members(expectedTokens.map(t => t.toNumber())); + }); + }); + }); + }); + + describe('_mint(address, uint256)', function () { + it('reverts with a null destination address', async function () { + await expectRevertCustomError(this.token.$_mint(ZERO_ADDRESS, firstTokenId), 'ERC721InvalidReceiver', [ + ZERO_ADDRESS, + ]); + }); + + context('with minted token', async function () { + beforeEach(async function () { + this.receipt = await this.token.$_mint(owner, firstTokenId); + }); + + it('adjusts owner tokens by index', async function () { + expect(await this.token.tokenOfOwnerByIndex(owner, 0)).to.be.bignumber.equal(firstTokenId); + }); + + it('adjusts all tokens list', async function () { + expect(await this.token.tokenByIndex(0)).to.be.bignumber.equal(firstTokenId); + }); + }); + }); + + describe('_burn', function () { + it('reverts when burning a non-existent token id', async function () { + await expectRevertCustomError(this.token.$_burn(firstTokenId), 'ERC721NonexistentToken', [firstTokenId]); + }); + + context('with minted tokens', function () { + beforeEach(async function () { + await this.token.$_mint(owner, firstTokenId); + await this.token.$_mint(owner, secondTokenId); + }); + + context('with burnt token', function () { + beforeEach(async function () { + this.receipt = await this.token.$_burn(firstTokenId); + }); + + it('removes that token from the token list of the owner', async function () { + expect(await this.token.tokenOfOwnerByIndex(owner, 0)).to.be.bignumber.equal(secondTokenId); + }); + + it('adjusts all tokens list', async function () { + expect(await this.token.tokenByIndex(0)).to.be.bignumber.equal(secondTokenId); + }); + + it('burns all tokens', async function () { + await this.token.$_burn(secondTokenId, { from: owner }); + expect(await this.token.totalSupply()).to.be.bignumber.equal('0'); + await expectRevertCustomError(this.token.tokenByIndex(0), 'ERC721OutOfBoundsIndex', [ZERO_ADDRESS, 0]); + }); + }); + }); + }); +} + +function shouldBehaveLikeERC721Metadata(name, symbol, owner) { + shouldSupportInterfaces(['ERC721Metadata']); + + describe('metadata', function () { + it('has a name', async function () { + expect(await this.token.name()).to.be.equal(name); + }); + + it('has a symbol', async function () { + expect(await this.token.symbol()).to.be.equal(symbol); + }); + + describe('token URI', function () { + beforeEach(async function () { + await this.token.$_mint(owner, firstTokenId); + }); + + it('return empty string by default', async function () { + expect(await this.token.tokenURI(firstTokenId)).to.be.equal(''); + }); + + it('reverts when queried for non existent token id', async function () { + await expectRevertCustomError(this.token.tokenURI(nonExistentTokenId), 'ERC721NonexistentToken', [ + nonExistentTokenId, + ]); + }); + + describe('base URI', function () { + beforeEach(function () { + if (this.token.setBaseURI === undefined) { + this.skip(); + } + }); + + it('base URI can be set', async function () { + await this.token.setBaseURI(baseURI); + expect(await this.token.baseURI()).to.equal(baseURI); + }); + + it('base URI is added as a prefix to the token URI', async function () { + await this.token.setBaseURI(baseURI); + expect(await this.token.tokenURI(firstTokenId)).to.be.equal(baseURI + firstTokenId.toString()); + }); + + it('token URI can be changed by changing the base URI', async function () { + await this.token.setBaseURI(baseURI); + const newBaseURI = 'https://api.example.com/v2/'; + await this.token.setBaseURI(newBaseURI); + expect(await this.token.tokenURI(firstTokenId)).to.be.equal(newBaseURI + firstTokenId.toString()); + }); + }); + }); + }); +} + +module.exports = { + shouldBehaveLikeERC721, + shouldBehaveLikeERC721Enumerable, + shouldBehaveLikeERC721Metadata, +}; diff --git a/test/token/ERC721/ERC721.test.js b/test/token/ERC721/ERC721.test.js new file mode 100644 index 000000000..372dd5069 --- /dev/null +++ b/test/token/ERC721/ERC721.test.js @@ -0,0 +1,15 @@ +const { shouldBehaveLikeERC721, shouldBehaveLikeERC721Metadata } = require('./ERC721.behavior'); + +const ERC721 = artifacts.require('$ERC721'); + +contract('ERC721', function (accounts) { + const name = 'Non Fungible Token'; + const symbol = 'NFT'; + + beforeEach(async function () { + this.token = await ERC721.new(name, symbol); + }); + + shouldBehaveLikeERC721(...accounts); + shouldBehaveLikeERC721Metadata(name, symbol, ...accounts); +}); diff --git a/test/token/ERC721/ERC721Enumerable.test.js b/test/token/ERC721/ERC721Enumerable.test.js new file mode 100644 index 000000000..31c28d177 --- /dev/null +++ b/test/token/ERC721/ERC721Enumerable.test.js @@ -0,0 +1,20 @@ +const { + shouldBehaveLikeERC721, + shouldBehaveLikeERC721Metadata, + shouldBehaveLikeERC721Enumerable, +} = require('./ERC721.behavior'); + +const ERC721Enumerable = artifacts.require('$ERC721Enumerable'); + +contract('ERC721Enumerable', function (accounts) { + const name = 'Non Fungible Token'; + const symbol = 'NFT'; + + beforeEach(async function () { + this.token = await ERC721Enumerable.new(name, symbol); + }); + + shouldBehaveLikeERC721(...accounts); + shouldBehaveLikeERC721Metadata(name, symbol, ...accounts); + shouldBehaveLikeERC721Enumerable(...accounts); +}); diff --git a/test/token/ERC721/extensions/ERC721Burnable.test.js b/test/token/ERC721/extensions/ERC721Burnable.test.js new file mode 100644 index 000000000..df059e090 --- /dev/null +++ b/test/token/ERC721/extensions/ERC721Burnable.test.js @@ -0,0 +1,82 @@ +const { BN, constants, expectEvent } = require('@openzeppelin/test-helpers'); + +const { expect } = require('chai'); +const { expectRevertCustomError } = require('../../../helpers/customError'); + +const ERC721Burnable = artifacts.require('$ERC721Burnable'); + +contract('ERC721Burnable', function (accounts) { + const [owner, approved, another] = accounts; + + const firstTokenId = new BN(1); + const secondTokenId = new BN(2); + const unknownTokenId = new BN(3); + + const name = 'Non Fungible Token'; + const symbol = 'NFT'; + + beforeEach(async function () { + this.token = await ERC721Burnable.new(name, symbol); + }); + + describe('like a burnable ERC721', function () { + beforeEach(async function () { + await this.token.$_mint(owner, firstTokenId); + await this.token.$_mint(owner, secondTokenId); + }); + + describe('burn', function () { + const tokenId = firstTokenId; + let receipt = null; + + describe('when successful', function () { + beforeEach(async function () { + receipt = await this.token.burn(tokenId, { from: owner }); + }); + + it('burns the given token ID and adjusts the balance of the owner', async function () { + await expectRevertCustomError(this.token.ownerOf(tokenId), 'ERC721NonexistentToken', [tokenId]); + expect(await this.token.balanceOf(owner)).to.be.bignumber.equal('1'); + }); + + it('emits a burn event', async function () { + expectEvent(receipt, 'Transfer', { + from: owner, + to: constants.ZERO_ADDRESS, + tokenId: tokenId, + }); + }); + }); + + describe('when there is a previous approval burned', function () { + beforeEach(async function () { + await this.token.approve(approved, tokenId, { from: owner }); + receipt = await this.token.burn(tokenId, { from: owner }); + }); + + context('getApproved', function () { + it('reverts', async function () { + await expectRevertCustomError(this.token.getApproved(tokenId), 'ERC721NonexistentToken', [tokenId]); + }); + }); + }); + + describe('when there is no previous approval burned', function () { + it('reverts', async function () { + await expectRevertCustomError(this.token.burn(tokenId, { from: another }), 'ERC721InsufficientApproval', [ + another, + tokenId, + ]); + }); + }); + + describe('when the given token ID was not tracked by this contract', function () { + it('reverts', async function () { + await expectRevertCustomError(this.token.burn(unknownTokenId, { from: owner }), 'ERC721NonexistentToken', [ + unknownTokenId, + ]); + }); + }); + }); + }); +}); diff --git a/test/token/ERC721/extensions/ERC721Consecutive.t.sol b/test/token/ERC721/extensions/ERC721Consecutive.t.sol new file mode 100644 index 000000000..eca15e717 --- /dev/null +++ b/test/token/ERC721/extensions/ERC721Consecutive.t.sol @@ -0,0 +1,181 @@ +// SPDX-License-Identifier: MIT + +pragma solidity ^0.8.20; + +// solhint-disable func-name-mixedcase + +import {ERC721} from "@openzeppelin/contracts/token/ERC721/ERC721.sol"; +import {ERC721Consecutive} from "@openzeppelin/contracts/token/ERC721/extensions/ERC721Consecutive.sol"; +import {Test, StdUtils} from "forge-std/Test.sol"; + +function toSingleton(address account) pure returns (address[] memory) { + address[] memory accounts = new address[](1); + accounts[0] = account; + return accounts; +} + +contract ERC721ConsecutiveTarget is StdUtils, ERC721Consecutive { + uint96 private immutable _offset; + uint256 public totalMinted = 0; + + constructor(address[] memory receivers, uint256[] memory batches, uint256 startingId) ERC721("", "") { + _offset = uint96(startingId); + for (uint256 i = 0; i < batches.length; i++) { + address receiver = receivers[i % receivers.length]; + uint96 batchSize = uint96(bound(batches[i], 0, _maxBatchSize())); + _mintConsecutive(receiver, batchSize); + totalMinted += batchSize; + } + } + + function burn(uint256 tokenId) public { + _burn(tokenId); + } + + function _firstConsecutiveId() internal view virtual override returns (uint96) { + return _offset; + } +} + +contract ERC721ConsecutiveTest is Test { + function test_balance(address receiver, uint256[] calldata batches, uint96 startingId) public { + vm.assume(receiver != address(0)); + + uint256 startingTokenId = bound(startingId, 0, 5000); + + ERC721ConsecutiveTarget token = new ERC721ConsecutiveTarget(toSingleton(receiver), batches, startingTokenId); + + assertEq(token.balanceOf(receiver), token.totalMinted()); + } + + function test_ownership( + address receiver, + uint256[] calldata batches, + uint256[2] calldata unboundedTokenId, + uint96 startingId + ) public { + vm.assume(receiver != address(0)); + + uint256 startingTokenId = bound(startingId, 0, 5000); + + ERC721ConsecutiveTarget token = new ERC721ConsecutiveTarget(toSingleton(receiver), batches, startingTokenId); + + if (token.totalMinted() > 0) { + uint256 validTokenId = bound( + unboundedTokenId[0], + startingTokenId, + startingTokenId + token.totalMinted() - 1 + ); + assertEq(token.ownerOf(validTokenId), receiver); + } + + uint256 invalidTokenId = bound( + unboundedTokenId[1], + startingTokenId + token.totalMinted(), + startingTokenId + token.totalMinted() + 1 + ); + vm.expectRevert(); + token.ownerOf(invalidTokenId); + } + + function test_burn( + address receiver, + uint256[] calldata batches, + uint256 unboundedTokenId, + uint96 startingId + ) public { + vm.assume(receiver != address(0)); + + uint256 startingTokenId = bound(startingId, 0, 5000); + + ERC721ConsecutiveTarget token = new ERC721ConsecutiveTarget(toSingleton(receiver), batches, startingTokenId); + + // only test if we minted at least one token + uint256 supply = token.totalMinted(); + vm.assume(supply > 0); + + // burn a token in [0; supply[ + uint256 tokenId = bound(unboundedTokenId, startingTokenId, startingTokenId + supply - 1); + token.burn(tokenId); + + // balance should have decreased + assertEq(token.balanceOf(receiver), supply - 1); + + // token should be burnt + vm.expectRevert(); + token.ownerOf(tokenId); + } + + function test_transfer( + address[2] calldata accounts, + uint256[2] calldata unboundedBatches, + uint256[2] calldata unboundedTokenId, + uint96 startingId + ) public { + vm.assume(accounts[0] != address(0)); + vm.assume(accounts[1] != address(0)); + vm.assume(accounts[0] != accounts[1]); + + uint256 startingTokenId = bound(startingId, 1, 5000); + + address[] memory receivers = new address[](2); + receivers[0] = accounts[0]; + receivers[1] = accounts[1]; + + // We assume _maxBatchSize is 5000 (the default). This test will break otherwise. + uint256[] memory batches = new uint256[](2); + batches[0] = bound(unboundedBatches[0], startingTokenId, 5000); + batches[1] = bound(unboundedBatches[1], startingTokenId, 5000); + + ERC721ConsecutiveTarget token = new ERC721ConsecutiveTarget(receivers, batches, startingTokenId); + + uint256 tokenId0 = bound(unboundedTokenId[0], startingTokenId, batches[0]); + uint256 tokenId1 = bound(unboundedTokenId[1], startingTokenId, batches[1]) + batches[0]; + + assertEq(token.ownerOf(tokenId0), accounts[0]); + assertEq(token.ownerOf(tokenId1), accounts[1]); + assertEq(token.balanceOf(accounts[0]), batches[0]); + assertEq(token.balanceOf(accounts[1]), batches[1]); + + vm.prank(accounts[0]); + token.transferFrom(accounts[0], accounts[1], tokenId0); + + assertEq(token.ownerOf(tokenId0), accounts[1]); + assertEq(token.ownerOf(tokenId1), accounts[1]); + assertEq(token.balanceOf(accounts[0]), batches[0] - 1); + assertEq(token.balanceOf(accounts[1]), batches[1] + 1); + + vm.prank(accounts[1]); + token.transferFrom(accounts[1], accounts[0], tokenId1); + + assertEq(token.ownerOf(tokenId0), accounts[1]); + assertEq(token.ownerOf(tokenId1), accounts[0]); + assertEq(token.balanceOf(accounts[0]), batches[0]); + assertEq(token.balanceOf(accounts[1]), batches[1]); + } + + function test_start_consecutive_id( + address receiver, + uint256[2] calldata unboundedBatches, + uint256[2] calldata unboundedTokenId, + uint96 startingId + ) public { + vm.assume(receiver != address(0)); + + uint256 startingTokenId = bound(startingId, 1, 5000); + + // We assume _maxBatchSize is 5000 (the default). This test will break otherwise. + uint256[] memory batches = new uint256[](2); + batches[0] = bound(unboundedBatches[0], startingTokenId, 5000); + batches[1] = bound(unboundedBatches[1], startingTokenId, 5000); + + ERC721ConsecutiveTarget token = new ERC721ConsecutiveTarget(toSingleton(receiver), batches, startingTokenId); + + uint256 tokenId0 = bound(unboundedTokenId[0], startingTokenId, batches[0]); + uint256 tokenId1 = bound(unboundedTokenId[1], startingTokenId, batches[1]); + + assertEq(token.ownerOf(tokenId0), receiver); + assertEq(token.ownerOf(tokenId1), receiver); + assertEq(token.balanceOf(receiver), batches[0] + batches[1]); + } +} diff --git a/test/token/ERC721/extensions/ERC721Consecutive.test.js b/test/token/ERC721/extensions/ERC721Consecutive.test.js new file mode 100644 index 000000000..d9e33aff2 --- /dev/null +++ b/test/token/ERC721/extensions/ERC721Consecutive.test.js @@ -0,0 +1,221 @@ +const { constants, expectEvent } = require('@openzeppelin/test-helpers'); +const { expect } = require('chai'); +const { sum } = require('../../../helpers/math'); +const { expectRevertCustomError } = require('../../../helpers/customError'); +const { ZERO_ADDRESS } = require('@openzeppelin/test-helpers/src/constants'); + +const ERC721ConsecutiveMock = artifacts.require('$ERC721ConsecutiveMock'); +const ERC721ConsecutiveEnumerableMock = artifacts.require('$ERC721ConsecutiveEnumerableMock'); +const ERC721ConsecutiveNoConstructorMintMock = artifacts.require('$ERC721ConsecutiveNoConstructorMintMock'); + +contract('ERC721Consecutive', function (accounts) { + const [user1, user2, user3, receiver] = accounts; + + const name = 'Non Fungible Token'; + const symbol = 'NFT'; + const batches = [ + { receiver: user1, amount: 0 }, + { receiver: user1, amount: 1 }, + { receiver: user1, amount: 2 }, + { receiver: user2, amount: 5 }, + { receiver: user3, amount: 0 }, + { receiver: user1, amount: 7 }, + ]; + const delegates = [user1, user3]; + + for (const offset of [0, 1, 42]) { + describe(`with offset ${offset}`, function () { + beforeEach(async function () { + this.token = await ERC721ConsecutiveMock.new( + name, + symbol, + offset, + delegates, + batches.map(({ receiver }) => receiver), + batches.map(({ amount }) => amount), + ); + }); + + describe('minting during construction', function () { + it('events are emitted at construction', async function () { + let first = offset; + + for (const batch of batches) { + if (batch.amount > 0) { + await expectEvent.inConstruction(this.token, 'ConsecutiveTransfer', { + fromTokenId: web3.utils.toBN(first), + toTokenId: web3.utils.toBN(first + batch.amount - 1), + fromAddress: constants.ZERO_ADDRESS, + toAddress: batch.receiver, + }); + } else { + // expectEvent.notEmitted.inConstruction only looks at event name, and doesn't check the parameters + } + first += batch.amount; + } + }); + + it('ownership is set', async function () { + const owners = [ + ...Array(offset).fill(constants.ZERO_ADDRESS), + ...batches.flatMap(({ receiver, amount }) => Array(amount).fill(receiver)), + ]; + + for (const tokenId in owners) { + if (owners[tokenId] != constants.ZERO_ADDRESS) { + expect(await this.token.ownerOf(tokenId)).to.be.equal(owners[tokenId]); + } + } + }); + + it('balance & voting power are set', async function () { + for (const account of accounts) { + const balance = sum(...batches.filter(({ receiver }) => receiver === account).map(({ amount }) => amount)); + + expect(await this.token.balanceOf(account)).to.be.bignumber.equal(web3.utils.toBN(balance)); + + // If not delegated at construction, check before + do delegation + if (!delegates.includes(account)) { + expect(await this.token.getVotes(account)).to.be.bignumber.equal(web3.utils.toBN(0)); + + await this.token.delegate(account, { from: account }); + } + + // At this point all accounts should have delegated + expect(await this.token.getVotes(account)).to.be.bignumber.equal(web3.utils.toBN(balance)); + } + }); + + it('reverts on consecutive minting to the zero address', async function () { + await expectRevertCustomError( + ERC721ConsecutiveMock.new(name, symbol, offset, delegates, [ZERO_ADDRESS], [10]), + 'ERC721InvalidReceiver', + [ZERO_ADDRESS], + ); + }); + }); + + describe('minting after construction', function () { + it('consecutive minting is not possible after construction', async function () { + await expectRevertCustomError(this.token.$_mintConsecutive(user1, 10), 'ERC721ForbiddenBatchMint', []); + }); + + it('simple minting is possible after construction', async function () { + const tokenId = sum(...batches.map(b => b.amount)) + offset; + + await expectRevertCustomError(this.token.ownerOf(tokenId), 'ERC721NonexistentToken', [tokenId]); + + expectEvent(await this.token.$_mint(user1, tokenId), 'Transfer', { + from: constants.ZERO_ADDRESS, + to: user1, + tokenId: tokenId.toString(), + }); + }); + + it('cannot mint a token that has been batched minted', async function () { + const tokenId = sum(...batches.map(b => b.amount)) + offset - 1; + + expect(await this.token.ownerOf(tokenId)).to.be.not.equal(constants.ZERO_ADDRESS); + + await expectRevertCustomError(this.token.$_mint(user1, tokenId), 'ERC721InvalidSender', [ZERO_ADDRESS]); + }); + }); + + describe('ERC721 behavior', function () { + const tokenId = web3.utils.toBN(offset + 1); + + it('core takes over ownership on transfer', async function () { + await this.token.transferFrom(user1, receiver, tokenId, { from: user1 }); + + expect(await this.token.ownerOf(tokenId)).to.be.equal(receiver); + }); + + it('tokens can be burned and re-minted #1', async function () { + expectEvent(await this.token.$_burn(tokenId, { from: user1 }), 'Transfer', { + from: user1, + to: constants.ZERO_ADDRESS, + tokenId, + }); + + await expectRevertCustomError(this.token.ownerOf(tokenId), 'ERC721NonexistentToken', [tokenId]); + + expectEvent(await this.token.$_mint(user2, tokenId), 'Transfer', { + from: constants.ZERO_ADDRESS, + to: user2, + tokenId, + }); + + expect(await this.token.ownerOf(tokenId)).to.be.equal(user2); + }); + + it('tokens can be burned and re-minted #2', async function () { + const tokenId = web3.utils.toBN(sum(...batches.map(({ amount }) => amount)) + offset); + + await expectRevertCustomError(this.token.ownerOf(tokenId), 'ERC721NonexistentToken', [tokenId]); + + // mint + await this.token.$_mint(user1, tokenId); + + expect(await this.token.ownerOf(tokenId), user1); + + // burn + expectEvent(await this.token.$_burn(tokenId, { from: user1 }), 'Transfer', { + from: user1, + to: constants.ZERO_ADDRESS, + tokenId, + }); + + await expectRevertCustomError(this.token.ownerOf(tokenId), 'ERC721NonexistentToken', [tokenId]); + + // re-mint + expectEvent(await this.token.$_mint(user2, tokenId), 'Transfer', { + from: constants.ZERO_ADDRESS, + to: user2, + tokenId, + }); + + expect(await this.token.ownerOf(tokenId), user2); + }); + }); + }); + } + + describe('invalid use', function () { + it('cannot mint a batch larger than 5000', async function () { + await expectRevertCustomError( + ERC721ConsecutiveMock.new(name, symbol, 0, [], [user1], ['5001']), + 'ERC721ExceededMaxBatchMint', + [5000, 5001], + ); + }); + + it('cannot use single minting during construction', async function () { + await expectRevertCustomError( + ERC721ConsecutiveNoConstructorMintMock.new(name, symbol), + 'ERC721ForbiddenMint', + [], + ); + }); + + it('cannot use single minting during construction', async function () { + await expectRevertCustomError( + ERC721ConsecutiveNoConstructorMintMock.new(name, symbol), + 'ERC721ForbiddenMint', + [], + ); + }); + + it('consecutive mint not compatible with enumerability', async function () { + await expectRevertCustomError( + ERC721ConsecutiveEnumerableMock.new( + name, + symbol, + batches.map(({ receiver }) => receiver), + batches.map(({ amount }) => amount), + ), + 'ERC721EnumerableForbiddenBatchMint', + [], + ); + }); + }); +}); diff --git a/test/token/ERC721/extensions/ERC721Pausable.test.js b/test/token/ERC721/extensions/ERC721Pausable.test.js new file mode 100644 index 000000000..5d77149f2 --- /dev/null +++ b/test/token/ERC721/extensions/ERC721Pausable.test.js @@ -0,0 +1,90 @@ +const { BN, constants } = require('@openzeppelin/test-helpers'); + +const { expect } = require('chai'); +const { expectRevertCustomError } = require('../../../helpers/customError'); + +const ERC721Pausable = artifacts.require('$ERC721Pausable'); + +contract('ERC721Pausable', function (accounts) { + const [owner, receiver, operator] = accounts; + + const name = 'Non Fungible Token'; + const symbol = 'NFT'; + + beforeEach(async function () { + this.token = await ERC721Pausable.new(name, symbol); + }); + + context('when token is paused', function () { + const firstTokenId = new BN(1); + const secondTokenId = new BN(1337); + + const mockData = '0x42'; + + beforeEach(async function () { + await this.token.$_mint(owner, firstTokenId, { from: owner }); + await this.token.$_pause(); + }); + + it('reverts when trying to transferFrom', async function () { + await expectRevertCustomError( + this.token.transferFrom(owner, receiver, firstTokenId, { from: owner }), + 'EnforcedPause', + [], + ); + }); + + it('reverts when trying to safeTransferFrom', async function () { + await expectRevertCustomError( + this.token.safeTransferFrom(owner, receiver, firstTokenId, { from: owner }), + 'EnforcedPause', + [], + ); + }); + + it('reverts when trying to safeTransferFrom with data', async function () { + await expectRevertCustomError( + this.token.methods['safeTransferFrom(address,address,uint256,bytes)'](owner, receiver, firstTokenId, mockData, { + from: owner, + }), + 'EnforcedPause', + [], + ); + }); + + it('reverts when trying to mint', async function () { + await expectRevertCustomError(this.token.$_mint(receiver, secondTokenId), 'EnforcedPause', []); + }); + + it('reverts when trying to burn', async function () { + await expectRevertCustomError(this.token.$_burn(firstTokenId), 'EnforcedPause', []); + }); + + describe('getApproved', function () { + it('returns approved address', async function () { + const approvedAccount = await this.token.getApproved(firstTokenId); + expect(approvedAccount).to.equal(constants.ZERO_ADDRESS); + }); + }); + + describe('balanceOf', function () { + it('returns the amount of tokens owned by the given address', async function () { + const balance = await this.token.balanceOf(owner); + expect(balance).to.be.bignumber.equal('1'); + }); + }); + + describe('ownerOf', function () { + it('returns the amount of tokens owned by the given address', async function () { + const ownerOfToken = await this.token.ownerOf(firstTokenId); + expect(ownerOfToken).to.equal(owner); + }); + }); + + describe('isApprovedForAll', function () { + it('returns the approval of the operator', async function () { + expect(await this.token.isApprovedForAll(owner, operator)).to.equal(false); + }); + }); + }); +}); diff --git a/test/token/ERC721/extensions/ERC721Royalty.test.js b/test/token/ERC721/extensions/ERC721Royalty.test.js new file mode 100644 index 000000000..78cba9858 --- /dev/null +++ b/test/token/ERC721/extensions/ERC721Royalty.test.js @@ -0,0 +1,47 @@ +require('@openzeppelin/test-helpers'); + +const { shouldBehaveLikeERC2981 } = require('../../common/ERC2981.behavior'); + +const ERC721Royalty = artifacts.require('$ERC721Royalty'); + +contract('ERC721Royalty', function (accounts) { + const [account1, account2, recipient] = accounts; + const tokenId1 = web3.utils.toBN('1'); + const tokenId2 = web3.utils.toBN('2'); + const royalty = web3.utils.toBN('200'); + const salePrice = web3.utils.toBN('1000'); + + beforeEach(async function () { + this.token = await ERC721Royalty.new('My Token', 'TKN'); + + await this.token.$_mint(account1, tokenId1); + await this.token.$_mint(account1, tokenId2); + this.account1 = account1; + this.account2 = account2; + this.tokenId1 = tokenId1; + this.tokenId2 = tokenId2; + this.salePrice = salePrice; + }); + + describe('token specific functions', function () { + beforeEach(async function () { + await this.token.$_setTokenRoyalty(tokenId1, recipient, royalty); + }); + + it('royalty information are kept during burn and re-mint', async function () { + await this.token.$_burn(tokenId1); + + const tokenInfoA = await this.token.royaltyInfo(tokenId1, salePrice); + expect(tokenInfoA[0]).to.be.equal(recipient); + expect(tokenInfoA[1]).to.be.bignumber.equal(salePrice.mul(royalty).divn(1e4)); + + await this.token.$_mint(account2, tokenId1); + + const tokenInfoB = await this.token.royaltyInfo(tokenId1, salePrice); + expect(tokenInfoB[0]).to.be.equal(recipient); + expect(tokenInfoB[1]).to.be.bignumber.equal(salePrice.mul(royalty).divn(1e4)); + }); + }); + + shouldBehaveLikeERC2981(); +}); diff --git a/test/token/ERC721/extensions/ERC721URIStorage.test.js b/test/token/ERC721/extensions/ERC721URIStorage.test.js new file mode 100644 index 000000000..8c882fab0 --- /dev/null +++ b/test/token/ERC721/extensions/ERC721URIStorage.test.js @@ -0,0 +1,114 @@ +const { BN, expectEvent } = require('@openzeppelin/test-helpers'); +const { expect } = require('chai'); + +const { shouldSupportInterfaces } = require('../../../utils/introspection/SupportsInterface.behavior'); +const { expectRevertCustomError } = require('../../../helpers/customError'); + +const ERC721URIStorageMock = artifacts.require('$ERC721URIStorageMock'); + +contract('ERC721URIStorage', function (accounts) { + const [owner] = accounts; + + const name = 'Non Fungible Token'; + const symbol = 'NFT'; + + const firstTokenId = new BN('5042'); + const nonExistentTokenId = new BN('13'); + + beforeEach(async function () { + this.token = await ERC721URIStorageMock.new(name, symbol); + }); + + shouldSupportInterfaces(['0x49064906']); + + describe('token URI', function () { + beforeEach(async function () { + await this.token.$_mint(owner, firstTokenId); + }); + + const baseURI = 'https://api.example.com/v1/'; + const sampleUri = 'mock://mytoken'; + + it('it is empty by default', async function () { + expect(await this.token.tokenURI(firstTokenId)).to.be.equal(''); + }); + + it('reverts when queried for non existent token id', async function () { + await expectRevertCustomError(this.token.tokenURI(nonExistentTokenId), 'ERC721NonexistentToken', [ + nonExistentTokenId, + ]); + }); + + it('can be set for a token id', async function () { + await this.token.$_setTokenURI(firstTokenId, sampleUri); + expect(await this.token.tokenURI(firstTokenId)).to.be.equal(sampleUri); + }); + + it('setting the uri emits an event', async function () { + expectEvent(await this.token.$_setTokenURI(firstTokenId, sampleUri), 'MetadataUpdate', { + _tokenId: firstTokenId, + }); + }); + + it('setting the uri for non existent token id is allowed', async function () { + expectEvent(await this.token.$_setTokenURI(nonExistentTokenId, sampleUri), 'MetadataUpdate', { + _tokenId: nonExistentTokenId, + }); + + // value will be accessible after mint + await this.token.$_mint(owner, nonExistentTokenId); + expect(await this.token.tokenURI(nonExistentTokenId)).to.be.equal(sampleUri); + }); + + it('base URI can be set', async function () { + await this.token.setBaseURI(baseURI); + expect(await this.token.$_baseURI()).to.equal(baseURI); + }); + + it('base URI is added as a prefix to the token URI', async function () { + await this.token.setBaseURI(baseURI); + await this.token.$_setTokenURI(firstTokenId, sampleUri); + + expect(await this.token.tokenURI(firstTokenId)).to.be.equal(baseURI + sampleUri); + }); + + it('token URI can be changed by changing the base URI', async function () { + await this.token.setBaseURI(baseURI); + await this.token.$_setTokenURI(firstTokenId, sampleUri); + + const newBaseURI = 'https://api.example.com/v2/'; + await this.token.setBaseURI(newBaseURI); + expect(await this.token.tokenURI(firstTokenId)).to.be.equal(newBaseURI + sampleUri); + }); + + it('tokenId is appended to base URI for tokens with no URI', async function () { + await this.token.setBaseURI(baseURI); + + expect(await this.token.tokenURI(firstTokenId)).to.be.equal(baseURI + firstTokenId); + }); + + it('tokens without URI can be burnt ', async function () { + await this.token.$_burn(firstTokenId); + + await expectRevertCustomError(this.token.tokenURI(firstTokenId), 'ERC721NonexistentToken', [firstTokenId]); + }); + + it('tokens with URI can be burnt ', async function () { + await this.token.$_setTokenURI(firstTokenId, sampleUri); + + await this.token.$_burn(firstTokenId); + + await expectRevertCustomError(this.token.tokenURI(firstTokenId), 'ERC721NonexistentToken', [firstTokenId]); + }); + + it('tokens URI is kept if token is burnt and reminted ', async function () { + await this.token.$_setTokenURI(firstTokenId, sampleUri); + + await this.token.$_burn(firstTokenId); + await expectRevertCustomError(this.token.tokenURI(firstTokenId), 'ERC721NonexistentToken', [firstTokenId]); + + await this.token.$_mint(owner, firstTokenId); + expect(await this.token.tokenURI(firstTokenId)).to.be.equal(sampleUri); + }); + }); +}); diff --git a/test/token/ERC721/extensions/ERC721Votes.test.js b/test/token/ERC721/extensions/ERC721Votes.test.js new file mode 100644 index 000000000..45020baf9 --- /dev/null +++ b/test/token/ERC721/extensions/ERC721Votes.test.js @@ -0,0 +1,183 @@ +/* eslint-disable */ + +const { expectEvent, time } = require('@openzeppelin/test-helpers'); +const { expect } = require('chai'); + +const { clock, clockFromReceipt } = require('../../../helpers/time'); + +const { shouldBehaveLikeVotes } = require('../../../governance/utils/Votes.behavior'); + +const MODES = { + blocknumber: artifacts.require('$ERC721Votes'), + // no timestamp mode for ERC721Votes yet +}; + +contract('ERC721Votes', function (accounts) { + const [account1, account2, other1, other2] = accounts; + + const name = 'My Vote'; + const symbol = 'MTKN'; + const version = '1'; + const tokens = ['10000000000000000000000000', '10', '20', '30'].map(n => web3.utils.toBN(n)); + + for (const [mode, artifact] of Object.entries(MODES)) { + describe(`vote with ${mode}`, function () { + beforeEach(async function () { + this.votes = await artifact.new(name, symbol, name, version); + }); + + // includes EIP6372 behavior check + shouldBehaveLikeVotes(accounts, tokens, { mode, fungible: false }); + + describe('balanceOf', function () { + beforeEach(async function () { + await this.votes.$_mint(account1, tokens[0]); + await this.votes.$_mint(account1, tokens[1]); + await this.votes.$_mint(account1, tokens[2]); + await this.votes.$_mint(account1, tokens[3]); + }); + + it('grants to initial account', async function () { + expect(await this.votes.balanceOf(account1)).to.be.bignumber.equal('4'); + }); + }); + + describe('transfers', function () { + beforeEach(async function () { + await this.votes.$_mint(account1, tokens[0]); + }); + + it('no delegation', async function () { + const { receipt } = await this.votes.transferFrom(account1, account2, tokens[0], { from: account1 }); + expectEvent(receipt, 'Transfer', { from: account1, to: account2, tokenId: tokens[0] }); + expectEvent.notEmitted(receipt, 'DelegateVotesChanged'); + + this.account1Votes = '0'; + this.account2Votes = '0'; + }); + + it('sender delegation', async function () { + await this.votes.delegate(account1, { from: account1 }); + + const { receipt } = await this.votes.transferFrom(account1, account2, tokens[0], { from: account1 }); + expectEvent(receipt, 'Transfer', { from: account1, to: account2, tokenId: tokens[0] }); + expectEvent(receipt, 'DelegateVotesChanged', { delegate: account1, previousVotes: '1', newVotes: '0' }); + + const { logIndex: transferLogIndex } = receipt.logs.find(({ event }) => event == 'Transfer'); + expect( + receipt.logs + .filter(({ event }) => event == 'DelegateVotesChanged') + .every(({ logIndex }) => transferLogIndex < logIndex), + ).to.be.equal(true); + + this.account1Votes = '0'; + this.account2Votes = '0'; + }); + + it('receiver delegation', async function () { + await this.votes.delegate(account2, { from: account2 }); + + const { receipt } = await this.votes.transferFrom(account1, account2, tokens[0], { from: account1 }); + expectEvent(receipt, 'Transfer', { from: account1, to: account2, tokenId: tokens[0] }); + expectEvent(receipt, 'DelegateVotesChanged', { delegate: account2, previousVotes: '0', newVotes: '1' }); + + const { logIndex: transferLogIndex } = receipt.logs.find(({ event }) => event == 'Transfer'); + expect( + receipt.logs + .filter(({ event }) => event == 'DelegateVotesChanged') + .every(({ logIndex }) => transferLogIndex < logIndex), + ).to.be.equal(true); + + this.account1Votes = '0'; + this.account2Votes = '1'; + }); + + it('full delegation', async function () { + await this.votes.delegate(account1, { from: account1 }); + await this.votes.delegate(account2, { from: account2 }); + + const { receipt } = await this.votes.transferFrom(account1, account2, tokens[0], { from: account1 }); + expectEvent(receipt, 'Transfer', { from: account1, to: account2, tokenId: tokens[0] }); + expectEvent(receipt, 'DelegateVotesChanged', { delegate: account1, previousVotes: '1', newVotes: '0' }); + expectEvent(receipt, 'DelegateVotesChanged', { delegate: account2, previousVotes: '0', newVotes: '1' }); + + const { logIndex: transferLogIndex } = receipt.logs.find(({ event }) => event == 'Transfer'); + expect( + receipt.logs + .filter(({ event }) => event == 'DelegateVotesChanged') + .every(({ logIndex }) => transferLogIndex < logIndex), + ).to.be.equal(true); + + this.account1Votes = '0'; + this.account2Votes = '1'; + }); + + it('returns the same total supply on transfers', async function () { + await this.votes.delegate(account1, { from: account1 }); + + const { receipt } = await this.votes.transferFrom(account1, account2, tokens[0], { from: account1 }); + const timepoint = await clockFromReceipt[mode](receipt); + + await time.advanceBlock(); + await time.advanceBlock(); + + expect(await this.votes.getPastTotalSupply(timepoint - 1)).to.be.bignumber.equal('1'); + expect(await this.votes.getPastTotalSupply(timepoint + 1)).to.be.bignumber.equal('1'); + + this.account1Votes = '0'; + this.account2Votes = '0'; + }); + + it('generally returns the voting balance at the appropriate checkpoint', async function () { + await this.votes.$_mint(account1, tokens[1]); + await this.votes.$_mint(account1, tokens[2]); + await this.votes.$_mint(account1, tokens[3]); + + const total = await this.votes.balanceOf(account1); + + const t1 = await this.votes.delegate(other1, { from: account1 }); + await time.advanceBlock(); + await time.advanceBlock(); + const t2 = await this.votes.transferFrom(account1, other2, tokens[0], { from: account1 }); + await time.advanceBlock(); + await time.advanceBlock(); + const t3 = await this.votes.transferFrom(account1, other2, tokens[2], { from: account1 }); + await time.advanceBlock(); + await time.advanceBlock(); + const t4 = await this.votes.transferFrom(other2, account1, tokens[2], { from: other2 }); + await time.advanceBlock(); + await time.advanceBlock(); + + t1.timepoint = await clockFromReceipt[mode](t1.receipt); + t2.timepoint = await clockFromReceipt[mode](t2.receipt); + t3.timepoint = await clockFromReceipt[mode](t3.receipt); + t4.timepoint = await clockFromReceipt[mode](t4.receipt); + + expect(await this.votes.getPastVotes(other1, t1.timepoint - 1)).to.be.bignumber.equal('0'); + expect(await this.votes.getPastVotes(other1, t1.timepoint)).to.be.bignumber.equal(total); + expect(await this.votes.getPastVotes(other1, t1.timepoint + 1)).to.be.bignumber.equal(total); + expect(await this.votes.getPastVotes(other1, t2.timepoint)).to.be.bignumber.equal('3'); + expect(await this.votes.getPastVotes(other1, t2.timepoint + 1)).to.be.bignumber.equal('3'); + expect(await this.votes.getPastVotes(other1, t3.timepoint)).to.be.bignumber.equal('2'); + expect(await this.votes.getPastVotes(other1, t3.timepoint + 1)).to.be.bignumber.equal('2'); + expect(await this.votes.getPastVotes(other1, t4.timepoint)).to.be.bignumber.equal('3'); + expect(await this.votes.getPastVotes(other1, t4.timepoint + 1)).to.be.bignumber.equal('3'); + + this.account1Votes = '0'; + this.account2Votes = '0'; + }); + + afterEach(async function () { + expect(await this.votes.getVotes(account1)).to.be.bignumber.equal(this.account1Votes); + expect(await this.votes.getVotes(account2)).to.be.bignumber.equal(this.account2Votes); + + // need to advance 2 blocks to see the effect of a transfer on "getPastVotes" + const timepoint = await clock[mode](); + await time.advanceBlock(); + expect(await this.votes.getPastVotes(account1, timepoint)).to.be.bignumber.equal(this.account1Votes); + expect(await this.votes.getPastVotes(account2, timepoint)).to.be.bignumber.equal(this.account2Votes); + }); + }); + }); + } +}); diff --git a/test/token/ERC721/extensions/ERC721Wrapper.test.js b/test/token/ERC721/extensions/ERC721Wrapper.test.js new file mode 100644 index 000000000..683997744 --- /dev/null +++ b/test/token/ERC721/extensions/ERC721Wrapper.test.js @@ -0,0 +1,289 @@ +const { BN, expectEvent, constants } = require('@openzeppelin/test-helpers'); +const { expect } = require('chai'); + +const { shouldBehaveLikeERC721 } = require('../ERC721.behavior'); +const { expectRevertCustomError } = require('../../../helpers/customError'); + +const ERC721 = artifacts.require('$ERC721'); +const ERC721Wrapper = artifacts.require('$ERC721Wrapper'); + +contract('ERC721Wrapper', function (accounts) { + const [initialHolder, anotherAccount, approvedAccount] = accounts; + + const name = 'My Token'; + const symbol = 'MTKN'; + const firstTokenId = new BN(1); + const secondTokenId = new BN(2); + + beforeEach(async function () { + this.underlying = await ERC721.new(name, symbol); + this.token = await ERC721Wrapper.new(`Wrapped ${name}`, `W${symbol}`, this.underlying.address); + + await this.underlying.$_safeMint(initialHolder, firstTokenId); + await this.underlying.$_safeMint(initialHolder, secondTokenId); + }); + + it('has a name', async function () { + expect(await this.token.name()).to.equal(`Wrapped ${name}`); + }); + + it('has a symbol', async function () { + expect(await this.token.symbol()).to.equal(`W${symbol}`); + }); + + it('has underlying', async function () { + expect(await this.token.underlying()).to.be.bignumber.equal(this.underlying.address); + }); + + describe('depositFor', function () { + it('works with token approval', async function () { + await this.underlying.approve(this.token.address, firstTokenId, { from: initialHolder }); + + const { tx } = await this.token.depositFor(initialHolder, [firstTokenId], { from: initialHolder }); + + await expectEvent.inTransaction(tx, this.underlying, 'Transfer', { + from: initialHolder, + to: this.token.address, + tokenId: firstTokenId, + }); + await expectEvent.inTransaction(tx, this.token, 'Transfer', { + from: constants.ZERO_ADDRESS, + to: initialHolder, + tokenId: firstTokenId, + }); + }); + + it('works with approval for all', async function () { + await this.underlying.setApprovalForAll(this.token.address, true, { from: initialHolder }); + + const { tx } = await this.token.depositFor(initialHolder, [firstTokenId], { from: initialHolder }); + + await expectEvent.inTransaction(tx, this.underlying, 'Transfer', { + from: initialHolder, + to: this.token.address, + tokenId: firstTokenId, + }); + await expectEvent.inTransaction(tx, this.token, 'Transfer', { + from: constants.ZERO_ADDRESS, + to: initialHolder, + tokenId: firstTokenId, + }); + }); + + it('works sending to another account', async function () { + await this.underlying.approve(this.token.address, firstTokenId, { from: initialHolder }); + + const { tx } = await this.token.depositFor(anotherAccount, [firstTokenId], { from: initialHolder }); + + await expectEvent.inTransaction(tx, this.underlying, 'Transfer', { + from: initialHolder, + to: this.token.address, + tokenId: firstTokenId, + }); + await expectEvent.inTransaction(tx, this.token, 'Transfer', { + from: constants.ZERO_ADDRESS, + to: anotherAccount, + tokenId: firstTokenId, + }); + }); + + it('works with multiple tokens', async function () { + await this.underlying.approve(this.token.address, firstTokenId, { from: initialHolder }); + await this.underlying.approve(this.token.address, secondTokenId, { from: initialHolder }); + + const { tx } = await this.token.depositFor(initialHolder, [firstTokenId, secondTokenId], { from: initialHolder }); + + await expectEvent.inTransaction(tx, this.underlying, 'Transfer', { + from: initialHolder, + to: this.token.address, + tokenId: firstTokenId, + }); + await expectEvent.inTransaction(tx, this.token, 'Transfer', { + from: constants.ZERO_ADDRESS, + to: initialHolder, + tokenId: firstTokenId, + }); + await expectEvent.inTransaction(tx, this.underlying, 'Transfer', { + from: initialHolder, + to: this.token.address, + tokenId: secondTokenId, + }); + await expectEvent.inTransaction(tx, this.token, 'Transfer', { + from: constants.ZERO_ADDRESS, + to: initialHolder, + tokenId: secondTokenId, + }); + }); + + it('reverts with missing approval', async function () { + await expectRevertCustomError( + this.token.depositFor(initialHolder, [firstTokenId], { from: initialHolder }), + 'ERC721InsufficientApproval', + [this.token.address, firstTokenId], + ); + }); + }); + + describe('withdrawTo', function () { + beforeEach(async function () { + await this.underlying.approve(this.token.address, firstTokenId, { from: initialHolder }); + await this.token.depositFor(initialHolder, [firstTokenId], { from: initialHolder }); + }); + + it('works for an owner', async function () { + const { tx } = await this.token.withdrawTo(initialHolder, [firstTokenId], { from: initialHolder }); + + await expectEvent.inTransaction(tx, this.underlying, 'Transfer', { + from: this.token.address, + to: initialHolder, + tokenId: firstTokenId, + }); + await expectEvent.inTransaction(tx, this.token, 'Transfer', { + from: initialHolder, + to: constants.ZERO_ADDRESS, + tokenId: firstTokenId, + }); + }); + + it('works for an approved', async function () { + await this.token.approve(approvedAccount, firstTokenId, { from: initialHolder }); + + const { tx } = await this.token.withdrawTo(initialHolder, [firstTokenId], { from: approvedAccount }); + + await expectEvent.inTransaction(tx, this.underlying, 'Transfer', { + from: this.token.address, + to: initialHolder, + tokenId: firstTokenId, + }); + await expectEvent.inTransaction(tx, this.token, 'Transfer', { + from: initialHolder, + to: constants.ZERO_ADDRESS, + tokenId: firstTokenId, + }); + }); + + it('works for an approved for all', async function () { + await this.token.setApprovalForAll(approvedAccount, true, { from: initialHolder }); + + const { tx } = await this.token.withdrawTo(initialHolder, [firstTokenId], { from: approvedAccount }); + + await expectEvent.inTransaction(tx, this.underlying, 'Transfer', { + from: this.token.address, + to: initialHolder, + tokenId: firstTokenId, + }); + await expectEvent.inTransaction(tx, this.token, 'Transfer', { + from: initialHolder, + to: constants.ZERO_ADDRESS, + tokenId: firstTokenId, + }); + }); + + it("doesn't work for a non-owner nor approved", async function () { + await expectRevertCustomError( + this.token.withdrawTo(initialHolder, [firstTokenId], { from: anotherAccount }), + 'ERC721InsufficientApproval', + [anotherAccount, firstTokenId], + ); + }); + + it('works with multiple tokens', async function () { + await this.underlying.approve(this.token.address, secondTokenId, { from: initialHolder }); + await this.token.depositFor(initialHolder, [secondTokenId], { from: initialHolder }); + + const { tx } = await this.token.withdrawTo(initialHolder, [firstTokenId, secondTokenId], { from: initialHolder }); + + await expectEvent.inTransaction(tx, this.underlying, 'Transfer', { + from: this.token.address, + to: initialHolder, + tokenId: firstTokenId, + }); + await expectEvent.inTransaction(tx, this.underlying, 'Transfer', { + from: this.token.address, + to: initialHolder, + tokenId: secondTokenId, + }); + await expectEvent.inTransaction(tx, this.token, 'Transfer', { + from: initialHolder, + to: constants.ZERO_ADDRESS, + tokenId: firstTokenId, + }); + await expectEvent.inTransaction(tx, this.token, 'Transfer', { + from: initialHolder, + to: constants.ZERO_ADDRESS, + tokenId: secondTokenId, + }); + }); + + it('works to another account', async function () { + const { tx } = await this.token.withdrawTo(anotherAccount, [firstTokenId], { from: initialHolder }); + + await expectEvent.inTransaction(tx, this.underlying, 'Transfer', { + from: this.token.address, + to: anotherAccount, + tokenId: firstTokenId, + }); + await expectEvent.inTransaction(tx, this.token, 'Transfer', { + from: initialHolder, + to: constants.ZERO_ADDRESS, + tokenId: firstTokenId, + }); + }); + }); + + describe('onERC721Received', function () { + it('only allows calls from underlying', async function () { + await expectRevertCustomError( + this.token.onERC721Received( + initialHolder, + this.token.address, + firstTokenId, + anotherAccount, // Correct data + { from: anotherAccount }, + ), + 'ERC721UnsupportedToken', + [anotherAccount], + ); + }); + + it('mints a token to from', async function () { + const { tx } = await this.underlying.safeTransferFrom(initialHolder, this.token.address, firstTokenId, { + from: initialHolder, + }); + + await expectEvent.inTransaction(tx, this.token, 'Transfer', { + from: constants.ZERO_ADDRESS, + to: initialHolder, + tokenId: firstTokenId, + }); + }); + }); + + describe('_recover', function () { + it('works if there is something to recover', async function () { + // Should use `transferFrom` to avoid `onERC721Received` minting + await this.underlying.transferFrom(initialHolder, this.token.address, firstTokenId, { from: initialHolder }); + + const { tx } = await this.token.$_recover(anotherAccount, firstTokenId); + + await expectEvent.inTransaction(tx, this.token, 'Transfer', { + from: constants.ZERO_ADDRESS, + to: anotherAccount, + tokenId: firstTokenId, + }); + }); + + it('reverts if there is nothing to recover', async function () { + const owner = await this.underlying.ownerOf(firstTokenId); + await expectRevertCustomError(this.token.$_recover(initialHolder, firstTokenId), 'ERC721IncorrectOwner', [ + this.token.address, + firstTokenId, + owner, + ]); + }); + }); + + describe('ERC712 behavior', function () { + shouldBehaveLikeERC721(...accounts); + }); +}); diff --git a/test/token/ERC721/utils/ERC721Holder.test.js b/test/token/ERC721/utils/ERC721Holder.test.js new file mode 100644 index 000000000..4aa2b7948 --- /dev/null +++ b/test/token/ERC721/utils/ERC721Holder.test.js @@ -0,0 +1,22 @@ +const { expect } = require('chai'); + +const ERC721Holder = artifacts.require('$ERC721Holder'); +const ERC721 = artifacts.require('$ERC721'); + +contract('ERC721Holder', function (accounts) { + const [owner] = accounts; + + const name = 'Non Fungible Token'; + const symbol = 'NFT'; + const tokenId = web3.utils.toBN(1); + + it('receives an ERC721 token', async function () { + const token = await ERC721.new(name, symbol); + await token.$_mint(owner, tokenId); + + const receiver = await ERC721Holder.new(); + await token.safeTransferFrom(owner, receiver.address, tokenId, { from: owner }); + + expect(await token.ownerOf(tokenId)).to.be.equal(receiver.address); + }); +}); diff --git a/test/token/common/ERC2981.behavior.js b/test/token/common/ERC2981.behavior.js new file mode 100644 index 000000000..15efa239f --- /dev/null +++ b/test/token/common/ERC2981.behavior.js @@ -0,0 +1,169 @@ +const { BN, constants } = require('@openzeppelin/test-helpers'); +const { expect } = require('chai'); +const { ZERO_ADDRESS } = constants; + +const { shouldSupportInterfaces } = require('../../utils/introspection/SupportsInterface.behavior'); +const { expectRevertCustomError } = require('../../helpers/customError'); + +function shouldBehaveLikeERC2981() { + const royaltyFraction = new BN('10'); + + shouldSupportInterfaces(['ERC2981']); + + describe('default royalty', function () { + beforeEach(async function () { + await this.token.$_setDefaultRoyalty(this.account1, royaltyFraction); + }); + + it('checks royalty is set', async function () { + const royalty = new BN((this.salePrice * royaltyFraction) / 10000); + + const initInfo = await this.token.royaltyInfo(this.tokenId1, this.salePrice); + + expect(initInfo[0]).to.be.equal(this.account1); + expect(initInfo[1]).to.be.bignumber.equal(royalty); + }); + + it('updates royalty amount', async function () { + const newPercentage = new BN('25'); + + // Updated royalty check + await this.token.$_setDefaultRoyalty(this.account1, newPercentage); + const royalty = new BN((this.salePrice * newPercentage) / 10000); + const newInfo = await this.token.royaltyInfo(this.tokenId1, this.salePrice); + + expect(newInfo[0]).to.be.equal(this.account1); + expect(newInfo[1]).to.be.bignumber.equal(royalty); + }); + + it('holds same royalty value for different tokens', async function () { + const newPercentage = new BN('20'); + await this.token.$_setDefaultRoyalty(this.account1, newPercentage); + + const token1Info = await this.token.royaltyInfo(this.tokenId1, this.salePrice); + const token2Info = await this.token.royaltyInfo(this.tokenId2, this.salePrice); + + expect(token1Info[1]).to.be.bignumber.equal(token2Info[1]); + }); + + it('Remove royalty information', async function () { + const newValue = new BN('0'); + await this.token.$_deleteDefaultRoyalty(); + + const token1Info = await this.token.royaltyInfo(this.tokenId1, this.salePrice); + const token2Info = await this.token.royaltyInfo(this.tokenId2, this.salePrice); + // Test royalty info is still persistent across all tokens + expect(token1Info[0]).to.be.bignumber.equal(token2Info[0]); + expect(token1Info[1]).to.be.bignumber.equal(token2Info[1]); + // Test information was deleted + expect(token1Info[0]).to.be.equal(ZERO_ADDRESS); + expect(token1Info[1]).to.be.bignumber.equal(newValue); + }); + + it('reverts if invalid parameters', async function () { + const royaltyDenominator = await this.token.$_feeDenominator(); + await expectRevertCustomError( + this.token.$_setDefaultRoyalty(ZERO_ADDRESS, royaltyFraction), + 'ERC2981InvalidDefaultRoyaltyReceiver', + [ZERO_ADDRESS], + ); + + const anotherRoyaltyFraction = new BN('11000'); + await expectRevertCustomError( + this.token.$_setDefaultRoyalty(this.account1, anotherRoyaltyFraction), + 'ERC2981InvalidDefaultRoyalty', + [anotherRoyaltyFraction, royaltyDenominator], + ); + }); + }); + + describe('token based royalty', function () { + beforeEach(async function () { + await this.token.$_setTokenRoyalty(this.tokenId1, this.account1, royaltyFraction); + }); + + it('updates royalty amount', async function () { + const newPercentage = new BN('25'); + let royalty = new BN((this.salePrice * royaltyFraction) / 10000); + // Initial royalty check + const initInfo = await this.token.royaltyInfo(this.tokenId1, this.salePrice); + + expect(initInfo[0]).to.be.equal(this.account1); + expect(initInfo[1]).to.be.bignumber.equal(royalty); + + // Updated royalty check + await this.token.$_setTokenRoyalty(this.tokenId1, this.account1, newPercentage); + royalty = new BN((this.salePrice * newPercentage) / 10000); + const newInfo = await this.token.royaltyInfo(this.tokenId1, this.salePrice); + + expect(newInfo[0]).to.be.equal(this.account1); + expect(newInfo[1]).to.be.bignumber.equal(royalty); + }); + + it('holds different values for different tokens', async function () { + const newPercentage = new BN('20'); + await this.token.$_setTokenRoyalty(this.tokenId2, this.account1, newPercentage); + + const token1Info = await this.token.royaltyInfo(this.tokenId1, this.salePrice); + const token2Info = await this.token.royaltyInfo(this.tokenId2, this.salePrice); + + // must be different even at the same this.salePrice + expect(token1Info[1]).to.not.be.equal(token2Info.royaltyFraction); + }); + + it('reverts if invalid parameters', async function () { + const royaltyDenominator = await this.token.$_feeDenominator(); + await expectRevertCustomError( + this.token.$_setTokenRoyalty(this.tokenId1, ZERO_ADDRESS, royaltyFraction), + 'ERC2981InvalidTokenRoyaltyReceiver', + [this.tokenId1.toString(), ZERO_ADDRESS], + ); + + const anotherRoyaltyFraction = new BN('11000'); + await expectRevertCustomError( + this.token.$_setTokenRoyalty(this.tokenId1, this.account1, anotherRoyaltyFraction), + 'ERC2981InvalidTokenRoyalty', + [this.tokenId1.toString(), anotherRoyaltyFraction, royaltyDenominator], + ); + }); + + it('can reset token after setting royalty', async function () { + const newPercentage = new BN('30'); + const royalty = new BN((this.salePrice * newPercentage) / 10000); + await this.token.$_setTokenRoyalty(this.tokenId1, this.account2, newPercentage); + + const tokenInfo = await this.token.royaltyInfo(this.tokenId1, this.salePrice); + + // Tokens must have own information + expect(tokenInfo[1]).to.be.bignumber.equal(royalty); + expect(tokenInfo[0]).to.be.equal(this.account2); + + await this.token.$_setTokenRoyalty(this.tokenId2, this.account1, new BN('0')); + const result = await this.token.royaltyInfo(this.tokenId2, this.salePrice); + // Token must not share default information + expect(result[0]).to.be.equal(this.account1); + expect(result[1]).to.be.bignumber.equal(new BN('0')); + }); + + it('can hold default and token royalty information', async function () { + const newPercentage = new BN('30'); + const royalty = new BN((this.salePrice * newPercentage) / 10000); + + await this.token.$_setTokenRoyalty(this.tokenId2, this.account2, newPercentage); + + const token1Info = await this.token.royaltyInfo(this.tokenId1, this.salePrice); + const token2Info = await this.token.royaltyInfo(this.tokenId2, this.salePrice); + // Tokens must not have same values + expect(token1Info[1]).to.not.be.bignumber.equal(token2Info[1]); + expect(token1Info[0]).to.not.be.equal(token2Info[0]); + + // Updated token must have new values + expect(token2Info[0]).to.be.equal(this.account2); + expect(token2Info[1]).to.be.bignumber.equal(royalty); + }); + }); +} + +module.exports = { + shouldBehaveLikeERC2981, +}; diff --git a/test/utils/Address.test.js b/test/utils/Address.test.js new file mode 100644 index 000000000..57453abd5 --- /dev/null +++ b/test/utils/Address.test.js @@ -0,0 +1,340 @@ +const { balance, constants, ether, expectRevert, send, expectEvent } = require('@openzeppelin/test-helpers'); +const { expect } = require('chai'); +const { expectRevertCustomError } = require('../helpers/customError'); + +const Address = artifacts.require('$Address'); +const EtherReceiver = artifacts.require('EtherReceiverMock'); +const CallReceiverMock = artifacts.require('CallReceiverMock'); + +contract('Address', function (accounts) { + const [recipient, other] = accounts; + + beforeEach(async function () { + this.mock = await Address.new(); + }); + + describe('sendValue', function () { + beforeEach(async function () { + this.recipientTracker = await balance.tracker(recipient); + }); + + context('when sender contract has no funds', function () { + it('sends 0 wei', async function () { + await this.mock.$sendValue(other, 0); + + expect(await this.recipientTracker.delta()).to.be.bignumber.equal('0'); + }); + + it('reverts when sending non-zero amounts', async function () { + await expectRevertCustomError(this.mock.$sendValue(other, 1), 'AddressInsufficientBalance', [ + this.mock.address, + ]); + }); + }); + + context('when sender contract has funds', function () { + const funds = ether('1'); + beforeEach(async function () { + await send.ether(other, this.mock.address, funds); + }); + + it('sends 0 wei', async function () { + await this.mock.$sendValue(recipient, 0); + expect(await this.recipientTracker.delta()).to.be.bignumber.equal('0'); + }); + + it('sends non-zero amounts', async function () { + await this.mock.$sendValue(recipient, funds.subn(1)); + expect(await this.recipientTracker.delta()).to.be.bignumber.equal(funds.subn(1)); + }); + + it('sends the whole balance', async function () { + await this.mock.$sendValue(recipient, funds); + expect(await this.recipientTracker.delta()).to.be.bignumber.equal(funds); + expect(await balance.current(this.mock.address)).to.be.bignumber.equal('0'); + }); + + it('reverts when sending more than the balance', async function () { + await expectRevertCustomError(this.mock.$sendValue(recipient, funds.addn(1)), 'AddressInsufficientBalance', [ + this.mock.address, + ]); + }); + + context('with contract recipient', function () { + beforeEach(async function () { + this.target = await EtherReceiver.new(); + }); + + it('sends funds', async function () { + const tracker = await balance.tracker(this.target.address); + + await this.target.setAcceptEther(true); + await this.mock.$sendValue(this.target.address, funds); + + expect(await tracker.delta()).to.be.bignumber.equal(funds); + }); + + it('reverts on recipient revert', async function () { + await this.target.setAcceptEther(false); + await expectRevertCustomError(this.mock.$sendValue(this.target.address, funds), 'FailedInnerCall', []); + }); + }); + }); + }); + + describe('functionCall', function () { + beforeEach(async function () { + this.target = await CallReceiverMock.new(); + }); + + context('with valid contract receiver', function () { + it('calls the requested function', async function () { + const abiEncodedCall = this.target.contract.methods.mockFunction().encodeABI(); + + const receipt = await this.mock.$functionCall(this.target.address, abiEncodedCall); + + expectEvent(receipt, 'return$functionCall', { + ret0: web3.eth.abi.encodeParameters(['string'], ['0x1234']), + }); + await expectEvent.inTransaction(receipt.tx, CallReceiverMock, 'MockFunctionCalled'); + }); + + it('calls the requested empty return function', async function () { + const abiEncodedCall = this.target.contract.methods.mockFunctionEmptyReturn().encodeABI(); + + const receipt = await this.mock.$functionCall(this.target.address, abiEncodedCall); + + await expectEvent.inTransaction(receipt.tx, CallReceiverMock, 'MockFunctionCalled'); + }); + + it('reverts when the called function reverts with no reason', async function () { + const abiEncodedCall = this.target.contract.methods.mockFunctionRevertsNoReason().encodeABI(); + + await expectRevertCustomError( + this.mock.$functionCall(this.target.address, abiEncodedCall), + 'FailedInnerCall', + [], + ); + }); + + it('reverts when the called function reverts, bubbling up the revert reason', async function () { + const abiEncodedCall = this.target.contract.methods.mockFunctionRevertsReason().encodeABI(); + + await expectRevert(this.mock.$functionCall(this.target.address, abiEncodedCall), 'CallReceiverMock: reverting'); + }); + + it('reverts when the called function runs out of gas', async function () { + const abiEncodedCall = this.target.contract.methods.mockFunctionOutOfGas().encodeABI(); + + await expectRevertCustomError( + this.mock.$functionCall(this.target.address, abiEncodedCall, { gas: '120000' }), + 'FailedInnerCall', + [], + ); + }); + + it('reverts when the called function throws', async function () { + const abiEncodedCall = this.target.contract.methods.mockFunctionThrows().encodeABI(); + + await expectRevert.unspecified(this.mock.$functionCall(this.target.address, abiEncodedCall)); + }); + + it('reverts when function does not exist', async function () { + const abiEncodedCall = web3.eth.abi.encodeFunctionCall( + { + name: 'mockFunctionDoesNotExist', + type: 'function', + inputs: [], + }, + [], + ); + + await expectRevertCustomError( + this.mock.$functionCall(this.target.address, abiEncodedCall), + 'FailedInnerCall', + [], + ); + }); + }); + + context('with non-contract receiver', function () { + it('reverts when address is not a contract', async function () { + const [recipient] = accounts; + const abiEncodedCall = this.target.contract.methods.mockFunction().encodeABI(); + + await expectRevertCustomError(this.mock.$functionCall(recipient, abiEncodedCall), 'AddressEmptyCode', [ + recipient, + ]); + }); + }); + }); + + describe('functionCallWithValue', function () { + beforeEach(async function () { + this.target = await CallReceiverMock.new(); + }); + + context('with zero value', function () { + it('calls the requested function', async function () { + const abiEncodedCall = this.target.contract.methods.mockFunction().encodeABI(); + + const receipt = await this.mock.$functionCallWithValue(this.target.address, abiEncodedCall, 0); + expectEvent(receipt, 'return$functionCallWithValue', { + ret0: web3.eth.abi.encodeParameters(['string'], ['0x1234']), + }); + await expectEvent.inTransaction(receipt.tx, CallReceiverMock, 'MockFunctionCalled'); + }); + }); + + context('with non-zero value', function () { + const amount = ether('1.2'); + + it('reverts if insufficient sender balance', async function () { + const abiEncodedCall = this.target.contract.methods.mockFunction().encodeABI(); + + await expectRevertCustomError( + this.mock.$functionCallWithValue(this.target.address, abiEncodedCall, amount), + 'AddressInsufficientBalance', + [this.mock.address], + ); + }); + + it('calls the requested function with existing value', async function () { + const abiEncodedCall = this.target.contract.methods.mockFunction().encodeABI(); + + const tracker = await balance.tracker(this.target.address); + + await send.ether(other, this.mock.address, amount); + + const receipt = await this.mock.$functionCallWithValue(this.target.address, abiEncodedCall, amount); + expectEvent(receipt, 'return$functionCallWithValue', { + ret0: web3.eth.abi.encodeParameters(['string'], ['0x1234']), + }); + await expectEvent.inTransaction(receipt.tx, CallReceiverMock, 'MockFunctionCalled'); + + expect(await tracker.delta()).to.be.bignumber.equal(amount); + }); + + it('calls the requested function with transaction funds', async function () { + const abiEncodedCall = this.target.contract.methods.mockFunction().encodeABI(); + + const tracker = await balance.tracker(this.target.address); + + expect(await balance.current(this.mock.address)).to.be.bignumber.equal('0'); + + const receipt = await this.mock.$functionCallWithValue(this.target.address, abiEncodedCall, amount, { + from: other, + value: amount, + }); + expectEvent(receipt, 'return$functionCallWithValue', { + ret0: web3.eth.abi.encodeParameters(['string'], ['0x1234']), + }); + await expectEvent.inTransaction(receipt.tx, CallReceiverMock, 'MockFunctionCalled'); + + expect(await tracker.delta()).to.be.bignumber.equal(amount); + }); + + it('reverts when calling non-payable functions', async function () { + const abiEncodedCall = this.target.contract.methods.mockFunctionNonPayable().encodeABI(); + + await send.ether(other, this.mock.address, amount); + await expectRevertCustomError( + this.mock.$functionCallWithValue(this.target.address, abiEncodedCall, amount), + 'FailedInnerCall', + [], + ); + }); + }); + }); + + describe('functionStaticCall', function () { + beforeEach(async function () { + this.target = await CallReceiverMock.new(); + }); + + it('calls the requested function', async function () { + const abiEncodedCall = this.target.contract.methods.mockStaticFunction().encodeABI(); + + expect(await this.mock.$functionStaticCall(this.target.address, abiEncodedCall)).to.be.equal( + web3.eth.abi.encodeParameters(['string'], ['0x1234']), + ); + }); + + it('reverts on a non-static function', async function () { + const abiEncodedCall = this.target.contract.methods.mockFunction().encodeABI(); + + await expectRevertCustomError( + this.mock.$functionStaticCall(this.target.address, abiEncodedCall), + 'FailedInnerCall', + [], + ); + }); + + it('bubbles up revert reason', async function () { + const abiEncodedCall = this.target.contract.methods.mockFunctionRevertsReason().encodeABI(); + + await expectRevert( + this.mock.$functionStaticCall(this.target.address, abiEncodedCall), + 'CallReceiverMock: reverting', + ); + }); + + it('reverts when address is not a contract', async function () { + const [recipient] = accounts; + const abiEncodedCall = this.target.contract.methods.mockFunction().encodeABI(); + + await expectRevertCustomError(this.mock.$functionStaticCall(recipient, abiEncodedCall), 'AddressEmptyCode', [ + recipient, + ]); + }); + }); + + describe('functionDelegateCall', function () { + beforeEach(async function () { + this.target = await CallReceiverMock.new(); + }); + + it('delegate calls the requested function', async function () { + // pseudorandom values + const slot = '0x93e4c53af435ddf777c3de84bb9a953a777788500e229a468ea1036496ab66a0'; + const value = '0x6a465d1c49869f71fb65562bcbd7e08c8044074927f0297127203f2a9924ff5b'; + + const abiEncodedCall = this.target.contract.methods.mockFunctionWritesStorage(slot, value).encodeABI(); + + expect(await web3.eth.getStorageAt(this.mock.address, slot)).to.be.equal(constants.ZERO_BYTES32); + + expectEvent( + await this.mock.$functionDelegateCall(this.target.address, abiEncodedCall), + 'return$functionDelegateCall', + { ret0: web3.eth.abi.encodeParameters(['string'], ['0x1234']) }, + ); + + expect(await web3.eth.getStorageAt(this.mock.address, slot)).to.be.equal(value); + }); + + it('bubbles up revert reason', async function () { + const abiEncodedCall = this.target.contract.methods.mockFunctionRevertsReason().encodeABI(); + + await expectRevert( + this.mock.$functionDelegateCall(this.target.address, abiEncodedCall), + 'CallReceiverMock: reverting', + ); + }); + + it('reverts when address is not a contract', async function () { + const [recipient] = accounts; + const abiEncodedCall = this.target.contract.methods.mockFunction().encodeABI(); + + await expectRevertCustomError(this.mock.$functionDelegateCall(recipient, abiEncodedCall), 'AddressEmptyCode', [ + recipient, + ]); + }); + }); + + describe('verifyCallResult', function () { + it('returns returndata on success', async function () { + const returndata = '0x123abc'; + expect(await this.mock.$verifyCallResult(true, returndata)).to.equal(returndata); + }); + }); +}); diff --git a/test/utils/Arrays.test.js b/test/utils/Arrays.test.js new file mode 100644 index 000000000..d939d59bd --- /dev/null +++ b/test/utils/Arrays.test.js @@ -0,0 +1,123 @@ +require('@openzeppelin/test-helpers'); + +const { expect } = require('chai'); + +const AddressArraysMock = artifacts.require('AddressArraysMock'); +const Bytes32ArraysMock = artifacts.require('Bytes32ArraysMock'); +const Uint256ArraysMock = artifacts.require('Uint256ArraysMock'); + +contract('Arrays', function () { + describe('findUpperBound', function () { + context('Even number of elements', function () { + const EVEN_ELEMENTS_ARRAY = [11, 12, 13, 14, 15, 16, 17, 18, 19, 20]; + + beforeEach(async function () { + this.arrays = await Uint256ArraysMock.new(EVEN_ELEMENTS_ARRAY); + }); + + it('returns correct index for the basic case', async function () { + expect(await this.arrays.findUpperBound(16)).to.be.bignumber.equal('5'); + }); + + it('returns 0 for the first element', async function () { + expect(await this.arrays.findUpperBound(11)).to.be.bignumber.equal('0'); + }); + + it('returns index of the last element', async function () { + expect(await this.arrays.findUpperBound(20)).to.be.bignumber.equal('9'); + }); + + it('returns first index after last element if searched value is over the upper boundary', async function () { + expect(await this.arrays.findUpperBound(32)).to.be.bignumber.equal('10'); + }); + + it('returns 0 for the element under the lower boundary', async function () { + expect(await this.arrays.findUpperBound(2)).to.be.bignumber.equal('0'); + }); + }); + + context('Odd number of elements', function () { + const ODD_ELEMENTS_ARRAY = [11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21]; + + beforeEach(async function () { + this.arrays = await Uint256ArraysMock.new(ODD_ELEMENTS_ARRAY); + }); + + it('returns correct index for the basic case', async function () { + expect(await this.arrays.findUpperBound(16)).to.be.bignumber.equal('5'); + }); + + it('returns 0 for the first element', async function () { + expect(await this.arrays.findUpperBound(11)).to.be.bignumber.equal('0'); + }); + + it('returns index of the last element', async function () { + expect(await this.arrays.findUpperBound(21)).to.be.bignumber.equal('10'); + }); + + it('returns first index after last element if searched value is over the upper boundary', async function () { + expect(await this.arrays.findUpperBound(32)).to.be.bignumber.equal('11'); + }); + + it('returns 0 for the element under the lower boundary', async function () { + expect(await this.arrays.findUpperBound(2)).to.be.bignumber.equal('0'); + }); + }); + + context('Array with gap', function () { + const WITH_GAP_ARRAY = [11, 12, 13, 14, 15, 20, 21, 22, 23, 24]; + + beforeEach(async function () { + this.arrays = await Uint256ArraysMock.new(WITH_GAP_ARRAY); + }); + + it('returns index of first element in next filled range', async function () { + expect(await this.arrays.findUpperBound(17)).to.be.bignumber.equal('5'); + }); + }); + + context('Empty array', function () { + beforeEach(async function () { + this.arrays = await Uint256ArraysMock.new([]); + }); + + it('always returns 0 for empty array', async function () { + expect(await this.arrays.findUpperBound(10)).to.be.bignumber.equal('0'); + }); + }); + }); + + describe('unsafeAccess', function () { + for (const { type, artifact, elements } of [ + { + type: 'address', + artifact: AddressArraysMock, + elements: Array(10) + .fill() + .map(() => web3.utils.randomHex(20)), + }, + { + type: 'bytes32', + artifact: Bytes32ArraysMock, + elements: Array(10) + .fill() + .map(() => web3.utils.randomHex(32)), + }, + { + type: 'uint256', + artifact: Uint256ArraysMock, + elements: Array(10) + .fill() + .map(() => web3.utils.randomHex(32)), + }, + ]) { + it(type, async function () { + const contract = await artifact.new(elements); + + for (const i in elements) { + expect(await contract.unsafeAccess(i)).to.be.bignumber.equal(elements[i]); + } + }); + } + }); +}); diff --git a/test/utils/Base64.test.js b/test/utils/Base64.test.js new file mode 100644 index 000000000..dfff0b0d0 --- /dev/null +++ b/test/utils/Base64.test.js @@ -0,0 +1,33 @@ +const { expect } = require('chai'); + +const Base64 = artifacts.require('$Base64'); + +contract('Strings', function () { + beforeEach(async function () { + this.base64 = await Base64.new(); + }); + + describe('from bytes - base64', function () { + it('converts to base64 encoded string with double padding', async function () { + const TEST_MESSAGE = 'test'; + const input = web3.utils.asciiToHex(TEST_MESSAGE); + expect(await this.base64.$encode(input)).to.equal('dGVzdA=='); + }); + + it('converts to base64 encoded string with single padding', async function () { + const TEST_MESSAGE = 'test1'; + const input = web3.utils.asciiToHex(TEST_MESSAGE); + expect(await this.base64.$encode(input)).to.equal('dGVzdDE='); + }); + + it('converts to base64 encoded string without padding', async function () { + const TEST_MESSAGE = 'test12'; + const input = web3.utils.asciiToHex(TEST_MESSAGE); + expect(await this.base64.$encode(input)).to.equal('dGVzdDEy'); + }); + + it('empty bytes', async function () { + expect(await this.base64.$encode([])).to.equal(''); + }); + }); +}); diff --git a/test/utils/Context.behavior.js b/test/utils/Context.behavior.js new file mode 100644 index 000000000..08f7558d7 --- /dev/null +++ b/test/utils/Context.behavior.js @@ -0,0 +1,42 @@ +const { BN, expectEvent } = require('@openzeppelin/test-helpers'); + +const ContextMock = artifacts.require('ContextMock'); + +function shouldBehaveLikeRegularContext(sender) { + describe('msgSender', function () { + it('returns the transaction sender when called from an EOA', async function () { + const receipt = await this.context.msgSender({ from: sender }); + expectEvent(receipt, 'Sender', { sender }); + }); + + it('returns the transaction sender when from another contract', async function () { + const { tx } = await this.caller.callSender(this.context.address, { from: sender }); + await expectEvent.inTransaction(tx, ContextMock, 'Sender', { sender: this.caller.address }); + }); + }); + + describe('msgData', function () { + const integerValue = new BN('42'); + const stringValue = 'OpenZeppelin'; + + let callData; + + beforeEach(async function () { + callData = this.context.contract.methods.msgData(integerValue.toString(), stringValue).encodeABI(); + }); + + it('returns the transaction data when called from an EOA', async function () { + const receipt = await this.context.msgData(integerValue, stringValue); + expectEvent(receipt, 'Data', { data: callData, integerValue, stringValue }); + }); + + it('returns the transaction sender when from another contract', async function () { + const { tx } = await this.caller.callData(this.context.address, integerValue, stringValue); + await expectEvent.inTransaction(tx, ContextMock, 'Data', { data: callData, integerValue, stringValue }); + }); + }); +} + +module.exports = { + shouldBehaveLikeRegularContext, +}; diff --git a/test/utils/Context.test.js b/test/utils/Context.test.js new file mode 100644 index 000000000..f372f7420 --- /dev/null +++ b/test/utils/Context.test.js @@ -0,0 +1,17 @@ +require('@openzeppelin/test-helpers'); + +const ContextMock = artifacts.require('ContextMock'); +const ContextMockCaller = artifacts.require('ContextMockCaller'); + +const { shouldBehaveLikeRegularContext } = require('./Context.behavior'); + +contract('Context', function (accounts) { + const [sender] = accounts; + + beforeEach(async function () { + this.context = await ContextMock.new(); + this.caller = await ContextMockCaller.new(); + }); + + shouldBehaveLikeRegularContext(sender); +}); diff --git a/test/utils/Create2.test.js b/test/utils/Create2.test.js new file mode 100644 index 000000000..336ab1acc --- /dev/null +++ b/test/utils/Create2.test.js @@ -0,0 +1,102 @@ +const { balance, ether, expectEvent, expectRevert, send } = require('@openzeppelin/test-helpers'); +const { expect } = require('chai'); +const { computeCreate2Address } = require('../helpers/create'); +const { expectRevertCustomError } = require('../helpers/customError'); + +const Create2 = artifacts.require('$Create2'); +const VestingWallet = artifacts.require('VestingWallet'); +// This should be a contract that: +// - has no constructor arguments +// - has no immutable variable populated during construction +const ConstructorLessContract = Create2; + +contract('Create2', function (accounts) { + const [deployerAccount, other] = accounts; + + const salt = 'salt message'; + const saltHex = web3.utils.soliditySha3(salt); + + const encodedParams = web3.eth.abi.encodeParameters(['address', 'uint64', 'uint64'], [other, 0, 0]).slice(2); + + const constructorByteCode = `${VestingWallet.bytecode}${encodedParams}`; + + beforeEach(async function () { + this.factory = await Create2.new(); + }); + describe('computeAddress', function () { + it('computes the correct contract address', async function () { + const onChainComputed = await this.factory.$computeAddress(saltHex, web3.utils.keccak256(constructorByteCode)); + const offChainComputed = computeCreate2Address(saltHex, constructorByteCode, this.factory.address); + expect(onChainComputed).to.equal(offChainComputed); + }); + + it('computes the correct contract address with deployer', async function () { + const onChainComputed = await this.factory.$computeAddress( + saltHex, + web3.utils.keccak256(constructorByteCode), + deployerAccount, + ); + const offChainComputed = computeCreate2Address(saltHex, constructorByteCode, deployerAccount); + expect(onChainComputed).to.equal(offChainComputed); + }); + }); + + describe('deploy', function () { + it('deploys a contract without constructor', async function () { + const offChainComputed = computeCreate2Address(saltHex, ConstructorLessContract.bytecode, this.factory.address); + + expectEvent(await this.factory.$deploy(0, saltHex, ConstructorLessContract.bytecode), 'return$deploy', { + addr: offChainComputed, + }); + + expect(ConstructorLessContract.bytecode).to.include((await web3.eth.getCode(offChainComputed)).slice(2)); + }); + + it('deploys a contract with constructor arguments', async function () { + const offChainComputed = computeCreate2Address(saltHex, constructorByteCode, this.factory.address); + + expectEvent(await this.factory.$deploy(0, saltHex, constructorByteCode), 'return$deploy', { + addr: offChainComputed, + }); + + const instance = await VestingWallet.at(offChainComputed); + + expect(await instance.owner()).to.be.equal(other); + }); + + it('deploys a contract with funds deposited in the factory', async function () { + const deposit = ether('2'); + await send.ether(deployerAccount, this.factory.address, deposit); + expect(await balance.current(this.factory.address)).to.be.bignumber.equal(deposit); + + const offChainComputed = computeCreate2Address(saltHex, constructorByteCode, this.factory.address); + + expectEvent(await this.factory.$deploy(deposit, saltHex, constructorByteCode), 'return$deploy', { + addr: offChainComputed, + }); + + expect(await balance.current(offChainComputed)).to.be.bignumber.equal(deposit); + }); + + it('fails deploying a contract in an existent address', async function () { + expectEvent(await this.factory.$deploy(0, saltHex, constructorByteCode), 'return$deploy'); + + // TODO: Make sure it actually throws "Create2FailedDeployment". + // For some unknown reason, the revert reason sometimes return: + // `revert with unrecognized return data or custom error` + await expectRevert.unspecified(this.factory.$deploy(0, saltHex, constructorByteCode)); + }); + + it('fails deploying a contract if the bytecode length is zero', async function () { + await expectRevertCustomError(this.factory.$deploy(0, saltHex, '0x'), 'Create2EmptyBytecode', []); + }); + + it('fails deploying a contract if factory contract does not have sufficient balance', async function () { + await expectRevertCustomError( + this.factory.$deploy(1, saltHex, constructorByteCode), + 'Create2InsufficientBalance', + [0, 1], + ); + }); + }); +}); diff --git a/test/utils/Multicall.test.js b/test/utils/Multicall.test.js new file mode 100644 index 000000000..65443cd0a --- /dev/null +++ b/test/utils/Multicall.test.js @@ -0,0 +1,69 @@ +const { BN } = require('@openzeppelin/test-helpers'); +const { expectRevertCustomError } = require('../helpers/customError'); + +const ERC20MulticallMock = artifacts.require('$ERC20MulticallMock'); + +contract('Multicall', function (accounts) { + const [deployer, alice, bob] = accounts; + const amount = 12000; + + beforeEach(async function () { + this.multicallToken = await ERC20MulticallMock.new('name', 'symbol'); + await this.multicallToken.$_mint(deployer, amount); + }); + + it('batches function calls', async function () { + expect(await this.multicallToken.balanceOf(alice)).to.be.bignumber.equal(new BN('0')); + expect(await this.multicallToken.balanceOf(bob)).to.be.bignumber.equal(new BN('0')); + + await this.multicallToken.multicall( + [ + this.multicallToken.contract.methods.transfer(alice, amount / 2).encodeABI(), + this.multicallToken.contract.methods.transfer(bob, amount / 3).encodeABI(), + ], + { from: deployer }, + ); + + expect(await this.multicallToken.balanceOf(alice)).to.be.bignumber.equal(new BN(amount / 2)); + expect(await this.multicallToken.balanceOf(bob)).to.be.bignumber.equal(new BN(amount / 3)); + }); + + it('returns an array with the result of each call', async function () { + const MulticallTest = artifacts.require('MulticallTest'); + const multicallTest = await MulticallTest.new({ from: deployer }); + await this.multicallToken.transfer(multicallTest.address, amount, { from: deployer }); + expect(await this.multicallToken.balanceOf(multicallTest.address)).to.be.bignumber.equal(new BN(amount)); + + const recipients = [alice, bob]; + const amounts = [amount / 2, amount / 3].map(n => new BN(n)); + + await multicallTest.checkReturnValues(this.multicallToken.address, recipients, amounts); + }); + + it('reverts previous calls', async function () { + expect(await this.multicallToken.balanceOf(alice)).to.be.bignumber.equal(new BN('0')); + + const call = this.multicallToken.multicall( + [ + this.multicallToken.contract.methods.transfer(alice, amount).encodeABI(), + this.multicallToken.contract.methods.transfer(bob, amount).encodeABI(), + ], + { from: deployer }, + ); + + await expectRevertCustomError(call, 'ERC20InsufficientBalance', [deployer, 0, amount]); + expect(await this.multicallToken.balanceOf(alice)).to.be.bignumber.equal(new BN('0')); + }); + + it('bubbles up revert reasons', async function () { + const call = this.multicallToken.multicall( + [ + this.multicallToken.contract.methods.transfer(alice, amount).encodeABI(), + this.multicallToken.contract.methods.transfer(bob, amount).encodeABI(), + ], + { from: deployer }, + ); + + await expectRevertCustomError(call, 'ERC20InsufficientBalance', [deployer, 0, amount]); + }); +}); diff --git a/test/utils/Nonces.test.js b/test/utils/Nonces.test.js new file mode 100644 index 000000000..67a3087e3 --- /dev/null +++ b/test/utils/Nonces.test.js @@ -0,0 +1,71 @@ +const expectEvent = require('@openzeppelin/test-helpers/src/expectEvent'); +const { expectRevertCustomError } = require('../helpers/customError'); + +require('@openzeppelin/test-helpers'); + +const Nonces = artifacts.require('$Nonces'); + +contract('Nonces', function (accounts) { + const [sender, other] = accounts; + + beforeEach(async function () { + this.nonces = await Nonces.new(); + }); + + it('gets a nonce', async function () { + expect(await this.nonces.nonces(sender)).to.be.bignumber.equal('0'); + }); + + describe('_useNonce', function () { + it('increments a nonce', async function () { + expect(await this.nonces.nonces(sender)).to.be.bignumber.equal('0'); + + const { receipt } = await this.nonces.$_useNonce(sender); + expectEvent(receipt, 'return$_useNonce', ['0']); + + expect(await this.nonces.nonces(sender)).to.be.bignumber.equal('1'); + }); + + it("increments only sender's nonce", async function () { + expect(await this.nonces.nonces(sender)).to.be.bignumber.equal('0'); + expect(await this.nonces.nonces(other)).to.be.bignumber.equal('0'); + + await this.nonces.$_useNonce(sender); + + expect(await this.nonces.nonces(sender)).to.be.bignumber.equal('1'); + expect(await this.nonces.nonces(other)).to.be.bignumber.equal('0'); + }); + }); + + describe('_useCheckedNonce', function () { + it('increments a nonce', async function () { + const currentNonce = await this.nonces.nonces(sender); + expect(currentNonce).to.be.bignumber.equal('0'); + + await this.nonces.$_useCheckedNonce(sender, currentNonce); + + expect(await this.nonces.nonces(sender)).to.be.bignumber.equal('1'); + }); + + it("increments only sender's nonce", async function () { + const currentNonce = await this.nonces.nonces(sender); + + expect(currentNonce).to.be.bignumber.equal('0'); + expect(await this.nonces.nonces(other)).to.be.bignumber.equal('0'); + + await this.nonces.$_useCheckedNonce(sender, currentNonce); + + expect(await this.nonces.nonces(sender)).to.be.bignumber.equal('1'); + expect(await this.nonces.nonces(other)).to.be.bignumber.equal('0'); + }); + + it('reverts when nonce is not the expected', async function () { + const currentNonce = await this.nonces.nonces(sender); + await expectRevertCustomError( + this.nonces.$_useCheckedNonce(sender, currentNonce.addn(1)), + 'InvalidAccountNonce', + [sender, currentNonce], + ); + }); + }); +}); diff --git a/test/utils/Pausable.test.js b/test/utils/Pausable.test.js new file mode 100644 index 000000000..e60a62c74 --- /dev/null +++ b/test/utils/Pausable.test.js @@ -0,0 +1,86 @@ +const { expectEvent } = require('@openzeppelin/test-helpers'); +const { expect } = require('chai'); + +const { expectRevertCustomError } = require('../helpers/customError'); + +const PausableMock = artifacts.require('PausableMock'); + +contract('Pausable', function (accounts) { + const [pauser] = accounts; + + beforeEach(async function () { + this.pausable = await PausableMock.new(); + }); + + context('when unpaused', function () { + beforeEach(async function () { + expect(await this.pausable.paused()).to.equal(false); + }); + + it('can perform normal process in non-pause', async function () { + expect(await this.pausable.count()).to.be.bignumber.equal('0'); + + await this.pausable.normalProcess(); + expect(await this.pausable.count()).to.be.bignumber.equal('1'); + }); + + it('cannot take drastic measure in non-pause', async function () { + await expectRevertCustomError(this.pausable.drasticMeasure(), 'ExpectedPause', []); + expect(await this.pausable.drasticMeasureTaken()).to.equal(false); + }); + + context('when paused', function () { + beforeEach(async function () { + this.receipt = await this.pausable.pause({ from: pauser }); + }); + + it('emits a Paused event', function () { + expectEvent(this.receipt, 'Paused', { account: pauser }); + }); + + it('cannot perform normal process in pause', async function () { + await expectRevertCustomError(this.pausable.normalProcess(), 'EnforcedPause', []); + }); + + it('can take a drastic measure in a pause', async function () { + await this.pausable.drasticMeasure(); + expect(await this.pausable.drasticMeasureTaken()).to.equal(true); + }); + + it('reverts when re-pausing', async function () { + await expectRevertCustomError(this.pausable.pause(), 'EnforcedPause', []); + }); + + describe('unpausing', function () { + it('is unpausable by the pauser', async function () { + await this.pausable.unpause(); + expect(await this.pausable.paused()).to.equal(false); + }); + + context('when unpaused', function () { + beforeEach(async function () { + this.receipt = await this.pausable.unpause({ from: pauser }); + }); + + it('emits an Unpaused event', function () { + expectEvent(this.receipt, 'Unpaused', { account: pauser }); + }); + + it('should resume allowing normal process', async function () { + expect(await this.pausable.count()).to.be.bignumber.equal('0'); + await this.pausable.normalProcess(); + expect(await this.pausable.count()).to.be.bignumber.equal('1'); + }); + + it('should prevent drastic measure', async function () { + await expectRevertCustomError(this.pausable.drasticMeasure(), 'ExpectedPause', []); + }); + + it('reverts when re-unpausing', async function () { + await expectRevertCustomError(this.pausable.unpause(), 'ExpectedPause', []); + }); + }); + }); + }); + }); +}); diff --git a/test/utils/ReentrancyGuard.test.js b/test/utils/ReentrancyGuard.test.js new file mode 100644 index 000000000..15355c098 --- /dev/null +++ b/test/utils/ReentrancyGuard.test.js @@ -0,0 +1,44 @@ +const { expectRevert } = require('@openzeppelin/test-helpers'); +const { expect } = require('chai'); + +const { expectRevertCustomError } = require('../helpers/customError'); + +const ReentrancyMock = artifacts.require('ReentrancyMock'); +const ReentrancyAttack = artifacts.require('ReentrancyAttack'); + +contract('ReentrancyGuard', function () { + beforeEach(async function () { + this.reentrancyMock = await ReentrancyMock.new(); + expect(await this.reentrancyMock.counter()).to.be.bignumber.equal('0'); + }); + + it('nonReentrant function can be called', async function () { + expect(await this.reentrancyMock.counter()).to.be.bignumber.equal('0'); + await this.reentrancyMock.callback(); + expect(await this.reentrancyMock.counter()).to.be.bignumber.equal('1'); + }); + + it('does not allow remote callback', async function () { + const attacker = await ReentrancyAttack.new(); + await expectRevert(this.reentrancyMock.countAndCall(attacker.address), 'ReentrancyAttack: failed call', []); + }); + + it('_reentrancyGuardEntered should be true when guarded', async function () { + await this.reentrancyMock.guardedCheckEntered(); + }); + + it('_reentrancyGuardEntered should be false when unguarded', async function () { + await this.reentrancyMock.unguardedCheckNotEntered(); + }); + + // The following are more side-effects than intended behavior: + // I put them here as documentation, and to monitor any changes + // in the side-effects. + it('does not allow local recursion', async function () { + await expectRevertCustomError(this.reentrancyMock.countLocalRecursive(10), 'ReentrancyGuardReentrantCall', []); + }); + + it('does not allow indirect local recursion', async function () { + await expectRevert(this.reentrancyMock.countThisRecursive(10), 'ReentrancyMock: failed call', []); + }); +}); diff --git a/test/utils/ShortStrings.t.sol b/test/utils/ShortStrings.t.sol new file mode 100644 index 000000000..b854d273c --- /dev/null +++ b/test/utils/ShortStrings.t.sol @@ -0,0 +1,55 @@ +// SPDX-License-Identifier: MIT + +pragma solidity ^0.8.20; + +import {Test} from "forge-std/Test.sol"; + +import {ShortStrings, ShortString} from "@openzeppelin/contracts/utils/ShortStrings.sol"; + +contract ShortStringsTest is Test { + string _fallback; + + function testRoundtripShort(string memory input) external { + vm.assume(_isShort(input)); + ShortString short = ShortStrings.toShortString(input); + string memory output = ShortStrings.toString(short); + assertEq(input, output); + } + + function testRoundtripWithFallback(string memory input, string memory fallbackInitial) external { + _fallback = fallbackInitial; // Make sure that the initial value has no effect + ShortString short = ShortStrings.toShortStringWithFallback(input, _fallback); + string memory output = ShortStrings.toStringWithFallback(short, _fallback); + assertEq(input, output); + } + + function testRevertLong(string memory input) external { + vm.assume(!_isShort(input)); + vm.expectRevert(abi.encodeWithSelector(ShortStrings.StringTooLong.selector, input)); + this.toShortString(input); + } + + function testLengthShort(string memory input) external { + vm.assume(_isShort(input)); + uint256 inputLength = bytes(input).length; + ShortString short = ShortStrings.toShortString(input); + uint256 shortLength = ShortStrings.byteLength(short); + assertEq(inputLength, shortLength); + } + + function testLengthWithFallback(string memory input, string memory fallbackInitial) external { + _fallback = fallbackInitial; + uint256 inputLength = bytes(input).length; + ShortString short = ShortStrings.toShortStringWithFallback(input, _fallback); + uint256 shortLength = ShortStrings.byteLengthWithFallback(short, _fallback); + assertEq(inputLength, shortLength); + } + + function toShortString(string memory input) external pure returns (ShortString) { + return ShortStrings.toShortString(input); + } + + function _isShort(string memory input) internal pure returns (bool) { + return bytes(input).length < 32; + } +} diff --git a/test/utils/ShortStrings.test.js b/test/utils/ShortStrings.test.js new file mode 100644 index 000000000..189281d38 --- /dev/null +++ b/test/utils/ShortStrings.test.js @@ -0,0 +1,55 @@ +const { expect } = require('chai'); +const { expectRevertCustomError } = require('../helpers/customError'); + +const ShortStrings = artifacts.require('$ShortStrings'); + +function length(sstr) { + return parseInt(sstr.slice(64), 16); +} + +function decode(sstr) { + return web3.utils.toUtf8(sstr).slice(0, length(sstr)); +} + +contract('ShortStrings', function () { + before(async function () { + this.mock = await ShortStrings.new(); + }); + + for (const str of [0, 1, 16, 31, 32, 64, 1024].map(length => 'a'.repeat(length))) { + describe(`with string length ${str.length}`, function () { + it('encode / decode', async function () { + if (str.length < 32) { + const encoded = await this.mock.$toShortString(str); + expect(decode(encoded)).to.be.equal(str); + + const length = await this.mock.$byteLength(encoded); + expect(length.toNumber()).to.be.equal(str.length); + + const decoded = await this.mock.$toString(encoded); + expect(decoded).to.be.equal(str); + } else { + await expectRevertCustomError(this.mock.$toShortString(str), 'StringTooLong', [str]); + } + }); + + it('set / get with fallback', async function () { + const { logs } = await this.mock.$toShortStringWithFallback(str, 0); + const { ret0 } = logs.find(({ event }) => event == 'return$toShortStringWithFallback').args; + + const promise = this.mock.$toString(ret0); + if (str.length < 32) { + expect(await promise).to.be.equal(str); + } else { + await expectRevertCustomError(promise, 'InvalidShortString', []); + } + + const length = await this.mock.$byteLengthWithFallback(ret0, 0); + expect(length.toNumber()).to.be.equal(str.length); + + const recovered = await this.mock.$toStringWithFallback(ret0, 0); + expect(recovered).to.be.equal(str); + }); + }); + } +}); diff --git a/test/utils/StorageSlot.test.js b/test/utils/StorageSlot.test.js new file mode 100644 index 000000000..846512ed2 --- /dev/null +++ b/test/utils/StorageSlot.test.js @@ -0,0 +1,210 @@ +const { constants, BN } = require('@openzeppelin/test-helpers'); + +const { expect } = require('chai'); + +const StorageSlotMock = artifacts.require('StorageSlotMock'); + +const slot = web3.utils.keccak256('some.storage.slot'); +const otherSlot = web3.utils.keccak256('some.other.storage.slot'); + +contract('StorageSlot', function (accounts) { + beforeEach(async function () { + this.store = await StorageSlotMock.new(); + }); + + describe('boolean storage slot', function () { + beforeEach(async function () { + this.value = true; + }); + + it('set', async function () { + await this.store.setBoolean(slot, this.value); + }); + + describe('get', function () { + beforeEach(async function () { + await this.store.setBoolean(slot, this.value); + }); + + it('from right slot', async function () { + expect(await this.store.getBoolean(slot)).to.be.equal(this.value); + }); + + it('from other slot', async function () { + expect(await this.store.getBoolean(otherSlot)).to.be.equal(false); + }); + }); + }); + + describe('address storage slot', function () { + beforeEach(async function () { + this.value = accounts[1]; + }); + + it('set', async function () { + await this.store.setAddress(slot, this.value); + }); + + describe('get', function () { + beforeEach(async function () { + await this.store.setAddress(slot, this.value); + }); + + it('from right slot', async function () { + expect(await this.store.getAddress(slot)).to.be.equal(this.value); + }); + + it('from other slot', async function () { + expect(await this.store.getAddress(otherSlot)).to.be.equal(constants.ZERO_ADDRESS); + }); + }); + }); + + describe('bytes32 storage slot', function () { + beforeEach(async function () { + this.value = web3.utils.keccak256('some byte32 value'); + }); + + it('set', async function () { + await this.store.setBytes32(slot, this.value); + }); + + describe('get', function () { + beforeEach(async function () { + await this.store.setBytes32(slot, this.value); + }); + + it('from right slot', async function () { + expect(await this.store.getBytes32(slot)).to.be.equal(this.value); + }); + + it('from other slot', async function () { + expect(await this.store.getBytes32(otherSlot)).to.be.equal(constants.ZERO_BYTES32); + }); + }); + }); + + describe('uint256 storage slot', function () { + beforeEach(async function () { + this.value = new BN(1742); + }); + + it('set', async function () { + await this.store.setUint256(slot, this.value); + }); + + describe('get', function () { + beforeEach(async function () { + await this.store.setUint256(slot, this.value); + }); + + it('from right slot', async function () { + expect(await this.store.getUint256(slot)).to.be.bignumber.equal(this.value); + }); + + it('from other slot', async function () { + expect(await this.store.getUint256(otherSlot)).to.be.bignumber.equal('0'); + }); + }); + }); + + describe('string storage slot', function () { + beforeEach(async function () { + this.value = 'lorem ipsum'; + }); + + it('set', async function () { + await this.store.setString(slot, this.value); + }); + + describe('get', function () { + beforeEach(async function () { + await this.store.setString(slot, this.value); + }); + + it('from right slot', async function () { + expect(await this.store.getString(slot)).to.be.equal(this.value); + }); + + it('from other slot', async function () { + expect(await this.store.getString(otherSlot)).to.be.equal(''); + }); + }); + }); + + describe('string storage pointer', function () { + beforeEach(async function () { + this.value = 'lorem ipsum'; + }); + + it('set', async function () { + await this.store.setStringStorage(slot, this.value); + }); + + describe('get', function () { + beforeEach(async function () { + await this.store.setStringStorage(slot, this.value); + }); + + it('from right slot', async function () { + expect(await this.store.stringMap(slot)).to.be.equal(this.value); + expect(await this.store.getStringStorage(slot)).to.be.equal(this.value); + }); + + it('from other slot', async function () { + expect(await this.store.stringMap(otherSlot)).to.be.equal(''); + expect(await this.store.getStringStorage(otherSlot)).to.be.equal(''); + }); + }); + }); + + describe('bytes storage slot', function () { + beforeEach(async function () { + this.value = web3.utils.randomHex(128); + }); + + it('set', async function () { + await this.store.setBytes(slot, this.value); + }); + + describe('get', function () { + beforeEach(async function () { + await this.store.setBytes(slot, this.value); + }); + + it('from right slot', async function () { + expect(await this.store.getBytes(slot)).to.be.equal(this.value); + }); + + it('from other slot', async function () { + expect(await this.store.getBytes(otherSlot)).to.be.equal(null); + }); + }); + }); + + describe('bytes storage pointer', function () { + beforeEach(async function () { + this.value = web3.utils.randomHex(128); + }); + + it('set', async function () { + await this.store.setBytesStorage(slot, this.value); + }); + + describe('get', function () { + beforeEach(async function () { + await this.store.setBytesStorage(slot, this.value); + }); + + it('from right slot', async function () { + expect(await this.store.bytesMap(slot)).to.be.equal(this.value); + expect(await this.store.getBytesStorage(slot)).to.be.equal(this.value); + }); + + it('from other slot', async function () { + expect(await this.store.bytesMap(otherSlot)).to.be.equal(null); + expect(await this.store.getBytesStorage(otherSlot)).to.be.equal(null); + }); + }); + }); +}); diff --git a/test/utils/Strings.test.js b/test/utils/Strings.test.js new file mode 100644 index 000000000..2435fc71c --- /dev/null +++ b/test/utils/Strings.test.js @@ -0,0 +1,153 @@ +const { BN, constants } = require('@openzeppelin/test-helpers'); +const { expectRevertCustomError } = require('../helpers/customError'); + +const { expect } = require('chai'); + +const Strings = artifacts.require('$Strings'); + +contract('Strings', function () { + before(async function () { + this.strings = await Strings.new(); + }); + + describe('toString', function () { + const values = [ + '0', + '7', + '10', + '99', + '100', + '101', + '123', + '4132', + '12345', + '1234567', + '1234567890', + '123456789012345', + '12345678901234567890', + '123456789012345678901234567890', + '1234567890123456789012345678901234567890', + '12345678901234567890123456789012345678901234567890', + '123456789012345678901234567890123456789012345678901234567890', + '1234567890123456789012345678901234567890123456789012345678901234567890', + ]; + + describe('uint256', function () { + it('converts MAX_UINT256', async function () { + const value = constants.MAX_UINT256; + expect(await this.strings.methods['$toString(uint256)'](value)).to.equal(value.toString(10)); + }); + + for (const value of values) { + it(`converts ${value}`, async function () { + expect(await this.strings.methods['$toString(uint256)'](value)).to.equal(value); + }); + } + }); + + describe('int256', function () { + it('converts MAX_INT256', async function () { + const value = constants.MAX_INT256; + expect(await this.strings.methods['$toStringSigned(int256)'](value)).to.equal(value.toString(10)); + }); + + it('converts MIN_INT256', async function () { + const value = constants.MIN_INT256; + expect(await this.strings.methods['$toStringSigned(int256)'](value)).to.equal(value.toString(10)); + }); + + for (const value of values) { + it(`convert ${value}`, async function () { + expect(await this.strings.methods['$toStringSigned(int256)'](value)).to.equal(value); + }); + + it(`convert negative ${value}`, async function () { + const negated = new BN(value).neg(); + expect(await this.strings.methods['$toStringSigned(int256)'](negated)).to.equal(negated.toString(10)); + }); + } + }); + }); + + describe('toHexString', function () { + it('converts 0', async function () { + expect(await this.strings.methods['$toHexString(uint256)'](0)).to.equal('0x00'); + }); + + it('converts a positive number', async function () { + expect(await this.strings.methods['$toHexString(uint256)'](0x4132)).to.equal('0x4132'); + }); + + it('converts MAX_UINT256', async function () { + expect(await this.strings.methods['$toHexString(uint256)'](constants.MAX_UINT256)).to.equal( + web3.utils.toHex(constants.MAX_UINT256), + ); + }); + }); + + describe('toHexString fixed', function () { + it('converts a positive number (long)', async function () { + expect(await this.strings.methods['$toHexString(uint256,uint256)'](0x4132, 32)).to.equal( + '0x0000000000000000000000000000000000000000000000000000000000004132', + ); + }); + + it('converts a positive number (short)', async function () { + const length = 1; + await expectRevertCustomError( + this.strings.methods['$toHexString(uint256,uint256)'](0x4132, length), + `StringsInsufficientHexLength`, + [0x4132, length], + ); + }); + + it('converts MAX_UINT256', async function () { + expect(await this.strings.methods['$toHexString(uint256,uint256)'](constants.MAX_UINT256, 32)).to.equal( + web3.utils.toHex(constants.MAX_UINT256), + ); + }); + }); + + describe('toHexString address', function () { + it('converts a random address', async function () { + const addr = '0xa9036907dccae6a1e0033479b12e837e5cf5a02f'; + expect(await this.strings.methods['$toHexString(address)'](addr)).to.equal(addr); + }); + + it('converts an address with leading zeros', async function () { + const addr = '0x0000e0ca771e21bd00057f54a68c30d400000000'; + expect(await this.strings.methods['$toHexString(address)'](addr)).to.equal(addr); + }); + }); + + describe('equal', function () { + it('compares two empty strings', async function () { + expect(await this.strings.methods['$equal(string,string)']('', '')).to.equal(true); + }); + + it('compares two equal strings', async function () { + expect(await this.strings.methods['$equal(string,string)']('a', 'a')).to.equal(true); + }); + + it('compares two different strings', async function () { + expect(await this.strings.methods['$equal(string,string)']('a', 'b')).to.equal(false); + }); + + it('compares two different strings of different lengths', async function () { + expect(await this.strings.methods['$equal(string,string)']('a', 'aa')).to.equal(false); + expect(await this.strings.methods['$equal(string,string)']('aa', 'a')).to.equal(false); + }); + + it('compares two different large strings', async function () { + const str1 = 'a'.repeat(201); + const str2 = 'a'.repeat(200) + 'b'; + expect(await this.strings.methods['$equal(string,string)'](str1, str2)).to.equal(false); + }); + + it('compares two equal large strings', async function () { + const str1 = 'a'.repeat(201); + const str2 = 'a'.repeat(201); + expect(await this.strings.methods['$equal(string,string)'](str1, str2)).to.equal(true); + }); + }); +}); diff --git a/test/utils/cryptography/ECDSA.test.js b/test/utils/cryptography/ECDSA.test.js new file mode 100644 index 000000000..f164ef196 --- /dev/null +++ b/test/utils/cryptography/ECDSA.test.js @@ -0,0 +1,245 @@ +require('@openzeppelin/test-helpers'); +const { expectRevertCustomError } = require('../../helpers/customError'); +const { toEthSignedMessageHash } = require('../../helpers/sign'); + +const { expect } = require('chai'); + +const ECDSA = artifacts.require('$ECDSA'); + +const TEST_MESSAGE = web3.utils.sha3('OpenZeppelin'); +const WRONG_MESSAGE = web3.utils.sha3('Nope'); +const NON_HASH_MESSAGE = '0x' + Buffer.from('abcd').toString('hex'); + +function to2098Format(signature) { + const long = web3.utils.hexToBytes(signature); + if (long.length !== 65) { + throw new Error('invalid signature length (expected long format)'); + } + if (long[32] >> 7 === 1) { + throw new Error("invalid signature 's' value"); + } + const short = long.slice(0, 64); + short[32] |= long[64] % 27 << 7; // set the first bit of the 32nd byte to the v parity bit + return web3.utils.bytesToHex(short); +} + +function split(signature) { + const raw = web3.utils.hexToBytes(signature); + switch (raw.length) { + case 64: + return [ + web3.utils.bytesToHex(raw.slice(0, 32)), // r + web3.utils.bytesToHex(raw.slice(32, 64)), // vs + ]; + case 65: + return [ + raw[64], // v + web3.utils.bytesToHex(raw.slice(0, 32)), // r + web3.utils.bytesToHex(raw.slice(32, 64)), // s + ]; + default: + expect.fail('Invalid signature length, cannot split'); + } +} + +contract('ECDSA', function (accounts) { + const [other] = accounts; + + beforeEach(async function () { + this.ecdsa = await ECDSA.new(); + }); + + context('recover with invalid signature', function () { + it('with short signature', async function () { + await expectRevertCustomError(this.ecdsa.$recover(TEST_MESSAGE, '0x1234'), 'ECDSAInvalidSignatureLength', [2]); + }); + + it('with long signature', async function () { + await expectRevertCustomError( + // eslint-disable-next-line max-len + this.ecdsa.$recover( + TEST_MESSAGE, + '0x01234567890123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789', + ), + 'ECDSAInvalidSignatureLength', + [85], + ); + }); + }); + + context('recover with valid signature', function () { + context('using web3.eth.sign', function () { + it('returns signer address with correct signature', async function () { + // Create the signature + const signature = await web3.eth.sign(TEST_MESSAGE, other); + + // Recover the signer address from the generated message and signature. + expect(await this.ecdsa.$recover(toEthSignedMessageHash(TEST_MESSAGE), signature)).to.equal(other); + }); + + it('returns signer address with correct signature for arbitrary length message', async function () { + // Create the signature + const signature = await web3.eth.sign(NON_HASH_MESSAGE, other); + + // Recover the signer address from the generated message and signature. + expect(await this.ecdsa.$recover(toEthSignedMessageHash(NON_HASH_MESSAGE), signature)).to.equal(other); + }); + + it('returns a different address', async function () { + const signature = await web3.eth.sign(TEST_MESSAGE, other); + expect(await this.ecdsa.$recover(WRONG_MESSAGE, signature)).to.not.equal(other); + }); + + it('reverts with invalid signature', async function () { + // eslint-disable-next-line max-len + const signature = + '0x332ce75a821c982f9127538858900d87d3ec1f9f737338ad67cad133fa48feff48e6fa0c18abc62e42820f05943e47af3e9fbe306ce74d64094bdf1691ee53e01c'; + await expectRevertCustomError(this.ecdsa.$recover(TEST_MESSAGE, signature), 'ECDSAInvalidSignature', []); + }); + }); + + context('with v=27 signature', function () { + // Signature generated outside ganache with method web3.eth.sign(signer, message) + const signer = '0x2cc1166f6212628A0deEf2B33BEFB2187D35b86c'; + // eslint-disable-next-line max-len + const signatureWithoutV = + '0x5d99b6f7f6d1f73d1a26497f2b1c89b24c0993913f86e9a2d02cd69887d9c94f3c880358579d811b21dd1b7fd9bb01c1d81d10e69f0384e675c32b39643be892'; + + it('works with correct v value', async function () { + const v = '1b'; // 27 = 1b. + const signature = signatureWithoutV + v; + expect(await this.ecdsa.$recover(TEST_MESSAGE, signature)).to.equal(signer); + + expect( + await this.ecdsa.methods['$recover(bytes32,uint8,bytes32,bytes32)'](TEST_MESSAGE, ...split(signature)), + ).to.equal(signer); + + expect( + await this.ecdsa.methods['$recover(bytes32,bytes32,bytes32)']( + TEST_MESSAGE, + ...split(to2098Format(signature)), + ), + ).to.equal(signer); + }); + + it('rejects incorrect v value', async function () { + const v = '1c'; // 28 = 1c. + const signature = signatureWithoutV + v; + expect(await this.ecdsa.$recover(TEST_MESSAGE, signature)).to.not.equal(signer); + + expect( + await this.ecdsa.methods['$recover(bytes32,uint8,bytes32,bytes32)'](TEST_MESSAGE, ...split(signature)), + ).to.not.equal(signer); + + expect( + await this.ecdsa.methods['$recover(bytes32,bytes32,bytes32)']( + TEST_MESSAGE, + ...split(to2098Format(signature)), + ), + ).to.not.equal(signer); + }); + + it('reverts wrong v values', async function () { + for (const v of ['00', '01']) { + const signature = signatureWithoutV + v; + await expectRevertCustomError(this.ecdsa.$recover(TEST_MESSAGE, signature), 'ECDSAInvalidSignature', []); + + await expectRevertCustomError( + this.ecdsa.methods['$recover(bytes32,uint8,bytes32,bytes32)'](TEST_MESSAGE, ...split(signature)), + 'ECDSAInvalidSignature', + [], + ); + } + }); + + it('rejects short EIP2098 format', async function () { + const v = '1b'; // 27 = 1b. + const signature = signatureWithoutV + v; + await expectRevertCustomError( + this.ecdsa.$recover(TEST_MESSAGE, to2098Format(signature)), + 'ECDSAInvalidSignatureLength', + [64], + ); + }); + }); + + context('with v=28 signature', function () { + const signer = '0x1E318623aB09Fe6de3C9b8672098464Aeda9100E'; + // eslint-disable-next-line max-len + const signatureWithoutV = + '0x331fe75a821c982f9127538858900d87d3ec1f9f737338ad67cad133fa48feff48e6fa0c18abc62e42820f05943e47af3e9fbe306ce74d64094bdf1691ee53e0'; + + it('works with correct v value', async function () { + const v = '1c'; // 28 = 1c. + const signature = signatureWithoutV + v; + expect(await this.ecdsa.$recover(TEST_MESSAGE, signature)).to.equal(signer); + + expect( + await this.ecdsa.methods['$recover(bytes32,uint8,bytes32,bytes32)'](TEST_MESSAGE, ...split(signature)), + ).to.equal(signer); + + expect( + await this.ecdsa.methods['$recover(bytes32,bytes32,bytes32)']( + TEST_MESSAGE, + ...split(to2098Format(signature)), + ), + ).to.equal(signer); + }); + + it('rejects incorrect v value', async function () { + const v = '1b'; // 27 = 1b. + const signature = signatureWithoutV + v; + expect(await this.ecdsa.$recover(TEST_MESSAGE, signature)).to.not.equal(signer); + + expect( + await this.ecdsa.methods['$recover(bytes32,uint8,bytes32,bytes32)'](TEST_MESSAGE, ...split(signature)), + ).to.not.equal(signer); + + expect( + await this.ecdsa.methods['$recover(bytes32,bytes32,bytes32)']( + TEST_MESSAGE, + ...split(to2098Format(signature)), + ), + ).to.not.equal(signer); + }); + + it('reverts invalid v values', async function () { + for (const v of ['00', '01']) { + const signature = signatureWithoutV + v; + await expectRevertCustomError(this.ecdsa.$recover(TEST_MESSAGE, signature), 'ECDSAInvalidSignature', []); + + await expectRevertCustomError( + this.ecdsa.methods['$recover(bytes32,uint8,bytes32,bytes32)'](TEST_MESSAGE, ...split(signature)), + 'ECDSAInvalidSignature', + [], + ); + } + }); + + it('rejects short EIP2098 format', async function () { + const v = '1c'; // 27 = 1b. + const signature = signatureWithoutV + v; + await expectRevertCustomError( + this.ecdsa.$recover(TEST_MESSAGE, to2098Format(signature)), + 'ECDSAInvalidSignatureLength', + [64], + ); + }); + }); + + it('reverts with high-s value signature', async function () { + const message = '0xb94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9'; + // eslint-disable-next-line max-len + const highSSignature = + '0xe742ff452d41413616a5bf43fe15dd88294e983d3d36206c2712f39083d638bde0a0fc89be718fbc1033e1d30d78be1c68081562ed2e97af876f286f3453231d1b'; + const [r, v, s] = split(highSSignature); + await expectRevertCustomError(this.ecdsa.$recover(message, highSSignature), 'ECDSAInvalidSignatureS', [s]); + await expectRevertCustomError( + this.ecdsa.methods['$recover(bytes32,uint8,bytes32,bytes32)'](TEST_MESSAGE, r, v, s), + 'ECDSAInvalidSignatureS', + [s], + ); + expect(() => to2098Format(highSSignature)).to.throw("invalid signature 's' value"); + }); + }); +}); diff --git a/test/utils/cryptography/EIP712.test.js b/test/utils/cryptography/EIP712.test.js new file mode 100644 index 000000000..faf01f1a3 --- /dev/null +++ b/test/utils/cryptography/EIP712.test.js @@ -0,0 +1,111 @@ +const ethSigUtil = require('eth-sig-util'); +const Wallet = require('ethereumjs-wallet').default; + +const { getDomain, domainType, domainSeparator, hashTypedData } = require('../../helpers/eip712'); +const { getChainId } = require('../../helpers/chainid'); +const { mapValues } = require('../../helpers/iterate'); + +const EIP712Verifier = artifacts.require('$EIP712Verifier'); +const Clones = artifacts.require('$Clones'); + +contract('EIP712', function (accounts) { + const [mailTo] = accounts; + + const shortName = 'A Name'; + const shortVersion = '1'; + + const longName = 'A'.repeat(40); + const longVersion = 'B'.repeat(40); + + const cases = [ + ['short', shortName, shortVersion], + ['long', longName, longVersion], + ]; + + for (const [shortOrLong, name, version] of cases) { + describe(`with ${shortOrLong} name and version`, function () { + beforeEach('deploying', async function () { + this.eip712 = await EIP712Verifier.new(name, version); + + this.domain = { + name, + version, + chainId: await getChainId(), + verifyingContract: this.eip712.address, + }; + this.domainType = domainType(this.domain); + }); + + describe('domain separator', function () { + it('is internally available', async function () { + const expected = await domainSeparator(this.domain); + + expect(await this.eip712.$_domainSeparatorV4()).to.equal(expected); + }); + + it("can be rebuilt using EIP-5267's eip712Domain", async function () { + const rebuildDomain = await getDomain(this.eip712); + expect(mapValues(rebuildDomain, String)).to.be.deep.equal(mapValues(this.domain, String)); + }); + + if (shortOrLong === 'short') { + // Long strings are in storage, and the proxy will not be properly initialized unless + // the upgradeable contract variant is used and the initializer is invoked. + + it('adjusts when behind proxy', async function () { + const factory = await Clones.new(); + const cloneReceipt = await factory.$clone(this.eip712.address); + const cloneAddress = cloneReceipt.logs.find(({ event }) => event === 'return$clone').args.instance; + const clone = new EIP712Verifier(cloneAddress); + + const cloneDomain = { ...this.domain, verifyingContract: clone.address }; + + const reportedDomain = await getDomain(clone); + expect(mapValues(reportedDomain, String)).to.be.deep.equal(mapValues(cloneDomain, String)); + + const expectedSeparator = await domainSeparator(cloneDomain); + expect(await clone.$_domainSeparatorV4()).to.equal(expectedSeparator); + }); + } + }); + + it('hash digest', async function () { + const structhash = web3.utils.randomHex(32); + expect(await this.eip712.$_hashTypedDataV4(structhash)).to.be.equal(hashTypedData(this.domain, structhash)); + }); + + it('digest', async function () { + const message = { + to: mailTo, + contents: 'very interesting', + }; + + const data = { + types: { + EIP712Domain: this.domainType, + Mail: [ + { name: 'to', type: 'address' }, + { name: 'contents', type: 'string' }, + ], + }, + domain: this.domain, + primaryType: 'Mail', + message, + }; + + const wallet = Wallet.generate(); + const signature = ethSigUtil.signTypedMessage(wallet.getPrivateKey(), { data }); + + await this.eip712.verify(signature, wallet.getAddressString(), message.to, message.contents); + }); + + it('name', async function () { + expect(await this.eip712.$_EIP712Name()).to.be.equal(name); + }); + + it('version', async function () { + expect(await this.eip712.$_EIP712Version()).to.be.equal(version); + }); + }); + } +}); diff --git a/test/utils/cryptography/MerkleProof.test.js b/test/utils/cryptography/MerkleProof.test.js new file mode 100644 index 000000000..5b87bc525 --- /dev/null +++ b/test/utils/cryptography/MerkleProof.test.js @@ -0,0 +1,207 @@ +const { expectRevert } = require('@openzeppelin/test-helpers'); + +const { MerkleTree } = require('merkletreejs'); +const keccak256 = require('keccak256'); + +const { expect } = require('chai'); +const { expectRevertCustomError } = require('../../helpers/customError'); + +const MerkleProof = artifacts.require('$MerkleProof'); + +contract('MerkleProof', function () { + beforeEach(async function () { + this.merkleProof = await MerkleProof.new(); + }); + + describe('verify', function () { + it('returns true for a valid Merkle proof', async function () { + const elements = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/='.split(''); + const merkleTree = new MerkleTree(elements, keccak256, { hashLeaves: true, sortPairs: true }); + + const root = merkleTree.getHexRoot(); + + const leaf = keccak256(elements[0]); + + const proof = merkleTree.getHexProof(leaf); + + expect(await this.merkleProof.$verify(proof, root, leaf)).to.equal(true); + expect(await this.merkleProof.$verifyCalldata(proof, root, leaf)).to.equal(true); + + // For demonstration, it is also possible to create valid proofs for certain 64-byte values *not* in elements: + const noSuchLeaf = keccak256( + Buffer.concat([keccak256(elements[0]), keccak256(elements[1])].sort(Buffer.compare)), + ); + expect(await this.merkleProof.$verify(proof.slice(1), root, noSuchLeaf)).to.equal(true); + expect(await this.merkleProof.$verifyCalldata(proof.slice(1), root, noSuchLeaf)).to.equal(true); + }); + + it('returns false for an invalid Merkle proof', async function () { + const correctElements = ['a', 'b', 'c']; + const correctMerkleTree = new MerkleTree(correctElements, keccak256, { hashLeaves: true, sortPairs: true }); + + const correctRoot = correctMerkleTree.getHexRoot(); + + const correctLeaf = keccak256(correctElements[0]); + + const badElements = ['d', 'e', 'f']; + const badMerkleTree = new MerkleTree(badElements); + + const badProof = badMerkleTree.getHexProof(badElements[0]); + + expect(await this.merkleProof.$verify(badProof, correctRoot, correctLeaf)).to.equal(false); + expect(await this.merkleProof.$verifyCalldata(badProof, correctRoot, correctLeaf)).to.equal(false); + }); + + it('returns false for a Merkle proof of invalid length', async function () { + const elements = ['a', 'b', 'c']; + const merkleTree = new MerkleTree(elements, keccak256, { hashLeaves: true, sortPairs: true }); + + const root = merkleTree.getHexRoot(); + + const leaf = keccak256(elements[0]); + + const proof = merkleTree.getHexProof(leaf); + const badProof = proof.slice(0, proof.length - 5); + + expect(await this.merkleProof.$verify(badProof, root, leaf)).to.equal(false); + expect(await this.merkleProof.$verifyCalldata(badProof, root, leaf)).to.equal(false); + }); + }); + + describe('multiProofVerify', function () { + it('returns true for a valid Merkle multi proof', async function () { + const leaves = ['a', 'b', 'c', 'd', 'e', 'f'].map(keccak256).sort(Buffer.compare); + const merkleTree = new MerkleTree(leaves, keccak256, { sort: true }); + + const root = merkleTree.getRoot(); + const proofLeaves = ['b', 'f', 'd'].map(keccak256).sort(Buffer.compare); + const proof = merkleTree.getMultiProof(proofLeaves); + const proofFlags = merkleTree.getProofFlags(proofLeaves, proof); + + expect(await this.merkleProof.$multiProofVerify(proof, proofFlags, root, proofLeaves)).to.equal(true); + expect(await this.merkleProof.$multiProofVerifyCalldata(proof, proofFlags, root, proofLeaves)).to.equal(true); + }); + + it('returns false for an invalid Merkle multi proof', async function () { + const leaves = ['a', 'b', 'c', 'd', 'e', 'f'].map(keccak256).sort(Buffer.compare); + const merkleTree = new MerkleTree(leaves, keccak256, { sort: true }); + + const root = merkleTree.getRoot(); + const badProofLeaves = ['g', 'h', 'i'].map(keccak256).sort(Buffer.compare); + const badMerkleTree = new MerkleTree(badProofLeaves); + const badProof = badMerkleTree.getMultiProof(badProofLeaves); + const badProofFlags = badMerkleTree.getProofFlags(badProofLeaves, badProof); + + expect(await this.merkleProof.$multiProofVerify(badProof, badProofFlags, root, badProofLeaves)).to.equal(false); + expect(await this.merkleProof.$multiProofVerifyCalldata(badProof, badProofFlags, root, badProofLeaves)).to.equal( + false, + ); + }); + + it('revert with invalid multi proof #1', async function () { + const fill = Buffer.alloc(32); // This could be anything, we are reconstructing a fake branch + const leaves = ['a', 'b', 'c', 'd'].map(keccak256).sort(Buffer.compare); + const badLeaf = keccak256('e'); + const merkleTree = new MerkleTree(leaves, keccak256, { sort: true }); + + const root = merkleTree.getRoot(); + + await expectRevertCustomError( + this.merkleProof.$multiProofVerify( + [leaves[1], fill, merkleTree.layers[1][1]], + [false, false, false], + root, + [leaves[0], badLeaf], // A, E + ), + 'MerkleProofInvalidMultiproof', + [], + ); + await expectRevertCustomError( + this.merkleProof.$multiProofVerifyCalldata( + [leaves[1], fill, merkleTree.layers[1][1]], + [false, false, false], + root, + [leaves[0], badLeaf], // A, E + ), + 'MerkleProofInvalidMultiproof', + [], + ); + }); + + it('revert with invalid multi proof #2', async function () { + const fill = Buffer.alloc(32); // This could be anything, we are reconstructing a fake branch + const leaves = ['a', 'b', 'c', 'd'].map(keccak256).sort(Buffer.compare); + const badLeaf = keccak256('e'); + const merkleTree = new MerkleTree(leaves, keccak256, { sort: true }); + + const root = merkleTree.getRoot(); + + await expectRevert( + this.merkleProof.$multiProofVerify( + [leaves[1], fill, merkleTree.layers[1][1]], + [false, false, false, false], + root, + [badLeaf, leaves[0]], // A, E + ), + 'reverted with panic code 0x32', + ); + + await expectRevert( + this.merkleProof.$multiProofVerifyCalldata( + [leaves[1], fill, merkleTree.layers[1][1]], + [false, false, false, false], + root, + [badLeaf, leaves[0]], // A, E + ), + 'reverted with panic code 0x32', + ); + }); + + it('limit case: works for tree containing a single leaf', async function () { + const leaves = ['a'].map(keccak256).sort(Buffer.compare); + const merkleTree = new MerkleTree(leaves, keccak256, { sort: true }); + + const root = merkleTree.getRoot(); + const proofLeaves = ['a'].map(keccak256).sort(Buffer.compare); + const proof = merkleTree.getMultiProof(proofLeaves); + const proofFlags = merkleTree.getProofFlags(proofLeaves, proof); + + expect(await this.merkleProof.$multiProofVerify(proof, proofFlags, root, proofLeaves)).to.equal(true); + expect(await this.merkleProof.$multiProofVerifyCalldata(proof, proofFlags, root, proofLeaves)).to.equal(true); + }); + + it('limit case: can prove empty leaves', async function () { + const leaves = ['a', 'b', 'c', 'd'].map(keccak256).sort(Buffer.compare); + const merkleTree = new MerkleTree(leaves, keccak256, { sort: true }); + + const root = merkleTree.getRoot(); + expect(await this.merkleProof.$multiProofVerify([root], [], root, [])).to.equal(true); + expect(await this.merkleProof.$multiProofVerifyCalldata([root], [], root, [])).to.equal(true); + }); + + it('reverts processing manipulated proofs with a zero-value node at depth 1', async function () { + // Create a merkle tree that contains a zero leaf at depth 1 + const leaves = [keccak256('real leaf'), Buffer.alloc(32, 0)]; + const merkleTree = new MerkleTree(leaves, keccak256, { sortPairs: true }); + + const root = merkleTree.getRoot(); + + // Now we can pass any **malicious** fake leaves as valid! + const maliciousLeaves = ['malicious', 'leaves'].map(keccak256).sort(Buffer.compare); + const maliciousProof = [leaves[0], leaves[0]]; + const maliciousProofFlags = [true, true, false]; + + await expectRevertCustomError( + this.merkleProof.$multiProofVerify(maliciousProof, maliciousProofFlags, root, maliciousLeaves), + 'MerkleProofInvalidMultiproof', + [], + ); + + await expectRevertCustomError( + this.merkleProof.$multiProofVerifyCalldata(maliciousProof, maliciousProofFlags, root, maliciousLeaves), + 'MerkleProofInvalidMultiproof', + [], + ); + }); + }); +}); diff --git a/test/utils/cryptography/MessageHashUtils.test.js b/test/utils/cryptography/MessageHashUtils.test.js new file mode 100644 index 000000000..b38e945da --- /dev/null +++ b/test/utils/cryptography/MessageHashUtils.test.js @@ -0,0 +1,55 @@ +require('@openzeppelin/test-helpers'); +const { toEthSignedMessageHash, toDataWithIntendedValidatorHash } = require('../../helpers/sign'); +const { domainSeparator, hashTypedData } = require('../../helpers/eip712'); + +const { expect } = require('chai'); + +const MessageHashUtils = artifacts.require('$MessageHashUtils'); + +contract('MessageHashUtils', function () { + beforeEach(async function () { + this.messageHashUtils = await MessageHashUtils.new(); + + this.message = '0x' + Buffer.from('abcd').toString('hex'); + this.messageHash = web3.utils.sha3(this.message); + this.verifyingAddress = web3.utils.toChecksumAddress(web3.utils.randomHex(20)); + }); + + context('toEthSignedMessageHash', function () { + it('prefixes bytes32 data correctly', async function () { + expect(await this.messageHashUtils.methods['$toEthSignedMessageHash(bytes32)'](this.messageHash)).to.equal( + toEthSignedMessageHash(this.messageHash), + ); + }); + + it('prefixes dynamic length data correctly', async function () { + expect(await this.messageHashUtils.methods['$toEthSignedMessageHash(bytes)'](this.message)).to.equal( + toEthSignedMessageHash(this.message), + ); + }); + }); + + context('toDataWithIntendedValidatorHash', function () { + it('returns the digest correctly', async function () { + expect( + await this.messageHashUtils.$toDataWithIntendedValidatorHash(this.verifyingAddress, this.message), + ).to.equal(toDataWithIntendedValidatorHash(this.verifyingAddress, this.message)); + }); + }); + + context('toTypedDataHash', function () { + it('returns the digest correctly', async function () { + const domain = { + name: 'Test', + version: 1, + chainId: 1, + verifyingContract: this.verifyingAddress, + }; + const structhash = web3.utils.randomHex(32); + const expectedDomainSeparator = await domainSeparator(domain); + expect(await this.messageHashUtils.$toTypedDataHash(expectedDomainSeparator, structhash)).to.equal( + hashTypedData(domain, structhash), + ); + }); + }); +}); diff --git a/test/utils/cryptography/SignatureChecker.test.js b/test/utils/cryptography/SignatureChecker.test.js new file mode 100644 index 000000000..ba8b100d1 --- /dev/null +++ b/test/utils/cryptography/SignatureChecker.test.js @@ -0,0 +1,87 @@ +const { toEthSignedMessageHash } = require('../../helpers/sign'); + +const { expect } = require('chai'); + +const SignatureChecker = artifacts.require('$SignatureChecker'); +const ERC1271WalletMock = artifacts.require('ERC1271WalletMock'); +const ERC1271MaliciousMock = artifacts.require('ERC1271MaliciousMock'); + +const TEST_MESSAGE = web3.utils.sha3('OpenZeppelin'); +const WRONG_MESSAGE = web3.utils.sha3('Nope'); + +contract('SignatureChecker (ERC1271)', function (accounts) { + const [signer, other] = accounts; + + before('deploying', async function () { + this.signaturechecker = await SignatureChecker.new(); + this.wallet = await ERC1271WalletMock.new(signer); + this.malicious = await ERC1271MaliciousMock.new(); + this.signature = await web3.eth.sign(TEST_MESSAGE, signer); + }); + + context('EOA account', function () { + it('with matching signer and signature', async function () { + expect( + await this.signaturechecker.$isValidSignatureNow(signer, toEthSignedMessageHash(TEST_MESSAGE), this.signature), + ).to.equal(true); + }); + + it('with invalid signer', async function () { + expect( + await this.signaturechecker.$isValidSignatureNow(other, toEthSignedMessageHash(TEST_MESSAGE), this.signature), + ).to.equal(false); + }); + + it('with invalid signature', async function () { + expect( + await this.signaturechecker.$isValidSignatureNow(signer, toEthSignedMessageHash(WRONG_MESSAGE), this.signature), + ).to.equal(false); + }); + }); + + context('ERC1271 wallet', function () { + for (const signature of ['isValidERC1271SignatureNow', 'isValidSignatureNow']) { + context(signature, function () { + it('with matching signer and signature', async function () { + expect( + await this.signaturechecker[`$${signature}`]( + this.wallet.address, + toEthSignedMessageHash(TEST_MESSAGE), + this.signature, + ), + ).to.equal(true); + }); + + it('with invalid signer', async function () { + expect( + await this.signaturechecker[`$${signature}`]( + this.signaturechecker.address, + toEthSignedMessageHash(TEST_MESSAGE), + this.signature, + ), + ).to.equal(false); + }); + + it('with invalid signature', async function () { + expect( + await this.signaturechecker[`$${signature}`]( + this.wallet.address, + toEthSignedMessageHash(WRONG_MESSAGE), + this.signature, + ), + ).to.equal(false); + }); + + it('with malicious wallet', async function () { + expect( + await this.signaturechecker[`$${signature}`]( + this.malicious.address, + toEthSignedMessageHash(TEST_MESSAGE), + this.signature, + ), + ).to.equal(false); + }); + }); + } + }); +}); diff --git a/test/utils/introspection/ERC165.test.js b/test/utils/introspection/ERC165.test.js new file mode 100644 index 000000000..6d531c16d --- /dev/null +++ b/test/utils/introspection/ERC165.test.js @@ -0,0 +1,11 @@ +const { shouldSupportInterfaces } = require('./SupportsInterface.behavior'); + +const ERC165 = artifacts.require('$ERC165'); + +contract('ERC165', function () { + beforeEach(async function () { + this.mock = await ERC165.new(); + }); + + shouldSupportInterfaces(['ERC165']); +}); diff --git a/test/utils/introspection/ERC165Checker.test.js b/test/utils/introspection/ERC165Checker.test.js new file mode 100644 index 000000000..caa220127 --- /dev/null +++ b/test/utils/introspection/ERC165Checker.test.js @@ -0,0 +1,300 @@ +require('@openzeppelin/test-helpers'); + +const { expect } = require('chai'); + +const ERC165Checker = artifacts.require('$ERC165Checker'); +const ERC165MissingData = artifacts.require('ERC165MissingData'); +const ERC165MaliciousData = artifacts.require('ERC165MaliciousData'); +const ERC165NotSupported = artifacts.require('ERC165NotSupported'); +const ERC165InterfacesSupported = artifacts.require('ERC165InterfacesSupported'); +const ERC165ReturnBombMock = artifacts.require('ERC165ReturnBombMock'); + +const DUMMY_ID = '0xdeadbeef'; +const DUMMY_ID_2 = '0xcafebabe'; +const DUMMY_ID_3 = '0xdecafbad'; +const DUMMY_UNSUPPORTED_ID = '0xbaddcafe'; +const DUMMY_UNSUPPORTED_ID_2 = '0xbaadcafe'; +const DUMMY_ACCOUNT = '0x1111111111111111111111111111111111111111'; + +contract('ERC165Checker', function () { + beforeEach(async function () { + this.mock = await ERC165Checker.new(); + }); + + context('ERC165 missing return data', function () { + beforeEach(async function () { + this.target = await ERC165MissingData.new(); + }); + + it('does not support ERC165', async function () { + const supported = await this.mock.$supportsERC165(this.target.address); + expect(supported).to.equal(false); + }); + + it('does not support mock interface via supportsInterface', async function () { + const supported = await this.mock.$supportsInterface(this.target.address, DUMMY_ID); + expect(supported).to.equal(false); + }); + + it('does not support mock interface via supportsAllInterfaces', async function () { + const supported = await this.mock.$supportsAllInterfaces(this.target.address, [DUMMY_ID]); + expect(supported).to.equal(false); + }); + + it('does not support mock interface via getSupportedInterfaces', async function () { + const supported = await this.mock.$getSupportedInterfaces(this.target.address, [DUMMY_ID]); + expect(supported.length).to.equal(1); + expect(supported[0]).to.equal(false); + }); + + it('does not support mock interface via supportsERC165InterfaceUnchecked', async function () { + const supported = await this.mock.$supportsERC165InterfaceUnchecked(this.target.address, DUMMY_ID); + expect(supported).to.equal(false); + }); + }); + + context('ERC165 malicious return data', function () { + beforeEach(async function () { + this.target = await ERC165MaliciousData.new(); + }); + + it('does not support ERC165', async function () { + const supported = await this.mock.$supportsERC165(this.target.address); + expect(supported).to.equal(false); + }); + + it('does not support mock interface via supportsInterface', async function () { + const supported = await this.mock.$supportsInterface(this.target.address, DUMMY_ID); + expect(supported).to.equal(false); + }); + + it('does not support mock interface via supportsAllInterfaces', async function () { + const supported = await this.mock.$supportsAllInterfaces(this.target.address, [DUMMY_ID]); + expect(supported).to.equal(false); + }); + + it('does not support mock interface via getSupportedInterfaces', async function () { + const supported = await this.mock.$getSupportedInterfaces(this.target.address, [DUMMY_ID]); + expect(supported.length).to.equal(1); + expect(supported[0]).to.equal(false); + }); + + it('does not support mock interface via supportsERC165InterfaceUnchecked', async function () { + const supported = await this.mock.$supportsERC165InterfaceUnchecked(this.target.address, DUMMY_ID); + expect(supported).to.equal(true); + }); + }); + + context('ERC165 not supported', function () { + beforeEach(async function () { + this.target = await ERC165NotSupported.new(); + }); + + it('does not support ERC165', async function () { + const supported = await this.mock.$supportsERC165(this.target.address); + expect(supported).to.equal(false); + }); + + it('does not support mock interface via supportsInterface', async function () { + const supported = await this.mock.$supportsInterface(this.target.address, DUMMY_ID); + expect(supported).to.equal(false); + }); + + it('does not support mock interface via supportsAllInterfaces', async function () { + const supported = await this.mock.$supportsAllInterfaces(this.target.address, [DUMMY_ID]); + expect(supported).to.equal(false); + }); + + it('does not support mock interface via getSupportedInterfaces', async function () { + const supported = await this.mock.$getSupportedInterfaces(this.target.address, [DUMMY_ID]); + expect(supported.length).to.equal(1); + expect(supported[0]).to.equal(false); + }); + + it('does not support mock interface via supportsERC165InterfaceUnchecked', async function () { + const supported = await this.mock.$supportsERC165InterfaceUnchecked(this.target.address, DUMMY_ID); + expect(supported).to.equal(false); + }); + }); + + context('ERC165 supported', function () { + beforeEach(async function () { + this.target = await ERC165InterfacesSupported.new([]); + }); + + it('supports ERC165', async function () { + const supported = await this.mock.$supportsERC165(this.target.address); + expect(supported).to.equal(true); + }); + + it('does not support mock interface via supportsInterface', async function () { + const supported = await this.mock.$supportsInterface(this.target.address, DUMMY_ID); + expect(supported).to.equal(false); + }); + + it('does not support mock interface via supportsAllInterfaces', async function () { + const supported = await this.mock.$supportsAllInterfaces(this.target.address, [DUMMY_ID]); + expect(supported).to.equal(false); + }); + + it('does not support mock interface via getSupportedInterfaces', async function () { + const supported = await this.mock.$getSupportedInterfaces(this.target.address, [DUMMY_ID]); + expect(supported.length).to.equal(1); + expect(supported[0]).to.equal(false); + }); + + it('does not support mock interface via supportsERC165InterfaceUnchecked', async function () { + const supported = await this.mock.$supportsERC165InterfaceUnchecked(this.target.address, DUMMY_ID); + expect(supported).to.equal(false); + }); + }); + + context('ERC165 and single interface supported', function () { + beforeEach(async function () { + this.target = await ERC165InterfacesSupported.new([DUMMY_ID]); + }); + + it('supports ERC165', async function () { + const supported = await this.mock.$supportsERC165(this.target.address); + expect(supported).to.equal(true); + }); + + it('supports mock interface via supportsInterface', async function () { + const supported = await this.mock.$supportsInterface(this.target.address, DUMMY_ID); + expect(supported).to.equal(true); + }); + + it('supports mock interface via supportsAllInterfaces', async function () { + const supported = await this.mock.$supportsAllInterfaces(this.target.address, [DUMMY_ID]); + expect(supported).to.equal(true); + }); + + it('supports mock interface via getSupportedInterfaces', async function () { + const supported = await this.mock.$getSupportedInterfaces(this.target.address, [DUMMY_ID]); + expect(supported.length).to.equal(1); + expect(supported[0]).to.equal(true); + }); + + it('supports mock interface via supportsERC165InterfaceUnchecked', async function () { + const supported = await this.mock.$supportsERC165InterfaceUnchecked(this.target.address, DUMMY_ID); + expect(supported).to.equal(true); + }); + }); + + context('ERC165 and many interfaces supported', function () { + beforeEach(async function () { + this.supportedInterfaces = [DUMMY_ID, DUMMY_ID_2, DUMMY_ID_3]; + this.target = await ERC165InterfacesSupported.new(this.supportedInterfaces); + }); + + it('supports ERC165', async function () { + const supported = await this.mock.$supportsERC165(this.target.address); + expect(supported).to.equal(true); + }); + + it('supports each interfaceId via supportsInterface', async function () { + for (const interfaceId of this.supportedInterfaces) { + const supported = await this.mock.$supportsInterface(this.target.address, interfaceId); + expect(supported).to.equal(true); + } + }); + + it('supports all interfaceIds via supportsAllInterfaces', async function () { + const supported = await this.mock.$supportsAllInterfaces(this.target.address, this.supportedInterfaces); + expect(supported).to.equal(true); + }); + + it('supports none of the interfaces queried via supportsAllInterfaces', async function () { + const interfaceIdsToTest = [DUMMY_UNSUPPORTED_ID, DUMMY_UNSUPPORTED_ID_2]; + + const supported = await this.mock.$supportsAllInterfaces(this.target.address, interfaceIdsToTest); + expect(supported).to.equal(false); + }); + + it('supports not all of the interfaces queried via supportsAllInterfaces', async function () { + const interfaceIdsToTest = [...this.supportedInterfaces, DUMMY_UNSUPPORTED_ID]; + + const supported = await this.mock.$supportsAllInterfaces(this.target.address, interfaceIdsToTest); + expect(supported).to.equal(false); + }); + + it('supports all interfaceIds via getSupportedInterfaces', async function () { + const supported = await this.mock.$getSupportedInterfaces(this.target.address, this.supportedInterfaces); + expect(supported.length).to.equal(3); + expect(supported[0]).to.equal(true); + expect(supported[1]).to.equal(true); + expect(supported[2]).to.equal(true); + }); + + it('supports none of the interfaces queried via getSupportedInterfaces', async function () { + const interfaceIdsToTest = [DUMMY_UNSUPPORTED_ID, DUMMY_UNSUPPORTED_ID_2]; + + const supported = await this.mock.$getSupportedInterfaces(this.target.address, interfaceIdsToTest); + expect(supported.length).to.equal(2); + expect(supported[0]).to.equal(false); + expect(supported[1]).to.equal(false); + }); + + it('supports not all of the interfaces queried via getSupportedInterfaces', async function () { + const interfaceIdsToTest = [...this.supportedInterfaces, DUMMY_UNSUPPORTED_ID]; + + const supported = await this.mock.$getSupportedInterfaces(this.target.address, interfaceIdsToTest); + expect(supported.length).to.equal(4); + expect(supported[0]).to.equal(true); + expect(supported[1]).to.equal(true); + expect(supported[2]).to.equal(true); + expect(supported[3]).to.equal(false); + }); + + it('supports each interfaceId via supportsERC165InterfaceUnchecked', async function () { + for (const interfaceId of this.supportedInterfaces) { + const supported = await this.mock.$supportsERC165InterfaceUnchecked(this.target.address, interfaceId); + expect(supported).to.equal(true); + } + }); + }); + + context('account address does not support ERC165', function () { + it('does not support ERC165', async function () { + const supported = await this.mock.$supportsERC165(DUMMY_ACCOUNT); + expect(supported).to.equal(false); + }); + + it('does not support mock interface via supportsInterface', async function () { + const supported = await this.mock.$supportsInterface(DUMMY_ACCOUNT, DUMMY_ID); + expect(supported).to.equal(false); + }); + + it('does not support mock interface via supportsAllInterfaces', async function () { + const supported = await this.mock.$supportsAllInterfaces(DUMMY_ACCOUNT, [DUMMY_ID]); + expect(supported).to.equal(false); + }); + + it('does not support mock interface via getSupportedInterfaces', async function () { + const supported = await this.mock.$getSupportedInterfaces(DUMMY_ACCOUNT, [DUMMY_ID]); + expect(supported.length).to.equal(1); + expect(supported[0]).to.equal(false); + }); + + it('does not support mock interface via supportsERC165InterfaceUnchecked', async function () { + const supported = await this.mock.$supportsERC165InterfaceUnchecked(DUMMY_ACCOUNT, DUMMY_ID); + expect(supported).to.equal(false); + }); + }); + + it('Return bomb resistance', async function () { + this.target = await ERC165ReturnBombMock.new(); + + const tx1 = await this.mock.$supportsInterface.sendTransaction(this.target.address, DUMMY_ID); + expect(tx1.receipt.gasUsed).to.be.lessThan(120000); // 3*30k + 21k + some margin + + const tx2 = await this.mock.$getSupportedInterfaces.sendTransaction(this.target.address, [ + DUMMY_ID, + DUMMY_ID_2, + DUMMY_ID_3, + DUMMY_UNSUPPORTED_ID, + DUMMY_UNSUPPORTED_ID_2, + ]); + expect(tx2.receipt.gasUsed).to.be.lessThan(250000); // (2+5)*30k + 21k + some margin + }); +}); diff --git a/test/utils/introspection/SupportsInterface.behavior.js b/test/utils/introspection/SupportsInterface.behavior.js new file mode 100644 index 000000000..49a30e755 --- /dev/null +++ b/test/utils/introspection/SupportsInterface.behavior.js @@ -0,0 +1,144 @@ +const { makeInterfaceId } = require('@openzeppelin/test-helpers'); + +const { expect } = require('chai'); + +const INVALID_ID = '0xffffffff'; +const INTERFACES = { + ERC165: ['supportsInterface(bytes4)'], + ERC721: [ + 'balanceOf(address)', + 'ownerOf(uint256)', + 'approve(address,uint256)', + 'getApproved(uint256)', + 'setApprovalForAll(address,bool)', + 'isApprovedForAll(address,address)', + 'transferFrom(address,address,uint256)', + 'safeTransferFrom(address,address,uint256)', + 'safeTransferFrom(address,address,uint256,bytes)', + ], + ERC721Enumerable: ['totalSupply()', 'tokenOfOwnerByIndex(address,uint256)', 'tokenByIndex(uint256)'], + ERC721Metadata: ['name()', 'symbol()', 'tokenURI(uint256)'], + ERC1155: [ + 'balanceOf(address,uint256)', + 'balanceOfBatch(address[],uint256[])', + 'setApprovalForAll(address,bool)', + 'isApprovedForAll(address,address)', + 'safeTransferFrom(address,address,uint256,uint256,bytes)', + 'safeBatchTransferFrom(address,address,uint256[],uint256[],bytes)', + ], + ERC1155Receiver: [ + 'onERC1155Received(address,address,uint256,uint256,bytes)', + 'onERC1155BatchReceived(address,address,uint256[],uint256[],bytes)', + ], + AccessControl: [ + 'hasRole(bytes32,address)', + 'getRoleAdmin(bytes32)', + 'grantRole(bytes32,address)', + 'revokeRole(bytes32,address)', + 'renounceRole(bytes32,address)', + ], + AccessControlEnumerable: ['getRoleMember(bytes32,uint256)', 'getRoleMemberCount(bytes32)'], + AccessControlDefaultAdminRules: [ + 'defaultAdminDelay()', + 'pendingDefaultAdminDelay()', + 'defaultAdmin()', + 'pendingDefaultAdmin()', + 'defaultAdminDelayIncreaseWait()', + 'changeDefaultAdminDelay(uint48)', + 'rollbackDefaultAdminDelay()', + 'beginDefaultAdminTransfer(address)', + 'acceptDefaultAdminTransfer()', + 'cancelDefaultAdminTransfer()', + ], + Governor: [ + 'name()', + 'version()', + 'COUNTING_MODE()', + 'hashProposal(address[],uint256[],bytes[],bytes32)', + 'state(uint256)', + 'proposalThreshold()', + 'proposalSnapshot(uint256)', + 'proposalDeadline(uint256)', + 'proposalProposer(uint256)', + 'proposalEta(uint256)', + 'proposalNeedsQueuing(uint256)', + 'votingDelay()', + 'votingPeriod()', + 'quorum(uint256)', + 'getVotes(address,uint256)', + 'getVotesWithParams(address,uint256,bytes)', + 'hasVoted(uint256,address)', + 'propose(address[],uint256[],bytes[],string)', + 'queue(address[],uint256[],bytes[],bytes32)', + 'execute(address[],uint256[],bytes[],bytes32)', + 'cancel(address[],uint256[],bytes[],bytes32)', + 'castVote(uint256,uint8)', + 'castVoteWithReason(uint256,uint8,string)', + 'castVoteWithReasonAndParams(uint256,uint8,string,bytes)', + 'castVoteBySig(uint256,uint8,address,bytes)', + 'castVoteWithReasonAndParamsBySig(uint256,uint8,address,string,bytes,bytes)', + ], + ERC2981: ['royaltyInfo(uint256,uint256)'], +}; + +const INTERFACE_IDS = {}; +const FN_SIGNATURES = {}; +for (const k of Object.getOwnPropertyNames(INTERFACES)) { + INTERFACE_IDS[k] = makeInterfaceId.ERC165(INTERFACES[k]); + for (const fnName of INTERFACES[k]) { + // the interface id of a single function is equivalent to its function signature + FN_SIGNATURES[fnName] = makeInterfaceId.ERC165([fnName]); + } +} + +function shouldSupportInterfaces(interfaces = []) { + describe('ERC165', function () { + beforeEach(function () { + this.contractUnderTest = this.mock || this.token || this.holder || this.accessControl; + }); + + describe('when the interfaceId is supported', function () { + it('uses less than 30k gas', async function () { + for (const k of interfaces) { + const interfaceId = INTERFACE_IDS[k] ?? k; + expect(await this.contractUnderTest.supportsInterface.estimateGas(interfaceId)).to.be.lte(30000); + } + }); + + it('returns true', async function () { + for (const k of interfaces) { + const interfaceId = INTERFACE_IDS[k] ?? k; + expect(await this.contractUnderTest.supportsInterface(interfaceId)).to.equal(true, `does not support ${k}`); + } + }); + }); + + describe('when the interfaceId is not supported', function () { + it('uses less thank 30k', async function () { + expect(await this.contractUnderTest.supportsInterface.estimateGas(INVALID_ID)).to.be.lte(30000); + }); + + it('returns false', async function () { + expect(await this.contractUnderTest.supportsInterface(INVALID_ID)).to.be.equal(false, `supports ${INVALID_ID}`); + }); + }); + + it('all interface functions are in ABI', async function () { + for (const k of interfaces) { + // skip interfaces for which we don't have a function list + if (INTERFACES[k] === undefined) continue; + for (const fnName of INTERFACES[k]) { + const fnSig = FN_SIGNATURES[fnName]; + expect(this.contractUnderTest.abi.filter(fn => fn.signature === fnSig).length).to.equal( + 1, + `did not find ${fnName}`, + ); + } + } + }); + }); +} + +module.exports = { + shouldSupportInterfaces, +}; diff --git a/test/utils/math/Math.t.sol b/test/utils/math/Math.t.sol new file mode 100644 index 000000000..0b497a858 --- /dev/null +++ b/test/utils/math/Math.t.sol @@ -0,0 +1,216 @@ +// SPDX-License-Identifier: MIT + +pragma solidity ^0.8.20; + +import {Test} from "forge-std/Test.sol"; + +import {Math} from "@openzeppelin/contracts/utils/math/Math.sol"; + +contract MathTest is Test { + // CEILDIV + function testCeilDiv(uint256 a, uint256 b) public { + vm.assume(b > 0); + + uint256 result = Math.ceilDiv(a, b); + + if (result == 0) { + assertEq(a, 0); + } else { + uint256 maxdiv = UINT256_MAX / b; + bool overflow = maxdiv * b < a; + assertTrue(a > b * (result - 1)); + assertTrue(overflow ? result == maxdiv + 1 : a <= b * result); + } + } + + // SQRT + function testSqrt(uint256 input, uint8 r) public { + Math.Rounding rounding = _asRounding(r); + + uint256 result = Math.sqrt(input, rounding); + + // square of result is bigger than input + if (_squareBigger(result, input)) { + assertTrue(Math.unsignedRoundsUp(rounding)); + assertTrue(_squareSmaller(result - 1, input)); + } + // square of result is smaller than input + else if (_squareSmaller(result, input)) { + assertFalse(Math.unsignedRoundsUp(rounding)); + assertTrue(_squareBigger(result + 1, input)); + } + // input is perfect square + else { + assertEq(result * result, input); + } + } + + function _squareBigger(uint256 value, uint256 ref) private pure returns (bool) { + (bool noOverflow, uint256 square) = Math.tryMul(value, value); + return !noOverflow || square > ref; + } + + function _squareSmaller(uint256 value, uint256 ref) private pure returns (bool) { + return value * value < ref; + } + + // LOG2 + function testLog2(uint256 input, uint8 r) public { + Math.Rounding rounding = _asRounding(r); + + uint256 result = Math.log2(input, rounding); + + if (input == 0) { + assertEq(result, 0); + } else if (_powerOf2Bigger(result, input)) { + assertTrue(Math.unsignedRoundsUp(rounding)); + assertTrue(_powerOf2Smaller(result - 1, input)); + } else if (_powerOf2Smaller(result, input)) { + assertFalse(Math.unsignedRoundsUp(rounding)); + assertTrue(_powerOf2Bigger(result + 1, input)); + } else { + assertEq(2 ** result, input); + } + } + + function _powerOf2Bigger(uint256 value, uint256 ref) private pure returns (bool) { + return value >= 256 || 2 ** value > ref; // 2**256 overflows uint256 + } + + function _powerOf2Smaller(uint256 value, uint256 ref) private pure returns (bool) { + return 2 ** value < ref; + } + + // LOG10 + function testLog10(uint256 input, uint8 r) public { + Math.Rounding rounding = _asRounding(r); + + uint256 result = Math.log10(input, rounding); + + if (input == 0) { + assertEq(result, 0); + } else if (_powerOf10Bigger(result, input)) { + assertTrue(Math.unsignedRoundsUp(rounding)); + assertTrue(_powerOf10Smaller(result - 1, input)); + } else if (_powerOf10Smaller(result, input)) { + assertFalse(Math.unsignedRoundsUp(rounding)); + assertTrue(_powerOf10Bigger(result + 1, input)); + } else { + assertEq(10 ** result, input); + } + } + + function _powerOf10Bigger(uint256 value, uint256 ref) private pure returns (bool) { + return value >= 78 || 10 ** value > ref; // 10**78 overflows uint256 + } + + function _powerOf10Smaller(uint256 value, uint256 ref) private pure returns (bool) { + return 10 ** value < ref; + } + + // LOG256 + function testLog256(uint256 input, uint8 r) public { + Math.Rounding rounding = _asRounding(r); + + uint256 result = Math.log256(input, rounding); + + if (input == 0) { + assertEq(result, 0); + } else if (_powerOf256Bigger(result, input)) { + assertTrue(Math.unsignedRoundsUp(rounding)); + assertTrue(_powerOf256Smaller(result - 1, input)); + } else if (_powerOf256Smaller(result, input)) { + assertFalse(Math.unsignedRoundsUp(rounding)); + assertTrue(_powerOf256Bigger(result + 1, input)); + } else { + assertEq(256 ** result, input); + } + } + + function _powerOf256Bigger(uint256 value, uint256 ref) private pure returns (bool) { + return value >= 32 || 256 ** value > ref; // 256**32 overflows uint256 + } + + function _powerOf256Smaller(uint256 value, uint256 ref) private pure returns (bool) { + return 256 ** value < ref; + } + + // MULDIV + function testMulDiv(uint256 x, uint256 y, uint256 d) public { + // Full precision for x * y + (uint256 xyHi, uint256 xyLo) = _mulHighLow(x, y); + + // Assume result won't overflow (see {testMulDivDomain}) + // This also checks that `d` is positive + vm.assume(xyHi < d); + + // Perform muldiv + uint256 q = Math.mulDiv(x, y, d); + + // Full precision for q * d + (uint256 qdHi, uint256 qdLo) = _mulHighLow(q, d); + // Add remainder of x * y / d (computed as rem = (x * y % d)) + (uint256 qdRemLo, uint256 c) = _addCarry(qdLo, _mulmod(x, y, d)); + uint256 qdRemHi = qdHi + c; + + // Full precision check that x * y = q * d + rem + assertEq(xyHi, qdRemHi); + assertEq(xyLo, qdRemLo); + } + + function testMulDivDomain(uint256 x, uint256 y, uint256 d) public { + (uint256 xyHi, ) = _mulHighLow(x, y); + + // Violate {testMulDiv} assumption (covers d is 0 and result overflow) + vm.assume(xyHi >= d); + + // we are outside the scope of {testMulDiv}, we expect muldiv to revert + try this.muldiv(x, y, d) returns (uint256) { + fail(); + } catch {} + } + + // External call + function muldiv(uint256 x, uint256 y, uint256 d) external pure returns (uint256) { + return Math.mulDiv(x, y, d); + } + + // Helpers + function _asRounding(uint8 r) private pure returns (Math.Rounding) { + vm.assume(r < uint8(type(Math.Rounding).max)); + return Math.Rounding(r); + } + + function _mulmod(uint256 x, uint256 y, uint256 z) private pure returns (uint256 r) { + assembly { + r := mulmod(x, y, z) + } + } + + function _mulHighLow(uint256 x, uint256 y) private pure returns (uint256 high, uint256 low) { + (uint256 x0, uint256 x1) = (x & type(uint128).max, x >> 128); + (uint256 y0, uint256 y1) = (y & type(uint128).max, y >> 128); + + // Karatsuba algorithm + // https://en.wikipedia.org/wiki/Karatsuba_algorithm + uint256 z2 = x1 * y1; + uint256 z1a = x1 * y0; + uint256 z1b = x0 * y1; + uint256 z0 = x0 * y0; + + uint256 carry = ((z1a & type(uint128).max) + (z1b & type(uint128).max) + (z0 >> 128)) >> 128; + + high = z2 + (z1a >> 128) + (z1b >> 128) + carry; + + unchecked { + low = x * y; + } + } + + function _addCarry(uint256 x, uint256 y) private pure returns (uint256 res, uint256 carry) { + unchecked { + res = x + y; + } + carry = res < x ? 1 : 0; + } +} diff --git a/test/utils/math/Math.test.js b/test/utils/math/Math.test.js new file mode 100644 index 000000000..7d4a58c81 --- /dev/null +++ b/test/utils/math/Math.test.js @@ -0,0 +1,469 @@ +const { BN, constants, expectRevert } = require('@openzeppelin/test-helpers'); +const { expect } = require('chai'); +const { MAX_UINT256 } = constants; +const { Rounding } = require('../../helpers/enums.js'); +const { expectRevertCustomError } = require('../../helpers/customError.js'); + +const Math = artifacts.require('$Math'); + +const RoundingDown = [Rounding.Floor, Rounding.Trunc]; +const RoundingUp = [Rounding.Ceil, Rounding.Expand]; + +function expectStruct(value, expected) { + for (const key in expected) { + if (BN.isBN(value[key])) { + expect(value[key]).to.be.bignumber.equal(expected[key]); + } else { + expect(value[key]).to.be.equal(expected[key]); + } + } +} + +async function testCommutativeIterable(fn, lhs, rhs, expected, ...extra) { + expectStruct(await fn(lhs, rhs, ...extra), expected); + expectStruct(await fn(rhs, lhs, ...extra), expected); +} + +contract('Math', function () { + const min = new BN('1234'); + const max = new BN('5678'); + const MAX_UINT256_SUB1 = MAX_UINT256.sub(new BN('1')); + const MAX_UINT256_SUB2 = MAX_UINT256.sub(new BN('2')); + + beforeEach(async function () { + this.math = await Math.new(); + }); + + describe('tryAdd', function () { + it('adds correctly', async function () { + const a = new BN('5678'); + const b = new BN('1234'); + + await testCommutativeIterable(this.math.$tryAdd, a, b, [true, a.add(b)]); + }); + + it('reverts on addition overflow', async function () { + const a = MAX_UINT256; + const b = new BN('1'); + + await testCommutativeIterable(this.math.$tryAdd, a, b, [false, '0']); + }); + }); + + describe('trySub', function () { + it('subtracts correctly', async function () { + const a = new BN('5678'); + const b = new BN('1234'); + + expectStruct(await this.math.$trySub(a, b), [true, a.sub(b)]); + }); + + it('reverts if subtraction result would be negative', async function () { + const a = new BN('1234'); + const b = new BN('5678'); + + expectStruct(await this.math.$trySub(a, b), [false, '0']); + }); + }); + + describe('tryMul', function () { + it('multiplies correctly', async function () { + const a = new BN('1234'); + const b = new BN('5678'); + + await testCommutativeIterable(this.math.$tryMul, a, b, [true, a.mul(b)]); + }); + + it('multiplies by zero correctly', async function () { + const a = new BN('0'); + const b = new BN('5678'); + + await testCommutativeIterable(this.math.$tryMul, a, b, [true, a.mul(b)]); + }); + + it('reverts on multiplication overflow', async function () { + const a = MAX_UINT256; + const b = new BN('2'); + + await testCommutativeIterable(this.math.$tryMul, a, b, [false, '0']); + }); + }); + + describe('tryDiv', function () { + it('divides correctly', async function () { + const a = new BN('5678'); + const b = new BN('5678'); + + expectStruct(await this.math.$tryDiv(a, b), [true, a.div(b)]); + }); + + it('divides zero correctly', async function () { + const a = new BN('0'); + const b = new BN('5678'); + + expectStruct(await this.math.$tryDiv(a, b), [true, a.div(b)]); + }); + + it('returns complete number result on non-even division', async function () { + const a = new BN('7000'); + const b = new BN('5678'); + + expectStruct(await this.math.$tryDiv(a, b), [true, a.div(b)]); + }); + + it('reverts on division by zero', async function () { + const a = new BN('5678'); + const b = new BN('0'); + + expectStruct(await this.math.$tryDiv(a, b), [false, '0']); + }); + }); + + describe('tryMod', function () { + describe('modulos correctly', async function () { + it('when the dividend is smaller than the divisor', async function () { + const a = new BN('284'); + const b = new BN('5678'); + + expectStruct(await this.math.$tryMod(a, b), [true, a.mod(b)]); + }); + + it('when the dividend is equal to the divisor', async function () { + const a = new BN('5678'); + const b = new BN('5678'); + + expectStruct(await this.math.$tryMod(a, b), [true, a.mod(b)]); + }); + + it('when the dividend is larger than the divisor', async function () { + const a = new BN('7000'); + const b = new BN('5678'); + + expectStruct(await this.math.$tryMod(a, b), [true, a.mod(b)]); + }); + + it('when the dividend is a multiple of the divisor', async function () { + const a = new BN('17034'); // 17034 == 5678 * 3 + const b = new BN('5678'); + + expectStruct(await this.math.$tryMod(a, b), [true, a.mod(b)]); + }); + }); + + it('reverts with a 0 divisor', async function () { + const a = new BN('5678'); + const b = new BN('0'); + + expectStruct(await this.math.$tryMod(a, b), [false, '0']); + }); + }); + + describe('max', function () { + it('is correctly detected in first argument position', async function () { + expect(await this.math.$max(max, min)).to.be.bignumber.equal(max); + }); + + it('is correctly detected in second argument position', async function () { + expect(await this.math.$max(min, max)).to.be.bignumber.equal(max); + }); + }); + + describe('min', function () { + it('is correctly detected in first argument position', async function () { + expect(await this.math.$min(min, max)).to.be.bignumber.equal(min); + }); + + it('is correctly detected in second argument position', async function () { + expect(await this.math.$min(max, min)).to.be.bignumber.equal(min); + }); + }); + + describe('average', function () { + function bnAverage(a, b) { + return a.add(b).divn(2); + } + + it('is correctly calculated with two odd numbers', async function () { + const a = new BN('57417'); + const b = new BN('95431'); + expect(await this.math.$average(a, b)).to.be.bignumber.equal(bnAverage(a, b)); + }); + + it('is correctly calculated with two even numbers', async function () { + const a = new BN('42304'); + const b = new BN('84346'); + expect(await this.math.$average(a, b)).to.be.bignumber.equal(bnAverage(a, b)); + }); + + it('is correctly calculated with one even and one odd number', async function () { + const a = new BN('57417'); + const b = new BN('84346'); + expect(await this.math.$average(a, b)).to.be.bignumber.equal(bnAverage(a, b)); + }); + + it('is correctly calculated with two max uint256 numbers', async function () { + const a = MAX_UINT256; + expect(await this.math.$average(a, a)).to.be.bignumber.equal(bnAverage(a, a)); + }); + }); + + describe('ceilDiv', function () { + it('reverts on zero division', async function () { + const a = new BN('2'); + const b = new BN('0'); + // It's unspecified because it's a low level 0 division error + await expectRevert.unspecified(this.math.$ceilDiv(a, b)); + }); + + it('does not round up a zero result', async function () { + const a = new BN('0'); + const b = new BN('2'); + expect(await this.math.$ceilDiv(a, b)).to.be.bignumber.equal('0'); + }); + + it('does not round up on exact division', async function () { + const a = new BN('10'); + const b = new BN('5'); + expect(await this.math.$ceilDiv(a, b)).to.be.bignumber.equal('2'); + }); + + it('rounds up on division with remainders', async function () { + const a = new BN('42'); + const b = new BN('13'); + expect(await this.math.$ceilDiv(a, b)).to.be.bignumber.equal('4'); + }); + + it('does not overflow', async function () { + const b = new BN('2'); + const result = new BN('1').shln(255); + expect(await this.math.$ceilDiv(MAX_UINT256, b)).to.be.bignumber.equal(result); + }); + + it('correctly computes max uint256 divided by 1', async function () { + const b = new BN('1'); + expect(await this.math.$ceilDiv(MAX_UINT256, b)).to.be.bignumber.equal(MAX_UINT256); + }); + }); + + describe('muldiv', function () { + it('divide by 0', async function () { + await expectRevert.unspecified(this.math.$mulDiv(1, 1, 0, Rounding.Floor)); + }); + + it('reverts with result higher than 2 ^ 256', async function () { + await expectRevertCustomError(this.math.$mulDiv(5, MAX_UINT256, 2, Rounding.Floor), 'MathOverflowedMulDiv', []); + }); + + describe('does round down', async function () { + it('small values', async function () { + for (const rounding of RoundingDown) { + expect(await this.math.$mulDiv('3', '4', '5', rounding)).to.be.bignumber.equal('2'); + expect(await this.math.$mulDiv('3', '5', '5', rounding)).to.be.bignumber.equal('3'); + } + }); + + it('large values', async function () { + for (const rounding of RoundingDown) { + expect(await this.math.$mulDiv(new BN('42'), MAX_UINT256_SUB1, MAX_UINT256, rounding)).to.be.bignumber.equal( + new BN('41'), + ); + + expect(await this.math.$mulDiv(new BN('17'), MAX_UINT256, MAX_UINT256, rounding)).to.be.bignumber.equal( + new BN('17'), + ); + + expect( + await this.math.$mulDiv(MAX_UINT256_SUB1, MAX_UINT256_SUB1, MAX_UINT256, rounding), + ).to.be.bignumber.equal(MAX_UINT256_SUB2); + + expect(await this.math.$mulDiv(MAX_UINT256, MAX_UINT256_SUB1, MAX_UINT256, rounding)).to.be.bignumber.equal( + MAX_UINT256_SUB1, + ); + + expect(await this.math.$mulDiv(MAX_UINT256, MAX_UINT256, MAX_UINT256, rounding)).to.be.bignumber.equal( + MAX_UINT256, + ); + } + }); + }); + + describe('does round up', async function () { + it('small values', async function () { + for (const rounding of RoundingUp) { + expect(await this.math.$mulDiv('3', '4', '5', rounding)).to.be.bignumber.equal('3'); + expect(await this.math.$mulDiv('3', '5', '5', rounding)).to.be.bignumber.equal('3'); + } + }); + + it('large values', async function () { + for (const rounding of RoundingUp) { + expect(await this.math.$mulDiv(new BN('42'), MAX_UINT256_SUB1, MAX_UINT256, rounding)).to.be.bignumber.equal( + new BN('42'), + ); + + expect(await this.math.$mulDiv(new BN('17'), MAX_UINT256, MAX_UINT256, rounding)).to.be.bignumber.equal( + new BN('17'), + ); + + expect( + await this.math.$mulDiv(MAX_UINT256_SUB1, MAX_UINT256_SUB1, MAX_UINT256, rounding), + ).to.be.bignumber.equal(MAX_UINT256_SUB1); + + expect(await this.math.$mulDiv(MAX_UINT256, MAX_UINT256_SUB1, MAX_UINT256, rounding)).to.be.bignumber.equal( + MAX_UINT256_SUB1, + ); + + expect(await this.math.$mulDiv(MAX_UINT256, MAX_UINT256, MAX_UINT256, rounding)).to.be.bignumber.equal( + MAX_UINT256, + ); + } + }); + }); + }); + + describe('sqrt', function () { + it('rounds down', async function () { + for (const rounding of RoundingDown) { + expect(await this.math.$sqrt('0', rounding)).to.be.bignumber.equal('0'); + expect(await this.math.$sqrt('1', rounding)).to.be.bignumber.equal('1'); + expect(await this.math.$sqrt('2', rounding)).to.be.bignumber.equal('1'); + expect(await this.math.$sqrt('3', rounding)).to.be.bignumber.equal('1'); + expect(await this.math.$sqrt('4', rounding)).to.be.bignumber.equal('2'); + expect(await this.math.$sqrt('144', rounding)).to.be.bignumber.equal('12'); + expect(await this.math.$sqrt('999999', rounding)).to.be.bignumber.equal('999'); + expect(await this.math.$sqrt('1000000', rounding)).to.be.bignumber.equal('1000'); + expect(await this.math.$sqrt('1000001', rounding)).to.be.bignumber.equal('1000'); + expect(await this.math.$sqrt('1002000', rounding)).to.be.bignumber.equal('1000'); + expect(await this.math.$sqrt('1002001', rounding)).to.be.bignumber.equal('1001'); + expect(await this.math.$sqrt(MAX_UINT256, rounding)).to.be.bignumber.equal( + '340282366920938463463374607431768211455', + ); + } + }); + + it('rounds up', async function () { + for (const rounding of RoundingUp) { + expect(await this.math.$sqrt('0', rounding)).to.be.bignumber.equal('0'); + expect(await this.math.$sqrt('1', rounding)).to.be.bignumber.equal('1'); + expect(await this.math.$sqrt('2', rounding)).to.be.bignumber.equal('2'); + expect(await this.math.$sqrt('3', rounding)).to.be.bignumber.equal('2'); + expect(await this.math.$sqrt('4', rounding)).to.be.bignumber.equal('2'); + expect(await this.math.$sqrt('144', rounding)).to.be.bignumber.equal('12'); + expect(await this.math.$sqrt('999999', rounding)).to.be.bignumber.equal('1000'); + expect(await this.math.$sqrt('1000000', rounding)).to.be.bignumber.equal('1000'); + expect(await this.math.$sqrt('1000001', rounding)).to.be.bignumber.equal('1001'); + expect(await this.math.$sqrt('1002000', rounding)).to.be.bignumber.equal('1001'); + expect(await this.math.$sqrt('1002001', rounding)).to.be.bignumber.equal('1001'); + expect(await this.math.$sqrt(MAX_UINT256, rounding)).to.be.bignumber.equal( + '340282366920938463463374607431768211456', + ); + } + }); + }); + + describe('log', function () { + describe('log2', function () { + it('rounds down', async function () { + for (const rounding of RoundingDown) { + expect(await this.math.methods['$log2(uint256,uint8)']('0', rounding)).to.be.bignumber.equal('0'); + expect(await this.math.methods['$log2(uint256,uint8)']('1', rounding)).to.be.bignumber.equal('0'); + expect(await this.math.methods['$log2(uint256,uint8)']('2', rounding)).to.be.bignumber.equal('1'); + expect(await this.math.methods['$log2(uint256,uint8)']('3', rounding)).to.be.bignumber.equal('1'); + expect(await this.math.methods['$log2(uint256,uint8)']('4', rounding)).to.be.bignumber.equal('2'); + expect(await this.math.methods['$log2(uint256,uint8)']('5', rounding)).to.be.bignumber.equal('2'); + expect(await this.math.methods['$log2(uint256,uint8)']('6', rounding)).to.be.bignumber.equal('2'); + expect(await this.math.methods['$log2(uint256,uint8)']('7', rounding)).to.be.bignumber.equal('2'); + expect(await this.math.methods['$log2(uint256,uint8)']('8', rounding)).to.be.bignumber.equal('3'); + expect(await this.math.methods['$log2(uint256,uint8)']('9', rounding)).to.be.bignumber.equal('3'); + expect(await this.math.methods['$log2(uint256,uint8)'](MAX_UINT256, rounding)).to.be.bignumber.equal('255'); + } + }); + + it('rounds up', async function () { + for (const rounding of RoundingUp) { + expect(await this.math.methods['$log2(uint256,uint8)']('0', rounding)).to.be.bignumber.equal('0'); + expect(await this.math.methods['$log2(uint256,uint8)']('1', rounding)).to.be.bignumber.equal('0'); + expect(await this.math.methods['$log2(uint256,uint8)']('2', rounding)).to.be.bignumber.equal('1'); + expect(await this.math.methods['$log2(uint256,uint8)']('3', rounding)).to.be.bignumber.equal('2'); + expect(await this.math.methods['$log2(uint256,uint8)']('4', rounding)).to.be.bignumber.equal('2'); + expect(await this.math.methods['$log2(uint256,uint8)']('5', rounding)).to.be.bignumber.equal('3'); + expect(await this.math.methods['$log2(uint256,uint8)']('6', rounding)).to.be.bignumber.equal('3'); + expect(await this.math.methods['$log2(uint256,uint8)']('7', rounding)).to.be.bignumber.equal('3'); + expect(await this.math.methods['$log2(uint256,uint8)']('8', rounding)).to.be.bignumber.equal('3'); + expect(await this.math.methods['$log2(uint256,uint8)']('9', rounding)).to.be.bignumber.equal('4'); + expect(await this.math.methods['$log2(uint256,uint8)'](MAX_UINT256, rounding)).to.be.bignumber.equal('256'); + } + }); + }); + + describe('log10', function () { + it('rounds down', async function () { + for (const rounding of RoundingDown) { + expect(await this.math.$log10('0', rounding)).to.be.bignumber.equal('0'); + expect(await this.math.$log10('1', rounding)).to.be.bignumber.equal('0'); + expect(await this.math.$log10('2', rounding)).to.be.bignumber.equal('0'); + expect(await this.math.$log10('9', rounding)).to.be.bignumber.equal('0'); + expect(await this.math.$log10('10', rounding)).to.be.bignumber.equal('1'); + expect(await this.math.$log10('11', rounding)).to.be.bignumber.equal('1'); + expect(await this.math.$log10('99', rounding)).to.be.bignumber.equal('1'); + expect(await this.math.$log10('100', rounding)).to.be.bignumber.equal('2'); + expect(await this.math.$log10('101', rounding)).to.be.bignumber.equal('2'); + expect(await this.math.$log10('999', rounding)).to.be.bignumber.equal('2'); + expect(await this.math.$log10('1000', rounding)).to.be.bignumber.equal('3'); + expect(await this.math.$log10('1001', rounding)).to.be.bignumber.equal('3'); + expect(await this.math.$log10(MAX_UINT256, rounding)).to.be.bignumber.equal('77'); + } + }); + + it('rounds up', async function () { + for (const rounding of RoundingUp) { + expect(await this.math.$log10('0', rounding)).to.be.bignumber.equal('0'); + expect(await this.math.$log10('1', rounding)).to.be.bignumber.equal('0'); + expect(await this.math.$log10('2', rounding)).to.be.bignumber.equal('1'); + expect(await this.math.$log10('9', rounding)).to.be.bignumber.equal('1'); + expect(await this.math.$log10('10', rounding)).to.be.bignumber.equal('1'); + expect(await this.math.$log10('11', rounding)).to.be.bignumber.equal('2'); + expect(await this.math.$log10('99', rounding)).to.be.bignumber.equal('2'); + expect(await this.math.$log10('100', rounding)).to.be.bignumber.equal('2'); + expect(await this.math.$log10('101', rounding)).to.be.bignumber.equal('3'); + expect(await this.math.$log10('999', rounding)).to.be.bignumber.equal('3'); + expect(await this.math.$log10('1000', rounding)).to.be.bignumber.equal('3'); + expect(await this.math.$log10('1001', rounding)).to.be.bignumber.equal('4'); + expect(await this.math.$log10(MAX_UINT256, rounding)).to.be.bignumber.equal('78'); + } + }); + }); + + describe('log256', function () { + it('rounds down', async function () { + for (const rounding of RoundingDown) { + expect(await this.math.$log256('0', rounding)).to.be.bignumber.equal('0'); + expect(await this.math.$log256('1', rounding)).to.be.bignumber.equal('0'); + expect(await this.math.$log256('2', rounding)).to.be.bignumber.equal('0'); + expect(await this.math.$log256('255', rounding)).to.be.bignumber.equal('0'); + expect(await this.math.$log256('256', rounding)).to.be.bignumber.equal('1'); + expect(await this.math.$log256('257', rounding)).to.be.bignumber.equal('1'); + expect(await this.math.$log256('65535', rounding)).to.be.bignumber.equal('1'); + expect(await this.math.$log256('65536', rounding)).to.be.bignumber.equal('2'); + expect(await this.math.$log256('65537', rounding)).to.be.bignumber.equal('2'); + expect(await this.math.$log256(MAX_UINT256, rounding)).to.be.bignumber.equal('31'); + } + }); + + it('rounds up', async function () { + for (const rounding of RoundingUp) { + expect(await this.math.$log256('0', rounding)).to.be.bignumber.equal('0'); + expect(await this.math.$log256('1', rounding)).to.be.bignumber.equal('0'); + expect(await this.math.$log256('2', rounding)).to.be.bignumber.equal('1'); + expect(await this.math.$log256('255', rounding)).to.be.bignumber.equal('1'); + expect(await this.math.$log256('256', rounding)).to.be.bignumber.equal('1'); + expect(await this.math.$log256('257', rounding)).to.be.bignumber.equal('2'); + expect(await this.math.$log256('65535', rounding)).to.be.bignumber.equal('2'); + expect(await this.math.$log256('65536', rounding)).to.be.bignumber.equal('2'); + expect(await this.math.$log256('65537', rounding)).to.be.bignumber.equal('3'); + expect(await this.math.$log256(MAX_UINT256, rounding)).to.be.bignumber.equal('32'); + } + }); + }); + }); +}); diff --git a/test/utils/math/SafeCast.test.js b/test/utils/math/SafeCast.test.js new file mode 100644 index 000000000..4b8ec5a72 --- /dev/null +++ b/test/utils/math/SafeCast.test.js @@ -0,0 +1,161 @@ +const { BN } = require('@openzeppelin/test-helpers'); +const { expect } = require('chai'); +const { range } = require('../../../scripts/helpers'); +const { expectRevertCustomError } = require('../../helpers/customError'); + +const SafeCast = artifacts.require('$SafeCast'); + +contract('SafeCast', async function () { + beforeEach(async function () { + this.safeCast = await SafeCast.new(); + }); + + function testToUint(bits) { + describe(`toUint${bits}`, () => { + const maxValue = new BN('2').pow(new BN(bits)).subn(1); + + it('downcasts 0', async function () { + expect(await this.safeCast[`$toUint${bits}`](0)).to.be.bignumber.equal('0'); + }); + + it('downcasts 1', async function () { + expect(await this.safeCast[`$toUint${bits}`](1)).to.be.bignumber.equal('1'); + }); + + it(`downcasts 2^${bits} - 1 (${maxValue})`, async function () { + expect(await this.safeCast[`$toUint${bits}`](maxValue)).to.be.bignumber.equal(maxValue); + }); + + it(`reverts when downcasting 2^${bits} (${maxValue.addn(1)})`, async function () { + await expectRevertCustomError( + this.safeCast[`$toUint${bits}`](maxValue.addn(1)), + `SafeCastOverflowedUintDowncast`, + [bits, maxValue.addn(1)], + ); + }); + + it(`reverts when downcasting 2^${bits} + 1 (${maxValue.addn(2)})`, async function () { + await expectRevertCustomError( + this.safeCast[`$toUint${bits}`](maxValue.addn(2)), + `SafeCastOverflowedUintDowncast`, + [bits, maxValue.addn(2)], + ); + }); + }); + } + + range(8, 256, 8).forEach(bits => testToUint(bits)); + + describe('toUint256', () => { + const maxInt256 = new BN('2').pow(new BN(255)).subn(1); + const minInt256 = new BN('2').pow(new BN(255)).neg(); + + it('casts 0', async function () { + expect(await this.safeCast.$toUint256(0)).to.be.bignumber.equal('0'); + }); + + it('casts 1', async function () { + expect(await this.safeCast.$toUint256(1)).to.be.bignumber.equal('1'); + }); + + it(`casts INT256_MAX (${maxInt256})`, async function () { + expect(await this.safeCast.$toUint256(maxInt256)).to.be.bignumber.equal(maxInt256); + }); + + it('reverts when casting -1', async function () { + await expectRevertCustomError(this.safeCast.$toUint256(-1), `SafeCastOverflowedIntToUint`, [-1]); + }); + + it(`reverts when casting INT256_MIN (${minInt256})`, async function () { + await expectRevertCustomError(this.safeCast.$toUint256(minInt256), `SafeCastOverflowedIntToUint`, [minInt256]); + }); + }); + + function testToInt(bits) { + describe(`toInt${bits}`, () => { + const minValue = new BN('-2').pow(new BN(bits - 1)); + const maxValue = new BN('2').pow(new BN(bits - 1)).subn(1); + + it('downcasts 0', async function () { + expect(await this.safeCast[`$toInt${bits}`](0)).to.be.bignumber.equal('0'); + }); + + it('downcasts 1', async function () { + expect(await this.safeCast[`$toInt${bits}`](1)).to.be.bignumber.equal('1'); + }); + + it('downcasts -1', async function () { + expect(await this.safeCast[`$toInt${bits}`](-1)).to.be.bignumber.equal('-1'); + }); + + it(`downcasts -2^${bits - 1} (${minValue})`, async function () { + expect(await this.safeCast[`$toInt${bits}`](minValue)).to.be.bignumber.equal(minValue); + }); + + it(`downcasts 2^${bits - 1} - 1 (${maxValue})`, async function () { + expect(await this.safeCast[`$toInt${bits}`](maxValue)).to.be.bignumber.equal(maxValue); + }); + + it(`reverts when downcasting -2^${bits - 1} - 1 (${minValue.subn(1)})`, async function () { + await expectRevertCustomError( + this.safeCast[`$toInt${bits}`](minValue.subn(1)), + `SafeCastOverflowedIntDowncast`, + [bits, minValue.subn(1)], + ); + }); + + it(`reverts when downcasting -2^${bits - 1} - 2 (${minValue.subn(2)})`, async function () { + await expectRevertCustomError( + this.safeCast[`$toInt${bits}`](minValue.subn(2)), + `SafeCastOverflowedIntDowncast`, + [bits, minValue.subn(2)], + ); + }); + + it(`reverts when downcasting 2^${bits - 1} (${maxValue.addn(1)})`, async function () { + await expectRevertCustomError( + this.safeCast[`$toInt${bits}`](maxValue.addn(1)), + `SafeCastOverflowedIntDowncast`, + [bits, maxValue.addn(1)], + ); + }); + + it(`reverts when downcasting 2^${bits - 1} + 1 (${maxValue.addn(2)})`, async function () { + await expectRevertCustomError( + this.safeCast[`$toInt${bits}`](maxValue.addn(2)), + `SafeCastOverflowedIntDowncast`, + [bits, maxValue.addn(2)], + ); + }); + }); + } + + range(8, 256, 8).forEach(bits => testToInt(bits)); + + describe('toInt256', () => { + const maxUint256 = new BN('2').pow(new BN(256)).subn(1); + const maxInt256 = new BN('2').pow(new BN(255)).subn(1); + + it('casts 0', async function () { + expect(await this.safeCast.$toInt256(0)).to.be.bignumber.equal('0'); + }); + + it('casts 1', async function () { + expect(await this.safeCast.$toInt256(1)).to.be.bignumber.equal('1'); + }); + + it(`casts INT256_MAX (${maxInt256})`, async function () { + expect(await this.safeCast.$toInt256(maxInt256)).to.be.bignumber.equal(maxInt256); + }); + + it(`reverts when casting INT256_MAX + 1 (${maxInt256.addn(1)})`, async function () { + await expectRevertCustomError(this.safeCast.$toInt256(maxInt256.addn(1)), 'SafeCastOverflowedUintToInt', [ + maxInt256.addn(1), + ]); + }); + + it(`reverts when casting UINT256_MAX (${maxUint256})`, async function () { + await expectRevertCustomError(this.safeCast.$toInt256(maxUint256), 'SafeCastOverflowedUintToInt', [maxUint256]); + }); + }); +}); diff --git a/test/utils/math/SignedMath.test.js b/test/utils/math/SignedMath.test.js new file mode 100644 index 000000000..c014e22ba --- /dev/null +++ b/test/utils/math/SignedMath.test.js @@ -0,0 +1,95 @@ +const { BN, constants } = require('@openzeppelin/test-helpers'); +const { expect } = require('chai'); +const { MIN_INT256, MAX_INT256 } = constants; + +const SignedMath = artifacts.require('$SignedMath'); + +contract('SignedMath', function () { + const min = new BN('-1234'); + const max = new BN('5678'); + + beforeEach(async function () { + this.math = await SignedMath.new(); + }); + + describe('max', function () { + it('is correctly detected in first argument position', async function () { + expect(await this.math.$max(max, min)).to.be.bignumber.equal(max); + }); + + it('is correctly detected in second argument position', async function () { + expect(await this.math.$max(min, max)).to.be.bignumber.equal(max); + }); + }); + + describe('min', function () { + it('is correctly detected in first argument position', async function () { + expect(await this.math.$min(min, max)).to.be.bignumber.equal(min); + }); + + it('is correctly detected in second argument position', async function () { + expect(await this.math.$min(max, min)).to.be.bignumber.equal(min); + }); + }); + + describe('average', function () { + function bnAverage(a, b) { + return a.add(b).divn(2); + } + + it('is correctly calculated with various input', async function () { + const valuesX = [ + new BN('0'), + new BN('3'), + new BN('-3'), + new BN('4'), + new BN('-4'), + new BN('57417'), + new BN('-57417'), + new BN('42304'), + new BN('-42304'), + MIN_INT256, + MAX_INT256, + ]; + + const valuesY = [ + new BN('0'), + new BN('5'), + new BN('-5'), + new BN('2'), + new BN('-2'), + new BN('57417'), + new BN('-57417'), + new BN('42304'), + new BN('-42304'), + MIN_INT256, + MAX_INT256, + ]; + + for (const x of valuesX) { + for (const y of valuesY) { + expect(await this.math.$average(x, y)).to.be.bignumber.equal( + bnAverage(x, y), + `Bad result for average(${x}, ${y})`, + ); + } + } + }); + }); + + describe('abs', function () { + for (const n of [ + MIN_INT256, + MIN_INT256.addn(1), + new BN('-1'), + new BN('0'), + new BN('1'), + MAX_INT256.subn(1), + MAX_INT256, + ]) { + it(`correctly computes the absolute value of ${n}`, async function () { + expect(await this.math.$abs(n)).to.be.bignumber.equal(n.abs()); + }); + } + }); +}); diff --git a/test/utils/structs/BitMap.test.js b/test/utils/structs/BitMap.test.js new file mode 100644 index 000000000..8a1470c5c --- /dev/null +++ b/test/utils/structs/BitMap.test.js @@ -0,0 +1,145 @@ +const { BN } = require('@openzeppelin/test-helpers'); +const { expect } = require('chai'); + +const BitMap = artifacts.require('$BitMaps'); + +contract('BitMap', function () { + const keyA = new BN('7891'); + const keyB = new BN('451'); + const keyC = new BN('9592328'); + + beforeEach(async function () { + this.bitmap = await BitMap.new(); + }); + + it('starts empty', async function () { + expect(await this.bitmap.$get(0, keyA)).to.equal(false); + expect(await this.bitmap.$get(0, keyB)).to.equal(false); + expect(await this.bitmap.$get(0, keyC)).to.equal(false); + }); + + describe('setTo', function () { + it('set a key to true', async function () { + await this.bitmap.$setTo(0, keyA, true); + expect(await this.bitmap.$get(0, keyA)).to.equal(true); + expect(await this.bitmap.$get(0, keyB)).to.equal(false); + expect(await this.bitmap.$get(0, keyC)).to.equal(false); + }); + + it('set a key to false', async function () { + await this.bitmap.$setTo(0, keyA, true); + await this.bitmap.$setTo(0, keyA, false); + expect(await this.bitmap.$get(0, keyA)).to.equal(false); + expect(await this.bitmap.$get(0, keyB)).to.equal(false); + expect(await this.bitmap.$get(0, keyC)).to.equal(false); + }); + + it('set several consecutive keys', async function () { + await this.bitmap.$setTo(0, keyA.addn(0), true); + await this.bitmap.$setTo(0, keyA.addn(1), true); + await this.bitmap.$setTo(0, keyA.addn(2), true); + await this.bitmap.$setTo(0, keyA.addn(3), true); + await this.bitmap.$setTo(0, keyA.addn(4), true); + await this.bitmap.$setTo(0, keyA.addn(2), false); + await this.bitmap.$setTo(0, keyA.addn(4), false); + expect(await this.bitmap.$get(0, keyA.addn(0))).to.equal(true); + expect(await this.bitmap.$get(0, keyA.addn(1))).to.equal(true); + expect(await this.bitmap.$get(0, keyA.addn(2))).to.equal(false); + expect(await this.bitmap.$get(0, keyA.addn(3))).to.equal(true); + expect(await this.bitmap.$get(0, keyA.addn(4))).to.equal(false); + }); + }); + + describe('set', function () { + it('adds a key', async function () { + await this.bitmap.$set(0, keyA); + expect(await this.bitmap.$get(0, keyA)).to.equal(true); + expect(await this.bitmap.$get(0, keyB)).to.equal(false); + expect(await this.bitmap.$get(0, keyC)).to.equal(false); + }); + + it('adds several keys', async function () { + await this.bitmap.$set(0, keyA); + await this.bitmap.$set(0, keyB); + expect(await this.bitmap.$get(0, keyA)).to.equal(true); + expect(await this.bitmap.$get(0, keyB)).to.equal(true); + expect(await this.bitmap.$get(0, keyC)).to.equal(false); + }); + + it('adds several consecutive keys', async function () { + await this.bitmap.$set(0, keyA.addn(0)); + await this.bitmap.$set(0, keyA.addn(1)); + await this.bitmap.$set(0, keyA.addn(3)); + expect(await this.bitmap.$get(0, keyA.addn(0))).to.equal(true); + expect(await this.bitmap.$get(0, keyA.addn(1))).to.equal(true); + expect(await this.bitmap.$get(0, keyA.addn(2))).to.equal(false); + expect(await this.bitmap.$get(0, keyA.addn(3))).to.equal(true); + expect(await this.bitmap.$get(0, keyA.addn(4))).to.equal(false); + }); + }); + + describe('unset', function () { + it('removes added keys', async function () { + await this.bitmap.$set(0, keyA); + await this.bitmap.$set(0, keyB); + await this.bitmap.$unset(0, keyA); + expect(await this.bitmap.$get(0, keyA)).to.equal(false); + expect(await this.bitmap.$get(0, keyB)).to.equal(true); + expect(await this.bitmap.$get(0, keyC)).to.equal(false); + }); + + it('removes consecutive added keys', async function () { + await this.bitmap.$set(0, keyA.addn(0)); + await this.bitmap.$set(0, keyA.addn(1)); + await this.bitmap.$set(0, keyA.addn(3)); + await this.bitmap.$unset(0, keyA.addn(1)); + expect(await this.bitmap.$get(0, keyA.addn(0))).to.equal(true); + expect(await this.bitmap.$get(0, keyA.addn(1))).to.equal(false); + expect(await this.bitmap.$get(0, keyA.addn(2))).to.equal(false); + expect(await this.bitmap.$get(0, keyA.addn(3))).to.equal(true); + expect(await this.bitmap.$get(0, keyA.addn(4))).to.equal(false); + }); + + it('adds and removes multiple keys', async function () { + // [] + + await this.bitmap.$set(0, keyA); + await this.bitmap.$set(0, keyC); + + // [A, C] + + await this.bitmap.$unset(0, keyA); + await this.bitmap.$unset(0, keyB); + + // [C] + + await this.bitmap.$set(0, keyB); + + // [C, B] + + await this.bitmap.$set(0, keyA); + await this.bitmap.$unset(0, keyC); + + // [A, B] + + await this.bitmap.$set(0, keyA); + await this.bitmap.$set(0, keyB); + + // [A, B] + + await this.bitmap.$set(0, keyC); + await this.bitmap.$unset(0, keyA); + + // [B, C] + + await this.bitmap.$set(0, keyA); + await this.bitmap.$unset(0, keyB); + + // [A, C] + + expect(await this.bitmap.$get(0, keyA)).to.equal(true); + expect(await this.bitmap.$get(0, keyB)).to.equal(false); + expect(await this.bitmap.$get(0, keyC)).to.equal(true); + }); + }); +}); diff --git a/test/utils/structs/Checkpoints.t.sol b/test/utils/structs/Checkpoints.t.sol new file mode 100644 index 000000000..7bdbcfddf --- /dev/null +++ b/test/utils/structs/Checkpoints.t.sol @@ -0,0 +1,332 @@ +// SPDX-License-Identifier: MIT +// This file was procedurally generated from scripts/generate/templates/Checkpoints.t.js. + +pragma solidity ^0.8.20; + +import {Test} from "forge-std/Test.sol"; +import {SafeCast} from "../../../contracts/utils/math/SafeCast.sol"; +import {Checkpoints} from "../../../contracts/utils/structs/Checkpoints.sol"; + +contract CheckpointsTrace224Test is Test { + using Checkpoints for Checkpoints.Trace224; + + // Maximum gap between keys used during the fuzzing tests: the `_prepareKeys` function with make sure that + // key#n+1 is in the [key#n, key#n + _KEY_MAX_GAP] range. + uint8 internal constant _KEY_MAX_GAP = 64; + + Checkpoints.Trace224 internal _ckpts; + + // helpers + function _boundUint32(uint32 x, uint32 min, uint32 max) internal view returns (uint32) { + return SafeCast.toUint32(bound(uint256(x), uint256(min), uint256(max))); + } + + function _prepareKeys(uint32[] memory keys, uint32 maxSpread) internal view { + uint32 lastKey = 0; + for (uint256 i = 0; i < keys.length; ++i) { + uint32 key = _boundUint32(keys[i], lastKey, lastKey + maxSpread); + keys[i] = key; + lastKey = key; + } + } + + function _assertLatestCheckpoint(bool exist, uint32 key, uint224 value) internal { + (bool _exist, uint32 _key, uint224 _value) = _ckpts.latestCheckpoint(); + assertEq(_exist, exist); + assertEq(_key, key); + assertEq(_value, value); + } + + // tests + function testPush(uint32[] memory keys, uint224[] memory values, uint32 pastKey) public { + vm.assume(values.length > 0 && values.length <= keys.length); + _prepareKeys(keys, _KEY_MAX_GAP); + + // initial state + assertEq(_ckpts.length(), 0); + assertEq(_ckpts.latest(), 0); + _assertLatestCheckpoint(false, 0, 0); + + uint256 duplicates = 0; + for (uint256 i = 0; i < keys.length; ++i) { + uint32 key = keys[i]; + uint224 value = values[i % values.length]; + if (i > 0 && key == keys[i - 1]) ++duplicates; + + // push + _ckpts.push(key, value); + + // check length & latest + assertEq(_ckpts.length(), i + 1 - duplicates); + assertEq(_ckpts.latest(), value); + _assertLatestCheckpoint(true, key, value); + } + + if (keys.length > 0) { + uint32 lastKey = keys[keys.length - 1]; + if (lastKey > 0) { + pastKey = _boundUint32(pastKey, 0, lastKey - 1); + + vm.expectRevert(); + this.push(pastKey, values[keys.length % values.length]); + } + } + } + + // used to test reverts + function push(uint32 key, uint224 value) external { + _ckpts.push(key, value); + } + + function testLookup(uint32[] memory keys, uint224[] memory values, uint32 lookup) public { + vm.assume(values.length > 0 && values.length <= keys.length); + _prepareKeys(keys, _KEY_MAX_GAP); + + uint32 lastKey = keys.length == 0 ? 0 : keys[keys.length - 1]; + lookup = _boundUint32(lookup, 0, lastKey + _KEY_MAX_GAP); + + uint224 upper = 0; + uint224 lower = 0; + uint32 lowerKey = type(uint32).max; + for (uint256 i = 0; i < keys.length; ++i) { + uint32 key = keys[i]; + uint224 value = values[i % values.length]; + + // push + _ckpts.push(key, value); + + // track expected result of lookups + if (key <= lookup) { + upper = value; + } + // find the first key that is not smaller than the lookup key + if (key >= lookup && (i == 0 || keys[i - 1] < lookup)) { + lowerKey = key; + } + if (key == lowerKey) { + lower = value; + } + } + + // check lookup + assertEq(_ckpts.lowerLookup(lookup), lower); + assertEq(_ckpts.upperLookup(lookup), upper); + assertEq(_ckpts.upperLookupRecent(lookup), upper); + } +} + +contract CheckpointsTrace208Test is Test { + using Checkpoints for Checkpoints.Trace208; + + // Maximum gap between keys used during the fuzzing tests: the `_prepareKeys` function with make sure that + // key#n+1 is in the [key#n, key#n + _KEY_MAX_GAP] range. + uint8 internal constant _KEY_MAX_GAP = 64; + + Checkpoints.Trace208 internal _ckpts; + + // helpers + function _boundUint48(uint48 x, uint48 min, uint48 max) internal view returns (uint48) { + return SafeCast.toUint48(bound(uint256(x), uint256(min), uint256(max))); + } + + function _prepareKeys(uint48[] memory keys, uint48 maxSpread) internal view { + uint48 lastKey = 0; + for (uint256 i = 0; i < keys.length; ++i) { + uint48 key = _boundUint48(keys[i], lastKey, lastKey + maxSpread); + keys[i] = key; + lastKey = key; + } + } + + function _assertLatestCheckpoint(bool exist, uint48 key, uint208 value) internal { + (bool _exist, uint48 _key, uint208 _value) = _ckpts.latestCheckpoint(); + assertEq(_exist, exist); + assertEq(_key, key); + assertEq(_value, value); + } + + // tests + function testPush(uint48[] memory keys, uint208[] memory values, uint48 pastKey) public { + vm.assume(values.length > 0 && values.length <= keys.length); + _prepareKeys(keys, _KEY_MAX_GAP); + + // initial state + assertEq(_ckpts.length(), 0); + assertEq(_ckpts.latest(), 0); + _assertLatestCheckpoint(false, 0, 0); + + uint256 duplicates = 0; + for (uint256 i = 0; i < keys.length; ++i) { + uint48 key = keys[i]; + uint208 value = values[i % values.length]; + if (i > 0 && key == keys[i - 1]) ++duplicates; + + // push + _ckpts.push(key, value); + + // check length & latest + assertEq(_ckpts.length(), i + 1 - duplicates); + assertEq(_ckpts.latest(), value); + _assertLatestCheckpoint(true, key, value); + } + + if (keys.length > 0) { + uint48 lastKey = keys[keys.length - 1]; + if (lastKey > 0) { + pastKey = _boundUint48(pastKey, 0, lastKey - 1); + + vm.expectRevert(); + this.push(pastKey, values[keys.length % values.length]); + } + } + } + + // used to test reverts + function push(uint48 key, uint208 value) external { + _ckpts.push(key, value); + } + + function testLookup(uint48[] memory keys, uint208[] memory values, uint48 lookup) public { + vm.assume(values.length > 0 && values.length <= keys.length); + _prepareKeys(keys, _KEY_MAX_GAP); + + uint48 lastKey = keys.length == 0 ? 0 : keys[keys.length - 1]; + lookup = _boundUint48(lookup, 0, lastKey + _KEY_MAX_GAP); + + uint208 upper = 0; + uint208 lower = 0; + uint48 lowerKey = type(uint48).max; + for (uint256 i = 0; i < keys.length; ++i) { + uint48 key = keys[i]; + uint208 value = values[i % values.length]; + + // push + _ckpts.push(key, value); + + // track expected result of lookups + if (key <= lookup) { + upper = value; + } + // find the first key that is not smaller than the lookup key + if (key >= lookup && (i == 0 || keys[i - 1] < lookup)) { + lowerKey = key; + } + if (key == lowerKey) { + lower = value; + } + } + + // check lookup + assertEq(_ckpts.lowerLookup(lookup), lower); + assertEq(_ckpts.upperLookup(lookup), upper); + assertEq(_ckpts.upperLookupRecent(lookup), upper); + } +} + +contract CheckpointsTrace160Test is Test { + using Checkpoints for Checkpoints.Trace160; + + // Maximum gap between keys used during the fuzzing tests: the `_prepareKeys` function with make sure that + // key#n+1 is in the [key#n, key#n + _KEY_MAX_GAP] range. + uint8 internal constant _KEY_MAX_GAP = 64; + + Checkpoints.Trace160 internal _ckpts; + + // helpers + function _boundUint96(uint96 x, uint96 min, uint96 max) internal view returns (uint96) { + return SafeCast.toUint96(bound(uint256(x), uint256(min), uint256(max))); + } + + function _prepareKeys(uint96[] memory keys, uint96 maxSpread) internal view { + uint96 lastKey = 0; + for (uint256 i = 0; i < keys.length; ++i) { + uint96 key = _boundUint96(keys[i], lastKey, lastKey + maxSpread); + keys[i] = key; + lastKey = key; + } + } + + function _assertLatestCheckpoint(bool exist, uint96 key, uint160 value) internal { + (bool _exist, uint96 _key, uint160 _value) = _ckpts.latestCheckpoint(); + assertEq(_exist, exist); + assertEq(_key, key); + assertEq(_value, value); + } + + // tests + function testPush(uint96[] memory keys, uint160[] memory values, uint96 pastKey) public { + vm.assume(values.length > 0 && values.length <= keys.length); + _prepareKeys(keys, _KEY_MAX_GAP); + + // initial state + assertEq(_ckpts.length(), 0); + assertEq(_ckpts.latest(), 0); + _assertLatestCheckpoint(false, 0, 0); + + uint256 duplicates = 0; + for (uint256 i = 0; i < keys.length; ++i) { + uint96 key = keys[i]; + uint160 value = values[i % values.length]; + if (i > 0 && key == keys[i - 1]) ++duplicates; + + // push + _ckpts.push(key, value); + + // check length & latest + assertEq(_ckpts.length(), i + 1 - duplicates); + assertEq(_ckpts.latest(), value); + _assertLatestCheckpoint(true, key, value); + } + + if (keys.length > 0) { + uint96 lastKey = keys[keys.length - 1]; + if (lastKey > 0) { + pastKey = _boundUint96(pastKey, 0, lastKey - 1); + + vm.expectRevert(); + this.push(pastKey, values[keys.length % values.length]); + } + } + } + + // used to test reverts + function push(uint96 key, uint160 value) external { + _ckpts.push(key, value); + } + + function testLookup(uint96[] memory keys, uint160[] memory values, uint96 lookup) public { + vm.assume(values.length > 0 && values.length <= keys.length); + _prepareKeys(keys, _KEY_MAX_GAP); + + uint96 lastKey = keys.length == 0 ? 0 : keys[keys.length - 1]; + lookup = _boundUint96(lookup, 0, lastKey + _KEY_MAX_GAP); + + uint160 upper = 0; + uint160 lower = 0; + uint96 lowerKey = type(uint96).max; + for (uint256 i = 0; i < keys.length; ++i) { + uint96 key = keys[i]; + uint160 value = values[i % values.length]; + + // push + _ckpts.push(key, value); + + // track expected result of lookups + if (key <= lookup) { + upper = value; + } + // find the first key that is not smaller than the lookup key + if (key >= lookup && (i == 0 || keys[i - 1] < lookup)) { + lowerKey = key; + } + if (key == lowerKey) { + lower = value; + } + } + + // check lookup + assertEq(_ckpts.lowerLookup(lookup), lower); + assertEq(_ckpts.upperLookup(lookup), upper); + assertEq(_ckpts.upperLookupRecent(lookup), upper); + } +} diff --git a/test/utils/structs/Checkpoints.test.js b/test/utils/structs/Checkpoints.test.js new file mode 100644 index 000000000..936ac565a --- /dev/null +++ b/test/utils/structs/Checkpoints.test.js @@ -0,0 +1,158 @@ +require('@openzeppelin/test-helpers'); + +const { expect } = require('chai'); + +const { VALUE_SIZES } = require('../../../scripts/generate/templates/Checkpoints.opts.js'); +const { expectRevertCustomError } = require('../../helpers/customError.js'); +const { expectRevert } = require('@openzeppelin/test-helpers'); + +const $Checkpoints = artifacts.require('$Checkpoints'); + +// The library name may be 'Checkpoints' or 'CheckpointsUpgradeable' +const libraryName = $Checkpoints._json.contractName.replace(/^\$/, ''); + +const first = array => (array.length ? array[0] : undefined); +const last = array => (array.length ? array[array.length - 1] : undefined); + +contract('Checkpoints', function () { + beforeEach(async function () { + this.mock = await $Checkpoints.new(); + }); + + for (const length of VALUE_SIZES) { + describe(`Trace${length}`, function () { + beforeEach(async function () { + this.methods = { + at: (...args) => this.mock.methods[`$at_${libraryName}_Trace${length}(uint256,uint32)`](0, ...args), + latest: (...args) => this.mock.methods[`$latest_${libraryName}_Trace${length}(uint256)`](0, ...args), + latestCheckpoint: (...args) => + this.mock.methods[`$latestCheckpoint_${libraryName}_Trace${length}(uint256)`](0, ...args), + length: (...args) => this.mock.methods[`$length_${libraryName}_Trace${length}(uint256)`](0, ...args), + push: (...args) => this.mock.methods[`$push(uint256,uint${256 - length},uint${length})`](0, ...args), + lowerLookup: (...args) => this.mock.methods[`$lowerLookup(uint256,uint${256 - length})`](0, ...args), + upperLookup: (...args) => this.mock.methods[`$upperLookup(uint256,uint${256 - length})`](0, ...args), + upperLookupRecent: (...args) => + this.mock.methods[`$upperLookupRecent(uint256,uint${256 - length})`](0, ...args), + }; + }); + + describe('without checkpoints', function () { + it('at zero reverts', async function () { + // Reverts with array out of bound access, which is unspecified + await expectRevert.unspecified(this.methods.at(0)); + }); + + it('returns zero as latest value', async function () { + expect(await this.methods.latest()).to.be.bignumber.equal('0'); + + const ckpt = await this.methods.latestCheckpoint(); + expect(ckpt[0]).to.be.equal(false); + expect(ckpt[1]).to.be.bignumber.equal('0'); + expect(ckpt[2]).to.be.bignumber.equal('0'); + }); + + it('lookup returns 0', async function () { + expect(await this.methods.lowerLookup(0)).to.be.bignumber.equal('0'); + expect(await this.methods.upperLookup(0)).to.be.bignumber.equal('0'); + expect(await this.methods.upperLookupRecent(0)).to.be.bignumber.equal('0'); + }); + }); + + describe('with checkpoints', function () { + beforeEach('pushing checkpoints', async function () { + this.checkpoints = [ + { key: '2', value: '17' }, + { key: '3', value: '42' }, + { key: '5', value: '101' }, + { key: '7', value: '23' }, + { key: '11', value: '99' }, + ]; + for (const { key, value } of this.checkpoints) { + await this.methods.push(key, value); + } + }); + + it('at keys', async function () { + for (const [index, { key, value }] of this.checkpoints.entries()) { + const at = await this.methods.at(index); + expect(at._value).to.be.bignumber.equal(value); + expect(at._key).to.be.bignumber.equal(key); + } + }); + + it('length', async function () { + expect(await this.methods.length()).to.be.bignumber.equal(this.checkpoints.length.toString()); + }); + + it('returns latest value', async function () { + expect(await this.methods.latest()).to.be.bignumber.equal(last(this.checkpoints).value); + + const ckpt = await this.methods.latestCheckpoint(); + expect(ckpt[0]).to.be.equal(true); + expect(ckpt[1]).to.be.bignumber.equal(last(this.checkpoints).key); + expect(ckpt[2]).to.be.bignumber.equal(last(this.checkpoints).value); + }); + + it('cannot push values in the past', async function () { + await expectRevertCustomError( + this.methods.push(last(this.checkpoints).key - 1, '0'), + 'CheckpointUnorderedInsertion', + [], + ); + }); + + it('can update last value', async function () { + const newValue = '42'; + + // check length before the update + expect(await this.methods.length()).to.be.bignumber.equal(this.checkpoints.length.toString()); + + // update last key + await this.methods.push(last(this.checkpoints).key, newValue); + expect(await this.methods.latest()).to.be.bignumber.equal(newValue); + + // check that length did not change + expect(await this.methods.length()).to.be.bignumber.equal(this.checkpoints.length.toString()); + }); + + it('lower lookup', async function () { + for (let i = 0; i < 14; ++i) { + const value = first(this.checkpoints.filter(x => i <= x.key))?.value || '0'; + + expect(await this.methods.lowerLookup(i)).to.be.bignumber.equal(value); + } + }); + + it('upper lookup & upperLookupRecent', async function () { + for (let i = 0; i < 14; ++i) { + const value = last(this.checkpoints.filter(x => i >= x.key))?.value || '0'; + + expect(await this.methods.upperLookup(i)).to.be.bignumber.equal(value); + expect(await this.methods.upperLookupRecent(i)).to.be.bignumber.equal(value); + } + }); + + it('upperLookupRecent with more than 5 checkpoints', async function () { + const moreCheckpoints = [ + { key: '12', value: '22' }, + { key: '13', value: '131' }, + { key: '17', value: '45' }, + { key: '19', value: '31452' }, + { key: '21', value: '0' }, + ]; + const allCheckpoints = [].concat(this.checkpoints, moreCheckpoints); + + for (const { key, value } of moreCheckpoints) { + await this.methods.push(key, value); + } + + for (let i = 0; i < 25; ++i) { + const value = last(allCheckpoints.filter(x => i >= x.key))?.value || '0'; + expect(await this.methods.upperLookup(i)).to.be.bignumber.equal(value); + expect(await this.methods.upperLookupRecent(i)).to.be.bignumber.equal(value); + } + }); + }); + }); + } +}); diff --git a/test/utils/structs/DoubleEndedQueue.test.js b/test/utils/structs/DoubleEndedQueue.test.js new file mode 100644 index 000000000..cbf37d76b --- /dev/null +++ b/test/utils/structs/DoubleEndedQueue.test.js @@ -0,0 +1,99 @@ +const { expectEvent } = require('@openzeppelin/test-helpers'); +const { expectRevertCustomError } = require('../../helpers/customError'); + +const DoubleEndedQueue = artifacts.require('$DoubleEndedQueue'); + +/** Rebuild the content of the deque as a JS array. */ +const getContent = deque => + deque.$length(0).then(bn => + Promise.all( + Array(bn.toNumber()) + .fill() + .map((_, i) => deque.$at(0, i)), + ), + ); + +contract('DoubleEndedQueue', function () { + const bytesA = '0xdeadbeef'.padEnd(66, '0'); + const bytesB = '0x0123456789'.padEnd(66, '0'); + const bytesC = '0x42424242'.padEnd(66, '0'); + const bytesD = '0x171717'.padEnd(66, '0'); + + beforeEach(async function () { + this.deque = await DoubleEndedQueue.new(); + }); + + describe('when empty', function () { + it('getters', async function () { + expect(await this.deque.$empty(0)).to.be.equal(true); + expect(await getContent(this.deque)).to.have.ordered.members([]); + }); + + it('reverts on accesses', async function () { + await expectRevertCustomError(this.deque.$popBack(0), 'QueueEmpty', []); + await expectRevertCustomError(this.deque.$popFront(0), 'QueueEmpty', []); + await expectRevertCustomError(this.deque.$back(0), 'QueueEmpty', []); + await expectRevertCustomError(this.deque.$front(0), 'QueueEmpty', []); + }); + }); + + describe('when not empty', function () { + beforeEach(async function () { + await this.deque.$pushBack(0, bytesB); + await this.deque.$pushFront(0, bytesA); + await this.deque.$pushBack(0, bytesC); + this.content = [bytesA, bytesB, bytesC]; + }); + + it('getters', async function () { + expect(await this.deque.$empty(0)).to.be.equal(false); + expect(await this.deque.$length(0)).to.be.bignumber.equal(this.content.length.toString()); + expect(await this.deque.$front(0)).to.be.equal(this.content[0]); + expect(await this.deque.$back(0)).to.be.equal(this.content[this.content.length - 1]); + expect(await getContent(this.deque)).to.have.ordered.members(this.content); + }); + + it('out of bounds access', async function () { + await expectRevertCustomError(this.deque.$at(0, this.content.length), 'QueueOutOfBounds', []); + }); + + describe('push', function () { + it('front', async function () { + await this.deque.$pushFront(0, bytesD); + this.content.unshift(bytesD); // add element at the beginning + + expect(await getContent(this.deque)).to.have.ordered.members(this.content); + }); + + it('back', async function () { + await this.deque.$pushBack(0, bytesD); + this.content.push(bytesD); // add element at the end + + expect(await getContent(this.deque)).to.have.ordered.members(this.content); + }); + }); + + describe('pop', function () { + it('front', async function () { + const value = this.content.shift(); // remove first element + expectEvent(await this.deque.$popFront(0), 'return$popFront', { value }); + + expect(await getContent(this.deque)).to.have.ordered.members(this.content); + }); + + it('back', async function () { + const value = this.content.pop(); // remove last element + expectEvent(await this.deque.$popBack(0), 'return$popBack', { value }); + + expect(await getContent(this.deque)).to.have.ordered.members(this.content); + }); + }); + + it('clear', async function () { + await this.deque.$clear(0); + + expect(await this.deque.$empty(0)).to.be.equal(true); + expect(await getContent(this.deque)).to.have.ordered.members([]); + }); + }); +}); diff --git a/test/utils/structs/EnumerableMap.behavior.js b/test/utils/structs/EnumerableMap.behavior.js new file mode 100644 index 000000000..67b19e39a --- /dev/null +++ b/test/utils/structs/EnumerableMap.behavior.js @@ -0,0 +1,178 @@ +const { expectEvent } = require('@openzeppelin/test-helpers'); +const { expect } = require('chai'); + +const zip = require('lodash.zip'); +const { expectRevertCustomError } = require('../../helpers/customError'); + +function shouldBehaveLikeMap(keys, values, zeroValue, methods, events) { + const [keyA, keyB, keyC] = keys; + const [valueA, valueB, valueC] = values; + + async function expectMembersMatch(map, keys, values) { + expect(keys.length).to.equal(values.length); + + await Promise.all(keys.map(async key => expect(await methods.contains(map, key)).to.equal(true))); + + expect(await methods.length(map)).to.bignumber.equal(keys.length.toString()); + + expect((await Promise.all(keys.map(key => methods.get(map, key)))).map(k => k.toString())).to.have.same.members( + values.map(value => value.toString()), + ); + + // To compare key-value pairs, we zip keys and values, and convert BNs to + // strings to workaround Chai limitations when dealing with nested arrays + expect( + await Promise.all( + [...Array(keys.length).keys()].map(async index => { + const entry = await methods.at(map, index); + return [entry[0].toString(), entry[1].toString()]; + }), + ), + ).to.have.same.deep.members( + zip( + keys.map(k => k.toString()), + values.map(v => v.toString()), + ), + ); + + // This also checks that both arrays have the same length + expect((await methods.keys(map)).map(k => k.toString())).to.have.same.members(keys.map(key => key.toString())); + } + + it('starts empty', async function () { + expect(await methods.contains(this.map, keyA)).to.equal(false); + + await expectMembersMatch(this.map, [], []); + }); + + describe('set', function () { + it('adds a key', async function () { + const receipt = await methods.set(this.map, keyA, valueA); + expectEvent(receipt, events.setReturn, { ret0: true }); + + await expectMembersMatch(this.map, [keyA], [valueA]); + }); + + it('adds several keys', async function () { + await methods.set(this.map, keyA, valueA); + await methods.set(this.map, keyB, valueB); + + await expectMembersMatch(this.map, [keyA, keyB], [valueA, valueB]); + expect(await methods.contains(this.map, keyC)).to.equal(false); + }); + + it('returns false when adding keys already in the set', async function () { + await methods.set(this.map, keyA, valueA); + + const receipt = await methods.set(this.map, keyA, valueA); + expectEvent(receipt, events.setReturn, { ret0: false }); + + await expectMembersMatch(this.map, [keyA], [valueA]); + }); + + it('updates values for keys already in the set', async function () { + await methods.set(this.map, keyA, valueA); + await methods.set(this.map, keyA, valueB); + + await expectMembersMatch(this.map, [keyA], [valueB]); + }); + }); + + describe('remove', function () { + it('removes added keys', async function () { + await methods.set(this.map, keyA, valueA); + + const receipt = await methods.remove(this.map, keyA); + expectEvent(receipt, events.removeReturn, { ret0: true }); + + expect(await methods.contains(this.map, keyA)).to.equal(false); + await expectMembersMatch(this.map, [], []); + }); + + it('returns false when removing keys not in the set', async function () { + const receipt = await methods.remove(this.map, keyA); + expectEvent(receipt, events.removeReturn, { ret0: false }); + + expect(await methods.contains(this.map, keyA)).to.equal(false); + }); + + it('adds and removes multiple keys', async function () { + // [] + + await methods.set(this.map, keyA, valueA); + await methods.set(this.map, keyC, valueC); + + // [A, C] + + await methods.remove(this.map, keyA); + await methods.remove(this.map, keyB); + + // [C] + + await methods.set(this.map, keyB, valueB); + + // [C, B] + + await methods.set(this.map, keyA, valueA); + await methods.remove(this.map, keyC); + + // [A, B] + + await methods.set(this.map, keyA, valueA); + await methods.set(this.map, keyB, valueB); + + // [A, B] + + await methods.set(this.map, keyC, valueC); + await methods.remove(this.map, keyA); + + // [B, C] + + await methods.set(this.map, keyA, valueA); + await methods.remove(this.map, keyB); + + // [A, C] + + await expectMembersMatch(this.map, [keyA, keyC], [valueA, valueC]); + + expect(await methods.contains(this.map, keyA)).to.equal(true); + expect(await methods.contains(this.map, keyB)).to.equal(false); + expect(await methods.contains(this.map, keyC)).to.equal(true); + }); + }); + + describe('read', function () { + beforeEach(async function () { + await methods.set(this.map, keyA, valueA); + }); + + describe('get', function () { + it('existing value', async function () { + expect(await methods.get(this.map, keyA).then(r => r.toString())).to.be.equal(valueA.toString()); + }); + it('missing value', async function () { + const key = web3.utils.toHex(keyB); + await expectRevertCustomError(methods.get(this.map, keyB), 'EnumerableMapNonexistentKey', [ + key.length == 66 ? key : web3.utils.padLeft(key, 64, '0'), + ]); + }); + }); + + describe('tryGet', function () { + it('existing value', async function () { + const result = await methods.tryGet(this.map, keyA); + expect(result['0']).to.be.equal(true); + expect(result['1'].toString()).to.be.equal(valueA.toString()); + }); + it('missing value', async function () { + const result = await methods.tryGet(this.map, keyB); + expect(result['0']).to.be.equal(false); + expect(result['1'].toString()).to.be.equal(zeroValue.toString()); + }); + }); + }); +} + +module.exports = { + shouldBehaveLikeMap, +}; diff --git a/test/utils/structs/EnumerableMap.test.js b/test/utils/structs/EnumerableMap.test.js new file mode 100644 index 000000000..545e12a4f --- /dev/null +++ b/test/utils/structs/EnumerableMap.test.js @@ -0,0 +1,149 @@ +const { BN, constants } = require('@openzeppelin/test-helpers'); +const { mapValues } = require('../../helpers/iterate'); + +const EnumerableMap = artifacts.require('$EnumerableMap'); + +const { shouldBehaveLikeMap } = require('./EnumerableMap.behavior'); + +const getMethods = ms => { + return mapValues( + ms, + m => + (self, ...args) => + self.methods[m](0, ...args), + ); +}; + +// Get the name of the library. In the transpiled code it will be EnumerableMapUpgradeable. +const library = EnumerableMap._json.contractName.replace(/^\$/, ''); + +contract('EnumerableMap', function (accounts) { + const [accountA, accountB, accountC] = accounts; + + const keyA = new BN('7891'); + const keyB = new BN('451'); + const keyC = new BN('9592328'); + + const bytesA = '0xdeadbeef'.padEnd(66, '0'); + const bytesB = '0x0123456789'.padEnd(66, '0'); + const bytesC = '0x42424242'.padEnd(66, '0'); + + beforeEach(async function () { + this.map = await EnumerableMap.new(); + }); + + // AddressToUintMap + describe('AddressToUintMap', function () { + shouldBehaveLikeMap( + [accountA, accountB, accountC], + [keyA, keyB, keyC], + new BN('0'), + getMethods({ + set: '$set(uint256,address,uint256)', + get: '$get(uint256,address)', + tryGet: '$tryGet(uint256,address)', + remove: '$remove(uint256,address)', + length: `$length_${library}_AddressToUintMap(uint256)`, + at: `$at_${library}_AddressToUintMap(uint256,uint256)`, + contains: '$contains(uint256,address)', + keys: `$keys_${library}_AddressToUintMap(uint256)`, + }), + { + setReturn: `return$set_${library}_AddressToUintMap_address_uint256`, + removeReturn: `return$remove_${library}_AddressToUintMap_address`, + }, + ); + }); + + // UintToAddressMap + describe('UintToAddressMap', function () { + shouldBehaveLikeMap( + [keyA, keyB, keyC], + [accountA, accountB, accountC], + constants.ZERO_ADDRESS, + getMethods({ + set: '$set(uint256,uint256,address)', + get: `$get_${library}_UintToAddressMap(uint256,uint256)`, + tryGet: `$tryGet_${library}_UintToAddressMap(uint256,uint256)`, + remove: `$remove_${library}_UintToAddressMap(uint256,uint256)`, + length: `$length_${library}_UintToAddressMap(uint256)`, + at: `$at_${library}_UintToAddressMap(uint256,uint256)`, + contains: `$contains_${library}_UintToAddressMap(uint256,uint256)`, + keys: `$keys_${library}_UintToAddressMap(uint256)`, + }), + { + setReturn: `return$set_${library}_UintToAddressMap_uint256_address`, + removeReturn: `return$remove_${library}_UintToAddressMap_uint256`, + }, + ); + }); + + // Bytes32ToBytes32Map + describe('Bytes32ToBytes32Map', function () { + shouldBehaveLikeMap( + [keyA, keyB, keyC].map(k => '0x' + k.toString(16).padEnd(64, '0')), + [bytesA, bytesB, bytesC], + constants.ZERO_BYTES32, + getMethods({ + set: '$set(uint256,bytes32,bytes32)', + get: `$get_${library}_Bytes32ToBytes32Map(uint256,bytes32)`, + tryGet: `$tryGet_${library}_Bytes32ToBytes32Map(uint256,bytes32)`, + remove: `$remove_${library}_Bytes32ToBytes32Map(uint256,bytes32)`, + length: `$length_${library}_Bytes32ToBytes32Map(uint256)`, + at: `$at_${library}_Bytes32ToBytes32Map(uint256,uint256)`, + contains: `$contains_${library}_Bytes32ToBytes32Map(uint256,bytes32)`, + keys: `$keys_${library}_Bytes32ToBytes32Map(uint256)`, + }), + { + setReturn: `return$set_${library}_Bytes32ToBytes32Map_bytes32_bytes32`, + removeReturn: `return$remove_${library}_Bytes32ToBytes32Map_bytes32`, + }, + ); + }); + + // UintToUintMap + describe('UintToUintMap', function () { + shouldBehaveLikeMap( + [keyA, keyB, keyC], + [keyA, keyB, keyC].map(k => k.add(new BN('1332'))), + new BN('0'), + getMethods({ + set: '$set(uint256,uint256,uint256)', + get: `$get_${library}_UintToUintMap(uint256,uint256)`, + tryGet: `$tryGet_${library}_UintToUintMap(uint256,uint256)`, + remove: `$remove_${library}_UintToUintMap(uint256,uint256)`, + length: `$length_${library}_UintToUintMap(uint256)`, + at: `$at_${library}_UintToUintMap(uint256,uint256)`, + contains: `$contains_${library}_UintToUintMap(uint256,uint256)`, + keys: `$keys_${library}_UintToUintMap(uint256)`, + }), + { + setReturn: `return$set_${library}_UintToUintMap_uint256_uint256`, + removeReturn: `return$remove_${library}_UintToUintMap_uint256`, + }, + ); + }); + + // Bytes32ToUintMap + describe('Bytes32ToUintMap', function () { + shouldBehaveLikeMap( + [bytesA, bytesB, bytesC], + [keyA, keyB, keyC], + new BN('0'), + getMethods({ + set: '$set(uint256,bytes32,uint256)', + get: `$get_${library}_Bytes32ToUintMap(uint256,bytes32)`, + tryGet: `$tryGet_${library}_Bytes32ToUintMap(uint256,bytes32)`, + remove: `$remove_${library}_Bytes32ToUintMap(uint256,bytes32)`, + length: `$length_${library}_Bytes32ToUintMap(uint256)`, + at: `$at_${library}_Bytes32ToUintMap(uint256,uint256)`, + contains: `$contains_${library}_Bytes32ToUintMap(uint256,bytes32)`, + keys: `$keys_${library}_Bytes32ToUintMap(uint256)`, + }), + { + setReturn: `return$set_${library}_Bytes32ToUintMap_bytes32_uint256`, + removeReturn: `return$remove_${library}_Bytes32ToUintMap_bytes32`, + }, + ); + }); +}); diff --git a/test/utils/structs/EnumerableSet.behavior.js b/test/utils/structs/EnumerableSet.behavior.js new file mode 100644 index 000000000..f80eb8169 --- /dev/null +++ b/test/utils/structs/EnumerableSet.behavior.js @@ -0,0 +1,129 @@ +const { expectEvent, expectRevert } = require('@openzeppelin/test-helpers'); +const { expect } = require('chai'); + +function shouldBehaveLikeSet(values, methods, events) { + const [valueA, valueB, valueC] = values; + + async function expectMembersMatch(set, values) { + const contains = await Promise.all(values.map(value => methods.contains(set, value))); + expect(contains.every(Boolean)).to.be.equal(true); + + const length = await methods.length(set); + expect(length).to.bignumber.equal(values.length.toString()); + + // To compare values we convert to strings to workaround Chai + // limitations when dealing with nested arrays (required for BNs) + const indexedValues = await Promise.all( + Array(values.length) + .fill() + .map((_, index) => methods.at(set, index)), + ); + expect(indexedValues.map(v => v.toString())).to.have.same.members(values.map(v => v.toString())); + + const returnedValues = await methods.values(set); + expect(returnedValues.map(v => v.toString())).to.have.same.members(values.map(v => v.toString())); + } + + it('starts empty', async function () { + expect(await methods.contains(this.set, valueA)).to.equal(false); + + await expectMembersMatch(this.set, []); + }); + + describe('add', function () { + it('adds a value', async function () { + const receipt = await methods.add(this.set, valueA); + expectEvent(receipt, events.addReturn, { ret0: true }); + + await expectMembersMatch(this.set, [valueA]); + }); + + it('adds several values', async function () { + await methods.add(this.set, valueA); + await methods.add(this.set, valueB); + + await expectMembersMatch(this.set, [valueA, valueB]); + expect(await methods.contains(this.set, valueC)).to.equal(false); + }); + + it('returns false when adding values already in the set', async function () { + await methods.add(this.set, valueA); + + const receipt = await methods.add(this.set, valueA); + expectEvent(receipt, events.addReturn, { ret0: false }); + + await expectMembersMatch(this.set, [valueA]); + }); + }); + + describe('at', function () { + it('reverts when retrieving non-existent elements', async function () { + await expectRevert.unspecified(methods.at(this.set, 0)); + }); + }); + + describe('remove', function () { + it('removes added values', async function () { + await methods.add(this.set, valueA); + + const receipt = await methods.remove(this.set, valueA); + expectEvent(receipt, events.removeReturn, { ret0: true }); + + expect(await methods.contains(this.set, valueA)).to.equal(false); + await expectMembersMatch(this.set, []); + }); + + it('returns false when removing values not in the set', async function () { + const receipt = await methods.remove(this.set, valueA); + expectEvent(receipt, events.removeReturn, { ret0: false }); + + expect(await methods.contains(this.set, valueA)).to.equal(false); + }); + + it('adds and removes multiple values', async function () { + // [] + + await methods.add(this.set, valueA); + await methods.add(this.set, valueC); + + // [A, C] + + await methods.remove(this.set, valueA); + await methods.remove(this.set, valueB); + + // [C] + + await methods.add(this.set, valueB); + + // [C, B] + + await methods.add(this.set, valueA); + await methods.remove(this.set, valueC); + + // [A, B] + + await methods.add(this.set, valueA); + await methods.add(this.set, valueB); + + // [A, B] + + await methods.add(this.set, valueC); + await methods.remove(this.set, valueA); + + // [B, C] + + await methods.add(this.set, valueA); + await methods.remove(this.set, valueB); + + // [A, C] + + await expectMembersMatch(this.set, [valueA, valueC]); + + expect(await methods.contains(this.set, valueB)).to.equal(false); + }); + }); +} + +module.exports = { + shouldBehaveLikeSet, +}; diff --git a/test/utils/structs/EnumerableSet.test.js b/test/utils/structs/EnumerableSet.test.js new file mode 100644 index 000000000..a1840257b --- /dev/null +++ b/test/utils/structs/EnumerableSet.test.js @@ -0,0 +1,79 @@ +const EnumerableSet = artifacts.require('$EnumerableSet'); +const { mapValues } = require('../../helpers/iterate'); + +const { shouldBehaveLikeSet } = require('./EnumerableSet.behavior'); + +const getMethods = ms => { + return mapValues( + ms, + m => + (self, ...args) => + self.methods[m](0, ...args), + ); +}; + +// Get the name of the library. In the transpiled code it will be EnumerableSetUpgradeable. +const library = EnumerableSet._json.contractName.replace(/^\$/, ''); + +contract('EnumerableSet', function (accounts) { + beforeEach(async function () { + this.set = await EnumerableSet.new(); + }); + + // Bytes32Set + describe('EnumerableBytes32Set', function () { + shouldBehaveLikeSet( + ['0xdeadbeef', '0x0123456789', '0x42424242'].map(e => e.padEnd(66, '0')), + getMethods({ + add: '$add(uint256,bytes32)', + remove: '$remove(uint256,bytes32)', + contains: '$contains(uint256,bytes32)', + length: `$length_${library}_Bytes32Set(uint256)`, + at: `$at_${library}_Bytes32Set(uint256,uint256)`, + values: `$values_${library}_Bytes32Set(uint256)`, + }), + { + addReturn: `return$add_${library}_Bytes32Set_bytes32`, + removeReturn: `return$remove_${library}_Bytes32Set_bytes32`, + }, + ); + }); + + // AddressSet + describe('EnumerableAddressSet', function () { + shouldBehaveLikeSet( + accounts, + getMethods({ + add: '$add(uint256,address)', + remove: '$remove(uint256,address)', + contains: '$contains(uint256,address)', + length: `$length_${library}_AddressSet(uint256)`, + at: `$at_${library}_AddressSet(uint256,uint256)`, + values: `$values_${library}_AddressSet(uint256)`, + }), + { + addReturn: `return$add_${library}_AddressSet_address`, + removeReturn: `return$remove_${library}_AddressSet_address`, + }, + ); + }); + + // UintSet + describe('EnumerableUintSet', function () { + shouldBehaveLikeSet( + [1234, 5678, 9101112].map(e => web3.utils.toBN(e)), + getMethods({ + add: '$add(uint256,uint256)', + remove: '$remove(uint256,uint256)', + contains: '$contains(uint256,uint256)', + length: `$length_${library}_UintSet(uint256)`, + at: `$at_${library}_UintSet(uint256,uint256)`, + values: `$values_${library}_UintSet(uint256)`, + }), + { + addReturn: `return$add_${library}_UintSet_uint256`, + removeReturn: `return$remove_${library}_UintSet_uint256`, + }, + ); + }); +}); diff --git a/test/utils/types/Time.test.js b/test/utils/types/Time.test.js new file mode 100644 index 000000000..614911738 --- /dev/null +++ b/test/utils/types/Time.test.js @@ -0,0 +1,140 @@ +require('@openzeppelin/test-helpers'); + +const { expect } = require('chai'); +const { clock } = require('../../helpers/time'); +const { product, max } = require('../../helpers/iterate'); + +const Time = artifacts.require('$Time'); + +const MAX_UINT32 = 1n << (32n - 1n); +const MAX_UINT48 = 1n << (48n - 1n); +const SOME_VALUES = [0n, 1n, 2n, 15n, 16n, 17n, 42n]; + +const asUint = (value, size) => { + if (typeof value != 'bigint') { + value = BigInt(value); + } + // chai does not support bigint :/ + if (value < 0 || value >= 1n << BigInt(size)) { + throw new Error(`value is not a valid uint${size}`); + } + return value; +}; + +const unpackDelay = delay => ({ + valueBefore: (asUint(delay, 112) >> 32n) % (1n << 32n), + valueAfter: (asUint(delay, 112) >> 0n) % (1n << 32n), + effect: (asUint(delay, 112) >> 64n) % (1n << 48n), +}); + +const packDelay = ({ valueBefore, valueAfter = 0n, effect = 0n }) => + (asUint(valueAfter, 32) << 0n) + (asUint(valueBefore, 32) << 32n) + (asUint(effect, 48) << 64n); + +const effectSamplesForTimepoint = timepoint => [ + 0n, + timepoint, + ...product([-1n, 1n], [1n, 2n, 17n, 42n]) + .map(([sign, shift]) => timepoint + sign * shift) + .filter(effect => effect > 0n && effect <= MAX_UINT48), + MAX_UINT48, +]; + +contract('Time', function () { + beforeEach(async function () { + this.mock = await Time.new(); + }); + + describe('clocks', function () { + it('timestamp', async function () { + expect(await this.mock.$timestamp()).to.be.bignumber.equal(web3.utils.toBN(await clock.timestamp())); + }); + + it('block number', async function () { + expect(await this.mock.$blockNumber()).to.be.bignumber.equal(web3.utils.toBN(await clock.blocknumber())); + }); + }); + + describe('Delay', function () { + describe('packing and unpacking', function () { + const valueBefore = 17n; + const valueAfter = 42n; + const effect = 69n; + const delay = 1272825341158973505578n; + + it('pack', async function () { + const packed = await this.mock.$pack(valueBefore, valueAfter, effect); + expect(packed).to.be.bignumber.equal(delay.toString()); + + const packed2 = packDelay({ valueBefore, valueAfter, effect }); + expect(packed2).to.be.equal(delay); + }); + + it('unpack', async function () { + const unpacked = await this.mock.$unpack(delay); + expect(unpacked[0]).to.be.bignumber.equal(valueBefore.toString()); + expect(unpacked[1]).to.be.bignumber.equal(valueAfter.toString()); + expect(unpacked[2]).to.be.bignumber.equal(effect.toString()); + + const unpacked2 = unpackDelay(delay); + expect(unpacked2).to.be.deep.equal({ valueBefore, valueAfter, effect }); + }); + }); + + it('toDelay', async function () { + for (const value of [...SOME_VALUES, MAX_UINT32]) { + const delay = await this.mock.$toDelay(value).then(unpackDelay); + expect(delay).to.be.deep.equal({ valueBefore: 0n, valueAfter: value, effect: 0n }); + } + }); + + it('get & getFull', async function () { + const timepoint = await clock.timestamp().then(BigInt); + const valueBefore = 24194n; + const valueAfter = 4214143n; + + for (const effect of effectSamplesForTimepoint(timepoint)) { + const isPast = effect <= timepoint; + + const delay = packDelay({ valueBefore, valueAfter, effect }); + + expect(await this.mock.$get(delay)).to.be.bignumber.equal(String(isPast ? valueAfter : valueBefore)); + + const result = await this.mock.$getFull(delay); + expect(result[0]).to.be.bignumber.equal(String(isPast ? valueAfter : valueBefore)); + expect(result[1]).to.be.bignumber.equal(String(isPast ? 0n : valueAfter)); + expect(result[2]).to.be.bignumber.equal(String(isPast ? 0n : effect)); + } + }); + + it('withUpdate', async function () { + const timepoint = await clock.timestamp().then(BigInt); + const valueBefore = 24194n; + const valueAfter = 4214143n; + const newvalueAfter = 94716n; + + for (const effect of effectSamplesForTimepoint(timepoint)) + for (const minSetback of [...SOME_VALUES, MAX_UINT32]) { + const isPast = effect <= timepoint; + const expectedvalueBefore = isPast ? valueAfter : valueBefore; + const expectedSetback = max(minSetback, expectedvalueBefore - newvalueAfter, 0n); + + const result = await this.mock.$withUpdate( + packDelay({ valueBefore, valueAfter, effect }), + newvalueAfter, + minSetback, + ); + + expect(result[0]).to.be.bignumber.equal( + String( + packDelay({ + valueBefore: expectedvalueBefore, + valueAfter: newvalueAfter, + effect: timepoint + expectedSetback, + }), + ), + ); + expect(result[1]).to.be.bignumber.equal(String(timepoint + expectedSetback)); + } + }); + }); +});

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 z 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�%Y5@MSyC#8E-c4W=h3xls!eWGApPoE(_giI^5 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