TruUpgradeableToken¶
Title: | TruUpgradeableToken |
Description: | Smart Contract derived from UpgradeableToken by Token Market with additional functionality for the TruReputationToken. |
Author: | Ian Bray, Tru Ltd |
Solidity Version: | 0.4.18 |
Relative Path: | ./contracts/supporting/TruUpgradeableToken.sol |
License: | Apache 2 License |
Current Version: | 0.1.12 |
Original Source: | UpgradeableToken |
1. Imports & Dependencies¶
The following imports and dependencies exist for the TruUpgradeableToken Solidity Library:
Name | Description |
SafeMath | Zeppelin Solidity Library to perform mathematics safely inside Solidity |
StandardToken | Zeppelin Solidity Smart Contract for a Standard ERC-20 Token |
TruUpgradeableToken | Library of helper functions surrounding the Solidity Address type |
UpgradeAgent | Token Market Smart Contract used to facilitate upgrading of tokens |
2. Variables¶
The following variables exist for the TruUpgradeableToken Smart Contract:
Variable | Type | Vis | Details |
upgradeMaster | address | public | Variable containing the address of the wallet designated as the Upgrade Master |
upgradeAgent | UpgradeAgent | public | Variable containing the UpgradeAgent Contract Instance |
totalUpgraded | uint256 | public | Variable to track the number of tokens that have been upgraded |
3. Enums¶
The following enums exist for the TruUpgradeableToken Solidity Library:
Enum | Description |
UpgradeState | Enum of the different states an UpgradeableToken can be in. |
UpgradeState¶
The following enum states exist for the UpgradeState enum:
Enum States | Detail |
Unknown | Token upgrade is in an Unknown State- fallback state not used |
NotAllowed | The child contract has not reached a condition where the upgrade can begin |
WaitingForAgent | Token allows upgrade, but an upgradeAgent has not been set |
ReadyToUpgrade | The upgradeAgent is set, but no tokens have been upgraded yet |
Upgrading | The upgradeAgent is set, and balance holders can upgrade their tokens |
4. Events¶
The following events exist for the TruUpgradeableToken Solidity Library:
Name | Description |
Upgrade | Event to notify when a token holder upgrades their tokens |
UpgradeAgentSet | Event to notify when an upgradeAgent is set |
NewUpgradedAmount | Event to notify the new total number of tokens that have been upgraded |
Upgrade¶
Event Name: | Upgrade |
Description: | Event to notify when a token holder upgrades their tokens |
Usage¶
The Upgrade event has the following usage syntax and arguments:
Argument | Type | Indexed? | Details | |
1 | from | address | Yes | Source wallet that the older tokens are sent from |
2 | to | address | Yes | Address of the destination for upgraded tokens which is hardcoded to the upgradeAgent who sends them back to the originating address |
3 | upgradeValue | uint256 | No | Number of tokens to upgrade |
Upgrade(0x123456789abcdefghijklmnopqrstuvwxyz98765,
0x123456789abcdefghijklmnopqrstuvwxyz01234,
100);
UpgradeAgentSet¶
Event Name: | UpgradeAgentSet |
Description: | Event to notify when an upgradeAgent is set |
Usage¶
The UpgradeAgentSet event has the following usage syntax and arguments:
Argument | Type | Indexed? | Details | |
1 | agent | address | Yes | Address of new upgradeAgent |
2 | executor | address | Yes | Address that executed the UpgradeAgentSet event |
UpgradeAgentSet(0x123456789abcdefghijklmnopqrstuvwxyz98765,
0x123456789abcdefghijklmnopqrstuvwxyz01234);
NewUpgradedAmount¶
Event Name: | NewUpgradedAmount |
Description: | Event to notify when an upgradeAgent is set |
Usage¶
The NewUpgradedAmount event has the following usage syntax and arguments:
Argument | Type | Indexed? | Details | |
1 | originalBalance | uint256 | No | Balance of Upgrade Tokens before |
2 | newBalance | uint256 | No | Balance of Upgrade Tokens after |
3 | executor | address | Yes | Address that executed the NewUpgradedAmount event |
NewUpgradedAmount(50, 100);
5. Mappings¶
There are no mappings for the TruUpgradeableToken Smart Contract.
6. Modifiers¶
The following modifiers exist for the TruUpgradeableToken Smart Contract:
Name | Description |
onlyUpgradeMaster | Modifier to check the Upgrade Master is executing this call |
onlyUpgradeMaster¶
Modifier Name: | onlyUpgradeMaster |
Description: | Modifier to check the Upgrade Master is executing this call |
Code¶
The code for the onlyUpgradeMaster modifier is as follows:
modifier onlyUpgradeMaster() {
require(msg.sender == upgradeMaster);
_;
}
The onlyUpgradeMaster function performs the following:
- Checks that the msg.sender matches the upgradeMaster variable
7. Functions¶
The following functions exist for the TruUpgradeableToken Smart Contract:
Name | Description |
TruUpgradeableToken Constructor | Constructor for the TruUpgradeableToken Smart Contract |
upgrade | Function to upgrade tokens. |
setUpgradeAgent | Function to set the upgradeAgent variable |
getUpgradeState | Function to get the current UpgradeState for the token |
setUpgradeMaster | Function to change the upgradeMaster variable |
canUpgrade | Function to get whether the token can be upgraded |
TruUpgradeableToken Constructor¶
Function Name: | TruUpgradeableToken |
Description: | Constructor for the TruUpgradeableToken Smart Contract |
Function Type: | Constructor |
Function Visibility: | Public |
Function Modifiers: | N/A |
Return Type: | None |
Return Details: | N/A |
Code¶
The code for the TruUpgradeableToken Constructor function is as follows:
function TruUpgradeableToken(address _upgradeMaster) public {
require(TruAddress.isValid(_upgradeMaster) == true);
upgradeMaster = _upgradeMaster;
}
The TruUpgradeableToken Constructor function performs the following:
- Checks the _upgradeMaster is a valid Ethereum address.
- Sets the upgradeMaster variable to the _upgradeMaster argument value.
Usage¶
The TruUpgradeableToken Constructor function has the following usage syntax and arguments:
Argument | Type | Details | |
1 | _upgradeMaster | address | Address to be set as the Upgrade Master |
TruUpgradeableToken(0x123456789abcdefghijklmnopqrstuvwxyz98765);
upgrade¶
Function Name: | upgrade |
Description: | Function to upgrade tokens |
Function Type: | N/A |
Function Visibility: | Public |
Function Modifiers: | N/A |
Return Type: | None |
Return Details: | N/A |
Code¶
The code for the upgrade function is as follows:
function upgrade(uint256 value) public {
UpgradeState state = getUpgradeState();
require((state == UpgradeState.ReadyToUpgrade) || (state == UpgradeState.Upgrading));
require(value > 0);
require(balances[msg.sender] >= value);
uint256 upgradedAmount = totalUpgraded.add(value);
assert(upgradedAmount >= value);
uint256 senderBalance = balances[msg.sender];
uint256 newSenderBalance = senderBalance.sub(value);
uint256 newTotalSupply = totalSupply.sub(value);
balances[msg.sender] = newSenderBalance;
totalSupply = newTotalSupply;
NewUpgradedAmount(totalUpgraded, newTotalSupply);
totalUpgraded = upgradedAmount;
// Upgrade agent reissues the tokens
upgradeAgent.upgradeFrom(msg.sender, value);
Upgrade(msg.sender, upgradeAgent, value);
}
The upgrade function performs the following:
- Checks the UpgradeState is either ReadyToUpgrade or Upgrading
- Checks the upgrade amount value is greater than zero
- Checks that the send has a balance of greater than or equal to the upgrade value
- Adds the value to the totalUpgraded variable and checks that this new value is equal to or greater than the value to be upgraded.
- Removes the value from the senders balance
- Removes the value from the token’s totalSupply
- Fires the NewUpgradedAmount event
- Initiates the Upgrade Agent’s upgradeFrom functionality to deliver the value in upgraded tokens to the sender.
- Fires the Upgrade event
setUpgradeAgent¶
Function Name: | setUpgradeAgent |
Description: | Function to set the upgradeAgent variable |
Function Type: | N/A |
Function Visibility: | Public |
Function Modifiers: | onlyUpgradeMaster |
Return Type: | None |
Return Details: | N/A |
Code¶
The code for the setUpgradeAgent function is as follows:
function setUpgradeAgent(address _agent) public onlyUpgradeMaster {
require(TruAddress.isValid(_agent) == true);
require(canUpgrade());
require(getUpgradeState() != UpgradeState.Upgrading);
UpgradeAgent newUAgent = UpgradeAgent(_agent);
require(newUAgent.isUpgradeAgent());
require(newUAgent.originalSupply() == totalSupply);
UpgradeAgentSet(upgradeAgent);
upgradeAgent = newUAgent;
}
The setUpgradeAgent function performs the following:
- Checks the _agent address is valid. If not, the function will throw.
- Checks that the token can upgrade via the canUpgrade function. If not, the function will throw.
- Checks that that UpgradeState is not Upgrading (and therefore in the middle of an upgrade). If not, the function will throw.
- Checks that the specified Upgrade Agent contract is an Upgrade Agent. If not, the function will
- throw.
- Checks that the Upgrade Agent’s original supply matches the current total supply of the token. If not, the function will throw.
- Fires the UpgradeAgentSet event.
- Sets the upgradeAgent variable.
Usage¶
The setUpgradeAgent function has the following usage syntax and arguments:
Argument | Type | Details | |
1 | _agent | address | Address of the new Upgrade Agent |
setUpgradeAgent(0x123456789abcdefghijklmnopqrstuvwxyz98765);
getUpgradeState¶
Function Name: | getUpgradeState |
Description: | Function to get the current UpgradeState of the token |
Function Type: | Constant |
Function Visibility: | Public |
Function Modifiers: | N/A |
Return Type: | UpgradeState |
Return Details: | Returns UpgradeState as a uint (0, 1, 2, 3 or 4) |
Code¶
The code for the getUpgradeState function is as follows:
function getUpgradeState() public constant returns(UpgradeState) {
if (!canUpgrade())
return UpgradeState.NotAllowed;
else if (TruAddress.isValid(upgradeAgent) == false)
return UpgradeState.WaitingForAgent;
else if (totalUpgraded == 0)
return UpgradeState.ReadyToUpgrade;
else
return UpgradeState.Upgrading;
}
The getUpgradeState function performs the following:
- the canUpgrade function to see if it is true. If it is false, returns NotAllowed UpgradeState
- Checks the upgradeAgent address is valid and set. If it is not, returns WaitingForAgent UpgradeState
- Checks that the totalUpgraded* is zero. If it is true, return ReadyToUpgrade UpgradeState
- Else return Upgrading UpgradeState
setUpgradeMaster¶
Function Name: | setUpgradeMaster |
Description: | Function to change the upgradeMaster variable |
Function Type: | N/A |
Function Visibility: | Public |
Function Modifiers: | onlyUpgradeMaster |
Return Type: | UpgradeState |
Return Details: | Returns UpgradeState as a uint (0, 1, 2, 3 or 4) |
Code¶
The code for the setUpgradeMaster function is as follows:
function setUpgradeMaster(address _master) public onlyUpgradeMaster {
require(TruAddress.isValid(_master) == true);
upgradeMaster = _master;
}
The setUpgradeMaster function performs the following:
- Checks the _master argument is a valid Ethereum Address. If it is not, it will throw.
- Sets the upgradeMaster variable to the _master argument.
Usage¶
The setUpgradeMaster function has the following usage syntax and arguments:
Argument | Type | Details | |
1 | _master | address | Address of the new Upgrade Master |
setUpgradeMaster(0x123456789abcdefghijklmnopqrstuvwxyz98765);
canUpgrade¶
Function Name: | canUpgrade |
Description: | Function to get whether the token can be upgraded or not |
Function Type: | Constant |
Function Visibility: | Public |
Function Modifiers: | N/A |
Return Type: | bool |
Return Details: | Returns true as a default; customised in child contracts to fit required conditions |
Code¶
The code for the canUpgrade function is as follows:
function canUpgrade() public constant returns(bool) {
return true;
}
The canUpgrade function performs the following:
- returns true. This functionality is overridden in child contracts to provide conditionality for this result.