The two layers#
Two different jobs are done by two different kinds of server. Keep them apart in your head and in your code.
- Layer 1 · Directory infrastructure. Many equal directories and relays that only store and find signed records. They are the phone book.
- Layer 2 · Balanced wallets and circles. Every circle keeps its own ledger of numbered blocks on its own relays. They are the books. A wallet balance is an account line in that ledger.
A third thing, BalanceID and the Compliance Passport (identity checks for banks), is a separate, future layer and is described on its own page. It is not part of either layer above and is not built.
Side by side#
| Layer 1 · Directory infrastructure | Layer 2 · Balanced wallets / circles | |
|---|---|---|
| Job | Find circles and people. Say where to look | Be the ledger. Say what is true |
| What is stored | Profiles (KIND 0), circle records (30910), heads (30915), member homes (30916), the present state: the newest day seals (43917) and snapshot chunks (43918) of the last 7 days | Blocks (43911) with notes (43910) and acts (43916), day seals (43917), snapshots (43918), rate quotes (43919), references (43921), statements (43924). The whole history |
| Who writes | People (their own profile and home), a circle's key and witnesses (record, head, seals), the directory's own collector (copies after it verified the chain) | The circle's node and witnesses (blocks, seals, snapshots), members (notes and acts), the circle (references, quotes) |
| Who can verify | Anyone: every record is signed. A directory also checks and may say verified | Anyone: the chain by prev digest, the witnesses' quorum, the genesis pin, the Merkle roots |
| Deletion | Impossible: the relay refuses KIND 5 and KIND 62. Old seals and snapshots (older than 9 days) are removed by an hourly cleanup because a directory is the present, not an archive | Impossible: circle relays never delete anything and refuse KIND 5 and KIND 62 for ledger kinds |
| Copies | Many equal directories, each with the same index; the target is as many as people want (up to 1,000) | At least 4 relays at 3 operators per circle, plus archives; a payment counts when a majority of witnesses has signed and 3 relays hold the block |
| If one server dies | Ask another directory. Nothing is lost: it is rebuilt from the circles' relays | Read another relay of the circle. If the circle's node dies, the circle is restored from its relays and a new node takes over by a public decision |
| What it can get wrong | It can omit or be late. It cannot forge | It cannot be wrong silently: every witness recomputes every block; a wrong block has no quorum |
| Who is trusted for what | For finding, for convenience | For the truth about a balance, and only through verification |
One key links the two#
The same 64-character HEX key appears in three places:
- the profile (KIND 0) stored by directories (layer 1),
- the member home (KIND 30916) that says which circle you belong to, written by you and attested by a witness (it bridges both layers),
- your account line
s3|<key>|…in the circle's ledger (layer 2).
Nothing is linked by hand and no name enters the ledger. A directory shows a person as: profile, circle, block joined. Whether the circle's own ledger confirms the join is ledgerChecked.
Which kind belongs to which layer#
Taken from the record definitions 0.3.0 (kinds page, kinds.json). Directory = accepted and kept by the directory relay. Circle ledger = lives on the circle's own relays as part of its book.
| KIND | Name | Layer 1 · directory | Layer 2 · circle ledger |
|---|---|---|---|
0 | Profile (plain Nostr) | ● | |
30910 | Circle Record | ● | |
30915 | Circle Head | ● | |
30916 | Member Home | ● | |
43910 | Payment Note | ● | |
43911 | Circle Block | ● | |
43916 | Circle Act | ● | |
43917 | Day Seal | ● (newest 7 days) | ● |
43918 | Snapshot Chunk | ● (newest 7 days) | ● |
43919 | Rate Quote | ● | |
43921 | Reference | ● | |
43924 | Statement | ● | |
43920 | BSA Rules (retired) | retired (decision E-1) | |
43922, 43923 | (unused) | reserved, unused | |
30917 | Service Offer | reserved for later |
Notes:
- 30910, 30915, 30916 are written by a circle's own parties (circle key, witness, member) but are stored by directories: they bridge the layers. Every version of the circle record is also carried in the ledger, so its history is never lost.
- 43917 and 43918 exist in both: the circle keeps all of them for ever; a directory keeps copies of the newest 7 days (the present state).
- 43910 is a payment note. It sits inside a block; a standalone copy is only evidence.
- 0 is the ordinary Nostr profile. It is not a BSA kind.
- Retired: 43920 (the world-wide rules record; each circle now sets its own rules, decision E-1, never published). Retired since 0.1.0: 30911, 30912, 30913, 30914, 43912, 43913, 43914, 43915. Reserved, unused: 43922, 43923. Not defined: 43925 (free text beside the chain was dropped). Reserved for later: 30917 (a service offer for relay, witness, archive or index operators).
Why separate them?#
Because they fail differently and they are trusted differently. A directory may be wrong by omission and nobody loses money. A ledger must never be wrong. Because many directories are cheap and one circle's ledger is the circle's own. And because the principles say so: everything is public; everything is on relays in at least three copies; there are no central authorities; each circle is an independent, balanced cell; cells connect by themselves into more. Read the six principles.