How the city gets to work.

01 Start

#Overview and limits

What Tsubo Protocol is, what it is not, and the state of this deployment.

Tsubo Protocol turns idle city spaces such as rooftops, vacant houses, idle lots, parking bays, storage rooms and wall panels into programmable usage and revenue rights. A right is modelled as space x time x usage x cash flow: which part of a building, for which purpose, during which period, with which economic claim.

People discover spaces on a 3D city map, fund projects through fixed-price primary offers, trade rights on a secondary market, claim deposited revenue and combine compatible revenue rights into fully backed baskets.

• The main application is connected to deployed Ethereum mainnet contracts. Wallet signatures can spend real ETH.
• The separate /demo experience remains simulated and wallet-free. City showcase examples are illustrative, not evidence of real registered assets.
• No smart-contract audit is claimed. Do not treat any contract as production-ready without an independent audit.
• Lending and borrowing are shown as coming soon. Additional finance contracts are optional and may not be deployed in any given environment.
• Selling revenue shares to the public is likely a regulated securities activity in Japan, Indonesia and most other jurisdictions. Obtain legal advice before any live offering.

02 Start

#Getting started

Three entry points and how to choose between them.

1. Open /demo to try every flow without a wallet. Use the Demo role selector to switch between Owner A, Investor B, Investor C and Demo verifier.
2. Open /app for Ethereum mainnet. Connect your wallet only when you intend to sign real transactions and pay ETH gas.
3. Use Quick tour in the application navigation for a guided walkthrough of the main screens.
4. Developers: run npm install, then npm run dev. Demo mode is the default and serves the app locally on port 3000.

03 Using the app

#Explore and the map

The city view, filters, lenses and asset details.

Explore is the default view. It renders real geographic map tiles and OpenStreetMap 3D buildings from OpenFreeMap, which requires no API key. A different MapLibre style can be configured by the operator. The buildings and streets are real; the assets placed on them are simulated test assets, not offers on real properties.

• Asset type filter: show all assets or a single kind such as Rooftop or Vacant house.
• Stage filter: narrow by lifecycle stage, for example funding, active or secondary market.
• Owned only: show assets where the active account holds a right. Available once balances have loaded.
• Funding only: show assets with an open primary offer.
• Dormant lens and X-ray: highlight dormant-space candidates from an illustrative dataset and reveal building structure.
• Select a marker to open its detail panel with the project overview, rights, terms, offers and activity history.

If WebGL is unavailable or the 3D map times out, the app switches to a 2D OpenStreetMap view. You can still pan, zoom, select asset markers and pick a location. Building extrusions and 3D-only overlays are not available in 2D. Retry 3D map attempts the original renderer again.

04 Using the app

#Dashboard

A data-first overview of the market.

The dashboard (?view=dashboard) replaces the full-screen map with an overview of registered assets, active rights, open funding projects and recent activity. It also provides the asset directory with its own search and filters. Selecting an asset there opens it on the map.

Data refreshes automatically. In demo mode it comes from the in-browser simulation; with a connected backend it is read from indexed chain data and refreshed on new events. If an update fails, previously loaded data is kept and a retry is offered.

05 Using the app

#Markets: primary, secondary and funding

How rights are offered, bought and resold.

1. Review the right's terms and tick the acceptance checkbox. Purchases are blocked until terms are accepted.
2. Enter a whole quantity within the remaining supply.
3. Approve the settlement token amount for the marketplace, then confirm the purchase.

• Rights with the Nontransferable policy, expired rights and rights not yet verified cannot be listed or bought.
• You cannot buy your own listing. If an offer changes while you review it, the purchase is rejected and must be reviewed again.
• Prices are shown in the configured settlement currency. Test deployments use a valueless MockJPY token.
• An optional card checkout exists for test environments only and disappears on mainnet configurations.

06 Using the app

#ENS Index and namespaces

Readable names for spaces and rights.

The ENS Index (?view=ens) presents a readable name hierarchy for districts, spaces and rights, so that a right can be referenced by a human-readable name rather than only a token ID. A namespace authority contract links names to on-chain rights.

07 Using the app

#My assets, portfolio and revenue claims

Holdings, listings and claimable income.

My assets (?view=assets) lists the rights and basket shares held by the active account, the listings it has created and the revenue it can claim.

• Revenue is only claimable after an operator actually deposits it into the revenue vault for a right. Nothing is accrued automatically and no yield is guaranteed.
• Deposits are distributed pro rata to holders, with checkpoints taken when rights move so that past revenue stays with the holder at the time.
• Claim transfers the claimable settlement tokens to the holder's wallet.
• Holders can list rights for resale from this view.

08 Using the app

#Compose and baskets

Combining revenue rights into fully backed basket shares.

