chunktech 0.1.0 → 0.3.0

package/README.md

@@ -2,15 +2,17 @@
 
 On-chain file storage via chunked transactions for EVM chains.
 
-Store and retrieve files on Ethereum, Base, and Arbitrum using transaction calldata.
+Store and retrieve files on Ethereum, Base, and Arbitrum using transaction calldata. Includes specialized support for censorship-resistant browser extension distribution.
 
 ## Features
 
 - **Chunk** - Split files into 33.3KB pieces for on-chain storage
-- **Send** - Broadcast chunks as transactions
+- **Send** - Broadcast chunks as self-transfer transactions
 - **Track** - Monitor transaction confirmations
 - **Reassemble** - Reconstruct files from on-chain data
 - **Encrypt** - Optional X3DH encryption for private data
+- **Cross-Chain** - Store data on L2, pointer on mainnet
+- **Extensions** - Distribute Chrome/Firefox extensions via inscriptions
 
 ## Installation
 
@@ -23,27 +25,6 @@ For encryption support:
 npm install @noble/curves @noble/hashes
 ```
 
-## Configuration
-
-Copy `.env.example` to `.env` and configure:
-
-```bash
-cp .env.example .env
-```
-
-```env
-# Private key for signing transactions (without 0x prefix)
-PRIVATE_KEY=your_private_key_here
-
-# RPC URLs (optional - uses public RPCs if not set)
-RPC_BASE=https://mainnet.base.org
-RPC_ARBITRUM=https://arb1.arbitrum.io/rpc
-RPC_ETHEREUM=https://eth.llamarpc.com
-
-# Default chain
-DEFAULT_CHAIN=base
-```
-
 ## Quick Start
 
 ```typescript
@@ -52,120 +33,220 @@ import { createWalletClient, http } from 'viem';
 import { base } from 'viem/chains';
 import { privateKeyToAccount } from 'viem/accounts';
 
-// Load from environment
 const account = privateKeyToAccount(`0x${process.env.PRIVATE_KEY}`);
 const walletClient = createWalletClient({
   account,
   chain: base,
-  transport: http(process.env.RPC_BASE),
+  transport: http(),
 });
 
-// Initialize ChunkTech
 const ct = new ChunkTech({ walletClient });
 
