mirror of
https://github.com/bigchaindb/bigchaindb.git
synced 2024-10-13 13:34:05 +00:00
8343bab89f
Commit messages for posterity: * wip transaction schema definition * test for SchemaObject * test SchemaObject definions meta property * schema documentation updates * test for basic validation * commit before change to .json file definiton + rst generation * move to straight .json schema, test for additionalProperties on each object * add asset to transaction definiton * remove outdated tx validation * make all tests pass * create own exception for validation error and start validating transactions * more tx validation fixes * move to yaml file for schema * automatic schema documentation generator * remove redundant section * use YAML safe loading * change current_owners to owners_before in tx schema * re-run tests and make correct yaml schema * fix some broken tests * update Release_Process.md * move tx validation into it's own method * add jsonschema dependency * perform schema validation after ID validation on Transaction * Release_Process.md, markdown auto numbering * remove old transaction.json * resolve remaining TODOs in schema docuementation * add `id` and `$schema` to transaction.yaml * add transaction.yaml to setup.py so it gets copied * address some concernes in PR for transaction.yaml * address more PR concerns in transaction.yaml * refactor validtion exceptions and move transaction schema validation into it's own function in bigchaindb.common.schema.__init__ * add note to generated schema.rst indicating when and how it's generated * move tx schema validation back above ID validation in Transaction.validate_structure, test that structurally invalid transaction gets caught and 400 returned in TX POST handler * remove timestamp from transaction schema index * Add README.md to bigchaindb.common.schema for introduction to JSON Schema and reasons for YAML * Use constant for schema definitions' base prefix * Move import of ValidationError exception into only the tests that require it * Move validate transaction test helper to tests/common/util.py * move ordered transaction schema load to generate_schema_documentation.py where it's needed * use double backticks to render terms in schema docs * change more backticks and change transaction version description in transaction schema * make details a mandatory property of condition * Many more documentation fixes * rename schema.rst to schema/transaction.rst * Fix documentation for Metadata * Add more links to documentation * Various other documentation fixes * Rename section titles in rendered documentation * use to manage file handle * fix extrenuous comma in test_tx_serialization_with_incorrect_hash args * 'a' * 64 * remove schema validation until we can analyze properly impact on downstream consumers * fix flake8 error * use `with` always
336 lines
5.4 KiB
ReStructuredText
336 lines
5.4 KiB
ReStructuredText
.. This file was auto generated by generate_schema_documentation.py
|
|
|
|
==================
|
|
Transaction Schema
|
|
==================
|
|
|
|
* `Transaction`_
|
|
|
|
* `Transaction Body`_
|
|
|
|
* Condition_
|
|
|
|
* Fulfillment_
|
|
|
|
* Asset_
|
|
|
|
* Metadata_
|
|
|
|
.. raw:: html
|
|
|
|
<style>
|
|
#transaction-schema h2 {
|
|
border-top: solid 3px #6ab0de;
|
|
background-color: #e7f2fa;
|
|
padding: 5px;
|
|
}
|
|
#transaction-schema h3 {
|
|
background: #f0f0f0;
|
|
border-left: solid 3px #ccc;
|
|
font-weight: bold;
|
|
padding: 6px;
|
|
font-size: 100%;
|
|
font-family: monospace;
|
|
}
|
|
</style>
|
|
|
|
Transaction
|
|
-----------
|
|
|
|
This is the outer transaction wrapper. It contains the ID, version and the body of the transaction, which is also called ``transaction``.
|
|
|
|
|
|
Transaction.id
|
|
^^^^^^^^^^^^^^
|
|
|
|
**type:** string
|
|
|
|
A sha3 digest of the transaction. The ID is calculated by removing all
|
|
derived hashes and signatures from the transaction, serializing it to
|
|
JSON with keys in sorted order and then hashing the resulting string
|
|
with sha3.
|
|
|
|
|
|
|
|
Transaction.transaction
|
|
^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
**type:** object
|
|
|
|
See: `Transaction Body`_.
|
|
|
|
|
|
|
|
Transaction.version
|
|
^^^^^^^^^^^^^^^^^^^
|
|
|
|
**type:** integer
|
|
|
|
BigchainDB transaction schema version.
|
|
|
|
|
|
|
|
|
|
|
|
Transaction Body
|
|
----------------
|
|
|
|
See: `Transaction Body`_.
|
|
|
|
|
|
Transaction.operation
|
|
^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
**type:** string
|
|
|
|
Type of the transaction:
|
|
|
|
A ``CREATE`` transaction creates an asset in BigchainDB. This
|
|
transaction has outputs (conditions) but no inputs (fulfillments),
|
|
so a dummy fulfillment is used.
|
|
|
|
A ``TRANSFER`` transaction transfers ownership of an asset, by providing
|
|
fulfillments to conditions of earlier transactions.
|
|
|
|
A ``GENESIS`` transaction is a special case transaction used as the
|
|
sole member of the first block in a BigchainDB ledger.
|
|
|
|
|
|
|
|
Transaction.asset
|
|
^^^^^^^^^^^^^^^^^
|
|
|
|
**type:** object
|
|
|
|
Description of the asset being transacted.
|
|
|
|
See: `Asset`_.
|
|
|
|
|
|
|
|
Transaction.fulfillments
|
|
^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
**type:** array (object)
|
|
|
|
Array of the fulfillments (inputs) of a transaction.
|
|
|
|
See: Fulfillment_.
|
|
|
|
|
|
|
|
Transaction.conditions
|
|
^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
**type:** array (object)
|
|
|
|
Array of conditions (outputs) provided by this transaction.
|
|
|
|
See: Condition_.
|
|
|
|
|
|
|
|
Transaction.metadata
|
|
^^^^^^^^^^^^^^^^^^^^
|
|
|
|
**type:** object or null
|
|
|
|
User provided transaction metadata. This field may be ``null`` or may
|
|
contain an id and an object with freeform metadata.
|
|
|
|
See: `Metadata`_.
|
|
|
|
|
|
|
|
Transaction.timestamp
|
|
^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
**type:** string
|
|
|
|
User provided timestamp of the transaction.
|
|
|
|
|
|
|
|
|
|
|
|
Condition
|
|
----------
|
|
|
|
An output of a transaction. A condition describes a quantity of an asset
|
|
and what conditions must be met in order for it to be fulfilled. See also:
|
|
fulfillment_.
|
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
Condition.condition
|
|
^^^^^^^^^^^^^^^^^^^
|
|
|
|
**type:** object
|
|
|
|
Body of the condition. Has the properties:
|
|
|
|
- **details**: Details of the condition.
|
|
- **uri**: Condition encoded as an ASCII string.
|
|
|
|
|
|
|
|
Condition.owners_after
|
|
^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
**type:** array (string) or null
|
|
|
|
List of public keys associated with asset ownership at the time
|
|
of the transaction.
|
|
|
|
|
|
|
|
Condition.amount
|
|
^^^^^^^^^^^^^^^^
|
|
|
|
**type:** integer
|
|
|
|
Integral amount of the asset represented by this condition.
|
|
In the case of a non divisible asset, this will always be 1.
|
|
|
|
|
|
|
|
|
|
|
|
Fulfillment
|
|
-----------
|
|
|
|
A fulfillment is an input to a transaction, named as such because it fulfills a condition of a previous transaction. In the case of a ``CREATE`` transaction, a fulfillment may provide no ``input``.
|
|
|
|
Fulfillment.fid
|
|
^^^^^^^^^^^^^^^
|
|
|
|
**type:** integer
|
|
|
|
The offset of the fulfillment within the fulfillents array.
|
|
|
|
|
|
|
|
Fulfillment.owners_before
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
**type:** array (string) or null
|
|
|
|
List of public keys of the previous owners of the asset.
|
|
|
|
|
|
|
|
Fulfillment.fulfillment
|
|
^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
**type:** object or string
|
|
|
|
Fulfillment of a condition_, or put a different way, this is a
|
|
payload that satisfies a condition in order to spend the associated
|
|
asset.
|
|
|
|
|
|
|
|
Fulfillment.input
|
|
^^^^^^^^^^^^^^^^^
|
|
|
|
**type:** object or null
|
|
|
|
Reference to a condition of a previous transaction
|
|
|
|
|
|
|
|
|
|
|
|
Asset
|
|
-----
|
|
|
|
Description of the asset being transacted. In the case of a ``TRANSFER``
|
|
transaction, this field contains only the ID of asset. In the case
|
|
of a ``CREATE`` transaction, this field may contain properties:
|
|
|
|
|
|
Asset.id
|
|
^^^^^^^^
|
|
|
|
**type:** string
|
|
|
|
A `UUID <https://tools.ietf.org/html/rfc4122.html>`_
|
|
of type 4 (random).
|
|
|
|
|
|
|
|
Asset.divisible
|
|
^^^^^^^^^^^^^^^
|
|
|
|
**type:** boolean
|
|
|
|
Whether or not the asset has a quantity that may be partially spent.
|
|
|
|
|
|
|
|
Asset.updatable
|
|
^^^^^^^^^^^^^^^
|
|
|
|
**type:** boolean
|
|
|
|
Whether or not the description of the asset may be updated. Defaults to false.
|
|
|
|
|
|
|
|
Asset.refillable
|
|
^^^^^^^^^^^^^^^^
|
|
|
|
**type:** boolean
|
|
|
|
Whether the amount of the asset can change after its creation. Defaults to false.
|
|
|
|
|
|
|
|
Asset.data
|
|
^^^^^^^^^^
|
|
|
|
**type:** object or null
|
|
|
|
User provided metadata associated with the asset. May also be ``null``.
|
|
|
|
|
|
|
|
|
|
|
|
Metadata
|
|
--------
|
|
|
|
User provided transaction metadata. This field may be ``null`` or may
|
|
contain an id and an object with freeform metadata.
|
|
|
|
|
|
Metadata.id
|
|
^^^^^^^^^^^
|
|
|
|
**type:** string
|
|
|
|
A `UUID <https://tools.ietf.org/html/rfc4122.html>`_
|
|
of type 4 (random).
|
|
|
|
|
|
|
|
Metadata.data
|
|
^^^^^^^^^^^^^
|
|
|
|
**type:** object
|
|
|
|
User provided transaction metadata.
|
|
|
|
|
|
|
|
|