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

Merge branch 'tendermint' into tendermint-docs-k8s-dep

Browse Source
This commit is contained in:
Ahmed Muawia Khan
2018-02-21 11:48:02 +01:00
parent a4ac9cf308 5bfa8e29d8
commit 669b2d586b
79 changed files with 1143 additions and 931 deletions
Download Patch File Download Diff File Expand all files Collapse all files

5
docs/server/source/appendices/cryptography.rst
View File

@@ -1,9 +1,8 @@
Cryptography
============
See `the IPDB Transaction Spec
<https://the-ipdb-transaction-spec.readthedocs.io/en/latest/>`_,
especially the pages about:
See the `IPDB Transaction Spec <https://github.com/ipdb/ipdb-tx-spec>`_,
especially the sections about:
- Cryptographic Hashes
- Cryptographic Keys & Signatures

1
docs/server/source/appendices/index.rst
View File

@@ -18,4 +18,3 @@ Appendices
licenses
run-with-vagrant
run-with-ansible
vote-yaml

5
docs/server/source/appendices/json-serialization.rst
View File

@@ -1,6 +1,5 @@
JSON Serialization
==================
See the page about JSON Serialization & Deserialization
in `the IPDB Transaction Spec
<https://the-ipdb-transaction-spec.readthedocs.io/en/latest/>`_.
See the section about JSON Serialization & Deserialization
in the `IPDB Transaction Spec <https://github.com/ipdb/ipdb-tx-spec>`_.

22
docs/server/source/appendices/vote-yaml.rst
View File

@@ -1,22 +0,0 @@
.. _the-vote-schema-file:
The Vote Schema File
====================
BigchainDB checks all :ref:`votes <the-vote-model>`
(JSON documents) against a formal schema
defined in a JSON Schema file named vote.yaml.
The contents of that file are copied below.
To understand those contents
(i.e. JSON Schema), check out
`"Understanding JSON Schema"
<https://spacetelescope.github.io/understanding-json-schema/index.html>`_
by Michael Droettboom or
`json-schema.org <http://json-schema.org/>`_.
vote.yaml
---------
.. literalinclude:: ../../../../bigchaindb/common/schema/vote.yaml
:language: yaml

3
docs/server/source/data-models/asset-model.rst
View File

@@ -1,5 +1,4 @@
The Asset Model
===============
See `the IPDB Transaction Spec
<https://the-ipdb-transaction-spec.readthedocs.io/en/latest/>`_.
See the `IPDB Transaction Spec <https://github.com/ipdb/ipdb-tx-spec>`_.

3
docs/server/source/data-models/conditions.rst
View File

@@ -1,5 +1,4 @@
Conditions
==========
See `the IPDB Transaction Spec
<https://the-ipdb-transaction-spec.readthedocs.io/en/latest/>`_.
See the `IPDB Transaction Spec <https://github.com/ipdb/ipdb-tx-spec>`_.

1
docs/server/source/data-models/index.rst
View File

@@ -9,4 +9,3 @@ Data Models
inputs-outputs
conditions
block-model
vote-model

3
docs/server/source/data-models/inputs-outputs.rst
View File

@@ -1,5 +1,4 @@
Inputs and Outputs
==================
See `the IPDB Transaction Spec
<https://the-ipdb-transaction-spec.readthedocs.io/en/latest/>`_.
See the `IPDB Transaction Spec <https://github.com/ipdb/ipdb-tx-spec>`_.

20
docs/server/source/data-models/transaction-model.rst
View File

@@ -3,22 +3,4 @@
The Transaction Model
=====================
See `the IPDB Transaction Spec
<https://the-ipdb-transaction-spec.readthedocs.io/en/latest/>`_.
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 Transaction Spec.
Their official source is the ``tx_schema/`` directory
in the `ipdb/ipdb-tx-spec repository on GitHub
<https://github.com/ipdb/ipdb-tx-spec>`_,
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>`_.
See the `IPDB Transaction Spec <https://github.com/ipdb/ipdb-tx-spec>`_.

123
docs/server/source/data-models/vote-model.rst
View File

