Reader Guide

What is Web3 & Why Bayanihan?

Welcome to the Bayanihan Web3 E-Book. This guide is designed specifically for non-technical readers, community organizers, students, and entrepreneurs to show how smart contracts function in the real world.

Instead of using complex theoretical math or dense code, we will explore these concepts through the lens of Bayanihan—the traditional Filipino spirit of communal unity, cooperation, and mutual support. We will dissect the 15 custom smart contracts powering the Bayanihan digital nation, converting Solidity code into everyday analogies.

How the Internet Has Evolved

Era	Core Capability	Control	Visual Analogy
Web1 (1990s)	Read-Only	Centralized (Publishers)	A library where you can only read books off the shelves.
Web2 (2000s)	Read & Write	Centralized (Big Tech)	A social media board where you upload content, but the board owner owns your profile.
Web3 (Future)	Read, Write & Own	Decentralized (Community)	A cooperative marketplace owned, run, and secured by the participants themselves.

The Core Engine: The Smart Contract

At the heart of Web3 is the Smart Contract. It is simply a digital agreement written in software code instead of legal documents.

Once a smart contract is uploaded to a blockchain, it becomes:

Immutable: It can never be edited, deleted, or tampered with by anyone—even the person who wrote it.
Trustless: It runs automatically and exactly as written. You do not need to trust a bank, lawyer, or government official to enforce its rules.

The Vending Machine Analogy

Think of a traditional contract like hiring a lawyer: you pay them, wait, and hope they enforce the rules.

A smart contract is like a vending machine: you drop in a coin (input data/tokens), and the machine automatically drops your soda (output code action). There is no intermediary standing in the way.

Let's dive into how the Bayanihan suite uses this technology to support community livelihoods across five core pillars.

Contract 1 of 15

🛡️ 1. QuantumIdentity.sol

Post-Quantum Digital ID & Social Recovery

The Hook

Imagine losing the keys to your house, and the locksmith tells you that you can never enter again, and everything inside is lost forever. In early blockchain systems, losing your private keys meant losing your life savings. How do we build a system that is secure enough to withstand future supercomputers but gentle enough to help you recover your account?

Core Lesson

In Web3, your wallet address is your account. QuantumIdentity.sol is a smart registry that does two things:

Post-Quantum Cryptographic Agility: It features built-in storage slots (PQKey) that can absorb next-generation cryptographic keys (like Crystals-Dilithium) to ensure quantum computers can't hack your account.
Social Recovery: Instead of relying on a password reset button (which requires a centralized company), you nominate a group of Guardians (trusted family, friends, or barangay members). If you lose your keys, a majority of these guardians vote on-chain to move your profile to a new wallet address.

Nominating Guardians

Rule of Thumb: Nominate at least 3-5 guardians (contracts require a minimum of 2).
Diversification: Choose people who do not know each other well or live in different neighborhoods to avoid them colluding to hijack your account.

Contract 2 of 15

📊 2. AIReputationOracle.sol

Off-Chain Character Reference

The Hook

When a local bank decides to lend you money, they look up your credit history. But what if you are a freelancer or a farmer who has never had a bank account? How do you prove you are reliable to someone on the other side of the country?

Core Lesson

An Oracle is a bridge that brings real-world data onto the blockchain. AIReputationOracle.sol takes external data (like customer ratings, on-time deliveries, and community work) and logs a verified Reputation Score (from 0 to 100) on-chain.

Cryptographic Signatures (ECDSA): To prevent malicious actors from falsifying scores, the data must be digitally signed by an authorized validator.

Figure 1.1: Core Trust Infrastructure Interconnectivity

Contract 3 of 15

🏦 3. NationalRewardsTreasury.sol

The Community Safety Vault

The Hook

If a community cooperative has a communal vault, what is to stop one greedy member from showing up with a truck and loading all the sacks of rice at once, leaving nothing for the rest?

Core Lesson

NationalRewardsTreasury.sol is the smart vault that manages the distribution of incentives. It uses:

