Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.
The vault — encrypted 3D models gated by an on-chain BNB Chain purchase
The vault, at three.ws/vault, sells access to
encrypted 3D models: sellers list an encrypted GLB, buyers pay on-chain and
receive the key to decrypt and view it. Buying one is a real BSC transaction
against a real smart contract, which triggers a real cross-chain call into
Greenfield's programmable storage: a genuinely unique capability BNB Chain
has that Ethereum L1, Base, and (mostly) Solana don't (hub addresses and
their verification are recorded in contracts/DEPLOYMENTS.md). This page is for
developers: it explains what the vault is, how it's built, and how to
reproduce the proof yourself. Everything here is real code against real
endpoints; nothing is mocked.
1. Why this only works on BNB Chain
Greenfield is a separate data-availability chain, but BSC contracts can
program its storage permissions directly — a BSC contract can call
PermissionHub.createPolicy(...) and grant an address read access to a
specific Greenfield object, cross-chain, with the result settling back
asynchronously as a real minted policy id. No other chain we've built on
lets a smart contract control object-level storage permissions on a separate
chain like this. The trade-off, and the reason this page surfaces it
honestly instead of hiding it: that cross-chain call is genuinely
asynchronous — a purchase confirms on BSC in ~0.45s, but the Greenfield
grant settles a few blocks later. /vault shows "granting access on
Greenfield…" for that window rather than faking an instant unlock.
2. Architecture
| Layer | Where |
|---|---|
| Contract | contracts/src/GreenfieldVault.sol — list/buy/revoke/withdraw, real IPermissionHub/ICrossChain/IGnfdAccessControl interfaces mirrored from bnb-chain/greenfield-contracts. Deploy record: contracts/DEPLOYMENTS.md. |
| Upload (seller-side) | api/bnb/vault-upload.js — encrypts a GLB (AES-256-GCM, fresh random content key per object), uploads ciphertext + a public manifest to Greenfield. |
| Manifest wire format | specs/vault-manifest.md — the JSON schema every reader/writer agrees on. |
| Buyer API | api/vault/list.js, status.js, unlock.js, download.js, buy-policy-data.js |
| Crypto | Server: api/_lib/bnb/vault-crypto.js (Node crypto AES-256-GCM + @noble/curves ECIES). Browser: src/bnb/vault-crypto-browser.js (Web Crypto + @noble/curves — byte-identical wire format). |
| UI | pages/vault.html + src/vault.js → /vault; buy calldata src/bnb/vault-buy.js; pure FSM helpers src/vault-fsm.js |
3. The buyer flow
- Browse.
GET /api/vault/listfolds the contract'sListed/Delistedevents into the active listing set and joins each with its Greenfield manifest for display metadata. AcontractDeployed:falseor 0-listings response renders as a clean, honest empty state — never an error. - Buy. The page needs a buyer identity that can later prove control of
its own raw secp256k1 private key — not just sign a message — because
unlocking uses ECIES key-wrapping to the buyer's own public key
(
wrapKey/unwrapKey), and a browser-extension wallet like MetaMask deliberately never exposes that raw key to a page. So the buyer identity is a local session key (src/bnb/vault-session.js) — generated once client-side, persisted tolocalStorage, the same patternsrc/agora/onchain-presence.jsalready established for prompt 16's on-chain presence toggle. MetaMask's only role is funding that session key with a plain tBNB transfer, or signing a seller's ownlist()transaction (sellers don't need ECIES, so they use a directly-connected wallet). The session key then sends a realbuy(objectId, policyData)transaction — gasless via MegaFuel when sponsorable, self-pay otherwise (sendGasless, prompt 02's fallback pattern) — carryingprice + the livequoteRelayFee()`. - Settle.
GET /api/vault/statuspollssaleIdOf/salesfresh on every call and derivesunlisted | available | pending-grant | unlocked.pending-grantmeans the purchase confirmed but Greenfield's cross-chain ack hasn't settled yet — shown honestly, with a bounded-backoff poll and a manual "check again" once it's been a while. - Unlock. The session key signs a canonical EIP-191 message
(
api/_lib/bnb/vault-unlock-message.js) proving control of the buyer address.POST /api/vault/unlockverifies it, checks the on-chain sale isGranted, and — the key design decision — reuses that same signature to recover the buyer's real secp256k1 public key (viem'srecoverPublicKey), so there's no separate "register your vault pubkey" step. It re-wraps the object's content key to that public key and returns it, alongside a short-lived download token (api/_lib/bnb/vault-download-token.js). The raw content key and plaintext GLB are never returned by the server. - View. The browser fetches ciphertext via
GET /api/vault/download, unwraps the content key with its own raw private key (src/bnb/vault-crypto-browser.js'sunwrapKey, Web Crypto +@noble/curves), decrypts (decryptGlb, AES-256-GCM, sha256-verified against the manifest), and renders the plaintext GLB in<model-viewer>from aBlobURL — the decrypted bytes never touch the network again.
Managing the session key from the page
The strip above the grid is the whole surface for the buyer identity, and
every control on it is in-page (no browser alert/prompt):
- Copy address puts the session address on the clipboard so it can be funded from a faucet or any other BSC testnet wallet. Where the Clipboard API is unavailable or denied (plain http, permission refused), it falls back to printing the full address for manual selection.
- Fund from wallet expands an inline amount field. The amount is validated before any wallet is touched, so a bad value reads as a bad value even with no injected wallet present. On submit it opens the visitor's wallet for one plain tBNB transfer to the session address, then reports the tx hash, the confirmation, and the refreshed balance in place.
- New session key discards the stored key
(
resetVaultSession). It is destructive (a fresh key cannot unlock anything the old one bought, nor spend the tBNB left in it), so it is a two-step control: the first click arms it and prints that warning, and only a second click within 8 seconds rotates the key.
The detail drawer is a real modal: role="dialog" aria-modal="true", Tab is
trapped inside it, Escape closes it, and closing returns focus to the card
that opened it. While closed it is visibility: hidden, so its controls are
not tabbable behind an aria-hidden wrapper.
4. Reproducing the proof
The public BSC testnet deploy is blocked on a funded deployer key (same wall
recorded in the GreenfieldVault and WorldMoves sections of
contracts/DEPLOYMENTS.md). Every
piece of logic above is provable today against a local anvil fork — the
same technique prompt 11 used at the exported-function level, extended here
to drive the actual running HTTP endpoints and a real headless browser:
node scripts/verify-vault-ui.mjs
This script deploys GreenfieldVault (with faithful mocked Greenfield hubs,
contracts/script/DeployGreenfieldVaultMocked.s.sol) on a local anvil --chain-id 97, lists a real object, boots the real server/index.mjs API
server in-process, serves a real AES-256-GCM-encrypted GLB from a tiny local
Storage-Provider stand-in, and drives /vault with Playwright through
browse → buy → settle → unlock. It stops at the ciphertext download step —
GET /api/vault/download uses the real @bnb-chain/greenfield-js-sdk
client for an authenticated private-object fetch, which requires a real
Greenfield chain lookup that cannot be mocked locally. That's the single
remaining gap, and it's the same funded-account wall as everywhere else in
this campaign, not a bug in this code path.
5. Honest gaps (re-checked 2026-10-25)
- Public testnet deploy: code-complete (
contracts/script/DeployGreenfieldVault.s.soldry-run succeeds against the live testnet RPC), blocked on a fundedBNB_TESTNET_DEPLOYER_KEY. The latest dry run incontracts/DEPLOYMENTS.mdis 1,711,362 total gas with 41/41forge testpassing. The one-command deploy-and-prove path isnode scripts/bnb-testnet-deploy-prove.mjs --broadcast. - Real Greenfield object upload:
api/bnb/vault-upload.jsis real and complete, blocked on a fundedGREENFIELD_VAULT_OPERATOR_KEY. The earlier E2E proof confirmed exactly how far the wire reaches with a throwaway (never-funded) operator key configured:GET /api/vault/downloadgets past the "not configured" guard and reaches LIVE Greenfield testnet infrastructure through the real SDK client, failing with a specific real protocol error —"Query failed with (6): No such bucket: unknown request"— not a generic timeout or config error. That confirms the SDK wire-connects correctly end-to-end and the funded-account wall is the complete explanation, not a hidden second gap. policyDatawire-format confirmation:GET /api/vault/buy-policy-data(api/_lib/bnb/vault-policy-data.js) builds a real protobuf-encoded GreenfieldPolicyforbuy(), but its exact byte-layout hasn't been confirmed against a livePermissionHubrelay in this session — it can only even attempt to run once a listing's object has completed a real Greenfield upload, which is blocked by the point above. Until then,buy()uses an honestly-labeled deterministic placeholder (buildPolicyDataPlaceholderinsrc/bnb/vault-buy.js) — the same posture the prompt-11 anvil proof used.- No seller browser wallet has actually completed a real
list()against a publicly deployed contract yet (deploy itself is blocked); the "Sell a model" panel on/vaultis real code against the real upload +list()path, exercised so far only on the local anvil fork above.
Related
- BNB Chain payments - MPP payments and the MegaFuel gasless-send rail the vault's
buy()uses - x402 on three.ws - the platform's pay-per-call protocol on Solana and Base