From 99dce60a97bf44a36d001741bf5bd8f84ecd3f3f Mon Sep 17 00:00:00 2001 From: lash Date: Sat, 11 Feb 2023 04:53:46 +0000 Subject: [PATCH 01/10] Bump dep --- python/requirements.txt | 2 +- python/setup.cfg | 2 +- solidity/Writer.sol | 5 +++++ 3 files changed, 7 insertions(+), 2 deletions(-) diff --git a/python/requirements.txt b/python/requirements.txt index 9524fb0..b5b2195 100644 --- a/python/requirements.txt +++ b/python/requirements.txt @@ -1 +1 @@ -chainlib-eth>=0.1.0b1,<0.2.0 +chainlib-eth~=0.4.7 diff --git a/python/setup.cfg b/python/setup.cfg index aade670..a6b900d 100644 --- a/python/setup.cfg +++ b/python/setup.cfg @@ -1,6 +1,6 @@ [metadata] name = cic-contracts -version = 0.1.0 +version = 0.2.0 description = CIC network smart contract interfaces author = Louis Holbrook author_email = dev@holbrook.no diff --git a/solidity/Writer.sol b/solidity/Writer.sol index f362499..5972570 100644 --- a/solidity/Writer.sol +++ b/solidity/Writer.sol @@ -5,6 +5,11 @@ pragma solidity >=0.6.12; // File-version: 1 interface Writer { + event WriterAdded(address _writer); + event WriterRemoved(address _writer); + function addWriter(address _writer) external returns (bool); function deleteWriter(address _writer) external returns (bool); + function isWriter(address _writer) external returns (bool); + function writers(uint256 _idx) external view returns (address); } From 0f2cc2d232684d271a20a7bac48fb0a10775ca4c Mon Sep 17 00:00:00 2001 From: lash Date: Tue, 21 Mar 2023 20:46:08 +0000 Subject: [PATCH 02/10] Update interfaces to current implenentations --- python/MANIFEST.in | 1 + solidity/AccountsIndex.sol | 19 +++++++++++++++---- solidity/Burner.sol | 14 ++++++++++++++ solidity/ERC173.sol | 4 ++-- solidity/ERC20.sol | 3 +-- solidity/ERC721.sol | 5 +++-- solidity/Expire.sol | 11 +++++++++++ solidity/Faucet.sol | 21 +++++++++++---------- solidity/Locator.sol | 13 +++++++++++++ solidity/Msg.sol | 17 +++++++++++++++++ solidity/Registry.sol | 3 +-- solidity/RegistryClient.sol | 3 ++- solidity/Writer.sol | 7 +++---- 13 files changed, 94 insertions(+), 27 deletions(-) create mode 100644 python/MANIFEST.in create mode 100644 solidity/Burner.sol create mode 100644 solidity/Expire.sol create mode 100644 solidity/Locator.sol create mode 100644 solidity/Msg.sol diff --git a/python/MANIFEST.in b/python/MANIFEST.in new file mode 100644 index 0000000..ea97a42 --- /dev/null +++ b/python/MANIFEST.in @@ -0,0 +1 @@ +include *requirements* diff --git a/solidity/AccountsIndex.sol b/solidity/AccountsIndex.sol index 1d77c02..dd74c20 100644 --- a/solidity/AccountsIndex.sol +++ b/solidity/AccountsIndex.sol @@ -2,7 +2,7 @@ pragma solidity >=0.6.12; // Author: Louis Holbrook 0826EDA1702D1E87C6E2875121D2E7BB88C2A746 // SPDX-License-Identifier: GPL-3.0-or-later -// File-version: 3 +// File-version: 4 interface AddressIndex { event AddressAdded(address indexed addedAccount, uint256 indexed accountIndex); // AccountsIndex @@ -10,9 +10,20 @@ interface AddressIndex { // Return number of entries in index function entryCount() external view returns (uint256); // Return entry at the spceificed index + // Will revert if index is beyond array length. function entry(uint256) external view returns (address); - // Add an entry to the index - function add(address _account) external returns (bool); + // Add an entry to the index. Incresases the entry count. + function add(address) external returns (bool); + // Remove an entry from the index. Reduces the entry count. + function remove(address) external returns (bool); // Verify that the entry exists in the index - function have(address _account) external view returns (bool); + function have(address) external view returns (bool); + // Deactivate account but keep in index. Does not affect entry count. + function deactivate(address) external returns (bool); + // Activate previously deactivated account. Does not affect entry count. + function activate(address) external returns (bool); + // Check if account exists and is active; + function isActive(address) external view returns (bool); + // Retrieve the timestamp when account was added + function time(address) external view returns (uint256); } diff --git a/solidity/Burner.sol b/solidity/Burner.sol new file mode 100644 index 0000000..1f4b6c5 --- /dev/null +++ b/solidity/Burner.sol @@ -0,0 +1,14 @@ +pragma solidity >=0.6.12; + +// Author: Louis Holbrook 0826EDA1702D1E87C6E2875121D2E7BB88C2A746 +// SPDX-License-Identifier: GPL-3.0-or-later +// File-version: 2 + +interface Burner { + event Burn(uint256 _burned); + + function burn(uint256 _burn) external returns (bool); + function totalBurned() external returns (uint256); + function totalMinted() external returns (uint256); +} + diff --git a/solidity/ERC173.sol b/solidity/ERC173.sol index 4fc19a7..b64e530 100644 --- a/solidity/ERC173.sol +++ b/solidity/ERC173.sol @@ -1,4 +1,4 @@ -pragma solidity ^0.8.0; +pragma solidity >=0.6.12; // Author: Louis Holbrook 0826EDA1702D1E87C6E2875121D2E7BB88C2A746 // SPDX-License-Identifier: GPL-3.0-or-later @@ -9,7 +9,7 @@ pragma solidity ^0.8.0; // - sha256:45e14ac315e380b5372a5ffc6783ab11d7eafb7fa5a123e0b8e5fc8c6c527c4c // - swarmhash:0cadf6a7122d2da20dbab0ef31c692b1b24cf49ae5c1c80f7ce6dbae8885ce01 interface ERC173 { - event OwnershipTransferred(address indexed previousOwner, address indexed newOwner); // EIP173 + event OwnershipTransferred(address indexed previousOwner, address indexed newOwner); function owner() external view returns (address); function transferOwnership(address _newOwner) external view returns (bool); diff --git a/solidity/ERC20.sol b/solidity/ERC20.sol index bbaf767..08bd8cd 100644 --- a/solidity/ERC20.sol +++ b/solidity/ERC20.sol @@ -2,7 +2,7 @@ pragma solidity >=0.6.12; // Author: Louis Holbrook 0826EDA1702D1E87C6E2875121D2E7BB88C2A746 // SPDX-License-Identifier: GPL-3.0-or-later -// File-version: 1 +// File-version: 2 // This is a representation of an officially approved Ethereum Improvement Proposal, written by Fabian Vogelsteller fabian@ethereum.org, Vitalik Buterin vitalik.buterin@ethereum.org. It was released under the CC0 license. // The proposal source used as reference was a Markdown file with the following digests: @@ -10,7 +10,6 @@ pragma solidity >=0.6.12; // - swarmhash:598f13429ec42f50d7a6576ab20feffdaf2135a90805678d24e4ea297bf0e639 interface ERC20 { event Transfer(address indexed _from, address indexed _to, uint256 _value); - event TransferFrom(address indexed _from, address indexed _to, address indexed _spender, uint256 _value); event Approval(address indexed _owner, address indexed _spender, uint256 _value); function transfer(address _to, uint256 _value) external returns (bool); diff --git a/solidity/ERC721.sol b/solidity/ERC721.sol index 41fda4a..419c47c 100644 --- a/solidity/ERC721.sol +++ b/solidity/ERC721.sol @@ -2,7 +2,7 @@ pragma solidity >=0.6.12; // Author: Louis Holbrook 0826EDA1702D1E87C6E2875121D2E7BB88C2A746 // SPDX-License-Identifier: GPL-3.0-or-later -// File-version: 1 +// File-version: 2 // This is a representation of an officially approved Ethereum Improvement Proposal, William Entriken (@fulldecent), Dieter Shirley dete@axiomzen.co, Jacob Evans jacob@dekz.net, Nastassia Sachs nastassia.sachs@protonmail.com // The proposal source used as reference was a Markdown file with the following digests: @@ -15,7 +15,8 @@ interface ERC721 { function balanceOf(address _owner) external view returns (uint256); function ownerOf(uint256 _tokenId) external view returns (address); - function safeTransferFrom(address _from, address _to, uint256 _tokenId, bytes memory data) external payable; + function safeTransferFrom(address _from, address _to, uint256 _tokenId) external payable; + function safeTransferFrom(address _from, address _to, uint256 _tokenId, bytes memory _data) external payable; function transferFrom(address _from, address _to, uint256 _tokenId) external payable; function approve(address _approved, uint256 _tokenId) external payable; function setApprovalForAll(address _operator, bool _approved) external; diff --git a/solidity/Expire.sol b/solidity/Expire.sol new file mode 100644 index 0000000..639bad0 --- /dev/null +++ b/solidity/Expire.sol @@ -0,0 +1,11 @@ +pragma solidity >=0.6.12; + +// Author: Louis Holbrook 0826EDA1702D1E87C6E2875121D2E7BB88C2A746 +// SPDX-License-Identifier: GPL-3.0-or-later +// File-version: 2 + +interface Expire { + event Expired(uint256 _timestamp); + + function expires() external returns (uint256); +} diff --git a/solidity/Faucet.sol b/solidity/Faucet.sol index 63234f9..dd2394b 100644 --- a/solidity/Faucet.sol +++ b/solidity/Faucet.sol @@ -2,22 +2,23 @@ pragma solidity >=0.6.12; // Author: Louis Holbrook 0826EDA1702D1E87C6E2875121D2E7BB88C2A746 // SPDX-License-Identifier: GPL-3.0-or-later -// File-version: 5 +// File-version: 6 interface Faucet { - event FaucetUsed(address indexed _recipient, address indexed _token, uint256 _value); - event FaucetFail(address indexed _recipient, address indexed _token, uint256 _value); + event Give(address indexed _recipient, address indexed _token, uint256 _value); event FaucetAmountChange(uint256 _value); // Address of token the faucet represents + // The faucet will return gas tokens with the zero-address is returned. function token() external returns (address); // Amount of tokens the faucet gives out function tokenAmount() external returns (uint256); - // Set the amount of tokens that the faucet gives out - function setAmount(uint256 _amount) external returns (bool); - // Give tokens to the given recipient - function giveTo(address _recipient) external returns (bool); - // Number of blocks that must be mined until faucet can be used for the same address - // max uint (-1) can be used to indicate that faucet may not be reused - function cooldown(address _recipient) external returns (uint256); + // Give tokens to the given recipient. Returns amount of tokens given. + function giveTo(address _recipient) external returns (uint256); + // Give tokens to yourself. Returns amount of tokens given. + function gimme() external returns (uint256); + // Returns timestamp when faucet may be used again by _recipient + // If 0 is returned, the address has not yet been used. + // A return value of max(uint256) indicates that the faucet may not be used again. + function nextTime(address _recipient) external returns (uint256); } diff --git a/solidity/Locator.sol b/solidity/Locator.sol new file mode 100644 index 0000000..41ba756 --- /dev/null +++ b/solidity/Locator.sol @@ -0,0 +1,13 @@ +pragma solidity >=0.6.12; + +// Author: Louis Holbrook 0826EDA1702D1E87C6E2875121D2E7BB88C2A746 +// SPDX-License-Identifier: GPL-3.0-or-later +// File-version: 3 + +interface Locator { + // URI that may or may not point to a specific resource location + function toURI(bytes memory _data) external view returns (string memory); + + // URL pointing to a specific resource location + function toURL(bytes memory _data) external view returns(string memory); +} diff --git a/solidity/Msg.sol b/solidity/Msg.sol new file mode 100644 index 0000000..24c409d --- /dev/null +++ b/solidity/Msg.sol @@ -0,0 +1,17 @@ +pragma solidity >=0.6.12; + +// Author: Louis Holbrook 0826EDA1702D1E87C6E2875121D2E7BB88C2A746 +// SPDX-License-Identifier: GPL-3.0-or-later +// File-version: 1 + +interface Message { + // Emitted when a new message digest has been set + // Should not be emitted if the digest set is identical to the previous + event Msg(bytes _msgDigest); + + // Set a new message content hash + function setMsg(bytes memory _digest) external; + + // Get the current message content hash + function getMsg() external view returns(bytes memory); +} diff --git a/solidity/Registry.sol b/solidity/Registry.sol index ce43238..0010285 100644 --- a/solidity/Registry.sol +++ b/solidity/Registry.sol @@ -2,10 +2,9 @@ pragma solidity >=0.6.12; // Author: Louis Holbrook 0826EDA1702D1E87C6E2875121D2E7BB88C2A746 // SPDX-License-Identifier: GPL-3.0-or-later -// File-version: 1 +// File-version: 2 interface Registry { function set(bytes32, address) external returns (bool); function bind(bytes32, bytes32) external returns (bool); - function identifiers(uint256) external view returns (bytes32); } diff --git a/solidity/RegistryClient.sol b/solidity/RegistryClient.sol index cd1fd6f..cf68d2e 100644 --- a/solidity/RegistryClient.sol +++ b/solidity/RegistryClient.sol @@ -2,8 +2,9 @@ pragma solidity >=0.6.12; // Author: Louis Holbrook 0826EDA1702D1E87C6E2875121D2E7BB88C2A746 // SPDX-License-Identifier: GPL-3.0-or-later -// File-version: 3 +// File-version: 2 interface RegistryClient { function addressOf(bytes32) external view returns (address); + function identifiers(uint256) external view returns (bytes32); } diff --git a/solidity/Writer.sol b/solidity/Writer.sol index 5972570..a1bc006 100644 --- a/solidity/Writer.sol +++ b/solidity/Writer.sol @@ -2,14 +2,13 @@ pragma solidity >=0.6.12; // Author: Louis Holbrook 0826EDA1702D1E87C6E2875121D2E7BB88C2A746 // SPDX-License-Identifier: GPL-3.0-or-later -// File-version: 1 +// File-version: 2 interface Writer { - event WriterAdded(address _writer); - event WriterRemoved(address _writer); + event WriterAdded(address indexed _executor, address _writer); + event WriterDeleted(address indexed _executor, address _writer); function addWriter(address _writer) external returns (bool); function deleteWriter(address _writer) external returns (bool); function isWriter(address _writer) external returns (bool); - function writers(uint256 _idx) external view returns (address); } From 8507f202e71a37f723218a233e0b7a9af6e0b3c6 Mon Sep 17 00:00:00 2001 From: lash Date: Fri, 24 Mar 2023 11:05:21 +0000 Subject: [PATCH 03/10] Update declarator to include topic --- VERSION | 2 +- solidity/Declarator.sol | 10 +++++++--- solidity/ERC165.sol | 13 ------------- solidity/ERC173.sol | 16 ---------------- solidity/ERC20.sol | 24 ------------------------ solidity/ERC721.sol | 25 ------------------------- solidity/ERC721Enumerable.sol | 15 --------------- solidity/ERC721Metadata.sol | 15 --------------- solidity/ERC721Receiver.sol | 13 ------------- solidity/Locator.sol | 13 ------------- solidity/Msg.sol | 17 ----------------- 11 files changed, 8 insertions(+), 155 deletions(-) delete mode 100644 solidity/ERC165.sol delete mode 100644 solidity/ERC173.sol delete mode 100644 solidity/ERC20.sol delete mode 100644 solidity/ERC721.sol delete mode 100644 solidity/ERC721Enumerable.sol delete mode 100644 solidity/ERC721Metadata.sol delete mode 100644 solidity/ERC721Receiver.sol delete mode 100644 solidity/Locator.sol delete mode 100644 solidity/Msg.sol diff --git a/VERSION b/VERSION index bbdeab6..0ea3a94 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -0.0.5 +0.2.0 diff --git a/solidity/Declarator.sol b/solidity/Declarator.sol index 4b4e6a5..b2eb42e 100644 --- a/solidity/Declarator.sol +++ b/solidity/Declarator.sol @@ -2,19 +2,23 @@ pragma solidity >=0.6.12; // Author: Louis Holbrook 0826EDA1702D1E87C6E2875121D2E7BB88C2A746 // SPDX-License-Identifier: GPL-3.0-or-later -// File-version: 2 +// File-version: 3 interface Declarator { - event DeclarationAdded(address _declarator, address _subject, bytes32 _proof); + event DeclarationAdded(address indexed _declarator, address indexed _subject, bytes32 indexed _topic, bytes32 _proof); - // Get all declarations for a subject signed by a declarator + // Get all declarations for a subject (without topic) signed by a declarator function declaration(address _declarator, address _subject) external view returns ( bytes32[] memory ); + // Get all declarations for a subject for the given topic signed by a declarator + function declaration(address _declarator, address _subject, bytes32 _topic) external view returns ( bytes32[] memory ); // Get number of declarations the declarator has ever signed function declarationCount(address _declarator) external view returns ( uint256 ); // Get the subject of a declarator's declarations at the specific index function declarationAddressAt(address _declarator, uint256 _idx) external view returns ( address ); // Add a declaration for the subject function addDeclaration(address _subject, bytes32 _proof) external returns ( bool ); + // Add a declaration with topic for the subject + function addDeclaration(address _subject, bytes32 _proof, bytes32 _topic) external returns ( bool ); // Get the declarator that signed a declaration at the specificed index for a subject function declaratorAddressAt(address _subject, uint256 _idx) external view returns ( address ); // Get the number of declarators that have signed for a subject diff --git a/solidity/ERC165.sol b/solidity/ERC165.sol deleted file mode 100644 index 47d29dc..0000000 --- a/solidity/ERC165.sol +++ /dev/null @@ -1,13 +0,0 @@ -pragma solidity ^0.8.0; - -// Author: Louis Holbrook 0826EDA1702D1E87C6E2875121D2E7BB88C2A746 -// SPDX-License-Identifier: GPL-3.0-or-later -// File-version: 2 - -// This is a representation of an officially approved Ethereum Improvement Proposal, written by Christian Reitwießner chris@ethereum.org, Nick Johnson nick@ethereum.org, Fabian Vogelsteller fabian@lukso.network, Jordi Baylina jordi@baylina.cat, Konrad Feldmeier konrad.feldmeier@brainbot.com and William Entriken github.com@phor.net. It was released under the CC0 license. -// The proposal source used as reference was a Markdown file with the following digests: -// - sha256:2fc8534206e1e5b7abbb9db21fa5b83d39c51b2dabad441a356b7d18320bfc51 -// - swarmhash:a1a2860be878a818a9207503fbbe49cdbd86c3e02a4fdac0a4faafa78f6bdd80 -interface ERC165 { - function supportsInterface(bytes4 _sum) external pure returns (bool); -} diff --git a/solidity/ERC173.sol b/solidity/ERC173.sol deleted file mode 100644 index b64e530..0000000 --- a/solidity/ERC173.sol +++ /dev/null @@ -1,16 +0,0 @@ -pragma solidity >=0.6.12; - -// Author: Louis Holbrook 0826EDA1702D1E87C6E2875121D2E7BB88C2A746 -// SPDX-License-Identifier: GPL-3.0-or-later -// File-version: 2 - -// This is a representation of an officially approved Ethereum Improvement Proposal, written by Nick Mudge and Dan Finlay and released under the CC0 license. -// The proposal source used as reference was a Markdown file with the following digests: -// - sha256:45e14ac315e380b5372a5ffc6783ab11d7eafb7fa5a123e0b8e5fc8c6c527c4c -// - swarmhash:0cadf6a7122d2da20dbab0ef31c692b1b24cf49ae5c1c80f7ce6dbae8885ce01 -interface ERC173 { - event OwnershipTransferred(address indexed previousOwner, address indexed newOwner); - - function owner() external view returns (address); - function transferOwnership(address _newOwner) external view returns (bool); -} diff --git a/solidity/ERC20.sol b/solidity/ERC20.sol deleted file mode 100644 index 08bd8cd..0000000 --- a/solidity/ERC20.sol +++ /dev/null @@ -1,24 +0,0 @@ -pragma solidity >=0.6.12; - -// Author: Louis Holbrook 0826EDA1702D1E87C6E2875121D2E7BB88C2A746 -// SPDX-License-Identifier: GPL-3.0-or-later -// File-version: 2 - -// This is a representation of an officially approved Ethereum Improvement Proposal, written by Fabian Vogelsteller fabian@ethereum.org, Vitalik Buterin vitalik.buterin@ethereum.org. It was released under the CC0 license. -// The proposal source used as reference was a Markdown file with the following digests: -// - sha256:d120f321f2bef19596a401fba86d13352693ccd39645c2bbc84ffb3ed551388f -// - swarmhash:598f13429ec42f50d7a6576ab20feffdaf2135a90805678d24e4ea297bf0e639 -interface ERC20 { - event Transfer(address indexed _from, address indexed _to, uint256 _value); - event Approval(address indexed _owner, address indexed _spender, uint256 _value); - - function transfer(address _to, uint256 _value) external returns (bool); - function transferFrom(address _from, address _to, uint256 _value) external returns (bool); - function approve(address _spender, uint256 _value) external returns (bool); - function name() external view returns (string memory); - function symbol() external view returns (string memory); - function decimals() external view returns (uint256); - function totalSupply() external view returns (uint256); - function allowance(address _owner, address _spender) external view returns(uint256); - function balanceOf(address _holder) external view returns (uint256); -} diff --git a/solidity/ERC721.sol b/solidity/ERC721.sol deleted file mode 100644 index 419c47c..0000000 --- a/solidity/ERC721.sol +++ /dev/null @@ -1,25 +0,0 @@ -pragma solidity >=0.6.12; - -// Author: Louis Holbrook 0826EDA1702D1E87C6E2875121D2E7BB88C2A746 -// SPDX-License-Identifier: GPL-3.0-or-later -// File-version: 2 - -// This is a representation of an officially approved Ethereum Improvement Proposal, William Entriken (@fulldecent), Dieter Shirley dete@axiomzen.co, Jacob Evans jacob@dekz.net, Nastassia Sachs nastassia.sachs@protonmail.com -// The proposal source used as reference was a Markdown file with the following digests: -// - sha256:f25b41ad1bff14ec57e8c247f2ecf372fd86245d08ba3cbd005c21a42744a7ca -// - swarmhash:cf43d96b21b0b017ae32fb2ac8df9268f13344d9fd20aa1d959453eaf379a51b -interface ERC721 { - event Transfer(address indexed _from, address indexed _to, uint256 indexed _tokenId); - event Approval(address indexed _owner, address indexed _approved, uint256 indexed _tokenId); - event ApprovalForAll(address indexed _owner, address indexed _operator, bool _approved); - - function balanceOf(address _owner) external view returns (uint256); - function ownerOf(uint256 _tokenId) external view returns (address); - function safeTransferFrom(address _from, address _to, uint256 _tokenId) external payable; - function safeTransferFrom(address _from, address _to, uint256 _tokenId, bytes memory _data) external payable; - function transferFrom(address _from, address _to, uint256 _tokenId) external payable; - function approve(address _approved, uint256 _tokenId) external payable; - function setApprovalForAll(address _operator, bool _approved) external; - function getApproved(uint256 _tokenId) external view returns (address); - function isApprovedForAll(address _owner, address _operator) external view returns (bool); -} diff --git a/solidity/ERC721Enumerable.sol b/solidity/ERC721Enumerable.sol deleted file mode 100644 index 1377a0c..0000000 --- a/solidity/ERC721Enumerable.sol +++ /dev/null @@ -1,15 +0,0 @@ -pragma solidity >=0.6.12; - -// Author: Louis Holbrook 0826EDA1702D1E87C6E2875121D2E7BB88C2A746 -// SPDX-License-Identifier: GPL-3.0-or-later -// File-version: 1 - -// This is a representation of an officially approved Ethereum Improvement Proposal, William Entriken (@fulldecent), Dieter Shirley dete@axiomzen.co, Jacob Evans jacob@dekz.net, Nastassia Sachs nastassia.sachs@protonmail.com -// The proposal source used as reference was a Markdown file with the following digests: -// - sha256:f25b41ad1bff14ec57e8c247f2ecf372fd86245d08ba3cbd005c21a42744a7ca -// - swarmhash:cf43d96b21b0b017ae32fb2ac8df9268f13344d9fd20aa1d959453eaf379a51b -interface ERC721Enumerable { - function totalSupply() external view returns (uint256); - function tokenByIndex(uint256 _index) external view returns (uint256); - function tokenOfOwnerByIndex(address _owner, uint256 _index) external view returns (uint256); -} diff --git a/solidity/ERC721Metadata.sol b/solidity/ERC721Metadata.sol deleted file mode 100644 index 5f6f97c..0000000 --- a/solidity/ERC721Metadata.sol +++ /dev/null @@ -1,15 +0,0 @@ -pragma solidity >=0.6.12; - -// Author: Louis Holbrook 0826EDA1702D1E87C6E2875121D2E7BB88C2A746 -// SPDX-License-Identifier: GPL-3.0-or-later -// File-version: 1 - -// This is a representation of an officially approved Ethereum Improvement Proposal, William Entriken (@fulldecent), Dieter Shirley dete@axiomzen.co, Jacob Evans jacob@dekz.net, Nastassia Sachs nastassia.sachs@protonmail.com -// The proposal source used as reference was a Markdown file with the following digests: -// - sha256:f25b41ad1bff14ec57e8c247f2ecf372fd86245d08ba3cbd005c21a42744a7ca -// - swarmhash:cf43d96b21b0b017ae32fb2ac8df9268f13344d9fd20aa1d959453eaf379a51b -interface ERC721Metadata { - function name() external view returns (string memory _name); - function symbol() external view returns (string memory _symbol); - function tokenURI(uint256 _tokenId) external view returns (string memory); -} diff --git a/solidity/ERC721Receiver.sol b/solidity/ERC721Receiver.sol deleted file mode 100644 index 32d9261..0000000 --- a/solidity/ERC721Receiver.sol +++ /dev/null @@ -1,13 +0,0 @@ -pragma solidity >=0.6.12; - -// Author: Louis Holbrook 0826EDA1702D1E87C6E2875121D2E7BB88C2A746 -// SPDX-License-Identifier: GPL-3.0-or-later -// File-version: 1 - -// This is a representation of an officially approved Ethereum Improvement Proposal, William Entriken (@fulldecent), Dieter Shirley dete@axiomzen.co, Jacob Evans jacob@dekz.net, Nastassia Sachs nastassia.sachs@protonmail.com -// The proposal source used as reference was a Markdown file with the following digests: -// - sha256:f25b41ad1bff14ec57e8c247f2ecf372fd86245d08ba3cbd005c21a42744a7ca -// - swarmhash:cf43d96b21b0b017ae32fb2ac8df9268f13344d9fd20aa1d959453eaf379a51b -interface ERC721Receiver { - function onERC721Received(address _operator, address _from, uint256 _tokenId, bytes memory _data) external returns(bytes4); -} diff --git a/solidity/Locator.sol b/solidity/Locator.sol deleted file mode 100644 index 41ba756..0000000 --- a/solidity/Locator.sol +++ /dev/null @@ -1,13 +0,0 @@ -pragma solidity >=0.6.12; - -// Author: Louis Holbrook 0826EDA1702D1E87C6E2875121D2E7BB88C2A746 -// SPDX-License-Identifier: GPL-3.0-or-later -// File-version: 3 - -interface Locator { - // URI that may or may not point to a specific resource location - function toURI(bytes memory _data) external view returns (string memory); - - // URL pointing to a specific resource location - function toURL(bytes memory _data) external view returns(string memory); -} diff --git a/solidity/Msg.sol b/solidity/Msg.sol deleted file mode 100644 index 24c409d..0000000 --- a/solidity/Msg.sol +++ /dev/null @@ -1,17 +0,0 @@ -pragma solidity >=0.6.12; - -// Author: Louis Holbrook 0826EDA1702D1E87C6E2875121D2E7BB88C2A746 -// SPDX-License-Identifier: GPL-3.0-or-later -// File-version: 1 - -interface Message { - // Emitted when a new message digest has been set - // Should not be emitted if the digest set is identical to the previous - event Msg(bytes _msgDigest); - - // Set a new message content hash - function setMsg(bytes memory _digest) external; - - // Get the current message content hash - function getMsg() external view returns(bytes memory); -} From 0877fe776980a95bc050e60152cf4904813bc0d5 Mon Sep 17 00:00:00 2001 From: lash Date: Sat, 25 Mar 2023 11:14:46 +0000 Subject: [PATCH 04/10] Embed solidity code, interfaces in documentation --- Makefile | 15 +++++- doc/texinfo/accountsindex.sol.texi | 18 +++++++ doc/texinfo/burner.sol.texi | 14 ++++++ doc/texinfo/declarator.sol.texi | 20 ++++++++ doc/texinfo/expire.sol.texi | 13 +++++ doc/texinfo/faucet.sol.texi | 39 +++++++++++++++ doc/texinfo/locator.sol.texi | 58 ++++++++++++++++++++++ doc/texinfo/minter.sol.texi | 14 ++++++ doc/texinfo/msg.sol.texi | 15 ++++++ doc/texinfo/multihash.sol.texi | 25 ++++++++++ doc/texinfo/old.texi | 59 ++++++++++++++++++++++ doc/texinfo/overview.texi | 80 ++++++++++++------------------ doc/texinfo/registry.sol.texi | 23 +++++++++ doc/texinfo/writer.sol.texi | 25 ++++++++++ solidity/AccountsIndex.sol | 17 +++++-- solidity/Burner.sol | 18 +++++-- solidity/Declarator.sol | 9 +++- solidity/Expire.sol | 2 + solidity/Faucet.sol | 15 ++++++ solidity/Locator.sol | 13 +++++ solidity/Minter.sol | 9 +++- solidity/Msg.sol | 14 ++++++ solidity/MultiHash.sol | 22 ++++++++ solidity/Registry.sol | 4 +- solidity/RegistryClient.sol | 10 +++- solidity/Writer.sol | 8 +++ texify.sh | 10 ++++ 27 files changed, 507 insertions(+), 62 deletions(-) create mode 100644 doc/texinfo/accountsindex.sol.texi create mode 100644 doc/texinfo/burner.sol.texi create mode 100644 doc/texinfo/declarator.sol.texi create mode 100644 doc/texinfo/expire.sol.texi create mode 100644 doc/texinfo/faucet.sol.texi create mode 100644 doc/texinfo/locator.sol.texi create mode 100644 doc/texinfo/minter.sol.texi create mode 100644 doc/texinfo/msg.sol.texi create mode 100644 doc/texinfo/multihash.sol.texi create mode 100644 doc/texinfo/old.texi create mode 100644 doc/texinfo/registry.sol.texi create mode 100644 doc/texinfo/writer.sol.texi create mode 100644 solidity/Locator.sol create mode 100644 solidity/Msg.sol create mode 100644 solidity/MultiHash.sol create mode 100644 texify.sh diff --git a/Makefile b/Makefile index 5a3db6a..b0bd8cf 100644 --- a/Makefile +++ b/Makefile @@ -19,14 +19,25 @@ PREFIX = /usr/local/share/cic/solidity/abi .sol.interface: bash to_interface.sh $(basename $@).sol > $@ -all: $(OUTPUTS) +all: outs doc + +outs: $(OUTPUTS) echo $(OUTPUTS) -install: $(OUTPUTS) +install-code: $(OUTPUTS) install -vDm0644 -t $(PREFIX) $? +install-doc: + bash texify.sh + +install: outs install-code install-doc doc + clean: rm -vf solidity/*.json rm -vf solidity/*.interface +doc: + bash texify.sh + make -C doc/texinfo + .PHONY: clean install diff --git a/doc/texinfo/accountsindex.sol.texi b/doc/texinfo/accountsindex.sol.texi new file mode 100644 index 0000000..52b7a8e --- /dev/null +++ b/doc/texinfo/accountsindex.sol.texi @@ -0,0 +1,18 @@ +@subsection Accounts Index + +Account address membership list. + +Records time when account was added. + +Addresses may be @emph{added}, @emph{removed}, aswell as @emph{deactivated} and @emph{activated}. Deactivated accounts still count towards the @code{entryCount}. + +The @code{entry} method is used to iterate the account list. The order of which accounts are returned is not guaranteed. Any returned value matching @code{address(0x00)} should be skipped, and not counted towards @code{entryCount}. + +@table @dfn +@item ERC165 Interface identifier +@include ../../build/AccountsIndex.interface +@item Solidity interface definition +@include ../../build/contract_AccountsIndex.texi +@item Reference implementation +@uref{git://holbrook.no/eth-accounts-index.git,} +@end table diff --git a/doc/texinfo/burner.sol.texi b/doc/texinfo/burner.sol.texi new file mode 100644 index 0000000..1c8d23f --- /dev/null +++ b/doc/texinfo/burner.sol.texi @@ -0,0 +1,14 @@ +@subsection Burner + +Attached to @code{ERC20} and @code{ERC721} tokens that may be @emph{burned}. + +Implements the @code{burn(...)} part of @code{ERC5679} for interoperability. + +@table @dfn +@item ERC165 Interface identifier +@include ../../build/Burner.interface +@item Solidity interface definition +@include ../../build/contract_Burner.texi +@item Example implementation +@uref{https://git.grassecon.net/cicnet/erc20-demurrage-token.git} +@end table diff --git a/doc/texinfo/declarator.sol.texi b/doc/texinfo/declarator.sol.texi new file mode 100644 index 0000000..9e6b0f5 --- /dev/null +++ b/doc/texinfo/declarator.sol.texi @@ -0,0 +1,20 @@ +@subsection Declarator + +Permissionless store of signed claims made by an address about other addresses, or addresses about themselves. + +It is used to declare or respond to certifications of vouchers, NFT, voucher members. + +Addresses may be Externally Owned Accounts or smart contracts. + +Claims may be made with or without topics. A missing topic is synonymous with a topic valud of @code{bytes32(0x00)}. + +Any number of claims can be made about an address under any number of topics. All claims must be stored, and returned in the order which they were added. + +@table @dfn +@item ERC165 Interface identifier +@include ../../build/Declarator.interface +@item Solidity interface definition +@include ../../build/contract_Declarator.texi +@item Reference implementation +@uref{git://holbrook.no/eth-address-index.git,} +@end table diff --git a/doc/texinfo/expire.sol.texi b/doc/texinfo/expire.sol.texi new file mode 100644 index 0000000..132bddf --- /dev/null +++ b/doc/texinfo/expire.sol.texi @@ -0,0 +1,13 @@ +@subsection Expire + +Defines a token contract that may not be used after a certain time. + +A contract defining an expiry @emph{must not} allow changing the expiration time to a time in the past. + + +@table @dfn +@item ERC165 Interface identifier +@include ../../build/Expire.interface +@item Solidity interface definition +@include ../../build/contract_Expire.texi +@end table diff --git a/doc/texinfo/faucet.sol.texi b/doc/texinfo/faucet.sol.texi new file mode 100644 index 0000000..92acab3 --- /dev/null +++ b/doc/texinfo/faucet.sol.texi @@ -0,0 +1,39 @@ +@subsection Faucet + +Used for dispensing tokens to any address. + +It can be used for gas tokens and @emph{ERC20} alike. + +The interface is the same whether the faucet is dispensing from existing balance or minting new tokens. + +The value dispersed @emph{must} be the same for all addresses. + +In general, four criteria are expected to exist in any combination for limiting access to the faucet: + +@table @dfn +@item Time +A recipient may only use the faucet again after some time has passed. +@item Balance threshold +A recipient may only use the faucet after its balance is below a certain amount. +@item Membership +A recipient may only use the faucet if it has been added to an access control list. +@item Capacity +The contract has sufficient token funds to dispense the current defined amount to dispense. +@end table + +The @emph{check(address)} contract call @emph{must} evaluate all four criteria, and @emph{must} return @code{false} if any of the criteria are not met. + + +@table @dfn +@item ERC165 Interface identifier +@include ../../build/Faucet.interface +@item Solidity interface definition +@include ../../build/contract_Faucet.texi +@item Reference implementations +@itemize +@item +@uref{git://holbrook.no/erc20-faucet.git,} +@item +@uref{git://holbrook.no/eth-faucet.git,} +@end itemize +@end table diff --git a/doc/texinfo/locator.sol.texi b/doc/texinfo/locator.sol.texi new file mode 100644 index 0000000..ac746ff --- /dev/null +++ b/doc/texinfo/locator.sol.texi @@ -0,0 +1,58 @@ +@subsection Locator + +This interface supports @code{ERC721 Metadata}, in particular the @code{tokenURI(uint256)} call. + +Off-chain resources in the CIC network @emph{must} be defined in terms of content addressed strings. + +It @emph{must} be possible to refer to all off-chain resources directly by the content address. + +Furthermore, it @emph{should} be possible to refer to a resource by a fully-qualified location on the web or an overlay network (e.g. tor). + +@table @dfn +@item ERC165 Interface identifier +@include ../../build/Locator.interface +@item Solidity interface definition +@include ../../build/contract_Locator.texi +@end table + + +@subsubsection Expressing locators in terms of numetic token id + +Given the numeric token id @code{1234567890987654321}, and a base url @code{https://contentgateway.grassecon.net}, the result of the methods may be as follows: + +@table @code +@item toURI(000000000000000000000000000000000000000000000000112210f4b16c1cb1) +-> @code{https://contentgateway.grassecon.net/000000000000000000000000000000000000000000000000112210f4b16c1cb1} +@item toURL(000000000000000000000000000000000000000000000000112210f4b16c1cb1) +-> @code{https://contentgateway.grassecon.net/000000000000000000000000000000000000000000000000112210f4b16c1cb1} +@item tokenURI(1234567890987654321) +-> @code{https://contentgateway.grassecon.net/000000000000000000000000000000000000000000000000112210f4b16c1cb1} +@end table + + +@subsubsection Expressing locators in terms of a digest + +Given the data @code{foo}, the digest algorithm @code{sha256} and a base url @code{https://contentgateway.grassecon.net}, the result of the methods may be as follows: + +@table @code +@item toURI(sha256(foo)) +-> @code{"sha256:2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae"} +@item toURL(sha256(foo)) +-> @code{"https://contentgateway.grassecon.net/2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae"} +@item tokenURI(toUint(sha256(foo))) +-> @code{"https://contentgateway.grassecon.net/2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae"} +@end table + + +@subsubsection Locator without URL + +Given the data @code{foo}, the digest algorithm @code{sha256} and no base url, the result of the methods may be as follows: + +@table @code +@item toURI(sha256(foo)) +-> @code{"sha256:2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae"} +@item toURL(sha256(foo)) +-> @code{""} +@item tokenURI(toUint(sha256(foo))) +-> @code{"sha256:2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae"} +@end table diff --git a/doc/texinfo/minter.sol.texi b/doc/texinfo/minter.sol.texi new file mode 100644 index 0000000..31fdbb9 --- /dev/null +++ b/doc/texinfo/minter.sol.texi @@ -0,0 +1,14 @@ +@subsection Minter + +Attached to @code{ERC20} and @code{ERC721} tokens that may be minted. + +Implements the @code{mint(...)} and @code{safeMint(...)} parts of @code{ERC5679} for interoperability. + +@table @dfn +@item ERC165 Interface identifier +@include ../../build/Minter.interface +@item Solidity interface definition +@include ../../build/contract_Minter.texi +@item Example implementation +@uref{https://git.grassecon.net/cicnet/erc20-demurrage-token.git} +@end table diff --git a/doc/texinfo/msg.sol.texi b/doc/texinfo/msg.sol.texi new file mode 100644 index 0000000..787b383 --- /dev/null +++ b/doc/texinfo/msg.sol.texi @@ -0,0 +1,15 @@ +@subsection Msg + +Enables a reference "message" to describe the contract using an off-chain resource. + +The reference may or may not be mutable. + +The interface complements @code{Locator} and @code{MultiHash} to generate locators for how to resolve the reference. + + +@table @dfn +@item ERC165 Interface identifier +@include ../../build/Msg.interface +@item Solidity interface definition +@include ../../build/contract_Msg.texi +@end table diff --git a/doc/texinfo/multihash.sol.texi b/doc/texinfo/multihash.sol.texi new file mode 100644 index 0000000..24e5609 --- /dev/null +++ b/doc/texinfo/multihash.sol.texi @@ -0,0 +1,25 @@ +@subsection Multihash + +A complement to @code{Locator}, enabling validation and generation for multihashes that have been registered to the contract. + + +@table @dfn +@item ERC165 Interface identifier +@include ../../build/MultiHash.interface +@item Solidity interface definition +@include ../../build/contract_MultiHash.texi +@end table + + +@subsubsection Using @code{Multihash} with @code{Locator} + +Given the data @code{foo}, the digest algorithm @code{sha256} (multihash prefix @code{1220}) and a base url @code{https://contentgateway.grassecon.net}, the result of the methods may be as follows: + +@table @code +@item toURI(sha256(foo)) +-> @code{"sha256:2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae"} +@item toURL(sha256(foo)) +-> @code{"https://contentgateway.grassecon.net/12202c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae"} +@item tokenURI(toUint(sha256(foo))) +-> @code{"https://contentgateway.grassecon.net/12202c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae"} +@end table diff --git a/doc/texinfo/old.texi b/doc/texinfo/old.texi new file mode 100644 index 0000000..c9d3a64 --- /dev/null +++ b/doc/texinfo/old.texi @@ -0,0 +1,59 @@ +@subsection Auxiliary contracts + +All other Smart Contracts in the network other than CICRegistry are essentially optional, and each applies @emph{at least one} the interfaces defined in the @code{cic-contracts} repository. + + +@subsection Contract interfaces + +All contracts interfaces also implement the @strong{EIP165} Standard Interface Detection. + + +@subsubsection Registry + +A key-value store, which resolves arbitrary 32-byte pointers to Ethereum addresses. Typically, this is used to resolve an address from a well-known identifier, either as a UTF-8 value or a 256-bit hash. + +It also provides numerical index access to all registered values in order of insertion. + + +@subsubsection Registry Client + +A subset of the @code{Registry} interface, which defines only the non-transactional methods of the contract. The @code{Registry Client} interface is implemented by the @code{CICRegistry} contract. + + +@subsubsection Faucet + +Enables disbursement of a set amount of tokens to a requesting address. + +Allows privileged accounts to adjust the amount of tokens to disburse. + +Can be implemented as a periodic or a one-time service per account. + + +@subsubsection Transfer approval + +Enables a third-party approval to spend an ERC20 token allowance. + +This is useful in the case of a custodial key store, where a transaction has been initiated by another entity than the owner of the key. + +The contract allows the third-party address to either allow or reject the transfer. + + +@subsubsection Declarator + +Stores one or more 32-byte entries as a description of an Ethereum address, @emph{signed} by another Ethereum address. + +This can be used to @emph{describe} network resources, be it tokens, contracts or user accounts. Examples of uses are KYC documentation proofs for users, token metadata used for display, or fraud alerts. + +Entries are stored by the transacting address that adds address/description pairs. In other words, any address may have different "opinions" registered about it, depending on which signing address it is queried in the context of. This, in turn, allows the quering entity to compile its own "opinion" of an address by combining data from signatures it trusts. + +Entries typically are text strings or content hashes. + + +@subsubsection Address Index + +A simple append-only list of addresses. Used to check whether an address is part of a particular group. + + +@subsubsection DEX Index + +Methods required to convert between tokens. diff --git a/doc/texinfo/overview.texi b/doc/texinfo/overview.texi index c2e5ce5..d4c541d 100644 --- a/doc/texinfo/overview.texi +++ b/doc/texinfo/overview.texi @@ -2,75 +2,59 @@ @chapter Smart contract interfaces -@section Smart Contracts in the CIC Network -@subsection Technology +@section Technology -The long-term aim of the CIC network is to be agnostic of consensus engines. However, since we have to start @emph{somewhere}, the current state of development only deals with Smart Contracts on the (Ethereum Virtual Machine (EVM). +CIC smart contracts are implemented using the @emph{solidity} programming language for the (Ethereum Virtual Machine (EVM). -@subsection The registry contract +@section Inherited ERC definitions -The CICRegistry contract defines the entry-point to the entire CIC network. All other CIC network resources can be discovered through this contract. +@subsection Direct use -Its implementation is contained in the @file{cic-registry} repository. Details about it are documented further in that section. +The following well-known solidity interfaces are used directly. -@subsection Auxiliary contracts - -All other Smart Contracts in the network other than CICRegistry are essentially optional, and each applies @emph{at least one} the interfaces defined in the @code{cic-contracts} repository. +@itemize @bullet +@item +@uref{https://eips.ethereum.org/EIPS/eip-20, ERC20 - Token Standard} +@item +@uref{https://eips.ethereum.org/EIPS/eip-165, ERC165 - Standard Interface Detection} +@item +@uref{https://eips.ethereum.org/EIPS/eip-173, ERC173 - Contract Ownership Standard} +@item +@uref{https://eips.ethereum.org/EIPS/eip-721, ERC721 - Non-Fungible Token Standard} +@end itemize -@subsection Contract interfaces +@subsection Extended ERC definitions -All contracts interfaces also implement the @strong{EIP165} Standard Interface Detection. +@itemize @dfn +@item +@uref{https://eips.ethereum.org/EIPS/eip-5679, ERC5679 - Token Minting and Burning} (See @code{Minter}, @code{Burner}) +@end itemize -@subsubsection Registry +@section Native implementations -A key-value store, which resolves arbitrary 32-byte pointers to Ethereum addresses. Typically, this is used to resolve an address from a well-known identifier, either as a UTF-8 value or a 256-bit hash. +@include accountsindex.sol.texi -It also provides numerical index access to all registered values in order of insertion. +@include burner.sol.texi +@include declarator.sol.texi -@subsubsection Registry Client +@include expire.sol.texi -A subset of the @code{Registry} interface, which defines only the non-transactional methods of the contract. The @code{Registry Client} interface is implemented by the @code{CICRegistry} contract. +@include faucet.sol.texi +@include locator.sol.texi -@subsubsection Faucet +@include minter.sol.texi -Enables disbursement of a set amount of tokens to a requesting address. +@include msg.sol.texi -Allows privileged accounts to adjust the amount of tokens to disburse. +@include multihash.sol.texi -Can be implemented as a periodic or a one-time service per account. +@include registry.sol.texi +@include writer.sol.texi -@subsubsection Transfer approval - -Enables a third-party approval to spend an ERC20 token allowance. - -This is useful in the case of a custodial key store, where a transaction has been initiated by another entity than the owner of the key. - -The contract allows the third-party address to either allow or reject the transfer. - - -@subsubsection Declarator - -Stores one or more 32-byte entries as a description of an Ethereum address, @emph{signed} by another Ethereum address. - -This can be used to @emph{describe} network resources, be it tokens, contracts or user accounts. Examples of uses are KYC documentation proofs for users, token metadata used for display, or fraud alerts. - -Entries are stored by the transacting address that adds address/description pairs. In other words, any address may have different "opinions" registered about it, depending on which signing address it is queried in the context of. This, in turn, allows the quering entity to compile its own "opinion" of an address by combining data from signatures it trusts. - -Entries typically are text strings or content hashes. - - -@subsubsection Address Index - -A simple append-only list of addresses. Used to check whether an address is part of a particular group. - - -@subsubsection DEX Index - -Methods required to convert between tokens. diff --git a/doc/texinfo/registry.sol.texi b/doc/texinfo/registry.sol.texi new file mode 100644 index 0000000..9c0c02c --- /dev/null +++ b/doc/texinfo/registry.sol.texi @@ -0,0 +1,23 @@ +@subsection Registry + +The Registry interface is a key-value store resolving well-known contract identifier names to contract addresses. + +It currently has two distinct uses in the CIC context: + +@enumerate +@item +Entry-point to discover all relevant contracts of CIC networks. +@item +Unique (ERC20) token symbol resolver. +@end enumerate + +@table @dfn +@item ERC165 Interface identifier +@include ../../build/RegistryClient.interface +@item Solidity interface definition +@include ../../build/contract_RegistryClient.texi +@item Reference implementation +@uref{git://holbrook.no/eth-contract-registry.git,} +@item Token index implementation +@uref{git://holbrook.no/eth-contract-registry.git,} +@end table diff --git a/doc/texinfo/writer.sol.texi b/doc/texinfo/writer.sol.texi new file mode 100644 index 0000000..1e794aa --- /dev/null +++ b/doc/texinfo/writer.sol.texi @@ -0,0 +1,25 @@ +@subsection Writer + +A complement to ERC173, which allows definition of a class of super-users for a contract. + +Typically, a super-user address may perform @emph{more} actions than a "normal" address, aswell as @emph{some} actions normally limited to the @emph{contract owner}. + +Typically, only the @emph{contract owner} can add or remove a super-user. + +Some use-case examples of super-user actions include: + +@itemize +@item +Mint new tokens. +@item +Change the amount dispensed by the faucet. +@item +Edit access control lists. +@end itemize + +@table @dfn +@item ERC165 Interface identifier +@include ../../build/Writer.interface +@item Solidity interface definition +@include ../../build/contract_Writer.texi +@end table diff --git a/solidity/AccountsIndex.sol b/solidity/AccountsIndex.sol index dd74c20..2d86250 100644 --- a/solidity/AccountsIndex.sol +++ b/solidity/AccountsIndex.sol @@ -1,29 +1,40 @@ pragma solidity >=0.6.12; // Author: Louis Holbrook 0826EDA1702D1E87C6E2875121D2E7BB88C2A746 -// SPDX-License-Identifier: GPL-3.0-or-later -// File-version: 4 +// SPDX-License-Identifier: AGPL-3.0-or-later +// File-version: 5 -interface AddressIndex { +interface AccountsIndex { event AddressAdded(address indexed addedAccount, uint256 indexed accountIndex); // AccountsIndex + event AddressActive(address indexed _executor, address indexed _account, bool _active); + event AddressRemoved(address indexed _executor, address _account); // Return number of entries in index function entryCount() external view returns (uint256); + // Return entry at the spceificed index // Will revert if index is beyond array length. + // An entry result of function entry(uint256) external view returns (address); + // Add an entry to the index. Incresases the entry count. function add(address) external returns (bool); + // Remove an entry from the index. Reduces the entry count. function remove(address) external returns (bool); + // Verify that the entry exists in the index function have(address) external view returns (bool); + // Deactivate account but keep in index. Does not affect entry count. function deactivate(address) external returns (bool); + // Activate previously deactivated account. Does not affect entry count. function activate(address) external returns (bool); + // Check if account exists and is active; function isActive(address) external view returns (bool); + // Retrieve the timestamp when account was added function time(address) external view returns (uint256); } diff --git a/solidity/Burner.sol b/solidity/Burner.sol index 1f4b6c5..4f1805d 100644 --- a/solidity/Burner.sol +++ b/solidity/Burner.sol @@ -2,13 +2,25 @@ pragma solidity >=0.6.12; // Author: Louis Holbrook 0826EDA1702D1E87C6E2875121D2E7BB88C2A746 // SPDX-License-Identifier: GPL-3.0-or-later -// File-version: 2 +// File-version: 3 interface Burner { - event Burn(uint256 _burned); + // Token(s) successfully burned; by who and how much. + event Burn(address indexed _burner, uint256 _burned); + // Satisfies ERC 5679 + function burn(address _from, uint256 _amount, bytes calldata _data) external; + + // Burn given amount of tokens held by signer. function burn(uint256 _burn) external returns (bool); + + // Burn all tokens held by signer. + function burn() external returns (bool); + + // Total amount of tokens that have been burned. function totalBurned() external returns (uint256); + + // Total amount of tokens ever minted. + // If totalSupply() is available (ERC20, ERC721 Enumerable), this equals totalSupply() + totalBurned(). function totalMinted() external returns (uint256); } - diff --git a/solidity/Declarator.sol b/solidity/Declarator.sol index b2eb42e..dbd39de 100644 --- a/solidity/Declarator.sol +++ b/solidity/Declarator.sol @@ -1,7 +1,7 @@ pragma solidity >=0.6.12; // Author: Louis Holbrook 0826EDA1702D1E87C6E2875121D2E7BB88C2A746 -// SPDX-License-Identifier: GPL-3.0-or-later +// SPDX-License-Identifier: AGPL-3.0-or-later // File-version: 3 interface Declarator { @@ -9,18 +9,25 @@ interface Declarator { // Get all declarations for a subject (without topic) signed by a declarator function declaration(address _declarator, address _subject) external view returns ( bytes32[] memory ); + // Get all declarations for a subject for the given topic signed by a declarator function declaration(address _declarator, address _subject, bytes32 _topic) external view returns ( bytes32[] memory ); + // Get number of declarations the declarator has ever signed function declarationCount(address _declarator) external view returns ( uint256 ); + // Get the subject of a declarator's declarations at the specific index function declarationAddressAt(address _declarator, uint256 _idx) external view returns ( address ); + // Add a declaration for the subject function addDeclaration(address _subject, bytes32 _proof) external returns ( bool ); + // Add a declaration with topic for the subject function addDeclaration(address _subject, bytes32 _proof, bytes32 _topic) external returns ( bool ); + // Get the declarator that signed a declaration at the specificed index for a subject function declaratorAddressAt(address _subject, uint256 _idx) external view returns ( address ); + // Get the number of declarators that have signed for a subject function declaratorCount(address _subject) external view returns ( uint256 ); } diff --git a/solidity/Expire.sol b/solidity/Expire.sol index 639bad0..e99386e 100644 --- a/solidity/Expire.sol +++ b/solidity/Expire.sol @@ -5,7 +5,9 @@ pragma solidity >=0.6.12; // File-version: 2 interface Expire { + // Expiration timestamp has been changed. event Expired(uint256 _timestamp); + // The current expiration timestamp. function expires() external returns (uint256); } diff --git a/solidity/Faucet.sol b/solidity/Faucet.sol index dd2394b..20eff7d 100644 --- a/solidity/Faucet.sol +++ b/solidity/Faucet.sol @@ -5,20 +5,35 @@ pragma solidity >=0.6.12; // File-version: 6 interface Faucet { + // Tokens were given to an address event Give(address indexed _recipient, address indexed _token, uint256 _value); + + // The amount that the faucet disperses has changed event FaucetAmountChange(uint256 _value); // Address of token the faucet represents // The faucet will return gas tokens with the zero-address is returned. function token() external returns (address); + // Amount of tokens the faucet gives out function tokenAmount() external returns (uint256); + // Give tokens to the given recipient. Returns amount of tokens given. function giveTo(address _recipient) external returns (uint256); + // Give tokens to yourself. Returns amount of tokens given. function gimme() external returns (uint256); + + // Check if faucet may be used in the current contract state by _recipient + function check(address _recipient) external view returns (bool); + // Returns timestamp when faucet may be used again by _recipient // If 0 is returned, the address has not yet been used. // A return value of max(uint256) indicates that the faucet may not be used again. function nextTime(address _recipient) external returns (uint256); + + // Returns the token balance under which faucet may be used again by _recipient + // A return value of max(uint256) indicates that the faucet may be used regardless + // of the token balance of _recipient + function nextBalance(address _recipient) external returns (uint256); } diff --git a/solidity/Locator.sol b/solidity/Locator.sol new file mode 100644 index 0000000..2c2b01a --- /dev/null +++ b/solidity/Locator.sol @@ -0,0 +1,13 @@ +pragma solidity >=0.6.12; + +// Author: Louis Holbrook 0826EDA1702D1E87C6E2875121D2E7BB88C2A746 +// SPDX-License-Identifier: GPL-3.0-or-later +// File-version: 3 + +interface ILocator { + // URI that may or may not point to a specific resource location + function toURI(bytes memory _data) external view returns (string memory); + + // URL pointing to a specific resource location + function toURL(bytes memory _data) external view returns(string memory); +} diff --git a/solidity/Minter.sol b/solidity/Minter.sol index ad7e8ff..a560129 100644 --- a/solidity/Minter.sol +++ b/solidity/Minter.sol @@ -2,11 +2,18 @@ pragma solidity >=0.6.12; // Author: Louis Holbrook 0826EDA1702D1E87C6E2875121D2E7BB88C2A746 // SPDX-License-Identifier: GPL-3.0-or-later -// File-version: 1 +// File-version: 2 interface Minter { + // Tokens are successfully minted; by who, to whom and how much event Mint(address indexed _minter, address indexed _beneficiary, uint256 value); // Mint the specified value of tokens to the specified recipient function mintTo(address _beneficiary, uint256 value) external returns (bool); + + // Satisfies ERC5679 for ERC20 + function mint(address _beneficiary, uint256 value, bytes calldata _data) external; + + // Satisfies ERC5679 for ERC721 + function safeMint(address _beneficiary, uint256 value, bytes calldata _data) external; } diff --git a/solidity/Msg.sol b/solidity/Msg.sol new file mode 100644 index 0000000..2a6d8d8 --- /dev/null +++ b/solidity/Msg.sol @@ -0,0 +1,14 @@ +pragma solidity >=0.6.12; + +// Author: Louis Holbrook 0826EDA1702D1E87C6E2875121D2E7BB88C2A746 +// SPDX-License-Identifier: AGPL-3.0-or-later +// File-version: 2 + +interface IMsg { + // Emitted when a new message digest has been set + // Should not be emitted if the digest set is identical to the previous + event Msg(bytes _msgDigest); + + // Get the current message content hash + function getMsg() external view returns(bytes memory); +} diff --git a/solidity/MultiHash.sol b/solidity/MultiHash.sol new file mode 100644 index 0000000..52746c4 --- /dev/null +++ b/solidity/MultiHash.sol @@ -0,0 +1,22 @@ +pragma solidity >=0.6.12; + +// Author: Louis Holbrook 0826EDA1702D1E87C6E2875121D2E7BB88C2A746 +// SPDX-License-Identifier: GPL-3.0-or-later +// File-version: 2 + +interface IMultiHash { + // Represents a multicodec item. + struct MultiHash { + uint8 l; + uint8 codecRLength; + uint8 prefixRLength; + bytes16 prefix; + bytes8 codec; + } + + // All registered multicodecs + function multiCodec(uint256 _codec) external view returns(MultiHash memory); + + // Generate a multihash from the given digest and current selected multicodec + function toMultiHash(uint256 _codec, bytes memory _digest) external view returns(bytes memory); +} diff --git a/solidity/Registry.sol b/solidity/Registry.sol index 0010285..620b323 100644 --- a/solidity/Registry.sol +++ b/solidity/Registry.sol @@ -1,8 +1,8 @@ pragma solidity >=0.6.12; // Author: Louis Holbrook 0826EDA1702D1E87C6E2875121D2E7BB88C2A746 -// SPDX-License-Identifier: GPL-3.0-or-later -// File-version: 2 +// SPDX-License-Identifier: AGPL-3.0-or-later +// File-version: 3 interface Registry { function set(bytes32, address) external returns (bool); diff --git a/solidity/RegistryClient.sol b/solidity/RegistryClient.sol index cf68d2e..24625ee 100644 --- a/solidity/RegistryClient.sol +++ b/solidity/RegistryClient.sol @@ -1,10 +1,16 @@ pragma solidity >=0.6.12; // Author: Louis Holbrook 0826EDA1702D1E87C6E2875121D2E7BB88C2A746 -// SPDX-License-Identifier: GPL-3.0-or-later -// File-version: 2 +// SPDX-License-Identifier: AGPL-3.0-or-later +// File-version: 3 interface RegistryClient { + // Return the address of the contract identified by the given byte string function addressOf(bytes32) external view returns (address); + + // Indexed accessor for the full list of registred identifiers function identifiers(uint256) external view returns (bytes32); + + // Number of registered interfaces + function identifierCount() external view returns (uint256); } diff --git a/solidity/Writer.sol b/solidity/Writer.sol index a1bc006..7554c8b 100644 --- a/solidity/Writer.sol +++ b/solidity/Writer.sol @@ -5,10 +5,18 @@ pragma solidity >=0.6.12; // File-version: 2 interface Writer { + // A writer has been added by _executor event WriterAdded(address indexed _executor, address _writer); + + // A writer has been removed by _executor event WriterDeleted(address indexed _executor, address _writer); + // Add a new writer to the contract. function addWriter(address _writer) external returns (bool); + + // Remove existing writer from the contract. function deleteWriter(address _writer) external returns (bool); + + // Check whether the given address is a writer. function isWriter(address _writer) external returns (bool); } diff --git a/texify.sh b/texify.sh new file mode 100644 index 0000000..7a5743b --- /dev/null +++ b/texify.sh @@ -0,0 +1,10 @@ +#!/bin/bash + +for f in $(ls solidity/*.sol); do + fn=$(basename $f) + fb=${fn%.*} + fn="build/contract_${fb}.texi" + echo "@verbatim" > $fn + awk 'f;/interface [a-zA-Z0-9]* /{print;f=1}' $f >> $fn + echo "@end verbatim" >> $fn +done From a28cfdbb364571a88bca5d1668a5643b1ed3ff80 Mon Sep 17 00:00:00 2001 From: lash Date: Sat, 25 Mar 2023 11:24:23 +0000 Subject: [PATCH 05/10] Improve locator example --- doc/texinfo/accountsindex.sol.texi | 6 +++--- doc/texinfo/declarator.sol.texi | 2 +- doc/texinfo/expire.sol.texi | 2 +- doc/texinfo/locator.sol.texi | 6 +++--- 4 files changed, 8 insertions(+), 8 deletions(-) diff --git a/doc/texinfo/accountsindex.sol.texi b/doc/texinfo/accountsindex.sol.texi index 52b7a8e..defe758 100644 --- a/doc/texinfo/accountsindex.sol.texi +++ b/doc/texinfo/accountsindex.sol.texi @@ -1,13 +1,13 @@ @subsection Accounts Index -Account address membership list. - -Records time when account was added. +Typically used for access control lists. Addresses may be @emph{added}, @emph{removed}, aswell as @emph{deactivated} and @emph{activated}. Deactivated accounts still count towards the @code{entryCount}. The @code{entry} method is used to iterate the account list. The order of which accounts are returned is not guaranteed. Any returned value matching @code{address(0x00)} should be skipped, and not counted towards @code{entryCount}. +Also records time when account was added. + @table @dfn @item ERC165 Interface identifier @include ../../build/AccountsIndex.interface diff --git a/doc/texinfo/declarator.sol.texi b/doc/texinfo/declarator.sol.texi index 9e6b0f5..ff25d97 100644 --- a/doc/texinfo/declarator.sol.texi +++ b/doc/texinfo/declarator.sol.texi @@ -6,7 +6,7 @@ It is used to declare or respond to certifications of vouchers, NFT, voucher mem Addresses may be Externally Owned Accounts or smart contracts. -Claims may be made with or without topics. A missing topic is synonymous with a topic valud of @code{bytes32(0x00)}. +Claims may be made with or without topics. A missing topic is synonymous with a topic value of @code{bytes32(0x00)}. Any number of claims can be made about an address under any number of topics. All claims must be stored, and returned in the order which they were added. diff --git a/doc/texinfo/expire.sol.texi b/doc/texinfo/expire.sol.texi index 132bddf..d4a57f7 100644 --- a/doc/texinfo/expire.sol.texi +++ b/doc/texinfo/expire.sol.texi @@ -1,6 +1,6 @@ @subsection Expire -Defines a token contract that may not be used after a certain time. +Defines an expiry time after which token balances or supply @emph{cannot change}. A contract defining an expiry @emph{must not} allow changing the expiration time to a time in the past. diff --git a/doc/texinfo/locator.sol.texi b/doc/texinfo/locator.sol.texi index ac746ff..0cdaa93 100644 --- a/doc/texinfo/locator.sol.texi +++ b/doc/texinfo/locator.sol.texi @@ -18,12 +18,12 @@ Furthermore, it @emph{should} be possible to refer to a resource by a fully-qua @subsubsection Expressing locators in terms of numetic token id -Given the numeric token id @code{1234567890987654321}, and a base url @code{https://contentgateway.grassecon.net}, the result of the methods may be as follows: +Given the numeric token id @code{1234567890987654321} (@code{0x112210f4b16c1cb1} hex), and a base url @code{https://contentgateway.grassecon.net}, the result of the methods may be as follows: @table @code -@item toURI(000000000000000000000000000000000000000000000000112210f4b16c1cb1) +@item toURI(toHex(1234567890987654321)) -> @code{https://contentgateway.grassecon.net/000000000000000000000000000000000000000000000000112210f4b16c1cb1} -@item toURL(000000000000000000000000000000000000000000000000112210f4b16c1cb1) +@item toURL(toHex(1234567890987654321)) -> @code{https://contentgateway.grassecon.net/000000000000000000000000000000000000000000000000112210f4b16c1cb1} @item tokenURI(1234567890987654321) -> @code{https://contentgateway.grassecon.net/000000000000000000000000000000000000000000000000112210f4b16c1cb1} From 46cc35b54c06e526a70b110a8e1c8ce0351b4b93 Mon Sep 17 00:00:00 2001 From: lash Date: Sat, 25 Mar 2023 12:32:56 +0000 Subject: [PATCH 06/10] Add back ERC interfaces --- doc/texinfo/multihash.sol.texi | 2 +- doc/texinfo/overview.texi | 8 +++++--- doc/texinfo/registry.sol.texi | 2 +- doc/texinfo/writer.sol.texi | 4 +++- solidity/AccountsIndex.sol | 2 +- solidity/Burner.sol | 4 ++-- solidity/Declarator.sol | 2 +- solidity/ERC165.sol | 12 ++++++++++++ solidity/ERC173.sol | 16 ++++++++++++++++ solidity/ERC20.sol | 24 ++++++++++++++++++++++++ solidity/ERC5679Ext20.sol | 14 ++++++++++++++ solidity/ERC5679Ext721.sol | 14 ++++++++++++++ solidity/ERC721.sol | 25 +++++++++++++++++++++++++ solidity/ERC721Enumerable.sol | 15 +++++++++++++++ solidity/ERC721Metadata.sol | 15 +++++++++++++++ solidity/ERC721Receiver.sol | 13 +++++++++++++ solidity/Expire.sol | 4 ++-- solidity/Faucet.sol | 4 ++-- solidity/Locator.sol | 2 +- solidity/Minter.sol | 4 ++-- solidity/MultiHash.sol | 2 +- solidity/OwnedAccepter.sol | 8 ++++---- solidity/OwnedTaker.sol | 6 +++--- solidity/Registry.sol | 2 +- solidity/RegistryClient.sol | 2 +- solidity/Seal.sol | 16 ++++++++++++++++ solidity/Writer.sol | 6 +++--- 27 files changed, 198 insertions(+), 30 deletions(-) create mode 100644 solidity/ERC165.sol create mode 100644 solidity/ERC173.sol create mode 100644 solidity/ERC20.sol create mode 100644 solidity/ERC5679Ext20.sol create mode 100644 solidity/ERC5679Ext721.sol create mode 100644 solidity/ERC721.sol create mode 100644 solidity/ERC721Enumerable.sol create mode 100644 solidity/ERC721Metadata.sol create mode 100644 solidity/ERC721Receiver.sol create mode 100644 solidity/Seal.sol diff --git a/doc/texinfo/multihash.sol.texi b/doc/texinfo/multihash.sol.texi index 24e5609..f48643f 100644 --- a/doc/texinfo/multihash.sol.texi +++ b/doc/texinfo/multihash.sol.texi @@ -1,6 +1,6 @@ @subsection Multihash -A complement to @code{Locator}, enabling validation and generation for multihashes that have been registered to the contract. +A complement to @code{Locator}, enabling validation and generation of multihashes for multicodecs that have been registered to the contract. @table @dfn diff --git a/doc/texinfo/overview.texi b/doc/texinfo/overview.texi index d4c541d..e434119 100644 --- a/doc/texinfo/overview.texi +++ b/doc/texinfo/overview.texi @@ -14,6 +14,7 @@ CIC smart contracts are implemented using the @emph{solidity} programming langua The following well-known solidity interfaces are used directly. + @itemize @bullet @item @uref{https://eips.ethereum.org/EIPS/eip-20, ERC20 - Token Standard} @@ -26,7 +27,7 @@ The following well-known solidity interfaces are used directly. @end itemize -@subsection Extended ERC definitions +@subsection Partial use @itemize @dfn @item @@ -34,7 +35,7 @@ The following well-known solidity interfaces are used directly. @end itemize -@section Native implementations +@section Native interfaces @include accountsindex.sol.texi @@ -56,5 +57,6 @@ The following well-known solidity interfaces are used directly. @include registry.sol.texi -@include writer.sol.texi +@include seal.sol.texi +@include writer.sol.texi diff --git a/doc/texinfo/registry.sol.texi b/doc/texinfo/registry.sol.texi index 9c0c02c..a19c3f0 100644 --- a/doc/texinfo/registry.sol.texi +++ b/doc/texinfo/registry.sol.texi @@ -16,7 +16,7 @@ Unique (ERC20) token symbol resolver. @include ../../build/RegistryClient.interface @item Solidity interface definition @include ../../build/contract_RegistryClient.texi -@item Reference implementation +@item Contract registry implementation @uref{git://holbrook.no/eth-contract-registry.git,} @item Token index implementation @uref{git://holbrook.no/eth-contract-registry.git,} diff --git a/doc/texinfo/writer.sol.texi b/doc/texinfo/writer.sol.texi index 1e794aa..25d0756 100644 --- a/doc/texinfo/writer.sol.texi +++ b/doc/texinfo/writer.sol.texi @@ -2,7 +2,9 @@ A complement to ERC173, which allows definition of a class of super-users for a contract. -Typically, a super-user address may perform @emph{more} actions than a "normal" address, aswell as @emph{some} actions normally limited to the @emph{contract owner}. +A super-user address may perform @emph{more} actions than a "normal" address, aswell as @emph{some} actions normally limited to the @emph{contract owner}. + +No super-user should be able to perform actions that @emph{contract owner} cannot perform. Typically, only the @emph{contract owner} can add or remove a super-user. diff --git a/solidity/AccountsIndex.sol b/solidity/AccountsIndex.sol index 2d86250..c2670b0 100644 --- a/solidity/AccountsIndex.sol +++ b/solidity/AccountsIndex.sol @@ -4,7 +4,7 @@ pragma solidity >=0.6.12; // SPDX-License-Identifier: AGPL-3.0-or-later // File-version: 5 -interface AccountsIndex { +interface IAccountsIndex { event AddressAdded(address indexed addedAccount, uint256 indexed accountIndex); // AccountsIndex event AddressActive(address indexed _executor, address indexed _account, bool _active); event AddressRemoved(address indexed _executor, address _account); diff --git a/solidity/Burner.sol b/solidity/Burner.sol index 4f1805d..c41c316 100644 --- a/solidity/Burner.sol +++ b/solidity/Burner.sol @@ -1,10 +1,10 @@ pragma solidity >=0.6.12; // Author: Louis Holbrook 0826EDA1702D1E87C6E2875121D2E7BB88C2A746 -// SPDX-License-Identifier: GPL-3.0-or-later +// SPDX-License-Identifier: AGPL-3.0-or-later // File-version: 3 -interface Burner { +interface IBurner { // Token(s) successfully burned; by who and how much. event Burn(address indexed _burner, uint256 _burned); diff --git a/solidity/Declarator.sol b/solidity/Declarator.sol index dbd39de..7db3b00 100644 --- a/solidity/Declarator.sol +++ b/solidity/Declarator.sol @@ -4,7 +4,7 @@ pragma solidity >=0.6.12; // SPDX-License-Identifier: AGPL-3.0-or-later // File-version: 3 -interface Declarator { +interface IDeclarator { event DeclarationAdded(address indexed _declarator, address indexed _subject, bytes32 indexed _topic, bytes32 _proof); // Get all declarations for a subject (without topic) signed by a declarator diff --git a/solidity/ERC165.sol b/solidity/ERC165.sol new file mode 100644 index 0000000..47bedc4 --- /dev/null +++ b/solidity/ERC165.sol @@ -0,0 +1,12 @@ +pragma solidity >=0.6.12; + +// Author: Louis Holbrook 0826EDA1702D1E87C6E2875121D2E7BB88C2A746 +// SPDX-License-Identifier: AGPL-3.0-or-later +// File-version: 4 + +// This is a representation of an officially approved Ethereum Improvement Proposal, written by Christian Reitwießner chris@ethereum.org, Nick Johnson nick@ethereum.org, Fabian Vogelsteller fabian@lukso.network, Jordi Baylina jordi@baylina.cat, Konrad Feldmeier konrad.feldmeier@brainbot.com and William Entriken github.com@phor.net. It was released under the CC0 license. +// The proposal source used as reference was a Markdown file with the following digests: +// - sha256:2fc8534206e1e5b7abbb9db21fa5b83d39c51b2dabad441a356b7d18320bfc51 +interface IERC165 { + function supportsInterface(bytes4 _sum) external pure returns (bool); +} diff --git a/solidity/ERC173.sol b/solidity/ERC173.sol new file mode 100644 index 0000000..4a38070 --- /dev/null +++ b/solidity/ERC173.sol @@ -0,0 +1,16 @@ +pragma solidity >=0.6.12; + +// Author: Louis Holbrook 0826EDA1702D1E87C6E2875121D2E7BB88C2A746 +// SPDX-License-Identifier: AGPL-3.0-or-later +// File-version: 3 + +// This is a representation of an officially approved Ethereum Improvement Proposal, written by Nick Mudge and Dan Finlay and released under the CC0 license. +// The proposal source used as reference was a Markdown file with the following digests: +// - sha256:45e14ac315e380b5372a5ffc6783ab11d7eafb7fa5a123e0b8e5fc8c6c527c4c +// - swarmhash:0cadf6a7122d2da20dbab0ef31c692b1b24cf49ae5c1c80f7ce6dbae8885ce01 +interface IERC173 { + event OwnershipTransferred(address indexed previousOwner, address indexed newOwner); + + function owner() external view returns (address); + function transferOwnership(address _newOwner) external view returns (bool); +} diff --git a/solidity/ERC20.sol b/solidity/ERC20.sol new file mode 100644 index 0000000..018f141 --- /dev/null +++ b/solidity/ERC20.sol @@ -0,0 +1,24 @@ +pragma solidity >=0.6.12; + +// Author: Louis Holbrook 0826EDA1702D1E87C6E2875121D2E7BB88C2A746 +// SPDX-License-Identifier: AGPL-3.0-or-later +// File-version: 3 + +// This is a representation of an officially approved Ethereum Improvement Proposal, written by Fabian Vogelsteller fabian@ethereum.org, Vitalik Buterin vitalik.buterin@ethereum.org. It was released under the CC0 license. +// The proposal source used as reference was a Markdown file with the following digests: +// - sha256:d120f321f2bef19596a401fba86d13352693ccd39645c2bbc84ffb3ed551388f +// - swarmhash:598f13429ec42f50d7a6576ab20feffdaf2135a90805678d24e4ea297bf0e639 +interface IERC20 { + event Transfer(address indexed _from, address indexed _to, uint256 _value); + event Approval(address indexed _owner, address indexed _spender, uint256 _value); + + function transfer(address _to, uint256 _value) external returns (bool); + function transferFrom(address _from, address _to, uint256 _value) external returns (bool); + function approve(address _spender, uint256 _value) external returns (bool); + function name() external view returns (string memory); + function symbol() external view returns (string memory); + function decimals() external view returns (uint256); + function totalSupply() external view returns (uint256); + function allowance(address _owner, address _spender) external view returns(uint256); + function balanceOf(address _holder) external view returns (uint256); +} diff --git a/solidity/ERC5679Ext20.sol b/solidity/ERC5679Ext20.sol new file mode 100644 index 0000000..42056a2 --- /dev/null +++ b/solidity/ERC5679Ext20.sol @@ -0,0 +1,14 @@ +pragma solidity >=0.6.12; + +// Author: Louis Holbrook 0826EDA1702D1E87C6E2875121D2E7BB88C2A746 +// SPDX-License-Identifier: AGPL-3.0-or-later +// File-version: 1 + +// This is a representation of an officially approved Ethereum Improvement Proposal, Zainan Victor Zhou (@xinbenlv). +// The proposal source used as reference was a Markdown file with the following digests: +// - sha256:7e799dd22588f62c52c4886d7b523c12696441a6c2350b739562ea8fb5d60649 + +interface IERC5679Ext20 { + function mint(address _to, uint256 _amount, bytes calldata _data) external; + function burn(address _from, uint256 _amount, bytes calldata _data) external; +} diff --git a/solidity/ERC5679Ext721.sol b/solidity/ERC5679Ext721.sol new file mode 100644 index 0000000..d123769 --- /dev/null +++ b/solidity/ERC5679Ext721.sol @@ -0,0 +1,14 @@ +pragma solidity >=0.6.12; + +// Author: Louis Holbrook 0826EDA1702D1E87C6E2875121D2E7BB88C2A746 +// SPDX-License-Identifier: AGPL-3.0-or-later +// File-version: 2 + +// This is a representation of an officially approved Ethereum Improvement Proposal, Zainan Victor Zhou (@xinbenlv). +// The proposal source used as reference was a Markdown file with the following digests: +// - sha256:7e799dd22588f62c52c4886d7b523c12696441a6c2350b739562ea8fb5d60649 + +interface IERC5679Ext721 { + function safeMint(address _to, uint256 _id, bytes calldata _data) external; + function burn(address _from, uint256 _id, bytes calldata _data) external; +} diff --git a/solidity/ERC721.sol b/solidity/ERC721.sol new file mode 100644 index 0000000..c3b5375 --- /dev/null +++ b/solidity/ERC721.sol @@ -0,0 +1,25 @@ +pragma solidity >=0.6.12; + +// Author: Louis Holbrook 0826EDA1702D1E87C6E2875121D2E7BB88C2A746 +// SPDX-License-Identifier: AGPL-3.0-or-later +// File-version: 3 + +// This is a representation of an officially approved Ethereum Improvement Proposal, William Entriken (@fulldecent), Dieter Shirley dete@axiomzen.co, Jacob Evans jacob@dekz.net, Nastassia Sachs nastassia.sachs@protonmail.com +// The proposal source used as reference was a Markdown file with the following digests: +// - sha256:f25b41ad1bff14ec57e8c247f2ecf372fd86245d08ba3cbd005c21a42744a7ca +// - swarmhash:cf43d96b21b0b017ae32fb2ac8df9268f13344d9fd20aa1d959453eaf379a51b +interface IERC721 { + event Transfer(address indexed _from, address indexed _to, uint256 indexed _tokenId); + event Approval(address indexed _owner, address indexed _approved, uint256 indexed _tokenId); + event ApprovalForAll(address indexed _owner, address indexed _operator, bool _approved); + + function balanceOf(address _owner) external view returns (uint256); + function ownerOf(uint256 _tokenId) external view returns (address); + function safeTransferFrom(address _from, address _to, uint256 _tokenId) external payable; + function safeTransferFrom(address _from, address _to, uint256 _tokenId, bytes memory _data) external payable; + function transferFrom(address _from, address _to, uint256 _tokenId) external payable; + function approve(address _approved, uint256 _tokenId) external payable; + function setApprovalForAll(address _operator, bool _approved) external; + function getApproved(uint256 _tokenId) external view returns (address); + function isApprovedForAll(address _owner, address _operator) external view returns (bool); +} diff --git a/solidity/ERC721Enumerable.sol b/solidity/ERC721Enumerable.sol new file mode 100644 index 0000000..01a35e4 --- /dev/null +++ b/solidity/ERC721Enumerable.sol @@ -0,0 +1,15 @@ +pragma solidity >=0.6.12; + +// Author: Louis Holbrook 0826EDA1702D1E87C6E2875121D2E7BB88C2A746 +// SPDX-License-Identifier: AGPL-3.0-or-later +// File-version: 2 + +// This is a representation of an officially approved Ethereum Improvement Proposal, William Entriken (@fulldecent), Dieter Shirley dete@axiomzen.co, Jacob Evans jacob@dekz.net, Nastassia Sachs nastassia.sachs@protonmail.com +// The proposal source used as reference was a Markdown file with the following digests: +// - sha256:f25b41ad1bff14ec57e8c247f2ecf372fd86245d08ba3cbd005c21a42744a7ca +// - swarmhash:cf43d96b21b0b017ae32fb2ac8df9268f13344d9fd20aa1d959453eaf379a51b +interface IERC721Enumerable { + function totalSupply() external view returns (uint256); + function tokenByIndex(uint256 _index) external view returns (uint256); + function tokenOfOwnerByIndex(address _owner, uint256 _index) external view returns (uint256); +} diff --git a/solidity/ERC721Metadata.sol b/solidity/ERC721Metadata.sol new file mode 100644 index 0000000..d3a97ac --- /dev/null +++ b/solidity/ERC721Metadata.sol @@ -0,0 +1,15 @@ +pragma solidity >=0.6.12; + +// Author: Louis Holbrook 0826EDA1702D1E87C6E2875121D2E7BB88C2A746 +// SPDX-License-Identifier: AGPL-3.0-or-later +// File-version: 2 + +// This is a representation of an officially approved Ethereum Improvement Proposal, William Entriken (@fulldecent), Dieter Shirley dete@axiomzen.co, Jacob Evans jacob@dekz.net, Nastassia Sachs nastassia.sachs@protonmail.com +// The proposal source used as reference was a Markdown file with the following digests: +// - sha256:f25b41ad1bff14ec57e8c247f2ecf372fd86245d08ba3cbd005c21a42744a7ca +// - swarmhash:cf43d96b21b0b017ae32fb2ac8df9268f13344d9fd20aa1d959453eaf379a51b +interface IERC721Metadata { + function name() external view returns (string memory _name); + function symbol() external view returns (string memory _symbol); + function tokenURI(uint256 _tokenId) external view returns (string memory); +} diff --git a/solidity/ERC721Receiver.sol b/solidity/ERC721Receiver.sol new file mode 100644 index 0000000..6d2e004 --- /dev/null +++ b/solidity/ERC721Receiver.sol @@ -0,0 +1,13 @@ +pragma solidity >=0.6.12; + +// Author: Louis Holbrook 0826EDA1702D1E87C6E2875121D2E7BB88C2A746 +// SPDX-License-Identifier: AGPL-3.0-or-later +// File-version: 2 + +// This is a representation of an officially approved Ethereum Improvement Proposal, William Entriken (@fulldecent), Dieter Shirley dete@axiomzen.co, Jacob Evans jacob@dekz.net, Nastassia Sachs nastassia.sachs@protonmail.com +// The proposal source used as reference was a Markdown file with the following digests: +// - sha256:f25b41ad1bff14ec57e8c247f2ecf372fd86245d08ba3cbd005c21a42744a7ca +// - swarmhash:cf43d96b21b0b017ae32fb2ac8df9268f13344d9fd20aa1d959453eaf379a51b +interface IERC721Receiver { + function onERC721Received(address _operator, address _from, uint256 _tokenId, bytes memory _data) external returns(bytes4); +} diff --git a/solidity/Expire.sol b/solidity/Expire.sol index e99386e..4cb6af4 100644 --- a/solidity/Expire.sol +++ b/solidity/Expire.sol @@ -1,10 +1,10 @@ pragma solidity >=0.6.12; // Author: Louis Holbrook 0826EDA1702D1E87C6E2875121D2E7BB88C2A746 -// SPDX-License-Identifier: GPL-3.0-or-later +// SPDX-License-Identifier: AGPL-3.0-or-later // File-version: 2 -interface Expire { +interface IExpire { // Expiration timestamp has been changed. event Expired(uint256 _timestamp); diff --git a/solidity/Faucet.sol b/solidity/Faucet.sol index 20eff7d..accda92 100644 --- a/solidity/Faucet.sol +++ b/solidity/Faucet.sol @@ -1,10 +1,10 @@ pragma solidity >=0.6.12; // Author: Louis Holbrook 0826EDA1702D1E87C6E2875121D2E7BB88C2A746 -// SPDX-License-Identifier: GPL-3.0-or-later +// SPDX-License-Identifier: AGPL-3.0-or-later // File-version: 6 -interface Faucet { +interface IFaucet { // Tokens were given to an address event Give(address indexed _recipient, address indexed _token, uint256 _value); diff --git a/solidity/Locator.sol b/solidity/Locator.sol index 2c2b01a..dc21167 100644 --- a/solidity/Locator.sol +++ b/solidity/Locator.sol @@ -1,7 +1,7 @@ pragma solidity >=0.6.12; // Author: Louis Holbrook 0826EDA1702D1E87C6E2875121D2E7BB88C2A746 -// SPDX-License-Identifier: GPL-3.0-or-later +// SPDX-License-Identifier: AGPL-3.0-or-later // File-version: 3 interface ILocator { diff --git a/solidity/Minter.sol b/solidity/Minter.sol index a560129..5757a39 100644 --- a/solidity/Minter.sol +++ b/solidity/Minter.sol @@ -1,10 +1,10 @@ pragma solidity >=0.6.12; // Author: Louis Holbrook 0826EDA1702D1E87C6E2875121D2E7BB88C2A746 -// SPDX-License-Identifier: GPL-3.0-or-later +// SPDX-License-Identifier: AGPL-3.0-or-later // File-version: 2 -interface Minter { +interface IMinter { // Tokens are successfully minted; by who, to whom and how much event Mint(address indexed _minter, address indexed _beneficiary, uint256 value); diff --git a/solidity/MultiHash.sol b/solidity/MultiHash.sol index 52746c4..2b76211 100644 --- a/solidity/MultiHash.sol +++ b/solidity/MultiHash.sol @@ -1,7 +1,7 @@ pragma solidity >=0.6.12; // Author: Louis Holbrook 0826EDA1702D1E87C6E2875121D2E7BB88C2A746 -// SPDX-License-Identifier: GPL-3.0-or-later +// SPDX-License-Identifier: AGPL-3.0-or-later // File-version: 2 interface IMultiHash { diff --git a/solidity/OwnedAccepter.sol b/solidity/OwnedAccepter.sol index 69f8f74..b2e40aa 100644 --- a/solidity/OwnedAccepter.sol +++ b/solidity/OwnedAccepter.sol @@ -1,9 +1,9 @@ -pragma solidity ^0.8.0; +pragma solidity >=0.6.12; // Author: Louis Holbrook 0826EDA1702D1E87C6E2875121D2E7BB88C2A746 -// SPDX-License-Identifier: GPL-3.0-or-later -// File-version: 1 +// SPDX-License-Identifier: AGPL-3.0-or-later +// File-version: 2 -interface OwnerAcceptable { +interface IOwnerAcceptable { function acceptOwnership() external view returns (bool); } diff --git a/solidity/OwnedTaker.sol b/solidity/OwnedTaker.sol index 96b48cb..a6149d0 100644 --- a/solidity/OwnedTaker.sol +++ b/solidity/OwnedTaker.sol @@ -1,8 +1,8 @@ -pragma solidity ^0.8.0; +pragma solidity >=0.6.12; // Author: Louis Holbrook 0826EDA1702D1E87C6E2875121D2E7BB88C2A746 -// SPDX-License-Identifier: GPL-3.0-or-later -// File-version: 1 +// SPDX-License-Identifier: AGPL-3.0-or-later +// File-version: 2 interface OwnerTakeable { event OwnershipTaken(address _result); diff --git a/solidity/Registry.sol b/solidity/Registry.sol index 620b323..c3bd492 100644 --- a/solidity/Registry.sol +++ b/solidity/Registry.sol @@ -4,7 +4,7 @@ pragma solidity >=0.6.12; // SPDX-License-Identifier: AGPL-3.0-or-later // File-version: 3 -interface Registry { +interface IRegistry { function set(bytes32, address) external returns (bool); function bind(bytes32, bytes32) external returns (bool); } diff --git a/solidity/RegistryClient.sol b/solidity/RegistryClient.sol index 24625ee..1cedd10 100644 --- a/solidity/RegistryClient.sol +++ b/solidity/RegistryClient.sol @@ -4,7 +4,7 @@ pragma solidity >=0.6.12; // SPDX-License-Identifier: AGPL-3.0-or-later // File-version: 3 -interface RegistryClient { +interface IRegistryClient { // Return the address of the contract identified by the given byte string function addressOf(bytes32) external view returns (address); diff --git a/solidity/Seal.sol b/solidity/Seal.sol new file mode 100644 index 0000000..44a5584 --- /dev/null +++ b/solidity/Seal.sol @@ -0,0 +1,16 @@ +pragma solidity >=0.6.12; + +// Author: Louis Holbrook 0826EDA1702D1E87C6E2875121D2E7BB88C2A746 +// SPDX-License-Identifier: AGPL-3.0-or-later +// File-version: 1 + +interface ISeal { + // Seal state has changed. + event SealStateChange(bool indexed _final, uint256 _sealState); + + // The current seal state. + function sealState() external view returns(uint256); + + // The numeric seal state in everything sealable has been sealed. + function maxSealState() external view returns(uint256); +} diff --git a/solidity/Writer.sol b/solidity/Writer.sol index 7554c8b..bcd2553 100644 --- a/solidity/Writer.sol +++ b/solidity/Writer.sol @@ -1,10 +1,10 @@ pragma solidity >=0.6.12; // Author: Louis Holbrook 0826EDA1702D1E87C6E2875121D2E7BB88C2A746 -// SPDX-License-Identifier: GPL-3.0-or-later -// File-version: 2 +// SPDX-License-Identifier: AGPL-3.0-or-later +// File-version: 3 -interface Writer { +interface IWriter { // A writer has been added by _executor event WriterAdded(address indexed _executor, address _writer); From 1e11d8df08cf97134df434001c32ecb273973551 Mon Sep 17 00:00:00 2001 From: lash Date: Sun, 26 Mar 2023 09:58:23 +0100 Subject: [PATCH 07/10] Update writer, registry, expire, improve comments --- doc/texinfo/accountsindex.sol.texi | 24 +++++++++++++++++++++--- doc/texinfo/overview.texi | 7 +++++++ solidity/AccountsIndex.sol | 30 +++++++++--------------------- solidity/Expire.sol | 14 ++++++++++++-- solidity/Locator.sol | 4 ++-- solidity/RegistryClient.sol | 5 ++++- solidity/Writer.sol | 6 +++--- 7 files changed, 58 insertions(+), 32 deletions(-) diff --git a/doc/texinfo/accountsindex.sol.texi b/doc/texinfo/accountsindex.sol.texi index defe758..b9adbad 100644 --- a/doc/texinfo/accountsindex.sol.texi +++ b/doc/texinfo/accountsindex.sol.texi @@ -1,12 +1,13 @@ @subsection Accounts Index -Typically used for access control lists. +Append-only list of addresses. Typically used for access control lists. Addresses may be @emph{added}, @emph{removed}, aswell as @emph{deactivated} and @emph{activated}. Deactivated accounts still count towards the @code{entryCount}. The @code{entry} method is used to iterate the account list. The order of which accounts are returned is not guaranteed. Any returned value matching @code{address(0x00)} should be skipped, and not counted towards @code{entryCount}. -Also records time when account was added. +May optionally record time when account was added. + @table @dfn @item ERC165 Interface identifier @@ -14,5 +15,22 @@ Also records time when account was added. @item Solidity interface definition @include ../../build/contract_AccountsIndex.texi @item Reference implementation -@uref{git://holbrook.no/eth-accounts-index.git,} +@uref{git://holbrook.no/eth-accounts-index.git,} (v0.5.1) +@end table + + +@subsection Accounts Index Mutable + +Extends the functionality of @code{Accounts Index} to allow changes to the address list. + +Addresses may be @emph{added}, @emph{removed}, aswell as @emph{deactivated} and @emph{activated}. Deactivated accounts still count towards the @code{entryCount}. + + +@table @dfn +@item ERC165 Interface identifier +@include ../../build/AccountsIndexMutable.interface +@item Solidity interface definition +@include ../../build/contract_AccountsIndexMutable.texi +@item Reference implementation +@uref{git://holbrook.no/eth-accounts-index.git,} (v0.5.1) @end table diff --git a/doc/texinfo/overview.texi b/doc/texinfo/overview.texi index e434119..fa91764 100644 --- a/doc/texinfo/overview.texi +++ b/doc/texinfo/overview.texi @@ -24,11 +24,16 @@ The following well-known solidity interfaces are used directly. @uref{https://eips.ethereum.org/EIPS/eip-173, ERC173 - Contract Ownership Standard} @item @uref{https://eips.ethereum.org/EIPS/eip-721, ERC721 - Non-Fungible Token Standard} +@item +@uref{https://eips.ethereum.org/EIPS/eip-5007, ERC5007 - Time NFT (EIP-721 Time Extension)} +@item +@uref{https://eips.ethereum.org/EIPS/eip-5192, ERC5192 - Minimal Soulbound NFTs} @end itemize @subsection Partial use +The following well-known solidity interfaces are partially implemented in CIC native interfaces. @itemize @dfn @item @uref{https://eips.ethereum.org/EIPS/eip-5679, ERC5679 - Token Minting and Burning} (See @code{Minter}, @code{Burner}) @@ -41,6 +46,8 @@ The following well-known solidity interfaces are used directly. @include burner.sol.texi +@include chrono.sol.texi + @include declarator.sol.texi @include expire.sol.texi diff --git a/solidity/AccountsIndex.sol b/solidity/AccountsIndex.sol index c2670b0..ee9dd0f 100644 --- a/solidity/AccountsIndex.sol +++ b/solidity/AccountsIndex.sol @@ -2,39 +2,27 @@ pragma solidity >=0.6.12; // Author: Louis Holbrook 0826EDA1702D1E87C6E2875121D2E7BB88C2A746 // SPDX-License-Identifier: AGPL-3.0-or-later -// File-version: 5 +// File-version: 6 interface IAccountsIndex { - event AddressAdded(address indexed addedAccount, uint256 indexed accountIndex); // AccountsIndex - event AddressActive(address indexed _executor, address indexed _account, bool _active); - event AddressRemoved(address indexed _executor, address _account); + // Address added to store, index in array. + event AddressAdded(uint256 indexed _idx, address _account); - // Return number of entries in index + // Return number of entries in index. function entryCount() external view returns (uint256); - // Return entry at the spceificed index + // Return entry at the spceificed index. // Will revert if index is beyond array length. - // An entry result of + // An entry result of 0 means the entry should be skipped, and not count towards entry count. function entry(uint256) external view returns (address); // Add an entry to the index. Incresases the entry count. function add(address) external returns (bool); - // Remove an entry from the index. Reduces the entry count. - function remove(address) external returns (bool); - - // Verify that the entry exists in the index + // Verify that the entry exists in the index. function have(address) external view returns (bool); - // Deactivate account but keep in index. Does not affect entry count. - function deactivate(address) external returns (bool); - - // Activate previously deactivated account. Does not affect entry count. - function activate(address) external returns (bool); - - // Check if account exists and is active; - function isActive(address) external view returns (bool); - - // Retrieve the timestamp when account was added + // Retrieve the timestamp when account was added. + // If time is not being tracked, a value of 0 should be returned. function time(address) external view returns (uint256); } diff --git a/solidity/Expire.sol b/solidity/Expire.sol index 4cb6af4..94b53aa 100644 --- a/solidity/Expire.sol +++ b/solidity/Expire.sol @@ -2,12 +2,22 @@ pragma solidity >=0.6.12; // Author: Louis Holbrook 0826EDA1702D1E87C6E2875121D2E7BB88C2A746 // SPDX-License-Identifier: AGPL-3.0-or-later -// File-version: 2 +// File-version: 3 interface IExpire { - // Expiration timestamp has been changed. + // Contract has expired. event Expired(uint256 _timestamp); + // Expiry time has changed. + event ExpiryChange(uint256 indexed _oldTimestamp, uint256 _newTimestamp); + // The current expiration timestamp. function expires() external returns (uint256); + + // Check expiry and apply expiration if expired. + // Return values must be: + // 0: not yet expired. + // 1: already expired. + // >1: expiry executed. + function applyExpiry() external returns(uint8); } diff --git a/solidity/Locator.sol b/solidity/Locator.sol index dc21167..a7bf079 100644 --- a/solidity/Locator.sol +++ b/solidity/Locator.sol @@ -5,9 +5,9 @@ pragma solidity >=0.6.12; // File-version: 3 interface ILocator { - // URI that may or may not point to a specific resource location + // URI that may or may not point to a specific resource location. function toURI(bytes memory _data) external view returns (string memory); - // URL pointing to a specific resource location + // URL pointing to a specific resource location. function toURL(bytes memory _data) external view returns(string memory); } diff --git a/solidity/RegistryClient.sol b/solidity/RegistryClient.sol index 1cedd10..a338633 100644 --- a/solidity/RegistryClient.sol +++ b/solidity/RegistryClient.sol @@ -5,11 +5,14 @@ pragma solidity >=0.6.12; // File-version: 3 interface IRegistryClient { + // Address added to store with the given key + event AddressKey(bytes32 indexed _key, address _address); + // Return the address of the contract identified by the given byte string function addressOf(bytes32) external view returns (address); // Indexed accessor for the full list of registred identifiers - function identifiers(uint256) external view returns (bytes32); + function identifier(uint256) external view returns (bytes32); // Number of registered interfaces function identifierCount() external view returns (uint256); diff --git a/solidity/Writer.sol b/solidity/Writer.sol index bcd2553..de0348e 100644 --- a/solidity/Writer.sol +++ b/solidity/Writer.sol @@ -2,14 +2,14 @@ pragma solidity >=0.6.12; // Author: Louis Holbrook 0826EDA1702D1E87C6E2875121D2E7BB88C2A746 // SPDX-License-Identifier: AGPL-3.0-or-later -// File-version: 3 +// File-version: 4 interface IWriter { // A writer has been added by _executor - event WriterAdded(address indexed _executor, address _writer); + event WriterAdded(address _writer); // A writer has been removed by _executor - event WriterDeleted(address indexed _executor, address _writer); + event WriterDeleted(address _writer); // Add a new writer to the contract. function addWriter(address _writer) external returns (bool); From b3f6e45696a261da379483ee38e39316b63e1e2b Mon Sep 17 00:00:00 2001 From: lash Date: Sun, 26 Mar 2023 12:04:31 +0100 Subject: [PATCH 08/10] Add Digest interface --- doc/texinfo/chrono.sol.texi | 15 +++++++++++++++ doc/texinfo/digest.sol.texi | 17 +++++++++++++++++ doc/texinfo/expire.sol.texi | 2 ++ doc/texinfo/locator.sol.texi | 2 ++ doc/texinfo/msg.sol.texi | 2 ++ doc/texinfo/multihash.sol.texi | 25 ------------------------- doc/texinfo/overview.texi | 4 ++-- doc/texinfo/seal.sol.texi | 31 +++++++++++++++++++++++++++++++ doc/texinfo/writer.sol.texi | 2 ++ solidity/AccountsIndexMutable.sol | 27 +++++++++++++++++++++++++++ solidity/Chrono.sol | 11 +++++++++++ solidity/Digest.sol | 23 +++++++++++++++++++++++ solidity/ERC5007.sol | 15 +++++++++++++++ solidity/ERC5192.sol | 17 +++++++++++++++++ solidity/Locator.sol | 2 +- solidity/MultiHash.sol | 6 ++++-- 16 files changed, 171 insertions(+), 30 deletions(-) create mode 100644 doc/texinfo/chrono.sol.texi create mode 100644 doc/texinfo/digest.sol.texi delete mode 100644 doc/texinfo/multihash.sol.texi create mode 100644 doc/texinfo/seal.sol.texi create mode 100644 solidity/AccountsIndexMutable.sol create mode 100644 solidity/Chrono.sol create mode 100644 solidity/Digest.sol create mode 100644 solidity/ERC5007.sol create mode 100644 solidity/ERC5192.sol diff --git a/doc/texinfo/chrono.sol.texi b/doc/texinfo/chrono.sol.texi new file mode 100644 index 0000000..6d47a49 --- /dev/null +++ b/doc/texinfo/chrono.sol.texi @@ -0,0 +1,15 @@ +@subsection Chrono + +Define a creation time for a resource. + +Complements @code{ERC5007}. + + +@table @dfn +@item ERC165 Interface identifier +@include ../../build/Chrono.interface +@item Solidity interface definition +@include ../../build/contract_Chrono.texi +@item Example implementation +@uref{https://git.defalsify.org/eth-erc721} (BadgeToken contract) +@end table diff --git a/doc/texinfo/digest.sol.texi b/doc/texinfo/digest.sol.texi new file mode 100644 index 0000000..9447986 --- /dev/null +++ b/doc/texinfo/digest.sol.texi @@ -0,0 +1,17 @@ +@subsection Digest + +Allows encoding of digests according to a specific encoding scheme. + +Primary use-case is the abstraction of self-describing @uref{https://multiformats.io/multihash/,Multhash} encoding. + +A default encoding @emph{must} always be defined, and the encoding of a valid digest @emph{must} succeed with the default encoding. + + +@table @dfn +@item ERC165 Interface identifier +@include ../../build/Digest.interface +@item Solidity interface definition +@include ../../build/contract_Digest.texi +@item Example implementation +@uref{git://holbrook.no/eth-event-msg.git} +@end table diff --git a/doc/texinfo/expire.sol.texi b/doc/texinfo/expire.sol.texi index d4a57f7..9ecacda 100644 --- a/doc/texinfo/expire.sol.texi +++ b/doc/texinfo/expire.sol.texi @@ -10,4 +10,6 @@ A contract defining an expiry @emph{must not} allow changing the expiration time @include ../../build/Expire.interface @item Solidity interface definition @include ../../build/contract_Expire.texi +@item Example implementation +@uref{https://git.grassecon.net/cicnet/erc20-demurrage-token.git} @end table diff --git a/doc/texinfo/locator.sol.texi b/doc/texinfo/locator.sol.texi index 0cdaa93..5e88a33 100644 --- a/doc/texinfo/locator.sol.texi +++ b/doc/texinfo/locator.sol.texi @@ -13,6 +13,8 @@ Furthermore, it @emph{should} be possible to refer to a resource by a fully-qua @include ../../build/Locator.interface @item Solidity interface definition @include ../../build/contract_Locator.texi +@item Example implementation +@uref{git://holbrook.no/eth-event-msg.git} @end table diff --git a/doc/texinfo/msg.sol.texi b/doc/texinfo/msg.sol.texi index 787b383..aaa7e33 100644 --- a/doc/texinfo/msg.sol.texi +++ b/doc/texinfo/msg.sol.texi @@ -12,4 +12,6 @@ The interface complements @code{Locator} and @code{MultiHash} to generate locat @include ../../build/Msg.interface @item Solidity interface definition @include ../../build/contract_Msg.texi +@item Example implementation +@uref{git://holbrook.no/eth-event-msg.git} @end table diff --git a/doc/texinfo/multihash.sol.texi b/doc/texinfo/multihash.sol.texi deleted file mode 100644 index f48643f..0000000 --- a/doc/texinfo/multihash.sol.texi +++ /dev/null @@ -1,25 +0,0 @@ -@subsection Multihash - -A complement to @code{Locator}, enabling validation and generation of multihashes for multicodecs that have been registered to the contract. - - -@table @dfn -@item ERC165 Interface identifier -@include ../../build/MultiHash.interface -@item Solidity interface definition -@include ../../build/contract_MultiHash.texi -@end table - - -@subsubsection Using @code{Multihash} with @code{Locator} - -Given the data @code{foo}, the digest algorithm @code{sha256} (multihash prefix @code{1220}) and a base url @code{https://contentgateway.grassecon.net}, the result of the methods may be as follows: - -@table @code -@item toURI(sha256(foo)) --> @code{"sha256:2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae"} -@item toURL(sha256(foo)) --> @code{"https://contentgateway.grassecon.net/12202c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae"} -@item tokenURI(toUint(sha256(foo))) --> @code{"https://contentgateway.grassecon.net/12202c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae"} -@end table diff --git a/doc/texinfo/overview.texi b/doc/texinfo/overview.texi index fa91764..9833f65 100644 --- a/doc/texinfo/overview.texi +++ b/doc/texinfo/overview.texi @@ -50,6 +50,8 @@ The following well-known solidity interfaces are partially implemented in CIC na @include declarator.sol.texi +@include digest.sol.texi + @include expire.sol.texi @include faucet.sol.texi @@ -60,8 +62,6 @@ The following well-known solidity interfaces are partially implemented in CIC na @include msg.sol.texi -@include multihash.sol.texi - @include registry.sol.texi @include seal.sol.texi diff --git a/doc/texinfo/seal.sol.texi b/doc/texinfo/seal.sol.texi new file mode 100644 index 0000000..de03540 --- /dev/null +++ b/doc/texinfo/seal.sol.texi @@ -0,0 +1,31 @@ +@subsection Seal + +Some smart contract parameters may need to be mutable over part of a smart contract's lifetime. + +This interface provides a method to explicitly signal when certain parameters have been rendered immutable. + +The value of @code{sealState()} @emph{must not} decrease, and must not exceed @code{maxSealState}. + +@code{maxSealState} is used to define that @emph{all mutable parameters} have been rendered immutable. The practical implications of this will vary between contracts. + +The implementer is encouraged to use simple, descriptive names in the source code to describe the applicable seal states. + +Use cases of sealing include: + +@itemize +@item +Whether more tokens can be minted +@item +Allow ownership of a contract to be transferred +@item +The expiry time of a token (see @code{Expire}) +@end itemize + +@table @dfn +@item ERC165 Interface identifier +@include ../../build/Seal.interface +@item Solidity interface definition +@include ../../build/contract_Seal.texi +@item Example implementation +@uref{https://git.grassecon.net/cicnet/erc20-demurrage-token.git} +@end table diff --git a/doc/texinfo/writer.sol.texi b/doc/texinfo/writer.sol.texi index 25d0756..50eb3ab 100644 --- a/doc/texinfo/writer.sol.texi +++ b/doc/texinfo/writer.sol.texi @@ -24,4 +24,6 @@ Edit access control lists. @include ../../build/Writer.interface @item Solidity interface definition @include ../../build/contract_Writer.texi +@item Example implementation +@uref{https://git.grassecon.net/cicnet/erc20-demurrage-token.git} @end table diff --git a/solidity/AccountsIndexMutable.sol b/solidity/AccountsIndexMutable.sol new file mode 100644 index 0000000..fb4f9cb --- /dev/null +++ b/solidity/AccountsIndexMutable.sol @@ -0,0 +1,27 @@ +pragma solidity >=0.6.12; + +// Author: Louis Holbrook 0826EDA1702D1E87C6E2875121D2E7BB88C2A746 +// SPDX-License-Identifier: AGPL-3.0-or-later +// File-version: 1 + +// Extends the AccountsIndex contract to enable account removal and deactivation. + +interface IAccountsIndexMutable { + // Active status of address changed, and by whom changed. + event AddressActive(address indexed _account, bool _active); + + // Address removed from store, and by whom removed. + event AddressRemoved(address _account); + + // Remove an entry from the index. Reduces the entry count. + function remove(address) external returns (bool); + + // Deactivate account but keep in index. Does not affect entry count. + function deactivate(address) external returns (bool); + + // Activate previously deactivated account. Does not affect entry count. + function activate(address) external returns (bool); + + // Check if account exists and is active; + function isActive(address) external view returns (bool); +} diff --git a/solidity/Chrono.sol b/solidity/Chrono.sol new file mode 100644 index 0000000..b6a6351 --- /dev/null +++ b/solidity/Chrono.sol @@ -0,0 +1,11 @@ +pragma solidity >=0.6.12; + +// Author: Louis Holbrook 0826EDA1702D1E87C6E2875121D2E7BB88C2A746 +// SPDX-License-Identifier: AGPL-3.0-or-later +// File-version: 1 + +interface IChrono { + // Returns the timestamp of when a resource corresponding to _idx was first created. + // int64 chosen as return value for simpler interoperability with ERC5007. + function createTime(uint256 _idx) external returns(int64); +} diff --git a/solidity/Digest.sol b/solidity/Digest.sol new file mode 100644 index 0000000..6fcd8fe --- /dev/null +++ b/solidity/Digest.sol @@ -0,0 +1,23 @@ +pragma solidity >=0.6.12; + +// Author: Louis Holbrook 0826EDA1702D1E87C6E2875121D2E7BB88C2A746 +// SPDX-License-Identifier: AGPL-3.0-or-later +// File-version: 1 + +interface IDigest { + // Returns the default digest encoding used by the contract instance. + function defaultDigestEncoding() external view returns (uint256 _encoding); + + // Check if the given encoding has been implemented in the contract instance. + function haveDigestEncoding(uint256 _codec) external view returns(bool); + + // Verify and encode the given digest for a specific hashing algorithm. + // Returns a zero-length byte array if digest is invalid. + // Must succeed if called with the defaultDigestEncoding and a valid digest. + function encodeDigest(bytes memory _data, uint256 _encoding) external view returns (bytes memory); + + // Encodes the digest using the default digest encoding. + // Returns a zero-length byte array if digest is invalid. + // Must succeed with a valid digest. + function encodeDigest(bytes memory _data) external view returns (bytes memory); +} diff --git a/solidity/ERC5007.sol b/solidity/ERC5007.sol new file mode 100644 index 0000000..1faeef1 --- /dev/null +++ b/solidity/ERC5007.sol @@ -0,0 +1,15 @@ +pragma solidity >=0.6.12; + +// Author: Louis Holbrook 0826EDA1702D1E87C6E2875121D2E7BB88C2A746 +// SPDX-License-Identifier: AGPL-3.0-or-later +// File-version: 4 + +// This is a representation of an officially approved Ethereum Improvement Proposal, written by Anders (@0xanders), Lance (@LanceSnow), Shrug . +// It was released under the CC0 license. +// The proposal source used as reference was a Markdown file with the following digest: +// - sha256:ec5a3d25822e616e032ef27faeb9a7191147a7b18064d95807df20fbc6b69870 + +interface IERC5007 { + function startTime(uint256 tokenId) external view returns (int64); + function endTime(uint256 tokenId) external view returns (int64); +} diff --git a/solidity/ERC5192.sol b/solidity/ERC5192.sol new file mode 100644 index 0000000..166557f --- /dev/null +++ b/solidity/ERC5192.sol @@ -0,0 +1,17 @@ +pragma solidity >=0.6.12; + +// Author: Louis Holbrook 0826EDA1702D1E87C6E2875121D2E7BB88C2A746 +// SPDX-License-Identifier: AGPL-3.0-or-later +// File-version: 4 + +// This is a representation of an officially approved Ethereum Improvement Proposal, written by Tim Daubenschütz (@TimDaub), Anders (@0xanders). +// It was released under the CC0 license. +// The proposal source used as reference was a Markdown file with the following digest: +// - sha256:c746922587ede699bd1560be0c0db5599104a25c976077d20706ec05340b3b7a + +interface IERC5192 { + event Locked(uint256 tokenId); + event Unlocked(uint256 tokenId); + + function locked(uint256 tokenId) external view returns (bool); +} diff --git a/solidity/Locator.sol b/solidity/Locator.sol index a7bf079..544026c 100644 --- a/solidity/Locator.sol +++ b/solidity/Locator.sol @@ -2,7 +2,7 @@ pragma solidity >=0.6.12; // Author: Louis Holbrook 0826EDA1702D1E87C6E2875121D2E7BB88C2A746 // SPDX-License-Identifier: AGPL-3.0-or-later -// File-version: 3 +// File-version: 4 interface ILocator { // URI that may or may not point to a specific resource location. diff --git a/solidity/MultiHash.sol b/solidity/MultiHash.sol index 2b76211..09d1593 100644 --- a/solidity/MultiHash.sol +++ b/solidity/MultiHash.sol @@ -15,8 +15,10 @@ interface IMultiHash { } // All registered multicodecs - function multiCodec(uint256 _codec) external view returns(MultiHash memory); + function digestCodec(uint256 _codec) external view returns(MultiHash memory); + + function haveDigestEncoding(uint256 _codec) external view returns(bool); // Generate a multihash from the given digest and current selected multicodec - function toMultiHash(uint256 _codec, bytes memory _digest) external view returns(bytes memory); + function encodeDigest(uint256 _codec, bytes memory _digest) external view returns(bytes memory); } From c2c9581dab32a708dc53fe3a8e1d6520305463ac Mon Sep 17 00:00:00 2001 From: lash Date: Sun, 26 Mar 2023 12:06:12 +0100 Subject: [PATCH 09/10] Update gitignore --- .gitignore | 3 +++ 1 file changed, 3 insertions(+) diff --git a/.gitignore b/.gitignore index 7a70e94..108b3af 100644 --- a/.gitignore +++ b/.gitignore @@ -3,3 +3,6 @@ gmon.out dist build *.egg-info +solidity/*.json +solidity/*.interface +solidity/*.bin From 2eba8c62541781320ab17e86506d6558734e60aa Mon Sep 17 00:00:00 2001 From: lash Date: Sun, 7 May 2023 19:01:06 +0100 Subject: [PATCH 10/10] Add token vote interfaces --- doc/texinfo/overview.texi | 18 +++++++++-- doc/texinfo/tokenvend.sol.texi | 21 +++++++++++++ doc/texinfo/tokenvote.sol.texi | 23 ++++++++++++++ doc/texinfo/writer.sol.texi | 4 +-- solidity/Offline.sol | 23 ++++++++++++++ solidity/TokenVend.sol | 16 ++++++++++ solidity/TokenVote.sol | 56 ++++++++++++++++++++++++++++++++++ 7 files changed, 156 insertions(+), 5 deletions(-) create mode 100644 doc/texinfo/tokenvend.sol.texi create mode 100644 doc/texinfo/tokenvote.sol.texi create mode 100644 solidity/Offline.sol create mode 100644 solidity/TokenVend.sol create mode 100644 solidity/TokenVote.sol diff --git a/doc/texinfo/overview.texi b/doc/texinfo/overview.texi index 9833f65..6948583 100644 --- a/doc/texinfo/overview.texi +++ b/doc/texinfo/overview.texi @@ -8,9 +8,12 @@ CIC smart contracts are implemented using the @emph{solidity} programming language for the (Ethereum Virtual Machine (EVM). -@section Inherited ERC definitions +@section Adopted standards -@subsection Direct use +@subsection Signing + + +@subsection ERC - Direct use The following well-known solidity interfaces are used directly. @@ -23,6 +26,10 @@ The following well-known solidity interfaces are used directly. @item @uref{https://eips.ethereum.org/EIPS/eip-173, ERC173 - Contract Ownership Standard} @item +@uref{https://eips.ethereum.org/EIPS/eip-191, ERC191 - Signed Data Standard} +@item +@uref{https://eips.ethereum.org/EIPS/eip-712, ERC712 - Typed structured data hashing and signing} +@item @uref{https://eips.ethereum.org/EIPS/eip-721, ERC721 - Non-Fungible Token Standard} @item @uref{https://eips.ethereum.org/EIPS/eip-5007, ERC5007 - Time NFT (EIP-721 Time Extension)} @@ -31,10 +38,11 @@ The following well-known solidity interfaces are used directly. @end itemize -@subsection Partial use +@subsection ERCs Partial use The following well-known solidity interfaces are partially implemented in CIC native interfaces. @itemize @dfn + @item @uref{https://eips.ethereum.org/EIPS/eip-5679, ERC5679 - Token Minting and Burning} (See @code{Minter}, @code{Burner}) @end itemize @@ -66,4 +74,8 @@ The following well-known solidity interfaces are partially implemented in CIC na @include seal.sol.texi +@include tokenvend.sol.texi + +@include tokenvote.sol.texi + @include writer.sol.texi diff --git a/doc/texinfo/tokenvend.sol.texi b/doc/texinfo/tokenvend.sol.texi new file mode 100644 index 0000000..9cbc584 --- /dev/null +++ b/doc/texinfo/tokenvend.sol.texi @@ -0,0 +1,21 @@ +@subsection TokenVend + +This interface defines the mechanism for which a specific ERC20 token may be exchanged for a different ERC20 token. + +A typical use-case is generation of voting tokens based on a momentary voucher balance. This is especially useful if the original ERC20 token is subject to decay (demurrage). + +The tokens used for exchange @strong{SHOULD} be locked for the full duration of holding the vended tokens. + +The withdrawal function may or may not allow partial withdrawals. + +@table @dfn +@item ERC165 Interface identifier +@include ../../build/TokenVend.interface +@item Solidity interface definition +@include ../../build/contract_TokenVend.texi +@item Reference implementations +@itemize +@item +@uref{git://holbrook.no/erc20-vend.git,} +@end itemize +@end table diff --git a/doc/texinfo/tokenvote.sol.texi b/doc/texinfo/tokenvote.sol.texi new file mode 100644 index 0000000..bb0c16d --- /dev/null +++ b/doc/texinfo/tokenvote.sol.texi @@ -0,0 +1,23 @@ +@anchor{token_vote} +@subsection TokenVote + +Execute elections with granular ERC20 token votes. + +A proposal submitted for vote may or may not contain multiple options. If multiple options are available, an ERC20 token holder may distribute its vote among the options with the granularity of the token balance. + +Voted tokens @strong{SHOULD} be locked until the voting has finalized. + +Finalization of voting should be callable by anyone. + + +@table @dfn +@item ERC165 Interface identifier +@include ../../build/TokenVote.interface +@item Solidity interface definition +@include ../../build/contract_TokenVote.texi +@item Reference implementations +@itemize +@item +@uref{git://holbrook.no/evm-tokenvote.git,} +@end itemize +@end table diff --git a/doc/texinfo/writer.sol.texi b/doc/texinfo/writer.sol.texi index 50eb3ab..a9a9586 100644 --- a/doc/texinfo/writer.sol.texi +++ b/doc/texinfo/writer.sol.texi @@ -4,9 +4,9 @@ A complement to ERC173, which allows definition of a class of super-users for a A super-user address may perform @emph{more} actions than a "normal" address, aswell as @emph{some} actions normally limited to the @emph{contract owner}. -No super-user should be able to perform actions that @emph{contract owner} cannot perform. +If an @emph{contract owner} is defined, No super-user should be able to perform actions that @emph{contract owner} cannot perform. -Typically, only the @emph{contract owner} can add or remove a super-user. +Typically, only the @emph{contract owner}, if it is defined, can add or remove a super-user. Some use-case examples of super-user actions include: diff --git a/solidity/Offline.sol b/solidity/Offline.sol new file mode 100644 index 0000000..545e385 --- /dev/null +++ b/solidity/Offline.sol @@ -0,0 +1,23 @@ +pragma solidity >=0.6.12; + +// Author: Louis Holbrook 0826EDA1702D1E87C6E2875121D2E7BB88C2A746 +// SPDX-License-Identifier: AGPL-3.0-or-later +// File-version: 1 + + +interface IOffline { + // Verify signer and data + // Check input assuming signature is valid against contract instance. + function isOfflineValid(address _signer, bytes memory _data) external view returns(bool); + + // Verify signature against data, and isOfflineValid() against data and signer (as validator) + // Signature must be ERC191 version 0x00 with contract instance as validator. + function verifyOfflineRequest(bytes memory _data, bytes memory _signature) external view returns(bool); + + // Change state if signature and signer is valid. + // Call verifyOfflineRequest and: + // - revert if it returns false. + // - return 0 if state is changed according to the request. + // - return any other valid to indicate an application specific error. + function executeOfflineRequest(bytes memory _data, bytes memory _signature) external returns(uint256); +} diff --git a/solidity/TokenVend.sol b/solidity/TokenVend.sol new file mode 100644 index 0000000..6661875 --- /dev/null +++ b/solidity/TokenVend.sol @@ -0,0 +1,16 @@ +pragma solidity >=0.6.12; + +// Author: Louis Holbrook 0826EDA1702D1E87C6E2875121D2E7BB88C2A746 +// SPDX-License-Identifier: AGPL-3.0-or-later +// File-version: 1 + +interface ITokenVend { + // A new vended token has been created. + event TokenCreated(uint256 indexed _tokenIdx, uint256 indexed _supply, address _token); + + // Create corresponding vended tokens for the control token balance of the caller. + function getFor(address _token) external returns (uint256); + + // Recover control tokens that were used to retrieve the corresponding vended tokens. + function withdrawFor(address _token) external returns (uint256); +} diff --git a/solidity/TokenVote.sol b/solidity/TokenVote.sol new file mode 100644 index 0000000..b91e4e9 --- /dev/null +++ b/solidity/TokenVote.sol @@ -0,0 +1,56 @@ +pragma solidity >=0.6.12; + +// Author: Louis Holbrook 0826EDA1702D1E87C6E2875121D2E7BB88C2A746 +// SPDX-License-Identifier: AGPL-3.0-or-later +// File-version: 1 + + +interface ITokenVote { + + // A new proposal has been created. + event ProposalAdded(uint256 indexed _blockDeadline, uint256 indexed voteTargetPpm, uint256 indexed _proposalIdx); + + // A proposal vote has been completed. + // The proposal is identified by the serial number in _proposalIdx. It is up to the implementer to define how the proposal should be retrieved by index. + // The proposal result may be in one of three states: + // * Ratified (_cancelled == false, _insufficient == false) + // * Cancelled (_cancelled == true, _insufficient == false) + // * Not reached quorum (_cancelled == false, _insufficient == true) + event ProposalCompleted(uint256 indexed _proposalIdx, bool indexed _cancelled, bool indexed _insufficient, uint256 _totalVote); + + // Propose a new vote. + // Voting is active until one of: + // * total cancel vote reach quorum (_targetVotePpm, ppm = parts-per-million). + // * _blockWait blocks from now. + function propose(bytes32 _description, uint256 _blockWait, uint24 _targetVotePpm) external returns (uint256); + + // Same as propose(...), but provide options to vote on. + function proposeMulti(bytes32 _description, bytes32[] memory _options, uint256 _blockWait, uint24 _targetVotePpm) external returns (uint256); + + // Get proposal option. Assumes that proposal was created with proposeMulti(...) + function getOption(uint256 _proposalIdx, uint256 _optionIdx) external view returns (bytes32); + + // Get vote count for the given option. + // If proposal has no options, it should be called with _optionIdx = 0 + function voteCount(uint256 _proposalIdx, uint256 _optionIdx) external view returns(uint256); + + // Vote on a proposal without options. + // Assumes that proposal was created with propose(...) and will fail otherwise. + function vote(uint256 _value) external returns (bool); + + // Vote on a proposal option. Assumes that proposal was created with proposeMulti(...). + // Must work with a non-option proposal if _optionIndex is 0. + function voteOption(uint256 _optionIndex, uint256 _value) external returns (bool); + + // Vote to cancel a proposal. + // If cancel has the majority: + // * A vote without options will have rejected the proposal description. + // * A vote with options will have rejected the proposal description as well as all option descriptions. + function voteCancel(uint256 _value) external returns (bool); + + // Finalize the vote for a proposal. + // May be called if deadline has been passed, or if: + // * quorum has been reached with cancel votes. + // * quorum has been reached and proposal has no/only one option. + function finalize() external returns (bool); +}