How Data Payloads Augment Smart Contracts

An explanation on how Token Foundry’s smart contracts work and the data payload we require all our users to include when contributing to a sale.

Purchasing anything online comes with an element of risk. As a consumer, you are expected to perform a cost-benefit analysis of completing a transaction. Is your purchase secure? Can you guarantee receipt of goods purchased, in the state you were promised?

When considering conducting a purchase on a decentralized network such as Ethereum, one might feel an added sense of caveat emptor. However, rather than having a third party intermediate, we design and build smart contracts that allow purchases to happen securely and fairly.

Smart contracts, used in this way, are protocols for ensuring transactions happen credibly at the time of purchase. We add a feature to our smart contracts called ‘data payloads’, to block bad actors from transacting on Ethereum and thereby building a stronger, more fair network for everyone.

This post is intended to provide insight into how we design our smart contracts, and specifically why we require a data payload by default.

Components of an Ethereum token sale

Let’s begin with the core concept: constructing a transaction to purchase tokens during a sale. I’ll begin by explaining the different fields included in a transaction, along with why they are required when participating in a Token Foundry sale. (If you are experienced with purchasing tokens on Ethereum please feel free to skip ahead to where I describe how we construct our data payload.) If you are just learning though, this should help provide you with greater insight into the inner workings of Ethereum.

First of all, what is gas?

Throughout this article, you’ll see me reference something called gas. Gas is the unit used to measure the computational work required to complete a transaction. You can think of gas the same way you think about electricity. For example, the amount of energy required to run the same light bulb each day will be constant, but the cost per unit of energy each day will be different. This cost varies depending how much demand there is for energy at a given time. The same concept can be applied to gas. It will take the same amount of gas to complete the exact same transaction every day but, depending on the network load, the cost per unit of gas could be drastically different.

{
“from”: “0xb60e8dd61c5d32be8058bb8eb970870f07233155”,
“to”: “0xd46e8dd67c5d32be8058bb8eb970870f07244567”,
“gas”: “0x76c0”, // 30400
“gasPrice”: “0x9184e72a000”, // 10000000000000
“value”: “0x9184e72a”, // 2441406250
“data”: “0xd46e8dd67c5d32be8d46e8dd67c5d32be8058bb8eb970870f072445675058bb8eb970870f072445675”
}

Refrence: https://github.com/ethereum/wiki/wiki/JSON-RPC#eth_sendtransaction`

The fields of a transaction

FROM

This is the Ethereum address that the transaction is being sent from. In the case of a token sale, it must be the address you’ve registered with on the Token Foundry platform. This will be the address you are purchasing from and, at the end of the token sale, this will also be the address that has access to your tokens.

TO

This is the Ethereum address that the transaction is being sent to. In general, this is the account or smart contract you are transferring money to, or calling a function of. In a token sale, this is the sale’s contract address

GAS

(Optional field, but recommended.) Also known as ‘gas limit’. This is the maximum amount of gas you are providing to execute your transaction. This will default to a specific value unless defined otherwise.

GAS PRICE

(Optional field, but recommended.) The amount of ether you are willing to pay per unit of gas, this is generally input as either price per Wei or per Gwei (these are subunits of ETH). If you wish for your transaction to be confirmed faster, you should submit a higher-than-average gas price. This will default to a specific value unless defined otherwise.

Value

The number of ETH you are sending to the TO address. Be sure to check the denomination before sending.

Data

When sending a transaction on Ethereum to a smart contract, the contract will have access to this data field. The data includes the first 4 bytes of the hash of the function’s signature, followed by the ABI-encoded parameters as an abstraction. In simpler terms, this is the function in the contract you are calling, along with the required parameters you are passing in.

The data payload

If you’ve participated in previous token sales you may have noticed that they don’t require you to include a “transactional data” field or a data field.

The reason Token Foundry requires purchasers to include this string is because in that piece of data, we verify a number of pieces of information about the contributor themselves. This includes:

• The address you are allowed to send ether from
• The limit of ether you are allowed to contribute
• Whether you have passed the project’s questionnaire
• Whether you have KYC’ed with Token Foundry
• The actual signature generated by Token Foundry’s whitelist admin to verify that you are allowed to contribute

This is our way of ensuring a purchaser is allowed to participate in a sale without having to add every address to a user registry. To prevent users from constructing the data payoad piece arbitrarily, our smart contract signs the hash of the tightly packed arguments with our “signator’s” private key. By doing this we are able to verify through our smart contract that the signature in the data payload passed with the transaction was constructed by Token Foundry.

There is a cool function within Solidity called ecrecover, which recovers the signer’s address from a message and a signature (if the signer actually signed the message). At the time of writing we are using the current implementation of open-zeppelins recover function which can be found here. https://github.com/OpenZeppelin/openzeppelin-solidity/blob/master/contracts/ECRecovery.sol

Conclusion

Sending a transaction on Ethereum can be a daunting task, but hopefully this post helped you understand a bit more about the behind-the-scenes of hitting ‘send’. We will be continuing to add more technical blog posts along with videos that will take you through sending a transaction from start to finish on the Token Foundry platform.

Stuart Hunter
Head of Technology