Rate Limits: It enforces strict caps on how much any single wallet can claim at once.
Authorized Category Allocations: It allocates treasury funds by percentages: a specific percentage goes strictly to farmers, another to OFWs, and another to students. This ensures no single group drains the vault.

Chapter 1 Common Mistakes

Guardian Neglect: Forgetting to update your guardians when a friend changes their phone/wallet, or when a relationship changes.

Self-Recovery Failure: Trying to initiate recovery using your own old wallet. The old wallet is lost; only your guardians can call initiateRecovery().

Chapter 1 Summary

Our digital cooperative's foundational infrastructure runs on three key principles:

Post-Quantum Identity keeps you safe from future hackers and uses trusted neighbors for recovery.
Oracles connect real-life achievements to your digital record.
Treasuries run on automated smart math to distribute community incentives fairly and sustainably.

Trust Setup Quick-Start Checklist

Register identity on QuantumIdentity.sol using a post-quantum public key slot.
Select 3 independent guardians across different circles for social recovery.
Log your first off-chain delivery to trigger the AIReputationOracle score.
Verify your eligibility tier within the NationalRewardsTreasury contract.

Contract 4 of 15

🌾 4. FarmerProsperity.sol

Crop Certificates & Weather Insurance

The Hook

A farmer works hard for three months, only for a typhoon to destroy the crop. The local middleman offers a predatory loan to help them survive. How can Web3 break this cycle?

Core Lesson

FarmerProsperity.sol introduces three powerful Web3 concepts:

Crop NFTs (ERC-1155): When a farmer logs a harvest, the contract mints a unique digital certificate. This token proves they own and produced a specific quantity of crops (organic, climate-friendly, water-conserving).
Forward Sales Escrow: Farmers can list their future harvests for sale. A buyer locks payment tokens inside the contract. Once delivered, the funds release to the farmer, and the NFT goes to the buyer. No middleman needed.
Weather-Indexed Insurance: The farmer pays a small premium into an insurance pool. If a climate oracle registers a disaster (e.g., wind speeds exceeding a typhoon threshold), the contract automatically payouts up to 10x the premium directly to the farmer's wallet without requiring a claims adjuster.

Crop Listing Framework

Step	Action	Actor	On-Chain State
1	Register Harvest	Farmer	NFT Minted + Eco-Rewards Disbursed
2	List Future Harvest	Farmer	NFT Locked in Escrow
3	Purchase	Buyer	Funds Locked in Escrow
4	Confirm Delivery	Buyer/Farmer	NFT to Buyer, Funds to Farmer

Figure 2.1: Farmer-to-Buyer Escrow Settlement Flow

Contract 5 of 15

🐟 5. FisherfolkRewards.sol

Oceans of Data & Catch Verification

The Hook

If a fisher logs that they caught 100 kg of tuna, how do we know they didn't catch endangered reef fish instead, or catch them in a marine sanctuary?

Core Lesson

FisherfolkRewards.sol rewards sustainable fishing through decentralized verification:

Catch Logging: Fisherfolk log the weight, species, and GPS coordinates on-chain.
Peer/Validator Audits: Trusted local wardens (Bantay Dagat) verify the catch's compliance before bonuses are unlocked.
Eco-Multipliers: Catching sustainable species or participating in beach cleanups boosts their on-chain "Impact Score," unlocking treasury rewards.

Eco-Multiplier Example

Standard Catch Bonus: 10 BAYANI.

With Eco-Multiplier (Beach Cleanup + GPS outside marine sanctuary): 1.5x Multiplier = 15 BAYANI.

Contract 6 of 15

☀️ 6. RenewableEnergy.sol

Peer-to-Peer Solar Trading

The Hook

If you install solar panels on your roof, you often have to sell excess energy back to a single monopoly utility grid at a price they dictate. What if you could barter your clean energy credits directly with your neighbors?

Core Lesson

RenewableEnergy.sol handles decentralized smart meter logs:

