aesthetic.computer / core

Fork 0

Monorepo for Aesthetic.Computer aesthetic.computer

Fork 0

core tezos KEEPS-TUI-PLAN.md

13 kB

Markdown

at codex/xbox-api-layer

Jeffrey Alan Scudder · restore 4270 files deleted by papers oven auto-build (17ac2f657) · 6mo ago

dbf25093

Keeps TUI Admin Interface #

A terminal-based UI for managing Keeps NFT contracts across Tezos networks.

Overview #

The Keeps TUI will provide a single command-line interface to:

Browse and manage multiple Keeps contracts (mainnet + ghostnet)
Switch between wallet identities (rolodex)
Perform admin operations on contracts
View token holdings and minting activity

Architecture #

┌─────────────────────────────────────────────────────────────┐
│                    keeps-tui.mjs                            │
│  (Entry point - imports from keeps.mjs + vault loader)      │
├─────────────────────────────────────────────────────────────┤
│  Views:                                                     │
│  ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐│
│  │ Contracts   │ │ Wallet      │ │ Token Browser           ││
│  │ Browser     │ │ Rolodex     │ │ (list/search tokens)    ││
│  └─────────────┘ └─────────────┘ └─────────────────────────┘│
├─────────────────────────────────────────────────────────────┤
│  Services:                                                  │
│  • TzKT API (read contract state, tokens, holders)          │
│  • Taquito (write operations with vault keys)               │
│  • Beacon SDK (optional - for external wallet signing)      │
└─────────────────────────────────────────────────────────────┘

Wallet Rolodex #

The TUI maintains a rolodex of wallet identities. Private keys stay in vault only.

Wallet Sources #

Wallet	Address	Source	Role
staging	`tz1dfoQDuxjwSgxdqJnisyKUxDHweade4Gzt`	`vault/tezos/staging/.env`	Testing
kidlisp	`tz1dfoQDuxjwSgxdqJnisyKUxDHweade4Gzt`	`vault/tezos/kidlisp/.env`	Production
aesthetic	`tz1gkf8EexComFBJvjtT1zdsisdah791KwBE`	Beacon (external wallet)	Treasury
custom	(user specified)	Runtime input / Beacon	Ad-hoc

Key Loading Strategy #

// Vault loader - NEVER exposes keys outside this module
async function loadWalletFromVault(walletId) {
  const envPath = `${VAULT_PATH}/tezos/${walletId}/.env`;
  // Returns a signing function, NOT the raw key
  return {
    address: pubKeyHash,
    sign: async (payload) => signWithKey(privateKey, payload),
    source: 'vault'
  };
}

// For external wallets, use Beacon
async function loadExternalWallet() {
  const wallet = new BeaconWallet({ name: 'Keeps TUI' });
  await wallet.requestPermissions({ network: { type: NetworkType.MAINNET } });
  return {
    address: await wallet.getPKH(),
    sign: (payload) => wallet.sign(payload),
    source: 'beacon'
  };
}

Contract Registry #

The TUI tracks known contracts across networks:

const CONTRACTS = {
  mainnet: {
    staging: {
      address: 'KT1EcsqR69BHekYF5mDQquxrvNg5HhPFx6NM',
      admin: 'tz1dfoQDuxjwSgxdqJnisyKUxDHweade4Gzt',
      label: 'Mainnet Staging',
      deployed: '2025-01-XX'
    },
    production: {
      address: null, // TBD
      admin: 'tz1gkf8EexComFBJvjtT1zdsisdah791KwBE',
      label: 'Mainnet Production',
      deployed: null
    }
  },
  ghostnet: {
    testing: {
      address: 'KT1StXrQNvRd9dNPpHdCGEstcGiBV6neq79K',
      admin: 'tz1dfoQDuxjwSgxdqJnisyKUxDHweade4Gzt',
      label: 'Ghostnet Testing',
      deployed: '2025-01-XX'
    }
  }
};

TUI Screens #

╔══════════════════════════════════════════════════════════╗
║              KEEPS CONTRACT ADMIN TUI                    ║
╠══════════════════════════════════════════════════════════╣
║                                                          ║
║  Active Wallet: staging (tz1dfo...4Gzt)                  ║
║  Network: mainnet                                        ║
║                                                          ║
║  [C] Contracts    - Browse & manage contracts            ║
║  [W] Wallets      - Switch wallet identity               ║
║  [T] Tokens       - Browse minted tokens                 ║
║  [M] Mint         - Mint a new Keep                      ║
║  [S] Settings     - Configure networks/RPCs              ║
║  [Q] Quit                                                ║
║                                                          ║
╚══════════════════════════════════════════════════════════╝

2. Contract Browser #

╔══════════════════════════════════════════════════════════╗
║              CONTRACTS (mainnet)                         ║
╠══════════════════════════════════════════════════════════╣
║                                                          ║
║  → [1] KT1Ecs...79K  STAGING     0 tokens   $cow minted  ║
║    [2] KT1Abc...123  PRODUCTION  -- tokens  (not active) ║
║                                                          ║
║  ─────────────────────────────────────────────────────── ║
║  GHOSTNET:                                               ║
║    [3] KT1Stx...q79K  TESTING   5 tokens                 ║
║                                                          ║
║  [Enter] View contract  [A] Admin ops  [D] Deploy new    ║
║  [N] Switch network     [B] Back                         ║
╚══════════════════════════════════════════════════════════╝

