From 80671fdfaa0745e7a7c2855d32fd6a0ddaddc84c Mon Sep 17 00:00:00 2001 From: lash Date: Tue, 1 Aug 2023 14:50:09 +0100 Subject: [PATCH] Add rate of change definition --- README.md | 52 ++++++++++++++++++++++++---- doc/texinfo/overview.texi | 2 ++ doc/texinfo/tokenratechange.sol.texi | 19 ++++++++++ python/README.md | 52 ++++++++++++++++++++++++---- solidity/TokenRateChange.sol | 29 ++++++++++++++++ solidity/TokenVote.sol | 6 ++-- 6 files changed, 145 insertions(+), 15 deletions(-) create mode 100644 doc/texinfo/tokenratechange.sol.texi create mode 100644 solidity/TokenRateChange.sol diff --git a/README.md b/README.md index 521404b..e37bb69 100644 --- a/README.md +++ b/README.md @@ -133,7 +133,7 @@ Attached to `ERC20` and `ERC721` tokens that may be *burned*. Implements the `burn(...)` part of `ERC5679` for interoperability. ERC165 Interface identifier -bc4babdd +b1110c1b Solidity interface definition interface IBurner { @@ -144,10 +144,11 @@ Solidity interface definition 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); + function burn(uint256 _amount) external returns (bool); // Burn all tokens held by signer. - function burn() external returns (bool); + // Returns the amount of tokens burned. + function burn() external returns (uint256); // Total amount of tokens that have been burned. function totalBurned() external returns (uint256); @@ -588,6 +589,45 @@ Solidity interface definition Example implementation +### TokenRateChange + +Enables detection of properties for CIC tokens that change value over +time, e.g. through demurrage. + +It allows defining the granularity of the rate of change, aswell as a +frequency for which the rate of change is applied. + +A method for canonical value change calculations is also provided. + +ERC165 Interface identifier +b716af03 + +Solidity interface definition + interface ITokenChangeRate { + // Time unit resolution for rate of change. + // A value of 0 indicates no rate of change, + function changeTimeUnit() external view returns(uint256); + + // Rate of change per changeTimeUnit(), signed integer. + // An effective value of 0 indicates no rate of change. + function changeRate() external view returns (int256); + + // Number of decimals with which the changeRate is defined. + // changeRate() should be divided by 10 ** changeRateDecimals() to obtain effective value + function changeRateDecimals() external view returns(uint8); + + // Timestamp from when rate of change should be applied. + // A value of 0 indicates no rate of change, + function changeStartTime() external view returns(uint256); + + // Calculate value with change rate applied for given amount of time units. + // Will calculate compounded change over the given amount of time units + function applyChange(int256 _value, uint256 _changeTimeUnits) external view returns(int256); + } + +Reference implementations +- + ### TokenVend This interface defines the mechanism for which a specific ERC20 token @@ -633,7 +673,7 @@ Voted tokens **SHOULD** be locked until the voting has finalized. Finalization of voting should be callable by anyone. ERC165 Interface identifier -28091366 +f2e0bfeb Solidity interface definition interface ITokenVote { @@ -655,8 +695,8 @@ Solidity interface definition // * _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); + // Add a voting option to a proposal + function addOption(uint256 _proposalIdx, bytes32 _description) external; // Get number of options available for the proposal. // This decides the boundary of the index that can be used with voteOptions(...) diff --git a/doc/texinfo/overview.texi b/doc/texinfo/overview.texi index 6948583..2706d17 100644 --- a/doc/texinfo/overview.texi +++ b/doc/texinfo/overview.texi @@ -74,6 +74,8 @@ The following well-known solidity interfaces are partially implemented in CIC na @include seal.sol.texi +@include tokenratechange.sol.texi + @include tokenvend.sol.texi @include tokenvote.sol.texi diff --git a/doc/texinfo/tokenratechange.sol.texi b/doc/texinfo/tokenratechange.sol.texi new file mode 100644 index 0000000..801ef90 --- /dev/null +++ b/doc/texinfo/tokenratechange.sol.texi @@ -0,0 +1,19 @@ +@subsection TokenRateChange + +Enables detection of properties for CIC tokens that change value over time, e.g. through demurrage. + +It allows defining the granularity of the rate of change, aswell as a frequency for which the rate of change is applied. + +A method for canonical value change calculations is also provided. + +@table @dfn +@item ERC165 Interface identifier +@include ../../build/TokenRateChange.interface +@item Solidity interface definition +@include ../../build/contract_TokenRateChange.texi +@item Reference implementations +@itemize +@item +@uref{git://holbrook.no/erc20-demurrage-token.git,} +@end itemize +@end table diff --git a/python/README.md b/python/README.md index 521404b..e37bb69 100644 --- a/python/README.md +++ b/python/README.md @@ -133,7 +133,7 @@ Attached to `ERC20` and `ERC721` tokens that may be *burned*. Implements the `burn(...)` part of `ERC5679` for interoperability. ERC165 Interface identifier -bc4babdd +b1110c1b Solidity interface definition interface IBurner { @@ -144,10 +144,11 @@ Solidity interface definition 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); + function burn(uint256 _amount) external returns (bool); // Burn all tokens held by signer. - function burn() external returns (bool); + // Returns the amount of tokens burned. + function burn() external returns (uint256); // Total amount of tokens that have been burned. function totalBurned() external returns (uint256); @@ -588,6 +589,45 @@ Solidity interface definition Example implementation +### TokenRateChange + +Enables detection of properties for CIC tokens that change value over +time, e.g. through demurrage. + +It allows defining the granularity of the rate of change, aswell as a +frequency for which the rate of change is applied. + +A method for canonical value change calculations is also provided. + +ERC165 Interface identifier +b716af03 + +Solidity interface definition + interface ITokenChangeRate { + // Time unit resolution for rate of change. + // A value of 0 indicates no rate of change, + function changeTimeUnit() external view returns(uint256); + + // Rate of change per changeTimeUnit(), signed integer. + // An effective value of 0 indicates no rate of change. + function changeRate() external view returns (int256); + + // Number of decimals with which the changeRate is defined. + // changeRate() should be divided by 10 ** changeRateDecimals() to obtain effective value + function changeRateDecimals() external view returns(uint8); + + // Timestamp from when rate of change should be applied. + // A value of 0 indicates no rate of change, + function changeStartTime() external view returns(uint256); + + // Calculate value with change rate applied for given amount of time units. + // Will calculate compounded change over the given amount of time units + function applyChange(int256 _value, uint256 _changeTimeUnits) external view returns(int256); + } + +Reference implementations +- + ### TokenVend This interface defines the mechanism for which a specific ERC20 token @@ -633,7 +673,7 @@ Voted tokens **SHOULD** be locked until the voting has finalized. Finalization of voting should be callable by anyone. ERC165 Interface identifier -28091366 +f2e0bfeb Solidity interface definition interface ITokenVote { @@ -655,8 +695,8 @@ Solidity interface definition // * _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); + // Add a voting option to a proposal + function addOption(uint256 _proposalIdx, bytes32 _description) external; // Get number of options available for the proposal. // This decides the boundary of the index that can be used with voteOptions(...) diff --git a/solidity/TokenRateChange.sol b/solidity/TokenRateChange.sol new file mode 100644 index 0000000..54390ae --- /dev/null +++ b/solidity/TokenRateChange.sol @@ -0,0 +1,29 @@ +pragma solidity >=0.6.12; + +// Author: Louis Holbrook 0826EDA1702D1E87C6E2875121D2E7BB88C2A746 +// SPDX-License-Identifier: AGPL-3.0-or-later +// File-version: 1 + +// Methods to detect tokens that are subject to continuous change, and + +interface ITokenChangeRate { + // Time unit resolution for rate of change. + // A value of 0 indicates no rate of change, + function changeTimeUnit() external view returns(uint256); + + // Rate of change per changeTimeUnit(), signed integer. + // An effective value of 0 indicates no rate of change. + function changeRate() external view returns (int256); + + // Number of decimals with which the changeRate is defined. + // changeRate() should be divided by 10 ** changeRateDecimals() to obtain effective value + function changeRateDecimals() external view returns(uint8); + + // Timestamp from when rate of change should be applied. + // A value of 0 indicates no rate of change, + function changeStartTime() external view returns(uint256); + + // Calculate value with change rate applied for given amount of time units. + // Will calculate compounded change over the given amount of time units + function applyChange(int256 _value, uint256 _changeTimeUnits) external view returns(int256); +} diff --git a/solidity/TokenVote.sol b/solidity/TokenVote.sol index 3b0e9b2..4bc9496 100644 --- a/solidity/TokenVote.sol +++ b/solidity/TokenVote.sol @@ -2,7 +2,7 @@ pragma solidity >=0.6.12; // Author: Louis Holbrook 0826EDA1702D1E87C6E2875121D2E7BB88C2A746 // SPDX-License-Identifier: AGPL-3.0-or-later -// File-version: 1 +// File-version: 2 interface ITokenVote { @@ -24,8 +24,8 @@ interface ITokenVote { // * _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); + // Add a voting option to a proposal + function addOption(uint256 _proposalIdx, bytes32 _description) external; // Get number of options available for the proposal. // This decides the boundary of the index that can be used with voteOptions(...)