github.com/true-sqn/fabric@v2.1.1+incompatible/docs/source/developapps/analysis.md (about) 1 # Analysis 2 3 **Audience**: Architects, Application and smart contract developers, Business 4 professionals 5 6 Let's analyze commercial paper in a little more detail. PaperNet participants 7 such as MagnetoCorp and DigiBank use commercial paper transactions to achieve 8 their business objectives -- let's examine the structure of a commercial paper 9 and the transactions that affect it over time. We will also consider which 10 organizations in PaperNet need to sign off on a transaction based on the trust 11 relationships among the organizations in the network. Later we'll focus on how 12 money flows between buyers and sellers; for now, let's focus on the first paper 13 issued by MagnetoCorp. 14 15 ## Commercial paper lifecycle 16 17 A paper 00001 is issued by MagnetoCorp on May 31. Spend a few moments looking at 18 the first **state** of this paper, with its different properties and values: 19 20 ``` 21 Issuer = MagnetoCorp 22 Paper = 00001 23 Owner = MagnetoCorp 24 Issue date = 31 May 2020 25 Maturity = 30 November 2020 26 Face value = 5M USD 27 Current state = issued 28 ``` 29 30 This paper state is a result of the **issue** transaction and it brings 31 MagnetoCorp's first commercial paper into existence! Notice how this paper has a 32 5M USD face value for redemption later in the year. See how the `Issuer` and 33 `Owner` are the same when paper 00001 is issued. Notice that this paper could be 34 uniquely identified as `MagnetoCorp00001` -- a composition of the `Issuer` and 35 `Paper` properties. Finally, see how the property `Current state = issued` 36 quickly identifies the stage of MagnetoCorp paper 00001 in its lifecycle. 37 38 Shortly after issuance, the paper is bought by DigiBank. Spend a few moments 39 looking at how the same commercial paper has changed as a result of this **buy** 40 transaction: 41 42 ``` 43 Issuer = MagnetoCorp 44 Paper = 00001 45 Owner = DigiBank 46 Issue date = 31 May 2020 47 Maturity date = 30 November 2020 48 Face value = 5M USD 49 Current state = trading 50 ``` 51 52 The most significant change is that of `Owner` -- see how the paper initially 53 owned by `MagnetoCorp` is now owned by `DigiBank`. We could imagine how the 54 paper might be subsequently sold to BrokerHouse or HedgeMatic, and the 55 corresponding change to `Owner`. Note how `Current state` allow us to easily 56 identify that the paper is now `trading`. 57 58 After 6 months, if DigiBank still holds the commercial paper, it can redeem 59 it with MagnetoCorp: 60 61 ``` 62 Issuer = MagnetoCorp 63 Paper = 00001 64 Owner = MagnetoCorp 65 Issue date = 31 May 2020 66 Maturity date = 30 November 2020 67 Face value = 5M USD 68 Current state = redeemed 69 ``` 70 71 This final **redeem** transaction has ended the commercial paper's lifecycle -- 72 it can be considered closed. It is often mandatory to keep a record of redeemed 73 commercial papers, and the `redeemed` state allows us to quickly identify these. 74 The value of `Owner` of a paper can be used to perform access control on the 75 **redeem** transaction, by comparing the `Owner` against the identity of the 76 transaction creator. Fabric supports this through the 77 [`getCreator()` chaincode API](https://github.com/hyperledger/fabric-chaincode-node/blob/{BRANCH}/fabric-shim/lib/stub.js#L293). 78 If Go is used as a chaincode language, the [client identity chaincode library](https://github.com/hyperledger/fabric-chaincode-go/blob/{BRANCH}/pkg/cid/README.md) 79 can be used to retrieve additional attributes of the transaction creator. 80 81 ## Transactions 82 83 We've seen that paper 00001's lifecycle is relatively straightforward -- it 84 moves between `issued`, `trading` and `redeemed` as a result of an **issue**, 85 **buy**, or **redeem** transaction. 86 87 These three transactions are initiated by MagnetoCorp and DigiBank (twice), and 88 drive the state changes of paper 00001. Let's have a look at the transactions 89 that affect this paper in a little more detail: 90 91 ### Issue 92 93 Examine the first transaction initiated by MagnetoCorp: 94 95 ``` 96 Txn = issue 97 Issuer = MagnetoCorp 98 Paper = 00001 99 Issue time = 31 May 2020 09:00:00 EST 100 Maturity date = 30 November 2020 101 Face value = 5M USD 102 ``` 103 104 See how the **issue** transaction has a structure with properties and values. 105 This transaction structure is different to, but closely matches, the structure 106 of paper 00001. That's because they are different things -- paper 00001 reflects 107 a state of PaperNet that is a result of the **issue** transaction. It's the 108 logic behind the **issue** transaction (which we cannot see) that takes these 109 properties and creates this paper. Because the transaction **creates** the 110 paper, it means there's a very close relationship between these structures. 111 112 The only organization that is involved in the **issue** transaction is MagnetoCorp. 113 Naturally, MagnetoCorp needs to sign off on the transaction. In general, the issuer 114 of a paper is required to sign off on a transaction that issues a new paper. 115 116 ### Buy 117 118 Next, examine the **buy** transaction which transfers ownership of paper 00001 119 from MagnetoCorp to DigiBank: 120 121 ``` 122 Txn = buy 123 Issuer = MagnetoCorp 124 Paper = 00001 125 Current owner = MagnetoCorp 126 New owner = DigiBank 127 Purchase time = 31 May 2020 10:00:00 EST 128 Price = 4.94M USD 129 ``` 130 131 See how the **buy** transaction has fewer properties that end up in this paper. 132 That's because this transaction only **modifies** this paper. It's only `New 133 owner = DigiBank` that changes as a result of this transaction; everything else 134 is the same. That's OK -- the most important thing about the **buy** transaction 135 is the change of ownership, and indeed in this transaction, there's an 136 acknowledgement of the current owner of the paper, MagnetoCorp. 137 138 You might ask why the `Purchase time` and `Price` properties are not captured in 139 paper 00001? This comes back to the difference between the transaction and the 140 paper. The 4.94 M USD price tag is actually a property of the transaction, 141 rather than a property of this paper. Spend a little time thinking about 142 this difference; it is not as obvious as it seems. We're going to see later 143 that the ledger will record both pieces of information -- the history of all 144 transactions that affect this paper, as well its latest state. Being clear on 145 this separation of information is really important. 146 147 It's also worth remembering that paper 00001 may be bought and sold many times. 148 Although we're skipping ahead a little in our scenario, let's examine what 149 transactions we **might** see if paper 00001 changes ownership. 150 151 If we have a purchase by BigFund: 152 153 ``` 154 Txn = buy 155 Issuer = MagnetoCorp 156 Paper = 00001 157 Current owner = DigiBank 158 New owner = BigFund 159 Purchase time = 2 June 2020 12:20:00 EST 160 Price = 4.93M USD 161 ``` 162 Followed by a subsequent purchase by HedgeMatic: 163 ``` 164 Txn = buy 165 Issuer = MagnetoCorp 166 Paper = 00001 167 Current owner = BigFund 168 New owner = HedgeMatic 169 Purchase time = 3 June 2020 15:59:00 EST 170 Price = 4.90M USD 171 ``` 172 173 See how the paper owners changes, and how in our example, the price changes. Can 174 you think of a reason why the price of MagnetoCorp commercial paper might be 175 falling? 176 177 Intuitively, a **buy** transaction demands that both the selling as well as the 178 buying organization need to sign off on such a transaction such that there is 179 proof of the mutual agreement among the two parties that are part of the deal. 180 181 ### Redeem 182 183 The **redeem** transaction for paper 00001 represents the end of its lifecycle. 184 In our relatively simple example, HedgeMatic initiates the transaction which 185 transfers the commercial paper back to MagnetoCorp: 186 187 ``` 188 Txn = redeem 189 Issuer = MagnetoCorp 190 Paper = 00001 191 Current owner = HedgeMatic 192 Redeem time = 30 Nov 2020 12:00:00 EST 193 ``` 194 195 Again, notice how the **redeem** transaction has very few properties; all of the 196 changes to paper 00001 can be calculated data by the redeem transaction logic: 197 the `Issuer` will become the new owner, and the `Current state` will change to 198 `redeemed`. The `Current owner` property is specified in our example, so that it 199 can be checked against the current holder of the paper. 200 201 From a trust perspective, the same reasoning of the **buy** transaction also 202 applies to the **redeem** instruction: both organizations involved in the 203 transaction are required to sign off on it. 204 205 ## The Ledger 206 207 In this topic, we've seen how transactions and the resultant paper states are 208 the two most important concepts in PaperNet. Indeed, we'll see these two 209 fundamental elements in any Hyperledger Fabric distributed 210 [ledger](../ledger/ledger.html) -- a world state, that contains the current 211 value of all objects, and a blockchain that records the history of all 212 transactions that resulted in the current world state. 213 214 The required sign-offs on transactions are enforced through rules, which 215 are evaluated before appending a transaction to the ledger. Only if the 216 required signatures are present, Fabric will accept a transaction as valid. 217 218 You're now in a great place translate these ideas into a smart contract. Don't 219 worry if your programming is a little rusty, we'll provide tips and pointers to 220 understand the program code. Mastering the commercial paper smart contract is 221 the first big step towards designing your own application. Or, if you're a 222 business analyst who's comfortable with a little programming, don't be afraid to 223 keep dig a little deeper! 224 225 <!--- Licensed under Creative Commons Attribution 4.0 International License 226 https://creativecommons.org/licenses/by/4.0/ -->