Architectural Overview

Core User Concepts

Quick Start Guide

LimeWire Network Concepts

This document explains the core structural concepts and primitives that power the LimeWire Network. Understanding these will make it easier to manage your storage, control permissions, and automate object lifecycles.

Accounts

An Account is the top-level entity for a storage user on the LimeWire Network.

• It is created and uniquely tied to a specific blockchain wallet (owner address).
• Every account is assigned a unique, auto-incrementing accountId.
• Accounts act as the root container for all your resources, including Buckets, API Keys, Groups, and Access Policies.

Dapp Usage: In the LimeWire Network Web3 App, you can connect your wallet and navigate to the Account dashboard to instantly create your storage account, view your account ID, and manage your Web3 identity on the network.

API Keys

Unlike centralized services that issue opaque API keys and secret pairs, the LimeWire Network uses public-key cryptography (ECDSA) for authentication.

• An API Key is essentially an ECDSA public key (address) registered to your Account, along with a human-readable description.
• Your application keeps the corresponding private key securely and uses it to sign S3 compatible API requests locally.
• API Keys can be organized into Groups and have Access Policies attached to them to strictly limit their privileges.

Dapp Usage: From the API Keys section of the LimeWire Network Web3 App, you can generate new API Key pairs directly in your browser. During this process, only the public key is transmitted to the smart contract, ensuring the private key is never sent, stored, or compromised. You can also seamlessly register existing public keys to your active account and logically organize them by grouping them together for easier access management.

Access Policies

Access Policies provide fine-grained Identity and Access Management (IAM) and natively share the exact same syntax as standard S3/AWS IAM policies.

• A Policy contains a list of Statements.
• Each Statement defines:
• An Effect (Allow or Deny).
• A list of Actions (e.g., GetObject, PutObject, DeleteObject, ListBucket, etc.).
• A list of Resources (e.g., specific bucket names and optional key prefixes/paths).
• Optional JSON-based conditions for more complex constraints.
• These policies can be attached directly to individual API Keys or to Groups (affecting all members of the group), allowing you to securely manage permissions across different applications.

Dapp Usage: The Access Policies dashboard in the LimeWire Network Web3 App is used to manage and attach policies. While it cannot be used to visually build policies graphically via drag-and-drop, it lets you seamlessly select from pre-defined templates such as “read-only”, “read-write”, and “full access”. For custom permissions, the interface provides a helpful JSON editor that assists you with writing the correct IAM JSON syntax directly.

Buckets

A Bucket is the fundamental logical container where your objects (files/data) are stored.

• Each bucket is owned by an Account and mapped to a primary Storage Provider (identified by a StorageProviderId).
• Buckets have a Visibility setting (Private or Public (coming later)).
• If a bucket is set to Public, it can leverage a specific publicAccessApiKey. However, it is vital to note that “Public Access” to buckets only works via an S3 Gateway. The core LimeWire Network API inherently lacks a concept of unauthenticated public access because the native API always requires ECDSA signature authentication. The S3 Gateway bridges this gap by mapping unauthenticated public requests to the correct bucket access keys.
• Buckets maintain their status (Active or Deleted) as on-chain state to coordinate replication and storage billing.
• By default, every bucket is initialized with a robust default lifecycle rule that cleans up expired object delete markers and prunes noncurrent versions after 1 day to heavily optimize your storage costs.

Dapp Usage: Using the Buckets tab in the LimeWire Network Web3 App, you can quickly provision new buckets on the blockchain, select their preferred primary Storage Provider, configure Public/Private visibility, and link their public access API keys.

Lifecycle Policies

Lifecycle Policies allow you to automate the management, cleanup, and deletion of objects over time within a bucket.

• A Lifecycle Policy contains up to 1000 Rules.
• Each Rule can target specific subsets of objects inside the bucket via Filters (matching by key prefix, tags, or explicitly by minimum/maximum object sizes).
• Rules define expiration behaviors, such as:
• Expiration in Days: Automatically granting objects a delete marker after a specified number of days.
• Noncurrent Version Expiration: Automatically cleaning up older versions of an object after a certain number of days (noncurrentDays) or retaining only a specific number of the most recent versions (newerNoncurrentVersions).
• Expired Object Delete Marker Cleanup: Automatically removing lingering delete markers that have no remaining noncurrent versions.

Dapp Usage: While managing buckets in the Web3 UI, you can add, edit, or remove Lifecycle Policies directly in the interface. This provides youi with a way to apply filters to key prefixes and configure expiration rules on-chain.

S3 Gateways

An S3 Gateway is a proxy service that allows standard S3-compatible clients (such as the AWS CLI, Boto3, or any application using the S3 API) to interact with buckets stored on the LimeWire Network. It bridges the gap between the traditional S3 authentication model (AWS Signature Version 4 with HMAC credentials) and the LimeWire Network’s native ECDSA-based authentication.

• The gateway accepts incoming S3 requests signed with conventional HMAC credentials (Access Key ID + Secret Access Key), verifies the AWS SigV4 signature, and then re-signs the request using the corresponding LimeWire Network API Key before forwarding it to the appropriate Storage Provider.
• This translation layer is essential because the core LimeWire Network API exclusively uses ECDSA signature authentication — it has no concept of static HMAC credentials. The S3 Gateway maps these familiar S3 credentials to the underlying blockchain-native identity.
• S3 Gateways also enable public bucket access (coming soon). Since the LimeWire Network API always requires ECDSA-signed requests, there is no native way to serve unauthenticated reads. When a bucket is configured as Public with a publicAccessApiKey, the S3 Gateway handles unauthenticated requests by looking up the bucket’s public access API key via TheGraph and using it to transparently authorize the request on the caller’s behalf.
• To use the S3 Gateway, users must first register their API Key’s private key with the gateway and then create HMAC key pairs (Access Key + Secret Access Key) associated with that API Key. These HMAC keys are what standard S3 clients use as their credentials.
• The gateway supports both path-style (https://gateway.example.com/bucket/key) and virtual-hosted-style (https://bucket.gateway.example.com/key) S3 request addressing.
• All S3 payload types are supported, including unsigned payloads (streamed directly), signed payloads (verified and re-signed), and chunked transfer encoding (STREAMING-AWS4-HMAC-SHA256-PAYLOAD), where each chunk is individually re-signed with the new credentials.

Dapp Usage: You can use the LimeWire Network Web3 App to create HMAC key pairs for your API Keys and to register your API Keys with the gateway.