Walrus SDK

https://sdk.mystenlabs.com/walrus
Admin
The Walrus SDK allows developers to publish and read blobs directly from Walrus storage nodes,...
Tokens:5,010
Snippets:52
Trust Score:9.8
Update:2 months ago
Show doc for...
Tokens:
Raw
### Install Walrus SDK

Source: https://sdk.mystenlabs.com/walrus

Install the required Walrus and Sui packages via npm.

```bash
npm install --save @mysten/walrus @mysten/sui
```

--------------------------------

### Initialize Walrus Client

Source: https://sdk.mystenlabs.com/walrus

Create a Sui client and extend it with the Walrus SDK functionality.

```ts
import { SuiGrpcClient } from '@mysten/sui/grpc';
import { walrus } from '@mysten/walrus';

const client = new SuiGrpcClient({
	network: 'testnet',
	baseUrl: 'https://fullnode.testnet.sui.io:443',
}).$extend(walrus());
```

--------------------------------

### Execute manual blob upload steps

Source: https://sdk.mystenlabs.com/walrus

Use executeRegister and executeCertify methods for granular control over the signing and certification process.

```ts
const flow = client.walrus.writeBlobFlow({ blob });
const enc = await flow.encode();
const reg = await flow.executeRegister({ signer, epochs: 3, deletable: true, owner: address });
const up = await flow.upload({ digest: reg.txDigest });
const cert = await flow.executeCertify({ signer });
```

--------------------------------

### Execute full blob upload pipeline

Source: https://sdk.mystenlabs.com/walrus

Use the run() method to execute the entire upload pipeline as an async iterator.

```ts
const flow = client.walrus.writeBlobFlow({ blob });

for await (const step of flow.run({ signer, epochs: 3, deletable: true })) {
	await db.save(fileId, step); // persist for crash recovery
}
```

--------------------------------

### Read files with WalrusFile

Source: https://sdk.mystenlabs.com/walrus

Use getFiles to retrieve files by blob or quilt ID. Batching requests improves efficiency when loading multiple files from the same quilt.

```ts
const [file1, file2] = await client.walrus.getFiles({ ids: [anyBlobId, orQuiltId] });
```

--------------------------------

### Configure Walrus Client with Custom IDs

Source: https://sdk.mystenlabs.com/walrus

Manually specify package and object IDs to connect to specific network deployments.

```ts
import { SuiGrpcClient } from '@mysten/sui/grpc';
import { walrus } from '@mysten/walrus';

const client = new SuiGrpcClient({
	network: 'testnet',
	baseUrl: 'https://fullnode.testnet.sui.io:443',
}).$extend(
	walrus({
		packageConfig: {
			systemObjectId: '0x98ebc47370603fe81d9e15491b2f1443d619d1dab720d586e429ed233e1255c1',
			stakingPoolId: '0x20266a17b4f1a216727f3eef5772f8d486a9e3b5e319af80a5b75809c035561d',
		},
	}),
);
```

--------------------------------

### Constructing WalrusFile objects

Source: https://sdk.mystenlabs.com/walrus

Create WalrusFile instances from Uint8Array, Blob, or string data types.

```ts
const file1 = WalrusFile.from({
	contents: new Uint8Array([1, 2, 3]),
	identifier: 'file1.bin',
});
const file2 = WalrusFile.from({
	contents: new Blob([new Uint8Array([1, 2, 3])]),
	identifier: 'file2.bin',
});
const file3 = WalrusFile.from({
	contents: new TextEncoder().encode('Hello from the TS SDK!!!\n'),
	identifier: 'README.md',
	tags: {
		'content-type': 'text/plain',
	},
});
```

--------------------------------

### Configure linear upload relay tip

Source: https://sdk.mystenlabs.com/walrus

Set a tip that combines a base amount with a multiplier based on the blob size using the linear tip kind.

```ts
const client = new SuiGrpcClient({
	network: 'testnet',
	baseUrl: 'https://fullnode.testnet.sui.io:443',
}).$extend(
	walrus({
		uploadRelay: {
			host: 'https://upload-relay.testnet.walrus.space',
			sendTip: {
				address: '0x123...',
				kind: {
					linear: {
						base: 105,
						perEncodedKib: 10,
					},
				},
			},
		},
	}),
);
```

--------------------------------

### Configure Next.js server external packages

Source: https://sdk.mystenlabs.com/walrus

Add Walrus packages to serverExternalPackages in next.config.ts to prevent bundling issues with WASM.

