Z-Storage Service

The Z-Storage service is a stateless proxy that manages binary data across multiple providers (AWS, IPFS, Filecoin). It supports both small direct uploads via MCP and large-file streaming via session initialization.

Types

StorageContext

Storage context sets the context for the provider about the upload

export interface StorageContext {
  userID?: string;              // User authorizing the storage
  region?: string;              // Target Network (e.g., "aws-us-east-1", "ipfs-mainnet")
  containerID?: string;         // Specific ipfs networtID or container/bucket ID
  provider: string;             //storage provider
}

BlobMetadata

The metadata of the file/blob

export interface BlobMetadata {
  fileName: string;
  mimeType: string;
  size: number;                // Total size in bytes
  options?: Record<string, any>; // Provider-specific flags (e.g., storageClass)
}

ResourceURI

Syntax: zttp://storage:<provider>/<containerID>/<fileID>

fileID

• would be CID incase of content-addressed providers like IPFS, filecoin
• would be absolutePath in case of location-addressed providers like AWS, Cloudflare R2

upload

Description: Uploads small blobs (typically < 5MB) directly via the MCP control plane.

Input Schema:

• data (string): Base64 encoded file content.

• metadata (object):

  • fileName (string): Name of the file.
  • mimeType (string): Standard MIME type.
  • mode (enum): normal (path-based) or content_addressed (CID-based).

• context (object):

  • appID (string): ID of the requesting application.
  • networkID (string): Target storage network (e.g., ipfs-mainnet, aws-us-east-1).
  • bucketID (string): The specific bucket or container ID.

This method is highly customized for smaller payloads from client such as AI Agents and IOT devices.

Recommended base64 string = 2MB

init_stream

Description: Initiates a handshake for large file uploads. Returns a session ID and a dedicated URL for the HTTP Data Plane.

Input Schema:

• metadata (object): Contains fileName, size, and mode.

• context (object): Contains appID, networkID, and bucketID.

• Response: Returns an UploadSession containing a sessionID and a uploadUrl for binary streaming.

read

Description: Retrieves a file from resource URI

• Input Schema:
• resourceURI (string): The standard URI (e.g., zttp://storage:ipfs-swarm/124/Qm...).
• context (object): Standard storage context for authorization.

init_download

Description: Initiates a handshake for large file downloads. Returns a session ID and a dedicated URL for the HTTP Data Plane.

Input Schema:

• resourceURI (string): The standard URI (e.g., zttp://storage:ipfs-swarm/124/Qm...).

• Response: Returns an DownloadSession containing a sessionID and a downloadUrl for binary streaming.

delete

Description: Deletes the file

Input Schema:

• resourceURI (string): The standard URI (e.g., zttp://storage:ipfs-swarm/124/Qm...).

• mode(string): soft(default) or hard

• Response: Returns an acknowledgement