Hostované ledger teraz riešia zahrnutia spravovaných cien

Priznajme si to: vaše držby sú vo vašom ledgeri už dokonale zaznamenané. Sú to ceny, ktoré vás držia v nekonečnom cykle opakovaného prepisovania.

Táto asymetria je najstaršia a najfrustrujúcejšia povinnosť v plain-text účtovníctve. Nákup zapíšete raz a je navždy daný: 120 NWRB {41.80 USD, 2024-03-12} natrvalo uzamkne množstvo, náklad a dátum. Nič, čo sa stane potom, tieto fakty nezmení. Cena je však presný opak — je správna presne jeden deň a potom sa potichu stane nesprávnou. Horšie je, že je nesprávna spôsobom, ktorý žiadna kontrola zostatku nikdy nezachytí, pretože ledger so zastaranými cenami sa stále dokonale vyvažuje.

Historicky bol spôsob, ako to v Beancounte riešiť, získať ceny pomocou skriptu a uložiť výstup. Funguje to a mnohí si to zautomatizovali. Ale na konci dňa je to stále skript, ktorý musíte opatrovať, cron úloha, ktorú udržiavate, a súbor, ktorý neustále zlučujete.

Už nie. Pre ledgery hostované na beancount.io náš engine teraz rieši toto rozlíšenie natívne. Tento príspevok presne pokrýva, čo sme práve vydali, čoho sme sa zámerne nedotkli a — rovnako dôležité — čo sme ešte nepostavili.

Čo bolo vydané​

Hostovaný ledger na beancount.io teraz môže niesť direktívu include, ktorá ukazuje na URL adresu namiesto lokálneho názvu súboru:

; main.bean, in a hosted beancount.io ledger.
;
; This page is Slovak, so the quote currency is EUR. On another language of
; this site, use the currency in the list under the fence.
 
option "title" "Taxable brokerage"
option "operating_currency" "EUR"
 
; Only the hosted engine resolves the URL form, and upstream `include` takes a
; file glob — so the line is shown commented out here and this file still
; loads if you copy it to your own machine. Uncomment it in a hosted ledger.
; include "https://beancount.io/prices/AAPL-EUR"

Upozornenie: Pred navštívením tejto URL adresy sa musíte prihlásiť. Anonymné požiadavky sa presmerujú na prihlasovaciu stránku. Táto stránka je v slovenčine, takže príklad uvádza eurá — menu, v ktorej tu čitatelia najčastejšie vedú účtovníctvo. Po overení otvorte https://beancount.io/prices/AAPL-EUR a potvrďte, že vidíte štandardné direktívy price. Potom pridajte tento riadok do svojho hostovaného ledgera.

Ak čítate v inom jazyku, použite namiesto toho obvyklú menu daného jazyka, a to len vtedy, keď ju katalóg uvádza ako kotáciu:

• English: USD, https://beancount.io/prices/AAPL-USD
• 中文: CNY, https://beancount.io/prices/AAPL-CNY. Táto URL adresa nie je uvedený pár. Je to neupravená zatváracia cena AAPL-USD od Databento, skrížená s USD-CNY od ECB.
• 日本語: JPY, https://beancount.io/prices/AAPL-JPY
• 한국어: KRW, https://beancount.io/prices/AAPL-KRW
• Deutsch, Français, Español, Italiano, Nederlands, Català, Português, Slovenčina a Български: EUR, https://beancount.io/prices/AAPL-EUR. Bulharské účtovníctva otvorené tento rok sú v eurách; katalóg tiež uvádza BGN, ak ho starší súbor stále používa.
• فارسی, Русский a Українська: katalóg nemá IRR, RUB ani UAH, takže neexistuje žiadny pár na otvorenie. Vyberte kotáciu, ktorú uvádza.

Katalóg na https://beancount.io/prices/ sa nachádza za tým istým prihlásením. AAPL-USD je samotné priama kotácia od Databento, nie krížová. Ostatné akcie tier-1 fungujú rovnako — vymeňte ticker, ponechajte menu kotácie pre svoj jazyk. ACME-USD vráti 404.

include v upstream Beancounte technicky očakáva názov súboru, takže zahrnutie URL adresy je striktne správanie hostovaného enginu. Nikdy sa nepretvára na obyčajný Beancount. Tu je presne to, čo náš engine robí pod kapotou:

