Mirroristas/bigchaindb
2
0
Fork 0
mirror of https://github.com/bigchaindb/bigchaindb.git synced 2024-10-13 13:34:05 +00:00
Code Issues Packages Projects Releases Wiki Activity

Docs: edited the tx, block and vote models section

Browse Source
This commit is contained in:
troymc
2016-05-24 17:38:35 +02:00
parent 3daa153878
commit 56efe3ff02
1 changed files with 59 additions and 58 deletions
Download Patch File Download Diff File Expand all files Collapse all files

117
docs/source/models.md
View File

@@ -6,47 +6,53 @@ Transactions, blocks and votes are represented using JSON documents with the fol
```json
{
"id": "<sha3 hash>",
"version": "<transaction version number>",
"id": "<SHA3-256 hash hexdigest of transaction (below)>",
"version": "<version number of the transaction model>",
"transaction": {
"fulfillments": ["<list of <fullfillment>"],
"conditions": ["<list of <condition>"],
"fulfillments": ["<list of fullfillments>"],
"conditions": ["<list of conditions>"],
"operation": "<string>",
"timestamp": "<timestamp from client>",
"data": {
"hash": "<SHA3-256 hash hexdigest of payload>",
"payload": "<generic json document>"
"payload": "<any JSON document>"
}
}
}
```
A transaction is an operation between the `current_owner` and the `new_owner` over the digital content described by `hash`. For example if could be a transfer of ownership of the digital content `hash`
Transactions are the basic things stored by BigchainDB. There are two kinds:
- **Transaction header**:
- `id`: sha3 hash of the transaction. The `id` is also the DB primary key.
- `version`: Version of the transaction. For future compability with changes in the transaction model.
- **Transaction body**:
- `fulfillments`: List of fulfillments. Each _fulfillment_ contains a pointer to an unspent digital asset
and a _crypto fulfillment_ that satisfies a spending condition set on the unspent digital asset. A _fulfillment_
is usually a signature proving the ownership of the digital asset.
See [conditions and fulfillments](models.md#conditions-and-fulfillments)
1. A "CREATE" transaction creates a new asset. It has `"operation": "CREATE"`. The `payload` or a "CREATE" transaction describes, encodes, or links to the asset in some way.
2. A "TRANSFER" transaction transfers one or more assets. It has `"operation": "TRANSFER"`. The `payload` of a "TRANSFER" transaction can be empty, but it can also be used for use-case-specific information (e.g. different kinds of transfers).
Here's some explanation of the contents of a transaction:
- `id`: The SHA3-256 hash hexdigest of everything inside the serialized `transaction` body (i.e. `fulfillments`, `conditions`, `operation`, `timestamp` and `data`; see below). 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 [Conditions and Fulfillments](#conditions-and-fulfillments) below.
- `conditions`: List of conditions. Each _condition_ is a _crypto condition_ that needs to be fulfilled by the
new owner in order to spend the digital asset.
See [conditions and fulfillments](models.md#conditions-and-fulfillments)
- `operation`: String representation of the operation being performed (`CREATE`, `TRANSFER`, ...) this will define how
the transactions should be validated
new owner in order to spend the asset.
See [Conditions and Fulfillments](#conditions-and-fulfillments) below.
- `operation`: String representation of the operation being performed (currently either "CREATE" or "TRANSFER"). It determines how
the transaction should be validated.
- `timestamp`: Time of creation of the transaction in UTC. It's provided by the client.
- `data`: JSON object describing the asset (digital content). It contains at least the field `hash` which is a
sha3 hash of the digital content.
- `data`:
- `hash`: The SHA3-256 hash hexdigest of the serialized `payload`.
- `payload`: Can be any JSON document. Its meaning depends on the whether the transaction
is a "CREATE" or "TRANSFER" transaction; see above.
## Conditions and Fulfillments
### Conditions
##### Simple Signature
#### One New Owner
If there is only one _new owner_ the condition will be a single signature condition.
If there is only one _new owner_, the condition will be a single-signature condition.
```json
{
@@ -54,33 +60,32 @@ If there is only one _new owner_ the condition will be a single signature condit
"condition": {
"details": {
"bitmask": "<base16 int>",
"public_key": "<explain>",
"public_key": "<new owner public key>",
"signature": null,
"type": "fulfillment",
"type_id": "<base16 int>"
},
"uri": "<string>"
},
"new_owners": ["<list of <base58 string>>"]
"new_owners": ["<new owner public key>"]
}
```
- **Condition header**:
- `cid`: Condition index so that we can reference this output as an input to another transaction. It also matches
the input `fid`, making this the condition to fulfill in order to spend the digital asset used as input with `fid`
- `new_owners`: List of public keys of the new owners.
the input `fid`, making this the condition to fulfill in order to spend the asset used as input with `fid`.
- `new_owners`: A list containing one item: the public key of the new owner.
- **Condition body**:
- `bitmask`: a set of bits representing the features required by the condition type
- `public_key`: the base58 representation of the _new_owner's_ verifying key.
- `type_id`: the fulfillment type ID (see the [ILP spec](https://interledger.org/five-bells-condition/spec.html))
- `uri`: binary representation of the condition using only URL-safe characters
- `bitmask`: A set of bits representing the features required by the condition type.
- `public_key`: The _new_owner's_ public key.
- `type_id`: The fulfillment type ID; see the [ILP spec](https://interledger.org/five-bells-condition/spec.html).
- `uri`: Binary representation of the condition using only URL-safe characters.
##### Multi Signature
#### Multiple New Owners
If there are multiple _new owners_ by default we create a condition requiring a signature from each new owner in order
to spend the digital asset.
If there are multiple _new owners_, we can create a condition requiring a signature from each new owner in order
to spend the asset. For example:
Example of a condition with two _new owners_:
```json
{
"cid": "<condition index>",
@@ -121,16 +126,17 @@ Example of a condition with two _new owners_:
- `weight`: integer weight for each subfulfillment's contribution to the threshold
- `threshold`: threshold to reach for the subfulfillments to reach a valid fulfillment
The `weight`s and `threshold` could be adjusted. For example, if the `threshold` was changed to 1 above, then only one of the new owners would have to provide a signature to spend the asset.
### Fulfillments
##### Simple Signature
#### One Current Owner
If there is only one _current owner_ the fulfillment will be a single signature fulfillment.
If there is only one _current owner_, the fulfillment will be a single-signature fulfillment.
```json
{
"current_owners": ["<Public Key>"],
"current_owners": ["<public key of current owner>"],
"fid": 0,
"fulfillment": "cf:4:RxFzIE679tFBk8zwEgizhmTuciAylvTUwy6EL6ehddHFJOhK5F4IjwQ1xLu2oQK9iyRCZJdfWAefZVjTt3DeG5j2exqxpGliOPYseNkRAWEakqJ_UrCwgnj92dnFRAEE",
"input": {
@@ -140,11 +146,11 @@ If there is only one _current owner_ the fulfillment will be a single signature
}
```
- `fid`: Fulfillment index. It matches a `cid` in the conditions with a new _crypto condition_ that the new owner(s)
need to fulfill to spend this digital asset
- `current_owners`: Public key of the current owner(s)
- `fid`: Fulfillment index. It matches a `cid` in the conditions with a new _crypto condition_ that the new owner
needs to fulfill to spend this asset.
- `current_owners`: A list of public keys of the current owners; in this case it has just one public key.
- `fulfillment`:
- `input`: Pointer to the digital asset and condition of a previous transaction
- `input`: Pointer to the asset and condition of a previous transaction
- `cid`: Condition index
- `txid`: Transaction id
@@ -152,7 +158,7 @@ need to fulfill to spend this digital asset
```json
{
"id": "<sha3 hash of the serialized block contents>",
"id": "<SHA3-256 hash hexdigest of the serialized block contents>",
"block": {
"timestamp": "<block-creation timestamp>",
"transactions": ["<list of transactions>"],
@@ -164,21 +170,16 @@ need to fulfill to spend this digital asset
}
```
Still to be defined when new blocks are created (after x number of transactions, or after x amount of seconds,
or both).
A block contains a group of transactions and includes the hash of the hash of the previous block to build the chain.
- `id`: sha3 hash of the contents of `block` (i.e. the timestamp, list of transactions, node_pubkey, and voters). This is also a RethinkDB primary key; that's how we ensure that all blocks are unique.
- `block`: The actual block
- `timestamp`: timestamp when the block was created. It's provided by the node that created the block.
- `transactions`: the list of transactions included in the block
- `node_pubkey`: the public key of the node that create the block
- `voters`: list of public keys of the federation nodes. Since the size of the
federation may change over time this will tell us how many nodes existed
in the federation when the block was created so that at a later point in
- `id`: SHA3-256 hash hexdigest of the contents of `block` (i.e. the timestamp, list of transactions, node_pubkey, and voters). This is also a database primary key; that's how we ensure that all blocks are unique.
- `block`:
- `timestamp`: Timestamp when the block was created. It's provided by the node that created the block.
- `transactions`: A list of the transactions included in the block.
- `node_pubkey`: The public key of the node that create the block.
- `voters`: A list of public keys of federation nodes. Since the size of the
federation may change over time, this will tell us how many nodes existed
in the federation when the block was created, so that at a later point in
time we can check that the block received the correct number of votes.
- `signature`: Signature of the block by the node that created the block (i.e. To create it, the node serialized the block contents and signed that with its private key)
- `signature`: Signature of the block by the node that created the block. (To create the signature, the node serializes the block contents and signs that with its private key.)
- `votes`: Initially an empty list. New votes are appended as they come in from the nodes.
## The Vote Model
@@ -187,7 +188,7 @@ Each node must generate a vote for each block, to be appended to that block's `v
```json
{
"node_pubkey": "<the pubkey of the voting node>",
"node_pubkey": "<the public key of the voting node>",
"vote": {
"voting_for_block": "<id of the block the node is voting for>",
"previous_block": "<id of the block previous to this one>",
@@ -199,4 +200,4 @@ Each node must generate a vote for each block, to be appended to that block's `v
}
```
Note: The `invalid_reason` was not being used as of v0.1.3.
Note: The `invalid_reason` was not being used as of v0.1.3 and may be dropped in a future version of BigchainDB.