mirror of
https://github.com/bigchaindb/bigchaindb.git
synced 2024-10-13 13:34:05 +00:00
83 lines
4.2 KiB
ReStructuredText
83 lines
4.2 KiB
ReStructuredText
The Transaction Model
|
|
=====================
|
|
|
|
A transaction has the following structure:
|
|
|
|
.. code-block:: json
|
|
|
|
{
|
|
"id": "<ID of the transaction>",
|
|
"version": "<Transaction schema version number>",
|
|
"inputs": ["<List of inputs>"],
|
|
"outputs": ["<List of outputs>"],
|
|
"operation": "<String>",
|
|
"asset": {"<Asset model; see below>"},
|
|
"metadata": {"<Arbitrary transaction metadata>"}
|
|
}
|
|
|
|
Here's some explanation of the contents:
|
|
|
|
- **id**: The ID of the transaction and also the hash of the transaction (loosely speaking). See below for an explanation of how it's computed. It's also the database primary key.
|
|
|
|
- **version**: The version-number of the transaction schema. As of BigchainDB Server 1.0.0, the only allowed value is ``"1.0"``.
|
|
|
|
- **inputs**: List of inputs.
|
|
Each input spends/transfers a previous output by satisfying/fulfilling
|
|
the crypto-conditions on that output.
|
|
A CREATE transaction should have exactly one input.
|
|
A TRANSFER transaction should have at least one input (i.e. ≥1).
|
|
|
|
- **outputs**: List of outputs.
|
|
Each output indicates the crypto-conditions which must be satisfied
|
|
by anyone wishing to spend/transfer that output.
|
|
It also indicates the number of shares of the asset tied to that output.
|
|
|
|
- **operation**: A string indicating what kind of transaction this is,
|
|
and how it should be validated.
|
|
It can only be ``"CREATE"``, ``"TRANSFER"`` or ``"GENESIS"``
|
|
(but there should only be one transaction whose operation is ``"GENESIS"``:
|
|
the one in the GENESIS block).
|
|
|
|
- **asset**: A JSON document for the asset associated with the transaction.
|
|
(A transaction can only be associated with one asset.)
|
|
See :ref:`the page about the asset model <The Asset Model>`.
|
|
|
|
- **metadata**: User-provided transaction metadata.
|
|
It can be any valid JSON document, or ``null``.
|
|
**NOTE:** When using MongoDB for storage, certain restriction apply
|
|
to all (including nested) keys of the JSON document:
|
|
1) keys (i.e. key names, not values) must **not** begin with the ``$`` character, and
|
|
2) keys must not contain ``.`` or the null character (Unicode code point 0000).
|
|
3) The key `"language"` (at any level in the hierarchy) is a special key and used for specifying text search language. Its value must be one of the allowed values; see the valid `Text Search Languages <https://docs.mongodb.com/manual/reference/text-search-languages/>`_ in the MongoDB Docs. In BigchainDB, only the languages supported by *MongoDB community edition* are allowed.
|
|
|
|
**How the transaction ID is computed.**
|
|
1) Build a Python dictionary containing ``version``, ``inputs``, ``outputs``, ``operation``, ``asset``, ``metadata`` and their values,
|
|
2) In each of the inputs, replace the value of each ``fulfillment`` with ``null``,
|
|
3) :ref:`Serialize <JSON Serialization>` that dictionary,
|
|
4) The transaction ID is just :ref:`the SHA3-256 hash <Hashes>` of the serialized dictionary.
|
|
|
|
**About signing the 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 input. What gets signed (as of version 1.0.0) is everything inside the transaction, including the ``id``, but the value of each ``fulfillment`` is replaced with ``null``.
|
|
|
|
There are example BigchainDB transactions in
|
|
:ref:`the HTTP API documentation <The HTTP Client-Server API>`
|
|
and
|
|
`the Python Driver documentation <https://docs.bigchaindb.com/projects/py-driver/en/latest/usage.html>`_.
|
|
|
|
|
|
The Transaction Schema
|
|
----------------------
|
|
|
|
BigchainDB checks all transactions (JSON documents)
|
|
against a formal schema defined
|
|
in some `JSON Schema <http://json-schema.org/>`_ files.
|
|
Those files are part of the IPDB Protocol.
|
|
Their official source is the ``tx_schema/`` directory
|
|
in the `ipdb/ipdb-protocol repository on GitHub
|
|
<https://github.com/ipdb/ipdb-protocol>`_,
|
|
but BigchainDB Server uses copies of those files;
|
|
those copies can be found
|
|
in the ``bigchaindb/common/schema/`` directory
|
|
in the `bigchaindb/bigchaindb repository on GitHub
|
|
<https://github.com/bigchaindb/bigchaindb>`_.
|