• Materializuje feed ako virtuálny súbor určený len na čítanie. URL adresa sa rozlíši cez vlastnú cestu rozlíšenia zahrnutí enginu — pristane presne tam, kde by pristál lokálny súbor — takže každá direktíva si zachová skutočné umiestnenie zdroja. Vaše pôvodné bajty sa nikdy neprepíšu. Súbor, ktorý ste napísali, zostáva súborom, ktorý ste napísali.
• Striktná validácia obsahu. Načítané telo sa validuje ako obsahujúce iba ceny. Striktne povoľujeme direktívy price, komentáre a štyri konkrétne kľúče metadát (price-source, price-kind, observed-at a provisional). Čokoľvek iné zamietne celé telo. Neexistuje čiastočné spracovanie, čo znamená, že nebezpečný feed nikdy nemôže prepašovať transakciu do vašich kníh.
• Inteligentné cachovanie. Feedy sa cachujú ako nemenná revízia s pohyblivým ukazovateľom. Cykly obnovenia sú riadené časovými značkami namiesto vypršania cache, čím sa zabezpečuje, že výpadok na strane zdroja nevymaže vašu poslednú dobrú revíziu.
• Auditovateľná aktuálnosť. Aktuálnosť sa vypočítava dynamicky pri čítaní ledgera (nedávna, zastaraná alebo nedostupná) spolu s časom pozorovania hláseným feedom. Cena, ktorú nedokážete datovať, je cena, ktorú nedokážete auditovať.
• Striktne len na čítanie. Spravované záznamy sa nedajú upravovať ani mazať (pokus o to vyhodí chybu s uvedením zdroja). Navyše sa nezapočítavajú do vašich limitov direktív — nedovoľujeme, aby feedy spotrebovali rozpočet vášho ledgera.

Nič z toho nemení to, čo cenová direktíva v Beancounte v zásade znamená. Jedinou úlohou enginu je postaviť pred zavádzač správne, datované a priraditeľné ceny.

Vaša vlastná cena vždy vyhráva​

Toto je kľúčová vec pre každého, kto berie svoj ledger vážne, takže buďme úplne jasní:

Pre rovnaký dátum a rovnaký páru komodít (vrátane jej recipročnej hodnoty) cena, ktorú ste napísali sami, vždy vyhráva nad spravovaným feedom.

Nie „zvyčajne“ a nie „len ak dáte svoje zahrnutie na koniec“. Toto rozhodnutie o zatienení sa vykonáva pred zostavením cenovej mapy, čo znamená, že je úplne nezávislé od toho, kde sa include nachádza vo vašom súbore. Dajte ho na začiatok, na koniec alebo ho rozdeľte do troch súborov — vaša ručne napísaná cena vždy vyhráva.

Recipročné pravidlo sa ľahko prehliadne, ale je kľúčové. Feed AAPL-USD je cena AAPL v USD. Ak ste ručne napísali cenu opačne — USD v AAPL, rovnaký dátum — váš záznam stále porazí feed. To isté platí pre akúkoľvek kotáciu, ktorú ste zahrnuli, vrátane CNY alebo JPY.

Prečo toto pravidlo? Pretože cena vo vašom vlastnom súbore je vedomé rozhodnutie. Môže to byť presná zatváracia cena, ktorú váš broker vytlačil na výpise, ktorý zosúlaďujete, aktuálna kotácia pre málo obchodované aktívum alebo konkrétna hodnota, ktorú požadoval váš účtovník. Feed nepozná váš kontext. Systém, ktorý potichu prepisuje človekom vytvorenú hodnotu, prestáva byť ledgerom a stáva sa názorom. Feed je tu na to, aby vypĺňal medzery; neopravuje vás.

Ceny ovplyvňujú ocenenie a nič iné​

Toto ďalšie upokojenie je skôr štrukturálne než politické rozhodnutie a najlepšie sa ukáže na skutočných číslach. Pozrite sa na náš príklad ledgera s kryptomenami, ktorý obsahuje datované loty, staking, DeFi pozície a airdropy:

Vytiahnime jeden konkrétny záznam. Airdrop governance tokenu príde a je zaznamenaný ako príjem v reálnej trhovej hodnote v deň, keď pristane:

2024-03-20 * "Uniswap" "Receive UNI governance token airdrop"
  Assets:Crypto:Wallet:MetaMask:UNI       50.00 UNI {12.50 USD, 2024-03-20}
  Income:Crypto:Airdrops                -625.00 USD
 

Tých 625,00 $ príjmu a základňa 12,50 $ za jednotku priradená k lotu sú teraz nemennými faktami o 2024-03-20. Každá cenová direktíva v ledgeri — či už spravovaná, ručne napísaná alebo úplne chýbajúca — necháva obe nedotknuté.

Ceny menia trhovú hodnotu; nikdy nemenia množstvá, nákladovú základňu, peňažné toky, poplatky ani realizované zisky. Presne preto je cenový feed bezpečný nástroj, o ktorý sa môžete oprieť: to absolútne najhoršie, čo môže zlá cena spôsobiť, je dočasne nesprávne uviesť, akú hodnotu má pozícia dnes. Nikdy nemôže poškodiť tvrdé čísla, ktoré dáte do svojho daňového priznania.

Kde vás nesprávny cenový model skutočne zvádza na scestie​

Príklad ledgera s akciami a ETF ilustruje ostrejšiu verziu presne tohto bodu:

Obsahuje rozdelenie akcií 4-za-1, zaznamenané správnym spôsobom — ako zmenu množstva, ktorá zachováva celkovú základňu bez dotknutia akýchkoľvek príjmových účtov:

