ledgdex 1.0.20__tar.gz

ledgdex-1.0.20/LICENSE

@@ -0,0 +1,121 @@
+Creative Commons Legal Code
+
+CC0 1.0 Universal
+
+    CREATIVE COMMONS CORPORATION IS NOT A LAW FIRM AND DOES NOT PROVIDE
+    LEGAL SERVICES. DISTRIBUTION OF THIS DOCUMENT DOES NOT CREATE AN
+    ATTORNEY-CLIENT RELATIONSHIP. CREATIVE COMMONS PROVIDES THIS
+    INFORMATION ON AN "AS-IS" BASIS. CREATIVE COMMONS MAKES NO WARRANTIES
+    REGARDING THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS
+    PROVIDED HEREUNDER, AND DISCLAIMS LIABILITY FOR DAMAGES RESULTING FROM
+    THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS PROVIDED
+    HEREUNDER.
+
+Statement of Purpose
+
+The laws of most jurisdictions throughout the world automatically confer
+exclusive Copyright and Related Rights (defined below) upon the creator
+and subsequent owner(s) (each and all, an "owner") of an original work of
+authorship and/or a database (each, a "Work").
+
+Certain owners wish to permanently relinquish those rights to a Work for
+the purpose of contributing to a commons of creative, cultural and
+scientific works ("Commons") that the public can reliably and without fear
+of later claims of infringement build upon, modify, incorporate in other
+works, reuse and redistribute as freely as possible in any form whatsoever
+and for any purposes, including without limitation commercial purposes.
+These owners may contribute to the Commons to promote the ideal of a free
+culture and the further production of creative, cultural and scientific
+works, or to gain reputation or greater distribution for their Work in
+part through the use and efforts of others.
+
+For these and/or other purposes and motivations, and without any
+expectation of additional consideration or compensation, the person
+associating CC0 with a Work (the "Affirmer"), to the extent that he or she
+is an owner of Copyright and Related Rights in the Work, voluntarily
+elects to apply CC0 to the Work and publicly distribute the Work under its
+terms, with knowledge of his or her Copyright and Related Rights in the
+Work and the meaning and intended legal effect of CC0 on those rights.
+
+1. Copyright and Related Rights. A Work made available under CC0 may be
+protected by copyright and related or neighboring rights ("Copyright and
+Related Rights"). Copyright and Related Rights include, but are not
+limited to, the following:
+
+  i. the right to reproduce, adapt, distribute, perform, display,
+     communicate, and translate a Work;
+ ii. moral rights retained by the original author(s) and/or performer(s);
+iii. publicity and privacy rights pertaining to a person's image or
+     likeness depicted in a Work;
+ iv. rights protecting against unfair competition in regards to a Work,
+     subject to the limitations in paragraph 4(a), below;
+  v. rights protecting the extraction, dissemination, use and reuse of data
+     in a Work;
+ vi. database rights (such as those arising under Directive 96/9/EC of the
+     European Parliament and of the Council of 11 March 1996 on the legal
+     protection of databases, and under any national implementation
+     thereof, including any amended or successor version of such
+     directive); and
+vii. other similar, equivalent or corresponding rights throughout the
+     world based on applicable law or treaty, and any national
+     implementations thereof.
+
+2. Waiver. To the greatest extent permitted by, but not in contravention
+of, applicable law, Affirmer hereby overtly, fully, permanently,
+irrevocably and unconditionally waives, abandons, and surrenders all of
+Affirmer's Copyright and Related Rights and associated claims and causes
+of action, whether now known or unknown (including existing as well as
+future claims and causes of action), in the Work (i) in all territories
+worldwide, (ii) for the maximum duration provided by applicable law or
+treaty (including future time extensions), (iii) in any current or future
+medium and for any number of copies, and (iv) for any purpose whatsoever,
+including without limitation commercial, advertising or promotional
+purposes (the "Waiver"). Affirmer makes the Waiver for the benefit of each
+member of the public at large and to the detriment of Affirmer's heirs and
+successors, fully intending that such Waiver shall not be subject to
+revocation, rescission, cancellation, termination, or any other legal or
+equitable action to disrupt the quiet enjoyment of the Work by the public
+as contemplated by Affirmer's express Statement of Purpose.
+
+3. Public License Fallback. Should any part of the Waiver for any reason
+be judged legally invalid or ineffective under applicable law, then the
+Waiver shall be preserved to the maximum extent permitted taking into
+account Affirmer's express Statement of Purpose. In addition, to the
+extent the Waiver is so judged Affirmer hereby grants to each affected
+person a royalty-free, non transferable, non sublicensable, non exclusive,
+irrevocable and unconditional license to exercise Affirmer's Copyright and
+Related Rights in the Work (i) in all territories worldwide, (ii) for the
+maximum duration provided by applicable law or treaty (including future
+time extensions), (iii) in any current or future medium and for any number
+of copies, and (iv) for any purpose whatsoever, including without
+limitation commercial, advertising or promotional purposes (the
+"License"). The License shall be deemed effective as of the date CC0 was
+applied by Affirmer to the Work. Should any part of the License for any
+reason be judged legally invalid or ineffective under applicable law, such
+partial invalidity or ineffectiveness shall not invalidate the remainder
+of the License, and in such case Affirmer hereby affirms that he or she
+will not (i) exercise any of his or her remaining Copyright and Related
+Rights in the Work or (ii) assert any associated claims and causes of
+action with respect to the Work, in either case contrary to Affirmer's
+express Statement of Purpose.
+
+4. Limitations and Disclaimers.
+
+ a. No trademark or patent rights held by Affirmer are waived, abandoned,
+    surrendered, licensed or otherwise affected by this document.
+ b. Affirmer offers the Work as-is and makes no representations or
+    warranties of any kind concerning the Work, express, implied,
+    statutory or otherwise, including without limitation warranties of
+    title, merchantability, fitness for a particular purpose, non
+    infringement, or the absence of latent or other defects, accuracy, or
+    the present or absence of errors, whether or not discoverable, all to
+    the greatest extent permissible under applicable law.
+ c. Affirmer disclaims responsibility for clearing rights of other persons
+    that may apply to the Work or any use thereof, including without
+    limitation any person's Copyright and Related Rights in the Work.
+    Further, Affirmer disclaims responsibility for obtaining any necessary
+    consents, permissions or other rights required for any use of the
+    Work.
+ d. Affirmer understands and acknowledges that Creative Commons is not a
+    party to this document and has no duty or obligation with respect to
+    this CC0 or use of the Work.

ledgdex-1.0.20/MANIFEST.in

@@ -0,0 +1,8 @@
+# The source package (sdist) holds only what "python run_tests.py" needs. The wheel holds only py/ledgdex.
+include README.md LICENSE run_tests.py
+recursive-include py/tests *.py *.mjs
+recursive-include vectors *
+recursive-include js *.js *.mjs *.json
+recursive-include guide/examples *
+include guide/tutorial.md guide/dex/ledgdex.jsonl
+global-exclude __pycache__ *.pyc

ledgdex-1.0.20/PKG-INFO

@@ -0,0 +1,254 @@
+Metadata-Version: 2.4
+Name: ledgdex
+Version: 1.0.20
+Summary: Simple market on a dex: signed, append-only ledgers with triple-entry accounting
+Author: Noorul Ali
+License: CC0-1.0
+Project-URL: Homepage, https://ledgdex.github.io
+Project-URL: Documentation, https://ledgdex.github.io/docs/
+Project-URL: Source, https://github.com/ledgdex/ledgdex
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: CC0 1.0 Universal (CC0 1.0) Public Domain Dedication
+Classifier: Operating System :: OS Independent
+Classifier: Environment :: Console
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: dexweb<5,>=4.2.5
+Provides-Extra: fast
+Requires-Dist: cryptography>=42; extra == "fast"
+Dynamic: license-file
+
+# Ledgdex
+
+A simple market on a dex. Every seller and buyer keeps a signed, append-only ledger (`ledgdex.jsonl`) in their own dex, a freely shared website built with [dexweb](https://github.com/matrixdex/dexweb). A trade exists three times: the buyer's signed claim, the seller's signed record of it, and the buyer's copy of that record. No server, no blockchain: SHA-256, Ed25519 and plain files.
+
+**Site: https://ledgdex.github.io** (viewer and live markets). **Docs: https://ledgdex.github.io/docs/** (getting started, setting up a marketplace, extending ledgdex, bots, the command line and API references, and tested examples). The docs are a dex built with dexweb, and a ledgdex too: dex is the core; dex + ledger is a ledgdex. Their source is [guide/](guide/).
+
+The specification is [architecture/SPEC.md](architecture/SPEC.md). Everything in it is built: the market (offers, claims, payment, delivery, receipts), disputes, sealed-bid auctions, device keys, key rotation and recovery, indexes, the root, dex pages, publishing and tamper checks, in Python, plus a JavaScript version and a browser viewer.
+
+## Install
+
+```
+pip install "ledgdex[fast]"
+```
+
+From the source on GitHub: `pip install "ledgdex[fast] @ git+https://github.com/ledgdex/ledgdex@v1.0.20"`. From a clone,
+to work on ledgdex: `pip install -e ".[fast]"`. Releases before 1.0.20 are on GitHub only, as tags; add
+`#subdirectory=py` to their address.
+
+Python 3.8 or later. The only dependency is dexweb (4.2.5 or later, before 5). Private keys live in `~/.ledgdex` (or `$LEDGDEX_HOME`), never in a dex, with mode 600: ledgdex refuses a key file others can read.
+
+The `fast` extra adds the `cryptography` package: signing and verifying get about 20 to 25 times faster. Without it ledgdex uses its own pure-Python Ed25519, with the same results. Verified ledgers are also cached (in `~/.cache/ledgdex`, or `$LEDGDEX_CACHE`) by the exact bytes already verified, so a ledger that grew is only verified from where it was verified before; any changed byte is verified in full. `ledgdex verify --full` and `LEDGDEX_NO_CACHE=1` skip the cache, and `LEDGDEX_PURE=1` forces the pure-Python Ed25519.
+
+## Sell
+
+```
+ledgdex init shop --name "Mango Farm" --about "Alphonso mangoes from Ratnagiri" --key farm \
+    --url https://farm.github.io --dest git@github.com:farm/farm.github.io.git --branch main
+ledgdex offer shop offer.json
+ledgdex publish shop
+```
+
+`offer.json`:
+
+```json
+{"item": {"title": "Alphonso mangoes", "text": "One dozen, ripe."},
+ "quantity": 10, "unit": "dozen", "currency": "INR", "price": 120000,
+ "pay": [{"method": "upi", "to": "farm@bank"}]}
+```
+
+Prices are integers in the currency's smallest unit (120000 is INR 1,200.00). Left out: `allow` is `"any"`, `terms` is empty, and the arbiter is the seller.
+
+## A whole shop from a catalog
+
+```
+ledgdex shop catalog.json --repo OWNER/NAME
+```
+
+One command makes the shop from a JSON catalog: the ledgdex (if it is missing), one offer for each product, and the
+publish with dexweb to GitHub. Run it again after the catalog changes: unchanged products keep their offers, new and
+changed products get new offers, and the offers of changed and removed products are withdrawn. The same catalog again
+signs nothing. In Python: `from ledgdex.shop import shop; shop("catalog.json", repo="OWNER/NAME")`.
+
+```json
+{"shop": {"name": "Penguin Shop", "currency": "USD", "pay": [{"method": "card", "to": "https://pay.example/penguin"}]},
+ "products": [{"title": "Ice axe", "price": 4999, "quantity": 20, "text": "Steel, 70 cm"}]}
+```
+
+`shop.name`, `shop.currency` and `shop.pay` (one or more methods) are necessary; each product needs `title`, `price`
+and `quantity`. Unknown fields are refused, and a wrong product stops the run before anything is signed. The full
+format is in spec 7.5. GitHub Pages must be on for the repository (`OWNER.github.io` always has it).
+
+## Buy
+
+```
+ledgdex init me --name "Asha" --key asha --url https://asha.github.io --dest git@github.com:asha/asha.github.io.git
+ledgdex claim me https://farm.github.io OFFER_ID --quantity 2
+ledgdex publish me
+```
+
+The claim is kept in your ledger as `sent`. Publishing your dex is sending it: the seller collects it with `ledgdex record shop --from https://asha.github.io`, or you send the claim file any other way and the seller runs `ledgdex record shop claim-....json`.
+
+## The rest of a trade
+
+```
+ledgdex receipt me https://farm.github.io                  buyer keeps the seller's record: the receipt and the claim id
+ledgdex pay me https://farm.github.io CLAIM_ID --method upi --ref UTR123
+ledgdex record shop --from https://asha.github.io          seller records the payment notice
+ledgdex received shop CLAIM_ID 240000
+ledgdex delivered shop CLAIM_ID --note "by courier"
+ledgdex confirm me https://farm.github.io CLAIM_ID
+ledgdex record shop --from https://asha.github.io          the claim is now closed
+```
+
+Publish after each step that others need to see. Anyone can check any ledger:
+
+```
+ledgdex verify https://farm.github.io
+ledgdex state https://farm.github.io
+```
+
+## Disputes
+
+```
+ledgdex dispute me CLAIM_ID --seller https://farm.github.io --text "never arrived"   buyer
+ledgdex record shop --from https://asha.github.io
+ledgdex ruling judge https://farm.github.io DISPUTE_ID --outcome refund            the offer's arbiter
+ledgdex record shop --from https://judge.github.io
+```
+
+## Sealed-bid auctions
+
+```
+ledgdex auction shop auction.json        {"item": {"title": "Old map"}, "currency": "INR", "close": "...", "reveal_until": "...", "reserve": 10000}
+ledgdex bid me https://farm.github.io AUCTION_ID --amount 25000      only a commitment is sent; the amount stays in ~/.ledgdex/bids
+ledgdex reveal me https://farm.github.io AUCTION_ID                 after the close, before reveal_until
+```
+
+The seller records bids and reveals with `ledgdex record`. The best revealed bid that meets the reserve wins; payment and delivery then use the auction id in place of a claim id.
+
+## Keys
+
+```
+ledgdex keygen phone                                  on the phone: prints its public key
+ledgdex device add shop ed25519:... --name phone      with the owner key: the phone may now sign
+ledgdex device revoke shop ed25519:... --reason lost
+ledgdex rotate shop --key farm2                       replace the owner key
+ledgdex recover root shop ed25519:NEW                 the root names a new key for a lost one
+ledgdex recovered shop --root ROOT --key farm-new     the owner takes the ledger back
+```
+
+On a machine with a device key, everyday commands sign with it. Messages to other ledgers (claims, payments, bids) are signed with the owner key, which is a self's identity in other ledgers.
+
+## Indexes and the root
+
+```
+ledgdex list market https://farm.github.io --note "mangoes"     an index lists ledgers
+ledgdex discover https://market.github.io --offers              what the listed ledgers sell
+ledgdex admit root ed25519:...                                  the root admits selves to The Matrix
+ledgdex state shop --root https://root.github.io                "allow": "admitted" then needs the root too
+```
+
+## Running the root
+
+The root is the ledger whose admissions define who is in The Matrix, and its owner is the default arbiter. Today
+Noorul Ali, founder of The Matrix, runs it. It is an ordinary ledgdex:
+
+```
+ledgdex init root --name "The Matrix root" --about "Admission to The Matrix" --key matrix-root \
+    --url https://ROOT_ADDRESS --dest git@github.com:YOU/root.git --branch main
+ledgdex publish root
+```
+
+Keep the owner key (`~/.ledgdex/matrix-root.key`) backed up offline. For daily work, give the laptop a device key,
+which may admit and revoke but not change keys. Recovery hands a ledger to a new key, so `ledgdex recover` needs the
+owner key itself:
+
+```
+ledgdex keygen root-laptop                                   prints ed25519:...
+ledgdex device add root ed25519:... --name laptop            with the owner key, once
+```
+
+Then, with `ledgdex publish root` after each change:
+
+```
+ledgdex admit root ed25519:THEIR_KEY --name "Shop 12" --note "ground floor"      admit a self
+ledgdex revoke root ed25519:THEIR_KEY --reason "left the mall"                   take it back
+ledgdex recover root https://THEIR_DEX ed25519:THEIR_NEW_KEY                     with the owner key, after checking who they are
+ledgdex list root https://THEIR_DEX --note "Shop 12"                             optional: the root as an index too
+```
+
+Every dex that trades in The Matrix names the root in its `config.json`, as `"ledgdex": {"root": "https://ROOT_ADDRESS"}`.
+The first time ledgdex reads it, it adds `"root_id"`, the root's ledger id, and from then on refuses any other ledger
+at that address (or a broken one): whoever controls the address cannot swap in a root of their own. Set `root_id`
+yourself, from a source you trust, to pin it before the first read. The dex also keeps the last root it read, in `.ledgdex-root.jsonl`: when
+the root's address is down, commands work on with that copy, and an address serving an older root is ignored.
+Its "admitted" offers then need admission by the root too, and its offers and auctions default to the root's owner as
+arbiter. Rulings are signed with the owner key, since that is the arbiter key offers name:
+
+```
+ledgdex ruling root https://SELLER_DEX DISPUTE_ID --outcome refund --text "..."
+```
+
+Run `ledgdex check` on the root (the GitHub workflow, or cron) so any change to its history is caught.
+
+## JavaScript and the viewer
+
+`js/` holds the same core in plain browser JavaScript (no npm): canonical JSON, SHA-256/512, Ed25519, verification, the state function, the dex pages (`render.js`) and the dexweb build (`dexweb.js`). `node js/test.mjs` checks it reproduces the shared vectors in `vectors/` byte for byte: states, pages, and whole dexs that dexweb built. `python py/tests/make_vectors.py` regenerates them.
+
+The site https://ledgdex.github.io comes from three dexes. Dexweb publishes them to [ledgdex/ledgdex.github.io](https://github.com/ledgdex/ledgdex.github.io), and GitHub Pages serves that repository.
+
+| Source | Published to | Address | Publish with |
+|---|---|---|---|
+| `home/` (home page, Live Markets, About) | the root | https://ledgdex.github.io | `cd home && python run.py` |
+| `viewer/` (the viewer and the JavaScript modules) | `viewer/` | https://ledgdex.github.io/viewer/index.html | `cd viewer && python run.py` |
+| `guide/dex/` (the docs) | `docs/` | https://ledgdex.github.io/docs/ | `cd guide/dex && ledgdex publish .` |
+
+After you change `viewer/` or `js/`, publish the viewer again. `python run.py --build-only` builds `gen/` and does not publish. The home pages run no scripts. Only the viewer runs scripts.
+
+The viewer page loads any ledger by address or file, verifies it in the browser, and shows it as the same pages its dex has. It signs claims, payments, confirmations, disputes, bids and reveals with a key kept in the browser, using the browser's own constant-time Web Crypto Ed25519 when it has one, else ledgdex's built-in code. The key is stored only sealed with your passphrase ("Keep, sealed"), and "Download key backup" gives you a copy to keep offline. The viewer also keeps your own ledger: every message you sign is kept as `sent`, and "Collect receipts" keeps the seller's records of them. "Download your dex" gives you your ledger as a complete dex (a zip), file for file what `ledgdex init` and dexweb make; publish it like any dex. So a buyer with only a browser has a ledgdex too. Open a ledger directly with `https://ledgdex.github.io/viewer/index.html?ledger=https://farm.github.io`.
+
+## Checking for tampering
+
+`ledgdex verify` checks one ledger once. `ledgdex check` checks ledgers over time:
+
+```
+ledgdex check shop https://farm.github.io            once; exit code 1 on tampering
+ledgdex check shop --every 3600                      as a worker, every hour
+17 6 * * * cd /srv/ledgdex && ledgdex check shop --json report.json      from cron
+ledgdex workflow seller/ledgdex.jsonl > .github/workflows/ledgdex-check.yml   as a GitHub workflow
+```
+
+It keeps the last copy of every ledger it has seen (in `.ledgdex-check/`) and reports an error, with signed proof in `.ledgdex-check/proofs/`, when a ledger stops extending that copy (two entries at one seq), when a receipt no longer matches the ledger it came from, or when an address starts serving a different ledger. Receipts in the ledgers you check are followed to the sellers' ledgers automatically. `--media` also checks offer pictures against their hashes; `--published` compares a dex folder with its published ledger. A copy that is only behind (a cache or an old snapshot) is a warning, not an error. The GitHub workflow runs on every push, daily and by hand, keeps its last-seen copies in the Actions cache, and attaches the report and proofs to each run.
+
+## Every ledgdex is a dex
+
+Each command rewrites the ledgdex pages in `data.json` (pages whose first paragraph starts with `<!-- ledgdex -->`) and rebuilds the site with dexweb. Your own pages are never touched. `ledgdex publish` publishes with dexweb; `config.json` has `"append_only": ["ledgdex.jsonl"]`, so dexweb refuses to publish a ledger that does not extend the published one. Publishing from two devices is safe: the second one catches up and re-sequences its unpublished entries.
+
+## Production (v1.0)
+
+Before you trade for real, read [SECURITY.md](SECURITY.md). In short:
+
+- Install the `fast` extra (`pip install "ledgdex[fast]"`) on every machine that signs: it signs in constant time. ledgdex warns when it signs without it.
+- Keep owner keys offline (backed up), and use device keys day to day. Revoke a lost device at once.
+- Run `ledgdex check` on your ledger and the ledgers you trade with, daily (the workflow, cron or a worker). An error there is tampering, with proof.
+- In the browser, keep your key sealed with a long passphrase and download a backup. Use the viewer at https://ledgdex.github.io/viewer/index.html, or host it on an address of its own: every page on one origin can read what pages there store.
+- Generated workflows install ledgdex from the release tag and pin each action to a commit.
+
+## Tests
+
+Two suites. `python run_tests.py` is the essential one (about 30 s): every Python test except the docs examples and
+the tutorial, with the fast backend, and the JavaScript core against the shared vectors; run it after small changes.
+`python run_tests.py --full` is the full one (about 10 min): every Python test on both Ed25519 backends, the
+JavaScript vectors, and a round of differential fuzzing; run it after larger changes and before a release. CI runs
+the essential suite on every push (on Linux), and the full suite (on Linux, macOS and Windows) for release tags, by
+hand, weekly, and for a push whose commit message contains `[full tests]`. Both work in a clone and in
+the source package on PyPI, which holds the tests and their data; the wheel holds only the code. Steps:
+https://ledgdex.github.io/docs/testlocalledgdexinstallation.html. It needs git and node 20 or later. The parts one by one:
+
+```
+cd py && python -m unittest discover -s tests
+node js/test.mjs
+cd py && python tests/fuzz.py --seed 7 --ledgers 1000      Python and JavaScript must agree on random and corrupted ledgers
+```

ledgdex-1.0.20/README.md

@@ -0,0 +1,233 @@
+# Ledgdex
+
+A simple market on a dex. Every seller and buyer keeps a signed, append-only ledger (`ledgdex.jsonl`) in their own dex, a freely shared website built with [dexweb](https://github.com/matrixdex/dexweb). A trade exists three times: the buyer's signed claim, the seller's signed record of it, and the buyer's copy of that record. No server, no blockchain: SHA-256, Ed25519 and plain files.
+
+**Site: https://ledgdex.github.io** (viewer and live markets). **Docs: https://ledgdex.github.io/docs/** (getting started, setting up a marketplace, extending ledgdex, bots, the command line and API references, and tested examples). The docs are a dex built with dexweb, and a ledgdex too: dex is the core; dex + ledger is a ledgdex. Their source is [guide/](guide/).
+
+The specification is [architecture/SPEC.md](architecture/SPEC.md). Everything in it is built: the market (offers, claims, payment, delivery, receipts), disputes, sealed-bid auctions, device keys, key rotation and recovery, indexes, the root, dex pages, publishing and tamper checks, in Python, plus a JavaScript version and a browser viewer.
+
+## Install
+
+```
+pip install "ledgdex[fast]"
+```
+
+From the source on GitHub: `pip install "ledgdex[fast] @ git+https://github.com/ledgdex/ledgdex@v1.0.20"`. From a clone,
+to work on ledgdex: `pip install -e ".[fast]"`. Releases before 1.0.20 are on GitHub only, as tags; add
+`#subdirectory=py` to their address.
+
+Python 3.8 or later. The only dependency is dexweb (4.2.5 or later, before 5). Private keys live in `~/.ledgdex` (or `$LEDGDEX_HOME`), never in a dex, with mode 600: ledgdex refuses a key file others can read.
+
+The `fast` extra adds the `cryptography` package: signing and verifying get about 20 to 25 times faster. Without it ledgdex uses its own pure-Python Ed25519, with the same results. Verified ledgers are also cached (in `~/.cache/ledgdex`, or `$LEDGDEX_CACHE`) by the exact bytes already verified, so a ledger that grew is only verified from where it was verified before; any changed byte is verified in full. `ledgdex verify --full` and `LEDGDEX_NO_CACHE=1` skip the cache, and `LEDGDEX_PURE=1` forces the pure-Python Ed25519.
+
+## Sell
+
+```
+ledgdex init shop --name "Mango Farm" --about "Alphonso mangoes from Ratnagiri" --key farm \
+    --url https://farm.github.io --dest git@github.com:farm/farm.github.io.git --branch main
+ledgdex offer shop offer.json
+ledgdex publish shop
+```
+
+`offer.json`:
+
+```json
+{"item": {"title": "Alphonso mangoes", "text": "One dozen, ripe."},
+ "quantity": 10, "unit": "dozen", "currency": "INR", "price": 120000,
+ "pay": [{"method": "upi", "to": "farm@bank"}]}
+```
+
+Prices are integers in the currency's smallest unit (120000 is INR 1,200.00). Left out: `allow` is `"any"`, `terms` is empty, and the arbiter is the seller.
+
+## A whole shop from a catalog
+
+```
+ledgdex shop catalog.json --repo OWNER/NAME
+```
+
+One command makes the shop from a JSON catalog: the ledgdex (if it is missing), one offer for each product, and the
+publish with dexweb to GitHub. Run it again after the catalog changes: unchanged products keep their offers, new and
+changed products get new offers, and the offers of changed and removed products are withdrawn. The same catalog again
+signs nothing. In Python: `from ledgdex.shop import shop; shop("catalog.json", repo="OWNER/NAME")`.
+
+```json
+{"shop": {"name": "Penguin Shop", "currency": "USD", "pay": [{"method": "card", "to": "https://pay.example/penguin"}]},
+ "products": [{"title": "Ice axe", "price": 4999, "quantity": 20, "text": "Steel, 70 cm"}]}
+```
+
+`shop.name`, `shop.currency` and `shop.pay` (one or more methods) are necessary; each product needs `title`, `price`
+and `quantity`. Unknown fields are refused, and a wrong product stops the run before anything is signed. The full
+format is in spec 7.5. GitHub Pages must be on for the repository (`OWNER.github.io` always has it).
+
+## Buy
+
+```
+ledgdex init me --name "Asha" --key asha --url https://asha.github.io --dest git@github.com:asha/asha.github.io.git
+ledgdex claim me https://farm.github.io OFFER_ID --quantity 2
+ledgdex publish me
+```
+
+The claim is kept in your ledger as `sent`. Publishing your dex is sending it: the seller collects it with `ledgdex record shop --from https://asha.github.io`, or you send the claim file any other way and the seller runs `ledgdex record shop claim-....json`.
+
+## The rest of a trade
+
+```
+ledgdex receipt me https://farm.github.io                  buyer keeps the seller's record: the receipt and the claim id
+ledgdex pay me https://farm.github.io CLAIM_ID --method upi --ref UTR123
+ledgdex record shop --from https://asha.github.io          seller records the payment notice
+ledgdex received shop CLAIM_ID 240000
+ledgdex delivered shop CLAIM_ID --note "by courier"
+ledgdex confirm me https://farm.github.io CLAIM_ID
+ledgdex record shop --from https://asha.github.io          the claim is now closed
+```
+
+Publish after each step that others need to see. Anyone can check any ledger:
+
+```
+ledgdex verify https://farm.github.io
+ledgdex state https://farm.github.io
+```
+
+## Disputes
+
+```
+ledgdex dispute me CLAIM_ID --seller https://farm.github.io --text "never arrived"   buyer
+ledgdex record shop --from https://asha.github.io
+ledgdex ruling judge https://farm.github.io DISPUTE_ID --outcome refund            the offer's arbiter
+ledgdex record shop --from https://judge.github.io
+```
+
+## Sealed-bid auctions
+
+```
+ledgdex auction shop auction.json        {"item": {"title": "Old map"}, "currency": "INR", "close": "...", "reveal_until": "...", "reserve": 10000}
+ledgdex bid me https://farm.github.io AUCTION_ID --amount 25000      only a commitment is sent; the amount stays in ~/.ledgdex/bids
+ledgdex reveal me https://farm.github.io AUCTION_ID                 after the close, before reveal_until
+```
+
+The seller records bids and reveals with `ledgdex record`. The best revealed bid that meets the reserve wins; payment and delivery then use the auction id in place of a claim id.
+
+## Keys
+
+```
+ledgdex keygen phone                                  on the phone: prints its public key
+ledgdex device add shop ed25519:... --name phone      with the owner key: the phone may now sign
+ledgdex device revoke shop ed25519:... --reason lost
+ledgdex rotate shop --key farm2                       replace the owner key
+ledgdex recover root shop ed25519:NEW                 the root names a new key for a lost one
+ledgdex recovered shop --root ROOT --key farm-new     the owner takes the ledger back
+```
+
+On a machine with a device key, everyday commands sign with it. Messages to other ledgers (claims, payments, bids) are signed with the owner key, which is a self's identity in other ledgers.
+
+## Indexes and the root
+
+```
+ledgdex list market https://farm.github.io --note "mangoes"     an index lists ledgers
+ledgdex discover https://market.github.io --offers              what the listed ledgers sell
+ledgdex admit root ed25519:...                                  the root admits selves to The Matrix
+ledgdex state shop --root https://root.github.io                "allow": "admitted" then needs the root too
+```
+
+## Running the root
+
+The root is the ledger whose admissions define who is in The Matrix, and its owner is the default arbiter. Today
+Noorul Ali, founder of The Matrix, runs it. It is an ordinary ledgdex:
+
+```
+ledgdex init root --name "The Matrix root" --about "Admission to The Matrix" --key matrix-root \
+    --url https://ROOT_ADDRESS --dest git@github.com:YOU/root.git --branch main
+ledgdex publish root
+```
+
+Keep the owner key (`~/.ledgdex/matrix-root.key`) backed up offline. For daily work, give the laptop a device key,
+which may admit and revoke but not change keys. Recovery hands a ledger to a new key, so `ledgdex recover` needs the
+owner key itself:
+
+```
+ledgdex keygen root-laptop                                   prints ed25519:...
+ledgdex device add root ed25519:... --name laptop            with the owner key, once
+```
+
+Then, with `ledgdex publish root` after each change:
+
+```
+ledgdex admit root ed25519:THEIR_KEY --name "Shop 12" --note "ground floor"      admit a self
+ledgdex revoke root ed25519:THEIR_KEY --reason "left the mall"                   take it back
+ledgdex recover root https://THEIR_DEX ed25519:THEIR_NEW_KEY                     with the owner key, after checking who they are
+ledgdex list root https://THEIR_DEX --note "Shop 12"                             optional: the root as an index too
+```
+
+Every dex that trades in The Matrix names the root in its `config.json`, as `"ledgdex": {"root": "https://ROOT_ADDRESS"}`.
+The first time ledgdex reads it, it adds `"root_id"`, the root's ledger id, and from then on refuses any other ledger
+at that address (or a broken one): whoever controls the address cannot swap in a root of their own. Set `root_id`
+yourself, from a source you trust, to pin it before the first read. The dex also keeps the last root it read, in `.ledgdex-root.jsonl`: when
+the root's address is down, commands work on with that copy, and an address serving an older root is ignored.
+Its "admitted" offers then need admission by the root too, and its offers and auctions default to the root's owner as
+arbiter. Rulings are signed with the owner key, since that is the arbiter key offers name:
+
+```
+ledgdex ruling root https://SELLER_DEX DISPUTE_ID --outcome refund --text "..."
+```
+
+Run `ledgdex check` on the root (the GitHub workflow, or cron) so any change to its history is caught.
+
+## JavaScript and the viewer
+
+`js/` holds the same core in plain browser JavaScript (no npm): canonical JSON, SHA-256/512, Ed25519, verification, the state function, the dex pages (`render.js`) and the dexweb build (`dexweb.js`). `node js/test.mjs` checks it reproduces the shared vectors in `vectors/` byte for byte: states, pages, and whole dexs that dexweb built. `python py/tests/make_vectors.py` regenerates them.
+
+The site https://ledgdex.github.io comes from three dexes. Dexweb publishes them to [ledgdex/ledgdex.github.io](https://github.com/ledgdex/ledgdex.github.io), and GitHub Pages serves that repository.
+
+| Source | Published to | Address | Publish with |
+|---|---|---|---|
+| `home/` (home page, Live Markets, About) | the root | https://ledgdex.github.io | `cd home && python run.py` |
+| `viewer/` (the viewer and the JavaScript modules) | `viewer/` | https://ledgdex.github.io/viewer/index.html | `cd viewer && python run.py` |
+| `guide/dex/` (the docs) | `docs/` | https://ledgdex.github.io/docs/ | `cd guide/dex && ledgdex publish .` |
+
+After you change `viewer/` or `js/`, publish the viewer again. `python run.py --build-only` builds `gen/` and does not publish. The home pages run no scripts. Only the viewer runs scripts.
+
+The viewer page loads any ledger by address or file, verifies it in the browser, and shows it as the same pages its dex has. It signs claims, payments, confirmations, disputes, bids and reveals with a key kept in the browser, using the browser's own constant-time Web Crypto Ed25519 when it has one, else ledgdex's built-in code. The key is stored only sealed with your passphrase ("Keep, sealed"), and "Download key backup" gives you a copy to keep offline. The viewer also keeps your own ledger: every message you sign is kept as `sent`, and "Collect receipts" keeps the seller's records of them. "Download your dex" gives you your ledger as a complete dex (a zip), file for file what `ledgdex init` and dexweb make; publish it like any dex. So a buyer with only a browser has a ledgdex too. Open a ledger directly with `https://ledgdex.github.io/viewer/index.html?ledger=https://farm.github.io`.
+
+## Checking for tampering
+
+`ledgdex verify` checks one ledger once. `ledgdex check` checks ledgers over time:
+
+```
+ledgdex check shop https://farm.github.io            once; exit code 1 on tampering
+ledgdex check shop --every 3600                      as a worker, every hour
+17 6 * * * cd /srv/ledgdex && ledgdex check shop --json report.json      from cron
+ledgdex workflow seller/ledgdex.jsonl > .github/workflows/ledgdex-check.yml   as a GitHub workflow
+```
+
+It keeps the last copy of every ledger it has seen (in `.ledgdex-check/`) and reports an error, with signed proof in `.ledgdex-check/proofs/`, when a ledger stops extending that copy (two entries at one seq), when a receipt no longer matches the ledger it came from, or when an address starts serving a different ledger. Receipts in the ledgers you check are followed to the sellers' ledgers automatically. `--media` also checks offer pictures against their hashes; `--published` compares a dex folder with its published ledger. A copy that is only behind (a cache or an old snapshot) is a warning, not an error. The GitHub workflow runs on every push, daily and by hand, keeps its last-seen copies in the Actions cache, and attaches the report and proofs to each run.
+
+## Every ledgdex is a dex
+
+Each command rewrites the ledgdex pages in `data.json` (pages whose first paragraph starts with `<!-- ledgdex -->`) and rebuilds the site with dexweb. Your own pages are never touched. `ledgdex publish` publishes with dexweb; `config.json` has `"append_only": ["ledgdex.jsonl"]`, so dexweb refuses to publish a ledger that does not extend the published one. Publishing from two devices is safe: the second one catches up and re-sequences its unpublished entries.
+
+## Production (v1.0)
+
+Before you trade for real, read [SECURITY.md](SECURITY.md). In short:
+
+- Install the `fast` extra (`pip install "ledgdex[fast]"`) on every machine that signs: it signs in constant time. ledgdex warns when it signs without it.
+- Keep owner keys offline (backed up), and use device keys day to day. Revoke a lost device at once.
+- Run `ledgdex check` on your ledger and the ledgers you trade with, daily (the workflow, cron or a worker). An error there is tampering, with proof.
+- In the browser, keep your key sealed with a long passphrase and download a backup. Use the viewer at https://ledgdex.github.io/viewer/index.html, or host it on an address of its own: every page on one origin can read what pages there store.
+- Generated workflows install ledgdex from the release tag and pin each action to a commit.
+
+## Tests
+
+Two suites. `python run_tests.py` is the essential one (about 30 s): every Python test except the docs examples and
+the tutorial, with the fast backend, and the JavaScript core against the shared vectors; run it after small changes.
+`python run_tests.py --full` is the full one (about 10 min): every Python test on both Ed25519 backends, the
+JavaScript vectors, and a round of differential fuzzing; run it after larger changes and before a release. CI runs
+the essential suite on every push (on Linux), and the full suite (on Linux, macOS and Windows) for release tags, by
+hand, weekly, and for a push whose commit message contains `[full tests]`. Both work in a clone and in
+the source package on PyPI, which holds the tests and their data; the wheel holds only the code. Steps:
+https://ledgdex.github.io/docs/testlocalledgdexinstallation.html. It needs git and node 20 or later. The parts one by one:
+
+```
+cd py && python -m unittest discover -s tests
+node js/test.mjs
+cd py && python tests/fuzz.py --seed 7 --ledgers 1000      Python and JavaScript must agree on random and corrupted ledgers
+```

ledgdex-1.0.20/guide/dex/ledgdex.jsonl

@@ -0,0 +1,5 @@
+{"ledger":1,"name":"Ledgdex Docs","owner":"ed25519:109fe19cccb5efede333f889bfedf3bb30ab39b0eeec7d6898dbb40de25c1a65"}
+{"msg":{"at":"2026-10-20T09:00:00Z","body":{"about":"The ledger of the ledgdex docs: a demonstration. Its key was destroyed after signing, so nothing can be added to it, and nobody may buy from it.","dex":"https://ledgdex.github.io/docs"},"by":"ed25519:109fe19cccb5efede333f889bfedf3bb30ab39b0eeec7d6898dbb40de25c1a65","sig":"48971bc58b4e5b55ff61660d5348fd0c7084443ebbaef1bb055ed36220930c21124dbd8304b828f8bd9518a6745deedc7fb14fed00b21c31f2e6551adc756c01","type":"open","v":1},"prev":"sha256:7b3d502db18a78b0c53a2c23d0ae2cf6281d27aa98708f9ae3edf0802d8f345c","seq":0,"sig":"608a79e5be4420a51b851629457143d7edeba04913687bdd06a0760fbd82bbefd57555fabe4e183a77c9eef07e6e3a1522bde05013a3c3657135e183b741840d","time":"2026-10-20T09:00:00Z"}
+{"msg":{"at":"2026-10-20T09:00:01Z","body":{"allow":[],"arbiter":{"key":"ed25519:109fe19cccb5efede333f889bfedf3bb30ab39b0eeec7d6898dbb40de25c1a65","url":""},"currency":"USD","item":{"media":[],"text":"A demonstration of the page ledgdex makes for an offer: the weights of Penjointu, a neural network that analyzes the bone density of knee joints. Nobody may buy it.","title":"Example offer: Penjointu v1 weights"},"pay":[{"method":"card","to":"https://pay.example/biobot"}],"price":250000,"quantity":10,"terms":"An example in the ledgdex docs: \"allow\" is an empty list, so every claim is refused.","unit":"license"},"by":"ed25519:109fe19cccb5efede333f889bfedf3bb30ab39b0eeec7d6898dbb40de25c1a65","sig":"f15781fbad22189ca3d83b0f1e820e54033a5bd430443acc497c2434c8fe656475eb878ed97b60eceb592839ad671fe9ae65bda85f19b8c76ce1749ea8681c0c","type":"offer","v":1},"prev":"sha256:c934353ae5d46814eeb94844b46dbc31ae9af77b6fe4c70785d37e1a831c8e6b","seq":1,"sig":"fe42164cfea5a20fb3747c301029c4d4196d467f2f44f60a7963ad61d88f4713178eba4bb67b28685a3e1bbf8345050dad99ae2a194fab742bcf8cd2db216801","time":"2026-10-20T09:00:01Z"}
+{"msg":{"at":"2026-10-20T09:00:02Z","body":{"allow":[],"arbiter":{"key":"ed25519:109fe19cccb5efede333f889bfedf3bb30ab39b0eeec7d6898dbb40de25c1a65","url":""},"best":"highest","close":"2026-10-28T09:00:00Z","currency":"USD","item":{"media":[],"text":"A demonstration of the page ledgdex makes for a sealed-bid auction: the v2 weights, 90 days before all other clinics. Nobody may bid.","title":"Example auction: Penjointu v2 early access"},"reserve":1000000,"reveal_until":"2026-10-29T09:00:00Z","terms":"An example in the ledgdex docs."},"by":"ed25519:109fe19cccb5efede333f889bfedf3bb30ab39b0eeec7d6898dbb40de25c1a65","sig":"cb188870d7b4189fd5591c7ae7e0b5776d89085594edde2b18475ba2eff2f7cc5daa5c7d393f7d30d5648a5a75af0b5191698669fefecaef910eb6240d11db07","type":"auction","v":1},"prev":"sha256:039bb4080d22c05d5f464e137c3f8ec720e64734bcd52fdf7677c3a72ca7aadc","seq":2,"sig":"598a418c8a10c57adc628ffc623f074857033e0e11a4d6ef561c941e6066f0fa876dbbe9957c4e84c103e2b5271823d2896c61c724a624a472d888b53041db08","time":"2026-10-20T09:00:02Z"}
+{"msg":{"at":"2026-10-20T09:00:03Z","body":{"ref":"sha256:039bb4080d22c05d5f464e137c3f8ec720e64734bcd52fdf7677c3a72ca7aadc","text":"This ledger was signed once, for the docs."},"by":"ed25519:109fe19cccb5efede333f889bfedf3bb30ab39b0eeec7d6898dbb40de25c1a65","sig":"6593e48a66c33bb60f69854707f35cfaa7679bb3e10cc078f03c4132e2db7811798ee9383f38aa13dfc88461ed9ece4b37f0d8c7bea8f3c7193ed99beb3b2000","type":"note","v":1},"prev":"sha256:e78a0fa08f3f9c1fb85d69fc66e43e9ac5a04248f0921cc303f2fe302b2cc664","seq":3,"sig":"2ad71ad9ef800cade5e92a381fe7dd2f3cea86eea2a489ae16500429a8e3ee252afaa6a725d1aa3a205aa855b6c6a3797a1000aba126df04ad006c725095b50f","time":"2026-10-20T09:00:03Z"}