Payment token smart contract

The payment token smart contract handles anything related to payments. Your supply chain participants will buy and sell products by using tokens instead of traditional currency. Although Ethereum includes its own currency, Ether, you will implement your own token for supply chain participants to use. Although you could just have participants pay each other by using Ether, a custom token helps you to manage the entire process.

Defining your own token helps ensure that you limit supply chain participation to only valid supply chain participants and can make transfers simpler. Instead of allowing any Ethereum account to interact with your supply chain, only accounts that own your tokens can pay for products. Therefore, the only way a participant can enter the supply chain is to gain the trust of another participant. You have to either sell your products to an existing participant or exchange some other currency for your tokens.

Many businesses use the token concept. Arcades often set up their games to use physical tokens instead of real coins or paper money. You buy tokens using real currency and then use the tokens to play each game. This approach makes breaking into game consoles less attractive because the games contain only tokens — not real money. The tokens have value only inside the arcade. (Also, any lost or misplaced tokens mean a profit for the house; a nice benefit if you’re issuing the tokens.)

Multiple proposed standards for Ethereum tokens in the form of Ethereum Request for Comments (ERC) documents exist. Ten of these proposals have been accepted to become Ethereum Improvement Proposals (EIP). ERC-20 (now EIP-20) defines one of the early standards for defining tokens for Ethereum. You’ll use the ERC/EIP-20 standard for your tokens.

ERC and EIP are used interchangeably. Technically, EIP refers to finalized ERC documents. However, even though a proposal is finalized, such as EIP-20, you still will see it referred to as ERC-20.

Your token smart contract will allow participants to acquire tokens and then transfer them to other participants in exchange for moving products along the supply chain. To complete this process, you need several data items and functions. The data items you’ll define follow:

• totalSupply: The total number of tokens in circulation
• name: A descriptive name for your token
• decimals: The number of decimals to use when displaying token amounts
• symbol: A short identifier for your token
• balances: The current balance of each participating account, mapped to the account's address
• allowed: A list of number of tokens authorized for transfer between accounts, mapped to the sender’s address

Your token smart contract will define six functions that allow users to manage token transfers. The functions you’ll define are as follows:

• totalSupply(): Returns the current total number of tokens
• balanceOf(): Returns the current balance, in tokens, of a specific account
• allowance(): Returns the remaining number of tokens that are allowed to be transferred from a specific source account to a specific target account
• transfer(): Transfers tokens from the caller to a specified target account
• approve(): Sets a number of tokens that are allowed to be transferred from a specific source account to a specific target account
• transferFrom(): Transfers tokens from a specified source account to a specified target account

Supply chain smart contract

Your second smart contract will contain the data and functionality to manage the product, participant, and product transfer data. In other words, it will handle all supply chain activity that isn't related to payment. As you learn how to implement supply chain functionality, you’ll probably think of more things that you’d like your dApp to handle. That’s okay. The smart contracts you’ll develop in this book are just a starting point. You can extend them to handle many more use cases.

To store the supply chain data necessary for managing product migration toward consumers, you’ll define the following data items:

• product structure: This data item stores data that defines a unique product (model number, part number, serial number, product owner, cost, manufactured time).
• participant structure: The participant structure stores data that defines a unique participant (user name, password, participant type, Ethereum address).
• registration structure: The registration structure stores data that records a transfer of a product from one owner to another as the product moves toward the consumer (product ID, owner ID, transaction time, product owner Ethereum address).
• p_id: The product ID uniquely identifies a product and is mapped to a product structure.
• u_id: The participant ID uniquely identifies a participant and is mapped to a participant structure.
• r_id: The registration ID uniquely identifies a registration and is mapped to a registration structure.

Now that you know the data and functions you'll need in your smart contracts, the next step is to start writing code in Solidity.

ERC-20 token interface

The first file you’ll edit is the interface for the ERC-20 token. An interface looks just like a smart contract but doesn’t contain any executable code. Developers use interfaces to define minimum functionality for groups of programs. When you define an interface, you define the minimum data items and functions that you want to be common among smart contracts that implement the interface.

ERC-20 tokens aren’t the only type of tokens in Ethereum. Another token standard that looks like it may challenge ERC-20’s popularity is ERC-223. You can find out more about the ERC-223 token standard at https://medium.com/kinblog/the-new-erc223-token-standard-8dddbf1a5909.

In our case, we’re going to use the standard ERC-20 (or EIP-20) token interface. Every ERC-20 token that uses this interface is guaranteed to have the same minimum data and functions. That’s the purpose of an interface. Your implementation may have more data and functions, but you can count on the fact that it has at least everything defined in the interface. In fact, if you use an interface and forget to define a data item or function, the compiler generates an error and refuses to compile the program.

