Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.lucid.foundation/llms.txt

Use this file to discover all available pages before exploring further.

​
DePIN Providers

Decentralized storage providers play a crucial role in ensuring data availability and anchoring within the Lucid ecosystem. This guide explains how these providers are integrated and utilized.

​
Overview

In Lucid, no feature interacts directly with the IDepinStorage interface. Instead, all decentralized storage uploads are managed through the Anchoring Control Plane. The process flow is as follows: 
Any feature → AnchorDispatcher.dispatch() → IDepinStorage → AnchorRegistry

​
Storage Providers

The IDepinStorage interface supports multiple storage providers, which can be swapped based on the use case:
ProviderEnv ValueTierUse Case
ArweaveStoragearweavePermanentImmutable artifacts (epochs, passports, deploys)
LighthouseStoragelighthouseEvolvingMutable/supersedable (memory snapshots, MMR checkpoints)
MockStoragemockEitherDevelopment/testing (local SHA-256 files)

​
Anchoring Control Plane

The Anchoring Control Plane is responsible for managing the data anchoring process. All producers utilize the getAnchorDispatcher().dispatch() method:
ProducerArtifact TypeStorage Tier
epochArchiverepoch_bundlePermanent
anchoringServiceepoch_proofPermanent
archivePipelinememory_snapshotEvolving
agentDeploymentServicedeploy_artifactPermanent
passportSyncServicepassport_metadataPermanent
passportManagernft_metadataPermanent
mmrCheckpointmmr_checkpointEvolving

​
Key Behaviors

  • Dispatch Method: The dispatch() method returns an AnchorResult or null. If DEPIN_UPLOAD_ENABLED=false, it returns null. All callers must handle null values.
  • Content Hash: Uses SHA-256 of canonicalJson(payload). This is always populated and never null.
  • Deduplication: Enforced by a UNIQUE constraint on (artifact_type, artifact_id, content_hash). If the same payload is uploaded twice, the existing record is returned.
  • Lineage: Uses parent_anchor_id for cross-referencing, such as when a snapshot supersedes a prior snapshot.
  • Registry: Acts as an L3 projection, rebuildable from on-chain data and DePIN.

​
Components

ComponentPurpose
AnchorDispatcherHandles uploads to DePIN and writes registry records
IAnchorRegistryManages CRUD operations for anchor_records (InMemory and Postgres)
AnchorVerifierVerifies CID existence on the provider
FactoryProvides getAnchorDispatcher(), getAnchorRegistry(), and getAnchorVerifier()

​
API Routes

  • GET /v1/anchors?agent_passport_id=X&artifact_type=Y: Query the registry.
  • GET /v1/anchors/:id: Retrieve a single record.
  • GET /v1/anchors/:id/lineage: Walk through the parent chain.
  • GET /v1/anchors/cid/:cid: Perform a reverse CID lookup.
  • POST /v1/anchors/:id/verify: Check if a CID still exists on the provider.

​
Environment Configuration

  • Permanent Provider: Set with DEPIN_PERMANENT_PROVIDER.
  • Evolving Provider: Set with DEPIN_EVOLVING_PROVIDER (default is mock).
  • Upload Enablement: Controlled by DEPIN_UPLOAD_ENABLED=false (acts as a kill switch).
  • Registry Store: Configured with ANCHOR_REGISTRY_STORE=postgres|memory.