Blockplot Protocol Docs

Overview

Blockplot Soroban is a compliant Real World Asset (RWA) tokenization platform that enables users globally to invest in fractionalized, yield-bearing assets such as real estate, infrastructure, and treasury-backed instruments.

The platform uses Soroban smart contracts on the Stellar network to tokenize off-chain assets into transferable digital ownership units while enforcing compliance, identity verification, governance rules, and reward distribution entirely on-chain.

Blockplot lowers the entry barrier to global asset ownership by enabling investments from as little as $1, while providing liquidity, transparent reward distribution, and decentralized governance.

Problem Statement

Traditional real-world asset investing suffers from structural barriers that exclude the majority of the world:

Blockplot solves these challenges through compliant fractional ownership infrastructure built on Stellar — where transactions settle in seconds for fractions of a cent.

Architecture

Blockplot is composed of three layers: on-chain contracts, an off-chain API, and the user-facing web application.

┌─────────────────────────────────────────────────────────┐
│                    blockplot-frontend                    │
│        Next.js · Tailwind · Freighter SDK               │
└───────────────────────┬─────────────────────────────────┘
                        │ REST
┌───────────────────────▼─────────────────────────────────┐
│                    blockplot-backend                     │
│        NestJS · Identity · Assets · Yield modules       │
└───────────────────────┬─────────────────────────────────┘
                        │ Soroban RPC
┌───────────────────────▼─────────────────────────────────┐
│                   blockplot-contracts                    │
│                                                         │
│  BlockplotID ──► FractionalAsset ──► PublicSale         │
│                        │                                │
│                  YieldDistributor                       │
│                                                         │
│              Stellar · Soroban Runtime                  │
└─────────────────────────────────────────────────────────┘

Contract Interaction Flow

User wallet
    │
    ├─ 1. identity check  →  BlockplotID.is_verified()
    │
    ├─ 2. purchase        →  PublicSale.purchase()
    │                              │
    │                        FractionalAsset.mint()
    │
    └─ 3. claim yield     →  YieldDistributor.claim()

Smart Contracts

All contracts are written in Rust targeting the Soroban WASM runtime. The workspace lives at github.com/Stellar-Land/blockplot-contracts.

None ──► Pending ──► Verified
                            │
                         Revoked

// Approve a user on testnet
stellar contract invoke \
  --id <BLOCKPLOT_ID_CONTRACT> \
  --source admin \
  --network testnet \
  -- set_status \
  --user GABC...XYZ \
  --status Verified

// 1. Check identity
const verified = await contract.is_verified(walletAddress)
if (!verified) throw new Error("KYC required")

// 2. Call purchase — returns token count
const tokens = await publicSale.purchase(buyer, paymentAmount)

// 3. Mint the tokens to the buyer
await fractionalAsset.mint(buyer, tokens)

claimable = (total_deposited × allocation_bps) / 10_000

// Example: holder owns 5% of the asset (500 bps)
// Total deposited: $10,000
// Claimable: (10_000 × 500) / 10_000 = $500

User Flows

1 — Onboarding

User connects Freighter wallet
        │
        ▼
User submits KYC form (name, country, ID)
        │
        ▼
Backend stores submission, status = "pending"
        │
        ▼
Compliance admin reviews and calls set_status(..., Verified)
        │
        ▼
User gains protocol access — can purchase asset tokens

2 — Investing in an Asset

User browses asset catalog → selects an asset
        │
        ▼
Protocol checks:  BlockplotID.is_verified(user) ✓
                  PublicSale.is_active()         ✓
                  payment ≥ token_price          ✓
        │
        ▼
PublicSale.purchase(buyer, amount)  →  returns token_count
        │
        ▼
FractionalAsset.mint(buyer, token_count)
        │
        ▼
Tokens appear in user's portfolio

3 — Claiming Yield

Asset generates income (rent collected, yield received)
        │
        ▼
Admin calls YieldDistributor.deposit(caller, income_amount)
        │
        ▼
Backend indexes balance_of for all holders
Computes each holder's allocation_bps
        │
        ▼
Admin calls YieldDistributor.allocate(holder, bps) for each holder
        │
        ▼
User opens /claim dashboard
User calls YieldDistributor.claim(wallet) via Freighter
        │
        ▼
Rewards land in user's Stellar wallet

API Reference

The backend exposes a REST API at http://localhost:3000 in development. All endpoints return JSON.

Identity — /identity

// Submit KYC
POST /identity/submit
{
  "walletAddress": "GABC...XYZ",
  "kycData": { "name": "Alice", "country": "NG" }
}

// Response
{ "walletAddress": "GABC...XYZ", "status": "pending", "updatedAt": "..." }

// Approve (admin)
PATCH /identity/GABC...XYZ/approve
// → { "status": "verified", "updatedAt": "..." }

Assets — /assets

// Create asset
POST /assets
{
  "name": "Lagos Commercial Tower A",
  "totalSupply": 1000000,
  "ownerCap": 100000,
  "priceUsd": 1
}

// Response
{
  "id": "uuid-here",
  "name": "Lagos Commercial Tower A",
  "totalSupply": 1000000,
  "ownerCap": 100000,
  "priceUsd": 1,
  "createdAt": "..."
}

Yield — /yield

// Deposit yield
POST /yield/asset-id-123/deposit
{ "amount": 5000 }

// Check claimable
GET /yield/asset-id-123/claimable/GABC...XYZ
// → { "walletAddress": "GABC...XYZ", "claimable": 250 }

// Claim
POST /yield/asset-id-123/claim/GABC...XYZ
// → { "walletAddress": "GABC...XYZ", "claimed": 250 }

Wallet Integration

Blockplot uses Freighter — the official Stellar browser extension wallet. Install it from freighter.app before connecting.

Connecting a wallet

import { isConnected, requestAccess, getAddress } from "@stellar/freighter-api"

// Check if Freighter is installed
const { isConnected: installed } = await isConnected()

// Request access — opens the Freighter popup
const { address, error } = await requestAccess()
if (error) throw new Error(error)

console.log("Connected:", address)
// → "GABC...XYZ"

Checking an existing session

// Silently restore a previous connection (no popup)
const { address } = await getAddress()
if (address) console.log("Already connected:", address)

Signing a transaction

import { signTransaction } from "@stellar/freighter-api"
import { Transaction } from "@stellar/stellar-sdk"

const { signedTxXdr, error } = await signTransaction(unsignedXDR, {
  networkPassphrase: Networks.TESTNET,
})
if (error) throw new Error(error)

// Submit the signed XDR to Stellar
await server.submitTransaction(TransactionBuilder.fromXDR(signedTxXdr, Networks.TESTNET))

Supported wallets

Roadmap

Phase 1 — MVP (Current)

Phase 2 — Expansion

Phase 3 — Advanced RWA Infrastructure