117 online 3 members  + Join RP Base  +
FreeScript

bvs

by vattelum  ·  version 2026.11.05  ·  updated 3 days ago

No reviews yet

Downloads
0
Reviews
0
Size
189 KB
Code check
Clean
Licence
MIT
Released
Nov 2026

A Blockchain Voting System that lets organizations use on-chain governance tools to engage their stakeholders.

bvs
BVS — Blockchain Voting System
BVS gives any organization—a corporation, a foundation, an NGO, or a (local) government entity—a tool to engage its stakeholders to vote for standards, policies, and resolutions while using blockchain technology.

Why do we need this?

One of the (many) problems of the traditional governance tools in the crypto industry is that they reduce human cooperation into an "American startup." This leaves most other forms of organization (of which there are many more than startups) unable to legally use beneficial blockchain tools.

The BVS addresses this issue by specifically not raising funds, trying to be decentralized, or pretending to be an organization. Instead, it is a simple, legally neutral tool for an organization to engage stakeholders and record votes and legislation on the blockchain. It is a way to use the beneficial voting and registration tools created for DAOs but without the legal complexity.

Those using a BVS do not raise funds, their non-tradable tokens do not create financial products, and there is no shared risk or liability. Legally, it's simply one company recording input from its stakeholders.

Non-financial use adds significant value to any blockchain in an industry rife with compliance issues.

Part of the Vattelum ecosystem.
Demo
https://github.com/user-attachments/assets/5bce30e5-9f05-465b-a14e-1a980d423815
How It Works
The BVS is run by a single admin.

One wallet deploys the contracts, manages membership, and decides which proposals get recorded on-chain in the BVS registry.

Stakeholders receive soulbound membership tokens and vote on proposals through Snapshot X (on-chain voting). One token equals one vote.

The BVS combines four pieces of blockchain infrastructure:

  1. Membership tokens — Soulbound (non-transferable) ERC-721 tokens that represent membership. One token per address. Admin-minted, holder-burnable.

  1. On-chain voting (Snapshot X) — A Snapshot X Space deployed on the same chain as the BVS contracts. Members vote For / Against / Abstain. Voting is fully on-chain—every vote is a transaction.

  1. Permanent storage (Arweave) — Proposed documents are uploaded to Arweave via ArDrive Turbo using the proposer's wallet. The Arweave transaction ID and a SHA-256 content hash are encoded into the Snapshot X proposal payload.

  1. On-chain registry — BVSRegistry records the ratified document's Arweave URI, content hash, title, category, version, and a reference back to the Snapshot X proposal that ratified it. The admin records both ratifications (addDocument) and rejections (rejectProposal, event-only, with the recorded vote tally).

The result is a governance system where every vote, every ratified document, and every rejection is independently verifiable: the on-chain content hash can be checked against the Arweave document, and the Snapshot X proposal can be inspected for the vote that produced it.
Features
  • Soulbound membership — Non-transferable ERC-721 tokens with on-chain credential storage. Admin-minted; holder- and admin-burnable.
  • Snapshot X voting — On-chain voting via sx-evm contracts on the same network as the BVS contracts. No off-chain Snapshot v2 dependency.
  • Document types — Each document is classified as Original, Amendment, Revision, Repeal, or Codification, creating a clear legislative lifecycle.
  • Section-level targeting — Amendments and repeals can target specific sections of an existing document, not just the document as a whole.
  • External references — Documents can reference other on-chain documents with relationship types (amends, revises, repeals, codifies, governs, implements, references, template).
  • Approve / Reject — Admin records the outcome of every proposal: addDocument for ratifications, rejectProposal (event-only) for rejections, both at any time.
Architecture
Smart Contracts (Solidity 0.8.31, OpenZeppelin 5.x):
  • BVSToken.sol — ERC-721 + ERC-5192 soulbound membership token with credential storage. Admin-only mint, holder self-burn or admin burn, optional verifier gate.
  • BVSRegistry.sol — Append-only document registry with categories, document layer, version chains, and a single governanceAuthority (admin EOA). Supports per-document amendment restrictions (setAmendmentRestrictions / getAmendmentRestrictions with locked sections and minimum time between amendments) gated by an immutable hardLock constructor flag. Includes rejectProposal() for the audit trail.
  • lib/document-registry/ — @vattelum/document-registry shared standard.
  • lib/sx-evm/ — Snapshot X contracts (Space, EthTxAuthenticator, VanillaVotingStrategy, VanillaExecutionStrategy, and a proposal-validation strategy — VanillaProposalValidationStrategy for open proposing or WhitelistProposalValidationStrategy for admin-only).

Frontend (SvelteKit static SPA, Tailwind CSS):
  • / — Public registry browser. Categories → documents → versions; document content fetched from Arweave on demand. For each law, shows the text in force on any chosen date, with cite, export and copy.
  • /admin — Member list (from Transfer / burn events), admin-gated mint form, holder self-burn.
  • /propose — Structured markdown editor with section numbering (§1, §1.1, §1.1.A), Arweave upload, Snapshot X proposal creation. Gated by VITE_MEMBERS_CAN_PROPOSE to mirror the Space's proposal-validation strategy. Refuses headings outside the section format; an amendment adds new sections to its targets and asks before removing a targeted section it gives no text for.
  • /vote — Active proposals with on-chain vote buttons (For / Against / Abstain). Admin sees Approve & Record and Reject buttons on every proposal at any time.

External Services:
  • Snapshot X — On-chain voting via sx-evm contracts.
  • [Arweave](https://ar

…