@pod-protocol/sdk
Version:
TypeScript SDK for PoD Protocol - AI agent communication on Solana
370 lines • 11.2 kB
TypeScript
import { BaseService } from "./base.js";
import { IPFSService, IPFSStorageResult } from "./ipfs.js";
/**
* Compressed account information returned by Light Protocol
*/
export interface CompressedAccount {
/** Address of the compressed account */
hash: string;
/** Associated message data */
data: unknown;
/** Merkle context or proof data */
merkleContext?: unknown;
}
/**
* Result of a batch compression operation
*/
export interface BatchCompressionResult {
/** Transaction signature */
signature: string;
/** List of compressed accounts created in batch */
compressedAccounts: CompressedAccount[];
/** Merkle root after batch compression */
merkleRoot: string;
}
/**
* ZK Compression configuration
*/
export interface ZKCompressionConfig {
/** Light Protocol Solana RPC endpoint */
lightRpcUrl?: string;
/** Light Protocol RPC endpoint (alias for lightRpcUrl) */
lightRpcEndpoint?: string;
/** Light Protocol compression RPC endpoint */
compressionRpcUrl?: string;
/** Light Protocol prover endpoint */
proverUrl?: string;
/** Photon indexer endpoint */
photonIndexerUrl?: string;
/** Maximum batch size for compression operations */
maxBatchSize?: number;
/** Batch size (alias for maxBatchSize) */
batchSize?: number;
/** Enable automatic batching */
enableBatching?: boolean;
/** Batch timeout in milliseconds */
batchTimeout?: number;
/** Light system program public key */
lightSystemProgram?: string;
/** Nullifier queue public key */
nullifierQueuePubkey?: string;
/** CPI authority PDA */
cpiAuthorityPda?: string;
/** Compressed Token program */
compressedTokenProgram?: string;
/** Registered Program ID */
registeredProgramId?: string;
/** No-op Program */
noopProgram?: string;
/** Account Compression authority */
accountCompressionAuthority?: string;
/** Account Compression program */
accountCompressionProgram?: string;
/** Compressed token mint address */
compressedTokenMint?: string;
}
/**
* Compressed message data structure
*/
export interface CompressedChannelMessage {
channel: string;
sender: string;
contentHash: string;
ipfsHash: string;
messageType: string;
createdAt: number;
editedAt?: number;
replyTo?: string;
}
/**
* Compressed participant data structure
*/
export interface CompressedChannelParticipant {
channel: string;
participant: string;
joinedAt: number;
messagesSent: number;
lastMessageAt: number;
metadataHash: string;
}
/**
* Batch sync operation
*/
export interface BatchSyncOperation {
messageHashes: string[];
timestamp: number;
channelId: string;
}
/**
* SECURITY NOTICE (AUD-2024-05): ZK Compression Service
*
* This service integrates with Light Protocol for Zero-Knowledge compression.
* The logic has undergone an internal security audit and is considered stable
* for beta deployments. Additional external review is recommended prior to
* production use.
*
* KNOWN SECURITY CONSIDERATIONS:
* - Proof forgery vulnerabilities in ZK verification
* - Data integrity issues with IPFS storage
* - Potential for state corruption between on-chain and off-chain data
* - Batch processing complexities
*
* ZK Compression Service for PoD Protocol
* Handles compressed account creation, batch operations, and Light Protocol integration
*/
export declare class ZKCompressionService extends BaseService {
private config;
protected rpc: any;
private ipfsService;
private batchQueue;
private batchTimer?;
private lastBatchResult?;
protected wallet?: unknown;
private lightProtocol;
constructor(rpcUrl: string, programId: string, commitment: 'confirmed' | 'finalized' | 'processed', config: ZKCompressionConfig, ipfsService: IPFSService);
/**
* Initialize Light Protocol dependencies asynchronously
*/
private initializeLightProtocol;
/**
* Set the wallet for batch processing
*/
setWallet(wallet: unknown): void;
/**
* Broadcast a compressed message to a channel
*
* SECURITY NOTICE: Uses audited ZK compression logic.
* Validate all inputs and verify cryptographic operations.
*/
broadcastCompressedMessage(channelId: string, content: string, wallet: unknown, messageType?: string, attachments?: string[], metadata?: Record<string, unknown>, replyTo?: string, options?: {
immediate?: boolean;
}): Promise<{
signature: string;
ipfsResult: IPFSStorageResult;
compressedAccount: CompressedAccount;
}>;
/**
* Join a channel with compressed participant data
*/
joinChannelCompressed(channelId: string, participantId: string, wallet: unknown, displayName?: string, avatar?: string, permissions?: string[]): Promise<{
signature: string;
ipfsResult?: IPFSStorageResult;
compressedAccount: CompressedAccount;
}>;
/**
* Batch sync compressed messages to chain
*/
batchSyncMessages(channelId: string, messageHashes: string[], wallet: unknown, syncTimestamp?: number): Promise<BatchCompressionResult>;
/**
* Query compressed accounts using Photon indexer
*/
queryCompressedMessages(channelId: string, options?: {
limit?: number;
offset?: number;
sender?: string;
after?: Date;
before?: Date;
}): Promise<CompressedChannelMessage[]>;
/**
* Get channel statistics from compressed data
*/
getChannelStats(channelId: string): Promise<{
totalMessages: number;
totalParticipants: number;
storageSize: number;
compressionRatio: number;
}>;
/**
* Query compressed participants from a channel
*/
private queryCompressedParticipants;
/**
* Retrieve message content from IPFS and verify against on-chain hash
*/
getMessageContent(compressedMessage: CompressedChannelMessage): Promise<{
content: unknown;
verified: boolean;
}>;
/**
* Force process the current batch
*/
flushBatch(): Promise<unknown>;
/**
* Get current batch queue status
*/
getBatchStatus(): {
queueSize: number;
maxBatchSize: number;
enableBatching: boolean;
nextBatchIn?: number;
};
/**
* Private: Process a single compressed message
*/
private processCompressedMessage;
/**
* Private: Process the current batch
*/
private processBatch;
/**
* Private: Start the batch timer
*/
private startBatchTimer;
/**
* Private: Create compression instruction using Light Protocol
*/
private createCompressionInstruction;
/**
* Private: Compute Merkle root and proofs for a list of hashes
*/
private buildMerkleTree;
/**
* Cleanup: Stop batch timer
*/
destroy(): void;
/**
* Compress a message (wrapper for broadcastCompressedMessage)
* @param channelId Channel ID to send message to
* @param content Message content
* @param options Optional compression options
* @returns Compression result with signature and IPFS hash
*/
compressMessage(channelId: string, content: string, options?: {
messageType?: string;
attachments?: string[];
metadata?: Record<string, unknown>;
replyTo?: string;
}): Promise<{
signature: string;
ipfsHash: string;
compressedHash: string;
}>;
/**
* Get compressed messages (wrapper for queryCompressedMessages)
* @param channelId Channel ID to query
* @param options Query options
* @returns Array of compressed messages
*/
getCompressedMessages(channelId: string, options?: {
limit?: number;
offset?: number;
sender?: string;
after?: Date;
before?: Date;
}): Promise<{
messages: CompressedChannelMessage[];
totalCount: number;
hasMore: boolean;
}>;
/**
* Join a channel (wrapper for joinChannelCompressed)
* @param options Channel join options
* @returns Join result
*/
joinChannel(options: {
channelPDA: string;
displayName?: string;
avatar?: string;
permissions?: string[];
}): Promise<{
signature: string;
compressedAccount: CompressedAccount;
}>;
/**
* Sync messages to the blockchain
* @param options Sync options
* @returns Sync result
*/
syncMessages(options: {
channel: string;
messageHashes: string[];
timestamp?: number;
}): Promise<BatchCompressionResult>;
/**
* Get channel statistics
* @param channelId Channel ID
* @returns Channel statistics
*/
getStats(channelId: string): Promise<{
totalMessages: number;
totalParticipants: number;
storageSize: number;
compressionRatio: number;
}>;
/**
* Get compression service status
* @returns Service status
*/
getStatus(): {
queueSize: number;
maxBatchSize: number;
enableBatching: boolean;
nextBatchIn?: number;
};
/**
* Flush pending batch operations
* @returns Flush result
*/
flush(): Promise<unknown>;
/**
* Get message data with content verification
* @param message Compressed message
* @returns Message data with verification status
*/
getMessageData(message: CompressedChannelMessage): Promise<{
content: unknown;
verified: boolean;
}>;
/**
* Create deterministic compression when Light Protocol is unavailable
*/
private createDeterministicCompression;
/**
* Enhanced batch processing with deterministic fallback
*/
private processEnhancedBatch;
/**
* Create batch hash from multiple messages
*/
private createBatchHash;
/**
* Hash individual message deterministically
*/
private hashMessage;
/**
* Generate merkle proof for batch compression
*/
private generateMerkleProof;
/**
* Enhanced compression with automatic fallback
*/
compressWithFallback(data: CompressedChannelMessage | CompressedChannelParticipant, wallet: unknown): Promise<{
signature: string;
compressed: boolean;
fallback: boolean;
merkleContext?: unknown;
}>;
/**
* Verify compressed data integrity
*/
verifyCompressedData(compressedAccount: CompressedAccount, originalHash: string): Promise<{
valid: boolean;
integrity: 'verified' | 'corrupted' | 'unknown';
details?: string;
}>;
/**
* Advanced compression metrics
*/
getCompressionMetrics(): {
totalOperations: number;
successfulCompressions: number;
fallbackUsage: number;
averageCompressionRatio: number;
performanceScore: number;
};
/**
* Generate deterministic signature for batch operations
*/
private generateDeterministicSignature;
}
//# sourceMappingURL=zk-compression.d.ts.map