Generation Logs: Smart meters digitally sign and post energy outputs (kWh) to the blockchain.
Energy Credit Bartering: The contract maintains a ledger of energy credits. Neighbors can trade energy tokens peer-to-peer to pay for power, avoiding central markups.

Chapter 2 Summary

Bayanihan applies smart contracts to physical work: harvesting crops, fishing sustainably, and generating solar energy, connecting physical effort directly to digital rewards.

Contract 7 of 15

🏪 7. MSMEGrowth.sol

Building Small Business Credit Histories

The Hook

A sari-sari store (micro-convenience shop) runs entirely on cash. Because there are no formal records, they can't get a bank loan to expand, forcing them to turn to loan sharks.

Core Lesson

MSMEGrowth.sol creates a formal, trustless business ledger:

Revenue Logging: Small merchants log their daily sales on-chain.
Community Contributions: MSMEs earn reputation points by participating in local charity drives.
Fee Discounts: As they build up positive reviews and revenue history, the contract elevates their tier, granting them lower digital transaction fees and higher credit ratings.

MSME Tier Structure

Tier	On-Chain Sales Required	Escrow Fee Discount	Loan Rate Cap
Basic	0 - 10,000 PHP	0%	12% APR
Silver	10,000+ PHP	25%	8% APR
Gold	50,000+ PHP + Good Rep	50%	5% APR

Contract 8 of 15

💻 8. FreelancerEscrow.sol

Safe Payments for Remote Workers

The Hook

A freelance graphic designer finishes a logo for an international client, only for the client to block them and refuse to pay. Conversely, a client pays a developer upfront, only for the developer to disappear.

Core Lesson

FreelancerEscrow.sol secures payments through a Neutral Escrow Lock:

Milestone Payments: The project budget is broken into phases and locked in the contract before work starts.
Fee Discount by Reputation: High-reputation freelancers get up to a 50% discount on contract escrow fees.
On-Chain Arbitration: If a dispute arises, an elected council of community arbiters reviews the work. The contract automatically executes their split decision.

Escrow Lifecycle

Figure 3.1: Milestone Escrow Dispute Escalation Flow

Escrow Pitfalls

Skipping Milestones: Locking the entire budget in a single milestone defeats the purpose. Break work into small, digestible weekly deliverables.

Contract 9 of 15

🎓 9. EducationRewards.sol

Soulbound Credentials & Scholarships

The Hook

In a world of digital forgery, anyone can copy-paste a certificate or resume. How can we prove a student actually took a class and passed it, without needing to verify with a university registrar every time?

Core Lesson

EducationRewards.sol introduces Soulbound Tokens (SBTs):

Soulbound Credentials: When a student passes an assessment, they receive a non-transferable NFT badge. If they try to sell or transfer it, the contract blocks the transaction. The badge is permanently bound to their digital identity.
Smart Scholarships: Generous donors fund a scholarship pool. The contract automatically distributes stipends to students based on their on-chain badge levels.

Chapter 3 Summary

MSME revenue logging builds formal credit histories, Milestone Escrow protects digital workers, and Soulbound Tokens guarantee credential integrity, enabling digital growth.

Contract 10 of 15

🏛️ 10. BarangayDAO.sol

Democratic Decisions without Whales

The Hook

In typical blockchain voting (DAOs), voting power is determined by the number of tokens you own. This means a single multi-millionaire (a "whale") can outvote 1,000 ordinary community members combined. How do we keep democracy fair?

Core Lesson

BarangayDAO.sol solves this by implementing Voting Power Caps:

Decentralized Autonomous Organization (DAO): An organization run by code, where proposals are submitted and executed by vote.
Democratic Power Cap: No matter how many tokens a wealthy participant stakes, their voting weight is capped. This ensures that infrastructure, scholarship, or emergency funding proposals represent the actual community's voice.

Voting Caps vs Token Weight

Figure 4.1: Democratic Barangay DAO Funding Path

Power Cap Example

