@btc-vision/cli 1.0.0

package/src/lib/ipfs.ts

@@ -0,0 +1,369 @@
+/**
+ * IPFS operations for OPNet CLI
+ *
+ * Handles pinning and fetching plugin binaries from IPFS.
+ *
+ * @module lib/ipfs
+ */
+
+import * as https from 'https';
+import * as http from 'http';
+import * as fs from 'fs';
+import { loadConfig } from './config.js';
+
+/**
+ * IPFS pinning result
+ */
+export interface PinResult {
+    cid: string;
+    size: number;
+}
+
+/**
+ * IPFS gateway fetch result
+ */
+export interface FetchResult {
+    data: Buffer;
+    size: number;
+}
+
+/**
+ * HTTP request options
+ */
+interface RequestOptions {
+    method: string;
+    headers?: Record<string, string>;
+    body?: Buffer | string;
+    timeout?: number;
+}
+
+/**
+ * Make an HTTP/HTTPS request
+ *
+ * @param url - The URL to request
+ * @param options - Request options
+ * @returns Response body buffer
+ */
+async function httpRequest(url: string, options: RequestOptions): Promise<Buffer> {
+    return new Promise((resolve, reject) => {
+        const parsedUrl = new URL(url);
+        const isHttps = parsedUrl.protocol === 'https:';
+        const lib = isHttps ? https : http;
+
+        const reqOptions: https.RequestOptions = {
+            hostname: parsedUrl.hostname,
+            port: parsedUrl.port || (isHttps ? 443 : 80),
+            path: parsedUrl.pathname + parsedUrl.search,
+            method: options.method,
+            headers: options.headers || {},
+            timeout: options.timeout || 30000,
+        };
+
+        const req = lib.request(reqOptions, (res) => {
+            const chunks: Buffer[] = [];
+
+            res.on('data', (chunk: Buffer) => {
+                chunks.push(chunk);
+            });
+
+            res.on('end', () => {
+                const body = Buffer.concat(chunks);
+
+                if (res.statusCode && res.statusCode >= 200 && res.statusCode < 300) {
+                    resolve(body);
+                } else {
+                    reject(
+                        new Error(
+                            `HTTP ${res.statusCode}: ${res.statusMessage} - ${body.toString()}`,
+                        ),
+                    );
+                }
+            });
+        });
+
+        req.on('error', reject);
+        req.on('timeout', () => {
+            req.destroy();
+            reject(new Error('Request timeout'));
+        });
+
+        if (options.body) {
+            req.write(options.body);
+        }
+
+        req.end();
+    });
+}
+
+/**
+ * Pin a file to IPFS using the configured pinning service
+ *
+ * @param data - The file data to pin
+ * @param name - Optional file name for metadata
+ * @returns The IPFS CID
+ */
+export async function pinToIPFS(data: Buffer, name?: string): Promise<PinResult> {
+    const config = loadConfig();
+    const endpoint = config.ipfsPinningEndpoint;
+
+    if (!endpoint) {
+        throw new Error(
+            'IPFS pinning endpoint not configured. Run `opnet config set ipfsPinningEndpoint <url>`',
+        );
+    }
+
+    // Build multipart form data
+    const boundary = '----FormBoundary' + Math.random().toString(36).substring(2);
+    const fileName = name || 'plugin.opnet';
+
+    const formParts: Buffer[] = [];
+
+    // File part
+    formParts.push(
+        Buffer.from(
+            `--${boundary}\r\n` +
+                `Content-Disposition: form-data; name="file"; filename="${fileName}"\r\n` +
+                `Content-Type: application/octet-stream\r\n\r\n`,
+        ),
+    );
+    formParts.push(data);
+    formParts.push(Buffer.from('\r\n'));
+
+    // End boundary
+    formParts.push(Buffer.from(`--${boundary}--\r\n`));
+
+    const body = Buffer.concat(formParts);
+
+    // Build headers
+    const headers: Record<string, string> = {
+        'Content-Type': `multipart/form-data; boundary=${boundary}`,
+        'Content-Length': body.length.toString(),
+    };
+
+    // Add authorization if configured
+    if (config.ipfsPinningAuthHeader) {
+        const [headerName, headerValue] = config.ipfsPinningAuthHeader
+            .split(':')
+            .map((s) => s.trim());
+        if (headerName && headerValue) {
+            headers[headerName] = headerValue;
+        }
+    } else if (config.ipfsPinningApiKey) {
+        headers['Authorization'] = `Bearer ${config.ipfsPinningApiKey}`;
+    }
+
+    // Detect pinning service type from URL and adjust request
+    const url = new URL(endpoint);
+
+    let requestUrl: string;
+    if (url.hostname.includes('ipfs.opnet.org')) {
+        // OPNet IPFS gateway - uses standard IPFS API
+        requestUrl = endpoint;
+    } else if (url.hostname.includes('pinata')) {
+        // Pinata-specific endpoint
+        requestUrl = 'https://api.pinata.cloud/pinning/pinFileToIPFS';
+        if (config.ipfsPinningApiKey) {
+            headers['pinata_api_key'] = config.ipfsPinningApiKey;
+        }
+    } else if (url.hostname.includes('web3.storage') || url.hostname.includes('w3s.link')) {
+        // web3.storage endpoint
+        requestUrl = endpoint.endsWith('/') ? endpoint + 'upload' : endpoint + '/upload';
+    } else if (url.hostname.includes('nft.storage')) {
+        // nft.storage endpoint
+        requestUrl = 'https://api.nft.storage/upload';
+    } else if (url.pathname.includes('/api/v0/')) {
+        // Standard IPFS API endpoint
+        requestUrl = endpoint;
+    } else {
+        // Generic IPFS pinning service (assumed to follow IPFS Pinning Services API)
+        requestUrl = endpoint.endsWith('/') ? endpoint + 'pins' : endpoint + '/pins';
+    }
+
+    const response = await httpRequest(requestUrl, {
+        method: 'POST',
+        headers,
+        body,
+        timeout: 120000, // 2 minutes for upload
+    });
+
+    // Parse response to extract CID
+    const result = JSON.parse(response.toString()) as Record<string, unknown>;
+
+    // Handle different response formats
+    let cid: string | undefined;
+
+    if (typeof result.IpfsHash === 'string') {
+        // Pinata format
+        cid = result.IpfsHash;
+    } else if (typeof result.cid === 'string') {
+        // web3.storage / nft.storage format
+        cid = result.cid;
+    } else if (typeof result.Hash === 'string') {
+        // IPFS API format
+        cid = result.Hash;
+    } else if (result.value && typeof (result.value as Record<string, unknown>).cid === 'string') {
+        // NFT.storage wrapped format
+        cid = (result.value as Record<string, unknown>).cid as string;
+    }
+
+    if (!cid) {
+        throw new Error(`Failed to extract CID from pinning response: ${JSON.stringify(result)}`);
+    }
+
+    return {
+        cid,
+        size: data.length,
+    };
+}
+
+/**
+ * Fetch a file from IPFS using configured gateways
+ *
+ * @param cid - The IPFS CID
+ * @returns The file data
+ */
+export async function fetchFromIPFS(cid: string): Promise<FetchResult> {
+    const config = loadConfig();
+    const gateways = config.ipfsGateways.length > 0 ? config.ipfsGateways : [config.ipfsGateway];
+
+    let lastError: Error | undefined;
+
+    for (const gateway of gateways) {
+        try {
+            const url = buildGatewayUrl(gateway, cid);
+            const data = await httpRequest(url, {
+                method: 'GET',
+                timeout: 60000, // 1 minute
+            });
+
+            return {
+                data,
+                size: data.length,
+            };
+        } catch (error) {
+            lastError = error instanceof Error ? error : new Error(String(error));
+            // Try next gateway
+            continue;
+        }
+    }
+
+    throw new Error(`Failed to fetch from all gateways: ${lastError?.message}`);
+}
+
+/**
+ * Build a gateway URL for a CID
+ *
+ * @param gateway - The gateway base URL
+ * @param cid - The IPFS CID
+ * @returns Full URL
+ */
+export function buildGatewayUrl(gateway: string, cid: string): string {
+    // Remove trailing slash
+    const base = gateway.replace(/\/$/, '');
+
+    // Handle different gateway URL patterns
+    if (base.includes('{cid}')) {
+        // Template URL
+        return base.replace('{cid}', cid);
+    } else if (base.includes('/ipfs/')) {
+        // Path-style gateway
+        return `${base}${cid}`;
+    } else {
+        // Standard gateway
+        return `${base}/ipfs/${cid}`;
+    }
+}
+
+/**
+ * Validate an IPFS CID
+ *
+ * @param cid - The CID to validate
+ * @returns True if valid CID format
+ */
+export function isValidCid(cid: string): boolean {
+    // CIDv0 (Qm...) or CIDv1 (ba...)
+    if (cid.startsWith('Qm') && cid.length === 46) {
+        // CIDv0 base58btc
+        return /^Qm[1-9A-HJ-NP-Za-km-z]{44}$/.test(cid);
+    } else if (cid.startsWith('ba')) {
+        // CIDv1 base32
+        return /^ba[a-z2-7]{57,}$/.test(cid);
+    } else if (cid.startsWith('b')) {
+        // Other CIDv1 bases
+        return cid.length >= 50;
+    }
+
+    return false;
+}
+
+/**
+ * Download a plugin binary from IPFS and save to file
+ *
+ * @param cid - The IPFS CID
+ * @param outputPath - Path to save the file
+ * @returns The downloaded file size
+ */
+export async function downloadPlugin(cid: string, outputPath: string): Promise<number> {
+    const result = await fetchFromIPFS(cid);
+    fs.writeFileSync(outputPath, result.data);
+    return result.size;
+}
+
+/**
+ * Upload a plugin binary file to IPFS
+ *
+ * @param filePath - Path to the plugin file
+ * @returns The IPFS CID
+ */
+export async function uploadPlugin(filePath: string): Promise<PinResult> {
+    const data = fs.readFileSync(filePath);
+    const fileName = filePath.split('/').pop() || 'plugin.opnet';
+    return pinToIPFS(data, fileName);
+}
+
+/**
+ * Check if a CID is available on any gateway
+ *
+ * @param cid - The IPFS CID
+ * @returns True if the file is accessible
+ */
+export async function checkAvailability(cid: string): Promise<boolean> {
+    try {
+        await fetchFromIPFS(cid);
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+/**
+ * Get IPFS gateway status
+ *
+ * @returns Object with gateway availability status
+ */
+export async function getGatewayStatus(): Promise<Record<string, boolean>> {
+    const config = loadConfig();
+    const gateways = config.ipfsGateways.length > 0 ? config.ipfsGateways : [config.ipfsGateway];
+
+    // Use a well-known CID for testing (empty directory)
+    const testCid = 'QmUNLLsPACCz1vLxQVkXqqLX5R1X345qqfHbsf67hvA3Nn';
+
+    const status: Record<string, boolean> = {};
+
+    await Promise.all(
+        gateways.map(async (gateway) => {
+            try {
+                const url = buildGatewayUrl(gateway, testCid);
+                await httpRequest(url, {
+                    method: 'HEAD',
+                    timeout: 10000,
+                });
+                status[gateway] = true;
+            } catch {
+                status[gateway] = false;
+            }
+        }),
+    );
+
+    return status;
+}

package/src/lib/manifest.ts

@@ -0,0 +1,172 @@
+/**
+ * Plugin manifest (plugin.json) utilities
+ *
+ * Uses @btc-vision/plugin-sdk for validation.
+ *
+ * @module lib/manifest
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import {
+    DEFAULT_LIFECYCLE,
+    DEFAULT_PERMISSIONS,
+    DEFAULT_RESOURCES,
+    IPluginMetadata,
+    IPluginPermissions,
+    IValidationResult,
+    PLUGIN_MANIFEST_FILENAME,
+    PLUGIN_NAME_REGEX,
+    validateManifest as sdkValidateManifest,
+} from '@btc-vision/plugin-sdk';
+
+/** Scoped package name pattern */
+const SCOPED_NAME_PATTERN = /^@[a-z][a-z0-9-]*\/[a-z][a-z0-9-]*$/;
+
+/**
+ * Validate a plugin name (scoped or unscoped)
+ *
+ * @param name - The name to validate
+ * @returns Array of validation errors (empty if valid)
+ */
+export function validatePluginName(name: string): string[] {
+    const errors: string[] = [];
+
+    if (!name) {
+        errors.push('Name is required');
+        return errors;
+    }
+
+    // Check if scoped
+    if (name.startsWith('@')) {
+        if (!SCOPED_NAME_PATTERN.test(name)) {
+            errors.push(
+                'Scoped name must be @scope/name where scope and name are lowercase alphanumeric with hyphens, starting with a letter',
+            );
+        }
+    } else {
+        if (!PLUGIN_NAME_REGEX.test(name)) {
+            errors.push('Name must be lowercase alphanumeric with hyphens, starting with a letter');
+        }
+    }
+
+    // Check length
+    if (name.length > 100) {
+        errors.push('Name must be 100 characters or less');
+    }
+
+    return errors;
+}
+
+/**
+ * Validate a complete plugin manifest using the SDK validator
+ *
+ * @param manifest - The manifest to validate
+ * @returns Validation result with field-specific errors
+ */
+export function validateManifest(manifest: Partial<IPluginMetadata>): IValidationResult {
+    return sdkValidateManifest(manifest);
+}
+
+/**
+ * Validate plugin permissions
+ *
+ * @param permissions - The permissions object
+ * @returns Array of validation errors (empty if valid)
+ */
+export function validatePermissions(permissions: IPluginPermissions): string[] {
+    const errors: string[] = [];
+
+    if (permissions.database?.enabled) {
+        if (!permissions.database.collections || !Array.isArray(permissions.database.collections)) {
+            errors.push('database.collections must be an array when database is enabled');
+        }
+    }
+
+    return errors;
+}
+
+/**
+ * Load and validate a plugin manifest from file
+ *
+ * @param manifestPath - Path to plugin.json
+ * @returns The loaded manifest or throws with validation errors
+ */
+export function loadManifest(manifestPath: string): IPluginMetadata {
+    const resolvedPath = path.resolve(manifestPath);
+
+    if (!fs.existsSync(resolvedPath)) {
+        throw new Error(`Manifest not found: ${resolvedPath}`);
+    }
+
+    let manifest: Partial<IPluginMetadata>;
+    try {
+        const content = fs.readFileSync(resolvedPath, 'utf-8');
+        manifest = JSON.parse(content) as Partial<IPluginMetadata>;
+    } catch (e) {
+        throw new Error(`Failed to parse manifest: ${e instanceof Error ? e.message : String(e)}`);
+    }
+
+    const result = validateManifest(manifest);
+    if (!result.valid) {
+        const errorList = result.errors.map((e) => `  - ${e.path}: ${e.message}`).join('\n');
+        throw new Error(`Invalid manifest:\n${errorList}`);
+    }
+
+    return manifest as IPluginMetadata;
+}
+
+/**
+ * Save a plugin manifest to file
+ *
+ * @param manifestPath - Path to save to
+ * @param manifest - The manifest to save
+ */
+export function saveManifest(manifestPath: string, manifest: IPluginMetadata): void {
+    const content = JSON.stringify(manifest, null, 4);
+    fs.writeFileSync(manifestPath, content, 'utf-8');
+}
+
+/**
+ * Create a default plugin manifest
+ *
+ * @param options - Manifest options
+ * @returns A complete manifest with defaults
+ */
+export function createManifest(options: {
+    name: string;
+    author: string;
+    email?: string;
+    description?: string;
+    pluginType: 'standalone' | 'library';
+}): IPluginMetadata {
+    return {
+        name: options.name,
+        version: '1.0.0',
+        opnetVersion: '^1.0.0',
+        main: 'dist/index.jsc',
+        target: 'bytenode',
+        type: 'plugin',
+        checksum: '',
+        author: {
+            name: options.author,
+            email: options.email,
+        },
+        description: options.description,
+        pluginType: options.pluginType,
+        permissions: DEFAULT_PERMISSIONS,
+        resources: DEFAULT_RESOURCES,
+        lifecycle: DEFAULT_LIFECYCLE,
+        dependencies: {},
+    };
+}
+
+/**
+ * Get the manifest path for a directory
+ *
+ * @param dir - Directory to search
+ * @returns Path to plugin.json
+ */
+export function getManifestPath(dir: string = process.cwd()): string {
+    return path.join(dir, PLUGIN_MANIFEST_FILENAME);
+}

package/src/lib/provider.ts

@@ -0,0 +1,121 @@
+/**
+ * JSONRpcProvider wrapper for OPNet CLI
+ *
+ * Provides a unified interface for blockchain interaction using the opnet package.
+ *
+ * @module lib/provider
+ */
+
+import { JSONRpcProvider } from 'opnet';
+
+import { NetworkName } from '../types/index.js';
+import { getRegistryAddress, getRpcUrl, loadConfig } from './config.js';
+import { getNetwork } from './wallet.js';
+
+/** Provider timeout in milliseconds */
+const DEFAULT_TIMEOUT = 30000;
+
+/**
+ * Provider instance cache
+ */
+const providerCache = new Map<string, JSONRpcProvider>();
+
+/**
+ * Get a JSONRpcProvider for a network
+ *
+ * @param network - Network name (defaults to configured default)
+ * @returns JSONRpcProvider instance
+ */
+export function getProvider(network?: NetworkName): JSONRpcProvider {
+    const config = loadConfig();
+    const targetNetwork = network || config.defaultNetwork;
+    const rpcUrl = getRpcUrl(targetNetwork);
+    const cacheKey = `${targetNetwork}:${rpcUrl}`;
+
+    // Return cached provider if available
+    const cached = providerCache.get(cacheKey);
+    if (cached) {
+        return cached;
+    }
+
+    // Create new provider
+    const bitcoinNetwork = getNetwork(targetNetwork);
+    const provider = new JSONRpcProvider(rpcUrl, bitcoinNetwork, DEFAULT_TIMEOUT);
+
+    providerCache.set(cacheKey, provider);
+    return provider;
+}
+
+/**
+ * Clear provider cache (useful for testing or network changes)
+ */
+export function clearProviderCache(): void {
+    providerCache.clear();
+}
+
+/**
+ * Get the registry contract address for a network
+ *
+ * @param network - Network name (defaults to configured default)
+ * @returns The registry contract address
+ */
+export function getRegistryContractAddress(network?: NetworkName): string {
+    return getRegistryAddress(network);
+}
+
+/**
+ * Check if the provider can connect to the RPC endpoint
+ *
+ * @param network - Network name (defaults to configured default)
+ * @returns True if connection successful
+ */
+export async function checkConnection(network?: NetworkName): Promise<boolean> {
+    try {
+        const provider = getProvider(network);
+        // Try to get the current block to verify connection
+        await provider.getBlockNumber();
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+/**
+ * Get the current block number
+ *
+ * @param network - Network name (defaults to configured default)
+ * @returns Current block number
+ */
+export async function getBlockNumber(network?: NetworkName): Promise<bigint> {
+    const provider = getProvider(network);
+    return provider.getBlockNumber();
+}
+
+/**
+ * Get the balance for an address
+ *
+ * @param address - The address to check
+ * @param network - Network name (defaults to configured default)
+ * @returns Balance in satoshis
+ */
+export async function getBalance(address: string, network?: NetworkName): Promise<bigint> {
+    const provider = getProvider(network);
+    return provider.getBalance(address);
+}
+
+/**
+ * Broadcast a signed transaction
+ *
+ * @param rawTx - The raw transaction hex
+ * @param network - Network name (defaults to configured default)
+ * @returns Transaction hash
+ */
+export async function broadcastTransaction(
+    rawTx: string,
+    network?: NetworkName,
+    isPsbt: boolean = false,
+): Promise<string> {
+    const provider = getProvider(network);
+    const result = await provider.sendRawTransaction(rawTx, isPsbt);
+    return result.result ?? '';
+}