Session Keys

A session key is a scoped, time-limited key the Pipoke app generates locally, registers on SessionRegistry, and uses to sign your social actions on your behalf. With a session key active, posts, replies, reposts, likes, reactions, bookmarks, pokes, drops, market actions, and most game actions go through silently. No wallet popup per action.

Pipoke runs on Octra Devnet today. Any fee, price, or limit referred to here is a contract setting chosen for testing. Every one is owner-settable, and mainnet values will be different. These docs describe how the mechanics work, not what the numbers are.

#What the session key is allowed to do

A session key is scoped. The Pipoke app issues each session key with:

A list of contract addresses the key may call (the Pipoke set: PipokeCore, the feed shards, the engagement shard, the auction router, the markets, the game shards, etc.).
A list of method names the key may invoke (everything that does not touch raw asset transfers other than POKE).
A POKE spend cap the key may consume over its lifetime.
A TTL in epochs of about 180,000 (roughly 25 days at half-second epochs).

If the key tries to call outside its scope, the registry rejects it. If the cap is exhausted, the registry rejects it. If the TTL has expired, the registry rejects it.

#What still needs your wallet

A few things bypass the session key on purpose:

Action	Why
Direct messages	DM sends use your wallet signing keypair to derive a per-pair box key. The session key cannot derive that.
Group messages	Same. Group rekey rounds need your wallet.
Coin launches	A coin launch is a deploy transaction with a one-`POKE` fee. The app surfaces it explicitly.
Sending `OCT` to an arbitrary address	Asset transfers stay wallet-signed.
Granting `POKE` allowances	Allowance grants stay wallet-signed.
Revoking the session key	The kill-switch must be wallet-signed by design.

#Setting up a session key

When you click "Activate session" in the wallet panel:

The app generates a fresh Ed25519 keypair in your browser from 32 bytes of random.
The session address is derived deterministically: 'oct' + base58(sha256(pubkey)).
The app builds a register_session(session_address, principal, pubkey_b64, expiry_epoch) tx on SessionRegistry. Your wallet signs the registration.
The session key is live on-chain. Subsequent calls signed by it pass is_valid_for(session_address, principal) and the called contract accepts them.

The private half lives in your browser's local storage and never leaves. If you move to a new device, you set up a new session key there. The old one stays valid until it expires or you revoke it.

#Method surface

Method	Where	Purpose
`register_session`	`SessionRegistry`	Issue a new session for a principal.
`is_valid_for`	`SessionRegistry` (view)	Called by every contract that accepts session signatures.
`revoke_session`	`SessionRegistry`	Kill an active session. Must be wallet-signed.

#Gas buffer

The session key needs a small OCT balance to pay gas. The app warns you when your OCT falls below a working minimum and recommends a faucet claim or a top-up. Without the buffer, session-signed actions fail at gas time.

#Revoking

You can kill an active session key any time from the wallet panel. Revocation is one wallet-signed transaction on SessionRegistry. After it confirms, the key is rejected on every contract. You can issue a new one immediately.

If your laptop is stolen or your browser is compromised, revoke the key from any device with your seed phrase. The attacker can only spend up to the unused part of the cap before the revocation lands, which is why caps are sized small.