Skip to content

docs: Session Key lifecycle guide for non-custodial transaction signing #201

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
KevinMB0220 merged 1 commit into from
Mar 29, 2026
Merged

docs: Session Key lifecycle guide for non-custodial transaction signing #201

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
45 changes: 44 additions & 1 deletion docs/architecture/architecture.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -87,7 +87,48 @@ The passkey-driven Soroban auth path is documented in [smart-wallet-auth-flow.md

### Session Key Lifecycle

The short-lived delegate signer flow is documented in [session-key-flow.md](./session-key-flow.md).
Session keys are short-lived Ed25519 delegate signers that eliminate repeated biometric prompts for high-frequency Soroban operations (DCA, automated swaps, small payments).

```mermaid
sequenceDiagram
participant App as Application
participant SKM as SessionKeyManager
participant WebAuthn as Browser / WebAuthn
participant SWS as SmartWalletService
participant Contract as Wallet Contract

App->>SKM: createSession(walletAddress, credentialId, ttlSeconds)
Copy link
Copy Markdown

@coderabbitai coderabbitai bot Mar 29, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Session API call shape is inconsistent with actual createSession(options) signature.

Line 100 shows positional args, but SessionKeyManager.createSession accepts an options object. Please align the diagram call shape to avoid copy/paste misuse.

Suggested doc fix 
-    App->>SKM: createSession(walletAddress, credentialId, ttlSeconds)
+    App->>SKM: createSession({ smartWalletAddress, passkeyCredentialId, ttlSeconds })
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
App->>SKM: createSession(walletAddress, credentialId, ttlSeconds)
App->>SKM: createSession({ smartWalletAddress, passkeyCredentialId, ttlSeconds })
🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@docs/architecture/architecture.md` at line 100, Update the sequence diagram
call so it matches the actual API signature: replace the positional-style call
App->>SKM: createSession(walletAddress, credentialId, ttlSeconds) with the
object-style call that reflects SessionKeyManager.createSession(options) (e.g.,
pass an options object containing walletAddress, credentialId, ttlSeconds) so
the diagram matches the real createSession(options) method shape.

SKM->>SKM: Generate fresh Ed25519 keypair (memory only)
SKM->>SKM: Derive challenge = SHA-256(walletAddress ‖ sessionPublicKey ‖ ttlSeconds)
SKM->>WebAuthn: ONE biometric prompt
WebAuthn-->>SKM: PublicKeyCredential assertion
SKM->>SWS: addSigner(walletAddress, sessionPublicKey, ttlSeconds, assertion)
SWS->>Contract: add_session_signer → Soroban temporary storage
Contract-->>App: Session active

loop Each transaction (no biometric)
App->>SKM: signTransaction(sorobanTx, contractAddress)
SKM->>SWS: signWithSessionKey(contract, tx, credentialId, signFn)
SWS->>Contract: Simulate → auth entry hash
SWS->>SKM: signFn(hash) — in-memory Ed25519
SWS-->>App: Fee-less signed XDR
end

App->>SKM: revoke(walletAddress, credentialId)
SKM->>SKM: Zero private key from memory FIRST
SKM->>SWS: removeSigner → remove_signer on-chain
```

**Key design decisions:**

- The Ed25519 private key lives only in memory — never in localStorage, sessionStorage, or any persistent store.
- Session signers use Soroban **temporary storage**, so they expire automatically when the TTL reaches zero — no server-side cleanup needed.
- The WebAuthn challenge for `createSession()` is derived deterministically from the operation parameters, binding the assertion to this specific `add_session_signer` invocation.
- `revoke()` zeroes the private key **before** the async network call, ensuring the key is gone even if the network call fails.

For the full guide including TTL strategy, error handling, and code examples, see [docs/smart-wallet/session-keys.md](../smart-wallet/session-keys.md).

The low-level sequence diagram is in [session-key-flow.md](./session-key-flow.md).

### DeFi Aggregation

Expand Down Expand Up @@ -139,3 +180,5 @@ sequenceDiagram
- [DeFi aggregation flow](./defi-aggregation-flow.md)
- [Smart wallet contract guide](../contracts/smart-wallet-contract.md)
- [Contract deployment guide](../contracts/deployment.md)
- [Session Key Lifecycle Guide](../smart-wallet/session-keys.md)
- [SmartWalletService API Reference](../smart-wallet/api-reference.md)
Loading
Loading