Stele Gate

Your Solana program refuses a protected action until the signing wallet has accepted your current terms. Deposits into a real-world-asset vault, a token offering, a permissioned credit pool: if the terms were not accepted, the transaction fails on-chain, whoever sent it.

In one minute#

A checkbox on a website protects only that website. Anyone can build the transaction themselves and call your program directly, and the checkbox never runs. Stele Gate puts the check inside the program:

1. You publish your terms and set a policy. In the Stele dashboard: "deposits require version 2 of the Offering Terms".
2. The user accepts once. A small Stele window shows the exact text; the user signs with their wallet. It is free for the user. Solana now holds an entry in the user's passport — one Stele account per wallet, listing every document it accepted: "this wallet accepted version 2".
3. Your program checks the passport. One call, require_current_passport(), before the action. No entry, an old version or someone else's passport, and the transaction fails.

Organization ── publishes ──▶ Document v1, v2 …                   (Stele program)
Organization ── sets ───────▶ Policy: "requires ≥ v2"              (Stele program)
User wallet ─── accepts v2 ─▶ Passport: "Offering Terms → v2, …"   (Stele program)

User wallet ─── deposit ────▶ Your program
                              └─ require_current_passport(passport, policy, user)  ✓ or ✕

When you require a new version, older entries stop working until the user accepts again. Nothing is rewritten: earlier acceptances stay on record and verifiable.

Two things to remember:

• Stele is not in the execution path. Your program reads two Stele accounts and decides. No proxy, no CPI into Stele, no shared signer and no Stele server takes part in the protected transaction.
• The frontend is optional; the program check is not. The SDK gives users a smooth "Accept & Continue". The check in your program is what a script, the CLI or another frontend cannot skip.

Proof or Gate?#

Every acceptance that opens a Gate is an ordinary Stele Proof acceptance, with a public receipt anyone can verify.

Add it in three steps#

1. Create the policy#

In the dashboard: publish the document (Documents), turn on Stele Gate for the organization, then Gate → Policies → Create policy. Copy the policy address.

2. Call require_current_passport in your program#

Add the policy and the user's passport to the protected instruction, and call require_current_passport before the action.

// Cargo.toml: stele-gate = "1.1"
use anchor_lang::prelude::*;

#[derive(Accounts)]
pub struct DepositWithPassport<'info> {
    pub investor: Signer<'info>,
    #[account(mut, seeds = [b"vault", vault.policy.as_ref()], bump = vault.bump)]
    pub vault: Account<'info, Vault>,
    /// CHECK: pinned to the vault's policy; verified by require_current_passport.
    #[account(address = vault.policy)]
    pub policy: UncheckedAccount<'info>,
    /// CHECK: the investor's Stele passport; verified by require_current_passport.
    pub passport: UncheckedAccount<'info>,
}

pub fn deposit_with_passport(ctx: Context<DepositWithPassport>, amount: u64) -> Result<()> {
    let granted = stele_gate::require_current_passport(
        &ctx.accounts.passport,
        &ctx.accounts.policy,
        &ctx.accounts.investor,
    )?;
    // granted.version_number and granted.accepted_at name the acceptance that allowed
    // this deposit — useful in your own events.
    // … the protected action
    Ok(())
}

This is the deposit of the Atlas Real Estate Vault from the live demo (programs/gate-demo), shortened. Several documents for one action (terms, privacy, risk disclosure): one passport and require_passport_policies(&REQUIRED, ctx.remaining_accounts, &passport, &user). The crate is stele-gate on crates.io (source: crates/stele-gate in the Stele repository).

3. Add "Accept & Continue" to your app#

Wrap the protected action with gate():

import { createSteleGate } from "@stelehq/sdk";

const stele = createSteleGate({
  apiBaseUrl: "https://stele.site/api",
  wallet: {
    address: wallet.publicKey.toBase58(),
    signMessage: (message) => wallet.signMessage(message),
  },
});

const signature = await stele.gate({
  policy: OFFERING_TERMS_POLICY,
  action: () => sendDepositTransaction(5_000_000_000n),
  acceptLabel: "Accept & Continue",
});

What gate() does:

• The acceptance is current → it runs action right away. The user sees nothing extra.
• Missing or outdated → it opens the Stele window with the exact text of the required version (checked against Solana), records the acceptance, waits until it is visible on-chain, then runs action.
• The user closes the window → it throws GateCancelledError; action never runs.

For your own UI, pass ui: "none": gate() then throws AccessRequiredError instead of opening the window, and stele.check(policy, wallet) returns the status without prompting. The SDK is in the Stele repository (packages/sdk); in a plain HTML page, load /sdk/v1/stele.js and use Stele.createGate().

Then: test the bypass#

Your tests should cover at least:

The dashboard's Gate → Testing runs the same scenarios live against your policy, and against the demo vault's deposit by simulation.

Stele Verified#

Your users cannot read your program, so give them proof instead: a Stele Verified badge on your site that opens public evidence that your program really waits for the current terms.

<script src="https://stele.site/sdk/v1/stele.js" defer></script>
<span data-stele-verified="YOUR_PROGRAM_ID"></span>

