Uploading Content

This guide will walk you through uploading content to Grove.

Grove supports both single-file uploads and bulk uploads in the form of folders. Currently, the maximum upload size is 8MB, but this is an initial limit and may be revised in the future.

Uploaded content on Grove can be immutable or mutable, depending on the Access Control Layer (ACL) configuration provided during the upload.

A single ACL configuration can be used for both edit and delete actions, or separate configurations can be defined for each action individually.

Grove supports four types of ACL configurations.

import { chains } from "@lens-chain/sdk/viem";import { immutable } from "@lens-chain/storage-client";
const acl = immutable(chains.testnet.id);

<form id="upload-form">  <label for="files">Select a file:</label>  <input type="file" name="image" accept="image/*" />  <button type="submit">Upload</button></form>

async function onSubmit(event: SubmitEvent) {  event.preventDefault();
  const input = event.currentTarget.elements["image"];  const file = input.files[0];
  const response = await storageClient.uploadFile(file, { acl });
  // response.uri: 'lens://323c0e1ccebcfa70dc130772…'}

That's it—your file is now available for download.

This section covers alternative upload methods designed to improve flexibility and ease of use.

If you need to upload a JSON file, you can use the uploadAsJson method to simplify the process.

import { chains } from "@lens-chain/sdk/viem";
const data = { key: "value" };const acl = immutable(chains.testnet.id);
const response = await storageClient.uploadAsJson(data, { acl });

If you need to upload an immutable file, you can do so directly via the API without first requesting a storage key. This approach simplifies the process by allowing you to send the file in a single request.

For example, if you want to upload a file named watch_this.mp4, you can do it directly in one step.

curl -s -X POST "https://api.grove.storage/?chain_id=37111" \  --data-binary @watch_this.mp4 \  -H 'Content-Type: video/mp4'

What happens here:

Like with the full upload process, the server may respond with one of the following status codes:

{  "storage_key": "323c0e1ccebcfa70dc130772…",  "gateway_url": "https://api.grove.storage/323c0e1ccebcfa70dc130772…",  "uri": "lens://323c0e1ccebcfa70dc130772…",  "status_url": "https://api.grove.storage/status/323c0e1ccebcfa70dc130772…"}

Where the response includes the same fields as in the full upload process.

import { chains } from "@lens-chain/sdk/viem";import { immutable } from "@lens-chain/storage-client";
const acl = immutable(chains.testnet.id);

const content = {  name: "My Folder",  description: "This is a folder",};
const index = new File([JSON.stringify(content)], "index.json", {  type: "text/plain",});

import type { CreateIndexContent, Resource } from "@lens-chain/storage-client";
const index: CreateIndexContent = (resources: Resource[]) => {  return {    name: "My Folder",    files: resources.map((resource) => ({      uri: resource.uri,      gatewayUrl: resource.gatewayUrl,      storageKey: resource.storageKey,    })),  };};

<form id="upload-form">  <label for="files">Select multiple files:</label>  <input type="file" name="images" accept="image/*" multiple />  <button type="submit">Upload</button></form>

async function onSubmit(event: SubmitEvent) {  event.preventDefault();
  const input = event.currentTarget.elements["images"];
  const response = await storageClient.uploadFolder(input.files, {    acl,    index,  });
  // response.folder.uri: 'lens://af5225b6262…'  // response.files[0].uri: 'lens://47ec69ef75122…'}

That's it—your folder and its content are now available for download.

As described earlier, edit and delete actions can share the same ACL, but they can also be configured separately. This allows for more granular control, enabling different permissions for modifying and removing content.

When integrating directly with the API, you can define two separate ACL files—acl-edit.json and acl-delete.json—each specifying the desired configurations. These ACLs are then included as separate entries in the multipart request.

curl -X POST 'https://api.grove.storage/323c0e1ccebcfa70dc130772…' \     -F '323c0e1ccebcfa70dc130772…=/path/to/watch_this.mp4;type=video/mp4' \     -F 'lens-acl-edit.json=/path/to/acl-edit.json;type=application/json' \     -F 'lens-acl-delete.json=/path/to/acl-delete.json;type=application/json'

What happens here:

Whenever you upload a file or a folder, you can check the status of the resource to see if it has been fully propagated to the underlying storage infrastructure.

const response = await storageClient.uploadFile(file, { acl });
await response.waitForPropagation();