Benchmark and document the storage cost delta from weighted governance in ARCHITECTURE.md

[thegreatfeez]

Smart Contract — Optimisation

Summary

Weighted governance added new fields to on-chain storage (per-owner weights, a cached total-weight counter, and quorum/approval-weight fields on each proposal), but the storage cost tables in ARCHITECTURE.md still describe the pre-weighted layout. This issue asks a contributor to benchmark the real byte-size impact and bring the documentation back in sync with the deployed contract.

Background

docs/ARCHITECTURE.md's "Storage Layout" section documents the OWNERS entry as a Vec<Address> and lists the Proposal struct with an approvals: u32 field and a plain threshold reference. In the current contract (contracts/accord/src/lib.rs), OWNERS is stored as a Map<Address, u32> (address to voting weight), a new TWEIGHT instance-storage key caches the total weight, and Proposal carries a quorum_weight: u32 field plus a wider ProposalKind enum (it now has six variants instead of one). The XDR byte breakdown tables and the "Storage Cost Per Proposal" section were never updated to reflect any of this.

What Needs to Be Done

1. Measure the actual XDR-encoded size of the OWNERS persistent entry now that it stores a Map<Address, u32> instead of a Vec<Address>, for a representative range of owner counts (e.g. 1, 7, and the 20-owner maximum).
2. Measure the actual XDR-encoded size of a ("PROP", id) proposal entry with the current Proposal struct fields, including the quorum_weight field and the largest ProposalKind variant.
3. Update the "Instance Storage" table in ARCHITECTURE.md to include the TWEIGHT key alongside the existing singleton keys, with its type, description, and TTL.
4. Update the "Persistent Storage" table and the "Proposal Struct Fields" listing to match the current struct definition and field names exactly.
5. Update the "Storage Cost Per Proposal" and "Storage Cost Methodology" sections with the new measured byte counts and recalculated worst-case totals (50 active proposals at the 20-owner cap), showing the before/after delta introduced by weighted governance.
6. Update the "Key Naming Conventions" table to include TWEIGHT among the documented singleton keys.

Acceptance Criteria

• ARCHITECTURE.md's storage tables list every current storage key, including TWEIGHT, with accurate types and descriptions.
• The Proposal Struct Fields listing in ARCHITECTURE.md matches the fields actually defined on the Proposal struct in lib.rs.
• The document states a measured (not estimated) byte size for the OWNERS entry and for a ("PROP", id) entry under the weighted-governance model.
• A clear before/after cost comparison is present showing the storage cost delta introduced by weighted governance, expressed in both bytes and approximate XLM per 30-day bump cycle.
• The worst-case total storage cost figure (50 proposals, 20 owners) is recalculated using the new measurements.

Files to Look At

• docs/ARCHITECTURE.md — contains the Storage Layout, Storage Cost Per Proposal, and Storage Cost Methodology sections to update
• contracts/accord/src/lib.rs — defines the current Proposal struct, ProposalKind enum, and the OWNERS/TWEIGHT storage keys to benchmark against
• contracts/accord/src/test.rs — existing tests use env.budget(), a useful reference for measuring on-chain resource costs during benchmarking

Difficulty: Medium

[Chinonso-Peter]

@Chinonso-Peter has applied to work on this issue as part of the Stellar Wave Program's 7th wave.

Can i work on this

ℹ️ Repo Maintainers: To accept this application, review their application or assign @Chinonso-Peter to this issue.

[blizzj]

@blizzj has applied to work on this issue as part of the Stellar Wave Program's 7th wave.

Hi Maintainer,
I'd really appreciate the opportunity to work on this issue. Having reviewed the acceptance criteria, I'm confident that I can submit a PR shortly after being assigned.
Kindly assign this issue to me.
Thank you.

ℹ️ Repo Maintainers: To accept this application, review their application or assign @blizzj to this issue.

[shaarknado]

@shaarknado has applied to work on this issue as part of the Stellar Wave Program's 7th wave.

I would love to work on this task

ℹ️ Repo Maintainers: To accept this application, review their application or assign @shaarknado to this issue.

[drips-wave]

Congratulations, @Chinonso-Peter! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on July 30, 2026.

🧑‍💻 @Chinonso-Peter: Please resolve the issue such that the repo's maintainers have enough time to review your contribution before the due date. You'll earn Points for completing the issue on-time, which will make you eligible for a share of the Stellar Wave Program's reward pool.

Warning

When opening a PR, please link it to this issue to ensure it gets tracked accurately. Points are awarded when this issue is marked as completed by the maintainer.

🤠 Repo maintainers: Please keep an eye on the contributor's progress and review their work before the due date. You can manage this issue, including adjusting its complexity and points, here.

🌊 Happy Wave 🌊