To make sure that your token complies with the ERC-20 token standard, you use the ERC-20 token interface. Click or tap the erc20Interface.sol tab in VS Code and enter the following code:

// ----------------------------------------------------------------------------

// ERC Token Standard #20 Interface

// https://github.com/ethereum/EIPs/blob/master/EIPS/eip-20.md

// ----------------------------------------------------------------------------

pragma solidity ^0.4.24;

contract ERC20Interface {

uint256 public totalSupply;

function totalSupply() public view returns (uint);

function balanceOf(address tokenOwner) public view returns (uint balance);

function allowance(address tokenOwner, address spender) public view returns (uint remaining);

function transfer(address to, uint tokens) public returns (bool success);

function approve(address spender, uint tokens) public returns (bool success);

function transferFrom(address from, address to, uint tokens) public returns (bool success);

event Transfer(address indexed from, address indexed to, uint tokens);

event Approval(address indexed tokenOwner, address indexed spender, uint tokens);

}

This interface defines the single variable, six functions, and two events that every token contract must implement to support the ERC-20 token standard. You’ll learn what each line of code does in the next section, where you implement the interface. At this point, just note that each line of code defines a variable, a function, or an event. There is no code that actually does anything.

ERC-20 token smart contract

After you define the interface, you can implement the code to make your token smart contract work. Click or tap the erc20Token.sol tab in VS Code and enter the following code:

// ----------------------------------------------------------------------------

///Implements EIP20 token standard: https://github.com/ethereum/EIPs/blob/master/EIPS/eip-20.md

// ----------------------------------------------------------------------------

pragma solidity ^0.4.24;

import "./erc20Interface.sol";

contract ERC20Token is ERC20Interface {

}

You learned about the pragma statement in Chapter 7. The import statement tells Solidity to open an external file and read it into this file to compile it, just as if you had copied the contents of erc20Interface.sol into this file. You can use the import statement as your projects grow to help you keep any single source code file from growing too large to manage easily. If any source code file starts to get too big, you can spilt it into multiple smaller files and import the pieces in the main file.

The last line in the code segment defines the smart contract. You use the contract statement to define a smart contract named ERC20Token. When you define the contract as ERC20token is ERC20Interface, you are telling Solidity that you intend to implement ERC20Interface in this file. Therefore, the compiler will check to make sure that every item defined in the interface is implemented in this file.

The first step to make your token work is to add the data items you'll need. Add the following code between the two curly braces (after the contract statement):

uint256 constant private MAX_UINT256 = 2**256 - 1;

mapping (address => uint256) public balances;

mapping (address => mapping (address => uint256)) public allowed;

uint256 public totalSupply; // Total number of tokens

string public name; // Descriptive name (i.e. For Dummies Token)

uint8 public decimals; // How many decimals to use to display amounts

string public symbol; // Short identifier for token (i.e. FDT)

These lines of source code define the data you’ll store on the blockchain for your token. The first data item, MAX_UINT256, is defined as a constant, which means that the value you assign to it can't be changed at runtime. Solidity uses the ** symbol to denote exponentiation, so 3 squared is 3**2 in Solidity. The value of 2 raised to the 256 power minus 1 is stored in the MAX_UINT256 constant. Defining MAX_UINT256 is a convenient way to store the largest possible value in a uint256 variable.

The balances and allowed data items are mappings. They exist to make it easy to look up a balance or a list of token transfer allowances for an Ethereum account address. The remaining data items are state variables that describe attributes of your token.

State variables are stored in the blockchain, and storing data in the blockchain costs gas. So you can conserve gas by minimizing how much and how often you store blockchain data. Don't define more state variables than you need. It is good practice to declare the smallest uint size for the data you’ll store, which is why the decimal variable is defined as uint8. When you define more complex data using structs, size matters even more.

Supply chain smart contract

The next step in writing developing your supply chain dApp is to begin the definition of the supply chain smart contract. Click or tap the SupplyChain.sol tab in VS Code and enter the following code:

pragma solidity ^0.4.24;

contract supplyChain {

uint32 public p_id = 0; // Product ID

uint32 public u_id = 0; // Participant ID

uint32 public r_id = 0; // Registration ID

}

This smart contract starts like the other smart contracts you’ve seen so far. Inside the contract body, you define three state variables to store the highest ID for products, participants, and registrations. The next sections define the details of each type of supply chain data.

ERC-20 token functions

