Lens Storage Nodes Basics
This guide will explain the core concepts and components of Lens Storage Nodes.
ACL Template
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 three different ACL templates for Lens Storage Nodes:
Lens Account Template
Wallet Address Template
Generic Template
Lens Account Template
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.
Wallet Address Template
This template type uses an existing wallet for ACL validations.
{ "template": "wallet_address", "wallet_address": "<WALLET_ADDRESS>"}
When you upload this ACL template together with your files, the ACL validators will use the provided address to validate any modification requests.
Generic Template
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.
Action
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.
Challenge
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 storage_key=af5225b6262e03be6bfacf31aa416ea5e00ebb05e802d0573222a92f8d0677f5 expires_at=1728383042721", "signature:": "<sign_here>", "secret_random": 6450360083131791513}
Content Resolution
All content stored on the Lens Storage Nodes can be addressed by a unique storage_key. This approach is used for resolving to both individual files and folders.
Files
Each file is addressed by its unique storage_key:
storage_key -> file
This always resolves to the latest file contents.
Folder Index
It's possible to address a folder by providing an index file called index.json during upload. When resolving the folder's storage_key, 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 storage_key_0:
file_1file_2
The following resolutions take place during retrieval
storage_key_0 -> index.json (folder index if present or 404)storage_key_1 -> file_1storage_key_2 -> file_2
Encoding
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 storage_key. More details follow in the subsections below.
File
A user-provided file with arbitrary contents and Content-Type. Max size of 1GB per file.
Folder
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.
Storage Key
A storage_key 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
Message
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 storage_key=af5225b6262e03be6bfacf31aa416ea5e00ebb05e802d0573222a92f8d0677f5 expires_at=1728383042721
Mutability
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.
Secret Random
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.