Without Cap: Landlord (10,000 tokens) outvotes 50 Tenants (100 tokens each = 5,000 tokens).

With Cap: Max voting weight per address = 200 tokens. Landlord's vote is capped at 200. Tenants count for 5,000. Tenants win.

Contracts 11 & 12 of 15

🏥 11. HealthcareAssistance.sol

Mutual Aid Paluwagan

Traditional health insurance is expensive, full of fine print, and slow to pay. HealthcareAssistance.sol digitizes the traditional Filipino paluwagan (mutual savings club):

Cooperative Savings: Members deposit savings into a mutual pool.
Peer-Reviewed Claims: When a member falls ill, they upload a hospital bill hash. Local validators vote to approve the emergency claim.
Automated Payouts: Once approved, emergency funds release directly to the hospital or the patient's wallet.

🏠 12. HousingCooperative.sol

Crowdfunded Homes

Buying a home requires high-interest bank mortgages. HousingCooperative.sol enables fractional brick-by-brick equity:

Cooperative Construction Pools: The community pools funds to buy land and build homes. Contributors own shares in the project.
On-Chain Mortgages: Borrowers pay monthly installments directly to the contract.

Chapter 4 Summary

The Digital Barangay allows decentralized, democratic organizations to manage community rules, run mutual health funds, and coordinate cooperative housing without massive administrative overhead.

Common Pitfalls

Under-collateralized Paluwagan: Not maintaining enough reserves for peak flu seasons. Establish a minimum baseline liquidity pool inside the healthcare contract.

Barangay Reflective Questions

How does the democratic voting cap protect your local community proposals?
What happens if a validator colludes on a paluwagan claim? (Hint: Oracle Rep Score drops).

Contract 13 of 15

✈️ 13. DiasporaNetwork.sol

Supporting Families Across Borders

The Hook

Overseas Filipino Workers (OFWs) send billions of dollars home every year, but traditional remittance networks charge high transfer fees. Additionally, OFWs have little control over how their remittances are used.

Core Lesson

DiasporaNetwork.sol establishes direct support pools:

Relative Lending Pools: An OFW can fund an interest-bearing lending pool for their relatives back home. The contract handles the repayment logic.
Diaspora Impact Score: OFWs earn rewards and community recognition when their investments fund local jobs or clean energy infrastructure.

Figure 5.1: Diaspora Remittance & Impact Loop

Contract 14 of 15

🏢 14. NationalAssetTokenization.sol

Fractional RWAs with Utility Yields

The Hook

If a community wants to fund a solar park or a public warehouse, they might want to sell shares to the public. However, paying out cash dividends often triggers strict regulatory compliance audits under securities law.

Core Lesson

NationalAssetTokenization.sol tokenizes Real-World Assets (RWAs) using Utility Yields:

Fractional Shares: An asset (like a warehouse) is split into digital shares that citizens can purchase.
Utility Yields (No Cash Dividends): To satisfy SEC regulations, the contract does not distribute cash. Instead, it yields Utility Points that can be burned for discounts (e.g., free warehouse storage space or cheap electricity). This keeps the asset classified as a utility rather than a security.

Contract 15 of 15

🕯️ 15. BayaniLegacy.sol

Inheritance Trusts without Lawyers

The Hook

If a blockchain user unexpectedly passes away, their digital assets are locked forever inside their wallet, lost to their grieving family.

Core Lesson

BayaniLegacy.sol is an automated inheritance vault:

Proof of Life: The owner must interact with the contract regularly (e.g., once every 6 months) to trigger a registerProofOfLife() heartbeat.
Inactivity Trigger: If the owner fails to call the heartbeat before the inactivity timeout expires, the contract unlocks.
Succession Execution: Nominated family members or successors can claim their pre-allocated shares directly from the vault, distributing inheritance automatically and without probate fees.

Chapter 5 Summary

Diaspora pools provide low-cost remittance and credit options, RWA tokenization builds community utility assets, and succession vaults protect wealth across generations.

Reference Book

Web3 Glossary (A - D)

