Walrus SDK Documentation

The Walrus SDK is a TypeScript library that provides an interface to interact with the Walrus storage system. It allows users to store and retrieve data using the Walrus Publisher and Aggregator.

Installation

To install the Walrus SDK, use npm:

npm install @galliun/walrus-sdk

Usage

First, import the WalrusSDK class:

import WalrusSDK from 'walrus-sdk';

Then, create an instance of the SDK:

const walrus = new WalrusSDK({
  aggregatorUrl: 'https://your-aggregator-url.com',
  publisherUrl: 'https://your-publisher-url.com'
});

If you don't provide URLs, the SDK will use default testnet URLs.

API Reference

Constructor

constructor(config: WalrusConfig = {})

Creates a new instance of the WalrusSDK.

• config: An optional configuration object with the following properties:
  • aggregatorUrl: The URL of the Walrus aggregator (default: 'https://aggregator.walrus-testnet.walrus.space')
  • publisherUrl: The URL of the Walrus publisher (default: 'https://publisher.walrus-testnet.walrus.space')

Methods

store

async store(data: string | ArrayBuffer, options: StoreOptions = {}): Promise<StoreResponse>

Stores data in the Walrus network.

• data: The data to store (string or ArrayBuffer)
• options: An optional object with the following properties:
  • epochs: Number of epochs to store the data
  • force: Force storage even if the data already exists
  • deletable: Whether the data can be deleted

Returns a Promise that resolves to a StoreResponse object, which can be either a NewlyCreatedResponse or an AlreadyCertifiedResponse.

read

async read(blobId: string): Promise<string>

Reads data from the Walrus network and returns it as a string.

• blobId: The ID of the blob to read

Returns a Promise that resolves to the data as a string.

readAsBuffer

async readAsBuffer(blobId: string): Promise<ArrayBuffer>

Reads data from the Walrus network and returns it as an ArrayBuffer.

• blobId: The ID of the blob to read

Returns a Promise that resolves to the data as an ArrayBuffer.

readAsStream

async readAsStream(blobId: string): Promise<ReadableStream>

Reads data from the Walrus network and returns it as a ReadableStream.

• blobId: The ID of the blob to read

Returns a Promise that resolves to a ReadableStream of the data.

Error Handling

The SDK throws errors in the following cases:

1. If the Publisher URL is not set when calling store.
2. If the Aggregator URL is not set when calling read, readAsBuffer, or readAsStream.
3. If there's an HTTP error during any API call.
4. If the response body is null when calling readAsStream.

Make sure to wrap your SDK calls in try-catch blocks to handle these errors appropriately.

Examples

Here's an example of how to use the Walrus SDK to store and retrieve data:

import WalrusSDK from 'walrus-sdk';

const walrus = new WalrusSDK();

async function storeAndRetrieveData() {
  try {
    // Store data
    const storeResponse = await walrus.store('Hello, Walrus!', { epochs: 5 });
    
    if ('newlyCreated' in storeResponse) {
      const blobId = storeResponse.newlyCreated.blobObject.blobId;
      console.log(`Data stored with Blob ID: ${blobId}`);
      
      // Retrieve data
      const retrievedData = await walrus.read(blobId);
      console.log(`Retrieved data: ${retrievedData}`);
    } else {
      console.log('Data was already certified:', storeResponse.alreadyCertified);
    }
  } catch (error) {
    console.error('An error occurred:', error);
  }
}

storeAndRetrieveData();