Compose lets a holder combine several compatible revenue rights into a basket. Basket shares are fully backed: the underlying rights are held by the basket vault, and shares can be redeemed for them.

• Compatible rights are Revenue Share rights with the Open transfer policy, verified or active, not expired, held by you and not already in a basket.
• Name the basket, select rights and units per share, then deposit and mint shares.
• Revenue received by the underlying rights can be claimed by basket shareholders.
• Basket shares can be listed on the secondary market or redeemed for the underlying rights.

09 Rights lifecycle

#Registration, review, issuance and activation

From an idle space to an operating, revenue-bearing right.

1. Register the asset. The issuer submits location, kind, area, capacity, overview, project assumptions and an evidence reference. Review the metadata and evidence before submitting.
2. Request verification. A verifier reviews the evidence and approves or rejects the asset.
3. Issue a right. For a verified asset the issuer defines right type (Usage Right, Revenue Share, Lease, Other), supply, terms, start and end dates, transfer policy (Open, Allowlist, Nontransferable), scope (Rooftop, Interior, Wall, Land, Whole asset), purpose and exclusivity. Encoded terms and evidence must fit within the 4 KB limit.
4. Verify the right. The verifier checks the terms. Exclusive rights cannot overlap the same scope and period on one asset.
5. Fund and list. Verified rights can be offered through funding or primary listings.
6. Activate. When the project is operating, the verifier activates the right. Revenue deposits can then be distributed.
7. Close. A verifier can close a right at the end of its life.

10 Rights lifecycle

#Roles and permissions

Who can do what.

In /demo, roles are switched with the Demo role selector. With a real wallet, the app reads VERIFIER_ROLE from the registry and rights contracts and hides verifier actions for other accounts. The contracts remain the final authority and reject unauthorised calls.

11 Wallets and networks

#Connecting a wallet with Reown

Connect, QR, cancel, account, network and disconnect.

Tsubo uses Reown AppKit. Detected browser wallets (EIP-6963) and mobile wallets through a WalletConnect QR code are supported. Connecting never signs a message or submits a transaction. Email and social login are not used and no embedded wallet is created.

1. Select Connect wallet in /app to open the wallet panel.
2. Select Connect wallet with Reown, then choose a browser wallet or the WalletConnect option to scan a QR code with a mobile wallet.
3. Approve the connection in the wallet, or cancel. Closing the connection modal returns you to the app without submitting a transaction.
4. The app checks the selected account and network. If the wallet is on another network it asks to switch to, or add, the configured network.
5. Changing accounts in the wallet clears the previous connection state. Disconnect clears local state and ends the Reown session.

• Allowed origins: the Reown dashboard only accepts connections from origins listed for the project. Add the exact development and published origins shown in the browser address bar, including scheme.
• Propagation: allowlist changes can take around 15 minutes to take effect. Retry after waiting before assuming a misconfiguration.
• The project ID is a public value. Private keys, seed phrases and server secrets must never be placed in any public environment variable.
• Reown and the selected wallet process connection information, including the app origin, public wallet address and network. Network requests can also expose connection metadata such as an IP address. Analytics, swaps and onramp are disabled. Private keys stay in the wallet.

12 Wallets and networks

#Demo, testnet and mainnet

What each mode does and what is active now.

The main application uses Ethereum mainnet, chain ID 1, and native ETH for settlement and gas. Review the network, recipient, amount and transaction details before signing. /demo remains a separate wallet-free simulation.

13 Technical

#Architecture and contracts

How the app and contracts fit together.

The web app is built with Next.js, React and MapLibre. In testnet or mainnet mode it reads indexed chain data through MultiBaas and sends transactions from the connected wallet. Contracts are written in Solidity and tested with Foundry.

14 Technical

#Deployment prerequisites

What must be in place before a real network launch.

• Set the app mode, chain ID and a reachable RPC URL together, and update contract addresses and backend configuration whenever the network changes.
• Deploy contracts with the testnet script (with MockJPY) or the mainnet script (real stablecoin and multisig handoff).
• Link contracts to the indexer and configure event notifications.
• Configure the Reown project ID and allowed origins, then rebuild. Public environment values are embedded at build time.
• Before mainnet: legal review, an independent smart-contract audit, a multisig admin, and an end-to-end test with a real wallet and a small testnet transaction.

15 Reference

#Safety

Habits that protect users.

• Never share a seed phrase or private key. Tsubo never asks for them.
• Read every wallet prompt. Approvals grant the marketplace or vault permission to move specific tokens.
• Check the network shown in your wallet matches the network shown in the app.
• Treat all demo and testnet assets as worthless and illustrative.

16 Reference

#Troubleshooting

Common problems and fixes.

17 Reference

#Glossary

Terms used across Tsubo.