# Smart contract interfaces
## Technology
CIC smart contracts are implemented using the *solidity* programming
language for the (Ethereum Virtual Machine (EVM).
## Adopted standards
### Signing
### ERC - Direct use
The following well-known solidity interfaces are used directly.
- [ERC20 - Token Standard](https://eips.ethereum.org/EIPS/eip-20)
- [ERC165 - Standard Interface
Detection](https://eips.ethereum.org/EIPS/eip-165)
- [ERC173 - Contract Ownership
Standard](https://eips.ethereum.org/EIPS/eip-173)
- [ERC191 - Signed Data
Standard](https://eips.ethereum.org/EIPS/eip-191)
- [ERC712 - Typed structured data hashing and
signing](https://eips.ethereum.org/EIPS/eip-712)
- [ERC721 - Non-Fungible Token
Standard](https://eips.ethereum.org/EIPS/eip-721)
- [ERC5007 - Time NFT (EIP-721 Time
Extension)](https://eips.ethereum.org/EIPS/eip-5007)
- [ERC5192 - Minimal Soulbound
NFTs](https://eips.ethereum.org/EIPS/eip-5192)
### ERCs Partial use
The following well-known solidity interfaces are partially implemented
in CIC native interfaces.
- [ERC5679 - Token Minting and
Burning](https://eips.ethereum.org/EIPS/eip-5679) (See `Minter`,
`Burner`)
## Native interfaces
### Accounts Index
Append-only list of addresses. Typically used for access control lists.
Addresses may be *added*, *removed*, aswell as *deactivated* and
*activated*. Deactivated accounts still count towards the `entryCount`.
The `entry` method is used to iterate the account list. The order of
which accounts are returned is not guaranteed. Any returned value
matching `address(0x00)` should be skipped, and not counted towards
`entryCount`.
May optionally record time when account was added.
ERC165 Interface identifier
b7bca625
Solidity interface definition
interface IAccountsIndex {
// Address added to store, index in array.
event AddressAdded(uint256 indexed _idx, 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 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);
// Verify that the entry exists in the index.
function have(address) external view returns (bool);
// 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);
}
Reference implementation
<git://holbrook.no/eth-accounts-index.git> (v0.5.1)
### Accounts Index Mutable
Extends the functionality of `Accounts Index` to allow changes to the
address list.
Addresses may be *added*, *removed*, aswell as *deactivated* and
*activated*. Deactivated accounts still count towards the `entryCount`.
ERC165 Interface identifier
9479f0ae
Solidity interface definition
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);
}
Reference implementation
<git://holbrook.no/eth-accounts-index.git> (v0.5.1)
### Burner
Attached to `ERC20` and `ERC721` tokens that may be *burned*.
Implements the `burn(...)` part of `ERC5679` for interoperability.
ERC165 Interface identifier
bc4babdd
Solidity interface definition
interface IBurner {
// 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);
}
Example implementation
<https://git.grassecon.net/cicnet/erc20-demurrage-token.git>
### Chrono
Define a creation time for a resource.
Complements `ERC5007`.
ERC165 Interface identifier
4db1ccd4
Solidity interface definition
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);
}
Example implementation
<https://git.defalsify.org/eth-erc721> (BadgeToken contract)
### 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 value of `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.
ERC165 Interface identifier
21b7493b
Solidity interface definition
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
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 );
}
Reference implementation
<git://holbrook.no/eth-address-index.git>
### Digest
Allows encoding of digests according to a specific encoding scheme.
Primary use-case is the abstraction of self-describing
[Multhash](https://multiformats.io/multihash/) encoding.
A default encoding *must* always be defined, and the encoding of a valid
digest *must* succeed with the default encoding.
ERC165 Interface identifier
982ab05d
Solidity interface definition
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);
}
Example implementation
<git://holbrook.no/eth-event-msg.git>
### Expire
Defines an expiry time after which token balances or supply *cannot
change*.
A contract defining an expiry *must not* allow changing the expiration
time to a time in the past.
ERC165 Interface identifier
841a0e94
Solidity interface definition
interface IExpire {
// 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);
}
Example implementation
<https://git.grassecon.net/cicnet/erc20-demurrage-token.git>
### Faucet
Used for dispensing tokens to any address.
It can be used for gas tokens and *ERC20* alike.
The interface is the same whether the faucet is dispensing from existing
balance or minting new tokens.
The value dispersed *must* be the same for all addresses.
In general, four criteria are expected to exist in any combination for
limiting access to the faucet:
Time
A recipient may only use the faucet again after some time has passed.
Balance threshold
A recipient may only use the faucet after its balance is below a certain
amount.
Membership
A recipient may only use the faucet if it has been added to an access
control list.
Capacity
The contract has sufficient token funds to dispense the current defined
amount to dispense.
The *check(address)* contract call *must* evaluate all four criteria,
and *must* return `false` if any of the criteria are not met.
ERC165 Interface identifier
1a3ac634
Solidity interface definition
interface IFaucet {
// 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);
}
Reference implementations
- <git://holbrook.no/erc20-faucet.git>
- <git://holbrook.no/eth-faucet.git>
### Locator
This interface supports `ERC721 Metadata`, in particular the
`tokenURI(uint256)` call.
Off-chain resources in the CIC network *must* be defined in terms of
content addressed strings.
It *must* be possible to refer to all off-chain resources directly by
the content address.
Furthermore, it *should* be possible to refer to a resource by a
fully-qualified location on the web or an overlay network (e.g. tor).
ERC165 Interface identifier
ed75b333
Solidity interface definition
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);
}
Example implementation
<git://holbrook.no/eth-event-msg.git>
#### Expressing locators in terms of numetic token id
Given the numeric token id `1234567890987654321` (`0x112210f4b16c1cb1`
hex), and a base url `https://contentgateway.grassecon.net`, the result
of the methods may be as follows:
`toURI(toHex(1234567890987654321))`
-\>
`https://contentgateway.grassecon.net/000000000000000000000000000000000000000000000000112210f4b16c1cb1`
`toURL(toHex(1234567890987654321))`
-\>
`https://contentgateway.grassecon.net/000000000000000000000000000000000000000000000000112210f4b16c1cb1`
`tokenURI(1234567890987654321)`
-\>
`https://contentgateway.grassecon.net/000000000000000000000000000000000000000000000000112210f4b16c1cb1`
#### Expressing locators in terms of a digest
Given the data `foo`, the digest algorithm `sha256` and a base url
`https://contentgateway.grassecon.net`, the result of the methods may be
as follows:
`toURI(sha256(foo))`
-\>
`"sha256:2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae"`
`toURL(sha256(foo))`
-\>
`"https://contentgateway.grassecon.net/2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae"`
`tokenURI(toUint(sha256(foo)))`
-\>
`"https://contentgateway.grassecon.net/2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae"`
#### Locator without URL
Given the data `foo`, the digest algorithm `sha256` and no base url, the
result of the methods may be as follows:
`toURI(sha256(foo))`
-\>
`"sha256:2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae"`
`toURL(sha256(foo))`
-\> `""`
`tokenURI(toUint(sha256(foo)))`
-\>
`"sha256:2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae"`
### Minter
Attached to `ERC20` and `ERC721` tokens that may be minted.
Implements the `mint(...)` and `safeMint(...)` parts of `ERC5679` for
interoperability.
ERC165 Interface identifier
5878bcf4
Solidity interface definition
interface IMinter {
// 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;
}
Example implementation
<https://git.grassecon.net/cicnet/erc20-demurrage-token.git>
### 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 `Locator` and `MultiHash` to generate locators
for how to resolve the reference.
ERC165 Interface identifier
a3002595
Solidity interface definition
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);
}
Example implementation
<git://holbrook.no/eth-event-msg.git>
### 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:
1. Entry-point to discover all relevant contracts of CIC networks.
2. Unique (ERC20) token symbol resolver.
ERC165 Interface identifier
effbf671
Solidity interface definition
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 identifier(uint256) external view returns (bytes32);
// Number of registered interfaces
function identifierCount() external view returns (uint256);
}
Contract registry implementation
<git://holbrook.no/eth-contract-registry.git>
Token index implementation
<git://holbrook.no/eth-contract-registry.git>
### 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 `sealState()` *must not* decrease, and must not exceed
`maxSealState`.
`maxSealState` is used to define that *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:
- Whether more tokens can be minted
- Allow ownership of a contract to be transferred
- The expiry time of a token (see `Expire`)
ERC165 Interface identifier
0d7491f8
Solidity interface definition
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);
}
Example implementation
<https://git.grassecon.net/cicnet/erc20-demurrage-token.git>
### 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 **SHOULD** be locked for the full duration
of holding the vended tokens.
The withdrawal function may or may not allow partial withdrawals.
ERC165 Interface identifier
8a13249c
Solidity interface definition
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);
}
Reference implementations
- <git://holbrook.no/erc20-vend.git>
### 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 **SHOULD** be locked until the voting has finalized.
Finalization of voting should be callable by anyone.
ERC165 Interface identifier
28091366
Solidity interface definition
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 number of options available for the proposal.
// This decides the boundary of the index that can be used with voteOptions(...)
// If the result is 0, vote(...) can be used aswell.
function optionCount(uint256 _proposalIdx) external view 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);
}
Reference implementations
- <git://holbrook.no/evm-tokenvote.git>
### Writer
A complement to ERC173, which allows definition of a class of
super-users for a contract.
A super-user address may perform *more* actions than a "normal" address,
aswell as *some* actions normally limited to the *contract owner*.
If an *contract owner* is defined, No super-user should be able to
perform actions that *contract owner* cannot perform.
Typically, only the *contract owner*, if it is defined, can add or
remove a super-user.
Some use-case examples of super-user actions include:
- Mint new tokens.
- Change the amount dispensed by the faucet.
- Edit access control lists.
ERC165 Interface identifier
abe1f1f5
Solidity interface definition
interface IWriter {
// A writer has been added by _executor
event WriterAdded(address _writer);
// A writer has been removed by _executor
event WriterDeleted(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 view returns (bool);
}
Example implementation
<https://git.grassecon.net/cicnet/erc20-demurrage-token.git>
Raw data
{
"_id": null,
"home_page": "https://gitlab.com/cicnet/cic-contracts",
"name": "cic-contracts",
"maintainer": "",
"docs_url": null,
"requires_python": "<3.11,>=3.8",
"maintainer_email": "",
"keywords": "dlt,blockchain,cryptocurrency,ethereum",
"author": "Louis Holbrook",
"author_email": "dev@holbrook.no",
"download_url": "https://files.pythonhosted.org/packages/30/aa/46eb8b8049b657bad4e9f80c8369e2459f2437a68d04664b52e912fa98ce/cic-contracts-0.3.8.tar.gz",
"platform": null,
"description": "# Smart contract interfaces\n\n## Technology\n\nCIC smart contracts are implemented using the *solidity* programming\nlanguage for the (Ethereum Virtual Machine (EVM).\n\n## Adopted standards\n\n### Signing\n\n### ERC - Direct use\n\nThe following well-known solidity interfaces are used directly.\n\n- [ERC20 - Token Standard](https://eips.ethereum.org/EIPS/eip-20)\n\n- [ERC165 - Standard Interface\n Detection](https://eips.ethereum.org/EIPS/eip-165)\n\n- [ERC173 - Contract Ownership\n Standard](https://eips.ethereum.org/EIPS/eip-173)\n\n- [ERC191 - Signed Data\n Standard](https://eips.ethereum.org/EIPS/eip-191)\n\n- [ERC712 - Typed structured data hashing and\n signing](https://eips.ethereum.org/EIPS/eip-712)\n\n- [ERC721 - Non-Fungible Token\n Standard](https://eips.ethereum.org/EIPS/eip-721)\n\n- [ERC5007 - Time NFT (EIP-721 Time\n Extension)](https://eips.ethereum.org/EIPS/eip-5007)\n\n- [ERC5192 - Minimal Soulbound\n NFTs](https://eips.ethereum.org/EIPS/eip-5192)\n\n### ERCs Partial use\n\nThe following well-known solidity interfaces are partially implemented\nin CIC native interfaces.\n\n- [ERC5679 - Token Minting and\n Burning](https://eips.ethereum.org/EIPS/eip-5679) (See `Minter`,\n `Burner`)\n\n## Native interfaces\n\n### Accounts Index\n\nAppend-only list of addresses. Typically used for access control lists.\n\nAddresses may be *added*, *removed*, aswell as *deactivated* and\n*activated*. Deactivated accounts still count towards the `entryCount`.\n\nThe `entry` method is used to iterate the account list. The order of\nwhich accounts are returned is not guaranteed. Any returned value\nmatching `address(0x00)` should be skipped, and not counted towards\n`entryCount`.\n\nMay optionally record time when account was added.\n\nERC165 Interface identifier \nb7bca625\n\nSolidity interface definition \n interface IAccountsIndex {\n // Address added to store, index in array.\n event AddressAdded(uint256 indexed _idx, address _account);\n\n // Return number of entries in index.\n function entryCount() external view returns (uint256);\n\n // Return entry at the spceificed index.\n // Will revert if index is beyond array length.\n // An entry result of 0 means the entry should be skipped, and not count towards entry count.\n function entry(uint256) external view returns (address);\n\n // Add an entry to the index. Incresases the entry count.\n function add(address) external returns (bool);\n\n // Verify that the entry exists in the index.\n function have(address) external view returns (bool);\n\n // Retrieve the timestamp when account was added.\n // If time is not being tracked, a value of 0 should be returned.\n function time(address) external view returns (uint256);\n }\n\nReference implementation \n<git://holbrook.no/eth-accounts-index.git> (v0.5.1)\n\n### Accounts Index Mutable\n\nExtends the functionality of `Accounts Index` to allow changes to the\naddress list.\n\nAddresses may be *added*, *removed*, aswell as *deactivated* and\n*activated*. Deactivated accounts still count towards the `entryCount`.\n\nERC165 Interface identifier \n9479f0ae\n\nSolidity interface definition \n interface IAccountsIndexMutable {\n // Active status of address changed, and by whom changed.\n event AddressActive(address indexed _account, bool _active);\n\n // Address removed from store, and by whom removed.\n event AddressRemoved(address _account);\n\n // Remove an entry from the index. Reduces the entry count.\n function remove(address) external returns (bool);\n\n // Deactivate account but keep in index. Does not affect entry count.\n function deactivate(address) external returns (bool);\n\n // Activate previously deactivated account. Does not affect entry count.\n function activate(address) external returns (bool);\n\n // Check if account exists and is active;\n function isActive(address) external view returns (bool);\n }\n\nReference implementation \n<git://holbrook.no/eth-accounts-index.git> (v0.5.1)\n\n### Burner\n\nAttached to `ERC20` and `ERC721` tokens that may be *burned*.\n\nImplements the `burn(...)`\u00a0part of `ERC5679` for interoperability.\n\nERC165 Interface identifier \nbc4babdd\n\nSolidity interface definition \n interface IBurner {\n // Token(s) successfully burned; by who and how much.\n event Burn(address indexed _burner, uint256 _burned);\n\n // Satisfies ERC 5679\n function burn(address _from, uint256 _amount, bytes calldata _data) external;\n\n // Burn given amount of tokens held by signer.\n function burn(uint256 _burn) external returns (bool);\n\n // Burn all tokens held by signer.\n function burn() external returns (bool);\n\n // Total amount of tokens that have been burned.\n function totalBurned() external returns (uint256);\n\n // Total amount of tokens ever minted.\n // If totalSupply() is available (ERC20, ERC721 Enumerable), this equals totalSupply() + totalBurned().\n function totalMinted() external returns (uint256);\n }\n\nExample implementation \n<https://git.grassecon.net/cicnet/erc20-demurrage-token.git>\n\n### Chrono\n\nDefine a creation time for a resource.\n\nComplements `ERC5007`.\n\nERC165 Interface identifier \n4db1ccd4\n\nSolidity interface definition \n interface IChrono {\n // Returns the timestamp of when a resource corresponding to _idx was first created.\n // int64 chosen as return value for simpler interoperability with ERC5007.\n function createTime(uint256 _idx) external returns(int64);\n }\n\nExample implementation \n<https://git.defalsify.org/eth-erc721> (BadgeToken contract)\n\n### Declarator\n\nPermissionless store of signed claims made by an address about other\naddresses, or addresses about themselves.\n\nIt is used to declare or respond to certifications of vouchers, NFT,\nvoucher members.\n\nAddresses may be Externally Owned Accounts or smart contracts.\n\nClaims may be made with or without topics. A missing topic is synonymous\nwith a topic value of `bytes32(0x00)`.\n\nAny number of claims can be made about an address under any number of\ntopics. All claims must be stored, and returned in the order which they\nwere added.\n\nERC165 Interface identifier \n21b7493b\n\nSolidity interface definition \n interface IDeclarator {\n event DeclarationAdded(address indexed _declarator, address indexed _subject, bytes32 indexed _topic, bytes32 _proof);\n \n // Get all declarations for a subject (without topic) signed by a declarator\n function declaration(address _declarator, address _subject) external view returns ( bytes32[] memory );\n\n // Get all declarations for a subject for the given topic signed by a declarator\n function declaration(address _declarator, address _subject, bytes32 _topic) external view returns ( bytes32[] memory );\n\n // Get number of declarations the declarator has ever signed\n function declarationCount(address _declarator) external view returns ( uint256 );\n\n // Get the subject of a declarator's declarations at the specific index\n function declarationAddressAt(address _declarator, uint256 _idx) external view returns ( address );\n\n // Add a declaration for the subject\n function addDeclaration(address _subject, bytes32 _proof) external returns ( bool );\n\n // Add a declaration with topic for the subject\n function addDeclaration(address _subject, bytes32 _proof, bytes32 _topic) external returns ( bool );\n\n // Get the declarator that signed a declaration at the specificed index for a subject\n function declaratorAddressAt(address _subject, uint256 _idx) external view returns ( address );\n\n // Get the number of declarators that have signed for a subject\n function declaratorCount(address _subject) external view returns ( uint256 );\n }\n\nReference implementation \n<git://holbrook.no/eth-address-index.git>\n\n### Digest\n\nAllows encoding of digests according to a specific encoding scheme.\n\nPrimary use-case is the abstraction of self-describing\n[Multhash](https://multiformats.io/multihash/) encoding.\n\nA default encoding *must* always\u00a0be defined, and the encoding of a valid\ndigest *must* succeed with the default encoding.\n\nERC165 Interface identifier \n982ab05d\n\nSolidity interface definition \n interface IDigest {\n // Returns the default digest encoding used by the contract instance.\n function defaultDigestEncoding() external view returns (uint256 _encoding);\n\n // Check if the given encoding has been implemented in the contract instance.\n function haveDigestEncoding(uint256 _codec) external view returns(bool);\n\n // Verify and encode the given digest for a specific hashing algorithm.\n // Returns a zero-length byte array if digest is invalid.\n // Must succeed if called with the defaultDigestEncoding and a valid digest.\n function encodeDigest(bytes memory _data, uint256 _encoding) external view returns (bytes memory);\n\n // Encodes the digest using the default digest encoding.\n // Returns a zero-length byte array if digest is invalid.\n // Must succeed with a valid digest.\n function encodeDigest(bytes memory _data) external view returns (bytes memory);\n }\n\nExample implementation \n<git://holbrook.no/eth-event-msg.git>\n\n### Expire\n\nDefines an expiry time after which token balances or supply *cannot\nchange*.\n\nA contract defining an expiry *must not* allow changing the expiration\ntime to a time in the past.\n\nERC165 Interface identifier \n841a0e94\n\nSolidity interface definition \n interface IExpire {\n // Contract has expired.\n event Expired(uint256 _timestamp);\n\n // Expiry time has changed.\n event ExpiryChange(uint256 indexed _oldTimestamp, uint256 _newTimestamp);\n\n // The current expiration timestamp.\n function expires() external returns (uint256);\n\n // Check expiry and apply expiration if expired.\n // Return values must be:\n // 0: not yet expired.\n // 1: already expired.\n // >1: expiry executed.\n function applyExpiry() external returns(uint8);\n }\n\nExample implementation \n<https://git.grassecon.net/cicnet/erc20-demurrage-token.git>\n\n### Faucet\n\nUsed for dispensing tokens to any address.\n\nIt can be used for gas tokens and *ERC20* alike.\n\nThe interface is the same whether the faucet is dispensing from existing\nbalance or minting new tokens.\n\nThe value dispersed *must*\u00a0be the same for all addresses.\n\nIn general, four criteria are expected to exist in any combination for\nlimiting access to the faucet:\n\nTime \nA recipient may only use the faucet again after some time has passed.\n\nBalance threshold \nA recipient may only use the faucet after its balance is below a certain\namount.\n\nMembership \nA recipient may only use the faucet if it has been added to an access\ncontrol list.\n\nCapacity \nThe contract has sufficient token funds to dispense the current defined\namount to dispense.\n\nThe *check(address)* contract call *must* evaluate all four criteria,\nand *must* return `false`\u00a0if any of the criteria are not met.\n\nERC165 Interface identifier \n1a3ac634\n\nSolidity interface definition \n interface IFaucet {\n // Tokens were given to an address\n event Give(address indexed _recipient, address indexed _token, uint256 _value);\n\n // The amount that the faucet disperses has changed\n event FaucetAmountChange(uint256 _value);\n\n // Address of token the faucet represents\n // The faucet will return gas tokens with the zero-address is returned.\n function token() external returns (address);\n\n // Amount of tokens the faucet gives out\n function tokenAmount() external returns (uint256);\n\n // Give tokens to the given recipient. Returns amount of tokens given.\n function giveTo(address _recipient) external returns (uint256);\n\n // Give tokens to yourself. Returns amount of tokens given.\n function gimme() external returns (uint256);\n\n // Check if faucet may be used in the current contract state by _recipient\n function check(address _recipient) external view returns (bool);\n\n // Returns timestamp when faucet may be used again by _recipient\n // If 0 is returned, the address has not yet been used.\n // A return value of max(uint256) indicates that the faucet may not be used again.\n function nextTime(address _recipient) external returns (uint256);\n\n // Returns the token balance under which faucet may be used again by _recipient\n // A return value of max(uint256) indicates that the faucet may be used regardless\n // of the token balance of _recipient\n function nextBalance(address _recipient) external returns (uint256);\n }\n\nReference implementations \n- <git://holbrook.no/erc20-faucet.git>\n\n- <git://holbrook.no/eth-faucet.git>\n\n### Locator\n\nThis interface supports `ERC721 Metadata`, in particular the\n`tokenURI(uint256)` call.\n\nOff-chain resources in the CIC network *must* be defined in terms of\ncontent addressed strings.\n\nIt *must* be possible to refer to all off-chain resources directly by\nthe content address.\n\nFurthermore, it *should*\u00a0be possible to refer to a resource by a\nfully-qualified location on the web or an overlay network (e.g. tor).\n\nERC165 Interface identifier \ned75b333\n\nSolidity interface definition \n interface ILocator {\n // URI that may or may not point to a specific resource location.\n function toURI(bytes memory _data) external view returns (string memory);\n\n // URL pointing to a specific resource location.\n function toURL(bytes memory _data) external view returns(string memory);\n }\n\nExample implementation \n<git://holbrook.no/eth-event-msg.git>\n\n#### Expressing locators in terms of numetic token id\n\nGiven the numeric token id `1234567890987654321` (`0x112210f4b16c1cb1`\nhex), and a base url `https://contentgateway.grassecon.net`, the result\nof the methods may be as follows:\n\n`toURI(toHex(1234567890987654321))` \n-\\>\n`https://contentgateway.grassecon.net/000000000000000000000000000000000000000000000000112210f4b16c1cb1`\n\n`toURL(toHex(1234567890987654321))` \n-\\>\n`https://contentgateway.grassecon.net/000000000000000000000000000000000000000000000000112210f4b16c1cb1`\n\n`tokenURI(1234567890987654321)` \n-\\>\n`https://contentgateway.grassecon.net/000000000000000000000000000000000000000000000000112210f4b16c1cb1`\n\n#### Expressing locators in terms of a digest\n\nGiven the data `foo`, the digest algorithm `sha256` and a base url\n`https://contentgateway.grassecon.net`, the result of the methods may be\nas follows:\n\n`toURI(sha256(foo))` \n-\\>\n`\"sha256:2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae\"`\n\n`toURL(sha256(foo))` \n-\\>\n`\"https://contentgateway.grassecon.net/2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae\"`\n\n`tokenURI(toUint(sha256(foo)))` \n-\\>\n`\"https://contentgateway.grassecon.net/2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae\"`\n\n#### Locator without URL\n\nGiven the data `foo`, the digest algorithm `sha256` and no base url, the\nresult of the methods may be as follows:\n\n`toURI(sha256(foo))` \n-\\>\n`\"sha256:2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae\"`\n\n`toURL(sha256(foo))` \n-\\> `\"\"`\n\n`tokenURI(toUint(sha256(foo)))` \n-\\>\n`\"sha256:2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae\"`\n\n### Minter\n\nAttached to `ERC20` and `ERC721` tokens that may be minted.\n\nImplements the `mint(...)` and `safeMint(...)`\u00a0parts of `ERC5679` for\ninteroperability.\n\nERC165 Interface identifier \n5878bcf4\n\nSolidity interface definition \n interface IMinter {\n // Tokens are successfully minted; by who, to whom and how much\n event Mint(address indexed _minter, address indexed _beneficiary, uint256 value);\n\n // Mint the specified value of tokens to the specified recipient\n function mintTo(address _beneficiary, uint256 value) external returns (bool);\n\n // Satisfies ERC5679 for ERC20\n function mint(address _beneficiary, uint256 value, bytes calldata _data) external;\n\n // Satisfies ERC5679 for ERC721\n function safeMint(address _beneficiary, uint256 value, bytes calldata _data) external;\n }\n\nExample implementation \n<https://git.grassecon.net/cicnet/erc20-demurrage-token.git>\n\n### Msg\n\nEnables a reference \"message\" to describe the contract using an\noff-chain resource.\n\nThe reference may or may not be mutable.\n\nThe interface complements `Locator`\u00a0and `MultiHash` to generate locators\nfor how to resolve the reference.\n\nERC165 Interface identifier \na3002595\n\nSolidity interface definition \n interface IMsg {\n // Emitted when a new message digest has been set\n // Should not be emitted if the digest set is identical to the previous\n event Msg(bytes _msgDigest);\n\n // Get the current message content hash\n function getMsg() external view returns(bytes memory);\n }\n\nExample implementation \n<git://holbrook.no/eth-event-msg.git>\n\n### Registry\n\nThe Registry interface is a key-value store resolving well-known\ncontract identifier names to contract addresses.\n\nIt currently has two distinct uses in the CIC context:\n\n1. Entry-point to discover all relevant contracts of CIC networks.\n\n2. Unique (ERC20) token symbol resolver.\n\nERC165 Interface identifier \neffbf671\n\nSolidity interface definition \n interface IRegistryClient {\n // Address added to store with the given key\n event AddressKey(bytes32 indexed _key, address _address);\n\n // Return the address of the contract identified by the given byte string\n function addressOf(bytes32) external view returns (address);\n\n // Indexed accessor for the full list of registred identifiers\n function identifier(uint256) external view returns (bytes32);\n\n // Number of registered interfaces\n function identifierCount() external view returns (uint256);\n }\n\nContract registry implementation \n<git://holbrook.no/eth-contract-registry.git>\n\nToken index implementation \n<git://holbrook.no/eth-contract-registry.git>\n\n### Seal\n\nSome smart contract parameters may need to be mutable over part of a\nsmart contract\u2019s lifetime.\n\nThis interface provides a method to explicitly signal when certain\nparameters have been rendered immutable.\n\nThe value of `sealState()` *must not*\u00a0decrease, and must not exceed\n`maxSealState`.\n\n`maxSealState` is used to define that *all mutable parameters* have been\nrendered immutable. The practical implications of this will vary between\ncontracts.\n\nThe implementer is encouraged to use simple, descriptive names in the\nsource code to describe the applicable seal states.\n\nUse cases of sealing include:\n\n- Whether more tokens can be minted\n\n- Allow ownership of a contract to be transferred\n\n- The expiry time of a token (see `Expire`)\n\nERC165 Interface identifier \n0d7491f8\n\nSolidity interface definition \n interface ISeal {\n // Seal state has changed.\n event SealStateChange(bool indexed _final, uint256 _sealState);\n\n // The current seal state.\n function sealState() external view returns(uint256);\n\n // The numeric seal state in everything sealable has been sealed.\n function maxSealState() external view returns(uint256);\n }\n\nExample implementation \n<https://git.grassecon.net/cicnet/erc20-demurrage-token.git>\n\n### TokenVend\n\nThis interface defines the mechanism for which a specific ERC20 token\nmay be exchanged for a different ERC20 token.\n\nA typical use-case is generation of voting tokens based on a momentary\nvoucher balance. This is especially useful if the original ERC20 token\nis subject to decay (demurrage).\n\nThe tokens used for exchange **SHOULD** be locked for the full duration\nof holding the vended tokens.\n\nThe withdrawal function may or may not allow partial withdrawals.\n\nERC165 Interface identifier \n8a13249c\n\nSolidity interface definition \n interface ITokenVend {\n // A new vended token has been created.\n event TokenCreated(uint256 indexed _tokenIdx, uint256 indexed _supply, address _token);\n\n // Create corresponding vended tokens for the control token balance of the caller. \n function getFor(address _token) external returns (uint256);\n\n // Recover control tokens that were used to retrieve the corresponding vended tokens.\n function withdrawFor(address _token) external returns (uint256);\n }\n\nReference implementations \n- <git://holbrook.no/erc20-vend.git>\n\n### TokenVote\n\nExecute elections with granular ERC20 token votes.\n\nA proposal submitted for vote may or may not contain multiple options.\nIf multiple options are available, an ERC20 token holder may distribute\nits vote among the options with the granularity of the token balance.\n\nVoted tokens **SHOULD** be locked until the voting has finalized.\n\nFinalization of voting should be callable by anyone.\n\nERC165 Interface identifier \n28091366\n\nSolidity interface definition \n interface ITokenVote {\n\n // A new proposal has been created.\n event ProposalAdded(uint256 indexed _blockDeadline, uint256 indexed voteTargetPpm, uint256 indexed _proposalIdx);\n\n // A proposal vote has been completed.\n // 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.\n // The proposal result may be in one of three states:\n // * Ratified (_cancelled == false, _insufficient == false)\n // * Cancelled (_cancelled == true, _insufficient == false)\n // * Not reached quorum (_cancelled == false, _insufficient == true)\n event ProposalCompleted(uint256 indexed _proposalIdx, bool indexed _cancelled, bool indexed _insufficient, uint256 _totalVote);\n\n // Propose a new vote.\n // Voting is active until one of:\n // * total cancel vote reach quorum (_targetVotePpm, ppm = parts-per-million).\n // * _blockWait blocks from now.\n function propose(bytes32 _description, uint256 _blockWait, uint24 _targetVotePpm) external returns (uint256);\n\n // Same as propose(...), but provide options to vote on.\n function proposeMulti(bytes32 _description, bytes32[] memory _options, uint256 _blockWait, uint24 _targetVotePpm) external returns (uint256);\n\n // Get number of options available for the proposal.\n // This decides the boundary of the index that can be used with voteOptions(...)\n // If the result is 0, vote(...) can be used aswell.\n function optionCount(uint256 _proposalIdx) external view returns(uint256);\n\n // Get proposal option. Assumes that proposal was created with proposeMulti(...)\n function getOption(uint256 _proposalIdx, uint256 _optionIdx) external view returns (bytes32);\n\n // Get vote count for the given option.\n // If proposal has no options, it should be called with _optionIdx = 0\n function voteCount(uint256 _proposalIdx, uint256 _optionIdx) external view returns(uint256);\n\n // Vote on a proposal without options.\n // Assumes that proposal was created with propose(...) and will fail otherwise.\n function vote(uint256 _value) external returns (bool);\n\n // Vote on a proposal option. Assumes that proposal was created with proposeMulti(...).\n // Must work with a non-option proposal if _optionIndex is 0.\n function voteOption(uint256 _optionIndex, uint256 _value) external returns (bool);\n\n // Vote to cancel a proposal.\n // If cancel has the majority:\n // * A vote without options will have rejected the proposal description.\n // * A vote with options will have rejected the proposal description as well as all option descriptions.\n function voteCancel(uint256 _value) external returns (bool);\n\n // Finalize the vote for a proposal.\n // May be called if deadline has been passed, or if:\n // * quorum has been reached with cancel votes.\n // * quorum has been reached and proposal has no/only one option.\n function finalize() external returns (bool);\n }\n\nReference implementations \n- <git://holbrook.no/evm-tokenvote.git>\n\n### Writer\n\nA complement to ERC173, which allows definition of a class of\nsuper-users for a contract.\n\nA super-user address may perform *more* actions than a \"normal\" address,\naswell as *some* actions normally limited to the *contract owner*.\n\nIf an *contract owner* is defined, No super-user should be able to\nperform actions that *contract owner*\u00a0cannot perform.\n\nTypically, only the *contract owner*, if it is defined, can add or\nremove a super-user.\n\nSome use-case examples of super-user actions include:\n\n- Mint new tokens.\n\n- Change the amount dispensed by the faucet.\n\n- Edit access control lists.\n\nERC165 Interface identifier \nabe1f1f5\n\nSolidity interface definition \n interface IWriter {\n // A writer has been added by _executor\n event WriterAdded(address _writer);\n\n // A writer has been removed by _executor\n event WriterDeleted(address _writer);\n\n // Add a new writer to the contract.\n function addWriter(address _writer) external returns (bool);\n\n // Remove existing writer from the contract.\n function deleteWriter(address _writer) external returns (bool);\n\n // Check whether the given address is a writer.\n function isWriter(address _writer) external view returns (bool);\n }\n\nExample implementation \n<https://git.grassecon.net/cicnet/erc20-demurrage-token.git>\n",
"bugtrack_url": null,
"license": "GPL3",
"summary": "CIC network smart contract interfaces",
"version": "0.3.8",
"project_urls": {
"Homepage": "https://gitlab.com/cicnet/cic-contracts"
},
"split_keywords": [
"dlt",
"blockchain",
"cryptocurrency",
"ethereum"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "30aa46eb8b8049b657bad4e9f80c8369e2459f2437a68d04664b52e912fa98ce",
"md5": "8793c6bfa3e05daf9aa7f35cb07c2721",
"sha256": "fa8dce145590facf57d87bf91908b2a5275ad4b66ee4b6ad4912ccbbc18b287c"
},
"downloads": -1,
"filename": "cic-contracts-0.3.8.tar.gz",
"has_sig": false,
"md5_digest": "8793c6bfa3e05daf9aa7f35cb07c2721",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.11,>=3.8",
"size": 47686,
"upload_time": "2023-06-09T08:47:10",
"upload_time_iso_8601": "2023-06-09T08:47:10.217771Z",
"url": "https://files.pythonhosted.org/packages/30/aa/46eb8b8049b657bad4e9f80c8369e2459f2437a68d04664b52e912fa98ce/cic-contracts-0.3.8.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-06-09 08:47:10",
"github": false,
"gitlab": true,
"bitbucket": false,
"codeberg": false,
"gitlab_user": "cicnet",
"gitlab_project": "cic-contracts",
"lcname": "cic-contracts"
}
JSON