mirror of
https://github.com/bigchaindb/bigchaindb.git
synced 2024-10-13 13:34:05 +00:00
2f4da6a32f
* Fix typos pointed out in review by @ttmc * Reword description of an input in the transaction schema * Re-add removed comment in transaction model * Fix small typos in some comments in the transaction model * Add trailling commas to a multiline dict in the transaction model tests * Fix small things with server docs changes * Add description of public keys' association with conditions in transaction concept docs * Reword description of Transaction.create's and args * Rename output_uri to output_condition_uri * Fix hardcoded class name vs. self.__class__ * Rename instances of 'out' with 'output' * Rename instances of and with to avoid name clash with built-in * Remove unnecessary renaming of cryptoconditions.Fulfillment import in transaction model * Remove instances of in transaction model * Remove usages of fulfillment in cases where input makes more sense * Reword docstrings for init methods in transaction models * Rename usages of condition where output is now a better fit * Add descriptions to TransactionLink's txid and idx in schema * Minor correction to output idx description in transaction yaml
86 lines
4.0 KiB
Markdown
86 lines
4.0 KiB
Markdown
# Transaction Concepts
|
|
|
|
In BigchainDB, _Transactions_ are used to register, issue, create or transfer
|
|
things (e.g. assets).
|
|
|
|
Transactions are the most basic kind of record stored by BigchainDB. There are
|
|
two kinds: CREATE transactions and TRANSFER transactions.
|
|
|
|
## CREATE Transactions
|
|
|
|
A CREATE transaction can be used to register, issue, create or otherwise
|
|
initiate the history of a single thing (or asset) in BigchainDB. For example,
|
|
one might register an identity or a creative work. The things are often called
|
|
"assets" but they might not be literal assets.
|
|
|
|
BigchainDB supports divisible assets as of BigchainDB Server v0.8.0.
|
|
That means you can create/register an asset with an initial quantity,
|
|
e.g. 700 oak trees. Divisible assets can be split apart or recombined
|
|
by transfer transactions (described more below).
|
|
|
|
A CREATE transaction also establishes, in its outputs, the conditions that must
|
|
be met to transfer the asset(s). The conditions may also be associated with a
|
|
list of public keys that, depending on the condition, may have full or partial
|
|
control over the asset(s). For example, there may be a condition that any
|
|
transfer must be signed (cryptographically) by the private key associated with a
|
|
given public key. More sophisticated conditions are possible. BigchainDB's
|
|
conditions are based on the crypto-conditions of the [Interledger Protocol
|
|
(ILP)](https://interledger.org/).
|
|
|
|
## TRANSFER Transactions
|
|
|
|
A TRANSFER transaction can transfer an asset
|
|
by providing inputs which fulfill the current output conditions on the asset.
|
|
It must also specify new transfer conditions.
|
|
|
|
**Example 1:** Suppose a red car is owned and controlled by Joe.
|
|
Suppose the current transfer condition on the car says
|
|
that any valid transfer must be signed by Joe.
|
|
Joe and a buyer named Rae could build a TRANSFER transaction containing
|
|
an input with Joe's signature (to fulfill the current output condition)
|
|
plus a new output condition saying that any valid transfer
|
|
must be signed by Rae.
|
|
|
|
**Example 2:** Someone might construct a TRANSFER transaction
|
|
that fulfills the output conditions on four
|
|
previously-untransferred assets of the same asset type
|
|
e.g. paperclips. The amounts might be 20, 10, 45 and 25, say,
|
|
for a total of 100 paperclips.
|
|
The TRANSFER transaction would also set up new transfer conditions.
|
|
For example, maybe a set of 60 paperclips can only be transferred
|
|
if Gertrude signs, and a separate set of 40 paperclips can only be
|
|
transferred if both Jack and Kelly sign.
|
|
Note how the sum of the incoming paperclips must equal the sum
|
|
of the outgoing paperclips (100).
|
|
|
|
## Transaction Validity
|
|
|
|
When a node is asked to check if a transaction is valid, it checks several
|
|
things. Some things it checks are:
|
|
|
|
* Are all the fulfillments valid? (Do they correctly satisfy the conditions
|
|
they claim to satisfy?)
|
|
* If it's a creation transaction, is the asset valid?
|
|
* If it's a transfer transaction:
|
|
* Is it trying to fulfill a condition in a nonexistent transaction?
|
|
* Is it trying to fulfill a condition that's not in a valid transaction?
|
|
(It's okay if the condition is in a transaction in an invalid block; those
|
|
transactions are ignored. Transactions in the backlog or undecided blocks
|
|
are not ignored.)
|
|
* Is it trying to fulfill a condition that has already been fulfilled, or
|
|
that some other pending transaction (in the backlog or an undecided block)
|
|
also aims to fulfill?
|
|
* Is the asset ID in the transaction the same as the asset ID in all
|
|
transactions whose conditions are being fulfilled?
|
|
* Is the sum of the amounts in the fulfillments equal
|
|
to the sum of the amounts in the new conditions?
|
|
|
|
If you're curious about the details of transaction validation, the code is in
|
|
the `validate` method of the `Transaction` class, in `bigchaindb/models.py` (at
|
|
the time of writing).
|
|
|
|
Note: The check to see if the transaction ID is equal to the hash of the
|
|
transaction body is actually done whenever the transaction is converted from a
|
|
Python dict to a Transaction object, which must be done before the `validate`
|
|
method can be called (since it's called on a Transaction object).
|