```ts
// next.config.ts
const nextConfig: NextConfig = {
	serverExternalPackages: ['@mysten/walrus', '@mysten/walrus-wasm'],
};
```

--------------------------------

### Writing files to Walrus

Source: https://sdk.mystenlabs.com/walrus

Use the writeFiles method to commit files to Walrus, requiring a Signer instance for transaction and storage fees.

```ts
const results: {
	id: string;
	blobId: string;
	blobObject: Blob.$inferType;
}[] = await client.walrus.writeFiles({
	files: [file1, file2, file3],
	epochs: 3,
	deletable: true,
	signer: keypair,
});
```

--------------------------------

### Resume interrupted blob upload

Source: https://sdk.mystenlabs.com/walrus

Pass a previously saved WriteBlobStep to the resume option to skip completed steps and recover from crashes.

```ts
const saved = await db.load(fileId);
const flow = client.walrus.writeBlobFlow({ blob, resume: saved });

for await (const step of flow.run({ signer, epochs: 3, deletable: true })) {
	await db.save(fileId, step);
}
```

--------------------------------

### Load WASM module in Vite

Source: https://sdk.mystenlabs.com/walrus

Import the WASM file with a ?url suffix and pass the URL to the Walrus client configuration.

```ts
import walrusWasmUrl from '@mysten/walrus-wasm/web/walrus_wasm_bg.wasm?url';

const client = new SuiGrpcClient({
	network: 'testnet',
	baseUrl: 'https://fullnode.testnet.sui.io:443',
}).$extend(
	walrus({
		wasmUrl: walrusWasmUrl,
	}),
);
```

--------------------------------

### Configure constant upload relay tip

Source: https://sdk.mystenlabs.com/walrus

Set a fixed tip amount for each blob written to the relay using the const tip kind.

```ts
const client = new SuiGrpcClient({
	network: 'testnet',
	baseUrl: 'https://fullnode.testnet.sui.io:443',
}).$extend(
	walrus({
		uploadRelay: {
			host: 'https://upload-relay.testnet.walrus.space',
			sendTip: {
				address: '0x123...',
				kind: {
					const: 105,
				},
			},
		},
	}),
);
```

--------------------------------

### Load WASM module from a CDN

Source: https://sdk.mystenlabs.com/walrus

Use a direct URL to a CDN-hosted WASM file if local bundling is not possible.

```ts
const client = new SuiGrpcClient({
	network: 'testnet',
	baseUrl: 'https://fullnode.testnet.sui.io:443',
}).$extend(
	walrus({
		wasmUrl: 'https://unpkg.com/@mysten/walrus-wasm@latest/web/walrus_wasm_bg.wasm',
	}),
);
```

--------------------------------

### Customize network requests with a custom fetch method

Source: https://sdk.mystenlabs.com/walrus

Provide a custom fetch implementation to the storageNodeClientOptions to control timeouts and request behavior.

```ts
import type { RequestInfo, RequestInit } from 'undici';
import { Agent, fetch } from 'undici';

const client = new SuiGrpcClient({
	network: 'testnet',
	baseUrl: 'https://fullnode.testnet.sui.io:443',
}).$extend(
	walrus({
		storageNodeClientOptions: {
			timeout: 60_000,
			fetch: (url, init) => {
				// Some casting may be required because undici types may not exactly match the @node/types types
				return fetch(url as RequestInfo, {
					...(init as RequestInit),
					dispatcher: new Agent({
						connectTimeout: 60_000,
					}),
				}) as unknown as Promise<Response>;
			},
		},
	}),
);
```

--------------------------------

### client.walrus.getFiles

Source: https://sdk.mystenlabs.com/walrus

Retrieves files from Walrus using blob IDs or quilt IDs, returning a WalrusFile object.

```APIDOC
## client.walrus.getFiles

### Description
Retrieves files from Walrus using a list of blob or quilt IDs. Returns a collection of WalrusFile objects.

### Parameters
- **ids** (Array<string>) - Required - A list of blob IDs or quilt IDs to retrieve.

### Usage Example
```ts
const [file1, file2] = await client.walrus.getFiles({ ids: [anyBlobId, orQuiltId] });
```
```

--------------------------------

### WalrusFile Methods

Source: https://sdk.mystenlabs.com/walrus

Methods available on a WalrusFile object to access data and metadata.

