Monorepo for Aesthetic.Computer
aesthetic.computer
1# Keeps TUI Admin Interface
2
3A terminal-based UI for managing Keeps NFT contracts across Tezos networks.
4
5## Overview
6
7The Keeps TUI will provide a single command-line interface to:
8- Browse and manage multiple Keeps contracts (mainnet + ghostnet)
9- Switch between wallet identities (rolodex)
10- Perform admin operations on contracts
11- View token holdings and minting activity
12
13## Architecture
14
15```
16┌─────────────────────────────────────────────────────────────┐
17│ keeps-tui.mjs │
18│ (Entry point - imports from keeps.mjs + vault loader) │
19├─────────────────────────────────────────────────────────────┤
20│ Views: │
21│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐│
22│ │ Contracts │ │ Wallet │ │ Token Browser ││
23│ │ Browser │ │ Rolodex │ │ (list/search tokens) ││
24│ └─────────────┘ └─────────────┘ └─────────────────────────┘│
25├─────────────────────────────────────────────────────────────┤
26│ Services: │
27│ • TzKT API (read contract state, tokens, holders) │
28│ • Taquito (write operations with vault keys) │
29│ • Beacon SDK (optional - for external wallet signing) │
30└─────────────────────────────────────────────────────────────┘
31```
32
33## Wallet Rolodex
34
35The TUI maintains a rolodex of wallet identities. **Private keys stay in vault only.**
36
37### Wallet Sources
38
39| Wallet | Address | Source | Role |
40|---------------|----------------------------------------|---------------------------------|------------|
41| staging | `tz1dfoQDuxjwSgxdqJnisyKUxDHweade4Gzt` | `vault/tezos/staging/.env` | Testing |
42| kidlisp | `tz1dfoQDuxjwSgxdqJnisyKUxDHweade4Gzt` | `vault/tezos/kidlisp/.env` | Production |
43| aesthetic | `tz1gkf8EexComFBJvjtT1zdsisdah791KwBE` | Beacon (external wallet) | Treasury |
44| custom | (user specified) | Runtime input / Beacon | Ad-hoc |
45
46### Key Loading Strategy
47
48```javascript
49// Vault loader - NEVER exposes keys outside this module
50async function loadWalletFromVault(walletId) {
51 const envPath = `${VAULT_PATH}/tezos/${walletId}/.env`;
52 // Returns a signing function, NOT the raw key
53 return {
54 address: pubKeyHash,
55 sign: async (payload) => signWithKey(privateKey, payload),
56 source: 'vault'
57 };
58}
59
60// For external wallets, use Beacon
61async function loadExternalWallet() {
62 const wallet = new BeaconWallet({ name: 'Keeps TUI' });
63 await wallet.requestPermissions({ network: { type: NetworkType.MAINNET } });
64 return {
65 address: await wallet.getPKH(),
66 sign: (payload) => wallet.sign(payload),
67 source: 'beacon'
68 };
69}
70```
71
72## Contract Registry
73
74The TUI tracks known contracts across networks:
75
76```javascript
77const CONTRACTS = {
78 mainnet: {
79 staging: {
80 address: 'KT1EcsqR69BHekYF5mDQquxrvNg5HhPFx6NM',
81 admin: 'tz1dfoQDuxjwSgxdqJnisyKUxDHweade4Gzt',
82 label: 'Mainnet Staging',
83 deployed: '2025-01-XX'
84 },
85 production: {
86 address: null, // TBD
87 admin: 'tz1gkf8EexComFBJvjtT1zdsisdah791KwBE',
88 label: 'Mainnet Production',
89 deployed: null
90 }
91 },
92 ghostnet: {
93 testing: {
94 address: 'KT1StXrQNvRd9dNPpHdCGEstcGiBV6neq79K',
95 admin: 'tz1dfoQDuxjwSgxdqJnisyKUxDHweade4Gzt',
96 label: 'Ghostnet Testing',
97 deployed: '2025-01-XX'
98 }
99 }
100};
101```
102
103## TUI Screens
104
105### 1. Main Menu
106
107```
108╔══════════════════════════════════════════════════════════╗
109║ KEEPS CONTRACT ADMIN TUI ║
110╠══════════════════════════════════════════════════════════╣
111║ ║
112║ Active Wallet: staging (tz1dfo...4Gzt) ║
113║ Network: mainnet ║
114║ ║
115║ [C] Contracts - Browse & manage contracts ║
116║ [W] Wallets - Switch wallet identity ║
117║ [T] Tokens - Browse minted tokens ║
118║ [M] Mint - Mint a new Keep ║
119║ [S] Settings - Configure networks/RPCs ║
120║ [Q] Quit ║
121║ ║
122╚══════════════════════════════════════════════════════════╝
123```
124
125### 2. Contract Browser
126
127```
128╔══════════════════════════════════════════════════════════╗
129║ CONTRACTS (mainnet) ║
130╠══════════════════════════════════════════════════════════╣
131║ ║
132║ → [1] KT1Ecs...79K STAGING 0 tokens $cow minted ║
133║ [2] KT1Abc...123 PRODUCTION -- tokens (not active) ║
134║ ║
135║ ─────────────────────────────────────────────────────── ║
136║ GHOSTNET: ║
137║ [3] KT1Stx...q79K TESTING 5 tokens ║
138║ ║
139║ [Enter] View contract [A] Admin ops [D] Deploy new ║
140║ [N] Switch network [B] Back ║
141╚══════════════════════════════════════════════════════════╝
142```
143
144### 3. Contract Detail View
145
146```
147╔══════════════════════════════════════════════════════════╗
148║ KT1EcsqR69BHekYF5mDQquxrvNg5HhPFx6NM ║
149║ Mainnet Staging ║
150╠══════════════════════════════════════════════════════════╣
151║ ║
152║ Admin: tz1dfoQDuxjwSgxdqJnisyKUxDHweade4Gzt ║
153║ Minter: tz1dfoQDuxjwSgxdqJnisyKUxDHweade4Gzt ║
154║ Tokens: 1 ║
155║ Balance: 0.05 ꜩ ║
156║ ║
157║ TOKEN LIST: ║
158║ #0 $cow 1 minted holder: tz1gkf...BHE ║
159║ ║
160║ ─────────────────────────────────────────────────────── ║
161║ ADMIN OPERATIONS (requires admin wallet): ║
162║ [1] set_metadata [2] update_minter [3] update_admin ║
163║ [4] Toggle pause [5] Withdraw balance ║
164║ ║
165║ [O] Open on objkt [T] Open on TzKT [B] Back ║
166╚══════════════════════════════════════════════════════════╝
167```
168
169### 4. Wallet Rolodex
170
171```
172╔══════════════════════════════════════════════════════════╗
173║ WALLET ROLODEX ║
174╠══════════════════════════════════════════════════════════╣
175║ ║
176║ → [1] staging tz1dfo...Gzt (vault) 0.95 ꜩ ║
177║ [2] kidlisp tz1dfo...Gzt (vault) 0.00 ꜩ ║
178║ [3] aesthetic tz1gkf...BHE (beacon) -- ║
179║ [4] + Add custom wallet ║
180║ ║
181║ ─────────────────────────────────────────────────────── ║
182║ CURRENT: staging ║
183║ Can sign: ✓ (vault key loaded) ║
184║ ║
185║ [Enter] Switch to wallet [B] Back ║
186╚══════════════════════════════════════════════════════════╝
187```
188
189## CLI Commands
190
191The TUI also supports direct CLI commands for scripting:
192
193```bash
194# List contracts
195node keeps-tui.mjs contracts --network mainnet
196
197# Switch wallet
198node keeps-tui.mjs wallet use staging
199
200# Mint a token
201node keeps-tui.mjs mint --name '$butterfly' --wallet staging --network mainnet
202
203# View token
204node keeps-tui.mjs token 0 --contract KT1Ecs...
205
206# Admin operations
207node keeps-tui.mjs admin set-minter --address tz1abc... --contract KT1Ecs...
208node keeps-tui.mjs admin set-metadata --uri ipfs://... --contract KT1Ecs...
209```
210
211## Security Model
212
213### Critical Rules
214
2151. **Private keys NEVER leave the vault**
216 - Keys are loaded into memory only during signing
217 - No key export or display functions
218 - All signing happens through wrapper functions
219
2202. **Vault structure**
221 ```
222 aesthetic-computer-vault/
223 └── tezos/
224 ├── staging/.env # TEZOS_PRIVATE_KEY=edsk...
225 ├── kidlisp/.env # TEZOS_PRIVATE_KEY=edsk...
226 └── wallets.json # Address registry (no keys)
227 ```
228
2293. **External wallets via Beacon**
230 - For wallets where vault key isn't available
231 - Requires manual approval in wallet app
232 - Used for `aesthetic.tez` (Jeffrey's main wallet)
233
2344. **Audit logging**
235 - All admin operations logged with timestamp
236 - Logs stored in vault (not repo)
237 - Includes: operation, wallet, contract, result
238
239## Implementation Phases
240
241### Phase 1: Read-Only Browser
242- [ ] Contract list view
243- [ ] Token browser
244- [ ] TzKT integration
245- [ ] Basic TUI framework (blessed or ink)
246
247### Phase 2: Wallet Management
248- [ ] Vault key loading
249- [ ] Wallet rolodex UI
250- [ ] Balance display
251- [ ] Beacon SDK integration
252
253### Phase 3: Admin Operations
254- [ ] Mint via TUI
255- [ ] set_metadata
256- [ ] update_minter / update_admin
257- [ ] Pause/unpause
258
259### Phase 4: Deployment
260- [ ] Deploy new contract from TUI
261- [ ] Contract comparison (diff storage/code)
262- [ ] Migration tools
263
264## Dependencies
265
266```json
267{
268 "dependencies": {
269 "blessed": "^0.1.81", // Terminal UI
270 "@taquito/taquito": "^19", // Tezos operations
271 "@airgap/beacon-sdk": "^4", // External wallet connection
272 "dotenv": "^16" // Vault env loading
273 }
274}
275```
276
277## File Location
278
279```
280tezos/
281├── keeps.mjs # Existing CLI (mint, deploy, etc.)
282├── keeps-tui.mjs # NEW: Interactive TUI entry point
283├── keeps-vault.mjs # NEW: Secure vault key loader
284├── keeps-contracts.mjs # NEW: Contract registry
285└── KEEPS-TUI-PLAN.md # This document
286```
287
288## Notes
289
290- Start with Phase 1 (read-only) to validate the TUI framework choice
291- Consider using `ink` (React for CLI) if blessed feels dated
292- The existing `keeps.mjs` commands will be wrapped, not replaced
293- All destructive operations require confirmation prompt