cartridge-gg / cartridge-gg/controller-cli
Support multiple simultaneous sessions across different chains
- Dominant language
- Rust
- Stars
- 2
- Forks
- 4
- PR merge metrics
- No merged PRs in 30d
Description
## Problem
Currently, the CLI only supports one active session at a time. Users cannot maintain simultaneous sessions on different chains (e.g., mainnet and sepolia). This creates friction when:
- Developers need to test on sepolia while having production access on mainnet
- Users want to switch between networks without re-registering and re-authorizing
- Multiple chains require different sessions (mainnet, sepolia, Cartridge SLOT)
Currently, registering a new session on a different chain overwrites the existing session.
## Proposed Solution
Support multiple concurrent sessions, one per chain. Sessions should be isolated by chain_id in storage.
### Storage Structure
Instead of a single session, store sessions keyed by chain_id:
```
~/.config/controller-cli/
sessions/
SN_MAIN.json # Mainnet session
SN_SEPOLIA.json # Sepolia session
SLOT.json # Cartridge SLOT session (future)
```
Or use the existing storage format with chain_id in the key (which already exists):
```
@cartridge/session/0x{address}/0x{chain_id}
```
### Command Behavior
**Auto-detect from --rpc-url:**
```bash
# Execute on mainnet (uses mainnet session)
controller execute \
--contract 0x... \
--entrypoint transfer \
--calldata 0x... \
--rpc-url https://api.cartridge.gg/x/starknet/mainnet
# Execute on sepolia (uses sepolia session)
controller execute \
--contract 0x... \
--entrypoint transfer \
--calldata 0x... \
--rpc-url https://api.cartridge.gg/x/starknet/sepolia
```
**Status shows all sessions:**
```bash
controller status --json
```
```json
{
"status": "active",
"sessions": {
"SN_MAIN": {
"address": "0x...",
"chain_id": "SN_MAIN",
"expires_at": 1735689600,
"expires_in_seconds": 3600,
"is_expired": false
},
"SN_SEPOLIA": {
"address": "0x...",
"chain_id": "SN_SEPOLIA",
"expires_at": 1735689600,
"expires_in_seconds": 7200,
"is_expired": false
}
},
"keypair": {
"public_key": "0x...",
"has_private_key": true
}
}
```
### Registration Flow
Sessions are registered per-chain:
```bash
# Register mainnet session
controller register-session mainnet-policy.json \
--rpc-url https://api.cartridge.gg/x/starknet/mainnet
# Register sepolia session (doesn't overwrite mainnet)
controller register-session sepolia-policy.json \
--rpc-url https://api.cartridge.gg/x/starknet/sepolia
```
## Implementation Details
### Changes Required
1. **Storage layer** (`src/commands/status.rs`, `src/commands/register.rs`, `src/commands/execute.rs`):
- Store multiple sessions keyed by chain_id
- Load the appropriate session based on --rpc-url
2. **Status command**:
- List all available sessions
- Show which chains have active sessions
- Indicate current/default session
3. **Execute command**:
- Determine chain_id from --rpc-url
- Load corresponding session for that chain
- Error if no session exists for that chain
4. **Clear command**:
- Add optional flag to clear specific chain: `controller clear --chain sepolia`
- Default behavior: clear all sessions
### Error Handling
```bash
# Attempting to execute on mainnet without mainnet session
controller execute --rpc-url https://api.cartridge.gg/x/starknet/mainnet ...
```
```json
{
"status": "error",
"error_code": "NoSessionForChain",
"message": "No active session found for chain SN_MAIN",
"recovery_hint": "Run 'controller register-session policy.json --rpc-url https://api.cartridge.gg/x/starknet/mainnet' to create a mainnet session"
}
```
## Benefits
1. **Developer productivity**: Switch between testnet/mainnet without re-auth
2. **Multi-chain support**: Ready for Cartridge SLOT and future chains
3. **Better UX**: Natural workflow for cross-chain operations
4. **LLM-friendly**: LLMs can execute on appropriate chain based on user intent
## Future Considerations
- Support for custom RPC endpoints (non-Cartridge chains)
- Session switching via `--chain` flag as alternative to `--rpc-url`
- Default chain preference in config
- Session synchronization across devices
## Related Files
- `src/commands/status.rs` - Status output
- `src/commands/register.rs` - Session registration
- `src/commands/execute.rs` - Session loading
- `src/commands/clear.rs` - Session cleanup
- `LLM_USAGE.md` - Documentation updates needed
Contributor guide
No contributing guide indexed for this repository
Assessment
This issue has not been assessed yet.