README (10501B)
1 # Usawa 2 3 A local-first, authenticated and immutable accounting schema for individuals and small businesses. 4 5 This readme will only guide you to run some example commands, without giving you much insight. 6 7 Please refer to the documentation in `doc/`. If is vanilla [GNU Texinfo](https://www.gnu.org/software/texinfo/), and can easily be built with: 8 9 ``` 10 cd doc/ 11 makeinfo --html index.texi 12 ``` 13 14 The HTML entry point for local browsing will be in `doc/index_html/index.html` 15 16 17 ## Dependencies 18 19 OS dependencies upon which python dependencies rely: 20 21 * [libsodium](https://libsodium.net/) 22 * [valkey](https://valkey.io/) (server running) 23 24 Note that `valkey` is implemented for the POC, but even this POC library allows for any key-value store that satisfies the [whee](https://pypi.org/project/wheepy/) interface. 25 26 ## Build 27 28 ``` 29 git submodule update --init 30 python -mvenv .venv 31 . .venv/bin/activate 32 cd dummy 33 pip install . 34 ``` 35 36 You can verify the setup by running the tests: 37 38 `find tests/ -iname "*.py" -exec python {} \;` 39 40 41 ## Trying out the tools 42 43 44 ### Creating a ledger 45 46 The topic may be any value, and will be stored under its digest. Prefix with `0x` to define a literal hexadecimal value. 47 48 `python usawa/runnable/create.py -t <sometopic> -o start.xml` 49 50 Once completed, the contents of `start.xml` will be something like this: 51 52 53 ``` 54 <?xml version="1.0"?> 55 <ledger xmlns="http://usawa.defalsify.org/" version="1"> 56 <topic xmlns:ns="http://usawa.defalsify.org/">7092e69f8179a45f673f8e4b85cf7de2a09d5f3e43f801fd2c1a47c6dcd9f14a0137c7a1244e7e625057850f3e0c4132bbd23877c2ede5f49f12e646bb5cca7b</topic> 57 <generated xmlns:ns="http://usawa.defalsify.org/">2026-01-19T18:19:57Z</generated> 58 <src xmlns:ns="http://usawa.defalsify.org/"/> 59 <units xmlns:ns="http://usawa.defalsify.org/" base="BTC"> 60 <unit sym="BTC"> 61 <precision>2</precision> 62 <exchange>1000000000</exchange> 63 </unit> 64 </units> 65 <identity xmlns:ns="http://usawa.defalsify.org/" keyid="3b54648d60bb8a5b9e84fa0057f79b3a5996e511682e80176dc948dcbff5a4fc" didtype="usawa"/> 66 <incoming xmlns:ns="http://usawa.defalsify.org/" serial="0"> 67 <real unit="BTC"> 68 <asset>0</asset> 69 <liability>0</liability> 70 </real> 71 <digest algo="sha512">00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000</digest> 72 <sig keyid="3b54648d60bb8a5b9e84fa0057f79b3a5996e511682e80176dc948dcbff5a4fc" type="ed25519">3615f40538a11d625400ac0195f803c68c7b53b93f095753dcca93c5eb2851004c2b28ca067fd6bd298e73ebe1fa02eb1392e0ff83c87a5c421516951c33c30b</sig> 73 </incoming> 74 </ledger> 75 ``` 76 77 78 ### Adding a ledger entry 79 80 Using the initial state of the ledger, the `add.py` tool can be used to interactively specify a new entry in the ledger. 81 82 `python usawa/runnable/add.py -i start.xml -o first.xml` 83 84 If correctly specified, this will store an entry in the `valkey` database, and output the new _truncated state_ (digest and serial set to last added entry) of the ledger to `first.xml`. 85 86 Another entry may be added using the new _truncated state_: 87 88 `python usawa/runnable/add.py -i first.xml -o second.xml` 89 90 ... and so on. 91 92 93 ### Viewing the ledger 94 95 An XML representation of the ledger and its entries may be generated using the corresponding ledger state. 96 97 Using states from the precending examples: 98 99 ``` 100 # Will output the zero-state ledger header, aswell as two entries 101 python usawa/runnable/view.py start.xml 102 # Will output the ledger header after the first entry, aswell as one entry. 103 python usawa/runnable/view.py first.xml 104 # Will output the ledger header after the second entry with no entries. 105 python usawa/runnable/view.py second.xml 106 ``` 107 108 Example output of the first command: 109 110 ``` 111 <?xml version="1.0"?> 112 <ledger xmlns="http://usawa.defalsify.org/" version="1"> 113 <topic xmlns:ns="http://usawa.defalsify.org/">24448167713e4f7d7e09fd06716b17ffcbd8bd10aa2ebbaac0a0902292993a86244acb9683c7dc45500daf1193a760b87de6fadd0f7b30c1a7b63ac06c555ca8</topic> 114 <generated xmlns:ns="http://usawa.defalsify.org/">2026-01-20T09:30:34Z</generated> 115 <src xmlns:ns="http://usawa.defalsify.org/">defalsify.org</src> 116 <units xmlns:ns="http://usawa.defalsify.org/" base="BTC"> 117 <unit sym="BTC"> 118 <precision>2</precision> 119 <exchange>1000000000</exchange> 120 </unit> 121 </units> 122 <identity xmlns:ns="http://usawa.defalsify.org/" keyid="3b54648d60bb8a5b9e84fa0057f79b3a5996e511682e80176dc948dcbff5a4fc" didtype="usawa"/> 123 <incoming xmlns:ns="http://usawa.defalsify.org/" serial="0"> 124 <real unit="BTC"> 125 <asset>0</asset> 126 <liability>0</liability> 127 </real> 128 <digest algo="sha512">00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000</digest> 129 </incoming> 130 <entry> 131 <data> 132 <parent>00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000</parent> 133 <ref>2ae1dae8-8071-4a40-983d-e25f80634d6b</ref> 134 <serial>1</serial> 135 <date>2026-01-20</date> 136 <dateTimeRegistered>2026-01-20T09:29:28Z</dateTimeRegistered> 137 <description>awergaergh</description> 138 <debit type="expense"> 139 <unit>BTC</unit> 140 <account>general</account> 141 <amount>-2346300</amount> 142 </debit> 143 <credit type="asset"> 144 <unit>BTC</unit> 145 <account>general</account> 146 <amount>2346300</amount> 147 </credit> 148 </data> 149 <sig type="ed25519" keyid="3b54648d60bb8a5b9e84fa0057f79b3a5996e511682e80176dc948dcbff5a4fc">0a0bec86152bd411dff6d7569778305f30bf52dd03c060992d8bfd1f3432fe27cf3acd17d8019a0e5e3fe0c038664c478b1576fed027f3902bb32b56b05fd708</sig> 150 </entry> 151 <entry> 152 <data> 153 <parent>50740013c78726ddd4fd199bbe21ad3eb3c50dcfd3540e12c5b52151a9b9f3a41346a22a2d1928dfc5749faac332a8c15ff2f545e8ff92b07aa037c39b1ba93e</parent> 154 <ref>182536c7-f2ce-4976-af2a-6b0d2cf10e0c</ref> 155 <serial>2</serial> 156 <date>2026-01-20</date> 157 <dateTimeRegistered>2026-01-20T09:29:40Z</dateTimeRegistered> 158 <description>wergagh</description> 159 <debit type="expense"> 160 <unit>BTC</unit> 161 <account>general</account> 162 <amount>-1251613262700</amount> 163 </debit> 164 <credit type="asset"> 165 <unit>BTC</unit> 166 <account>general</account> 167 <amount>1251613262700</amount> 168 </credit> 169 </data> 170 <sig type="ed25519" keyid="3b54648d60bb8a5b9e84fa0057f79b3a5996e511682e80176dc948dcbff5a4fc">603bf1bf05951f1c78e3ba9ab430e914f73f03b6570c15cb241695393e57eb178029ba1ff0f86afa5f29ea10ea49418825e387feb8d03f79280593e4598b1b0d</sig> 171 </entry> 172 </ledger> 173 ``` 174 175 Sample output of second command: 176 177 ``` 178 <?xml version="1.0"?> 179 <ledger xmlns="http://usawa.defalsify.org/" version="1"> 180 <topic xmlns:ns="http://usawa.defalsify.org/">24448167713e4f7d7e09fd06716b17ffcbd8bd10aa2ebbaac0a0902292993a86244acb9683c7dc45500daf1193a760b87de6fadd0f7b30c1a7b63ac06c555ca8</topic> 181 <generated xmlns:ns="http://usawa.defalsify.org/">2026-01-20T09:32:09Z</generated> 182 <src xmlns:ns="http://usawa.defalsify.org/">defalsify.org</src> 183 <units xmlns:ns="http://usawa.defalsify.org/" base="BTC"> 184 <unit sym="BTC"> 185 <precision>2</precision> 186 <exchange>1000000000</exchange> 187 </unit> 188 </units> 189 <identity xmlns:ns="http://usawa.defalsify.org/" keyid="3b54648d60bb8a5b9e84fa0057f79b3a5996e511682e80176dc948dcbff5a4fc" didtype="usawa"/> 190 <incoming xmlns:ns="http://usawa.defalsify.org/" serial="1"> 191 <real unit="BTC"> 192 <asset>2346300</asset> 193 <liability>0</liability> 194 </real> 195 <digest algo="sha512">50740013c78726ddd4fd199bbe21ad3eb3c50dcfd3540e12c5b52151a9b9f3a41346a22a2d1928dfc5749faac332a8c15ff2f545e8ff92b07aa037c39b1ba93e</digest> 196 </incoming> 197 <entry> 198 <data> 199 <parent>50740013c78726ddd4fd199bbe21ad3eb3c50dcfd3540e12c5b52151a9b9f3a41346a22a2d1928dfc5749faac332a8c15ff2f545e8ff92b07aa037c39b1ba93e</parent> 200 <ref>182536c7-f2ce-4976-af2a-6b0d2cf10e0c</ref> 201 <serial>2</serial> 202 <date>2026-01-20</date> 203 <dateTimeRegistered>2026-01-20T09:29:40Z</dateTimeRegistered> 204 <description>wergagh</description> 205 <debit type="expense"> 206 <unit>BTC</unit> 207 <account>general</account> 208 <amount>-1251613262700</amount> 209 </debit> 210 <credit type="asset"> 211 <unit>BTC</unit> 212 <account>general</account> 213 <amount>1251613262700</amount> 214 </credit> 215 </data> 216 <sig type="ed25519" keyid="3b54648d60bb8a5b9e84fa0057f79b3a5996e511682e80176dc948dcbff5a4fc">603bf1bf05951f1c78e3ba9ab430e914f73f03b6570c15cb241695393e57eb178029ba1ff0f86afa5f29ea10ea49418825e387feb8d03f79280593e4598b1b0d</sig> 217 </entry> 218 </ledger> 219 ``` 220 221 Sample output of third command: 222 223 ``` 224 <?xml version="1.0"?> 225 <ledger xmlns="http://usawa.defalsify.org/" version="1"> 226 <topic xmlns:ns="http://usawa.defalsify.org/">24448167713e4f7d7e09fd06716b17ffcbd8bd10aa2ebbaac0a0902292993a86244acb9683c7dc45500daf1193a760b87de6fadd0f7b30c1a7b63ac06c555ca8</topic> 227 <generated xmlns:ns="http://usawa.defalsify.org/">2026-01-20T09:34:49Z</generated> 228 <src xmlns:ns="http://usawa.defalsify.org/">defalsify.org</src> 229 <units xmlns:ns="http://usawa.defalsify.org/" base="BTC"> 230 <unit sym="BTC"> 231 <precision>2</precision> 232 <exchange>1000000000</exchange> 233 </unit> 234 </units> 235 <identity xmlns:ns="http://usawa.defalsify.org/" keyid="3b54648d60bb8a5b9e84fa0057f79b3a5996e511682e80176dc948dcbff5a4fc" didtype="usawa"/> 236 <incoming xmlns:ns="http://usawa.defalsify.org/" serial="2"> 237 <real unit="BTC"> 238 <asset>1251613262700</asset> 239 <liability>0</liability> 240 </real> 241 <digest algo="sha512">aaaf17ff1a5866b1e43746686cd3029a5d0a08178986b3eccd8f94ad6f5e3076160f8bfb67ba2ee8c0e68fcec6f8bf3f2da2e61ef96cd5c11c0cef8043dde4df</digest> 242 </incoming> 243 </ledger> 244 ``` 245 246 247 ## State of development 248 249 This software is to be considered proof-of-concept and not safe for use in production in any way. 250 251 Shortcomings include: 252 253 * Media assets and attachments are not yet implemented. 254 * No PKI functions are available to manage public key lists. 255 * A single, unencrypted private key entry in the key-value store is used for signatures. 256 257 258 ## Legals 259 260 Copyright 2026 by Louis Holbrook, all rights reserved. 261 262 All software licensed under [GNU Affero General Public License 3.0](https://www.gnu.org/licenses/agpl-3.0.en.html). 263 264 All documentation licensed under [Creative Commons Attribution-Sharealike 4.0 International](https://creativecommons.org/licenses/by-sa/4.0/).