```APIDOC
## WalrusFile Methods

### Description
WalrusFile objects provide methods to read content and retrieve metadata associated with the file.

### Methods
- **bytes()** - Returns the file contents as a Uint8Array.
- **text()** - Returns the file contents as a utf-8 string.
- **json()** - Parses the file contents as JSON.
- **getIdentifier()** - Returns the file identifier if stored in a quilt.
- **getTags()** - Returns the tags associated with the file if stored in a quilt.
```

--------------------------------

### Handling browser-based file uploads

Source: https://sdk.mystenlabs.com/walrus

Break the write flow into separate steps to accommodate browser wallet popup requirements.

```tsx
// Step 1: Create and encode the flow (can be done immediately when file is selected)
const flow = client.walrus.writeFilesFlow({
	files: [
		WalrusFile.from({
			contents: new Uint8Array(fileData),
			identifier: 'my-file.txt',
		}),
	],
});

await flow.encode();

// Step 2: Register the blob (triggered by user clicking a register button after the encode step)
async function handleRegister() {
	const registerTx = flow.register({
		epochs: 3,
		owner: currentAccount.address,
		deletable: true,
	});
	const result = await signAndExecuteTransaction({ transaction: registerTx });

	// Check transaction status
	if (result.$kind === 'FailedTransaction') {
		throw new Error(`Registration failed: ${result.FailedTransaction.status.error?.message}`);
	}

	// Step 3: Upload the data to storage nodes
	// This can be done immediately after the register step, or as a separate step the user initiates
	await flow.upload({ digest: result.Transaction.digest });
}

// Step 4: Certify the blob (triggered by user clicking a certify button after the blob is uploaded)
async function handleCertify() {
	const certifyTx = flow.certify();

	const result = await signAndExecuteTransaction({ transaction: certifyTx });

	// Check transaction status
	if (result.$kind === 'FailedTransaction') {
		throw new Error(`Certification failed: ${result.FailedTransaction.status.error?.message}`);
	}

	// Step 5: Get the new files
	const files = await flow.listFiles();
	console.log('Uploaded files', files);
}
```

--------------------------------

### writeBlob

Source: https://sdk.mystenlabs.com/walrus

Writes a blob to Walrus with specified storage parameters.

```APIDOC
## writeBlob(options)

### Description
Writes a Uint8Array blob to Walrus. Supports configuration for storage duration, deletability, and crash-recoverable uploads.

### Parameters
- **blob** (Uint8Array) - Required - The data to write.
- **deletable** (boolean) - Required - Whether the blob can be deleted.
- **epochs** (number) - Required - The number of epochs to store the blob.
- **signer** (Keypair) - Required - The signer for the transaction.
- **onStep** (function) - Optional - Callback for tracking upload progress.
- **resume** (any) - Optional - State to resume a previously interrupted upload.

### Example
```ts
const { blobId } = await client.walrus.writeBlob({
	blob: file,
	deletable: false,
	epochs: 3,
	signer: keypair,
});
```
```

--------------------------------

### Customize Fetch Behavior

Source: https://sdk.mystenlabs.com/walrus

Implement custom fetch logic, such as logging, timeouts, or retry mechanisms, for storage node requests.

```ts
import { SuiGrpcClient } from '@mysten/sui/grpc';
import { walrus } from '@mysten/walrus';

const client = new SuiGrpcClient({
	network: 'testnet',
	baseUrl: 'https://fullnode.testnet.sui.io:443',
}).$extend(
	walrus({
		storageNodeClientOptions: {
			fetch: (url, options) => {
				console.log('fetching', url);
				return fetch(url, options);
			},
			timeout: 60_000,
		},
	}),
);
```

--------------------------------

### Configure upload relay

Source: https://sdk.mystenlabs.com/walrus

Add the uploadRelay option to the Walrus extension to offload write operations to a server.

```ts
const client = new SuiGrpcClient({
	network: 'testnet',
	baseUrl: 'https://fullnode.testnet.sui.io:443',
}).$extend(
	walrus({
		uploadRelay: {
			host: 'https://upload-relay.testnet.walrus.space',
			sendTip: {
				max: 1_000,
			},
		},
	}),
);
```

--------------------------------

### readBlob

Source: https://sdk.mystenlabs.com/walrus

Reads a blob from Walrus given its blobId.

```APIDOC
## readBlob(options)

### Description
Reads a blob from the Walrus network and returns its content as a Uint8Array.

### Parameters
- **blobId** (string) - Required - The unique identifier of the blob to read.

### Example
```ts
const blob = await client.walrus.readBlob({ blobId });
```
```

