From ebfc03d94db65d7c96e8285dc4b697ada4d669f1 Mon Sep 17 00:00:00 2001 From: Rodolphe Marques Date: Mon, 17 Oct 2016 12:59:49 +0200 Subject: [PATCH 1/2] document digital asset --- docs/source/topic-guides/models.md | 55 +++++++++++++++++++++++++----- 1 file changed, 46 insertions(+), 9 deletions(-) diff --git a/docs/source/topic-guides/models.md b/docs/source/topic-guides/models.md index fabf331d..5e053f78 100644 --- a/docs/source/topic-guides/models.md +++ b/docs/source/topic-guides/models.md @@ -64,9 +64,10 @@ Assets can be mutable (changeable) or immutable. To change a mutable asset, you "conditions": [""], "operation": "", "timestamp": "", - "data": { - "uuid": "", - "payload": "" + "asset": "", + "metadata": { + "id": "", + "data": "" } } } @@ -84,10 +85,11 @@ Here's some explanation of the contents of a transaction: - `conditions`: List of conditions. Each _condition_ is a _crypto-condition_ that needs to be fulfilled by a transfer transaction in order to transfer ownership to new owners. 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`: The Unix time when the transaction was created. It's provided by the client. See the page about [timestamps in BigchainDB](https://docs.bigchaindb.com/en/latest/timestamps.html). - - `data`: - - `uuid`: UUID version 4 (random) converted to a string of hex digits in standard form. - - `payload`: Can be any JSON document. It may be empty in the case of a transfer transaction. + - `timestamp`: The Unix time when the transaction was created. It's provided by the client. See [the section on timestamps](timestamps.html). + - `asset`: Definition of the digital asset. See next section. + - `metadata`: + - `id`: UUID version 4 (random) converted to a string of hex digits in standard form. + - `data`: Can be any JSON document. It may be empty in the case of a transfer transaction. Later, when we get to the models for the block and the vote, we'll see that both include a signature (from the node which created it). You may wonder why transactions don't have signatures... The answer is that they do! They're just hidden inside the `fulfillment` string of each fulfillment. A creation transaction is signed by the node that created it. A transfer transaction is signed by whoever currently controls or owns it. @@ -96,6 +98,39 @@ What gets signed? For each fulfillment in the transaction, the "fullfillment mes One other note: Currently, transactions contain only the public keys of asset-owners (i.e. who own an asset or who owned an asset in the past), inside the conditions and fulfillments. A transaction does _not_ contain the public key of the client (computer) which generated and sent it to a BigchainDB node. In fact, there's no need for a client to _have_ a public/private keypair. In the future, each client may also have a keypair, and it may have to sign each sent transaction (using its private key); see [Issue #347 on GitHub](https://github.com/bigchaindb/bigchaindb/issues/347). In practice, a person might think of their keypair as being both their "ownership-keypair" and their "client-keypair," but there is a difference, just like there's a difference between Joe and Joe's computer. +## The Digital Asset Model +To avoid redundant data in transactions the digital asset model is different for `CREATE` and `TRANSFER` transactions. + +The digital asset properties are defined at creation time in a `CREATE` transaction with the following model: +```json +{ + "id": "", + "divisible": "", + "updatable": "", + "refillable": "", + "data": "" +} +``` + +For `TRANSFER` transactions we only keep the asset id. +```json +{ + "id": "", +} +``` + + +- `id`: UUID version 4 (random) converted to a string of hex digits in standard form. Added server side. +- `divisible`: Whether the asset is divisible or not. Defaults to false. +- `updatable`: Whether the data in the asset can be updated in the future or not. Defaults to false. +- `refillable`: Whether the amount of the asset can change after its creation. Defaults to false. +- `data`: A user supplied JSON document with custom information about the asset. Defaults to null. +- _amount_: The amount of "shares". Only relevant if the asset is marked as divisible. Defaults to 1. The amount is not specified in the asset, but in the conditions (see next section). + +At the time of this writing divisible, updatable, and refillable assets are not yet implemented. +See [Issue #487 on Github](https://github.com/bigchaindb/bigchaindb/issues/487) + + ## Conditions and Fulfillments To create a transaction that transfers an asset to new owners, one must fulfill the asset’s current conditions (crypto-conditions). The most basic kinds of conditions are: @@ -141,7 +176,8 @@ If there is only one _new owner_, the condition will be a simple signature condi }, "uri": "" }, - "owners_after": [""] + "owners_after": [""], + "amount": "" } ``` @@ -149,6 +185,7 @@ If there is only one _new owner_, the condition will be a simple signature condi - `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 asset used as input with `fid`. - `owners_after`: A list containing one item: the public key of the new owner. + - `amount`: The of shares for a divisible asset to send to the new owners. - **Condition body**: - `bitmask`: A set of bits representing the features required by the condition type. - `public_key`: The new owner's public key. @@ -245,7 +282,7 @@ If there is only one _current owner_, the fulfillment will be a simple signature - `id`: The hash of the serialized `block` (i.e. the `timestamp`, `transactions`, `node_pubkey`, and `voters`). This is also a database primary key; that's how we ensure that all blocks are unique. - `block`: - - `timestamp`: The Unix time when the block was created. It's provided by the node that created the block. See the page about [timestamps in BigchainDB](https://docs.bigchaindb.com/en/latest/timestamps.html). + - `timestamp`: The Unix time when the block was created. It's provided by the node that created the block. See [the section on timestamps](timestamps.html). - `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 From 5d71fb436908a935fe85ae73a8b98bad2f5239b9 Mon Sep 17 00:00:00 2001 From: Rodolphe Marques Date: Mon, 17 Oct 2016 13:46:08 +0200 Subject: [PATCH 2/2] fixed typo --- docs/source/topic-guides/models.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/topic-guides/models.md b/docs/source/topic-guides/models.md index 5e053f78..8b66682f 100644 --- a/docs/source/topic-guides/models.md +++ b/docs/source/topic-guides/models.md @@ -185,7 +185,7 @@ If there is only one _new owner_, the condition will be a simple signature condi - `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 asset used as input with `fid`. - `owners_after`: A list containing one item: the public key of the new owner. - - `amount`: The of shares for a divisible asset to send to the new owners. + - `amount`: The amount of shares for a divisible asset to send to the new owners. - **Condition body**: - `bitmask`: A set of bits representing the features required by the condition type. - `public_key`: The new owner's public key.