bounded-onchain

Bounded onchain

Wallets, tokens, on-chain transactions, and payments. The canonical Bounded email/social login includes a wallet by default: keep the default Turnkey auth and supported email/social logins carry a real @user.address - see docs/embedded-wallets.md. @user.id (the account id) stays the identity/ownership key; @user.address is the wallet. On-chain writes still pass their policy rules and invariants first, so pair this with the bounded-backend skill for the governing rules. To route across the family, see the root bounded skill.

Reference Router

Read only the row matching the current task or term.

Rules Of Thumb

• Default onchain login = default Turnkey email/social auth, plus optional wallet login. Do not add authMode or auth.wallets for the normal path; supported email/social users already have @user.address. Deploy "auth": { "wallets": true } only for an EXTERNAL-keypair session (wallet login, a server-SDK keypair client, the CLI keypair data lane). Full rule and the opt-outs: docs/embedded-wallets.md -> recommended login.
• Use @user.address only for wallet/onchain semantics; use @user.id for normal ownership. See the bounded-backend skill.
• A guest (`signInAnonymously`) session can never write an `onchain: true` collection, on ANY network. Poofnet, devnet, and mainnet all return 403 anonymous_onchain_blocked before a transaction is built, so a guest flow that works against a test network cannot break on promotion. Keep the guest-reachable surface offchain and prompt the upgrade before the first onchain write. See guests cannot write to an onchain collection.
• When a function's existing manifest description accepts account IDs, a non-pubkey string resolves to its own program-signed PDA. @contract.address is ONE shared fund for the whole app; a named id is a separate fund per name. Do not assume every source, owner, creator, or destination accepts all three custody forms - check that argument's manifest description on the function page. When separate pots of user money coexist (escrows, auctions, prize pools, per-tenant balances), use named accounts where accepted. Decide before the first deposit; retrofitting means migrating live balances.
• For onchain writes, use explicit network/RPC configuration and devnet by default; do not treat immediate read-after-write as confirmation.

The CLI submits the transaction itself, and it reads its endpoint ONLY from SOLANA_DEVNET_RPC_URL / SOLANA_MAINNET_RPC_URL: no flag, no config-file setting, and no public-RPC fallback. An unset variable fails the write before signing with validate pre-built transaction: SOLANA_DEVNET_RPC_URL is required ..., so set it in the shell running bounded whenever an app is realtime_devnet or realtime_mainnet. See CLI submission needs an explicit RPC endpoint.

• Mainnet is a real target, not a placeholder: the program is live on mainnet-beta. Creating a mainnet app requires a paid account plan (no API key or shared secret), and an app you create is owned on-chain by the creator's wallet immutably - a wallet your signed-in identity can prove it controls: the local CLI keypair, or on a web login your Bounded account's own wallet, whose permit signatures happen through a per-deploy browser approval. It can never be ownership-transferred. (oApp roots and workloads are also mainnet, but the platform mints them under a Bounded-custodied owner; you never create those yourself - see the oapps-fun skill.) See docs/onchain.md.
• @contract.address is the Solana program-ID sentinel, not the app escrow address returned by a direct query.

Supported built-in plugins resolve the sentinel to the app escrow PDA. On the current deployed Devnet runtime, do not compose the sentinel as @AccountPlugin.getAccountAddress(@contract.address): that call fails because the sentinel is address-typed while this function currently accepts a string account id. For a Devnet policy query that needs the concrete escrow address, bind the current Devnet program ID as a string literal: @AccountPlugin.getAccountAddress("openTv7fbpYSseNHYmCZFZ1CZgj4r8D9fKNgEz1qo6F"). This literal is Devnet-specific and must be updated if the deployed program changes. See policy-primitives.md.

• Treat discovery, deployed-runtime support, and live-network verification as three independent states.
• Use bounded plugins list --json and bounded plugins describe <plugin.function> --json as the offline callable signature source before authoring a hook.
• Run bounded verify --protocol <protocol> --json on the actual policy and inspect advisory capabilityReadiness, while still requiring retained live evidence before claiming network support.
• Check the Solana devnet capability catalog before proposing any plugin or primitive.
• Never infer devnet support from a compiler tag, manifest, proof contract, Poofnet model, lookup-table entry, or local validator test.
• When live evidence uses a hosted release marker, resolve its environment-qualified site URL from bounded domains list --app-id <id> --env <environment> --json slugUrl or the exact successful site-deploy receipt url.

Require the JSON field itself for staging evidence instead of copying a human-rendered hostname. bounded apps inspect proves the active policy/runtime publication and carries no hosted URL.

• Never emit runtime-v2 primitives for a runtime-v1 deployment; follow docs/policy-primitives.md.
• Current chain-backed named queries belong on onchain: true paths. Anonymous execution is admitted for identity-independent queries whose path read rule authorizes the caller; a query reading @user.address/@user.evmAddress requires that identity. The anonymous surface is the browser SDK, not the CLI.
• Do not recommend an onchain: false view for an offchain-only plugin read until standalone chain-query execution is fixed.
• Treat runtime-v3 governance the same way: enroll only after the deployed capability registry reports v3, and publish governance from observed chain state rather than policy intent.
• Keep Poofnet and Solana behavior paired.
• Use bounded wallet fund only for explicit development funding on realtime_offchain.

The caller must be the app owner, an admin, or a developer, and the balance exists only inside the selected app's simulated ledger.

• Pure/read primitives must return the same shape in runtimes where they are actually executable, and mutating primitives must apply a modeled effect or fail closed.
• Validation-only success is a parity bug.
• For a Poofnet onchain hook, application-side success means _hook_completed == _transaction_hash. Row existence and _error_message == null are only pending state. But those stamps are SIMULATOR-only: a policy RULE that requires them is permanently unsatisfiable on a real-chain protocol - a payout gated that way becomes a one-way valve that locks user funds, and every sim-side proof and test stays green. Rules gate on a declared field the hook itself writes (paidAt-style) or on the hook-derived head state; reserved _ stamps are for Poofnet clients only. Give every semantic operation id a policy-legal failed-attempt retry path. See reserved receipt stamps are Poofnet-only.
• Helius mirroring is environment-level Bounded infrastructure: one raw program webhook per environment/network, never one per app. App builders never create webhook URLs or supply provider secrets, and the operator runbook (webhook, secrets, queue/DLQ, recovery) lives in the monorepo, not this skill. See mirror completeness for the app-facing caveats.
• Crypto is accepted non-custodially; sellers settle to their own wallet.