diff --git a/docs/source/.conf.py.swp b/docs/source/.conf.py.swp deleted file mode 100644 index 24d0812..0000000 Binary files a/docs/source/.conf.py.swp and /dev/null differ diff --git a/docs/source/advanced.rst b/docs/source/advanced.rst new file mode 100644 index 0000000..3c9c661 --- /dev/null +++ b/docs/source/advanced.rst @@ -0,0 +1,81 @@ +================= +Advanced Examples +================= + +Crypto Conditions +----------------- + +Let's start with a basic use case example. Alice bought a bicycle for €240. +She will use the bike for a year and will give it to her daughter afterwards. +First, we create an asset registering the bicycle: + +.. code-block:: js + + const txCreateAliceSimple = driver.Transaction.makeCreateTransaction( + {'asset': 'bicycle'}, + {'purchase_price': '€240'}, + [ + driver.Transaction.makeOutput(driver.Transaction.makeEd25519Condition(alice.publicKey)) + ], + alice.publicKey + ) + + const txCreateAliceSimpleSigned = driver.Transaction.signTransaction(txCreateAliceSimple, alice.privateKey) + +After a year, she decides it's time to transfer the bicycle to her daughter Carly. +However, Alice wants to maintain the right over the bike so she can possibly sell it. If she would transfer the bicycle to Carly, she won't be able to do this. +So, Alice needs a crypto conditions that defines that she or her daughter can sign the ``TRANSFER`` transaction to a possible buyer. + +We need to define a threshold as well. This defines how many persons have to sign the transaction to ``TRANSFER`` it. +In this case, we define two subconditions with the public keys from Alice and Carly. Next, we set the threshold to **one**. +This means that just one of the subconditions has to sign the transaction to transfer it. +This can be the mother Alice, or Carly herself. + +.. code-block:: js + + // Create condition for Alice and Carly + let subConditionFrom = driver.Transaction.makeEd25519Condition(alice.publicKey, false) + let subConditionTo = driver.Transaction.makeEd25519Condition(carly.publicKey, false) + + // Create condition object with threshold and subconditions + let condition = driver.Transaction.makeThresholdCondition(1, [subConditionFrom, subConditionTo]) + + // Generate output with condition added + let output = driver.Transaction.makeOutput(condition) + + // Add Carly to the output.public_keys field so she is the owner + output.public_keys = [carly.publicKey] + + let transaction = driver.Transaction.makeTransferTransaction( + txCreateAliceSimpleSigned, + {'meta': 'Transfer to new user with conditions'}, + [output], + 0 + ); + + // Add alice as previous owner + transaction.inputs[0].owners_before = [alice.publicKey] + + // Because the addition of crypto conditions, the id for the transaction has to be regenerated + delete transaction.id + transaction.id = sha3.sha3_256 + .create() + .update(driver.Transaction.serializeTransactionIntoCanonicalString(transaction)) + .hex() + + // Alice has to sign this transfer because she is still the owner of the created asset + let signedCryptoConditionTx = driver.Transaction.signTransaction(transaction, alice.privateKey) + +As you can see, we need to generate a new transactionId because we have added crypto conditions. +We do this with the js-sha3 package, you need to install this package through ``npm``: + +``npm install --save js-sha3`` + +Don't forget to import the package in your code: + +.. code-block:: js + + import * as sha3 from 'js-sha3' + + +.. TODO: Document Utils when finished diff --git a/docs/source/conf.py b/docs/source/conf.py index d9027d1..dfbf3f9 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -105,7 +105,8 @@ html_theme = 'sphinx_rtd_theme' # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ['nstatic'] +# html_static_path = ['nstatic'] +# Commented out this option because Sphinx can not find the path # Custom sidebar templates, must be a dictionary that maps document names # to template names. diff --git a/docs/source/index.rst b/docs/source/index.rst index 6443cba..cc3f2d9 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -8,6 +8,7 @@ BigchainDB Javascript Driver Documentation readme quickstart usage + advanced Indices and tables ================== diff --git a/docs/source/usage.rst b/docs/source/usage.rst index 27248e6..edcf73f 100644 --- a/docs/source/usage.rst +++ b/docs/source/usage.rst @@ -356,6 +356,32 @@ Recap: Asset Creation & Transfer // Search for asset based on the serial number of the bicycle .then(() => conn.searchAssets('Bicycle Inc.')) .then(assets => console.log('Found assets with serial number Bicycle Inc.:', assets)) + + +Ed25519Keypair Seed Functionality +--------------------------------- + +BigchainDB JavaScript driver allows you to create a keypair based on a seed. +The constructor accepts a 32 byte seed. One of the ways to create a seed from +a string (e.g. a passphrase) is the one used by ``bip39``, specifically the function ``mnemonicToSeed``. + +Install bip39 with npm: ``npm install bip39`` + +Next, require ``bip39`` in your file like this: ``var bip39 = require('bip39')`` + +At last, we can create the keypair based on a string. The function will transform the string to a byte array. +As our constructor ``Ed25519Keypair()`` only accepts a seed of 32 bytes, we slice the first 32 bytes: ``slice(0,32)``. + +.. code-block:: js + + var keypair = new driver.Ed25519Keypair(bip39.mnemonicToSeed("yourString").slice(0, 32)) + +You can use the ``Ed25519Keypair()`` constructor as well without seed. + +.. code-block:: js + + var keypair = new driver.Ed25519Keypair() + Websocket Event Stream API Usage @@ -614,7 +640,6 @@ Output of above code looks like this. As you can see, Chris has no spent output, Spent outputs for Chris: 0 Unspent outputs for Chris: 1 - Divisible Assets ----------------