Blockchain: A shared, digital notebook that everyone can view, but no one can erase or alter. It records who owns what.
Smart Contract: A digital vending machine. An automated agreement that executes automatically once its coded rules are met.
Token: A digital unit of value (like game credits) stored on a blockchain. Can represent money (BAYANI), energy credits, or RWA shares.
NFT (Non-Fungible Token): A digital certificate of ownership for a unique item (like a crop harvest certificate or a house deed).
Soulbound Token (SBT): A special type of NFT that cannot be sold or transferred. It is permanently tied to your profile (like a diploma).
DAO (Decentralized Autonomous Organization): A digital cooperative run by smart contracts, where members vote on decisions.

Reference Book

Web3 Glossary (E - Z)

Oracle: A secure bridge that brings external data (like weather conditions or AI reputation scores) onto the blockchain.
Escrow: A neutral third-party lock box. Money is held by the smart contract until the freelancer or farmer delivers their work.
Post-Quantum Cryptography: Advanced security methods that protect your identity and funds from being hacked by future supercomputers.
Gas: A small fee paid to the blockchain network to process your transaction.
Paluwagan (Mutual Pool): A traditional informal saving/credit circle, digitized as an on-chain mutual assistance contract.

Closing Thoughts

Epilogue & Credits

Bayanihan represents the best of us: working together to lift a home, support a neighbor, and feed a community. Web3 provides the digital toolbox to scale this spirit to global, transparent cooperative structures.

By designing smart contracts that focus on local identity, reputation, sustainability, and mutual assistance, we can shape a decentralized economy built for people, not just profits.

Acknowledgements

This e-book is a collective project of the Bayanihan digital nation initiative. Special thanks to the Solidity developers, community organizers, and cooperative farmers who provided feedback on these designs.

"Sama-sama sa pagsulong ng komunidad sa tulong ng teknolohiya."

Bayanihan Quantum Commerce Chain

A Plain-English Guide to Web3 for Communities

Can a blockchain strengthen community bonds? Can smart contracts help a farmer sell their crops, or a neighborhood fund its own clinics? This guidebook outlines the 15 Solidity contracts of the Bayanihan suite, detailing a decentralized commerce chain designed for real-world impact.

Post-Quantum Cryptography Dilithium / Crystals

Smart Contract Standards ERC-1155 / Soulbound

Table of Contents

What is Web3 & Why Bayanihan?

How the Internet Has Evolved

The Core Engine: The Smart Contract

🛡️ 1. QuantumIdentity.sol

The Hook

Core Lesson

Nominating Guardians

📊 2. AIReputationOracle.sol

The Hook

Core Lesson

🏦 3. NationalRewardsTreasury.sol

The Hook

Core Lesson

Chapter 1 Summary

🌾 4. FarmerProsperity.sol

The Hook

Core Lesson

Crop Listing Framework

🐟 5. FisherfolkRewards.sol

The Hook

Core Lesson

☀️ 6. RenewableEnergy.sol

The Hook

Core Lesson

Chapter 2 Summary

🏪 7. MSMEGrowth.sol

The Hook

Core Lesson

MSME Tier Structure

💻 8. FreelancerEscrow.sol

The Hook

Core Lesson

Escrow Lifecycle

🎓 9. EducationRewards.sol

The Hook

Core Lesson

Chapter 3 Summary

🏛️ 10. BarangayDAO.sol

The Hook

Core Lesson

Voting Caps vs Token Weight

🏥 11. HealthcareAssistance.sol

🏠 12. HousingCooperative.sol

Chapter 4 Summary

✈️ 13. DiasporaNetwork.sol

The Hook

Core Lesson

🏢 14. NationalAssetTokenization.sol

The Hook

Core Lesson

🕯️ 15. BayaniLegacy.sol

The Hook

Core Lesson

Chapter 5 Summary

Web3 Glossary (A - D)

Web3 Glossary (E - Z)

Epilogue & Credits

A Plain-English Guide to Web3 for Communities