§ 01Context
This is a mechanism prototype for fractional real-world-asset crowdfunding, built and labeled honestly as one. A real asset is represented on-chain as a deed NFT with its own goal-based campaign; backers contribute and, on a successful raise, receive pro-rata fractional ERC-20 shares of that asset. The shares are gated: only KYC-verified addresses can ever hold them. It runs entirely on a testnet — no real funds, no securities.
§ 02Challenge
Make compliance programmable — guarantee that only verified investors can hold shares — without dragging in a heavyweight standard. Build an escrow that handles success, over-funding and refunds safely, with no way to drain it. Keep the whole thing backend-free so reads come straight from the chain. And build all of it in a weekend.
Compliance lives in one function — a single hook that reverts for any address not on the allowlist, across mints, transfers and burns.— Contract design
§ 03The contracts
- KYC registry. An owner-managed allowlist of verified investors — a clean stand-in for a production identity provider.
- Deed NFT. One ERC-721 token per asset, carrying only its identity and a metadata pointer.
- Shares (KYC-gated ERC-20). Whole-unit shares whose transfer hook reverts for any non-verified party — the single chokepoint that enforces “only verified addresses hold a balance” across mint, transfer and burn, while letting mint and burn themselves through.
- Crowdfund escrow. Contribute → claim shares (pro-rata) → withdraw, with refunds on failure; reentrancy-guarded, checks-effects-interactions on every money path, and a state machine derived from the amount raised rather than stored, so over-funding is blocked and success/refund branch cleanly.
One transfer hook enforces the allowlist across every movement of shares — the lightweight stand-in for a permissioned-token standard.
Separate claim / withdraw / refund paths, each reentrancy-guarded, with state derived from the raise.
Deeds hold only identity on-chain; rich metadata lives off-chain on IPFS — no backend, reads direct from chain.
Both stacks proven in throwaway spikes first, then lifted in — so the timed build was execution, not setup.
§ 04Rapid build
The build was fast because the risk was retired first. Both stacks were proven in gitignored spikes — the contracts spike hit 7/7 tests with a green deploy simulation; the web spike resolved the thorny peer-dependency compatibility between the wallet libraries and got a clean build — and only then were they promoted into the real repository. Contract types flow from the compiler's output straight into the frontend hooks, so the frontend and contracts never drift.
§ 05Result
- Four contracts, deployed and verified on an L2 testnet, with 7/7 tests covering the KYC gate, escrow math and refunds.
- Compliance in one function. A single hook guarantees only verified addresses hold shares.
- A safe, backend-free dApp. Non-custodial, reads direct from chain, one-command full deploy.
- An honest base to grow on. A clean mechanism ready to graduate to a production permissioned-token standard.
— Testnet prototype · no real funds or securities. Prototyping on-chain? Start a conversation.
