From c8228d7ff721ad1441c826f26a73ee73a6d30728 Mon Sep 17 00:00:00 2001 From: Scott Sadler Date: Wed, 23 Nov 2016 16:14:11 +0100 Subject: [PATCH 1/6] move 'Data Models' from root to server docs and make links to schema --- .../source/data-models/transaction-model.md | 43 ------------- docs/root/source/index.rst | 1 - docs/server/source/conf.py | 1 + .../source/data-models/asset-model.md | 0 .../source/data-models/block-model.rst | 0 .../source/data-models/crypto-conditions.md | 0 .../source/data-models/index.rst | 0 .../source/data-models/transaction-model.rst | 62 +++++++++++++++++++ .../source/data-models/vote-model.md | 0 docs/server/source/index.rst | 1 + 10 files changed, 64 insertions(+), 44 deletions(-) delete mode 100644 docs/root/source/data-models/transaction-model.md rename docs/{root => server}/source/data-models/asset-model.md (100%) rename docs/{root => server}/source/data-models/block-model.rst (100%) rename docs/{root => server}/source/data-models/crypto-conditions.md (100%) rename docs/{root => server}/source/data-models/index.rst (100%) create mode 100644 docs/server/source/data-models/transaction-model.rst rename docs/{root => server}/source/data-models/vote-model.md (100%) diff --git a/docs/root/source/data-models/transaction-model.md b/docs/root/source/data-models/transaction-model.md deleted file mode 100644 index f9503093..00000000 --- a/docs/root/source/data-models/transaction-model.md +++ /dev/null @@ -1,43 +0,0 @@ -# The Transaction Model - -A transaction has the following structure: - -```json -{ - "id": "", - "version": "", - "transaction": { - "fulfillments": [""], - "conditions": [""], - "operation": "", - "asset": "", - "metadata": { - "id": "", - "data": "" - } - } -} -``` - -Here's some explanation of the contents of a transaction: - -- `id`: The hash of everything inside the serialized `transaction` body (i.e. `fulfillments`, `conditions`, `operation`, and `data`; see below), with one wrinkle: for each fulfillment in `fulfillments`, `fulfillment` is set to `null`. The `id` is also the database primary key. -- `version`: Version number of the transaction model, so that software can support different transaction models. -- `transaction`: - - `fulfillments`: List of fulfillments. Each _fulfillment_ contains a pointer to an unspent asset - and a _crypto fulfillment_ that satisfies a spending condition set on the unspent asset. A _fulfillment_ - is usually a signature proving the ownership of the asset. - See the page about [Crypto-Conditions and Fulfillments](crypto-conditions.html). - - `conditions`: List of conditions. Each _condition_ is a _crypto-condition_ that needs to be fulfilled by a transfer transaction in order to transfer ownership to new owners. - See the page about [Crypto-Conditions and Fulfillments](crypto-conditions.html). - - `operation`: String representation of the operation being performed (currently either "CREATE", "TRANSFER" or "GENESIS"). It determines how the transaction should be validated. - - `asset`: Definition of the digital asset. See next section. - - `metadata`: - - `id`: UUID version 4 (random) converted to a string of hex digits in standard form. - - `data`: Can be any JSON document. It may be empty in the case of a transfer transaction. - -Later, when we get to the models for the block and the vote, we'll see that both include a signature (from the node which created it). You may wonder why transactions don't have signatures... The answer is that they do! They're just hidden inside the `fulfillment` string of each fulfillment. A creation transaction is signed by the node that created it. A transfer transaction is signed by whoever currently controls or owns it. - -What gets signed? For each fulfillment in the transaction, the "fullfillment message" that gets signed includes the `operation`, `data`, `version`, `id`, corresponding `condition`, and the fulfillment itself, except with its fulfillment string set to `null`. The computed signature goes into creating the `fulfillment` string of the fulfillment. - -One other note: Currently, transactions contain only the public keys of asset-owners (i.e. who own an asset or who owned an asset in the past), inside the conditions and fulfillments. A transaction does _not_ contain the public key of the client (computer) which generated and sent it to a BigchainDB node. In fact, there's no need for a client to _have_ a public/private keypair. In the future, each client may also have a keypair, and it may have to sign each sent transaction (using its private key); see [Issue #347 on GitHub](https://github.com/bigchaindb/bigchaindb/issues/347). In practice, a person might think of their keypair as being both their "ownership-keypair" and their "client-keypair," but there is a difference, just like there's a difference between Joe and Joe's computer. diff --git a/docs/root/source/index.rst b/docs/root/source/index.rst index c8ddb1ff..534f2901 100644 --- a/docs/root/source/index.rst +++ b/docs/root/source/index.rst @@ -86,4 +86,3 @@ More About BigchainDB smart-contracts transaction-concepts timestamps - data-models/index diff --git a/docs/server/source/conf.py b/docs/server/source/conf.py index ab9531fd..c0de76d7 100644 --- a/docs/server/source/conf.py +++ b/docs/server/source/conf.py @@ -43,6 +43,7 @@ extensions = [ 'sphinx.ext.viewcode', 'sphinx.ext.napoleon', 'sphinxcontrib.httpdomain', + 'sphinx.ext.autosectionlabel', ] # autodoc settings diff --git a/docs/root/source/data-models/asset-model.md b/docs/server/source/data-models/asset-model.md similarity index 100% rename from docs/root/source/data-models/asset-model.md rename to docs/server/source/data-models/asset-model.md diff --git a/docs/root/source/data-models/block-model.rst b/docs/server/source/data-models/block-model.rst similarity index 100% rename from docs/root/source/data-models/block-model.rst rename to docs/server/source/data-models/block-model.rst diff --git a/docs/root/source/data-models/crypto-conditions.md b/docs/server/source/data-models/crypto-conditions.md similarity index 100% rename from docs/root/source/data-models/crypto-conditions.md rename to docs/server/source/data-models/crypto-conditions.md diff --git a/docs/root/source/data-models/index.rst b/docs/server/source/data-models/index.rst similarity index 100% rename from docs/root/source/data-models/index.rst rename to docs/server/source/data-models/index.rst diff --git a/docs/server/source/data-models/transaction-model.rst b/docs/server/source/data-models/transaction-model.rst new file mode 100644 index 00000000..4c5a68fc --- /dev/null +++ b/docs/server/source/data-models/transaction-model.rst @@ -0,0 +1,62 @@ +.. raw:: html + + + +===================== +The Transaction Model +===================== + +A transaction has the following structure: + +.. code-block:: json + + { + "id": "", + "version": "", + "transaction": { + "fulfillments": [""], + "conditions": [""], + "operation": "", + "asset": "", + "metadata": { + "id": "", + "data": "" + } + } + } + +Here's some explanation of the contents of a :ref:`transaction `: + +- :ref:`id `: The id of the transaction, and also the database primary key. +- :ref:`version `: Version number of the transaction model, so that software can support different transaction models. +- :ref:`transaction `: + - **fulfillments**: List of fulfillments. Each :ref:`fulfillment ` contains a pointer to an unspent asset + and a *crypto fulfillment* that satisfies a spending condition set on the unspent asset. A *fulfillment* + is usually a signature proving the ownership of the asset. + See :doc:`./crypto-conditions`. + + - **conditions**: List of conditions. Each :ref:`condition ` is a *crypto-condition* that needs to be fulfilled by a transfer transaction in order to transfer ownership to new owners. + See :doc:`./crypto-conditions`. + + - **operation**: String representation of the :ref:`operation ` being performed (currently either "CREATE", "TRANSFER" or "GENESIS"). It determines how the transaction should be validated. + + - **asset**: Definition of the digital :ref:`asset `. See next section. + + - **metadata**: + - :ref:`id `: UUID version 4 (random) converted to a string of hex digits in standard form. + - :ref:`data `: Can be any JSON document. It may be empty in the case of a transfer transaction. + +Later, when we get to the models for the block and the vote, we'll see that both include a signature (from the node which created it). You may wonder why transactions don't have signatures... The answer is that they do! They're just hidden inside the ``fulfillment`` string of each fulfillment. A creation transaction is signed by the node that created it. A transfer transaction is signed by whoever currently controls or owns it. + +What gets signed? For each fulfillment in the transaction, the "fullfillment message" that gets signed includes the ``operation``, ``data``, ``version``, ``id``, corresponding ``condition``, and the fulfillment itself, except with its fulfillment string set to ``null``. The computed signature goes into creating the ``fulfillment`` string of the fulfillment. + +One other note: Currently, transactions contain only the public keys of asset-owners (i.e. who own an asset or who owned an asset in the past), inside the conditions and fulfillments. A transaction does *not* contain the public key of the client (computer) which generated and sent it to a BigchainDB node. In fact, there's no need for a client to *have* a public/private keypair. In the future, each client may also have a keypair, and it may have to sign each sent transaction (using its private key); see `Issue #347 on GitHub `_. In practice, a person might think of their keypair as being both their "ownership-keypair" and their "client-keypair," but there is a difference, just like there's a difference between Joe and Joe's computer. diff --git a/docs/root/source/data-models/vote-model.md b/docs/server/source/data-models/vote-model.md similarity index 100% rename from docs/root/source/data-models/vote-model.md rename to docs/server/source/data-models/vote-model.md diff --git a/docs/server/source/index.rst b/docs/server/source/index.rst index 572e573f..1c2b4428 100644 --- a/docs/server/source/index.rst +++ b/docs/server/source/index.rst @@ -14,6 +14,7 @@ BigchainDB Server Documentation drivers-clients/index clusters-feds/index topic-guides/index + data-models/index schema/transaction release-notes appendices/index From 01037a0b82168b5902b67c6f636d4a72f3adb3a0 Mon Sep 17 00:00:00 2001 From: Scott Sadler Date: Wed, 23 Nov 2016 16:14:27 +0100 Subject: [PATCH 2/6] fix warning generated in schema/transaction.rst --- docs/server/source/schema/transaction.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/server/source/schema/transaction.rst b/docs/server/source/schema/transaction.rst index 68abab0c..766e0c4a 100644 --- a/docs/server/source/schema/transaction.rst +++ b/docs/server/source/schema/transaction.rst @@ -157,8 +157,8 @@ Condition.cid **type:** integer -Index of this condition's appearance in the `Transaction.conditions`_ -array. In a transaction with 2 conditions, the ``cid``s will be 0 and 1. +Index of this condition's appearance in the Transaction.conditions_ +array. In a transaction with 2 conditions, the ``cid``\ s will be 0 and 1. From 85b34227991ad14a00a9ad65817c3ba4a333544f Mon Sep 17 00:00:00 2001 From: Scott Sadler Date: Thu, 24 Nov 2016 10:01:20 +0100 Subject: [PATCH 3/6] leave link to Data Models in root section with hard link --- docs/root/source/index.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/root/source/index.rst b/docs/root/source/index.rst index 534f2901..003d07b3 100644 --- a/docs/root/source/index.rst +++ b/docs/root/source/index.rst @@ -86,3 +86,4 @@ More About BigchainDB smart-contracts transaction-concepts timestamps + Data Models From 0ab6e2b43276a0952bf572e9ba5ac2965c8f15ae Mon Sep 17 00:00:00 2001 From: Scott Sadler Date: Thu, 24 Nov 2016 10:06:36 +0100 Subject: [PATCH 4/6] fix duplicate label in aws testing cluster docs --- docs/server/source/clusters-feds/aws-testing-cluster.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/server/source/clusters-feds/aws-testing-cluster.md b/docs/server/source/clusters-feds/aws-testing-cluster.md index 2e75584f..942871e3 100644 --- a/docs/server/source/clusters-feds/aws-testing-cluster.md +++ b/docs/server/source/clusters-feds/aws-testing-cluster.md @@ -32,7 +32,7 @@ What did you just install? * [The aws-cli package](https://pypi.python.org/pypi/awscli), which is an AWS Command Line Interface (CLI). -## Basic AWS Setup +## Setting up in AWS See the page about [basic AWS Setup](../appendices/aws-setup.html) in the Appendices. From a002c380096647ee1cb6640e74d53733acb5d4f5 Mon Sep 17 00:00:00 2001 From: Scott Sadler Date: Thu, 24 Nov 2016 10:08:06 +0100 Subject: [PATCH 5/6] updating wording for transaction creation in transaction-model.rst --- docs/server/source/data-models/transaction-model.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/server/source/data-models/transaction-model.rst b/docs/server/source/data-models/transaction-model.rst index 4c5a68fc..b325e6fe 100644 --- a/docs/server/source/data-models/transaction-model.rst +++ b/docs/server/source/data-models/transaction-model.rst @@ -55,7 +55,7 @@ Here's some explanation of the contents of a :ref:`transaction `: - :ref:`id `: UUID version 4 (random) converted to a string of hex digits in standard form. - :ref:`data `: Can be any JSON document. It may be empty in the case of a transfer transaction. -Later, when we get to the models for the block and the vote, we'll see that both include a signature (from the node which created it). You may wonder why transactions don't have signatures... The answer is that they do! They're just hidden inside the ``fulfillment`` string of each fulfillment. A creation transaction is signed by the node that created it. A transfer transaction is signed by whoever currently controls or owns it. +Later, when we get to the models for the block and the vote, we'll see that both include a signature (from the node which created it). You may wonder why transactions don't have signatures... The answer is that they do! They're just hidden inside the ``fulfillment`` string of each fulfillment. A creation transaction is signed by whoever created it. A transfer transaction is signed by whoever currently controls or owns it. What gets signed? For each fulfillment in the transaction, the "fullfillment message" that gets signed includes the ``operation``, ``data``, ``version``, ``id``, corresponding ``condition``, and the fulfillment itself, except with its fulfillment string set to ``null``. The computed signature goes into creating the ``fulfillment`` string of the fulfillment. From db673838fdb702bd07cd494ad91500915b6acf30 Mon Sep 17 00:00:00 2001 From: Scott Sadler Date: Thu, 24 Nov 2016 10:09:26 +0100 Subject: [PATCH 6/6] remove distracting para from transaction-model.rst docs --- docs/server/source/data-models/transaction-model.rst | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/server/source/data-models/transaction-model.rst b/docs/server/source/data-models/transaction-model.rst index b325e6fe..2bee661f 100644 --- a/docs/server/source/data-models/transaction-model.rst +++ b/docs/server/source/data-models/transaction-model.rst @@ -58,5 +58,3 @@ Here's some explanation of the contents of a :ref:`transaction `: Later, when we get to the models for the block and the vote, we'll see that both include a signature (from the node which created it). You may wonder why transactions don't have signatures... The answer is that they do! They're just hidden inside the ``fulfillment`` string of each fulfillment. A creation transaction is signed by whoever created it. A transfer transaction is signed by whoever currently controls or owns it. What gets signed? For each fulfillment in the transaction, the "fullfillment message" that gets signed includes the ``operation``, ``data``, ``version``, ``id``, corresponding ``condition``, and the fulfillment itself, except with its fulfillment string set to ``null``. The computed signature goes into creating the ``fulfillment`` string of the fulfillment. - -One other note: Currently, transactions contain only the public keys of asset-owners (i.e. who own an asset or who owned an asset in the past), inside the conditions and fulfillments. A transaction does *not* contain the public key of the client (computer) which generated and sent it to a BigchainDB node. In fact, there's no need for a client to *have* a public/private keypair. In the future, each client may also have a keypair, and it may have to sign each sent transaction (using its private key); see `Issue #347 on GitHub `_. In practice, a person might think of their keypair as being both their "ownership-keypair" and their "client-keypair," but there is a difference, just like there's a difference between Joe and Joe's computer.