From 8e7c213fb9914bcc55603ccb91ab5820987f4cf8 Mon Sep 17 00:00:00 2001 From: michielmulders Date: Mon, 9 Oct 2017 15:09:23 +0200 Subject: [PATCH] Finished divisible asset example --- docs/source/usage.rst | 100 +++++++++++++++++++++++++++++++++++++++--- 1 file changed, 95 insertions(+), 5 deletions(-) diff --git a/docs/source/usage.rst b/docs/source/usage.rst index 4b958bb..ce265af 100644 --- a/docs/source/usage.rst +++ b/docs/source/usage.rst @@ -64,7 +64,7 @@ that represents a bicycle: .. code-block:: js - assetdata = { + const assetdata = { 'bicycle': { 'serial_number': 'abcd1234', 'manufacturer': 'Bicycle Inc.', @@ -86,7 +86,7 @@ For example, the bicycle will be transferred on earth which is metadata: .. code-block:: js - metadata = {'planet': 'earth'} + const metadata = {'planet': 'earth'} Asset Creation -------------- @@ -288,7 +288,7 @@ Recap: Asset Creation & Transfer // Define the asset to store, in this example // we store a bicycle with its serial number and manufacturer - assetdata = { + const assetdata = { 'bicycle': { 'serial_number': 'cde', 'manufacturer': 'Bicycle Inc.', @@ -298,7 +298,7 @@ Recap: Asset Creation & Transfer // Metadata contains information about the transaction itself // (can be `null` if not needed) // E.g. the bicycle is fabricated on earth - metadata = {'planet': 'earth'} + const metadata = {'planet': 'earth'} // Construct a transaction payload const txCreateAliceSimple = driver.Transaction.makeCreateTransaction( @@ -360,7 +360,97 @@ Recap: Asset Creation & Transfer Divisible Assets ---------------- -Yet to come! +All assets in BigchainDB become implicitly divisible if a transaction contains more than one of that asset (we’ll see how this happens shortly). + +Let's assume we have created a token to pay each other for small transactions like a beer or some food between friends. + +.. code-block:: js + + const token = { + 'value': '1 euro' + } + +Let's create the asset. Note that we give an extra parameter to the ``makeOutput()`` function. +We give it the parameter ``'4'`` to indicate that we want to create 4 tokens. +**Pay attention to give the function a String instead of a plain Number.** + +.. code-block:: js + + const txCreateAliceDivisible = driver.Transaction.makeCreateTransaction( + token, + {metaDataMessage: 'I am specific to this create transaction'}, + [driver.Transaction.makeOutput(driver.Transaction.makeEd25519Condition(alice.publicKey), '4')], + alice.publicKey + ) + +Alice goes dining at Bob and Carly. She decides to give a small fee to Bob and Carly. +Alice decides to issue 4 tokens as a payment for her food: one to Bob, two to Carly and one to herself. +Why one to herself? If you decide to fulfill an output, you have to spend all tokens. +So if you want to keep one token for yourself, you have to transfer it to yourself. +As you can see, we fulfill the first output of the create transaction (it's 0 because we start counting from 0). +This gives us 4 tokens to transfer. + +.. code-block:: js + + const txTransferDivisible = driver.Transaction.makeTransferTransaction( + txCreateAliceDivisibleSigned, + { + metaDataMessage: 'I am specific to this transfer transaction' + }, + [ + driver.Transaction.makeOutput(driver.Transaction.makeEd25519Condition(carly.publicKey), '2'), + driver.Transaction.makeOutput(driver.Transaction.makeEd25519Condition(bob.publicKey), '1'), + driver.Transaction.makeOutput(driver.Transaction.makeEd25519Condition(alice.publicKey), '1') + ], 0); + +To make the use of the last parameter of ``makeTransferTransaction()`` function more clear, we will do another transfer. +We will fulfill the first and second output of the create transaction (0, 1) because Carly and Bob decide to redistribute some money. + +* Output 0 represents 2 tokens for Carly +* Output 1 represents 1 token for Bob + +This gives us 3 tokens to redistribute. I want to give 1 token to Carly and 2 tokens Alice. + +.. code-block:: js + + const txTransferDivisibleInputs = driver.Transaction.makeTransferTransaction( + txTransferDivisibleSigned, + { + metaDataMessage: 'I am specific to this transfer transaction' + }, + [ + driver.Transaction.makeOutput(driver.Transaction.makeEd25519Condition(carly.publicKey), '1'), + driver.Transaction.makeOutput(driver.Transaction.makeEd25519Condition(alice.publicKey), '2') + ], 0, 1) + +Because we want to fulfill two outputs (Carly and Bob), we have to sign the transfer transaction in the same order: + +.. code-block:: js + + const txTransferDivisibleInputsSigned = driver.Transaction.signTransaction( + txTransferDivisibleInputs, + carly.privateKey, bob.privateKey) + +Here is a better overview of the flow of the tokens. + ++-----------+------------+-----------------+ +| **Owner** | **Amount** | **Transaction** | ++===========+============+=================+ +| ``Alice`` | 4 | ``CREATE`` | ++-----------+------------+-----------------+ +| ``Alice`` | 1 | ``TRANSFER 1`` | ++-----------+------------+-----------------+ +| ``Bob`` | 1 | ``TRANSFER 1`` | ++-----------+------------+-----------------+ +| ``Carly`` | 2 | ``TRANSFER 1`` | ++-----------+------------+-----------------+ +| ``Alice`` | 3 | ``TRANSFER 2`` | ++-----------+------------+-----------------+ +| ``Bob`` | 0 | ``TRANSFER 2`` | ++-----------+------------+-----------------+ +| ``Carly`` | 1 | ``TRANSFER 2`` | ++-----------+------------+-----------------+ + .. TODO: .. - Add lexer: https://stackoverflow.com/questions/4259105/which-sphinx-code-block-language-to-use-for-json