-// Upload a file
-const file = new Uint8Array([...]); // Your file data
-const result = await ct.upload(file, {
-  onProgress: (sent, total) => console.log(`${sent}/${total} chunks sent`),
+// Upload
+const result = await ct.upload(fileData, {
+  onProgress: (sent, total) => console.log(`${sent}/${total}`),
 });
 
-console.log('Chunk ID:', result.chunkId);
-console.log('TX Hashes:', result.txHashes);
-
-// Download the file
+// Download
 const downloaded = await ct.download(result.txHashes);
-console.log('Retrieved:', downloaded.data);
 ```
 
-## API
+## Browser Extension Distribution
 
-### `new ChunkTech(config)`
+Distribute Chrome and Firefox extensions as on-chain inscriptions. The inscription itself is the installer - a self-contained HTML page that fetches extension data from L2 and offers downloads.
 
-Create a new ChunkTech instance.
+```
+┌─────────────────────────────────────────────────────────┐
+│  Inscription (Ethereum)                                 │
+│                                                         │
+│  Self-contained HTML that:                              │
+│  ├── Shows extension info + download buttons            │
+│  ├── Fetches chunks from Base via RPC                   │
+│  ├── Reassembles + verifies SHA256                      │
+│  └── Downloads as .zip (Chrome) or .xpi (Firefox)       │
+│                                                         │
+└─────────────────────────────────────────────────────────┘
+```
+
+### Upload Extension
 
 ```typescript
-interface ChunkTechConfig {
-  walletClient: WalletClient;    // viem WalletClient for signing
-  publicClient?: PublicClient;   // Optional, created from walletClient if not provided
-  chain?: Chain;                 // Optional, detected from walletClient
-  rpcUrl?: string;               // Optional custom RPC URL
-}
+import { ExtensionUploader } from 'chunktech';
+import { createWalletClient, http } from 'viem';
+import { base, mainnet } from 'viem/chains';
+import { privateKeyToAccount } from 'viem/accounts';
+import { readFileSync } from 'fs';
+
+const account = privateKeyToAccount(`0x${process.env.PRIVATE_KEY}`);
+
+const uploader = new ExtensionUploader({
+  keyChain: 'ethereum',     // Inscription lives here (1 tx)
+  dataChain: 'base',        // Extension data lives here (cheap)
+  keyWalletClient: createWalletClient({
+    account,
+    chain: mainnet,
+    transport: http(),
+  }),
+  dataWalletClient: createWalletClient({
+    account,
+    chain: base,
+    transport: http(),
+  }),
+});
+
+const result = await uploader.upload({
+  name: 'My Extension',
+  version: '1.0.0',
+  developer: 'vitalik.eth',
+  description: 'A censorship-resistant browser extension',
+  homepage: 'https://myextension.xyz',
+  chrome: readFileSync('dist/chrome.zip'),
+  firefox: readFileSync('dist/firefox.xpi'),
+}, {
+  onProgress: (phase, sent, total) => {
+    console.log(`${phase}: ${sent}/${total}`);
+  },
+});
+
+console.log('Inscription TX:', result.inscriptionTxHash);
+// View at: https://ethscriptions.com/ethscriptions/0x...
+```
+
+### What Users See
+
+The inscription renders as a download page:
+
 ```
+╔═══════════════════════════════════════════════════╗
+║         My Extension v1.0.0                       ║
+║         vitalik.eth                               ║
+╚═══════════════════════════════════════════════════╝
+
+A censorship-resistant browser extension
+
+┌─────────────────┐    ┌─────────────────┐
+│  Chrome/Brave   │    │    Firefox      │
+│   [Detected]    │    │                 │
+│  [Download]     │    │  [Download]     │
+│   142 KB        │    │   138 KB        │
+└─────────────────┘    └─────────────────┘
+
+Installation Instructions:
+1. Download the extension
+2. Unzip (Chrome) or keep as .xpi (Firefox)
+3. Load in developer mode / Install from file
+```
+
+### Why This Matters
+
+- **Censorship-resistant** - No app store can remove it
+- **Immutable** - Code is permanently on-chain
+- **Verifiable** - SHA256 verified on download
+- **Self-contained** - The inscription IS the installer
+- **Multi-browser** - Chrome, Brave, Edge, Firefox from one inscription
 
-### `upload(data, options)`
+## Cross-Chain Upload
 
-Upload data to the blockchain.
+Store bulk data on L2 (cheap), pointer on mainnet (durable):
 
 ```typescript
-const result = await ct.upload(data, {
-  encrypt: false,                // Enable encryption
-  keys: encryptionKeys,          // Required if encrypt: true
-  recipients: [...],             // Recipients for encrypted data
-  onProgress: (sent, total) => {}, // Progress callback
-  confirmations: 1,              // Wait for confirmations
+import { CrossChainUploader } from 'chunktech';
+
+const uploader = new CrossChainUploader({
+  keyChain: 'ethereum',
+  dataChain: 'base',
+  keyWalletClient,
+  dataWalletClient,
+});
+
+const result = await uploader.upload(fileData, {
+  format: 'html',
+  title: 'My File',
 });
 
-// Returns:
-{
-  chunkId: string;       // Unique ID for this upload
-  txHashes: Hash[];      // Transaction hashes
-  totalChunks: number;   // Number of chunks sent
-  totalBytes: number;    // Original data size
-}
+// result.keyTxHash = mainnet inscription (self-loading HTML)
+// result.dataTxHashes = Base data chunks
 ```
 
-### `download(txHashes, options)`
+## API Reference
+
+### ChunkTech
 
-Download and reassemble data from the blockchain.
+Main class for single-chain uploads.
 
 ```typescript
-const result = await ct.download(txHashes, {
-  keys: encryptionKeys,     // Required if data was encrypted
-  recipientId: 'myId',      // Required if data was encrypted
+const ct = new ChunkTech({
+  walletClient: WalletClient,  // viem wallet
+  publicClient?: PublicClient, // Optional
+  chain?: Chain,               // Auto-detected
+  rpcUrl?: string,             // Custom RPC
 });
 
-// Returns:
-{
-  data: Uint8Array;      // The reassembled file
-  chunkId: string;       // Chunk set ID
-  totalChunks: number;   // Number of chunks retrieved
-}
+// Upload
+const result = await ct.upload(data, {
+  encrypt?: boolean,
+  keys?: EncryptionKeys,
+  recipients?: Recipient[],
+  onProgress?: (sent, total) => void,
+  confirmations?: number,
+});
+
+// Download
+const result = await ct.download(txHashes, {
+  keys?: EncryptionKeys,
+  recipientId?: string,
+});
 ```
 
-## Encryption
+### ExtensionUploader
 
-ChunkTech supports optional X3DH encryption for private data.
+Specialized uploader for browser extensions.
 
 ```typescript
-import { generateEncryptionKeys, deriveKeysFromSignature } from 'chunktech';
+const uploader = new ExtensionUploader({
+  keyChain: 'ethereum' | 'sepolia',
+  dataChain: 'base' | 'baseSepolia',
+  keyWalletClient: WalletClient,
+  dataWalletClient: WalletClient,
+  keyRpcUrl?: string,
+  dataRpcUrl?: string,
+});
 
-// Generate new keys
-const myKeys = await generateEncryptionKeys();
+const result = await uploader.upload({
+  name: string,
+  version: string,
+  developer: string,
+  description?: string,
+  homepage?: string,
+  chrome?: Uint8Array,
+  firefox?: Uint8Array,
+}, {
+  onProgress?: (phase, sent, total) => void,
+  confirmations?: number,
+});
+```
 
-// Or derive from wallet signature (deterministic)
-const signature = await wallet.signMessage('chunktech-keys');
-const myKeys = await deriveKeysFromSignature(signature);
+### CrossChainUploader
 
-// Upload encrypted data
-await ct.upload(data, {
-  encrypt: true,
-  keys: myKeys,
-  recipients: [
-    { id: 'alice', bundle: aliceBundle },
-    { id: 'bob', bundle: bobBundle },
-  ],
+General-purpose cross-chain uploader with HTML loader.
+
+```typescript
+const uploader = new CrossChainUploader({
+  keyChain: ChainName,
+  dataChain: ChainName,
+  keyWalletClient: WalletClient,
+  dataWalletClient: WalletClient,
 });
 
-// Download encrypted data
-const result = await ct.download(txHashes, {
-  keys: myKeys,
-  recipientId: 'sender', // Use 'sender' if you're the uploader
+const result = await uploader.upload(data, {
+  format?: 'html' | 'json',
+  title?: string,
+  description?: string,
+  mimeType?: string,
 });
 ```
 
-## Low-Level API
-
-For more control, use the individual modules:
+### Low-Level Utilities
 
 ```typescript
 import {
@@ -175,75 +256,151 @@ import {
   decodeChunk,
   reassembleChunks,
   ChunkTracker,
+  estimateChunks,
 
   // Sending
   sendChunk,
   sendChunks,
+  sendChunksParallel,
 
   // Tracking
+  waitForTransaction,
   waitForTransactions,
   TransactionMonitor,
 
   // Fetching
   fetchChunk,
+  fetchChunks,
   assembleFromHashes,
   StreamingAssembler,
+
+  // Encryption
+  generateEncryptionKeys,
+  deriveKeysFromSignature,
+  encryptForRecipients,
+  decryptForRecipient,
 } from 'chunktech';
 ```
 
-### Chunking
+## Encryption
+
+Optional X3DH + AES-256-GCM encryption for private data.
 
 ```typescript
-// Split data into chunks
-const chunked = chunkData(myData);
-console.log(`${chunked.total} chunks, ID: ${chunked.id}`);
+import { generateEncryptionKeys } from 'chunktech';
 
-// Encode for on-chain storage
-const calldata = encodeChunk(chunked.chunks[0]);
+const myKeys = await generateEncryptionKeys();
 
-// Decode from calldata
-const chunk = decodeChunk(calldata);
+// Upload encrypted
+await ct.upload(data, {
+  encrypt: true,
+  keys: myKeys,
+  recipients: [
+    { id: 'alice', bundle: aliceKeys.bundle },
+  ],
+});
+
+// Download encrypted
+const result = await ct.download(txHashes, {
+  keys: myKeys,
+  recipientId: 'sender',
+});
 ```
 
-### Streaming Reassembly
+## Supported Chains
 
-```typescript
-const tracker = new ChunkTracker();
+| Chain | ID | Use Case |
+|-------|-----|----------|
+| Ethereum | 1 | Inscriptions, durability |
+| Base | 8453 | Cheap data storage |
+| Arbitrum | 42161 | Cheap data storage |
+| Sepolia | 11155111 | Testing |
+| Base Sepolia | 84532 | Testing |
+| Arbitrum Sepolia | 421614 | Testing |
+
+## Cost Estimates
 
-for (const txHash of incomingHashes) {
-  const result = await fetchChunk(publicClient, txHash);
-  if (result.chunk) {
-    const assembled = tracker.add(result.chunk);
-    if (assembled) {
-      console.log('Complete!', assembled);
-    }
-  }
-}
+For a 500KB extension on Base:
 
-// Check progress
-console.log(tracker.getIncomplete());
-// [{ id: '...', have: 2, need: 5 }]
 ```
+Chunks: ~15 (at 33KB each)
+Cost per chunk: ~$0.002
+Total: ~$0.03
 
-## Supported Chains
++ 1 Ethereum inscription: ~$2-5 (varies with gas)
+```
 
-| Chain | Chain ID |
-|-------|----------|
-| Ethereum | 1 |
-| Base | 8453 |
-| Arbitrum | 42161 |
-| Sepolia | 11155111 |
-| Base Sepolia | 84532 |
-| Arbitrum Sepolia | 421614 |
+## How It Works
 
-## Constants
+1. **Chunking** - Files split into 33.3KB pieces with metadata (ID, part, total)
+2. **Encoding** - Each chunk → JSON → base64 → prefixed calldata
+3. **Sending** - Self-transfer transactions (to == from, value = 0)
+4. **Storage** - Calldata stored permanently in transaction history
+5. **Retrieval** - Fetch via `eth_getTransactionByHash`, decode, reassemble
+6. **Verification** - SHA256 hash checked after reassembly
 
-```typescript
-import { MAX_CHUNK_SIZE } from 'chunktech';
+## On-Chain Viewer Pages
+
+Create standalone HTML pages that fetch, verify, and display on-chain content. Perfect for:
+- NPM packages with auditable source
+- Browser extensions with install instructions
+- Any file needing public verification
+
+### Quick Inscribe
+
+```javascript
+import { readFileSync } from 'fs';
+import { createWalletClient, http, toHex } from 'viem';
+import { base } from 'viem/chains';
+import { createHash } from 'crypto';
+
+const zipData = readFileSync('package.zip');
+const base64 = zipData.toString('base64');
+const sha256 = createHash('sha256').update(zipData).digest('hex');
+
+const dataUri = `data:application/zip;base64,${base64}`;
+const calldata = toHex(new TextEncoder().encode(dataUri));
+
+const hash = await walletClient.sendTransaction({
+  to: account.address,
+  data: calldata,
+});
+
+console.log(`TX: ${hash}`);
+console.log(`SHA256: ${sha256}`);
+```
+
+### Viewer HTML
+
+The viewer fetches from any RPC, verifies SHA256, and displays source:
 
-// MAX_CHUNK_SIZE = 33333 (33.3KB)
-// This ensures wrapped chunks stay under 128KB tx limit
 ```
+┌─────────────────────────────────────────┐
+│  MyPackage v1.0.0                       │
+│                                         │
+│  [Download]  [Verify On-Chain]          │
+│                                         │
+│  ┌─────────────────────────────────┐    │
+│  │ README │ index.ts │ package.json│    │
+│  ├─────────────────────────────────┤    │
+│  │                                 │    │
+│  │  // Source code displayed here  │    │
+│  │                                 │    │
+│  └─────────────────────────────────┘    │
+└─────────────────────────────────────────┘
+```
+
+Key features:
+- Fetches tx via public RPC (no backend)
+- SHA256 verification on download
+- Source code tabs for auditing
+- Works offline once loaded
+
+See `skill.md` for full implementation details.
+
+## Acknowledgments
+
+- [calldata-rpc](https://github.com/chopperdaddy/calldata-rpc) by [@chopperdaddy](https://github.com/chopperdaddy) - Decentralized RPC endpoint discovery via IPFS and ENS, used in the HTML loaders for reliable chain access.
 
 ## License
 

package/dist/crosschain.d.ts

@@ -0,0 +1,24 @@
+/**
+ * ChunkTech - Cross-Chain Upload
+ * Key transaction on mainnet, bulk data on L2
+ */
+import type { CrossChainConfig, CrossChainUploadOptions, CrossChainUploadResult, CrossChainManifest } from './types.js';
+export declare class CrossChainUploader {
+    private keyWalletClient;
+    private dataWalletClient;
+    private keyPublicClient;
+    private dataPublicClient;
+    private keyChain;
+    private dataChain;
+    constructor(config: CrossChainConfig);
+    /**
+     * Upload data across chains - key on mainnet, chunks on L2
+     */
+    upload(data: Uint8Array | ArrayBuffer | string, options?: CrossChainUploadOptions): Promise<CrossChainUploadResult>;
+}
+declare function generateHtmlLoader(manifest: CrossChainManifest, options: {
+    title: string;
+    description: string;
+}): string;
+export { generateHtmlLoader };
+//# sourceMappingURL=crosschain.d.ts.map

package/dist/crosschain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"crosschain.d.ts","sourceRoot":"","sources":["../src/crosschain.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAMH,OAAO,KAAK,EAEV,gBAAgB,EAChB,uBAAuB,EACvB,sBAAsB,EACtB,kBAAkB,EAEnB,MAAM,YAAY,CAAC;AAuBpB,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,eAAe,CAAe;IACtC,OAAO,CAAC,gBAAgB,CAAe;IAEvC,OAAO,CAAC,eAAe,CAAM;IAC7B,OAAO,CAAC,gBAAgB,CAAM;IAC9B,OAAO,CAAC,QAAQ,CAAY;IAC5B,OAAO,CAAC,SAAS,CAAY;gBAEjB,MAAM,EAAE,gBAAgB;IAiBpC;;OAEG;IACG,MAAM,CACV,IAAI,EAAE,UAAU,GAAG,WAAW,GAAG,MAAM,EACvC,OAAO,GAAE,uBAA4B,GACpC,OAAO,CAAC,sBAAsB,CAAC;CAwFnC;AAMD,iBAAS,kBAAkB,CACzB,QAAQ,EAAE,kBAAkB,EAC5B,OAAO,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GAC9C,MAAM,CA+IR;AA0ED,OAAO,EAAE,kBAAkB,EAAE,CAAC"}