--------------------------------

### Configure network error logging

Source: https://sdk.mystenlabs.com/walrus

Passes an onError callback to storageNodeClientOptions to capture individual request failures.

```ts
const client = new SuiGrpcClient({
	network: 'testnet',
	baseUrl: 'https://fullnode.testnet.sui.io:443',
}).$extend(
	walrus({
		storageNodeClientOptions: {
			onError: (error) => console.log(error),
		},
	}),
);
```

--------------------------------

### WalrusBlob.files

Source: https://sdk.mystenlabs.com/walrus

Retrieves files from a WalrusBlob, supporting filtering by identifiers, tags, or specific quilt IDs.

```APIDOC
## WalrusBlob.files

### Description
Reads files contained within a WalrusBlob. If the blob is a quilt, it supports filtering options.

### Parameters
- **identifiers** (Array<string>) - Optional - Filter files by identifier.
- **tags** (Array<Record<string, string>>) - Optional - Filter files by tags.
- **ids** (Array<string>) - Optional - Filter files by specific quilt IDs.

### Usage Example
```ts
const files = await blob.files({ identifiers: ['README.md'] });
```
```

--------------------------------

### Write a blob to Walrus

Source: https://sdk.mystenlabs.com/walrus

Uploads a Uint8Array to Walrus with specified storage duration and deletability settings.

```ts
const file = new TextEncoder().encode('Hello from the TS SDK!!!\n');

const { blobId } = await client.walrus.writeBlob({
	blob: file,
	deletable: false,
	epochs: 3,
	signer: keypair,
});
```

```ts
const { blobId } = await client.walrus.writeBlob({
	blob: file,
	deletable: true,
	epochs: 3,
	signer: keypair,
	onStep: (step) => db.save(fileId, step),
	resume: await db.load(fileId), // pass a previously saved step to resume
});
```

--------------------------------

### Parse WalrusFile content

Source: https://sdk.mystenlabs.com/walrus

WalrusFile objects behave like fetch Response objects, supporting methods to retrieve data as bytes, text, or JSON.

```ts
// get contents as a Uint8Array
const bytes = await file1.bytes();
// Parse the contents as a `utf-8` string
const text = await file1.text();
// Parse the contents as JSON
const json = await file2.json();
```

--------------------------------

### Read files from a WalrusBlob

Source: https://sdk.mystenlabs.com/walrus

Access files within a blob, optionally filtering by identifiers, tags, or specific quilt IDs.

```ts
// Get all files:
const files = await blob.files();
// Get files by identifier
const [readme] = await blob.files({ identifiers: ['README.md'] });
// Get files by tag
const textFiles = await blob.files({ tags: [{ 'content-type': 'text/plain' }] });
// Get files by quilt id
const filesById = await blob.files({ ids: [quiltID] });
```

--------------------------------

### Access WalrusFile metadata

Source: https://sdk.mystenlabs.com/walrus

Retrieve identifiers and tags for files stored within a quilt.

```ts
const identifier: string | null = await file1.getIdentifier();
const tags: Record<string, string> = await file1.getTags();
```

--------------------------------

### client.walrus.getBlob

Source: https://sdk.mystenlabs.com/walrus

Retrieves a WalrusBlob object by its blob ID.

```APIDOC
## client.walrus.getBlob

### Description
Retrieves a WalrusBlob object using a specific blob ID.

### Parameters
- **blobId** (string) - Required - The ID of the blob to retrieve.

### Usage Example
```ts
const blob = await client.walrus.getBlob({ blobId });
```
```

--------------------------------

### Handle retryable client errors

Source: https://sdk.mystenlabs.com/walrus

Resets the client when a RetryableWalrusClientError occurs to handle potential epoch change issues.

```ts
import { RetryableWalrusClientError } from '@mysten/walrus';

if (error instanceof RetryableWalrusClientError) {
	client.walrus.reset();

	/* retry your operation */
}
```

--------------------------------

### Read a blob by ID

Source: https://sdk.mystenlabs.com/walrus

Retrieves blob content as a Uint8Array using the blobId.

```ts
const blob = await client.walrus.readBlob({ blobId });
```

--------------------------------

### Retrieve a WalrusBlob

Source: https://sdk.mystenlabs.com/walrus

Fetch a WalrusBlob directly using its blob ID.

```ts
const blob = await client.walrus.getBlob({ blobId });
```
Tokens:
Raw