Lens Storage Nodes Basics

An ACL (Access Control Layer) template is an optional user-specified file that may be passed during the initial upload. Doing so make your files mutable as the template is used to validate access to any given contents stored on the Lens Storage Nodes. It's possible to use a single ACL template for both edit and delete actions or two separate ones for each or none at all. In the latter case, your content will become immutable.

With ACL templates, all actions that edit or delete content on Lens Storage Nodes must be signed with your EVM-based private key.

We've implemented two different ACL templates for Lens Storage Nodes:

This is the simplest solution to start with when you're working with Lens Accounts and you want to allow files to become mutable:

{  "template": "lens_account",  "lens_account": "<LENS_ACCOUNT_ADDRESS>"}

When you upload this ACL template together with your files, the ACL validators will call your Lens Account to validate any modification requests.

Use this if you want to have full control of your ACL validations:

{  "template": "generic_acl",  "generic_acl":    {      "contract_address": "<ANY_CONTRACT>",      "chain_id": <CHAIN_ID>,      "network_type": "evm",      "function_sig": "<FUNCTION_SIG>",      "params": ["<recovered_address>", <ADDITIONAL_PARAMS>]    }}

By specifying the contract_address, function_sig and params fields, every content owner can customize the validations applied during any file modifications. The special string <recovered_address> is reserved and the actual message signer is injected into that variable for the function call that validates ACL.

An Action refers to the modification action. It can be either edit for editing contents or delete for deleting contents. It must match the Message that will be part of the Challenge when modifying content guarded by ACL templates.

A Challenge is data structure that's used to proof that a user is authorized to perform any given modification action. It passes a message which needs to be signed by the content owner and a secret random.

Example:

{  "message": "Access request for action=edit link_hash=af5225b6262e03be6bfacf31aa416ea5e00ebb05e802d0573222a92f8d0677f5 expires_at=1728383042721",  "signature:": "<sign_here>",  "secret_random": 6450360083131791513}

All content stored on the Lens Storage Nodes can be addressed by a unique link_hash. This approach is used for resolving to both individual files and folders.

Each file is addressed by its unique link_hash:

link_hash -> file

This always resolves to the latest file contents.

It's possible to address a folder by providing an index file called index.json during upload. When resolving the folder's link_hash, the contents of the index file will be returned.

By default, there is no folder index and a 404 status code will be returned.

Consider the following files within the folder addressed by link_hash_0:

file_1file_2

The following resolutions take place during retrieval

link_hash_0 -> index.json (folder index if present or 404)link_hash_1 -> file_1link_hash_2 -> file_2

You must use the multipart/form-data encoding for uploading contents which is supported by many browsers and client libraries. For every file you'd like to upload, a new part inside the multipart request must be created and linked with a unique link_hash. More details follow in the subsections below.

A user-provided file with arbitrary contents and Content-Type. Max size of 1GB per file.

A light-weight structure for organizing files and allowing to group them together for doing bulk uploads/deletion. Does not implement full folder semantics or ability to add files or nest folders.

A link_hash is a unique identifier that belongs to you and your content. It will always resolve to the newest content data stored on the Lens Storage Nodes.

Example: af5225b6262e03be6bfacf31aa416ea5e00ebb05e802d0573222a92f8d0677f5

A Message contains a stringified version of a modification intent. The content owner signs the Message and injects it into the Challenge.

Example: Access request for action=edit link_hash=af5225b6262e03be6bfacf31aa416ea5e00ebb05e802d0573222a92f8d0677f5 expires_at=1728383042721

A mutable file can be modified or deleted after it has been uploaded. Immutable files can never be modified or deleted once they have been uploaded. You can control the mutability of a file by providing an ACL template during upload.

A Secret Random is a random number retrieved from the API when a content owner intents to modify any contents. It must be injected along with the signed Message into the Challenge and is used to prevent replay attacks.