2025-07-15 * "Broker" "NWRB 4-for-1 share split — quantity change, not income"
  Assets:Brokerage:NWRB                   -120 NWRB {41.80 USD, 2024-03-12}
  Assets:Brokerage:NWRB                    480 NWRB {10.45 USD, 2024-03-12}
 

Obe strany sa rovnajú 5 016,00 $. Trhová hodnota zostáva počas rozdelenia nezmenená (7 440,00 $ v oboch prípadoch) a dátum nadobudnutia v zátvorkách prežíva — čo je to, čo udržiava predaj týchto akcií v roku 2026 klasifikovaný ako dlhodobý.

Častou pascou je zaznamenať rozdelenie ako cenovú udalosť a silne sa oprieť o „na rozdelenie upravený“ cenový rad, aby matematika vyšla. To funguje len dovtedy, kým každá cena, na ktorú sa kedy pozriete, bola upravená presne rovnakým spôsobom. Vo chvíli, keď sa do vášho ledgera dostane neupravené číslo — starý potvrdzujúci doklad, snímka obrazovky alebo feed tretej strany, ktorý neprepočítava historické údaje — pozícia sa zrazu ocení na štvornásobok svojej skutočnej hodnoty. Horšie je, že počet akcií v ledgeri už nezodpovedá výpisu vášho brokera, čo znamená, že vaše kontroly zostatku na konci roka potichu zlyhajú.

Toto je skutočný argument pre spoľahnutie sa na cenový feed s deklarovaným zdrojom, deklarovaným druhom a viditeľným časom pozorovania. Nejde len o pohodlie; ide o to vedieť presne, akú matematickú konvenciu vaše importované čísla používajú.

(Krátka poznámka k vloženiam: prehliadač hostovaného ledgera vykresľuje zostatky účtov v nákladoch a momentálne neponúka ovládacie prvky ocenenia priamo na stránke. Vyššie uvedené ledgery majú predviesť základnú mechaniku — loty, rozdelenie, predaje. Oba sú verejné a môžete si ich naklonovať a spustiť lokálne.)

Čo tu ešte nie je​

Veríme, že changelog je horší ako zbytočný, ak sľubuje príliš veľa. Takže tu je neprikrášlená pravda o tom, čo sme ešte nepostavili, bez uvedených termínov:

• Autentifikácia je povinná. Anonymné požiadavky na https://beancount.io/prices/<ALIAS> vás presmerujú na prihlasovaciu stránku.
• Žiadna podpora lokálneho CLI. Lokálne CLI bea číta súbory z disku, čo znamená, že zahrnutie URL adresy lokálne zlyhá ako nezhodný glob súborov. Pridanie podpory zavádzača do CLI je v našom pláne.
• Žiadne API rozhranie. Momentálne nemáme pole REST, GraphQL ani MCP pre spravované ceny.
• Žiadny UI dashboard. Zatiaľ neexistuje obrazovka „pripojiť-feed“ ani označenie aktuálnosti v UI. (Údaje o aktuálnosti, ktoré náš engine vypočítava, momentálne nemajú kde byť zobrazené).
• Žiadne snímky, exporty ani koncové body manuálneho obnovenia.

To, čo sme dnes vydali, je striktne vrstva enginu: rozlíšenie zahrnutí, validácia, cachovanie revízií, pravidlá priority a výpočet aktuálnosti. Je to základná infraštruktúra, na ktorej musí stáť všetko ostatné, a presne preto sme ju postavili ako prvú.

Kam sa pozrieť ďalej​

Oba vyššie vložené ledgery sú súčasťou našej galérie príkladov — šesť plne vypracovaných vzorov, ktoré si môžete naklonovať a spustiť lokálne. (Oba zámerne dodávame so statickými, do repozitára uloženými cenovými súbormi, čím sa zabezpečuje, že klon vytvorený o dva roky vygeneruje presne ten istý report ako dnes). Všetko ostatné, čo vydáme, sa objaví priamo v našom changelogu.

Ak ste úplne spokojní s udržiavaním cien aktuálnych pomocou vlastného sťahovača, zostaňte pri ňom. Stále je to najlepšia odpoveď pre striktne lokálny ledger. Samotná dokumentácia Beancountu o sťahovaní cien a udržiavaný nástroj beanprice sú najlepšími miestami, kde začať.

Nechajte nudnú časť nudnou​

Ceny sa oplatí automatizovať práve preto, že sú jedinou časťou plain-text ledgera, ktorá časom hnije. Beancount.io je postavený tak, aby vám dalo plain-text účtovníctvo, ktoré zostáva vaše — auditovateľné, pod verzionálnou kontrolou a nikdy prepísané za vašimi chrbtami. To bol základný štandard, ktorý musel spravovaný feed spĺňať, kým sme boli ochotní ho vydať.

Začnite zadarmo a vedte svoje knihy v súboroch, ktoré skutočne dokážete prečítať.