internals.texi (7921B)
1 @chapter Internals 2 3 4 @section Serialization for signature 5 6 Object XML representations are used to generate signature material. The XML is canonicalized using the @url{https://www.w3.org/TR/xml-c14n2/,C14N 2.0 standard}, and all unnecessary whitespace is removed. 7 8 Signatures are calculated and embedded on three elements individually, while at the same time having a hierarchical relation. Some data is omitted from the full XML representation. 9 10 The following describes any transformation applied to the XML. Also, any @code{sig} elements are removed before . 11 12 13 @anchor{serialize_attachment} 14 @subsection Attachment 15 16 Before canonicalization, the entry attachment element is reduced to contents that can be recreated with only the actual file data available: 17 18 @itemize 19 @item The @code{mime} attribute. 20 @item The @code{digest} element. 21 @end itemize 22 23 24 @subsection Entry 25 26 Contains zero or more @strong{Attachment} elements, as specified @ref{serialize_attachment,above}. 27 28 Otherwise, used in its entirety. 29 30 31 @subsection Ledger 32 33 Before signing, the last known entry is applied to the ledger state, and all entry elements are removed. 34 35 The @code{digest} sub-element and @code{serial} attribute of the @code{ledger/incoming} element is set accordingly. @xref{ledger_trunc_header,Truncated header}. 36 37 Thus, the XML used to calculate the ledger state signature material is the @code{ledger} element @emph{without} any @code{entry} elements. 38 39 40 @section Serialization for cache store 41 42 This serialization is used as compact representation of the data in the cache store. 43 44 Serialization uses the rencode format, and all individual elements are elements in a list. 45 46 The lookup key descriptions below are enumerated. Each element in the list should be concatenated in order, without intermediate data. 47 48 Any optional and undefined elements @emph{must} contain a @emph{null value} in the serialization. 49 50 Where expendient, @url{https://dwarfstd.org/doc/Dwarf3.pdf,LEB128s} encoding is used for variable-length integer encoding. 51 52 @xref{store,Cache store} for more details. 53 54 @subsection Ledger 55 56 The lookup key for the ledger cache item is: 57 58 @enumerate 59 @item @code{0x01} 60 @item The literal bytes of the @emph{ledger topic} 61 @end enumerate 62 63 The list elements for the value are generated as follows: 64 65 @enumerate 66 @item @strong{topic}, literal bytes. 67 @item The current state @strong{serial}, LEB128s encoded. 68 @item The current state @strong{digest}, 64 bytes (sha512). 69 @item @strong{timestamp} as big endian 32-bit value. 70 @item Serialization of the @strong{Unit Index}. 71 @item Serialization of the @strong{Access Control List}. 72 @item Serialization of the @strong{Running Total}. 73 @end enumerate 74 75 76 @anchor{serialize_entry} 77 @subsection Entry 78 79 The lookup key for the entry cache item is: 80 81 @enumerate 82 @item @code{0x04} 83 @item The literal bytes of the @emph{ledger topic}. 84 @item The entry @strong{serial}, LEB128s encoded. 85 @end enumerate 86 87 The list elements for the value are generated as follows: 88 89 @enumerate 90 @item @strong{parent}, literal bytes of the preceding entry digest (or zero-value if it is the first entry). 91 @item The @strong{serial} number of the entry. 92 @item The @strong{local reference} of the entry, by default a @emph{uuid string}. 93 @item The @strong{datetime} the entry was @emph{registered} (i.e. signed into) the ldger. 94 @item The @strong{date} or @strong{datetime} of the transaction. @xref{entry_timing,Timing in ledger entries}. 95 @item Serializations of the @emph{entry parts} of the @strong{debits}, one or more. @xref{serialize_entry_part,Entry part serialization}. 96 @item Serializations of the @emph{entry parts} of the @strong{credits}, one or more. @xref{serialize_entry_part,Entry part serialization}. 97 @item The @emph{digest} from each of the @strong{attachments}, zero or more. 98 @end enumerate 99 100 101 @anchor{serialize_entry_part} 102 @subsubsection Entry parts 103 104 Entry parts are @strong{debit} and @strong{credit} items. 105 106 These are individually @emph{rencode serialized} before embedded in the @ref{serialize_entry,Entry serialization}. They do not have their own lookup key. 107 108 The list elements for both have identical structure, and are generated as follows: 109 110 @enumerate 111 @item The @ref{unit_index,account unit symbol}. 112 @item The @ref{account_type,account type}. 113 @item The @ref{account_path,account path}. 114 @item The @ref{account_value,value of the item}. 115 @end enumerate 116 117 118 @anchor{serialize_asset} 119 @subsection Entry attachment assets 120 121 The lookup key for the entry cache item is: 122 123 @enumerate 124 @item @code{0x10} 125 @item The literal bytes of the @emph{asset digest}. 126 @end enumerate 127 128 The list elements for the value are generated as follows: 129 130 @enumerate 131 @item The @strong{mime type} string (required). 132 @item The @strong{mime encoding / charset} string (required, if it has been defined). 133 @item The @strong{uuid}. 134 @item The @strong{external reference}. 135 @item The @strong{slug} (the filename stem). 136 @item The @strong{file extension}. 137 @item The @strong{description}. 138 @end enumerate 139 140 All elements are optional unless otherwise marked. 141 142 The file data is never stored in the cache store. File content for a @emph{digest} should be retrieved consulting @ref{resolver,resolvers} and @ref{method,lookup methods}. 143 144 145 @subsection Unit Index 146 147 A collection of units of account, defining their value precision level aswell as exchange rates. 148 149 Serialization uses the rencode format, and all individual elements are elements in a list. 150 151 The unit index cache items have a number of lookup key variations, all of which have the prefix @code{0x08}. 152 153 The values format for each variation differs. 154 155 @anchor{baseunit} 156 @subsubsection Base unit 157 158 Defines the base unit used for the ledger. 159 160 Lookup key: 161 162 @enumerate 163 @item @code{0x08} 164 @item The @emph{legder index} @strong{reference number}. 165 @end enumerate 166 167 The value is the @emph{UTF-8 encoded} @strong{base symbol name}. 168 169 170 @anchor{ledgerunit} 171 @subsubsection Ledger unit 172 173 Defines the default metadata for a unit. 174 175 Lookup key: 176 177 @enumerate 178 @item @code{0x08} 179 @item The @emph{legder index} @strong{reference number}. 180 @item The unit index symbol, as stored in the @emph{baseunit,Base Unit} item. 181 @end enumerate 182 183 Value: 184 185 @enumerate 186 @item Type of unit. @xref{realvirt,Real vs virtual}. 187 @item Precision, as a single-byte numeric value. 188 @item Exchange rate vs base unit, @emph{LEB128s encoded integer}. @xref{data_unit_index,Unit Index data structure}. 189 @end enumerate 190 191 The exchange rate defined in this item is the default exchange rate, and/or the exchange rate at the moment of ledger creation (before the first entry). 192 193 194 @subsubsection Ledger unit momentary exchange rate 195 196 Defines the exchange rate for a unit at a specific moment in time. 197 198 Lookup key: 199 200 @enumerate 201 @item @code{0x08} 202 @item The @emph{legder index} @strong{reference number}. 203 @item The unit index symbol, as stored in the @emph{baseunit,Base Unit} item. 204 @item The @strong{datetime} of the exchange rate snapshot as a @emph{32-bit big-endian numeric value}. 205 @end enumerate 206 207 The value is the @emph{LEB128s encoded integer} of the exchange rate. @xref{data_unit_index,Unit Index data structure}, as used in @ref{ledgerunit,Ledger unit} above. 208 209 210 211 @subsection Access Control List 212 213 (TODO: rename) 214 215 Defines known public keys and what each key can be trusted to sign for. 216 217 The list elements are themselves lists, the latter generated as follows: 218 219 @enumerate 220 @item Public key, literal, hex-encoded. 221 @item The persmissions bitflag array, currently 4 bytes. literal. 222 @end enumerate 223 224 225 226 @subsection Running Total 227 228 Keeps the state of accounts for each used unit. 229 230 The list elements are generated as follows: 231 232 @enumerate 233 @item The unit symbol the running totla is kept for. 234 @item The income account balance, positive or negative, LEB128s encoded. 235 @item The expense account balance, positive or negative, LEB128s encoded. 236 @item The asset account balance, positive or negative, LEB128s encoded. 237 @item The liability account balance, positive or negative, LEB128s encoded. 238 @end enumerate