github.com/true-sqn/fabric@v2.1.1+incompatible/docs/source/developapps/architecture.md (about) 1 # Process and Data Design 2 3 **Audience**: Architects, Application and smart contract developers, Business 4 professionals 5 6 This topic shows you how to design the commercial paper processes and their 7 related data structures in PaperNet. Our [analysis](./analysis.html) highlighted 8 that modelling PaperNet using states and transactions provided a precise way to 9 understand what's happening. We're now going to elaborate on these two strongly 10 related concepts to help us subsequently design the smart contracts and 11 applications of PaperNet. 12 13 ## Lifecycle 14 15 As we've seen, there are two important concepts that concern us when dealing 16 with commercial paper; **states** and **transactions**. Indeed, this is true for 17 *all* blockchain use cases; there are conceptual objects of value, modeled as 18 states, whose lifecycle transitions are described by transactions. An effective 19 analysis of states and transactions is an essential starting point for a 20 successful implementation. 21 22 We can represent the life cycle of a commercial paper using a state transition 23 diagram: 24 25  *The state transition 26 diagram for commercial paper. Commercial papers transition between **issued**, 27 **trading** and **redeemed** states by means of the **issue**, **buy** and 28 **redeem** transactions.* 29 30 See how the state diagram describes how commercial papers change over time, and 31 how specific transactions govern the life cycle transitions. In Hyperledger 32 Fabric, smart contracts implement transaction logic that transition commercial 33 papers between their different states. Commercial paper states are actually held 34 in the ledger world state; so let's take a closer look at them. 35 36 ## Ledger state 37 38 Recall the structure of a commercial paper: 39 40  *A commercial paper can be 41 represented as a set of properties, each with a value. Typically, some 42 combination of these properties will provide a unique key for each paper.* 43 44 See how a commercial paper `Paper` property has value `00001`, and the `Face 45 value` property has value `5M USD`. Most importantly, the `Current state` 46 property indicates whether the commercial paper is `issued`,`trading` or 47 `redeemed`. In combination, the full set of properties make up the **state** of 48 a commercial paper. Moreover, the entire collection of these individual 49 commercial paper states constitutes the ledger 50 [world state](../ledger/ledger.html#world-state). 51 52 All ledger state share this form; each has a set of properties, each with a 53 different value. This *multi-property* aspect of states is a powerful feature -- 54 it allows us to think of a Fabric state as a vector rather than a simple scalar. 55 We then represent facts about whole objects as individual states, which 56 subsequently undergo transitions controlled by transaction logic. A Fabric state 57 is implemented as a key/value pair, in which the value encodes the object 58 properties in a format that captures the object's multiple properties, typically 59 JSON. The [ledger 60 database](../ledger/ledger.html#ledger-world-state-database-options) can support 61 advanced query operations against these properties, which is very helpful for 62 sophisticated object retrieval. 63 64 See how MagnetoCorp's paper `00001` is represented as a state vector that 65 transitions according to different transaction stimuli: 66 67  *A commercial paper state is 68 brought into existence and transitions as a result of different transactions. 69 Hyperledger Fabric states have multiple properties, making them vectors rather 70 than scalars.* 71 72 Notice how each individual paper starts with the empty state, which is 73 technically a [`nil`](https://en.wikipedia.org/wiki/Null_(SQL)) state for the 74 paper, as it doesn't exist! See how paper `00001` is brought into existence by 75 the **issue** transaction, and how it is subsequently updated as a result of the 76 **buy** and **redeem** transactions. 77 78 Notice how each state is self-describing; each property has a name and a value. 79 Although all our commercial papers currently have the same properties, this need 80 not be the case for all time, as Hyperledger Fabric supports different states 81 having different properties. This allows the same ledger world state to contain 82 different forms of the same asset as well as different types of asset. It also 83 makes it possible to update a state's structure; imagine a new regulation that 84 requires an additional data field. Flexible state properties support the 85 fundamental requirement of data evolution over time. 86 87 ## State keys 88 89 In most practical applications, a state will have a combination of properties 90 that uniquely identify it in a given context -- it's **key**. The key for a 91 PaperNet commercial paper is formed by a concatenation of the `Issuer` and 92 `paper` properties; so for MagnetoCorp's first paper, it's `MagnetoCorp00001`. 93 94 A state key allows us to uniquely identify a paper; it is created as a result 95 of the **issue** transaction and subsequently updated by **buy** and **redeem**. 96 Hyperledger Fabric requires each state in a ledger to have a unique key. 97 98 When a unique key is not available from the available set of properties, an 99 application-determined unique key is specified as an input to the transaction 100 that creates the state. This unique key is usually with some form of 101 [UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier), which 102 although less readable, is a standard practice. What's important is that every 103 individual state object in a ledger must have a unique key. 104 105 _Note: You should avoid using U+0000 (nil byte) in keys._ 106 107 ## Multiple states 108 109 As we've seen, commercial papers in PaperNet are stored as state vectors in a 110 ledger. It's a reasonable requirement to be able to query different commercial 111 papers from the ledger; for example: find all the papers issued by MagnetoCorp, 112 or: find all the papers issued by MagnetoCorp in the `redeemed` state. 113 114 To make these kinds of search tasks possible, it's helpful to group all related 115 papers together in a logical list. The PaperNet design incorporates the idea of 116 a commercial paper list -- a logical container which is updated whenever 117 commercial papers are issued or otherwise changed. 118 119 ### Logical representation 120 121 It's helpful to think of all PaperNet commercial papers being in a single list 122 of commercial papers: 123 124  *MagnetoCorp's 125 newly created commercial paper 00004 is added to the list of existing 126 commercial papers.* 127 128 New papers can be added to the list as a result of an **issue** transaction, and 129 papers already in the list can be updated with **buy** or **redeem** 130 transactions. See how the list has a descriptive name: `org.papernet.papers`; 131 it's a really good idea to use this kind of [DNS 132 name](https://en.wikipedia.org/wiki/Domain_Name_System) because well-chosen 133 names will make your blockchain designs intuitive to other people. This idea 134 applies equally well to smart contract [names](./contractname.html). 135 136 ### Physical representation 137 138 While it's correct to think of a single list of papers in PaperNet -- 139 `org.papernet.papers` -- lists are best implemented as a set of individual 140 Fabric states, whose composite key associates the state with its list. In this 141 way, each state's composite key is both unique and supports effective list query. 142 143  *Representing a list of 144 PaperNet commercial papers as a set of distinct Hyperledger Fabric states* 145 146 Notice how each paper in the list is represented by a vector state, with a 147 unique **composite** key formed by the concatenation of `org.papernet.paper`, 148 `Issuer` and `Paper` properties. This structure is helpful for two reasons: 149 150 * It allows us to examine any state vector in the ledger to determine which 151 list it's in, without reference to a separate list. It's analogous to 152 looking at set of sports fans, and identifying which team they support by 153 the colour of the shirt they are wearing. The sports fans self-declare their 154 allegiance; we don't need a list of fans. 155 156 157 * Hyperlegder Fabric internally uses a concurrency control 158 mechanism <!-- Add more information to explain this topic--> 159 to update a ledger, such that keeping papers in separate state vectors vastly 160 reduces the opportunity for shared-state collisions. Such collisions require 161 transaction re-submission, complicate application design, and decrease 162 performance. 163 164 This second point is actually a key take-away for Hyperledger Fabric; the 165 physical design of state vectors is **very important** to optimum performance 166 and behaviour. Keep your states separate! 167 168 ## Trust relationships 169 170 We have discussed how the different roles in a network, such as issuer, trader 171 or rating agencies as well as different business interests determine who needs 172 to sign off on a transaction. In Fabric, these rules are captured by so-called 173 [**endorsement policies**](endorsementpolicies.html). The rules can be set on 174 a chaincode granularity, as well as for individual state keys. 175 176 This means that in PaperNet, we can set one rule for the whole namespace that 177 determines which organizations can issue new papers. Later, rules can be set 178 and updated for individual papers to capture the trust relationships of buy 179 and redeem transactions. 180 181 182 In the next topic, we will show you how to combine these design concepts to 183 implement the PaperNet commercial paper smart contract, and then an application 184 in exploits it! 185 186 <!--- Licensed under Creative Commons Attribution 4.0 International License 187 https://creativecommons.org/licenses/by/4.0/ -->