Merge pull request #17 from hyperledger-labs/f-3-docs

additional documentation

README.md

@@ -15,8 +15,8 @@ token-based distributed application on Hyperledger Fabric.
   - Submit your issues [`here`][`fabric-token-sdk` Issues]. 
   - If you have any questions, queries or comments, find us on [GitHub discussions].
 
-- [`Fabric Smart Client`](https://github.com/hyperledger-labs/fabric-client-sdk): The Token SDK leverages the 
-  [`Fabric Smart Client`](https://github.com/hyperledger-labs/fabric-smart-client) for transaction orchestration, check it out.
+- [`Fabric Smart Client`](https://github.com/hyperledger-labs/fabric-smart-client): The Token SDK leverages the 
+  `Fabric Smart Client` for transaction orchestration, storing tokens and wallets, and more. Check it out. 
 
 # Disclaimer
 
@@ -44,10 +44,6 @@ What would happen if the developers could use a `Fabric Token SDK` that let:
 
 Developing Enterprise Token-based distributed applications would become simpler and more secure.
 
-# Issues
-
-The `Fabric Token SDK` issues are tracked in the GitHub issues tab.
-
 # Use the Fabric Token SDK
 
 ## Install

docs/design.md

@@ -1,11 +1,15 @@
 # The Fabric Token SDK
 
-The scope of the Fabric Token SDK is to deliver a set of API and services that let developers create token-based distributed application on Hyperledger Fabric.
+The scope of the `Fabric Token SDK` is to deliver a set of API and services that let developers create token-based 
+distributed application on Hyperledger Fabric.
 The `Fabric Token SDK` has the following characteristics;
-- It adopts the UTXO model. In the UTXO model, a direct acyclic graph reflects the movements of the assets. Nodes are token transactions. Edges are transaction outputs. Each new token transaction consumes some the UTXOs and create new ones.
+- It adopts the UTXO model. In the UTXO model, a direct acyclic graph reflects the movements of the assets. 
+  Nodes are token transactions. Edges are transaction outputs. Each new token transaction consumes some the 
+  UTXOs and create new ones.
 - Wallets contain a set of `secret keys` and keep track of the list of unspent outputs `owned` those keys.
-- It supports different privacy levels: from a plain instantiation, where everything is in the clear on the ledger, to Zero Knowledge-based instantiations that will obfuscate the ledger while enforcing the required invariants.
-- It allows the developers to write their own services on top of the Token SDK to deliver customised services 
+- It supports different privacy levels: from a `plain` instantiation, where everything is in the clear on the ledger, 
+  to `Zero Knowledge-based` instantiations that will obfuscate the ledger while enforcing the required invariants.
+- It allows the developers to write their own `services` on top of the Token SDK to deliver customised compoenents 
   for their token-based applications.
 
 ## The Token SDK Stack
@@ -16,18 +20,18 @@ This is the Fabric Token SDK stack:
 
 It consists of the following layers:
 - `Services` (light-blue boxes): Services offer pre-packaged token-related functionalities,
-like `Token Transaction` assembling, Token Selectors, and so on.
+like `Token Transaction` assembling, `Token Selectors`, and so on.
 They are built of top of the `Token API` abstraction. Therefore, they are independent of the underlying token technology.
-- `Token API`: This API offers a useful abstraction to deal with tokens in an implementation-independent way. 
-- `Driver API`: This API takes the burden of translating calls of the Token API into API calls that are implementation-specific.
+- `Token API`: This API offers a useful abstraction to deal with tokens in an implementation and blockchain independent way. 
+- `Driver API`: This API takes the burden of translating calls to the Token API into API calls that are implementation-specific.
 - `Driver Implementations`: This is the lowest level of the Token SDK. A driver implementation is responsible for 
   defining the representation of tokens on the ledger, what it means to perform certain token actions,
   and when a token transaction is valid, among other things.
 
-The Fabric Token SDK is built on top of the Fabric Smart Client stack. 
-The Smart Client allows the Token SDK to: 
+The `Fabric Token SDK` is built on top of the `Fabric Smart Client` stack. 
+The `Smart Client` allows the `Token SDK` to: 
 - Orchestrate very complex token-dependent business processes;
-- Store the tokens inside the Vault to easy lookup and manipulation;
+- Store the tokens inside the Vault for easy lookup and manipulation;
 - To listen to events from Fabric related to token transaction, and more.
 
 Le us explore in more details each layer of the Token SDK stack.

docs/driver-api.md

@@ -1,6 +1,9 @@
 # Driver API
 
 The Driver API defines the contracts any implementation should respect to be compatible with the Token API.
-It has a finer granularity than the Token API to accommodate better the difference between the various token technologies.
+It has a finer granularity than the Token API to accommodate better the difference between 
+the various token technologies.
 
-![img_2.png](imgs/driver_api.png)
+Here is a pictorial representation of the dependencies among the various building blocks.
+
+![driver_api.png](imgs/driver_api.png)

docs/drivers.md

@@ -1 +1,8 @@
-# Drivers
+# Drivers
+
+The Token SDK comes equipped with two driver implementations:
+- [`FabToken`](./fabtoken.md): This is a simple implementation of the Driver API that does not support privacy.
+- [`ZKAT DLog`](./zkat-dlog.md): This driver supports privacy via Zero Knowledge. We follow
+  a simplified version of the blueprint described in the paper
+  [`Privacy-preserving auditable token payments in a permissioned blockchain system`]('https://eprint.iacr.org/2019/1058.pdf')
+  by Androulaki et al.

docs/fabtoken.md

@@ -1 +1,3 @@
-# FabToken
+# FabToken
+
+To Be Continued...

docs/token-api.md

@@ -1,7 +1,6 @@
 # Token API
 
-The `Token API` offers a useful abstraction to deal with tokens in an 
-implementation and blockchain independent way.
+The `Token API` offers a useful abstraction to deal with tokens in an implementation and blockchain independent way.
 
 Let us start with defining the tokens that the Token SDK handles.
 A token consists of the following triplet:
@@ -16,9 +15,23 @@ A token consists of the following triplet:
 These tokens are `fungible` with the respect to the same type. In particular,
 tokens with the same denomination can be merged and split, if not otherwise forbidden.
 
-Let us now focus on the building blocks the Token API consists of:
+A token can be spent only by the `rightful owner`. This concept is implementation dependant. For example,
+if the `Owner` field contains a public-key, then a valid signature under public key must be presented to spend the token.
+If the `Owner` field contains a script, then an input that satisfies the script must be presented to spend the token.
 
-![img.png](imgs/token_api.png)
+The Token SDK supports the following basic operations:
+- The `Issue` operation creates new tokens. `Issuers` are in charge of issuing new tokens. Depending on the driver
+  implementation, an issuing policy can be used to identify the authorized issuers for a given type. 
+- The `Transfer` operation transfers the ownership of a given token. A transfer operation must refer to tokens of the same
+type.
+- The `Redeem` operation deletes tokens. Depending on the driver implementation, either the rightful owner or special
+parties, called `redeemers` can invoke this operation.
+
+A `Token Request` aggregates token operations that must be performed atomically.
+
+Let us now focus on the building blocks the `Token API` consists of:
+
+![token_api.png](imgs/token_api.png)
 
 - `Token Management Service`: The Token Management Service (TMS, for short) is the entry point of the Token SDK
   and gives access to the other building blocks.
@@ -60,44 +73,53 @@ Let us now focus on the building blocks the Token API consists of:
   A token request should:
     - Well-formed, and
     - Satisfies the constraints of the payment system. Namely:
-        - Only the rightful owner can transfer a token,
+        - Only the `rightful owner` can transfer a token,
         - No token can be created out of the blue,
         - Audited(able)
         - Etc. (Each implementation can enforce additional requirements, if needed)
 
 The tuple `(network, channel, namespace, public parameters)` uniquely identifies a TMS, where:
-- `network` is the identifier of the Fabric network of reference;
-- `channel` is the channel inside the Fabric network;
-- `namespace` is the namespace inside the channel where the tokens are stored.
+- `network` is the identifier of the network of reference;
+- `channel` is the channel inside the network, if available;
+- `namespace` is the namespace inside the channel that stores the tokens.
 - `public parameters` contain all information needed to operate the specific token infrastructure.
 
 ## Token Request
 
-Let us spend a few more words on the Token Request that is the core of the Token API.
+Let us spend a few more words on the `Token Request` that is the core of the Token API.
 The Token Request is a `container` of token actions (issue, transfer, and redeem) that must be performed atomically.
-Looking ahead, parties interacting to assemble a token transaction are, under the hood, assembling a Token Request that it is
+Looking ahead, parties interacting to assemble a token transaction are, under the hood, assembling a `Token Request` that it is
 later marshalled into the format required by the target Blockchain.
 
 This is the anatomy of a Token Request:
 
-![img_2.png](imgs/token_request.png)
+![token_request.png](imgs/token_request.png)
 
 It consists of three parts:
 - `Anchor`: It is used to bind the Actions to a given Transaction. In Fabric, the anchor is the Transaction ID.
 - `Actions`: It is a collection of `Token Action`:
     - `Issues`, to create new Tokens;
     - `Transfers`, to manipulate Tokens (e.g., transfer ownership or redeem)
 
-  The actions in the collection are independent.
-  In addition, actions comes with a set of `Witnesses` that attest the will of the `Issuers` and/or the `Token Owners`
-  to perform a certain operation.
+  The actions in the collection are independent. An action cannot spend tokens created by another action in the same Token Request.
+  In addition, actions comes with a set of `Witnesses` to verify the `right to spend` or the `right to issue` a given token
 
 - `Metadata`: It is a collection of `Token Metadata`, one entry for each Token Action.
   Parties, assembling a token request, exchange metadata that contain secret information used by
   the parties to check the content of the token actions. This is particularly relevant when using ZK-based drivers.
-  Notice that, no metadata is stored on the ledger.
+  Notice that, the ledger does not store any metadata.
 
 As we mentioned earlier, a Token Request is itself agnostic to the details of the specific Blockchain.
 Indeed, a Token Request must be translated to the Transaction format of the target Blockchain to become meaningful.
 A service called `Token Request Translator` translates the token requests.
-The Token Request Translator does not belong to the Token API. It is offered as a service on top of the Token API.
+The `Token Request Translator` does not belong to the Token API. It is offered as a service on top of the `Token API`
+because it is blockchain dependant. 
+
+Here is a pictorial representation of the translation process. 
+
+![token_request_translator.png](imgs/token_request_translator.png)
+
+In the section dedicated to [`What you need to build Token-Based Applications on top of Fabric`](./services.md), 
+we will learn that a special chaincode called `Token Chaincode` performs
+1. The `validation` of the Token Request, and 
+2. The `translation` to the RWSet.

docs/zkat-dlog.md

@@ -1 +1,3 @@
-# ZKAT DLog
+# ZKAT DLog
+
+To Be Continued...

go.mod

@@ -30,7 +30,7 @@ require (
 	github.com/stretchr/testify v1.7.0
 	github.com/tedsuo/ifrit v0.0.0-20191009134036-9a97d0632f00
 	go.uber.org/atomic v1.7.0
-	golang.org/x/sys v0.0.0-20210615035016-665e8c7367d1 // indirect
+	golang.org/x/sys v0.0.0-20210616094352-59db8d763f22 // indirect
 	golang.org/x/tools v0.1.3 // indirect
 	google.golang.org/grpc v1.36.1 // indirect
 	google.golang.org/protobuf v1.26.0 // indirect

go.sum

@@ -901,10 +901,8 @@ golang.org/x/sys v0.0.0-20210330210617-4fbd30eecc44/go.mod h1:h1NjWce9XRLGQEsW7w
 golang.org/x/sys v0.0.0-20210510120138-977fb7262007/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.0.0-20210608053332-aa57babbf139 h1:C+AwYEtBp/VQwoLntUmQ/yx3MS9vmZaKNdw5eOpoQe8=
 golang.org/x/sys v0.0.0-20210608053332-aa57babbf139/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
-golang.org/x/sys v0.0.0-20210611083646-a4fc73990273 h1:faDu4veV+8pcThn4fewv6TVlNCezafGoC1gM/mxQLbQ=
-golang.org/x/sys v0.0.0-20210611083646-a4fc73990273/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
-golang.org/x/sys v0.0.0-20210615035016-665e8c7367d1 h1:SrN+KX8Art/Sf4HNj6Zcz06G7VEz+7w9tdXTPOZ7+l4=
-golang.org/x/sys v0.0.0-20210615035016-665e8c7367d1/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.0.0-20210616094352-59db8d763f22 h1:RqytpXGR1iVNX7psjB3ff8y7sNFinVFvkx1c8SjBkio=
+golang.org/x/sys v0.0.0-20210616094352-59db8d763f22/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/term v0.0.0-20201117132131-f5c789dd3221/go.mod h1:Nr5EML6q2oocZ2LXRh80K7BxOlk5/8JxuGnuhpl+muw=
 golang.org/x/term v0.0.0-20201126162022-7de9c90e9dd1 h1:v+OssWQX+hTHEmOBgwxdZxK4zHq3yOs8F9J7mk0PY8E=
 golang.org/x/term v0.0.0-20201126162022-7de9c90e9dd1/go.mod h1:bj7SfCRtBDWHUb9snDiAeCFNEtKQo2Wmx5Cou7ajbmo=

integration/README.md

@@ -10,5 +10,5 @@ business processes by invoking the `initiator view` on the specific FSC nodes.
 Here is a list of available examples:
 
 - [`Tha Basics`](./token/tcc/basic/README.md): A showcase of all possibility that the Token SDK offers.
-- [`I Owe You`](./token/dvp/README.md): In this example, we see how to orchestrate a Delivery vs Payment use-case
+- [`DvP`](./token/dvp/README.md): In this example, we see how to orchestrate a Delivery vs Payment use-case
 

integration/token/dvp/README.md

@@ -1,3 +1,14 @@
 # Delivery vs Payment 
 
-To be continued...
+In this section, we will address a more complex scenario.
+Let us start by describing it first.
+There are two parties: a `seller` and a `buyer`.
+- The `seller` owns a house that she wants to sell for an amount of money corresponding
+to the house's valuation.
+- The `buyer` owns some cash in the form of digital tokens and wants to buy the house
+the seller is offering.
+
+This can be seen as a classical `delivery versus payment`, (DVP, for short).
+
+[comment]: <> (The following diagram gives a pictorial representation of the business interactions)
+[comment]: <> (that allow the parties to track the exchange they are performing on a blockchain.)