To define the actions your ERC-20 token smart contract should carry out, you need to define its functions and provide the code for the body of each function. Remember that your ERC-20 token smart contract implements an interface, so you have to at least define the functions required in the interface. Note that you can define more functions than those in the interface.

Click or tap the erc20Token.sol tab in VS Code and enter the code for each of the following functions. (Start entering function source code after the symbol state variable definition.)

Supply chain functions

To define the functionality of your supply chain smart contract, you need to define its functions and provide the code for the body of each function.

Click or tap the SupplyChain.sol tab in VS Code and enter the code for each of the following functions. (Start entering function source code after the productTrack mapping definition.)

Defining events

Your supply chain smart contracts will use three events. The ERC-20 token interface requires that you implement two of the events, and you’ll define the other one in the main supply chain smart contract.

Click or tap the erc20Interface.sol tab in VS Code to switch to the ERC-20 interface code. Look at the last two lines of code:

event Transfer(address indexed from, address indexed to, uint tokens);

event Approval(address indexed tokenOwner, address indexed spender, uint tokens);

These lines define the Transfer and Approval events. When the Transfer event triggers, it tells any program that is listening for this event that a transfer has just occurred, and that the transfer consisted of send tokens from one address to another. When the Approval event triggers, it tells any program that is listening for this event that a new approval was just authorized for a token owner to transfer up to some number of tokens to a specific sender. It is up to the listening programs to do something with these events. Your smart contracts need to only define and trigger the events.

Click or tap the SupplyChain.sol tab in VS Code to switch to the supply chain smart contract code. Scroll down to the definitions for the two mappings after the registrations struct. This should be around line 35. Type the following text on a new line:

event Transfer(uint32 productId);

After you enter this new code, the last few lines of your SupplyChain.sol code should look like Figure 9-3.

You will use your new Transfer event every time you create a new registration. That means you'll use the event to let any listening program know that a product has just been transferred from one supply chain participant to another. The Transfer event sends the transferred product ID to the listening program to tell it what product just moved. The event mechanism makes it easy for external programs to monitor changes that your smart contracts carry out.

Triggering events

After you define the events you’ll need in your smart contracts, the next step is to trigger each event at the right time. All you really have to do here is trigger the event in your code when you carry out the action you want to communicate. In other words, you should trigger the Transfer event at the point where your code carries out the transfer action.

In Solidity, you use the emit statement to trigger an event. When you use the emit statement, it is like calling a function. You tell Solidity what event to trigger, and then you provide parameter values, as you do with a function.

Click or tap the erc20Interface.sol tab in VS Code to switch to the ERC-20 smart contract code. Update your transfer(), transferFrom(), and approve() functions to include the emit statements shown here (new code is in bold):

function transfer(address _to, uint256 _value) public returns (bool success) {

require(balances[msg.sender] >= _value,"Insufficient funds for transfer source.");

balances[msg.sender] -= _value;

balances[_to] += _value;

emit Transfer(msg.sender, _to, _value);

return true;

}

function transferFrom(address _from, address _to, uint256 _value) public returns (bool success) {

uint256 allowance = allowed[_from][msg.sender];

require(balances[_from] >= _value && allowance >= _value,"Insufficient allowed funds for transfer source.");

balances[_to] += _value;

balances[_from] -= _value;

if (allowance < MAX_UINT256) {

allowed[_from][msg.sender] -= _value;

}

emit Transfer(_from, _to, _value);

return true;

}

function approve(address _spender, uint256 _value) public returns (bool success) {

allowed[msg.sender][_spender] = _value;

emit Approval(msg.sender, _spender, _value);

return true;

}

You can call the emit statement anywhere in your smart contract code. In your ERC-20 token smart contract, you have added the emit statement in three places to signal that some notable action has just occurred.

Click or tap the SupplyChain.sol tab in VS Code to switch to the supply chain smart contract code. Update your transferToOwner() function to include the emit statement shown here (new code is in bold):

function transferToOwner(uint32 _user1Id ,uint32 _user2Id, uint32 _prodId) onlyOwner(_prodId) public returns(bool) {

participant memory p1 = participants[_user1Id];

participant memory p2 = participants[_user2Id];

uint32 registration_id = r_id++;

registrations[registration_id].productId = _prodId;

registrations[registration_id].productOwner = p2.participantAddress;

registrations[registration_id].ownerId = _user2Id;

registrations[registration_id].trxTimeStamp = uint32(now);

products[_prodId].productOwner = p2.participantAddress;

productTrack[_prodId].push(registration_id);

emit Transfer(_prodId);

return (true);

}