1  # Tableland Module
  2  
  3  Clean, organized Tableland operations. All scripts are network-agnostic and support both private key and Ledger signing.
  4  
  5  ## 📁 Folder Structure
  6  
  7  ```
  8  tableland/
  9  ├── deploy/                  # Deployment scripts
 10  │   ├── unified-deploy.ts    # Main unified deployment tool
 11  │   ├── index.ts            # Entry point wrapper
 12  │   ├── README.md           # Deployment documentation
 13  │   └── deprecated/         # Legacy scripts (do not use)
 14  │       ├── deploy-table.ts # Old single deployment
 15  │       └── MIGRATION.md    # Migration guide
 16  ├── operations/             # CRUD operations
 17  │   ├── add/               # Add songs (supports --ledger)
 18  │   ├── update/            # Update data
 19  │   └── query/             # Query data
 20  ├── deployments/           # Deployment records
 21  │   ├── testnet/          # Test network deployments
 22  │   └── mainnet/          # Main network deployments
 23  ├── scripts/              # Utility scripts
 24  ├── config.ts             # Centralized configuration
 25  └── package.json          # NPM scripts and dependencies
 26  ```
 27  
 28  ## 🌐 Available Networks
 29  
 30  All defined in `config.ts`:
 31  - `optimism-sepolia` (default for most scripts)
 32  - `base-sepolia`
 33  - `base-mainnet`
 34  - `optimism-mainnet`
 35  
 36  ## 🚀 Core Operations
 37  
 38  ### Deploy Tables (Unified System)
 39  
 40  The new unified deployment system provides powerful features for managing table deployments:
 41  
 42  ```bash
 43  # Show deployment help
 44  bun run deploy --help
 45  
 46  # Deploy a single table with private key
 47  bun run deploy:table songs base-mainnet
 48  
 49  # Deploy with Ledger
 50  bun run deploy:table songs base-mainnet --ledger
 51  bun run deploy:table songs base-mainnet --ledger --path "m/44'/60'/0'/0/1"
 52  
 53  # Dry run (preview without deploying)
 54  bun run deploy:table songs base-mainnet --dry-run
 55  
 56  # Batch deploy multiple tables
 57  bun run deploy:batch songs,user_history base-mainnet
 58  bun run deploy:batch all base-mainnet,base-sepolia --ledger
 59  
 60  # List all deployments
 61  bun run deploy:list
 62  bun run deploy:list base-mainnet
 63  
 64  # Verify a deployment
 65  bun run deploy:verify songs base-mainnet
 66  
 67  # Legacy method (still supported)
 68  bun run deploy:legacy songs base-mainnet
 69  ```
 70  
 71  ### Add Songs
 72  ```bash
 73  # Add single song with private key
 74  bun run add song.json
 75  bun run add song.json base-mainnet
 76  bun run add song.json base-mainnet karaoke_songs_8453_123
 77  
 78  # Add single song with Ledger
 79  bun run add song.json base-mainnet --ledger
 80  bun run add song.json --ledger  # uses default network
 81  
 82  # Batch add songs with private key
 83  bun run batch ./songs-folder/
 84  bun run batch ./songs-folder/ optimism-sepolia
 85  
 86  # Batch add songs with Ledger
 87  bun run batch ./songs-folder/ base-mainnet --ledger
 88  ```
 89  
 90  ### Query Data
 91  ```bash
 92  # Query any network (default: optimism-sepolia)
 93  bun run query "SELECT * FROM {table}"
 94  
 95  # Query specific network
 96  bun run query "SELECT * FROM {table}" base-mainnet
 97  
 98  # Query with custom table
 99  bun run query "SELECT * FROM {table}" optimism-sepolia "custom_table_name"
100  ```
101  
102  ### Update Data
103  ```bash
104  # Update on default network
105  bun run update 1 '{"title":"New Title"}'
106  
107  # Update on specific network
108  bun run update 1 '{"stems":{"piano":"QmNewCID"}}' base-mainnet
109  
110  # Update multiple fields
111  bun run update 1 '{"duration":195,"language":"es"}' optimism-sepolia
112  ```
113  
114  ## 📝 Usage Pattern
115  
116  All scripts follow the same pattern:
117  ```bash
118  script.ts <required-args> [network] [tableName] [--ledger] [--path <derivation-path>]
119  ```
120  
121  - If network is provided and valid, it's used
122  - Otherwise, the argument is treated as a table name on the default network
123  - Scripts automatically load table names from `deployments/` folder
124  - `--ledger` flag enables hardware wallet signing
125  - `--path` allows custom derivation paths for Ledger
126  
127  ## 🔤 Ledger Setup
128  
129  When using the `--ledger` flag:
130  
131  1. **Connect your Ledger device** via USB
132  2. **Unlock it** with your PIN
133  3. **Open the Ethereum app** on the device
134  4. **Enable "Contract data"** in the Ethereum app settings:
135     - Go to Settings → Contract data → Enable
136  5. **Approve each transaction** on the device when prompted
137  
138  ## 💾 Deployment Records
139  
140  All deployments are automatically saved:
141  ```
142  deployments/
143  ├── testnet/
144  │   ├── optimism_sepolia.json
145  │   └── base_sepolia.json
146  └── mainnet/
147      ├── base_mainnet.json
148      └── optimism_mainnet.json
149  ```
150  
151  Format:
152  ```json
153  {
154    "tables": {
155      "songs": {
156        "network": "optimism-sepolia",
157        "chainId": 11155420,
158        "tableName": "karaoke_songs_11155420_123",
159        "transactionHash": "0x...",
160        "deployedAt": "2024-01-21T10:30:00Z",
161        "deployedBy": "0x..."
162      }
163    },
164    "lastUpdated": "2024-01-21T10:30:00Z"
165  }
166  ```
167  
168  ## 🔧 Configuration
169  
170  ### Environment Variables
171  
172  Create a `.env` file in the parent directory with:
173  
174  ```env
175  # For private key signing
176  PRIVATE_KEY=your_private_key_here
177  
178  # Optional: Custom RPC URLs
179  BASE_MAINNET_RPC_URL=https://mainnet.base.org
180  OPTIMISM_MAINNET_RPC_URL=https://mainnet.optimism.io
181  
182  # Optional: Table name (for compatibility)
183  SONGS_TABLE_NAME=karaoke_songs_8453_123
184  ```
185  
186  ### `config.ts`
187  Centralized config with network settings and table schemas. Add new networks/schemas here.
188  
189  ### `TableManager.ts`
190  Reusable class for programmatic table operations.
191  
192  ## 📋 Data Structure
193  
194  Songs table includes:
195  - `id`, `isrc`, `iswc`, `title`, `artist`, `duration`, `language`
196  - `stems` - JSON: `{"piano":"QmCID"}` (will expand to multiple instruments)
197  - `translations` - JSON: `{"zh":"QmCID","ug":"QmCID","bo":"QmCID"}`
198  - `artwork_hash` - JSON: `{"id":"hash","ext":"png","sizes":{"t":"300x300x1"}}`
199  - `streaming_links` - JSON: `{"spotify":"id","youtube":"id"}`
200  - `genius_id`, `lrclib_id`, `genius_slug`
201  - `updated_at` - Unix timestamp
202  
203  ## 🔐 Encryption Flow
204  
205  1. **Encrypt**: Lit Protocol encrypts content using Base Sepolia contract access conditions
206  2. **Store**: Encrypted content uploaded to IPFS via Pinata
207  3. **Index**: CIDs stored in Optimism Sepolia Tableland for metadata
208  4. **Access**: Web app queries Tableland → fetches from IPFS → decrypts with Lit
209  
210  ## 🔄 Workflow After Contract Update
211  
212  When the smart contract is updated and content is re-encrypted:
213  
214  1. **Get new IPFS CIDs** from re-encryption output:
215     ```bash
216     # After running scripts/re-encrypt-songs.sh, you'll see:
217     # Song 1: MIDI CID: QmU6BW8DHL8Ack54Pmtu18mjPFhGYmQy3V45br5dJN8WSL
218     # Song 1: Lyrics CID: QmPQRRJcnnsLEg59kEtHSoPeAe9rWfa7PwYYWtWUniXHCW
219     ```
220  
221  2. **Update each song** with new CIDs:
222     ```bash
223     # Update Song 1
224     bun run update 1 '{
225       "stems": {
226         "piano": "QmU6BW8DHL8Ack54Pmtu18mjPFhGYmQy3V45br5dJN8WSL"
227       },
228       "translations": {
229         "zh": "QmPQRRJcnnsLEg59kEtHSoPeAe9rWfa7PwYYWtWUniXHCW",
230         "ug": "QmPQRRJcnnsLEg59kEtHSoPeAe9rWfa7PwYYWtWUniXHCW",
231         "bo": "QmPQRRJcnnsLEg59kEtHSoPeAe9rWfa7PwYYWtWUniXHCW"
232       }
233     }' optimism-sepolia
234     ```
235  
236  3. **Verify updates**:
237     ```bash
238     bun run query "SELECT id, title, stems, translations FROM {table}"
239     ```
240  
241  ## 🔒 Security Notes
242  
243  - **Never commit private keys** to version control
244  - **Use Ledger for mainnet** deployments to ensure security
245  - **Verify addresses** before approving transactions on Ledger
246  - **Test on testnet first** before mainnet deployments
247  
248  ## 🚫 Anti-Bloat Rules
249  
250  - ✅ Use existing tools for updates/queries
251  - ❌ Don't create new scripts for one-off tasks
252  - ✅ Add functionality to existing modular tools
253  - ❌ Don't duplicate query/update logic
254  
255  ## 🎯 Unified Deployment System
256  
257  The new unified deployment system (`deploy/unified-deploy.ts`) consolidates all deployment functionality:
258  
259  ### Key Features
260  - **Single Entry Point**: All deployment operations through one tool
261  - **Batch Deployments**: Deploy multiple tables across multiple networks
262  - **Deployment Tracking**: Automatic tracking and history
263  - **Dry Run Mode**: Preview deployments before execution
264  - **Built-in Verification**: Verify deployments are accessible
265  - **Hardware Wallet Support**: Full Ledger integration
266  - **Better Error Handling**: Comprehensive error messages
267  
268  ### Migration from Legacy Scripts
269  - `deploy-table.ts` → `bun run deploy:table`
270  - `deploy-tables.ts` → `bun run deploy:batch`
271  - `deploy-table-ledger-*.ts` → `bun run deploy:table --ledger`
272  
273  See [deploy/README.md](deploy/README.md) for complete documentation.
274  
275  ## 🔄 Migration Notes
276  
277  All deployment and operation scripts have been modernized:
278  - **Deployment**: Use the unified deployment system
279  - **Operations**: All scripts support `--ledger` flag
280  - **Legacy Scripts**: Preserved in `deprecated/` folders but should not be used
281  
282  This provides a cleaner, more maintainable codebase with consistent CLI interfaces across all operations.