The private account
One wallet signature opens your user's private account on this device, and the same wallet opens the same account anywhere.
A Solana wallet is a keypair. Whoever holds the secret key controls the wallet. A private account has no keypair of its own to back up. It comes from the wallet your user already has.
One signature opens it
When your app calls openNimbusSession, the wallet asks your user to sign a fixed message. The SDK
derives everything the account needs from that signature, on the device.
Signing moves no money and costs nothing. No transaction is sent, and nothing is written to Solana.
The same wallet always opens the same private account, on any device. There is nothing extra to back up.
What the account holds
- Keys. They read your user's notes and spend them. They stay in the browser.
- A platform wallet. This is a second Solana address the SDK derives for your user. Deposits pass through it on their way into the pool.
- An identity. This is the public value Solana knows the account by. Registering publishes it and ties it to both wallets. It reveals nothing about the keys.
Each accountIndex you pass to openNimbusSession opens a separate private account from the same
wallet. Most apps use the default, 0.
Remembering the sign-in
So that a reload does not ask the wallet again, the session keeps the signature in a signature secret store. You choose one when you open the session:
| Store | Remembers it for | On reload, your user sees | Kept in | Readable by |
|---|---|---|---|---|
createMemorySignatureSecretStore | Never | A signature request, every time | The page's memory | Nothing outside the page |
createTabSignatureSecretStore (default) | This tab | No request. A new tab asks again. | sessionStorage | Any script on your site, while the tab is open |
createPersistentSignatureSecretStore | This browser | No request, until you wipe it | localStorage | Any script on your site, and anyone with the browser profile |
The longer a store remembers, the smoother sign-in feels and the wider the exposure.
A stored signature is the whole account
The tab and browser stores keep the signature unencrypted. Any script that runs on your site can read it, including an injected one or a compromised dependency. Whoever reads it can spend the private balance.
Keys never leave the browser
The SDK sends services only what a payment needs. These are the most sensitive parts:
- To Nimbus's context service: the account's identity, the token, the recipient and the notes a payment spends. It answers with what the proof needs.
- To each guardian node: one share of a viewing key, encrypted to that node. One share alone reveals nothing, and no share can spend.
- To the fee enclave: the payment's fee details, sealed to the enclave.
- To the relayer: the finished, proved transaction.
- To Nimbus's gateway: the gateway token, sent to the gateway's addresses and nowhere else.
It never sends the signature, the spending keys or the device's copy of the notes. Nimbus's services describes what each service receives.
What this means for your app
- Ask once. Your user signs one message. The store you choose decides how long it lasts.
- Pick a store for your product. A wallet-style app may choose the browser store. A shared or kiosk device should choose memory.
- Sign out properly.
closeNimbusSessionleaves the store as it is. Wipe the store too.
Last updated