From 56efe3ff02cbe9f5b85d6f64e5d954de15389bcf Mon Sep 17 00:00:00 2001 From: troymc Date: Tue, 24 May 2016 17:38:35 +0200 Subject: [PATCH] Docs: edited the tx, block and vote models section --- docs/source/models.md | 117 +++++++++++++++++++++--------------------- 1 file changed, 59 insertions(+), 58 deletions(-) diff --git a/docs/source/models.md b/docs/source/models.md index 9f2ec1dd..69854407 100644 --- a/docs/source/models.md +++ b/docs/source/models.md @@ -6,47 +6,53 @@ Transactions, blocks and votes are represented using JSON documents with the fol ```json { - "id": "", - "version": "", + "id": "", + "version": "", "transaction": { - "fulfillments": [""], - "conditions": [""], + "fulfillments": [""], + "conditions": [""], "operation": "", "timestamp": "", "data": { "hash": "", - "payload": "" + "payload": "" } } } ``` -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": "", - "public_key": "", + "public_key": "", "signature": null, "type": "fulfillment", "type_id": "" }, "uri": "" }, - "new_owners": [">"] + "new_owners": [""] } ``` - **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": "", @@ -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": [""], + "current_owners": [""], "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": "", + "id": "", "block": { "timestamp": "", "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": "", + "node_pubkey": "", "vote": { "voting_for_block": "", "previous_block": "", @@ -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.