3. Contract Detail View #

╔══════════════════════════════════════════════════════════╗
║  KT1EcsqR69BHekYF5mDQquxrvNg5HhPFx6NM                     ║
║  Mainnet Staging                                          ║
╠══════════════════════════════════════════════════════════╣
║                                                          ║
║  Admin:     tz1dfoQDuxjwSgxdqJnisyKUxDHweade4Gzt         ║
║  Minter:    tz1dfoQDuxjwSgxdqJnisyKUxDHweade4Gzt         ║
║  Tokens:    1                                            ║
║  Balance:   0.05 ꜩ                                       ║
║                                                          ║
║  TOKEN LIST:                                             ║
║    #0  $cow    1 minted   holder: tz1gkf...BHE           ║
║                                                          ║
║  ─────────────────────────────────────────────────────── ║
║  ADMIN OPERATIONS (requires admin wallet):               ║
║  [1] set_metadata   [2] update_minter   [3] update_admin ║
║  [4] Toggle pause   [5] Withdraw balance                 ║
║                                                          ║
║  [O] Open on objkt  [T] Open on TzKT  [B] Back           ║
╚══════════════════════════════════════════════════════════╝

4. Wallet Rolodex #

╔══════════════════════════════════════════════════════════╗
║              WALLET ROLODEX                              ║
╠══════════════════════════════════════════════════════════╣
║                                                          ║
║  → [1] staging    tz1dfo...Gzt  (vault)   0.95 ꜩ         ║
║    [2] kidlisp    tz1dfo...Gzt  (vault)   0.00 ꜩ         ║
║    [3] aesthetic  tz1gkf...BHE  (beacon)  --             ║
║    [4] + Add custom wallet                               ║
║                                                          ║
║  ─────────────────────────────────────────────────────── ║
║  CURRENT: staging                                        ║
║  Can sign: ✓ (vault key loaded)                          ║
║                                                          ║
║  [Enter] Switch to wallet  [B] Back                      ║
╚══════════════════════════════════════════════════════════╝

CLI Commands #

The TUI also supports direct CLI commands for scripting:

# List contracts
node keeps-tui.mjs contracts --network mainnet

# Switch wallet
node keeps-tui.mjs wallet use staging

# Mint a token
node keeps-tui.mjs mint --name '$butterfly' --wallet staging --network mainnet

# View token
node keeps-tui.mjs token 0 --contract KT1Ecs...

# Admin operations
node keeps-tui.mjs admin set-minter --address tz1abc... --contract KT1Ecs...
node keeps-tui.mjs admin set-metadata --uri ipfs://... --contract KT1Ecs...

Security Model #

Critical Rules #

Private keys NEVER leave the vault
- Keys are loaded into memory only during signing
- No key export or display functions
- All signing happens through wrapper functions

Vault structure

aesthetic-computer-vault/
└── tezos/
    ├── staging/.env    # TEZOS_PRIVATE_KEY=edsk...
    ├── kidlisp/.env    # TEZOS_PRIVATE_KEY=edsk...
    └── wallets.json    # Address registry (no keys)

External wallets via Beacon
- For wallets where vault key isn't available
- Requires manual approval in wallet app
- Used for aesthetic.tez (Jeffrey's main wallet)
Audit logging
- All admin operations logged with timestamp
- Logs stored in vault (not repo)
- Includes: operation, wallet, contract, result

Implementation Phases #

Phase 1: Read-Only Browser #

Contract list view
Token browser
TzKT integration
Basic TUI framework (blessed or ink)

Phase 2: Wallet Management #

Vault key loading
Wallet rolodex UI
Balance display
Beacon SDK integration

Phase 3: Admin Operations #

Mint via TUI
set_metadata
update_minter / update_admin
Pause/unpause

Phase 4: Deployment #

Deploy new contract from TUI
Contract comparison (diff storage/code)
Migration tools

Dependencies #

{
  "dependencies": {
    "blessed": "^0.1.81",       // Terminal UI
    "@taquito/taquito": "^19",  // Tezos operations
    "@airgap/beacon-sdk": "^4", // External wallet connection
    "dotenv": "^16"             // Vault env loading
  }
}

File Location #

tezos/
├── keeps.mjs            # Existing CLI (mint, deploy, etc.)
├── keeps-tui.mjs        # NEW: Interactive TUI entry point
├── keeps-vault.mjs      # NEW: Secure vault key loader
├── keeps-contracts.mjs  # NEW: Contract registry
└── KEEPS-TUI-PLAN.md    # This document

Notes #

Start with Phase 1 (read-only) to validate the TUI framework choice
Consider using ink (React for CLI) if blessed feels dated
The existing keeps.mjs commands will be wrapped, not replaced
All destructive operations require confirmation prompt