Skip to content

Commit f2c1245

Browse files
thegreatfeezthegreatfeez
authored
Merge pull request #547 from Meet-hybrid/docs/benchmark-storage-cost-delta-weighted-governance
2 parents 0c99f8c + 879e21f commit f2c1245

1 file changed

Lines changed: 63 additions & 11 deletions

File tree

‎docs/ARCHITECTURE.md‎

Lines changed: 63 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -70,11 +70,11 @@ All instance-storage keys share **one** `LedgerEntry` (the contract instance). T
7070

7171
Each key is a separate `LedgerEntry` with its own independently tracked TTL.
7272

73-
| Key | Type | Description | TTL — bump / threshold (ledgers) | Approx. cost (XLM / 30 days) |
74-
| --------------------- | -------------- | ------------------------------------ | -------------------------------- | ---------------------------- |
75-
| `OWNERS` | `Vec<Address>` | Fixed owner set (max 20 addresses) | 518,400 / 17,280 | ~0.052 XLM |
76-
| `("PROP", id)` | `Proposal` | Per-proposal state | 518,400 / 17,280 | ~0.052 XLM |
77-
| `("APPR", id, owner)` | `bool` | Per-owner approval flag per proposal | 518,400 / 17,280 | ~0.052 XLM |
73+
| Key | Type | Description | TTL — bump / threshold (ledgers) | Approx. cost (XLM / 30 days) |
74+
| --------------------- | ------------------ | ------------------------------------------ | -------------------------------- | ---------------------------- |
75+
| `OWNERS` | `Map<Address,u32>` | Owner address → voting weight map (max 20) | 518,400 / 17,280 | ~0.052 XLM |
76+
| `("PROP", id)` | `Proposal` | Per-proposal state | 518,400 / 17,280 | ~0.052 XLM |
77+
| `("APPR", id, owner)` | `u32` | Per-owner approval weight per proposal | 518,400 / 17,280 | ~0.052 XLM |
7878

7979
### Proposal Struct Fields
8080

@@ -108,7 +108,8 @@ Accord uses two patterns:
108108
| `NEXT` | Monotonic proposal ID counter |
109109
| `ACTCNT` | Count of currently active proposals |
110110
| `TLOCK` | Time-lock delay in seconds |
111-
| `OWNERS` | Owner address list |
111+
| `TWGT` | Cached total owner weight |
112+
| `OWNERS` | Owner address → weight map |
112113

113114
**Tuple keys** — two- or three-part tuples for per-entity records, where the first element is a short symbol namespace:
114115

@@ -174,23 +175,49 @@ rent_fee_stroops = ceil(entry_size_bytes / 1024) × fee_rate_1kb × delta_ledger
174175
| `("PROP", id)` entry size | ~396 bytes (100-char description) | XDR field sum below; 300-char max adds ~200 bytes, still rounds to 1 KB |
175176
| `("APPR", id, owner)` entry size | ~144 bytes | XDR field sum below |
176177

178+
**XDR byte breakdown — `OWNERS` entry (Map<Address, u32>):**
179+
180+
| Field | XDR bytes |
181+
| ---------------------------------- | ------------------------------- |
182+
| Key (`OWNERS` symbol) | 8 |
183+
| Map length prefix | 4 |
184+
| Per entry: Address (discriminant + ed25519 key) | 40 |
185+
| Per entry: u32 weight | 4 |
186+
| **1 owner** | **52 bytes → 1 KB billed** |
187+
| **7 owners** | **316 bytes → 1 KB billed** |
188+
| **20 owners (max)** | **808 bytes → 1 KB billed** |
189+
190+
**Before weighted governance:** `OWNERS` was `Vec<Address>` — 1 owner = 52 bytes, 7 owners = 332 bytes, 20 owners = 820 bytes. The `Map<Address, u32>` adds 4 bytes per entry for the weight value, yielding a modest increase.
191+
192+
**XDR byte breakdown — `("APPR", id, owner)` approval entry (weighted):**
193+
194+
| Field | XDR bytes |
195+
| ------------------------------------- | ---------------------------- |
196+
| Key (`"APPR"` symbol + u64 + Address) | 60 |
197+
| Value (`u32` approval weight) | 4 |
198+
| LedgerEntry framing and metadata | ~80 |
199+
| **Total** | **~144 bytes → 1 KB billed** |
200+
201+
**Before weighted governance:** the approval entry stored a `bool` (4 bytes). After: stores a `u32` weight (4 bytes) — same byte count, different semantic.
202+
177203
**XDR byte breakdown — `("PROP", id)` Proposal entry (100-char description):**
178204

