Bvs

Abstract

1. Introduction

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.

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.

2. Objective

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

This project demonstrates how Svelte, Ethereum, Solidity can be applied to a real-world Blockchain & Cloud Computing problem.

3. Key Features / Modules

• 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.

4. Technology Stack

5. System Requirements

General requirements for this technology stack — check the README for exact versions.

• Node.js and npm
• Hardhat / Truffle / Remix IDE
• MetaMask wallet with a test network
• Git (to clone the repository)

6. Installation & Setup

git clone https://github.com/vattelum/bvs.git
cd bvs

1. Connect signature — A one-time wallet signature to authenticate with the Turbo service (once per session).
2. Arweave upload — The wallet signs the data item for permanent storage on Arweave.
3. On-chain registration — A standard Ethereum transaction to record the document in the registry contract.
4. Go to app.ardrive.io and connect your Ethereum wallet
5. Purchase Turbo credits using ETH (a small amount covers many documents)

cd apps/contracts
forge install
forge build
forge test

cd apps/contracts
cp .env.example .env  # set PRIVATE_KEY (and optionally ADMIN_ADDRESS, BVS_HARD_LOCK)

# 1. Deploy BVSToken + BVSRegistry, seed initial categories
forge script script/01_Deploy.s.sol --rpc-url $SEPOLIA_RPC_URL --broadcast --verify

# 2. Deploy a Snapshot X Space wired to your token
forge script script/02_CreateVotingSpace.s.sol --rpc-url $SEPOLIA_RPC_URL --broadcast

# 3. Deploy a VanillaExecutionStrategy (quorum=1) referenced by every BVS proposal
forge script script/03_DeployExecutionStrategy.s.sol --rpc-url $SEPOLIA_RPC_URL --broadcast --verify

forge script script/ReduceVotingPeriod.s.sol --rpc-url $SEPOLIA_RPC_URL --broadcast

Full setup instructions are in the project README.

7. Future Enhancements

Suggested extensions you can add to make this your own project.

• Add a CI/CD pipeline with GitHub Actions
• Deploy to a public test network or cloud free tier
• Add monitoring and cost alerts

8. Viva / Review Questions

Common questions examiners ask for projects in this domain.

1. Why does this problem need a blockchain or cloud-native design?
2. Explain the smart contract / infrastructure components and how they interact.
3. How are gas costs or cloud costs kept under control?
4. How is the system secured (keys, IAM, access control)?
5. How would the solution scale to many more users?

9. Source Code & License

This project is developed by vattelum and published on GitHub under the MIT License. Please follow the license terms and credit the original author when you use or modify this code.