Decentral Commons (Farm Exchange)

A vendor-neutral, SPV-first BSV application compliant with BRC-100.

Decentral Commons

A Metanet-native application for community governance and marketplace.

Metanet & SPV Architecture

This application is built following strictly peer-to-peer SPV principles on Bitcoin SV.

• No Centralized Indexers: We do not rely on block explorers or centralized APIs for transaction history. All state is derived from the user's wallet via SPV.
• Wallet-First: We use @bsv/sdk to connect to local Metanet wallets (like BSV Desktop) for identity and signing.
• Overlay Networks: We support SHIP/SLAP overlay schemes for service discovery and routing.
• UHRP: File metadata is resolved via UHRP (Universal Hash Resolution Protocol) storage servers.

Setup & Development (LARS)

We use the LARS (Local App Runtime System) pattern for development.

1. Install Dependencies:

   npm install
   cd frontend && npm install

2. Run Locally:

   npm run dev

   This starts the Vite development server. Ensure your local BSV wallet is running and accessible (default: http://localhost:3301/v1 or via window injection).

3. Wallet Connection: The app automatically attempts to detect a local Metanet client. If found, it will prompt for authentication.

   • Diagnostics: Use the "Diagnostics" panel in the wallet card to test connectivity (XDM and Window API).

Deployment (CARS)

For cloud deployment (CARS - Cloud App Runtime System), refer to deployment-info.json.

1. Build:

   npm run build

2. Deploy: Configure your CARS provider credentials and run:

   # Example deployment command (depends on your CARS provider toolchain)
   bsv-deploy --target=cloud

Overlay URLs & Facilitators

The app handles various URI schemes beyond https://.

• SHIP: https+bsvauth+smf:// (Authenticated, secure message format)
• SLAP: wss:// (Real-time streams)

Adding Facilitators: To support new schemes, register a facilitator in frontend/utils/overlayUrl.ts:

import { registerFacilitator } from './utils/overlayUrl';

registerFacilitator({
    scheme: 'myscheme',
    handle: async (parts) => {
        // Handle the request
    }
});

UHRP Storage

Files are referenced via uhrp:// URLs. The UhrpService resolves these to metadata (name, size, expiry) by querying a storage server.

• Ensure your wallet is connected to sign the lookup request.
• Expired content will be rejected automatically.

Getting Started

Prerequisites

• Node.js
• A BRC-100 compliant BSV wallet (e.g., Yours Wallet, Panda Wallet, or BRC-100 reference wallet).

Installation

npm install

Running Locally (LARS)

To start the local development environment:

npm run lars
# OR
npm run start

This will start the frontend application at http://localhost:5173.

Deployment (CARS)

To build and deploy the application:

npm run build
npm run deploy

Architecture & Standards

BRC-100 Wallet Integration

The app uses the @bsv/sdk WalletClient to interact with the user's wallet. This ensures compatibility with any wallet that implements the BRC-100 standard.

• Connection: Request permission to access the user's identity.
• Transactions: Create and sign transactions directly in the wallet.
• UTXOs: Managed by the wallet, the app requests spends.

SPV & Proofs

Transactions are broadcast with the expectation of receiving an SPV proof (Merkle proof).

• Lifecycle: Pending -> Proved -> Confirmed.
• Formats: Supports standard Merkle proofs (BRC-10, BRC-58, etc.).
• No Indexers: The app does not query a block explorer API for balance or history; it relies on the wallet and local state verified by proofs.

No-Address UX (BRC-49)

Users never see or paste raw Bitcoin addresses. All payments are handled via:

• Payment Requests: The app constructs a transaction or request and hands it to the wallet.
• BRC-100 Wallet Identity: Users interact with cryptographic BRC-100 identity keys and WalletClient.

Overlay Services

The app is designed to interact with Overlay Services (SHIP/SLAP) for transaction submission and lookup, configured via deployment-info.json.

Project Structure

• deployment-info.json: BRC-102 compliant deployment configuration.
• frontend/: React application source code.
• frontend/services/WalletService.ts: BRC-100 Wallet Client abstraction.
• frontend/context/WalletContext.tsx: React context for wallet state.

Configuration

The application can be configured via deployment-info.json to point to different networks (mainnet/testnet) and overlay providers.