A decentralized protocol on Sui that lets retail investors pool USDC to fund vetted real-world projects (housing, machinery, trade finance, agriculture, energy, infrastructure) and receive digital deeds that pay yield — with milestone-escrowed funding, validator-staked legal attestation, and slashing-backed accountability.
This is the repo-level summary: why Gally exists, how the deeds and yield math work, and how to run it. Each component has its own README with the deep detail.
Real-world-asset (RWA) yield is mostly closed to retail: deals are large, illiquid, and require trusting an operator to actually pay out. Gally makes every trust assumption either removed, collateralized, or legally bound, so ordinary investors can fund real projects and earn from them safely. Security is dual-layer — on-chain code for mathematical safety, plus an off-chain, court-enforceable Smart Trust for legal enforcement (code + courts).
- Pooled, all-or-nothing funding. Investors contribute USDC into an on-chain escrow. The raise either reaches its goal and converts to deeds, or it fails and everyone refunds in full — capital is never stranded.
- Milestone-escrowed release. A funded project's money is not handed to the builder up front. It sits in escrow and is released tranche-by-tranche, each one gated by a validator-approved proof with a hard deadline. Miss a deadline → default & compensation path.
- The Smart Trust (code + courts). Every asset is bound by a legally binding, court-enforceable contract that ties the operating entity and the real asset to the deeds — defining rights, operation, tax and compliance. The on-chain numbers are its digital twin. So the tokens are receipts for a legally defensible reality, not just numbers on a screen.
- Accountability by stake. Validators are a decentralized legal oracle: they lock USDC to vouch for an asset's Smart Trust (its legal strength and ongoing compliance). Vouching for fraud or letting the legal documents go stale gets them slashed and investors compensated. Anyone can post a bond to dispute a vouch — including the Smart Trust's legal validity — and a jury votes on it.
- Self-custody, always. Every investor action is permissionless. Even under an emergency pause, exits (refund, claim, unwrap, redeem) always work — the protocol can never trap your funds.
Trust thesis in one line: you don't blindly trust the operator — you trust a validator who has staked real capital to vouch for the asset's legally binding Smart Trust, backed by an admin trusted only with parameters, never with your money.
When a raise succeeds, your contribution becomes a deed: a transferable, composable on-chain object where 1 share = 1 USDC of principal. A project's funding goal is its total deed supply, which is what keeps share accounting exact. Each deed carries its own unclaimed-yield bookkeeping, so selling or transferring it moves exactly its pending yield with it.
When a project earns money it deposits gross revenue; the contract automatically routes the
investors' cut into a single global index instead of iterating over holders. For an investor
portion
Each deed remembers the index value at its last claim, so what you're owed is always just the difference since then:
All of this is u128 fixed-point, multiply-before-divide, and floors in the protocol's favor —
the rounding dust stays in the reward pool as a solvency buffer, so the pool always covers what it
owes.
A deed can be wrapped into a plain Coin<T> (burn the deed, mint the coin) for full DeFi
liquidity — instantly tradable on a DEX or usable as collateral — and unwrapped back. The coin's
supply can never exceed wrapped deeds, because the only mint authority lives inside the protocol
forever and the only way to mint is to wrap.
The trade-off: only unwrapped deeds earn yield. The index denominator
stateDiagram-v2
[*] --> PENDING_VOUCH : entity lists a project
PENDING_VOUCH --> FUNDING : validator vouches & locks stake
FUNDING --> FUNDED : raise hits goal → receipts become deeds
FUNDING --> FAILED : deadline missed → everyone refunds
FUNDED --> EXECUTING : capital released tranche-by-tranche
EXECUTING --> OPERATIONAL : final tranche released → revenue & yield flow
EXECUTING --> DEFAULTED : tranche deadline missed
OPERATIONAL --> CLOSED : term complete / wind-down
DEFAULTED --> COMPENSATING : entity collateral + escrow seized
COMPENSATING --> CLOSED : investors compensated, redemptions open
Every state that holds funds at risk has a permissionless, never-pausable exit (refund, claim, unwrap, sweep, redeem).
As an investor you contribute to a FUNDING project, claim your deeds when it funds, claim yield
while it operates, optionally wrap/unwrap for liquidity, and refund or redeem to exit. As a
challenger you can dispute a validator's vouch by posting a bond. All of this is done from the
explorer with a connected wallet — the app builds the transaction, your wallet signs it, and it never
holds your keys.
Bring the whole stack up end-to-end with one command:
| Target | Command |
|---|---|
| Local Sui node | ./run_stack.sh --soak 40 |
| Official Sui Devnet | ./run_devnet.sh |
Each publishes the contracts, starts the indexer, seeds demo data, and runs an activity bot so the explorer fills with live, continuously-updating data. See each component's README for its own runbook.
The protocol is published on Sui Devnet (RPC https://fullnode.devnet.sui.io:443):
| Object | ID |
|---|---|
gally_core package |
0x154f007808084283212118536cf212c997abc5aa8bfc7ccdc3cb546bb3680e74 |
usdc package |
0x05aebd94af5bcde02c41b18a6eb62ceb0fdee27ed42b12a15e7c43e3fc09ca9b |
gally_mock_faucet package |
0xccf91720b4200a19bd310fda56e2a7c7120ee9b2b6d28bc0092342eaa368017b |
ProtocolConfig (shared) |
0xe5c1c11d59e9ecdb02787f274adb1ab6cf0a2179a628144decb326cf6368fcaf |
MockFaucet (shared) |
0xf06c0ac5303bb542a5077af84826cbea1cf5f61e09c4ef3a0af307378a7b4880 |
⚠️ Sui Devnet is periodically wiped (≈ weekly). After a reset these IDs go stale — re-run./run_devnet.shto republish and the new IDs are written back toconfig.toml.
Gally is a monorepo of cooperating components across three layers. The chain is the only IPC — components talk only by reading/writing on-chain state and events; none calls another's API.
flowchart LR
subgraph chain["On-chain (Sui Move)"]
core["gally_core"]
end
core -- events --> idx["Backend Indexer<br/>(Postgres + REST/WS)"]
idx --> fe["frontend-explorer<br/>(explorer + dApp)"]
core -. live object reads .-> fe
fe -- "signed transactions" --> core
bot["Live Simulation Bot"] -- "drives real activity" --> core
| Directory | Role |
|---|---|
gally_core/ |
The protocol: config, validators, asset lifecycle, deeds, yield engine, wrap machine, disputes |
entity_token_template/ |
One-shot per-project token package; hands a virgin mint authority to the protocol at finalize |
usdc/ |
The settlement coin type usdc::usdc::USDC — Circle's real USDC on mainnet, a mintable mock elsewhere |
gally_mock_faucet/ |
Shared faucet that vends test USDC (simulation only — never on mainnet) |
Backend Indexer/ |
Ingests every event into Postgres; serves the read API (REST + WebSocket + object proxy) |
frontend-explorer/ |
Public block explorer and investor dApp |
Live Simulation Bot/ |
Publishes the stack and drives continuous real activity so the explorer comes alive |
Per-component build/test:
| Component | Commands |
|---|---|
gally_core / gally_mock_faucet / usdc (Move) |
sui move build && sui move test |
Backend Indexer / Live Simulation Bot (Rust) |
cargo build && cargo test |
frontend-explorer (Next.js) |
pnpm typecheck && pnpm lint && pnpm build && pnpm test |
As of 2026-06, every component is feature-complete with green test suites — the protocol, the per-entity token, the backend indexer, the frontend explorer (live read + wallet transactions), and the live-simulation bot (through Sui Devnet onboarding). Remaining toward production: a real document (Walrus) layer and a mainnet publish.