CLI.md (4105B)
1 # Tutorial - usawa CLI 2 3 All commands has a debug option on the `-v` flag. Valid values are `debug`, `info`, `warning` and `error`. Default is `warning` 4 5 Some commands prompt for passphrases. If an empty passphrase is given on wallet creation (i.e. just pressed "enter"), the `-p` flag is not necessary for consecutive commands. 6 7 8 ## Preparations 9 10 ### Accounts list 11 12 Accounts are ordered by units of account, account type and account path respectively. 13 14 There are five account types: 15 16 - Asset 17 - Liability 18 - Income 19 - Expense 20 - Equity 21 22 At this time, valid accounts are listed in a separate file, specifically mentioned by the configuration below. Although it is possible to use any account path with 23 24 25 ### Configuration 26 27 For this tutorial, we will use the fs backend for localstore and asset resolver. This means each entry and asset will be stored as individual files under a directory. 28 29 We create a configuration override to specify the fs backend: 30 31 ``` 32 configdir=$(realpath ./fsconfig) 33 storedir=$(realpath ./fsstore) 34 objdir=$(realpath ./fsobj) 35 mkdir -vp $configdir $storedir $objdir 36 cat <<EOF > $configdir/config.ini 37 [store] 38 type = fs 39 [fsstore] 40 base = $storedir 41 [fs_resolver] 42 store_path = $objdir 43 EOF 44 45 ``` 46 47 48 ## Creating signing key 49 50 To maintain ledgers and ledger entries, a signing key is required. 51 52 To create it: 53 54 ``` 55 # will prompt for a passphrase. 56 # creates new default key in the fs store 57 usawa-wallet -c fsconfig 58 ``` 59 60 61 ## Create new ledger 62 63 This will use the default key in the store. 64 65 ``` 66 # topic is an arbitrary value. 67 # units of account for the ledger are specified 68 usawa-create -c fsconfig -t myledger -u USD:2 -u BTC:9 -u EUR:2 -p > state.xml 69 ``` 70 71 ### Back up the initial ledger 72 73 The ledger first created has serial 0 and zero-value hash parent. This ledger state may be used later for example for commands listing transactions. 74 75 ``` 76 cp state.xml init.xml 77 ``` 78 79 80 ## Create a new ledger entry 81 82 This is an interactive tool, where a single ledger entry can be added to the ledger. 83 84 ``` 85 usawa-entry -c fsconfig -i init.xml 86 ``` 87 88 ### Entering data 89 90 For a new entry it will prompt for some information: 91 92 * Entry description (free text) 93 * Internal ref (a uuid string) 94 * External ref (optional) 95 * Date (and optionally time) of transaction. 96 97 After this phase, an interactive menu is presented. Menu options are single character strings. To see all available options in the menu, write `h` 98 99 The primary action in the interactive phase is to enter transaction deltas on each side of the ledger. `i` lets you add a "source" (or debit) account, `o` lets you add a "destination" (or credit) account. Each entry may have one or more transaction deltas. 100 101 **NOTE! The CLI tool will NOT enforce zero-sum between debit and credit. Also, the sums/balances displayed per entry do not work correctly yet** 102 103 104 ### Storing data 105 106 Once the entry has been completed, select `w` to commit the entry to the ledger. 107 108 "Commit" means: 109 110 * The entry is added to the local store. Any attempt at adding an additional entry with the same serial number to the store will fail. 111 * The ledger xml file is updated with the new serial number and entry digest, and a signature of the client private key is applied. 112 113 114 ## View the ledger entries 115 116 To view all entries in a ledger as a single XML document, from oldest to newest (serial numbers, incrementally): 117 118 ``` 119 usawa-view -c fsconfig -i init.xml 120 ``` 121 122 123 ## Export entry XML 124 125 Extract each entry into individual XML. 126 127 ``` 128 usawa-export -c fsconfig -i init.xml <target_dir> 129 ``` 130 131 Two versions will be generated per entry, one canonical *digest* XML that is used for the digest for the entry in the ledger chain. 132 133 The other is the canonical *full* XML, containing all other elements not part of the *digest* XML. 134 135 136 ## Interpreting the XML 137 138 ### Ledger 139 140 The ledger xml contains the serial number and digest of the last comitted entry. 141 142 The consecutive entry will have that digest as it's **parent** value, along with the *following* serial number. 143 144 145 ### Entry 146 147 The parent digest is the sha512 of the canonical *full* XML. 148 149 The signature is calculated over the correspinding canonical *digest* XML.