@@ -1,123 +0,0 @@
.. _the-vote-model:
The Vote Model
==============
A vote is a JSON object with a particular schema,
as outlined in this page.
A vote must contain the following JSON keys
(also called names or fields):
.. code-block:: json
{
"node_pubkey": "<The public key of the voting node>",
"vote": {
"voting_for_block": "<ID of the block the node is voting on>",
"previous_block": "<ID of the block previous to the block being voted on>",
"is_block_valid": "<true OR false>",
"invalid_reason": null,
"timestamp": "<Vote-creation timestamp>"
},
"signature": "<Signature of inner vote object>"
}
.. note::
Votes have no ID (or ``"id"``), as far as users are concerned.
The backend database may use one internally,
but it's of no concern to users and it's never reported to them via APIs.
The JSON Keys in a Vote
-----------------------
**node_pubkey**
The public key of the node which cast this vote.
It's a string.
For more information about public keys,
see the `IPDB Transaction Spec page about cryptographic keys and signatures
<https://the-ipdb-transaction-spec.readthedocs.io/en/latest/common-operations/crypto-keys-and-sigs.html>`_.
**vote.voting_for_block**
The block ID that this vote is for.
It's a string.
For more information about block IDs,
see the page about :ref:`blocks <the-block-model>`.
**vote.previous_block**
The block ID of the block "before" the block that this vote is for,
according to the node which cast this vote.
It's a string.
(It's possible for different nodes to see different block orders.)
For more information about block IDs,
see the page about :ref:`blocks <the-block-model>`.
**vote.is_block_valid**
``true`` if the node which cast this vote considered the block in question to be valid,
and ``false`` otherwise.
Note that it's a *boolean* (i.e. ``true`` or ``false``), not a string.
**vote.invalid_reason**
Always ``null``, that is, it's not being used.
It may be used or dropped in a future version.
See `bigchaindb/bigchaindb issue #217
<https://github.com/bigchaindb/bigchaindb/issues/217>`_ on GitHub.
**vote.timestamp**
The `Unix time <https://en.wikipedia.org/wiki/Unix_time>`_
when the vote was created, according to the node which created it.
It's a string representation of an integer.
**signature**
The cryptographic signature of the inner ``vote``
by the node that created the vote
(i.e. the node with public key ``node_pubkey``).
To compute that:
#. Construct an :term:`associative array` ``d`` containing the contents of the inner ``vote``
(i.e. ``vote.voting_for_block``, ``vote.previous_block``, ``vote.is_block_valid``,
``vote.invalid_reason``, ``vote.timestamp``, and their values).
#. Compute ``signature = sig_of_aa(d, private_key)``, where ``private_key``
is the node's private key (i.e. ``node_pubkey`` and ``private_key`` are a key pair).
There's pseudocode for the ``sig_of_aa()`` function
on `the IPDB Transaction Spec page about cryptographic keys and signatures
<https://the-ipdb-transaction-spec.readthedocs.io/en/latest/common-operations/crypto-keys-and-sigs.html#computing-the-signature-of-an-associative-array>`_.
The Vote Schema
---------------
BigchainDB checks all votes (JSON documents) against a formal schema
defined in a :ref:`JSON Schema file named vote.yaml <the-vote-schema-file>`.
An Example Vote
---------------
.. code-block:: json
{
"node_pubkey": "3ZCsVWPAhPTqHx9wZVxp9Se54pcNeeM5mQvnozDWyDR9",
"vote": {
"voting_for_block": "11c3a3fcc9efa4fc4332a0849fc39b58e403ff37794a7d1fdfb9e7703a94a274",
"previous_block": "3dd1441018b782a50607dc4c7f83a0f0a23eb257f4b6a8d99330dfff41271e0d",
"is_block_valid": true,
"invalid_reason": null,
"timestamp": "1509977988"
},
"signature": "3tW2EBVgxaZTE6nixVd9QEQf1vUxqPmQaNAMdCHc7zHik5KEosdkwScGYt4VhiHDTB6BCxTUzmqu3P7oP93tRWfj"
}

6
docs/server/source/drivers-clients/index.rst
View File

@@ -6,12 +6,6 @@ Libraries and Tools Maintained by the BigchainDB Team
* `Python Driver <https://docs.bigchaindb.com/projects/py-driver/en/latest/index.html>`_
* `JavaScript / Node.js Driver <https://github.com/bigchaindb/js-bigchaindb-driver>`_
* `The Transaction CLI <https://docs.bigchaindb.com/projects/cli/en/latest/>`_ is
a command-line interface for building BigchainDB transactions.
You may be able to call it from inside the language of
your choice, and then use :ref:`the HTTP API <the-http-client-server-api>`
to post transactions.
Community-Driven Libraries and Tools
------------------------------------

8
docs/server/source/events/websocket-event-stream-api.rst
View File

@@ -71,7 +71,7 @@ All messages sent in a stream are in the JSON format.
For simplicity, BigchainDB initially only provides a stream for all
validated transactions. In the future, we may provide streams for other
information, such as new blocks, new votes, or invalid transactions. We may
information. We may
also provide the ability to filter the stream for specific qualities, such
as a specific ``output``'s ``public_key``.
@@ -101,8 +101,4 @@ Example message:
.. note::
Transactions in BigchainDB are validated in batches ("blocks") and will,
therefore, be streamed in batches. Each block can contain up to a 1000
transactions, ordered by the time at which they were included in the block.
The ``/valid_transactions`` stream will send these transactions in the same
order that the block stored them in, but this does **NOT** guarantee that
you will recieve the events in that same order.
therefore, be streamed in batches.

121
docs/server/source/http-client-server-api.rst
View File

@@ -31,7 +31,7 @@ with something like the following in the body:
.. _api-root-endpoint:
API Root Endpoint
-------------------
-----------------
If you send an HTTP GET request to the API Root Endpoint
e.g. ``http://localhost:9984/api/v1/``
@@ -44,7 +44,7 @@ that allows you to discover the BigchainDB API endpoints:
Transactions
-------------------
------------
.. http:get:: /api/v1/transactions/{transaction_id}
@@ -138,10 +138,6 @@ Transactions
.. note::
This option is only available when using BigchainDB with Tendermint.
.. note::
The posted `transaction
<https://docs.bigchaindb.com/projects/server/en/latest/data-models/transaction-model.html>`_
should be structurally valid and not spending an already spent output.
@@ -163,15 +159,12 @@ Transactions
:language: http
.. note::
If the server is returning a ``202`` HTTP status code, then the
transaction has been accepted for processing. To check the status of the
transaction, poll the link to the
:ref:`status monitor <get_status_of_transaction>`
provided in the ``Location`` header or listen to server's
:ref:`WebSocket Event Stream API <the-websocket-event-stream-api>`.
If the server is returning a ``202`` HTTP status code when ``mode=aysnc`` or ``mode=sync``, then the
transaction has been accepted for processing. The client can subscribe to the
:ref:`WebSocket Event Stream API <The WebSocket Event Stream API>` to listen for comitted transactions.
:resheader Content-Type: ``application/json``
:resheader Location: Relative link to a status monitor for the submitted transaction.
:statuscode 202: The pushed transaction was accepted in the ``BACKLOG``, but the processing has not been completed.
:statuscode 400: The transaction was malformed and not accepted in the ``BACKLOG``.
@@ -179,7 +172,8 @@ Transactions
.. http:post:: /api/v1/transactions
This endpoint (without any parameters) will push a new transaction. If BigchainDB is used with Tendermint, the default mode ``async`` is used.
This endpoint (without any parameters) will push a new transaction.
Since no ``mode`` parameter is included, the default mode is assumed: ``async``.
Transaction Outputs
@@ -295,71 +289,6 @@ unspent outputs.
:statuscode 400: The request wasn't understood by the server, e.g. the ``public_key`` querystring was not included in the request.
Statuses
--------------------------------
.. http:get:: /api/v1/statuses
Get the status of an asynchronously written transaction or block by their id.
:query string transaction_id: transaction ID
:query string block_id: block ID
.. note::
Exactly one of the ``transaction_id`` or ``block_id`` query parameters must be
used together with this endpoint (see below for getting `transaction
statuses <#get--statuses?tx_id=tx_id>`_ and `block statuses
<#get--statuses?block_id=block_id>`_).
.. _get_status_of_transaction:
.. http:get:: /api/v1/statuses?transaction_id={transaction_id}
Get the status of a transaction.
The possible status values are ``undecided``, ``valid`` or ``backlog``.
If a transaction in neither of those states is found, a ``404 Not Found``
HTTP status code is returned. `We're currently looking into ways to unambigously let the user know about a transaction's status that was included in an invalid block. <https://github.com/bigchaindb/bigchaindb/issues/1039>`_
**Example request**:
.. literalinclude:: http-samples/get-statuses-tx-request.http
:language: http
**Example response**:
.. literalinclude:: http-samples/get-statuses-tx-valid-response.http
:language: http
:resheader Content-Type: ``application/json``
:statuscode 200: A transaction with that ID was found.
:statuscode 404: A transaction with that ID was not found.
.. http:get:: /api/v1/statuses?block_id={block_id}
Get the status of a block.
The possible status values are ``undecided``, ``valid`` or ``invalid``.
**Example request**:
.. literalinclude:: http-samples/get-statuses-block-request.http
:language: http
**Example response**:
.. literalinclude:: http-samples/get-statuses-block-valid-response.http
:language: http
:resheader Content-Type: ``application/json``
:statuscode 200: A block with that ID was found.
:statuscode 404: A block with that ID was not found.
Assets
--------------------------------
@@ -594,9 +523,6 @@ a certain transaction with ``transaction_id`` occured in (a transaction can occu
either gets rejected or validated by the system). This endpoint gives the ability to drill down on the lifecycle of a
transaction
The `votes endpoint <#votes>`_ contains all the voting information for a specific block. So after retrieving the
``block_id`` for a given ``transaction_id``, one can now simply inspect the votes that happened at a specific time on that block.
Blocks
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -682,37 +608,6 @@ Blocks
:statuscode 400: The request wasn't understood by the server, e.g. just requesting ``/blocks``, without defining ``transaction_id``.
Votes
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. http:get:: /api/v1/votes?block_id={block_id}
Retrieve a list of votes for a certain block with ID ``block_id``.
To check for the validity of a vote, a user of this endpoint needs to
perform the `following steps: <https://github.com/bigchaindb/bigchaindb/blob/8ebd93ed3273e983f5770b1617292aadf9f1462b/bigchaindb/util.py#L119>`_
1. Check if the vote's ``node_pubkey`` is allowed to vote.
2. Verify the vote's signature against the vote's body (``vote.vote``) and ``node_pubkey``.
:query string block_id: The block ID to filter the votes.
**Example request**:
.. literalinclude:: http-samples/get-vote-request.http
:language: http
**Example response**:
.. literalinclude:: http-samples/get-vote-response.http
:language: http
:resheader Content-Type: ``application/json``
:statuscode 200: A list of votes voting for a block with ID ``block_id`` was found and returned.
:statuscode 400: The request wasn't understood by the server, e.g. just requesting ``/votes``, without defining ``block_id``.
.. _determining-the-api-root-url:
Determining the API Root URL

35
docs/server/source/server-reference/configuration.md
View File

@@ -48,7 +48,6 @@ For convenience, here's a list of all the relevant environment variables (docume
`BIGCHAINDB_DATABASE_KEYFILE`<br>
`BIGCHAINDB_DATABASE_KEYFILE_PASSPHRASE`<br>
`BIGCHAINDB_DATABASE_CRLFILE`<br>
`BIGCHAINDB_GRAPHITE_HOST`<br>
The local config file is `$HOME/.bigchaindb` by default (a file which might not even exist), but you can tell BigchainDB to use a different file by using the `-c` command-line option, e.g. `bigchaindb -c path/to/config_file.json start`
or using the `BIGCHAINDB_CONFIG_PATH` environment variable, e.g. `BIGHAINDB_CONFIG_PATH=.my_bigchaindb_config bigchaindb start`.
@@ -217,7 +216,7 @@ export BIGCHAINDB_SERVER_WORKERS=5
## wsserver.scheme, wsserver.host and wsserver.port
These settings are for the
[aiohttp server](https://aiohttp.readthedocs.io/en/stable/index.html),
[aiohttp server](https://aiohttp.readthedocs.io/en/stable/index.html),
which is used to serve the
[WebSocket Event Stream API](../websocket-event-stream-api.html).
`wsserver.scheme` should be either `"ws"` or `"wss"`
@@ -360,8 +359,8 @@ The full paths to the files where logs and error logs should be written to.
}
```
**Defaults to**:
**Defaults to**:
* `"~/bigchaindb.log"`
* `"~/bigchaindb-errors.log"`
@@ -383,7 +382,7 @@ For example if we consider the log file setting:
```
logs would always be written to `bigchain.log`. Each time the file
`bigchain.log` reaches 200 MB it would be closed and renamed
`bigchain.log` reaches 200 MB it would be closed and renamed
`bigchain.log.1`. If `bigchain.log.1` and `bigchain.log.2` already exist they
would be renamed `bigchain.log.2` and `bigchain.log.3`. This pattern would be
applied up to `bigchain.log.5` after which `bigchain.log.5` would be
@@ -550,29 +549,3 @@ The port number at which the logging server should listen.
```
**Defaults to**: `9020`
## graphite.host
The host name or IP address of a server listening for statsd events on UDP
port 8125. This defaults to `localhost`, and if no statsd collector is running,
the events are simply dropped by the operating system.
**Example using environment variables**
```text
export BIGCHAINDB_GRAPHITE_HOST=10.0.0.5
```
**Example config file snippet**
```js
"graphite": {
"host": "10.0.0.5"
}
```
**Default values (from a config file)**
```js
"graphite": {
"host": "localhost"
}
```