Open-Transactions  0.93.0-ge03d287
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
OTTransactionType.hpp
Go to the documentation of this file.
1 /************************************************************
2  *
3  * OTTransactionType.hpp
4  *
5  */
6 
7 /************************************************************
8  -----BEGIN PGP SIGNED MESSAGE-----
9  Hash: SHA1
10 
11  * OPEN TRANSACTIONS
12  *
13  * Financial Cryptography and Digital Cash
14  * Library, Protocol, API, Server, CLI, GUI
15  *
16  * -- Anonymous Numbered Accounts.
17  * -- Untraceable Digital Cash.
18  * -- Triple-Signed Receipts.
19  * -- Cheques, Vouchers, Transfers, Inboxes.
20  * -- Basket Currencies, Markets, Payment Plans.
21  * -- Signed, XML, Ricardian-style Contracts.
22  * -- Scripted smart contracts.
23  *
24  * Copyright (C) 2010-2013 by "Fellow Traveler" (A pseudonym)
25  *
26  * EMAIL:
28  *
29  * BITCOIN: 1NtTPVVjDsUfDWybS4BwvHpG2pdS9RnYyQ
30  *
31  * KEY FINGERPRINT (PGP Key in license file):
32  * 9DD5 90EB 9292 4B48 0484 7910 0308 00ED F951 BB8E
33  *
34  * OFFICIAL PROJECT WIKI(s):
35  * https://github.com/FellowTraveler/Moneychanger
36  * https://github.com/FellowTraveler/Open-Transactions/wiki
37  *
38  * WEBSITE:
39  * http://www.OpenTransactions.org/
40  *
41  * Components and licensing:
42  * -- Moneychanger..A Java client GUI.....LICENSE:.....GPLv3
43  * -- otlib.........A class library.......LICENSE:...LAGPLv3
44  * -- otapi.........A client API..........LICENSE:...LAGPLv3
45  * -- opentxs/ot....Command-line client...LICENSE:...LAGPLv3
46  * -- otserver......Server Application....LICENSE:....AGPLv3
47  * Github.com/FellowTraveler/Open-Transactions/wiki/Components
48  *
49  * All of the above OT components were designed and written by
50  * Fellow Traveler, with the exception of Moneychanger, which
51  * was contracted out to Vicky C ([email protected]).
52  * The open-source community has since actively contributed.
53  *
54  * -----------------------------------------------------
55  *
56  * LICENSE:
57  * This program is free software: you can redistribute it
58  * and/or modify it under the terms of the GNU Affero
59  * General Public License as published by the Free Software
60  * Foundation, either version 3 of the License, or (at your
61  * option) any later version.
62  *
63  * ADDITIONAL PERMISSION under the GNU Affero GPL version 3
64  * section 7: (This paragraph applies only to the LAGPLv3
65  * components listed above.) If you modify this Program, or
66  * any covered work, by linking or combining it with other
67  * code, such other code is not for that reason alone subject
68  * to any of the requirements of the GNU Affero GPL version 3.
69  * (==> This means if you are only using the OT API, then you
70  * don't have to open-source your code--only your changes to
71  * Open-Transactions itself must be open source. Similar to
72  * LGPLv3, except it applies to software-as-a-service, not
73  * just to distributing binaries.)
74  *
75  * Extra WAIVER for OpenSSL, Lucre, and all other libraries
76  * used by Open Transactions: This program is released under
77  * the AGPL with the additional exemption that compiling,
78  * linking, and/or using OpenSSL is allowed. The same is true
79  * for any other open source libraries included in this
80  * project: complete waiver from the AGPL is hereby granted to
81  * compile, link, and/or use them with Open-Transactions,
82  * according to their own terms, as long as the rest of the
83  * Open-Transactions terms remain respected, with regard to
84  * the Open-Transactions code itself.
85  *
86  * Lucre License:
87  * This code is also "dual-license", meaning that Ben Lau-
88  * rie's license must also be included and respected, since
89  * the code for Lucre is also included with Open Transactions.
90  * See Open-Transactions/src/otlib/lucre/LUCRE_LICENSE.txt
91  * The Laurie requirements are light, but if there is any
92  * problem with his license, simply remove the Lucre code.
93  * Although there are no other blind token algorithms in Open
94  * Transactions (yet. credlib is coming), the other functions
95  * will continue to operate.
96  * See Lucre on Github: https://github.com/benlaurie/lucre
97  * -----------------------------------------------------
98  * You should have received a copy of the GNU Affero General
99  * Public License along with this program. If not, see:
100  * http://www.gnu.org/licenses/
101  *
102  * If you would like to use this software outside of the free
103  * software license, please contact FellowTraveler.
104  * (Unfortunately many will run anonymously and untraceably,
105  * so who could really stop them?)
106  *
107  * DISCLAIMER:
108  * This program is distributed in the hope that it will be
109  * useful, but WITHOUT ANY WARRANTY; without even the implied
110  * warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
111  * PURPOSE. See the GNU Affero General Public License for
112  * more details.
113 
114  -----BEGIN PGP SIGNATURE-----
115  Version: GnuPG v1.4.9 (Darwin)
116 
117  iQIcBAEBAgAGBQJRSsfJAAoJEAMIAO35UbuOQT8P/RJbka8etf7wbxdHQNAY+2cC
118  vDf8J3X8VI+pwMqv6wgTVy17venMZJa4I4ikXD/MRyWV1XbTG0mBXk/7AZk7Rexk
119  KTvL/U1kWiez6+8XXLye+k2JNM6v7eej8xMrqEcO0ZArh/DsLoIn1y8p8qjBI7+m
120  aE7lhstDiD0z8mwRRLKFLN2IH5rAFaZZUvj5ERJaoYUKdn4c+RcQVei2YOl4T0FU
121  LWND3YLoH8naqJXkaOKEN4UfJINCwxhe5Ke9wyfLWLUO7NamRkWD2T7CJ0xocnD1
122  sjAzlVGNgaFDRflfIF4QhBx1Ddl6wwhJfw+d08bjqblSq8aXDkmFA7HeunSFKkdn
123  oIEOEgyj+veuOMRJC5pnBJ9vV+7qRdDKQWaCKotynt4sWJDGQ9kWGWm74SsNaduN
124  TPMyr9kNmGsfR69Q2Zq/FLcLX/j8ESxU+HYUB4vaARw2xEOu2xwDDv6jt0j3Vqsg
125  x7rWv4S/Eh18FDNDkVRChiNoOIilLYLL6c38uMf1pnItBuxP3uhgY6COm59kVaRh
126  nyGTYCDYD2TK+fI9o89F1297uDCwEJ62U0Q7iTDp5QuXCoxkPfv8/kX6lS6T3y9G
127  M9mqIoLbIQ1EDntFv7/t6fUTS2+46uCrdZWbQ5RjYXdrzjij02nDmJAm2BngnZvd
128  kamH0Y/n11lCvo1oQxM+
129  =uSzz
130  -----END PGP SIGNATURE-----
131  **************************************************************/
132 
133 #ifndef OPENTXS_CORE_OTTRANSACTIONTYPE_HPP
134 #define OPENTXS_CORE_OTTRANSACTIONTYPE_HPP
135 
136 #include "crypto/OTASCIIArmor.hpp"
137 #include "OTContract.hpp"
138 #include "OTNumList.hpp"
139 
140 namespace opentxs
141 {
142 
143 class OTIdentifier;
144 class OTString;
145 
146 // OTTransactionType is a base class for OTLedger, OTTransaction, and OTItem.
148 {
149 private: // Private prevents erroneous use by other classes.
150  typedef OTContract ot_super;
151 
152 protected:
153  // keeping constructor protected in order to force people to use the other
154  // constructors and
155  // therefore provide the requisite IDs.
157 
158  // Basically what I want here is, SERVER ID and ACCOUNT ID.
159  // That way, all the child classes can also have a server ID and account ID,
160  // and they can compare to the internal ones to make sure they match.
161  // This class centralizes that mechanism so I'm not duplicating it three or
162  // four times.
163  //
164  // So I need the SERVER ID and the ACCOUNT ID stored here.
165  //
166  // Fortunately, OTContract already handles the ID, which is the Account ID
167  // in
168  // the context of all transaction objects. If your "bank account" is acct
169  // #350, then
170  // ALL of your transactions will have m_ID of #350 as a rule, and once
171  // loaded from
172  // storage and signature verified, m_AcctID should also contain #350. The
173  // transaction
174  // number is a separate value, m_lTransactionNum, which uniquely identifies
175  // a transaction.
176  // The idea is to prevent a file from loading up into the same variable and
177  // overwriting
178  // what we expected with a new value that we didn't expect (and that perhaps
179  // has a good
180  // signature on it, but from some other account, etc). A transaction can
181  // ONLY be generated
182  // properly (using a transaction # that was already signed out to you, yadda
183  // yadda yadda)
184  // OR it can be an existing transaction being loaded from string or storage.
185  // Since transactions
186  // are nested (with a ledger containing a list of transactions, each
187  // containing a list of
188  // items) then we always know WHICH VALUES we are EXPECTING, out of any of
189  // these objects,
190  // BEFORE they are loaded into memory. (For account ID, server ID, user ID.)
191  // We set those
192  // values when INSTANTIATING the objects, BEFORE they have been loaded. ===>
193  // Then the loading
194  // occurs, and we see the server ID, acct ID, user ID, etc that were
195  // ACTUALLY in the file,
196  // whose signature we have now verified, stored as SEPARATE VALUES, so we
197  // can compare.
198  // After loading there is a separate, "VERIFY" process, where a transaction
199  // type can be
200  // verified, make sure all the right IDs are in order, etc.
201  // Why is this important? Primarily because these IDs *are* set, for most
202  // objects, before
203  // they are loaded, and they should NEVER be different than what they are
204  // set to at the
205  // time they were FIRST GENERATED. (Loading should only faithfully copy
206  // them, thereafter.)
207  // However, once they are loaded, we shall see what they really are -- and
208  // we should not
209  // accidentally propagate new and different values under our own signature,
210  // in some future
211  // receipt, if they were to be somehow substituted during the loading phase.
212  // Remember that
213  // these objects are nestable. Sometimes an individual transaction item is
214  // later individually
215  // tacked onto someone else's receipt. For example, when someone deposits
216  // your cheque, drawn
217  // from one of your accounts, you will not get his entire "depositCheque"
218  // transaction attached
219  // to the chequeReceipt in your inbox. That original transaction #3 (say)
220  // not only included a
221  // "depositCheque" transaction item, also #3, (and also for the same acct#
222  // and server# etc)
223  // but it also included a "balance agreement" transaction item, necessary
224  // for proving his
225  // balance at the time of the transaction, and for proving (between him and
226  // the server) which
227  // of his transactions had already cleared, and which instruments were
228  // valid. This is part
229  // of the mechanism that makes destruction of account history possible.
230  // Every transaction
231  // request must be accompanied by a signed balance agreement, which has the
232  // same acct # and
233  // server # and transaction # as the main transaction and all the other
234  // transaction items.
235  // BUT WHAT BUSINSESS IS IT OF YOURS the information that appears on his
236  // balance agreement?
237  // Just because he deposited your cheque, now you should have access to his
238  // entire balance
239  // agreement? No, because a copy of his transaction is not what appears on
240  // your chequeReceipt.
241  // Rather, the individual "depositCheque" transaction item is what appears
242  // on your receipt,
243  // not any of the other transaction items (such as the balance agreement)
244  // and not a copy
245  // of the overall depositCheque transaction itself, that he originally
246  // submitted to the
247  // server. Fortunately, each individual transaction item is signed, and is
248  // verified to have
249  // all the same IDs as the overall transaction that it belongs to. And while
250  // although there are
251  // individual transaction items for any given transaction#, there is only a
252  // single transaction.
253  // And no item can ever be substituted onto another transaction without
254  // failing this verification,
255  // since the IDs wouldn't match--just as none of the IDs themselves can be
256  // changed later without
257  // failing the signature verification. No transaction ID can be used to
258  // change your balance, without
259  // a corresponding receipt appearing in your inbox (signed by you) to
260  // compensate for the change
261  // in balance. The same instrument cannot be used to change your balance
262  // twice, because two
263  // balance changes (double the amount authorized) must necessarily be
264  // accompanied by two inbox
265  // receipts, signed by you, authorizing each balance change. The same ID
266  // cannot appear twice in your inbox
267  // without giving itself away (and provably so, since it appears on every
268  // receipt) and clearly
269  // you could wave the receipt around and prove that ID is being used twice,
270  // and that thus one
271  // of the balance changes is entirely invalid, based on a repeated
272  // transaction, but furthermore,
273  // once you have signed a NEW balance agreement (on the receipt of your next
274  // future transaction)
275  // closing transaction #3 for good (and thus removing it from your inbox AND
276  // DESTROYING ANY
277  // TRACE ON THE SERVER SIDE THAT THE TRANSACTION EVER OCCURRED!!!!!) it now
278  // becomes IMPOSSIBLE
279  // for that old instrument to be re-used and to alter your balance! I'll
280  // explain. Remember how
281  // I said, AS LONG AS the receipt appears in your inbox, criminals cannot
282  // steal from you by
283  // putting through a copy of that transaction twice? (since clearly you have
284  // paid already
285  // for transaction #3...) This is easily proven by the simple fact that 2
286  // transactions with
287  // the same ID must appear at the SAME TIME in your inbox for this to be
288  // possible, which would
289  // also appear on every receipt, signed by both client and server, which
290  // clearly both entities
291  // have an interest in consistently refusing to do (neither of them in his
292  // clear mind would ever
293  // sign such a receipt.) Well what happens once the receipt is REMOVED from
294  // your inbox, as you
295  // sign off on it, in your next/future balance agreement for your next
296  // transaction? Once you
297  // have signed off on the new balance, the server doesn't need to keep a
298  // copy of the inbox
299  // receipt anymore to prove your current balance -- you have now SIGNED OFF
300  // on the latest balance,
301  // so the server doesn't NEED to keep ANYTHING around to prove your balance
302  // anymore, other
303  // than your latest balance agreement. It doesn't NEED your old inbox
304  // receipts anymore to prove
305  // your current balance --- they are old and can be thrown away. So the
306  // question arises again--
307  // how then can I prevent a SECOND RECEIPT WITH THE SAME ID from appearing
308  // ONCE AGAIN in my Inbox,
309  // (a copy of an old instrument perhaps, featuring my actual signature, that
310  // WAS a valid instrument
311  // in the past, but that has already been used and is no longer valid). How
312  // can I prove that this
313  // instrument, BEARING MY SIGNATURE (along with the account#, server# etc)
314  // is no longer valid?
315  //
316  // ====> Because when I closed out the chequeReceipt, signing the new
317  // balance agreement and
318  // removing it from my inbox, that balance agreement included a list of all
319  // the transaction #s
320  // that were STILL SIGNED OUT TO ME AT THAT TIME, and #3 was REMOVED from
321  // that list. That is, I
322  // did not sign the new balance agreement removing the receipt#3 from my
323  // inbox, without simultaneously
324  // forcing the server to sign that I am no longer responsible for
325  // transaction #3.
326  // ===> Therefore, should a receipt ever appear in my inbox in the future,
327  // featuring transaction #3,
328  // it would again be provably invalid, EVEN IF MY SIGNATURE IS GOOD, since I
329  // am no longer responsible
330  // for transaction #3, as I can prove by waving my last (server-signed)
331  // receipt around, which
332  // contains a list of exactly the transaction #s that are still signed out
333  // to me. If the server
334  // wishes to dispute this, then let it produce a newer receipt with my
335  // signature on it. (It cannot.)
336  //
337  //
338  // Okay, then what if the server tricks me into signing for a transaction #
339  // that I ONCE signed out
340  // BEFORE, years ago? For example, let's say I used #3 for a $10000 cheque,
341  // which was cashed 5 years
342  // ago. The money already came out of my account. Now it is five years
343  // later, and #3 no longer appears
344  // on my list, but as a normal routine of banking, I ask the server for some
345  // new transaction #s, and
346  // it sends me #3, and I sign out the number AGAIN. Perhaps I am about to
347  // use it for buying a stick of
348  // gum for 5 cents. But the malicious server pounces! It was waiting for
349  // this, and it immediately runs
350  // through the $100000 cheque from 5 years before! Featuring the exact same
351  // transaction #, and
352  // featuring my signature! But it cannot do this either, because no user
353  // will ever sign out a transaction
354  // number that is LESS THAN one it has signed out in the past! The Nym
355  // object keeps track of the highest
356  // # it has EVER received from each server, and it will NEVER sign out a
357  // transaction # that is less
358  // than this number.
359  //
360  // Remember, the transaction # of all of these NESTED, TRANSACTION TYPE
361  // objects, (ledgers, transactions,
362  // transaction items, balance agreements, etc) must match perfectly, and is
363  // verified at the same time
364  // that the signature on the transaction is verified. The same is true for
365  // verifying the account ID,
366  // the server ID, and the user ID. Any discrepancy is immediately caught
367  // anytime a transaction is
368  // loaded/verified (which must happen in order for it to be used.) A
369  // malicious actor wishing to trick
370  // you into signing a transaction # you were not expecting (so as to make
371  // you liable for some old
372  // instrument you signed, bearing the same #) cannot do so if you will only
373  // write the "Real" server
374  // ID when first generating the transaction (such as when first generating
375  // the transaction), but you
376  // will only read or write into the "Purported" server ID when loading
377  // something up, and that you always
378  // compare them when loading. Instantly any discrepancy is caught upon
379  // loading, preventing the transaction
380  // from loading, and thus preventing you from later going on to sign the
381  // wrong number after loading it,
382  // by for example including a copy of it on some signed receipt of your own.
383  // You could not have included
384  // it on your signed receipt, without loading it up first, and you could not
385  // have loaded it without
386  // verifying the signatures and IDs on all sub-items. You never could have
387  // had an actual ID overwritten
388  // by the wrong ID, and then perpetuated by your own signed copies of that
389  // going into the future.
390  //
391  // The IDs that appear on the transaction when it is FIRST GENERATED -- one
392  // ID is even signed out to me --
393  // are the only IDs that can ever appear. Example: Alice owns accounts A and
394  // B. Therefore the server
395  // will successfully verify Alice's signature on any account A instruments,
396  // and it will also successfully
397  // verify Alice's signature on any account B instruments. This means if you
398  // sneakily give the server
399  // an "account B" instrument, BUT TRY TO REDEEM IT AT "ACCOUNT A", that the
400  // signature itself, on the
401  // signed instrument, WILL VERIFY SUCCESSFULLY. When the server is loading a
402  // transaction for "account A",
403  // it is coming from an "account A" ledger, which already has the acct#
404  // built it, and thus it sets that
405  // account # onto the transaction before the transaction is even loaded.
406  // Once the transaction is loaded,
407  // the # inside is available (we now have both) and we can compare them to
408  // make sure they are the same,
409  // which we do before ever actually using that transaction object. This is
410  // why it's important not to
411  // simply "load up" the transaction and go with whatever IDs are in there,
412  // or allow them to overwrite
413  // the ones we are expecting to be there.
414  //
415  //
416  // Basically: We set the number beforehand, and verify after loading to make
417  // sure each thing loaded has the
418  // IDs expected. The # cannot be changed after signing, without invalidating
419  // the signature, so we verify the
420  // signature. This means the transaction item cannot be used on any OTHER
421  // transaction except for the one
422  // it was meant, or by any other acct owned by that same nym, because those
423  // IDs are compared whenever each
424  // piece is loaded.
425  // An "account B" instrument, with "account B" written all it, cannot be
426  // simply loaded as an "account A"
427  // transaction, even though the signature is good, because the "account B"
428  // will be loaded into a separate
429  // spot than the actual acct #, and compared against it. I will never
430  // accidentally sign "account B" transaction
431  // thinking that it is an "account A" transaction. Furthermore, I will never
432  // load an "account B" transaction
433  // and then accidentally overwrite "A" over the "B" and sign it again.
434  // (Meaning I cannot be tricked, by
435  // a valid signature on "B", into loading it up mistakenly as an "A" and
436  // then signing it as an "A" when it
437  // was secretly a "B" the whole time.)
438  //
439  // The idea is that whatever number appears inside a transaction (and all
440  // its items) when you LOAD the file
441  // will always be the same number that you write out when you SAVE the file.
442  // But that this number might
443  // not be the same as the number that it was when you first generated the
444  // transaction, or that you are
445  // expecting it to be when you load the transaction up. You keep them
446  // separate, and you compare them to
447  // make sure they are the same.
448  // Put another way: You don't want to load up a bad number and then
449  // accidentally save a bad transaction with
450  // a GOOD ID, simply because you were EXPECTING it to be the right number
451  // (and had thus forced that # as the only
452  // one you're willing to write), and you also don't want to FAIL TO EXPECT A
453  // SPECIFIC NUMBER and thus allow
454  // it to be determined by what is loaded up, in complete disregard of what
455  // number was expected to be there before
456  //
457  // Put another way:
458  // 1. You normally want to force specific IDs when you sign a contract, to
459  // prevent any others from being substituted,
460  // because you want to choose the IDs that you sign.
461  // 2. But you don't want the practice of forcing the IDs to cause you to
462  // mistakenly load up an instrument with
463  // one ID, perhaps a transaction# you have used before, or for an
464  // AccountID that is yours, but is for a different
465  // one of your accounts, (otherwise successfully verifying the signature
466  // itself) and then re-save it with the
467  // forced IDs. You normally never want to save a transaction any
468  // differently than how it appeared when you loaded
469  // it up.
470  // For example: If you give me transaction #3, but it secretly has an item
471  // #5 in its list (where all other items are
472  // supposed to be for #3), and then I load it up, I don't want to save #5 as
473  // a 3 when I save it again.
474  // =========> And I must reset the XML contents at the time the contract is
475  // signed! THAT is the
476  // critical time when all the data members are taken from the data object,
477  // and put into XML form -- just before
478  // signing itself, which requires a hash, and if you are making decisions
479  // based on the data members of some contract,
480  // and then you sign the contract, then you want damn well sure to know that
481  // the XML contents you are signing, match up
482  // with the data objects you were using, and not based on some older
483  // configuration of those objects that just happened to
484  // persist in an old copy of the XML. The best way to insure that, is to
485  // actually write those data objects freshly to the
486  // XML as part of the signing process, just before the signing itself. At
487  // this time, I do not want to write any Server ID
488  // other than the right one -- the one it is supposed to be (the one I am
489  // expecting) but simultaneously, I cannot just
490  // force my own
491  // server ID into that spot, or Acct ID, or transaction ID, because I don't
492  // want to ever be tricked by way of
493  // an otherwise good instrument (but with a wrong Acct ID) from being
494  // re-signed with my actual acct ID substituted.
495  // Rather, if I load it up and it has the wrong ID, then when I WRITE IT OUT
496  // it should CONTINUE to have the wrong ID.
497  //
498  // Put another way:
499  // I should never write these IDs as being any different than what I read,
500  // if they are wrong, but I should also never
501  // write them as being different from what I EXPECT. Clearer: If I expect #3
502  // when loading a transaction up, then I
503  // damn well better only read #3, and I will store separately what I expect,
504  // versus what I load, and I will compare
505  // them when I load, to make sure they are the same. But I will also only
506  // WRITE the number that I READ!! Meaning
507  // if I expected #3, but actually loaded #5, I'm not going to then take #5
508  // and SAVE IT AS A THREE, just because I
509  // am in the habit of forcing myself to ONLY SAVE AS A THREE. That could
510  // enable someone to "slip" me a 5, and get
511  // me to re-sign it as a 3!! As long as the signature matches, that part
512  // verifies successfully. If I just loaded
513  // and verified the signature, and forced the actual # to be the one I'm
514  // expecting, the a "5" could be used as a "3"
515  // as long as they had the same owner. I DO want to force the number, since
516  // it should be a specific one, but I don't
517  // want that to ever cause me to get tricked into turning "auto-fixing" an
518  // instrument from a different # by substituting
519  // the correct # onto it just prior to signing, because someone had tricked
520  // me into loading it at the wrong time,
521  // by swapping it for the contract that was meant to be there, etc. That's
522  // why I have to compare IDs.
523  //
524  // The "Real" server ID is set when the item is first generated. SINCE it
525  // was first generated, we go ahead at that one
526  // time and set the Purported Server ID to match. Ever thereafter, they are
527  // separated in a way, with the "real" ID being
528  // only set as an "expected to load number" and the "purported" ID being
529  // "the one we actually loaded" number.
530  //
531  // -- We only save to storage the purported number. This prevents you from
532  // accidentally saving any number other than
533  // the one you loaded, into any given instrument, whether it's the number
534  // you expected or not. No one can ever give
535  // you one instrument and "trick" you into signing it with your "expected"
536  // IDs substituted. If you slip me a 69, then
537  // I will also save it as a 69, not as a 5 just because I thought it would
538  // be a 5.
539  // -- We only load from storage to the purported number, not to the real
540  // one. This prevents the software from actually
541  // using the number for anything internally.
542  // We never load to the real number. (This prevents anyone from "fucking
543  // with" your actual ID by something
544  // they put into a file, since nothing in the datafile will ever be used as
545  // the "real" number.)
546  // We never save the real number. (This insures that we will only save the
547  // same number we loaded.)
548  //
549  // -- If you slip me a #69 when I expected a #5, you can never trick me into
550  // using "#69" on any of my stuff by doing so,
551  // since I will only use numbers that are what I expected them to be, which
552  // is the "real" number that I force (#5)
553  // and not the "purported" number that I load.
554  // -- You also cannot trick me into signing an old "#69" instrument where I
555  // accidentally force the # to 5 just before
556  // signing, since I would have an error at the time of first loading up the
557  // instrument, when the 69 would fail to match
558  // the expected 5, which would in fact cause the transaction to entirely
559  // fail loading.
560  // -- If I ONLY EVER load/save to/from the purported number, I will only
561  // ever pass it on the same as how I found it.
562  // If there is a bad 69 on an instrument, then that bad 69 will stay there,
563  // and nothing will trick me into putting a
564  // good 5 onto that instrument just because that's what I was expecting.
565  // (And then signing it.)
566  // -- If I only ever actually USE the REAL number, then I can never be
567  // tricked into using a number I didn't expect
568  // based purely on the number that appears as the correct number in the data
569  // file. If I was expecting a #5, and that
570  // is what I set on the "real" number, and I only USE the "real" number,
571  // then I can only ever use #5, which is what
572  // I expect! Even if you could somehow stick a #69 into the purported value
573  // (by sticking it into the file) you cannot
574  // get me to USE it. I use the real value, not the purported value.
575  // -- If I always COMPARE the two values when first loading, then I can make
576  // sure I never use the wrong ID, since
577  // I'm not even PHYSICALLY ABLE to LOAD the transaction--so how could I ever
578  // expect to inadvertantly end up USING it
579  // in any way? I can't even load it.
580  // -- Once the loading process has finished, then I'm basically safe to use
581  // either number (real or purported) since
582  // we know they are identical anyway. The main use of them is before /
583  // during the **loading/verification process.**
584  //
585  // -- OTTransaction the_transaction(ID: 5); m_ID shows me what acct# I
586  // expect the_transaction to have (5) perhaps
587  // because I got it off of the ledger object. I set this before loading the
588  // transaction from string. After loading,
589  // m_AcctID is what shows me the acct# that T actually HAS in its datafile.
590  // They SHOULD match. I verify this at
591  // loading to make sure people haven't swapped the datafile for one from a
592  // different acct but perhaps same
593  // signature/owner. m_AcctID, which is
594  // what I actually loaded, is also the only value I will save back again. If
595  // it said "69" then I will save 69.
596  // I have still forced it to #5 because the item marked #69 causes the
597  // transaction to fail loading. Only a correct #5
598  // will load, and therefore I will only ever SAVE a correct #5 as well.
599  // After all, there are only two times that value
600  // gets set: Upon generation, and upon loading
601  //
602  //
603  // Another example:
604  // OTAccount THE_ACCOUNT(USER_ID, GetRealAccountID(), GetRealServerID());
605  //
606  // Notice I am loading the account based on the ID from the transaction. If
607  // I used the "Purported Account ID"
608  // then I would basically be loading WHATEVER account ID that's there inside
609  // the transaction, even if it's not
610  // the one I was expecting. You could put account # "6969" wrongly into one
611  // of the items, and trick me into
612  // loading up account #6969 when this transaction is only actually
613  // authorized for account #5. The REAL account
614  // number, #5, the authorized one, the one on the receipt, is the ONLY one I
615  // want to potentially load up and
616  // subtract money from. NOT the one I read from the file, which may have
617  // been swapped by a malicious entity.
618  // Of course, once the initial loading/verification is done, then we know
619  // the IDs match, so we're basically
620  // cool to use Purported, but in perfect theory, should not use it, just
621  // persist it. The Real one, do NOT persist
622  // it -- it's set at generation, and then set at loading based on
623  // expectations, and whatever is actually loaded
624  // gets verified against that.
625  //
626  //
627  // It's important to keep the server (or any party) from being tricked into
628  // signing
629  // a transaction #, or any other ID, that is different than what he EXPECTED
630  // it to be.
631  //
632  // It may be strange to think of the "purported" account # as the one that
633  // actually appears
634  // in the signed file, while the "real" account # is the one that I'm
635  // EXPECTING, whether it's in
636  // the file or not. But the "REAL" account most importantly is the account
637  // that I'm ACTUALLY using
638  // for the transaction, that I've actually requested, and been verified for
639  // that account, and provided
640  // signed receipts for that account -- THAT is the real account as far as
641  // anyone is concerned, when it
642  // comes to moving any money out of it, certainly! Any jackass could replace
643  // a receipt with another.
644  //
645  // How do I want to use Real versus Purported, as a general rule of thumb?
646  //
647  // Purported is where I load to and save from. It's also what I distrust. In
648  // fact I verify it the
649  // very first thing when I load it up, as part of the loading process. Also,
650  // anytime I want to verify
651  // an actual (trusted) ID from somewhere against an instrument, in order to
652  // help verify that instrument,
653  // I will compare it to the Purported ID on the instrument, because unlike
654  // what I expect it to be, that's
655  // what ID ACTUALLY appears on the instrument! So if I am to verify
656  // ANYTHING, it must be the actual ID on
657  // the instrument.
658  // ===> Whereas with Real IDs, that's what I use when I am actually DOING
659  // SOMETHING with the instrument. For
660  // example again:
661  // OTAccount THE_ACCOUNT(USER_ID, GetRealAccountID(), GetRealServerID());
662  // In that case, I am ACTUALLY LOADING AN ACCOUNT, and may move some money
663  // from it. I do NOT want to load
664  // ANY account whatsoever other than the actually-authorized account,
665  // period. So I should always use the Real
666  // ID here, because I am actually DOING something with it.
667  // In practice, as I said before, this is verified as part of successfully
668  // loading a transaction into memory,
669  // so the two numbers in practice will always match. But todo, I plan to
670  // review my code and make sure everything
671  // is safely in keeping with this philosophy and if not, why not, with
672  // comments.
673  //
674  /*
675  this code segment, btw, completely illustrates that philsophy:
676 
677  // When actually doing something, we use the real IDs...
678  OTAccount THE_ACCOUNT(USER_ID, GetRealAccountID(), GetRealServerID());
679 
680  // When distrusting the instrument (immediately following in the actual
681  code), we
682  // use the purported IDs in verification.
683  //
684  if (!THE_ACCOUNT.LoadContract() || !THE_ACCOUNT.VerifyAccount(THE_NYM))
685  {
686  // error, return.
687  otOut << "Failed loading or verifying account in
688  OTTransaction::VerifyBalanceReceipt.\n";
689  return false;
690  }
691  // the account, inbox, and outbox all have the same Server ID. But does it
692  match *this receipt?
693  else if (THE_ACCOUNT.GetPurportedServerID() != GetPurportedServerID())
694  {
695  // error, return.
696  otOut << "Account, inbox or outbox server ID fails to match receipt
697  server ID.\n";
698  return false;
699  }
700  else if (THE_ACCOUNT.GetPurportedAccountID() != GetPurportedAccountID()) //
701  Same as above except for account ID instead of server ID.
702  {
703  // error, return.
704  otOut << "Account ID fails to match receipt account ID.\n";
705  return false;
706  }
707 
708 
709  */
710  //
711  //
712  // So therefore I just need to add the Server ID, and I have both.
713  // Then all child classes should ALSO implement their own copy of both, and
714  // compare the
715  // two whenever loading something, so that we know we're safe, as well as
716  // comparing
717  // signatures.
718  //
719  // That's really the whole point of this software -- comparing IDs and
720  // verifying
721  // signatures.
722 
723  // OTIdentifier m_ID; // Account ID. This is in OTContract
724  // (parent class). Here we use it for the REAL ACCOUNT ID (set before
725  // loading.)
726  OTIdentifier m_AcctID; // Compare m_AcctID to m_ID after loading it from
727  // string or file. They should match, and signature
728  // should verify.
729 
730  OTIdentifier m_ServerID; // Server ID as used to instantiate the
731  // transaction, based on expected ServerID.
732  OTIdentifier m_AcctServerID; // Actual ServerID within the signed portion.
733  // (Compare to m_ServerID upon loading.)
734 
735  // Update: instead of in the child classes, like OTLedger, OTTransaction,
736  // OTItem, etc, I put the
737  // "purported acct ID" and "purported server ID" here in the base class, to
738  // manage it all centrally.
739 
740  OTIdentifier m_AcctUserID; // NymID of the user who created this item. (In
741  // the future, this item
742  // might be the only reference someone has. They'll want my NymID.)
743  // I put this in protected because there are now Get/Set methods...so use
744  // them!
745  int64_t m_lTransactionNum; // The server issues this and it must be sent
746  // with transaction request.
748  // Sometimes an item is in reference to some other transaction, which does
749  // NOT need to be
750  // included in the item (since the server already has it) but instead can be
751  // referenced by
752  // transaction ID.
753  // Let's say Alice sends a transfer #100 to Bob.
754  // Then Bob receives a pending in his inbox, #800, which is in reference to
755  // #100.
756  // Then Bob accepts the pending with processInbox #45, which is in reference
757  // to #800.
758  // Then Alice receives a transferReceipt #64, which is in reference to #45.
759  // Then Alice accepts the transferReceipt with processInbox #91, in
760  // reference to #64.
761  // ALL OF THOSE transactions and receipts will have origin #100 attached to
762  // them.
763  // This:
764  //
765  int64_t m_lNumberOfOrigin; // In reference to in reference to in reference
766  // to in reference to the origin.
767  OTASCIIArmor m_ascInReferenceTo; // This item may be in reference to a
768  // different item.
769  bool m_bLoadSecurely; // Defaults to true.
770  // For a "blank" or "successNotice" transaction, this contains the list of
771  // transaction
772  // numbers that are either about to be signed out (blank) or have already
773  // just been signed-out
774  // (successNotice). Either way, we used to have a separate transaction in
775  // the Nymbox for EACH
776  // blank number as well as a separate transaction for EACH successNotice,
777  // along with box receipts
778  // needing to be downloaded for each! 10 transaction numbers being signed
779  // out could result in the
780  // download of 20 or more box receipts....
781  // Therefore, finally decided to put MULTIPLE transaction numbers onto
782  // "blank" and "successNotice".
783  // So there is only a single message in the Nymbox which contains ALL your
784  // incoming blanks, and a
785  // single message for ALL your "successNotice" numbers.
786  // If the server goes to ADD MORE, it first checks to see if one is ALREADY
787  // THERE, and then simply
788  // adds the number to the existing blank or successNotice (whichever is
789  // appropriate) that's already
790  // in your Nymbox, where an entire list of those numbers might already be.
791  //
792  // THIS is where that list is stored:
793  //
794  OTNumList m_Numlist; // blanks and successNotice use this instead of having
795  // a separate transaction for EVERY NUMBER.
796  // (Had to fix that... way too many box receipts were being downloaded.)
797  // Note: I moved this to OTTransactionType so I can use it from within
798  // OTItem as well, so when I accept transaction
799  // numbers, I am able to list them in the accept item.
800 public:
801  EXPORT void GetNumList(OTNumList& theOutput);
802  EXPORT static OTTransactionType* TransactionFactory(OTString strInput);
803  bool Contains(const OTString& strContains); // Allows you to string-search
804  // the raw contract.
805  EXPORT bool Contains(const char* szContains); // Allows you to string-search
806  // the raw contract.
807  // OTAccount, OTTransaction, OTItem, and OTLedger are all derived from
808  // this class (OTTransactionType). Therefore they can all quickly identify
809  // whether one of the other components belongs to the same account.
810  //
811  bool IsSameAccount(const OTTransactionType& rhs) const;
812 
813  // This means, "I don't know the 'Real' IDs when I'm about to load this
814  // contract, so just
815  // read the purported IDs (the ones inside the contract itself) and set the
816  // real IDs to match."
817  //
818  // (Normally you'd set the real IDs, then load into purported, then compare
819  // the two, to make
820  // sure your file hasn't been swapped. The only time you circumvent that, is
821  // when you know
822  // the IDs are correct, or when you have no "real" ID other than what is in
823  // the file itself.)
824  //
826  {
827  m_bLoadSecurely = false;
828  }
829 
830  // Someday I'll add EntityID and RoleID here (in lieu of UserID,
831  // in cases when the account is owned by an Entity and not a Nym.)
832  //
833  inline const OTIdentifier& GetUserID() const
834  {
835  return m_AcctUserID;
836  }
837  inline void SetUserID(const OTIdentifier& theID)
838  {
839  m_AcctUserID = theID;
840  }
841 
842  // Used for: Load an account based on this ID
843  inline const OTIdentifier& GetRealAccountID() const
844  {
845  return m_ID;
846  }
847  inline void SetRealAccountID(const OTIdentifier& theID)
848  {
849  m_ID = theID;
850  }
851 
852  // Used for: Verify this ID on a transaction to make sure it matches the one
853  // above.
854  inline const OTIdentifier& GetPurportedAccountID() const
855  {
856  return m_AcctID;
857  }
858  inline void SetPurportedAccountID(const OTIdentifier& theID)
859  {
860  m_AcctID = theID;
861  }
862 
863  // Used for: Load or save a filename based on this ID.
864  inline const OTIdentifier& GetRealServerID() const
865  {
866  return m_ServerID;
867  }
868  inline void SetRealServerID(const OTIdentifier& theID)
869  {
870  m_ServerID = theID;
871  }
872 
873  // Used for: Load or save the ID in the file contents into/out of this ID.
874  inline const OTIdentifier& GetPurportedServerID() const
875  {
876  return m_AcctServerID;
877  }
878  inline void SetPurportedServerID(const OTIdentifier& theID)
879  {
880  m_AcctServerID = theID;
881  }
882 
883  // Compares the m_AcctID from the xml portion of the contract
884  // with m_ID (supposedly the same number.)
885  // Also Verifies the ServerID, since this object type is all about the both
886  // of those IDs.
887  EXPORT virtual bool VerifyContractID() const;
888 
889  // This calls VerifyContractID() as well as VerifySignature()
890  // Use this instead of OTContract::VerifyContract, which expects/uses a
891  // pubkey from inside the contract.
892  virtual bool VerifyAccount(const OTPseudonym& theNym);
893 
894  // The parameters to the constructor are supposed to be the ACTUAL account
895  // ID and server ID.
896  // Whereas the child classes contain their own copies of those IDs which
897  // they load into their
898  // own member variables. When that happens, they can then be compared to the
899  // ones that were
900  // already passed in HERE to see if anything is fishy.
901  // Thus, while OTContract instituted a constructor with an ID,
902  // OTTransactionType will require
903  // both the Account ID and the ServerID.
904  OTTransactionType(const OTIdentifier& theUserID,
905  const OTIdentifier& theAccountID,
906  const OTIdentifier& theServerID);
907  OTTransactionType(const OTIdentifier& theUserID,
908  const OTIdentifier& theAccountID,
909  const OTIdentifier& theServerID, int64_t lTransactionNum);
910 
911  void InitTransactionType();
912  virtual ~OTTransactionType();
913  virtual void Release();
915 
916  // return -1 if error, 0 if nothing, and 1 if the node was processed.
917  // virtual int32_t ProcessXMLNode(irr::io::IrrXMLReader*& xml);
918  // void UpdateContents(); // I don't think I need this here. My parent
919  // and child classes do well enough.
920 
921  // need to know the transaction number of this transaction? Call this.
922  EXPORT int64_t GetTransactionNum() const;
923  void SetTransactionNum(int64_t lTransactionNum);
924 
925  EXPORT virtual void CalculateNumberOfOrigin(); // Calculates number of
926  // origin.
927  EXPORT virtual int64_t GetNumberOfOrigin(); // Calculates IF NECESSARY.
928 
929  EXPORT int64_t GetRawNumberOfOrigin() const; // Gets WITHOUT calculating.
930 
931  EXPORT void SetNumberOfOrigin(int64_t lTransactionNum);
932  EXPORT void SetNumberOfOrigin(OTTransactionType& setFrom);
933 
934  EXPORT bool VerifyNumberOfOrigin(OTTransactionType& compareTo);
935 
936  EXPORT int64_t GetReferenceToNum() const;
937  EXPORT void SetReferenceToNum(int64_t lTransactionNum);
938 
939  EXPORT void GetReferenceString(OTString& theStr) const;
940  EXPORT void SetReferenceString(const OTString& theStr);
941 
942  // virtual bool SaveContractWallet(FILE* fl);
943  virtual bool SaveContractWallet(std::ofstream& ofs) const;
944 };
945 
946 } // namespace opentxs
947 
948 #endif // OPENTXS_CORE_OTTRANSACTIONTYPE_HPP
EXPORT void GetReferenceString(OTString &theStr) const
virtual EXPORT void CalculateNumberOfOrigin()
EXPORT void SetNumberOfOrigin(int64_t lTransactionNum)
void SetTransactionNum(int64_t lTransactionNum)
static EXPORT OTTransactionType * TransactionFactory(OTString strInput)
bool IsSameAccount(const OTTransactionType &rhs) const
EXPORT void GetNumList(OTNumList &theOutput)
void SetRealAccountID(const OTIdentifier &theID)
void SetRealServerID(const OTIdentifier &theID)
virtual bool SaveContractWallet(std::ofstream &ofs) const
virtual EXPORT int64_t GetNumberOfOrigin()
const OTIdentifier & GetRealAccountID() const
EXPORT void SetReferenceString(const OTString &theStr)
const OTIdentifier & GetPurportedServerID() const
OTIdentifier m_ID
Definition: OTContract.hpp:172
EXPORT int64_t GetReferenceToNum() const
void SetUserID(const OTIdentifier &theID)
const OTIdentifier & GetPurportedAccountID() const
virtual bool VerifyAccount(const OTPseudonym &theNym)
EXPORT int64_t GetTransactionNum() const
EXPORT void SetReferenceToNum(int64_t lTransactionNum)
void SetPurportedServerID(const OTIdentifier &theID)
virtual EXPORT bool VerifyContractID() const
const OTIdentifier & GetUserID() const
bool Contains(const OTString &strContains)
void SetPurportedAccountID(const OTIdentifier &theID)
const OTIdentifier & GetRealServerID() const
EXPORT bool VerifyNumberOfOrigin(OTTransactionType &compareTo)
EXPORT int64_t GetRawNumberOfOrigin() const