From 791de0d760f10af55c6f765b4f95ced63912468b Mon Sep 17 00:00:00 2001 From: michielmulders Date: Thu, 28 Sep 2017 13:15:40 +0200 Subject: [PATCH 1/4] Seed Functionality integrated in docs --- docs/source/.conf.py.swp | Bin 1024 -> 0 bytes docs/source/conf.py | 3 ++- docs/source/usage.rst | 19 +++++++++++++++++++ 3 files changed, 21 insertions(+), 1 deletion(-) delete mode 100644 docs/source/.conf.py.swp diff --git a/docs/source/.conf.py.swp b/docs/source/.conf.py.swp deleted file mode 100644 index 24d08126d6feeea5e2c82d1753bb7f9332ccdf16..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 1024 zcmYc?$V<%2S1{5u)iY*50v)p%7;-a{Gcr?ikVLUFOOs0TN=mWIA&VyG=cVZtR3ZzF NvPVN;Gz11P1OQ conn.searchAssets('Bicycle Inc.')) .then(assets => console.log('Found assets with serial number Bicycle Inc.:', assets)) +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)) + + Divisible Assets ---------------- From 25054cc136c517cab09a4b7fe5e51dd08bee06db Mon Sep 17 00:00:00 2001 From: michielmulders Date: Thu, 28 Sep 2017 13:16:01 +0200 Subject: [PATCH 2/4] Small update to seed func docs --- docs/source/usage.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/source/usage.rst b/docs/source/usage.rst index 42689b4..ee7120a 100644 --- a/docs/source/usage.rst +++ b/docs/source/usage.rst @@ -357,8 +357,8 @@ Recap: Asset Creation & Transfer .then(() => conn.searchAssets('Bicycle Inc.')) .then(assets => console.log('Found assets with serial number Bicycle Inc.:', assets)) -Seed Functionality ------------------- +Seed Functionality Ed25519Keypair +--------------------------------- 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 From 49fe2e879e30479296eb64cb4d70c8f5af994d01 Mon Sep 17 00:00:00 2001 From: michielmulders Date: Thu, 28 Sep 2017 13:33:19 +0200 Subject: [PATCH 3/4] Added sentence to inform that a seed is not obligatory --- docs/source/usage.rst | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/docs/source/usage.rst b/docs/source/usage.rst index ee7120a..4324c2c 100644 --- a/docs/source/usage.rst +++ b/docs/source/usage.rst @@ -357,10 +357,10 @@ Recap: Asset Creation & Transfer .then(() => conn.searchAssets('Bicycle Inc.')) .then(assets => console.log('Found assets with serial number Bicycle Inc.:', assets)) -Seed Functionality Ed25519Keypair +Ed25519Keypair Seed Functionality --------------------------------- -BigchainDB JavaScript driver allows you to create a keypair based on a seed. +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``. @@ -375,6 +375,11 @@ As our constructor ``Ed25519Keypair()`` only accepts a seed of 32 bytes, we slic 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() Divisible Assets ---------------- From 1dc8bb98839ced066c8cd8b7022eb8b87a361b67 Mon Sep 17 00:00:00 2001 From: michielmulders Date: Sun, 15 Oct 2017 18:39:00 +0200 Subject: [PATCH 4/4] remove file --- docs/source/advanced.rst | 81 ++++++++++++++++++++++++++++++++++++++++ docs/source/index.rst | 1 + 2 files changed, 82 insertions(+) create mode 100644 docs/source/advanced.rst 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/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 ==================