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