cerc-io/solidity
16
0
Fork 0
mirror of https://github.com/ethereum/solidity synced 2023-10-03 13:03:40 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Begin review of micropayments example

Browse Source 
Language tidy, add correct method and package namespaces and make more consistent with each project docs

First changes from review

Further fixes after review

Fix line breaks

Revert code changes

Update
This commit is contained in:
Chris Ward 2018-07-10 17:54:09 +02:00
parent 88fbd315bc
commit 121d733b34
1 changed files with 65 additions and 124 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

189
docs/solidity-by-example.rst
View File

@ -647,10 +647,10 @@ Safe Remote Purchase
Micropayment Channel Micropayment Channel
******************** ********************
In this section we will learn how to build a simple implementation In this section we will learn how to build an example implementation
of a payment channel. It use cryptographics signatures to make of a payment channel. It uses cryptographic signatures to make
repeated transfers of Ether between the same parties secure, instantaneous, and repeated transfers of Ether between the same parties secure, instantaneous, and
without transaction fees. To do it we need to understand how to without transaction fees. For the example, we need to understand how to
sign and verify signatures, and setup the payment channel. sign and verify signatures, and setup the payment channel.
Creating and verifying signatures Creating and verifying signatures
@ -658,88 +658,69 @@ Creating and verifying signatures
Imagine Alice wants to send a quantity of Ether to Bob, i.e. Imagine Alice wants to send a quantity of Ether to Bob, i.e.
Alice is the sender and the Bob is the recipient. Alice is the sender and the Bob is the recipient.
Alice only needs to send cryptographically signed messages off-chain
(e.g. via email) to Bob and it will be very similar to writing checks.
Signatures are used to authorize transactions, Alice only needs to send cryptographically signed messages off-chain
and they are a general tool that is available to (e.g. via email) to Bob and it is similar to writing checks.
smart contracts. Alice will build a simple
smart contract that lets her transmit Ether, but Alice and Bob use signatures to authorise transactions, which is possible with smart contracts on Ethereum.
in a unusual way, instead of calling a function herself Alice will build a simple smart contract that lets her transmit Ether, but instead of calling a function herself
to initiate a payment, she will let Bob to initiate a payment, she will let Bob do that, and therefore pay the transaction fee.
do that, and therefore pay the transaction fee.
The contract will work as follows: The contract will work as follows:
1. Alice deploys the ``ReceiverPays`` contract, attaching enough Ether to cover the payments that will be made. 1. Alice deploys the ``ReceiverPays`` contract, attaching enough Ether to cover the payments that will be made.
2. Alice authorizes a payment by signing a message with their private key. 2. Alice authorises a payment by signing a message with their private key.
3. Alice sends the cryptographically signed message to Bob. The message does not need to be kept secret 3. Alice sends the cryptographically signed message to Bob. The message does not need to be kept secret
(you will understand it later), and the mechanism for sending it does not matter. (explained later), and the mechanism for sending it does not matter.
4. Bob claims their payment by presenting the signed message to the smart contract, it verifies the 4. Bob claims their payment by presenting the signed message to the smart contract, it verifies the
authenticity of the message and then releases the funds. authenticity of the message and then releases the funds.
Creating the signature Creating the signature
---------------------- ----------------------
Alice does not need to interact with Ethereum network to Alice does not need to interact with the Ethereum network to sign the transaction, the process is completely offline.
sign the transaction, the process is completely offline. In this tutorial, we will sign messages in the browser using `web3.js <https://github.com/ethereum/web3.js>`_ and `MetaMask <https://metamask.io>`_, using the method described in `EIP-762 <https://github.com/ethereum/EIPs/pull/712>`_,
In this tutorial, we will sign messages in the browser
using ``web3.js`` and ``MetaMask``.
In particular, we will use the standard way described in `EIP-762 <https://github.com/ethereum/EIPs/pull/712>`_,
as it provides a number of other security benefits. as it provides a number of other security benefits.
:: ::
/// Hashing first makes things easier
var hash = web3.utils.sha3("message to sign");
web3.eth.personal.sign(hash, web3.eth.defaultAccount, function () {
console.log("Signed")
});
/// Hashing first makes a few things easier .. note::
var hash = web3.sha3("message to sign"); The ``web3.eth.personal.sign`` prepends the length of the message to the signed data. Since we hash first, the message will always be exactly 32 bytes long, and thus this length prefix is always the same.
web3.personal.sign(hash, web3.eth.defaultAccount, function () {...});
Note that the ``web3.personal.sign`` prepends the length of the message to the signed data.
Since we hash first, the message will always be exactly 32 bytes long,
and thus this length prefix is always the same, making everything easier.
What to Sign What to Sign
------------ ------------
For a contract that fulfills payments, the signed message must include: For a contract that fulfils payments, the signed message must include:
1. The recipient's address 1. The recipient's address.
2. The amount to be transferred 2. The amount to be transferred.
3. Protection against replay attacks 3. Protection against replay attacks.
A replay attack is when a signed message is reused to claim authorization for A replay attack is when a signed message is reused to claim authorization for
a second action. a second action.
To avoid replay attacks we will use the same as in Ethereum transactions To avoid replay attacks we use the same as in Ethereum transactions
themselves, a so-called nonce, which is the number of transactions sent by an themselves, a so-called nonce, which is the number of transactions sent by an
account. account.
The smart contract will check if a nonce is used multiple times. The smart contract checks if a nonce is used multiple times.
There is another type of replay attacks, it occurs when the Another type of replay attack can occur when the owner deploys a ``ReceiverPays`` smart contract, makes some payments, and then destroys the contract. Later, they decide to deploy the ``RecipientPays`` smart contract again, but the new contract does not know the nonces used in the previous deployment, so the attacker can use the old messages again.
owner deploys a ``ReceiverPays`` smart contract, performs some payments,
and then destroy the contract. Later, she decides to deploy the
``RecipientPays`` smart contract again, but the new contract does not
know the nonces used in the previous deployment, so the attacker
can use the old messages again.
Alice can protect against it including Alice can protect against this attack by including the contract's address in the message, and only messages containing the contract's address itself will be accepted. You can find an example of this in the first two lines of the ``claimPayment()`` function of the full contract at the end of this section.
the contract's address in the message, and only
messages containing contract's address itself will be accepted.
This functionality can be found in the first two lines of the ``claimPayment()`` function in the full contract
at the end of this chapter.
Packing arguments Packing arguments
----------------- -----------------
Now that we have identified what information to include in the Now that we have identified what information to include in the signed message,
signed message, we are ready to put the message together, hash it, we are ready to put the message together, hash it, and sign it. For simplicity,
and sign it. For simplicity, we just concatenate the data. we concatenate the data. The `ethereumjs-abi <https://github.com/ethereumjs/ethereumjs-abi>`_
The library provides a function called ``soliditySHA3`` that mimics the behaviour of
`ethereumjs-abi <https://github.com/ethereumjs/ethereumjs-abi>`_ library provides Solidity's ``keccak256`` function applied to arguments encoded using ``abi.encodePacked``.
a function called ``soliditySHA3`` that mimics the behavior Here is a JavaScript function that creates the proper signature for the ``ReceiverPays`` example:
of Solidity's ``keccak256`` function applied to arguments encoded
using ``abi.encodePacked``.
Putting it all together, here is a JavaScript function that
creates the proper signature for the ``ReceiverPays`` example:
:: ::
@ -748,46 +729,30 @@ creates the proper signature for the ``ReceiverPays`` example:
// nonce can be any unique number to prevent replay attacks // nonce can be any unique number to prevent replay attacks
// contractAddress is used to prevent cross-contract replay attacks // contractAddress is used to prevent cross-contract replay attacks
function signPayment(recipient, amount, nonce, contractAddress, callback) { function signPayment(recipient, amount, nonce, contractAddress, callback) {
var hash = "0x" + ethereumjs.ABI.soliditySHA3( var hash = "0x" + abi.soliditySHA3(
["address", "uint256", "uint256", "address"], ["address", "uint256", "uint256", "address"],
[recipient, amount, nonce, contractAddress] [recipient, amount, nonce, contractAddress]
).toString("hex"); ).toString("hex");
web3.personal.sign(hash, web3.eth.defaultAccount, callback); web3.eth.personal.sign(hash, web3.eth.defaultAccount, callback);
} }
Recovering the Message Signer in Solidity Recovering the Message Signer in Solidity
----------------------------------------- -----------------------------------------
In general, ECDSA signatures consist of two parameters, ``r`` and ``s``. In general, ECDSA signatures consist of two parameters, ``r`` and ``s``. Signatures in Ethereum include a third parameter called ``v``, that you can use to verify which account's private key was used to sign the message, and the transaction's sender. Solidity provides a built-in function `ecrecover <mathematical-and-cryptographic-functions>`_ that accepts a message along with the ``r``, ``s`` and ``v`` parameters and returns the address that was used to sign the message.
Signatures in Ethereum include a third parameter called ``v``, that can be used
to recover which account's private key was used to sign in the message,
the transaction's sender. Solidity provides a built-in function
`ecrecover <mathematical-and-cryptographic-functions>`_
that accepts a message along with the ``r``, ``s`` and ``v`` parameters and
returns the address that was used to sign the message.
Extracting the Signature Parameters Extracting the Signature Parameters
----------------------------------- -----------------------------------
Signatures produced by web3.js are the concatenation of ``r``, ``s`` and ``v``, Signatures produced by web3.js are the concatenation of ``r``, ``s`` and ``v``, so the first step is to split these parameters apart. You can do this on the client-side, but doing it inside the smart contract means you only need to send one signature parameter rather than three. Splitting apart a byte array into component parts is a messy, so we use `inline assembly <assembly>`_ to do the job in the ``splitSignature`` function (the third function in the full contract at the end of this section).
so the first step is splitting those parameters back out. It can be done on the client,
but doing it inside the smart contract means only one signature parameter
needs to be sent rather than three.
Splitting apart a byte array into component parts is a little messy.
We will use `inline assembly <assembly>`_ to do the job
in the ``splitSignature`` function (the third function in the full contract
at the end of this chapter).
Computing the Message Hash Computing the Message Hash
-------------------------- --------------------------
The smart contract needs to know exactly what parameters were signed, The smart contract needs to know exactly what parameters were signed, and so it
and so it must recreate the message from the parameters and use that must recreate the message from the parameters and use that for signature verification.
for signature verification. The functions ``prefixed`` and The functions ``prefixed`` and ``recoverSigner`` do this in the ``claimPayment`` function.
``recoverSigner`` do this and their use can be found in the
``claimPayment`` function.
The full contract The full contract
----------------- -----------------
@ -861,41 +826,26 @@ The full contract
Writing a Simple Payment Channel Writing a Simple Payment Channel
================================ ================================
Alice will now build a simple but complete implementation of a payment channel. Alice now builds a simple but complete implementation of a payment channel. Payment channels use cryptographic signatures to make repeated transfers of Ether securely, instantaneously, and without transaction fees.
Payment channels use cryptographic signatures to make repeated transfers
of Ether securely, instantaneously, and without transaction fees.
What is a Payment Channel? What is a Payment Channel?
-------------------------- --------------------------
Payment channels allow participants to make repeated transfers of Ether without Payment channels allow participants to make repeated transfers of Ether without using transactions. This means that you can avoid the delays and fees associated with transactions. We are going to explore a simple unidirectional payment channel between two parties (Alice and Bob). It involves three steps:
using transactions. This means that the delays and fees associated with transactions
can be avoided. We are going to explore a simple unidirectional payment channel between
two parties (Alice and Bob). Using it involves three steps:
1. Alice funds a smart contract with Ether. This "opens" the payment channel. 1. Alice funds a smart contract with Ether. This "opens" the payment channel.
2. Alice signs messages that specify how much of that Ether is owed to the recipient. This step is repeated for each payment. 2. Alice signs messages that specify how much of that Ether is owed to the recipient. This step is repeated for each payment.
3. Bob "closes" the payment channel, withdrawing their portion of the Ether and sending the remainder back to the sender. 3. Bob "closes" the payment channel, withdrawing their portion of the Ether and sending the remainder back to the sender.
Note that only steps 1 and 3 require Ethereum transactions, step 2 means that .. note::
the sender transmits a cryptographically signed message to the recipient via off chain ways (e.g. email). Only steps 1 and 3 require Ethereum transactions, step 2 means that the sender transmits a cryptographically signed message to the recipient via off chain methods (e.g. email). This means only two transactions are required to support any number of transfers.
This means only two transactions are required to support any number of transfers.
Bob is guaranteed to receive their funds because the smart contract escrows Bob is guaranteed to receive their funds because the smart contract escrows the Ether and honours a valid signed message. The smart contract also enforces a timeout, so Alice is guaranteed to eventually recover their funds even if the recipient refuses to close the channel. It is up to the participants in a payment channel to decide how long to keep it open. For a short-lived transaction, such as paying an internet café for each minute of network access, or for a longer relationship, such as paying an employee an hourly wage, a payment could last for months or years.
the Ether and honors a valid signed message. The smart contract also enforces a timeout,
so Alice is guaranteed to eventually recover their funds even if the recipient refuses
to close the channel.
It is up to the participants in a payment channel to decide how long to keep it open.
For a short-lived transaction, such as paying an internet cafe for each minute of network access,
or for a longer relationship, such as paying an employee an hourly wage, a payment could last for months or years.
Opening the Payment Channel Opening the Payment Channel
--------------------------- ---------------------------
To open the payment channel, Alice deploys the smart contract, To open the payment channel, Alice deploys the smart contract, attaching the Ether to be escrowed and specifying the intended recipient and a maximum duration for the channel to exist. This is the function ``SimplePaymentChannel`` in the contract, at the end of this section.
attaching the Ether to be escrowed and specifying the intendend recipient
and a maximum duration for the channel to exist. It is the function
``SimplePaymentChannel`` in the contract, that is at the end of this chapter.
Making Payments Making Payments
--------------- ---------------
@ -910,27 +860,26 @@ Each message includes the following information:
* The total amount of Ether that is owed the recipient so far. * The total amount of Ether that is owed the recipient so far.
A payment channel is closed just once, at the end of a series of transfers. A payment channel is closed just once, at the end of a series of transfers.
Because of this, only one of the messages sent will be redeemed. This is why Because of this, only one of the messages sent is redeemed. This is why
each message specifies a cumulative total amount of Ether owed, rather than the each message specifies a cumulative total amount of Ether owed, rather than the
amount of the individual micropayment. The recipient will naturally choose to amount of the individual micropayment. The recipient will naturally choose to
redeem the most recent message because that is the one with the highest total. redeem the most recent message because that is the one with the highest total.
The nonce per-message is not needed anymore, because the smart contract will The nonce per-message is not needed anymore, because the smart contract only honors a single message. The address of the smart contract is still used
only honor a single message. The address of the smart contract is still used
to prevent a message intended for one payment channel from being used for a different channel. to prevent a message intended for one payment channel from being used for a different channel.
Here is the modified javascript code to cryptographically sign a message from the previous chapter: Here is the modified JavaScript code to cryptographically sign a message from the previous section:
:: ::
function constructPaymentMessage(contractAddress, amount) { function constructPaymentMessage(contractAddress, amount) {
return ethereumjs.ABI.soliditySHA3( return abi.soliditySHA3(
["address", "uint256"], ["address", "uint256"],
[contractAddress, amount] [contractAddress, amount]
); );
} }
function signMessage(message, callback) { function signMessage(message, callback) {
web3.personal.sign( web3.eth.personal.sign(
"0x" + message.toString("hex"), "0x" + message.toString("hex"),
web3.eth.defaultAccount, web3.eth.defaultAccount,
callback callback
@ -951,18 +900,15 @@ Closing the Payment Channel
When Bob is ready to receive their funds, it is time to When Bob is ready to receive their funds, it is time to
close the payment channel by calling a ``close`` function on the smart contract. close the payment channel by calling a ``close`` function on the smart contract.
Closing the channel pays the recipient the Ether they are owed and destroys the contract, Closing the channel pays the recipient the Ether they are owed and destroys the contract, sending any remaining Ether back to Alice. To close the channel, Bob needs to provide a message signed by Alice.
sending any remaining Ether back to Alice.
To close the channel, Bob needs to provide a message signed by Alice.
The smart contract must verify that the message contains a valid signature from the sender. The smart contract must verify that the message contains a valid signature from the sender.
The process for doing this verification is the same as the process the recipient uses. The process for doing this verification is the same as the process the recipient uses.
The Solidity functions ``isValidSignature`` and ``recoverSigner`` work just like their The Solidity functions ``isValidSignature`` and ``recoverSigner`` work just like their
JavaScript counterparts in the previous section. The latter is borrowed from the JavaScript counterparts in the previous section, with the latter function borrowed from the ``ReceiverPays`` contract.
``ReceiverPays`` contract in the previous chapter.
The ``close`` function can only be called by the payment channel recipient, Only the payment channel recipient can call the ``close`` function,
who will naturally pass the most recent payment message because that message who naturally passes the most recent payment message because that message
carries the highest total owed. If the sender were allowed to call this function, carries the highest total owed. If the sender were allowed to call this function,
they could provide a message with a lower amount and cheat the recipient out of what they are owed. they could provide a message with a lower amount and cheat the recipient out of what they are owed.
@ -977,13 +923,11 @@ Channel Expiration
Bob can close the payment channel at any time, but if they fail to do so, Bob can close the payment channel at any time, but if they fail to do so,
Alice needs a way to recover their escrowed funds. An *expiration* time was set Alice needs a way to recover their escrowed funds. An *expiration* time was set
at the time of contract deployment. Once that time is reached, Alice can call at the time of contract deployment. Once that time is reached, Alice can call
``claimTimeout`` to recover their funds. You can see the ``claimTimeout`` function in the ``claimTimeout`` to recover their funds. You can see the ``claimTimeout`` function in the full contract.
full contract.
After this function is called, Bob can no longer receive any Ether, After this function is called, Bob can no longer receive any Ether,
so it is important that Bob closes the channel before the expiration is reached. so it is important that Bob closes the channel before the expiration is reached.
The full contract The full contract
----------------- -----------------
@ -1081,16 +1025,15 @@ The full contract
} }
Note: The function ``splitSignature`` is very simple and does not use all security checks. .. note::
A real implementation should use a more rigorously tested library, such as The function ``splitSignature`` does not use all security
openzepplin's `version <https://github.com/OpenZeppelin/openzeppelin-solidity/blob/master/contracts/ECRecovery.sol>`_ of this code. checks. A real implementation should use a more rigorously tested library,
such as openzepplin's `version <https://github.com/OpenZeppelin/openzeppelin-solidity/blob/master/contracts/ECRecovery.sol>`_ of this code.
Verifying Payments Verifying Payments
------------------ ------------------
Unlike in our previous chapter, messages in a payment channel aren't Unlike in the previous section, messages in a payment channel aren't
redeemed right away. The recipient keeps track of the latest message and redeemed right away. The recipient keeps track of the latest message and
redeems it when it's time to close the payment channel. This means it's redeems it when it's time to close the payment channel. This means it's
critical that the recipient perform their own verification of each message. critical that the recipient perform their own verification of each message.
@ -1105,10 +1048,8 @@ The recipient should verify each message using the following process:
4. Verify that the signature is valid and comes from the payment channel sender. 4. Verify that the signature is valid and comes from the payment channel sender.
We'll use the `ethereumjs-util <https://github.com/ethereumjs/ethereumjs-util>`_ We'll use the `ethereumjs-util <https://github.com/ethereumjs/ethereumjs-util>`_
library to write this verifications. The final step can be done a number of ways, library to write this verification. The final step can be done a number of ways,
but if it's being done in **JavaScript**. and we use JavaScript. The following code borrows the `constructMessage` function from the signing **JavaScript code** above:
The following code borrows the `constructMessage` function from the signing **JavaScript code**
above:
:: ::