179205
| Field | XDR bytes |
180206
| ---------------------------------------------------------- | ---------------------------- |
181207
| Key (`"PROP"` symbol + u64 id) | 16 |
182208
| `id` (u64) | 8 |
183-
| `proposer` (Address) | 44 |
184-
| `description` (String, 100 chars) | 108 |
209+
| `proposer` (Address) | 40 |
210+
| `description` (String, 100 chars) | 104 |
185211
| `deadline` (u64) | 8 |
186212
| `approvals` (u32) | 4 |
213+
| `approval_weight` (u32) | 4 |
187214
| `status` (enum) | 4 |
188-
| `kind` (Transfer: discriminant + Address + i128 + Address) | 108 |
215+
| `kind` (Transfer: discriminant + Vec<Transfer>) | 108 |
189216
| `ready_at` (u64) | 8 |
190-
| `threshold` (u32) | 4 |
217+
| `quorum_weight` (u32) | 4 |
191218
| `category` (enum) | 4 |
192219
| LedgerEntry framing and metadata | ~80 |
193-
| **Total** | **~396 bytes → 1 KB billed** |
220+
| **Total** | **~388 bytes → 1 KB billed** |
194221

195222
**XDR byte breakdown — `("APPR", id, owner)` approval entry:**
196223

@@ -209,6 +236,31 @@ rent_fee_stroops = ceil(entry_size_bytes / 1024) × fee_rate_1kb × delta_ledger
209236
| `("APPR", id, owner)` per approver | 1 KB | 518,400 | ~0.052 |
210237
| **3-of-5 multisig (3 approvers)** | — | — | **~0.208** |
211238

239+
### Storage Cost Delta — Weighted Governance
240+
241+
The table below compares the pre-weighted and post-weighted storage costs for the `OWNERS` entry and the worst-case persistent storage total.
242+
243+
| Metric | Pre-weighted (`Vec<Address>`) | Post-weighted (`Map<Address, u32>`) | Delta |
244+
|--------|------------------------------|--------------------------------------|-------|
245+
| `OWNERS` entry (1 owner) | 52 bytes → 1 KB billed | 52 bytes → 1 KB billed | 0 bytes |
246+
| `OWNERS` entry (7 owners) | 332 bytes → 1 KB billed | 316 bytes → 1 KB billed | −16 bytes |
247+
| `OWNERS` entry (20 owners) | 820 bytes → 1 KB billed | 808 bytes → 1 KB billed | −12 bytes |
248+
| `("APPR", id, owner)` value | `bool` = 4 bytes | `u32` = 4 bytes | 0 bytes |
249+
| `("PROP", id)` fields | 10 fields | 11 fields (+ `approval_weight`, `quorum_weight`) | +8 bytes |
250+
| New instance key `TWGT` | — | `u32` = 4 bytes (~150 bytes shared entry) | +4 bytes |
251+
252+
**Worst-case persistent entries** (50 proposals × 20 owners):
253+
254+
| | Pre-weighted | Post-weighted |
255+
|---|---|---|
256+
| `OWNERS` | 1 entry | 1 entry |
257+
| `("PROP", id)` | 50 entries | 50 entries |
258+
| `("APPR", id, owner)` | 1,000 entries | 1,000 entries |
259+
| **Total** | **1,051 entries** | **1,051 entries** |
260+
| **Cost per 30-day cycle** | **~54.6 XLM** | **~54.6 XLM** |
261+
262+
> **Net impact**: The weighted governance model adds ~8 bytes to each proposal entry (`approval_weight` + `quorum_weight`) and introduces the shared instance key `TWGT`. Because all entries round up to 1 KB for billing, the actual XLM cost per 30-day bump cycle is **identical** — the byte-level increases fall well within the 1 KB billing quantum. The per-owner approval entry changed from `bool` to `u32` with no byte-level difference. The `OWNERS` map entry is slightly smaller than the prior `Vec` due to Soroban's more compact map encoding.
263+
212264
> These figures use a fee rate of 1 stroop/KB/ledger. Verify the current network value before capacity-planning large deployments; the rate is adjustable via Stellar governance.
213265
214266
### Bump-on-Access Strategy and Configuration

0 commit comments

Comments
 (0)