docs rework #1264
docs rework #1264
Conversation
Signed-off-by: Angelo De Caro <[email protected]>
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
|
|
||
| A single backend system is shared by all databases, offering a more streamlined approach for deployments with simpler requirements. | ||
| The specific SQL Driver used by the application will ultimately determine the available deployment options. | ||
| For the list of options to configure sql datasources, refer to the [Fabric Smart Client documentation](https://github.com/hyperledger-labs/fabric-smart-client/blob/main/docs/core-fabric.md). |
There was a problem hiding this comment.
🚫 [linkspector] reported by reviewdog 🐶
Cannot reach https://github.com/hyperledger-labs/fabric-smart-client/blob/main/docs/core-fabric.md Status: 404
|
|
||
| The `Zero Knowledge Asset Transfer DLog` (zkat-dlog, for short) driver supports privacy using Zero Knowledge Proofs. | ||
| We follow a simplified version of the blueprint described in the paper <!-- markdown-link-check-disable --> | ||
| [`Privacy-preserving auditable token payments in a permissioned blockchain system`]('https://eprint.iacr.org/2019/1058.pdf')<!-- markdown-link-check-disable --> |
There was a problem hiding this comment.
🚫 [linkspector] reported by reviewdog 🐶
Cannot reach 'https://eprint.iacr.org/2019/1058.pdf' Status: 404 Cannot find: 'https://eprint.iacr.org/2019/1058.pdf'
| It does not guarantee: | ||
| - Anonymity of the issuers and auditors; | ||
| - Token Graph | ||
| Claims and security properties can be found in this paper [`Privacy-preserving auditable token payments in a permissioned blockchain system`]('https://eprint.iacr.org/2019/1058.pdf') |
There was a problem hiding this comment.
🚫 [linkspector] reported by reviewdog 🐶
Cannot reach 'https://eprint.iacr.org/2019/1058.pdf' Status: 404 Cannot find: 'https://eprint.iacr.org/2019/1058.pdf'
Signed-off-by: Angelo De Caro <[email protected]>
| - [`Education Sessions`](./docs/education/README.md): Detailed education sessions with code walkthroughs of the Fabric Token SDK. | ||
| - [`Documentation`](docs/tokensdk.md): The design principles of the Fabric Token SDK. | ||
| - [`Development`](docs/development/development.md): All about the development guidelines. | ||
| - [`Education Sessions`](./docs/education/README.md): Detailed education sessions with code walkthrough of the Fabric Token SDK. |
There was a problem hiding this comment.
| - [`Education Sessions`](./docs/education/README.md): Detailed education sessions with code walkthrough of the Fabric Token SDK. | |
| - [`Education Sessions`](./docs/education/README.md): Detailed education sessions with code walkthroughs of the Fabric Token SDK. |
Matching sessions and walkthroughs to plural
| - [`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. | ||
| - | ||
|
|
There was a problem hiding this comment.
Unneeded cahnge.
| - Found a bug? Need help to fix an issue? You have a great idea for a new feature? Talk to us! You can reach us on | ||
| [Discord](https://discord.gg/hyperledger) in #fabric-token-sdk. | ||
|
|
||
| - [`Fabric Smart Client`](https://github.com/hyperledger-labs/fabric-smart-client): The Token SDK leverages the |
There was a problem hiding this comment.
Consistency:
| - [`Fabric Smart Client`](https://github.com/hyperledger-labs/fabric-smart-client): The Token SDK leverages the | |
| - [`Fabric Smart Client`](https://github.com/hyperledger-labs/fabric-smart-client): The Token-SDK leverages the |
In some pages Token-SDK is used and in other Token SDK
| - All the tokens that need to be spent must carry the same type. | ||
| - For each tuple for which a token must be created, it generates a Pedersen commitment containing the expected value and type. | ||
| - Then, it generates the ZK proof to prove that the commitments are valid Pedersen commitments under the given public params. | ||
| Input and output tokens must have the same type and the sum of values in input must be equal to the same of the values in outputs. |
There was a problem hiding this comment.
| Input and output tokens must have the same type and the sum of values in input must be equal to the same of the values in outputs. | |
| Input and output tokens must have the same type and the sum of values in input must be equal to the sum of the values in outputs. |
| At this stage, no signature is generated to prove the will of the owners to spend the inputs. | ||
| Notice also that all the above crypto operations happen over the elliptic curve defined in the public parameters. | ||
|
|
||
| This happens later. The `ttx service` assists the developer to do so. |
There was a problem hiding this comment.
ttx service or TTX service? (code vs text format)
| #### Tokens and their Metadata | ||
|
|
||
| A token is presented on the ledger as a pair `(pedersen commitment to type and value, owner)`. | ||
| The pedersen commitment is computed as $g_0^{H_{Z_r}(Type)}g_1^{Value} g_2^{BF}$, |
There was a problem hiding this comment.
| The pedersen commitment is computed as $g_0^{H_{Z_r}(Type)}g_1^{Value} g_2^{BF}$, | |
| The Pedersen commitment is computed as $g_0^{H_{Z_r}(Type)} g_1^{Value} g_2^{BF}$, |
| ${g_i}$ are the bases of the pedersen commitment, | ||
| $Type$ is a string, and both $Value$ and $BF$ are in $Z_r$. | ||
|
|
||
| The token metadata is then a tuple containing: Token type, value, blinding factor, and issuer's identity. |
There was a problem hiding this comment.
| The token metadata is then a tuple containing: Token type, value, blinding factor, and issuer's identity. | |
| The token metadata is a tuple containing: Token type, value, blinding factor, and issuer's identity. |
| - The identity of the issuer; | ||
| - The output tokens to be created; | ||
| - A zero-knowledge proof of validity of the action; | ||
| - Additional public metadata. |
There was a problem hiding this comment.
This is slightly ambigious can we be more specific?
| The actions includes the following: | ||
| - The input tokens to be spent; | ||
| - The output tokens to be created; | ||
| - A zero-knowledge proof of validity of the action; |
There was a problem hiding this comment.
| - A zero-knowledge proof of validity of the action; | |
| - A zero-knowledge proof of the validity of the action; |
|
|
||
| ### `FabToken` | ||
|
|
||
| Fabtoken is a straightforward implementation of the Driver API. |
There was a problem hiding this comment.
Consistency: Fabtoken or FabToken, this comment is relevant for all pages.
| - The input tokens to be spent; | ||
| - The output tokens to be created; | ||
| - A zero-knowledge proof of validity of the action; | ||
| - Additional public metadata. |
There was a problem hiding this comment.
Same ambigiouty here. Can we be more specific?
| The validator guarantees that: | ||
| - Only the issuers listed in the public parameters can issue tokens; | ||
| - Only the auditors listed in the public parameters can audit transactions; | ||
| - Only legitimate owners can spend their tokens |
There was a problem hiding this comment.
| - Only legitimate owners can spend their tokens | |
| - Only legitimate owners can spend their tokens; |
| The validator guarantees that: | ||
| - Only the issuers listed in the public parameters can issue tokens; | ||
| - Only the auditors listed in the public parameters can audit transactions; | ||
| - Only legitimate owners can spend their tokens |
There was a problem hiding this comment.
| - Only legitimate owners can spend their tokens | |
| - Only legitimate owners can spend their tokens; |
| - In a transfer, the sum of the inputs being spent is equal to the sum of the outputs being created. | ||
| It does not guarantee: | ||
| - Anonymity of the issuers and auditors; | ||
| - Token Graph |
There was a problem hiding this comment.
| - Token Graph | |
| - Token Graph; |
Same comment for the rest of the document.
| - In a transfer, the sum of the inputs being spent is equal to the sum of the outputs being created. | ||
| It does not guarantee: | ||
| - Anonymity of the issuers and auditors; | ||
| - Token Graph |
There was a problem hiding this comment.
Also, does "Token Graph" refers to “token-flow graph”? “UTXO graph”? (ambigiouty?)
| When loading Idemix credentials, only the public part of the credential is store in the `IdentityConfigurations` table. | ||
| The secret key is stored in the key store and the secret key component of the credential is replaced with the secret key's SKI. | ||
|
|
||
| Idemix identities are only used for the `owner` wallets. X509 identities are used for issuers and auditors. |
There was a problem hiding this comment.
| Idemix identities are only used for the `owner` wallets. X509 identities are used for issuers and auditors. | |
| Idemix identities are only used for the owner wallets. X509 identities are used for issuers and auditors. |
Consistency with the next line.
| Idemix identities are only used for the `owner` wallets. X509 identities are used for issuers and auditors. | ||
| When an identity is derived from an owner wallet via a call to `GetRecipientIdentity`, | ||
| then both the `IdentityInfo` and the `IdentitySigners` tables are filled with a row. | ||
| The field `identity_audit_info` contains private information about the identity. |
There was a problem hiding this comment.
Can we add private information? e.g., (such as ...)
| * **Owners:** Owners hold tokens, just like possessing a digital asset. | ||
| * **Auditors:** These act as financial inspectors, overseeing token requests and ensuring proper use. | ||
| * **Certifiers:** They verify the existence and legitimacy of specific tokens, similar to checking identification. | ||
| This role is used only by certain token drivers that support the so called `graph hiding`. |
There was a problem hiding this comment.
| This role is used only by certain token drivers that support the so called `graph hiding`. | |
| This role is used only by certain token drivers that support the so called "graph hiding". |
I assume graph hiding is a term and not a variable name.
| A wallet is like a digital vault that stores a long-term identity (the main key) and any credentials derived from it, if supported. | ||
| Different wallet types provide different functionalities. | ||
| For example, an issuer wallet lets you see a list of issued tokens, while an owner wallet shows unspent tokens. | ||
| All these wallets have though a minimum common denominator: |
There was a problem hiding this comment.
| All these wallets have though a minimum common denominator: | |
| All these wallets have, however, share a minimum common denominator: |
| Different wallet types provide different functionalities. | ||
| For example, an issuer wallet lets you see a list of issued tokens, while an owner wallet shows unspent tokens. | ||
| All these wallets have though a minimum common denominator: | ||
| Given a wallet, you, as the developer, can derive identities to be used in different contexts. |
There was a problem hiding this comment.
| Given a wallet, you, as the developer, can derive identities to be used in different contexts. | |
| Given a wallet, identities can be derived for use in different contexts. |
Regarding, till now the document used a formal tone, and now it has a different tutorial like tone ("you, as the developer,")
| The services are pre-built functionalities to simplify the use of the Token API. | ||
| Some of the services are also used to back the `Drivers`, like the `Identity Service`. | ||
|
|
||
| Below is a pictorial representations of the `Services` and their interactions: |
There was a problem hiding this comment.
| Below is a pictorial representations of the `Services` and their interactions: | |
| Below is a pictorial representation of the `Services` and their interactions: |
| It is used to back part of the Token and Driver API. | ||
| - `services/selector`: This is `token selector service`. | ||
| It is used to select tokens in such way the risk of accidental double-spending is minimized. | ||
| Different implementations provides different trades-off. |
There was a problem hiding this comment.
| Different implementations provides different trades-off. | |
| Different implementations provide different trades-off. |
| ## The `services/network` service | ||
|
|
||
| The `network` service is responsible to provide to the other services a uniform and predictable interface to the backend (e.g. Fabric). | ||
| Internal the network service is structured similarly to the Token API. |
There was a problem hiding this comment.
| Internal the network service is structured similarly to the Token API. | |
| Internally, the network service is structured similarly to the Token API. |
|
|
||
|  | ||
|
|
||
| The Fabric-based network relays on the Fabric Smart Client for its configuration and operations like: Query chaincodes, broadcast transactions, and so on. |
There was a problem hiding this comment.
| The Fabric-based network relays on the Fabric Smart Client for its configuration and operations like: Query chaincodes, broadcast transactions, and so on. | |
| The Fabric-based network relies on the Fabric Smart Client for its configuration and operations like: Query chaincodes, broadcast transactions, and so on. |
|
|
||
| At bootstrap time, the Token-SDK goes through the TMS defined in the configuration. | ||
| For each TMS, the network provider is asked to return the network instance identified by the `network` and `channel` value of the TMSID. | ||
| If the network provider fails, then the boostrap of the Token-SDK stack fails. |
There was a problem hiding this comment.
| If the network provider fails, then the boostrap of the Token-SDK stack fails. | |
| If the network provider fails, then the bootstrap of the Token-SDK stack fails. |
|
|
||
| At bootstrap time, the Token-SDK goes through the TMS defined in the configuration. | ||
| For each TMS, the network provider is asked to return the network instance identified by the `network` and `channel` value of the TMSID. | ||
| If the network provider fails, then the boostrap of the Token-SDK stack fails. |
There was a problem hiding this comment.
Should we write what will happen next? Is there a retry mechanism or does the entire SDK initialization abort?
|
|
||
| Then, `RequestRecipientIdentityView` does the following: | ||
| - Read `RecipientData` from the session. | ||
| - Register it in the `WalletManager` that checks that the information contained in `RecipientData` are correct and compatible with the public parameters. |
There was a problem hiding this comment.
What happens if it fails? Is the transaction aborted or retried?
|
|
||
| The `AuditApproveView` is invoked inside a responding view for a given auditing business process. | ||
| The auditor is supposed to invoke `ReceiveTransactionView` first to receive the transaction to audit. | ||
| The auditor will perform all the required business checks and if no error occurs during the check, |
There was a problem hiding this comment.
Can we provide a reference to these checks?
| - Check the status of the Request with given transaction id in the Transactions DB. | ||
| If the status is either `Valid` or `Invalid` then the view returns immediately without and with an error respectively. | ||
| - Otherwise, the status is `Pending` and the view adds a listener to the Transactions DB to get notified when the request's status changes. | ||
| - If a timeout occurs, an error is returned. |
There was a problem hiding this comment.
Is the timeout configurable? Can we add a link?
| It is used to back part of the Token and Driver API. | ||
| - `services/selector`: This is `token selector service`. | ||
| It is used to select tokens in such way the risk of accidental double-spending is minimized. | ||
| Different implementations provides different trades-off. |
There was a problem hiding this comment.
What type of trades-off exist. Can we provide an example?
| @@ -0,0 +1,388 @@ | |||
| # Services | |||
There was a problem hiding this comment.
- Previously
services/identity.mdhas a sectionHashiCorp Vault Secrets Engine Supportwhich I cannot locate now. Was it deleted on purpose? or moved to another file?
| @@ -0,0 +1,388 @@ | |||
| # Services | |||
|
|
|||
There was a problem hiding this comment.
Previously services/selector.md and selector/sherdlock.md explained locking, replication issues, and algorithms. But the new doc only briefly mentions selector service; no mention of Sherdlock or concurrency strategies. Where is this documentation went?
Same question for services/interop.md and deployment/deployment.md (node bootstrap, HSM support). I suggest to explicitly list in the description of the PR the expected modifications Remove/Add/Move.
| #### Tokens and their Metadata | ||
|
|
||
| A token is presented on the ledger as a pair `(pedersen commitment to type and value, owner)`. | ||
| The pedersen commitment is computed as $g_0^{H_{Z_r}(Type)}g_1^{Value} g_2^{BF}$, |
There was a problem hiding this comment.
Maybe this is a "too" cryptographic detail for this document and we should have a different file that explains cryptographic primitives?
|
|
||
| ## Command Line Interface (CLI) | ||
|
|
||
| FTS comes equipped with `tokengen`. It is a utility for generating Fabric Token-SDK material. |
There was a problem hiding this comment.
In the document "FTS" and "Fabric Token-SDK" used interchangably. Please use the FTS definition above for the rest of the doc.
|
|
||
| Token-based applications that require: | ||
| - Privacy; | ||
| - Bankend agnostic; |
There was a problem hiding this comment.
| - Bankend agnostic; | |
| * Backend agnostic; |
|
|
||
| ## Developer Experience | ||
|
|
||
| The developers will face both the Token API and the services to build their own token-based applications. |
There was a problem hiding this comment.
| The developers will face both the Token API and the services to build their own token-based applications. | |
| Developers will work with both the Token API and the services to build their own token-based applications. |
|
|
||
| ## Introduction | ||
|
|
||
| The Fabric Token-SDK (FTS, for short) is set of APIs and services for building token-based applications on Hyperledger Fabric, and potentially other platforms. |
There was a problem hiding this comment.
| The Fabric Token-SDK (FTS, for short) is set of APIs and services for building token-based applications on Hyperledger Fabric, and potentially other platforms. | |
| The Fabric Token-SDK (FTS, for short) is a set of APIs and services for building token-based applications on Hyperledger Fabric, and potentially other platforms. |
|
|
||
| The Fabric Token-SDK (FTS, for short) is set of APIs and services for building token-based applications on Hyperledger Fabric, and potentially other platforms. | ||
|
|
||
| The key Features are: |
There was a problem hiding this comment.
| The key Features are: | |
| The key features are: |
| ## Requirements and Use Cases | ||
|
|
||
| Token-based applications that require: | ||
| - Privacy; |
There was a problem hiding this comment.
| - Privacy; | |
| * Privacy; |
For consistency with the rest of the doc.
| - [`Fabric Smart Client (FSC, for short)`](https://github.com/hyperledger-labs/fabric-smart-client): For complex workflows orchestration, secure storage, and event listening. | ||
| - [`Idemix`](https://github.com/IBM/idemix): For the anonymous credentials. | ||
| - [`Mathlib`](https://github.com/IBM/mathlib): For the elliptic curve math operations. | ||
|
|
||
| The system administrator is responsible for preparing: | ||
|
|
||
| - `Configuration`: FTS needs to be configured accordingly to the specific use-case. | ||
| FTS uses the FSC's `config service` to access its configuration. | ||
| An example of such a configuration can be found [`here`](./core-token.md). | ||
| - `Data storage`: FTS requires an SQL data source to store relevant information for its functioning. | ||
| - `HSM`: When relevant to store secret keys. | ||
| - `External Key Store`: When relevant to store secret keys | ||
|
|
||
| In some configurations, FTS might run in a container that is volume-less. | ||
|
|
||
| Other pre-requisites come from the Fabric Smart Client directly. | ||
|
|
||
| ## Terminology and Glossary | ||
|
|
||
| - For an introduction into the concepts of `Database`, `Persistence`, `Driver`, `Store`, read [this documentation](https://github.com/hyperledger-labs/fabric-smart-client/blob/main/docs/platform/view/db-driver.md). | ||
| - FTS stands for Fabric Token SDK | ||
| - FSC stands for Fabric Smart Client |
There was a problem hiding this comment.
| - [`Fabric Smart Client (FSC, for short)`](https://github.com/hyperledger-labs/fabric-smart-client): For complex workflows orchestration, secure storage, and event listening. | |
| - [`Idemix`](https://github.com/IBM/idemix): For the anonymous credentials. | |
| - [`Mathlib`](https://github.com/IBM/mathlib): For the elliptic curve math operations. | |
| The system administrator is responsible for preparing: | |
| - `Configuration`: FTS needs to be configured accordingly to the specific use-case. | |
| FTS uses the FSC's `config service` to access its configuration. | |
| An example of such a configuration can be found [`here`](./core-token.md). | |
| - `Data storage`: FTS requires an SQL data source to store relevant information for its functioning. | |
| - `HSM`: When relevant to store secret keys. | |
| - `External Key Store`: When relevant to store secret keys | |
| In some configurations, FTS might run in a container that is volume-less. | |
| Other pre-requisites come from the Fabric Smart Client directly. | |
| ## Terminology and Glossary | |
| - For an introduction into the concepts of `Database`, `Persistence`, `Driver`, `Store`, read [this documentation](https://github.com/hyperledger-labs/fabric-smart-client/blob/main/docs/platform/view/db-driver.md). | |
| - FTS stands for Fabric Token SDK | |
| - FSC stands for Fabric Smart Client | |
| * [`Fabric Smart Client (FSC, for short)`](https://github.com/hyperledger-labs/fabric-smart-client): For complex workflows orchestration, secure storage, and event listening. | |
| * [`Idemix`](https://github.com/IBM/idemix): For the anonymous credentials. | |
| * [`Mathlib`](https://github.com/IBM/mathlib): For the elliptic curve math operations. | |
| The system administrator is responsible for preparing: | |
| * `Configuration`: FTS needs to be configured accordingly to the specific use-case. | |
| FTS uses the FSC's `config service` to access its configuration. | |
| An example of such a configuration can be found [`here`](./core-token.md). | |
| * `Data storage`: FTS requires an SQL data source to store relevant information for its functioning. | |
| * `HSM`: When relevant to store secret keys. | |
| * `External Key Store`: When relevant to store secret keys | |
| In some configurations, FTS might run in a container that is volume-less. | |
| Other pre-requisites come from the Fabric Smart Client directly. | |
| ## Terminology and Glossary | |
| * For an introduction into the concepts of `Database`, `Persistence`, `Driver`, `Store`, read [this documentation](https://github.com/hyperledger-labs/fabric-smart-client/blob/main/docs/platform/view/db-driver.md). | |
| * FTS stands for Fabric Token SDK | |
| * FSC stands for Fabric Smart Client |
|
|
||
| Every Token Management Service (TMS) is linked to a set of public parameters. | ||
| This information, managed by the `Public Parameters Manager` (`token.PublicParametersManager`), holds the key to operating the token infrastructure effectively. | ||
| The public parameters are holds by the Public Parameters Manager. |
There was a problem hiding this comment.
| The public parameters are holds by the Public Parameters Manager. | |
| The public parameters are held by the Public Parameters Manager. |
| A TMS can be created only upon presenting concrete public parameters. | ||
| When the `Token Management Service Provider` is requested to create a new TMS, the TMSP inspects the public parameters. | ||
| Depending on the `Driver Name` and `Driver Version`, a matching implementation of the `Driver API` is selected, if available. | ||
| Available `Driver API` implementations must be burned inside the Go executable. |
There was a problem hiding this comment.
"burned" or "compiled"
| Wallets play a crucial role in signing and verifying operations. | ||
| Whenever a signature is needed, the system looks to the appropriate wallet within the Wallet Manager to locate the necessary keys. | ||
| This manager keeps track of wallets for different roles like Issuers, Owners, and Auditors. | ||
| Notably, Certifiers aren't supported because this driver doesn't handle a specific privacy feature called Graph Hiding. |
There was a problem hiding this comment.
| Notably, Certifiers aren't supported because this driver doesn't handle a specific privacy feature called Graph Hiding. | |
| Notably, Certifiers are only relevant for drivers supporting graph hiding, which this driver does not. |
|
|
||
| ## Manage all your tokens with ease using Token Vault | ||
| The implementation of Driver API's `Validator` contains the specific checks performed by that driver. | ||
| Further details are postponed to the sections about the Driver API. |
There was a problem hiding this comment.
| Further details are postponed to the sections about the Driver API. | |
| Further details are provided in Driver API documentation. |
and provide a reference?
| ``` | ||
|
|
||
| This vault instance is the same one provided by the dedicated [`Vault Service`](../services/vault.md). | ||
| The `Token Vault` is built on top of the `Transactions DB` `Audit Transactions DB` and `Tokens DB`. |
There was a problem hiding this comment.
Consider expand the explanation, something like.
| The `Token Vault` is built on top of the `Transactions DB` `Audit Transactions DB` and `Tokens DB`. | |
| The `Token Vault` is built on top of the `Transactions DB` `Audit Transactions DB` and `Tokens DB`. The vault uses these databases to provide query APIs for unspent tokens and transaction history. |
|
|
||
| The `token.SignatureService` acts as your gateway to secure transactions. | ||
| The `token.SignatureService` acts as your gateway to secure transactions. | ||
| It provides access to both signature verifiers and signers, all seamlessly linked to identities retrieved from the Wallet Manager. |
There was a problem hiding this comment.
Should there be more information here about how signers/verifiers are linked to wallets.
|
|
||
| Imagine a `Token Request` as a blueprint for a secure financial transaction. | ||
| It groups together different actions like issuing new tokens, transferring ownership, or redeeming existing ones. | ||
| Imagine a `Token Request` as a blueprint for a secure financial transaction. |
There was a problem hiding this comment.
Is this docuemnt a formal doc or a tutorial? I tend to see it as a formal document and thus, the verb "imagine" is not part of the format.
| * **Token Data Hiding:** When enabled (true), the content of the tokens is obscured. | ||
| * **Graph Hiding:** With this set to true, tokens become untraceable within the system. | ||
| * **Auditors:** This list identifies authorized auditors for the token system. | ||
| * **Issuer:** This list identifies authorized issuers for the token system. |
There was a problem hiding this comment.
| * **Issuer:** This list identifies authorized issuers for the token system. | |
| * **Issuers:** This list identifies authorized issuers for the token system. |
| Wallets play a crucial role in signing and verifying operations. | ||
| Whenever a signature is needed, the system looks to the appropriate wallet within the Wallet Manager to locate the necessary keys. | ||
| This manager keeps track of wallets for different roles like Issuers, Owners, and Auditors. | ||
| Notably, Certifiers aren't supported because this driver doesn't handle a specific privacy feature called Graph Hiding. |
There was a problem hiding this comment.
I think that there should be a reference to a point where the term Graph-hiding is explained.
| * **Issue:** Creates brand new tokens. | ||
| * **Transfer:** Manages existing tokens, allowing ownership changes or redemption. | ||
|
|
||
| These actions within the request are independent. One action cannot utilize tokens created by another action within the same request. Additionally, each action comes with witnesses, which are essentially verifications. These witnesses confirm the "right to spend" or "right to issue" a particular token. In simpler scenarios, witnesses might be signatures from token owners or issuers. |
There was a problem hiding this comment.
One action cannot utilize tokens created by another action within the same request.
We may want to exaplain why.
| "github.com/hyperledger-labs/fabric-smart-client/pkg/utils/errors" | ||
| "github.com/hyperledger-labs/fabric-smart-client/platform/view/services/endpoint" | ||
| "github.com/hyperledger-labs/fabric-smart-client/platform/view/services/id" | ||
| "github.com/hyperledger-labs/fabric-token-sdk/docs/core/extension/zkatdlog/nogh/v2/setup" |
There was a problem hiding this comment.
Is this modification related to this PR? I thought that it only deals with documentation.
| * Uses the `Unspent Transaction Output` (UTXO) model for tracking token movements. | ||
| * Manages cryptographic keys through `Wallets`, keeping track of owned unspent outputs. | ||
| * Supports `various privacy levels`, from fully transparent to Zero-Knowledge Proofs for obfuscating transaction details. | ||
| * Allows developers to create `custom services` on top of the core API for specific application needs. |
There was a problem hiding this comment.
| * Uses the `Unspent Transaction Output` (UTXO) model for tracking token movements. | |
| * Manages cryptographic keys through `Wallets`, keeping track of owned unspent outputs. | |
| * Supports `various privacy levels`, from fully transparent to Zero-Knowledge Proofs for obfuscating transaction details. | |
| * Allows developers to create `custom services` on top of the core API for specific application needs. | |
| * Uses the *Unspent Transaction Output* (UTXO) model for tracking token movements. | |
| * Manages cryptographic keys through *Wallets*, keeping track of owned unspent outputs. | |
| * Supports *various privacy levels*, from fully transparent to Zero-Knowledge Proofs for obfuscating transaction details. | |
| * Allows developers to create *custom services* on top of the core API for specific application needs. |
- Usuall backticks are ussed for variables which I don't think is the case here. It makes the reading harder because of the smaller fonts, especially in dark mode.
- Wallets or wallets for consistency with the rest of the text.
| The key Features are: | ||
| * Uses the `Unspent Transaction Output` (UTXO) model for tracking token movements. | ||
| * Manages cryptographic keys through `Wallets`, keeping track of owned unspent outputs. | ||
| * Supports `various privacy levels`, from fully transparent to Zero-Knowledge Proofs for obfuscating transaction details. |
There was a problem hiding this comment.
I find the sentence logic to be confusing because it mixes privacy levels (which are conceptual) with Zero-Knowledge Proofs (ZKP), which is a technique. Consider
| * Supports `various privacy levels`, from fully transparent to Zero-Knowledge Proofs for obfuscating transaction details. | |
| * Supports *various privacy levels* for transactions, from fully transparent to obfuscated through the use of Zero-Knowledge Proofs. |
| * Uses the `Unspent Transaction Output` (UTXO) model for tracking token movements. | ||
| * Manages cryptographic keys through `Wallets`, keeping track of owned unspent outputs. | ||
| * Supports `various privacy levels`, from fully transparent to Zero-Knowledge Proofs for obfuscating transaction details. | ||
| * Allows developers to create `custom services` on top of the core API for specific application needs. |
There was a problem hiding this comment.
custom services and core API should be links to the relevant documentation.
|
|
||
| The Fabric Token SDK stack consists of several layers: | ||
| * Services: Pre-built functionalities like assembling transactions and selecting unspent tokens. | ||
| * Token API: Provides a common abstraction for interacting with tokens across different backends. |
There was a problem hiding this comment.
At this point of the reading it is unclear what a backend is. Is it a driver? a network?
It might be good to move the stack.png image near this text for better clarity.
|
|
||
| The SDK leverages the Fabric Smart Client stack for complex workflows, secure storage, and event listening. | ||
|
|
||
| The Fabric Token SDK has evolved beyond its initial focus on Hyperledger Fabric. |
There was a problem hiding this comment.
The sentence is unclear because it suggests the SDK expanded beyond Hyperledger Fabric but then mentions Fabric again, which is redundant. Consider rephrasing to clarify that the SDK now supports multiple platforms while still supporting Fabric. For example:
Originally designed for Hyperledger Fabric, the SDK now supports other permissioned blockchains while continuing to work with Fabric.
|
|
||
| ## Requirements and Use Cases | ||
|
|
||
| Token-based applications that require: |
There was a problem hiding this comment.
Does all token-based applications require privacy? Above it was listed that there can be transparent transactions.
| The developers must decide how to configure the Token-SDK to achieve the intended goals. | ||
| Moreover, they are also responsible for defining the initial content of the datasource used by the Token-SDK. | ||
|
|
||
| ## Requirements and Use Cases |
There was a problem hiding this comment.
I don't see any use cases listed below.
| - [`Idemix`](https://github.com/IBM/idemix): For the anonymous credentials. | ||
| - [`Mathlib`](https://github.com/IBM/mathlib): For the elliptic curve math operations. | ||
|
|
||
| The system administrator is responsible for preparing: |
There was a problem hiding this comment.
Till that point, there was nowhere mentioning of the system administrator, nor how the FTS is integrated in a full solution. Maybe the introduction should start with this information?
| - `Configuration`: FTS needs to be configured accordingly to the specific use-case. | ||
| FTS uses the FSC's `config service` to access its configuration. | ||
| An example of such a configuration can be found [`here`](./core-token.md). | ||
| - `Data storage`: FTS requires an SQL data source to store relevant information for its functioning. | ||
| - `HSM`: When relevant to store secret keys. | ||
| - `External Key Store`: When relevant to store secret keys |
There was a problem hiding this comment.
| - `Configuration`: FTS needs to be configured accordingly to the specific use-case. | |
| FTS uses the FSC's `config service` to access its configuration. | |
| An example of such a configuration can be found [`here`](./core-token.md). | |
| - `Data storage`: FTS requires an SQL data source to store relevant information for its functioning. | |
| - `HSM`: When relevant to store secret keys. | |
| - `External Key Store`: When relevant to store secret keys | |
| * **Configuration**: FTS needs to be configured accordingly to the specific use-case. | |
| FTS uses the FSC's `config service` to access its configuration. | |
| An example of such a configuration can be found [`here`](./core-token.md). | |
| * **Data storage**: FTS requires an SQL data source to store relevant information for its functioning. | |
| * **HSM**: When relevant to store secret keys. | |
| * **External Key Store**: When relevant to store secret keys |
|
|
||
| The system administrator is responsible for preparing: | ||
|
|
||
| - `Configuration`: FTS needs to be configured accordingly to the specific use-case. |
There was a problem hiding this comment.
FTS needs to be configured accordingly to the specific use-case.
Without examples, this sentence means nothing...
| - `Configuration`: FTS needs to be configured accordingly to the specific use-case. | ||
| FTS uses the FSC's `config service` to access its configuration. | ||
| An example of such a configuration can be found [`here`](./core-token.md). | ||
| - `Data storage`: FTS requires an SQL data source to store relevant information for its functioning. |
There was a problem hiding this comment.
How should the administrator provide access to the SQL source? Should this line include a reference to some relevant documentation?
| FTS uses the FSC's `config service` to access its configuration. | ||
| An example of such a configuration can be found [`here`](./core-token.md). | ||
| - `Data storage`: FTS requires an SQL data source to store relevant information for its functioning. | ||
| - `HSM`: When relevant to store secret keys. |
There was a problem hiding this comment.
The documentation should list when and whcih secret keys are used and alert the users so that they can be prepared in advanced. A reference for such a documentaiton is missing here.
| An example of such a configuration can be found [`here`](./core-token.md). | ||
| - `Data storage`: FTS requires an SQL data source to store relevant information for its functioning. | ||
| - `HSM`: When relevant to store secret keys. | ||
| - `External Key Store`: When relevant to store secret keys |
There was a problem hiding this comment.
What is the relation between the key store and the HSM? Should they be operated together? separately? How to configure the Token SDK to use them?
| - `HSM`: When relevant to store secret keys. | ||
| - `External Key Store`: When relevant to store secret keys | ||
|
|
||
| In some configurations, FTS might run in a container that is volume-less. |
There was a problem hiding this comment.
This sentence feels out of context and lacks explanation. Why is running FTS in a volume-less container important? What implications does it have (e.g., for persistence, configuration, or key storage)? Consider adding context and clarifying what data or functionality is affected when no volumes are available.
|
|
||
| In some configurations, FTS might run in a container that is volume-less. | ||
|
|
||
| Other pre-requisites come from the Fabric Smart Client directly. |
There was a problem hiding this comment.
"... and can be found here..."
|
|
||
| ## Performance, Scalability, and Resource Consumption | ||
|
|
||
| The Token-SDK handles the entire lifecycle of a token transactions. |
There was a problem hiding this comment.
| The Token-SDK handles the entire lifecycle of a token transactions. | |
| The Token-SDK handles the entire lifecycle of token transactions. |
?
|
|
||
| The Token-SDK handles the entire lifecycle of a token transactions. | ||
| Different parts of the Token-SDK will run on different network nodes with different roles. | ||
| The careful orchestration of their interactions guarantees that a token transaction is successfully processed. |
There was a problem hiding this comment.
This sentence feels a bit like it assumes everything works perfectly without explaining how. Could we clarify which interactions or mechanisms guarantee the transaction succeeds?
- If it is the role of the administrator to orchestrate everything (I asssume not) then this sentence should explain exactly how.
|
|
||
| ## Serviceability, Logging and Troubleshooting | ||
|
|
||
| The Token-SDK uses the logging infrastructure offered by the Fabric Smart Client. |
There was a problem hiding this comment.
So an application that would also like to use this mechanism should use the FTS logger or directly the FSC logger?
Same question for monitoring.
|
|
||
| The Token-SDK adopts the monitoring infrastructure provided by the [`Fabric Smart Client`](https://github.com/hyperledger-labs/fabric-smart-client/blob/main/docs/platform/view/monitoring.md). | ||
|
|
||
| We use the following two methods to monitor the performance of the application: |
There was a problem hiding this comment.
| We use the following two methods to monitor the performance of the application: | |
| It uses the following two methods to monitor the performance of the application: |
|
|
||
| We use the following two methods to monitor the performance of the application: | ||
| * **Metrics** provide an overview of the overall system performance using aggregated results, e.g. total requests, requests per second, current state of a variable, average duration, percentile of duration | ||
| * **Traces** help us analyze single requests by breaking down their lifecycles into smaller components |
There was a problem hiding this comment.
| * **Traces** help us analyze single requests by breaking down their lifecycles into smaller components | |
| * **Traces** help analyze single requests by breaking down their lifecycles into smaller components |
|
|
||
| ## Serialization | ||
|
|
||
| The Driver API recommends to use the `protobuf` protocol to serialize public parameters, token requests. |
There was a problem hiding this comment.
It recommends protobuf but does it support other alternatives? should we name them?
|
|
||
| The Driver API recommends to use the `protobuf` protocol to serialize public parameters, token requests. | ||
| The relative protobuf messages are [`here`](https://github.com/hyperledger-labs/fabric-token-sdk/blob/2118c1535ebaaed2ecc293b0c3f66aa71eeafe21/token/driver/protos/). | ||
| This guarantees retro and forward compatibility. |
There was a problem hiding this comment.
| This guarantees retro and forward compatibility. | |
| This guarantees backward and forward compatibility. |
| The relative protobuf messages are [`here`](https://github.com/hyperledger-labs/fabric-token-sdk/blob/2118c1535ebaaed2ecc293b0c3f66aa71eeafe21/token/driver/protos/). | ||
| This guarantees retro and forward compatibility. | ||
|
|
||
| The message for the public parameters carries: |
There was a problem hiding this comment.
The term "public parameters" was not defined in this context. Consider explaining it first.
| This guarantees retro and forward compatibility. | ||
|
|
||
| The message for the public parameters carries: | ||
| - A token driver identifier to be able to understand which driver generated these parameters. |
There was a problem hiding this comment.
| - A token driver identifier to be able to understand which driver generated these parameters. | |
| - An identifier of the token driver that generated these parameters. |
The sentence is slightly messy.
|
|
||
| The message for the public parameters carries: | ||
| - A token driver identifier to be able to understand which driver generated these parameters. | ||
| - The lower-lever representation of the public parameters. Each driver must decide how to encode these bytes. |
There was a problem hiding this comment.
| - The lower-lever representation of the public parameters. Each driver must decide how to encode these bytes. | |
| - A lower-level representation of the public parameters. Drivers are responsible for choosing an appropriate byte encoding. |
|
|
||
| ## Security | ||
|
|
||
| Security claims are related to the Token Drivers, implementations of the Driver API. |
There was a problem hiding this comment.
| Security claims are related to the Token Drivers, implementations of the Driver API. | |
| Security claims are associated with Token Drivers, which implement the Driver API. |
| Security claims are related to the Token Drivers, implementations of the Driver API. | ||
| As we have seen before, the Token-SDK comes equipped with two Drivers: | ||
| - `FabToken` does not guarantee the privacy of tokens and identities. | ||
| The validator guarantees that: |
There was a problem hiding this comment.
The validator role was not defined under the FabToken section. Thus, in this context (without reading the dlog section) it is unclear who is the validtor and what is its relation to FTS.
|
|
||
| ### Secrets or Keys | ||
|
|
||
| Secrets and Keys in the Token-SDK are associated to tokens and identities. |
There was a problem hiding this comment.
| Secrets and Keys in the Token-SDK are associated to tokens and identities. | |
| Secrets and keys in the Token-SDK are associated to tokens and identities. |
|
|
||
| Also, here, for simplicity, we assume that: | ||
| - The backend is Fabric, | ||
| - The Token Driver is `DLOG w/o Graph Hiding`. |
There was a problem hiding this comment.
This section is written as a concrete example tied to a specific driver. That may be confusing for readers, since not all drivers will use the same secrets/keys.
Would it make sense to:
- Extract this into a separate example (or “driver‑specific details”) section, rather than part of the core Driver API spec; and
- ensure that this section (in the main documentation) only lists typical kinds of secrets/keys (driver-independent), without assuming one particular implementation?
This would help make the API doc more modular and clearer for anyone implementing a different kind of driver.
|
|
||
| So, let us ask: How does this table get populated? | ||
| There are two ways: | ||
| - From the configuration file. Here is an example take from [`here`](./core-token.md): |
There was a problem hiding this comment.
| - From the configuration file. Here is an example take from [`here`](./core-token.md): | |
| - From the configuration file. Here is an example taken from [`here`](./core-token.md): |
This PR reworks the documentation folder to streamline its content.
In subsequent PRs, we will make sure any misalignment is removed.