(React: <SteleVerifiedBadge program="YOUR_PROGRAM_ID" /> from @stelehq/sdk/react; README: https://stele.site/api/v1/public/verified/YOUR_PROGRAM_ID/badge.svg.)

How Stele checks it. In the dashboard (Gate → Verification) you show Stele how your protected instruction is called: upload your program's Anchor IDL (target/idl/<program>.json, or Export IDL in Solana Playground) and pick the instruction — the user, their passport and your policy are recognised by name, fixed accounts and PDAs derived from known accounts are filled in, and arguments are typed values. Without an IDL, give the data (hex) and the accounts by hand. The user, the passport and the policy are placeholders Stele fills in per scenario. Stele then simulates that instruction against your deployed program — nothing is signed or sent — in three scenarios:

A program passes only if the Stele check of your policy is what decides — a refusal for another reason, or another organization's policy, fails. The deployed code is fingerprinted (sha256), and Stele re-runs the probes whenever the program is upgraded or its upgrade authority changes (checked every minute), and at least every six hours. A status change is sent as the gate.program_verification_changed webhook.

Ownership. Your program's upgrade authority signs a memo stele-verify <program> <organization> — from the dashboard with the connected wallet, or from a multisig (paste the transaction signature). An immutable program has no authority: it cannot change, which is stronger still.

What a visitor sees at stele.site/verified/<program>: what was checked and when, the terms and version, the code fingerprint, who can change the program (nobody, a multisig or a single key), the ownership proof — and a Re-check in my browser button that runs the same three simulations from the visitor's browser against Solana, so nobody has to trust Stele's word.

Copies of the badge. The live badge reads "Not valid on this site" outside your verified domains, and the evidence page warns when the visitor came from another site. A static image can be copied anywhere, so the page always states which websites the verification belongs to.

What it does not prove. That a website sends the user to this program (their wallet shows the program they sign for — the page tells them to compare), who controls a wallet, or anything about the program besides this check. It is not an audit.

Good to know#

"Accept & Continue" is two transactions#

1. The acceptance. The user signs a message (not a transaction); Stele's relayer submits it and pays the fee and the passport deposit.
2. Your action. The user signs your transaction as usual.

They are not atomic:

• If the second transaction fails or the user rejects it, the acceptance stays recorded and the passport entry stays current. The user does not have to accept again.
• If the organization requires a newer version between the two, the action fails with AccessPassOutdated and the next attempt shows the window again.
• If the document changes while the window is open, the SDK refuses to sign the old text and loads the new version.

Why a direct call fails#

A Solana program cannot know which website a transaction came from. require_current_passport runs inside the program that executes the action, so it holds for every caller:

To see it from a terminal, against a local validator in a clone of the repository:

# Without --keypair, a fresh wallet (funded by airdrop on localnet) that never accepted.
pnpm --filter @stele/localnet vault-deposit -- --policy <policy address>
# ✘ rejected on-chain by the vault program — AccessPassMissing

What Gate does not do#

• It is not KYC. A wallet signature proves control of a key, not who holds it. Gate answers "which exact version did this wallet accept?", not "who is this?". Identity, jurisdiction and accreditation checks are outside Stele.
• It is not a compliance engine. It enforces one thing: acceptance of a required document version. Whether that satisfies a regulation is a question for your counsel.
• It does not custody funds or route your transactions.
• It is only as good as your integration. A program that forgets to pin the policy, or to call require_current_passport in every protected instruction, is not protected.
• The policy is the organization's. Its owner, admins and publishers can change the requirement, including back to an older version; each change is a public on-chain event.
• The Stele program is upgradeable by its upgrade authority, as described in the trust model. Stele currently runs on Devnet.

Questions#

Does Stele Gate replace my frontend? No. Your app keeps its UI; the SDK adds a window only when acceptance is needed.

What does the user pay? Nothing for the acceptance. They pay your protected transaction as they would without Stele; the check adds no fee.

Can I gate several instructions? Yes. Call require_current_passport in each, with the same policy or different ones.

Can I require several documents? Yes: require_passport_policies checks a pinned list of policies against the one passport — N documents, N + 1 accounts.

What if Stele shuts down? Your program's check, existing passports and verification keep working — they live on Solana. For new acceptances, the organization opens a shard to everyone and wallets record their own acceptances; see the guide's "If Stele disappears".

Can a user lose their entry? Only by choice: the holder (or whoever paid an entry's deposit) can remove it, and the deposit returns to its payer. Raising the requirement makes an older entry insufficient, not invalid. Either way the earlier acceptance remains verifiable.

Can a passkey (Face ID) open a Gate? No. A passport belongs to a Solana wallet, because the same wallet must sign the protected transaction. Passkey acceptances remain available everywhere else in Stele Proof.

Reference#

Policy#

A policy names the version of one document that a protected action requires.

Publishing a new version does not change the policy. The organization chooses when to require it (set_policy_requirement), so publishing a typo fix does not lock every investor out. The requirement can name any published version, lower or higher; every change emits a PolicyChanged event with the previous requirement.

Passport#

A passport records, for one wallet, the latest version it accepted of every gated document.

The program derives the passport from the wallet whose signature it verified; the relayer cannot name another account. Nobody — not Stele, not the organization — can add or advance an entry without the holder's signature, and an entry never moves back to an older version. The acceptance identifier of each acceptance is in its PassportUpdated event and its receipt (/receipt/<acceptance_id>).

The holder, or whoever paid an entry's deposit, can remove the entry (remove_passport_entry); the deposit returns to its payer. Receipts still verify; protected programs refuse the wallet for that document until it accepts again.

Versions, step by step#

1. The policy requires v1. An investor accepts v1 → their passport's entry names v1 → deposits succeed.
2. The organization publishes v2. The policy still requires v1 → deposits still succeed.
3. The organization requires v2. The entry still names v1 — that acceptance stays on record and verifiable — but it no longer satisfies the policy: the next deposit fails with AccessPassOutdated.
4. The investor accepts v2 → the entry is advanced in place (no new deposit) → deposits succeed again.

What require_current_passport checks#

In this order — the first failure is returned:

It reads two accounts and never writes. A document's version numbers never change once published, so the version number alone identifies the accepted text.

Costs#

Measured on the real program binaries, for 1 to 1,000,000 investors — the numbers do not change with the number of users.

See Measured costs.