Token-Gated Files on Solana

In this tutorial, you'll build a complete token-gated file marketplace where:

Sellers upload encrypted files to Shelby storage and register them on Solana with a price
Buyers pay in SOL to purchase access, then decrypt and download the files

The encryption uses threshold cryptography—the decryption key is only released when a buyer proves they have purchased access via a signed Solana transaction.

What You'll Build

By the end of this tutorial, you'll have a fully functional dApp with:

Two Solana programs (Anchor) for access control
A Next.js frontend with wallet integration
End-to-end encrypted file storage
SOL-based payments for file access

Architecture

The system uses a "double encryption" approach for security:

Seller Flow

┌─────────────────────────────────────────────────────────────────┐
│  1. Generate random cipher key (redKey)                         │
│  2. Encrypt file with redKey → redBox                          │
│  3. Upload redBox to Shelby storage                             │
│  4. Encrypt redKey with threshold IBE → greenBox               │
│  5. Register blob on Solana (greenBox + price)                 │
└─────────────────────────────────────────────────────────────────┘

Buyer Flow

┌─────────────────────────────────────────────────────────────────┐
│  1. Call purchase() on access_control → creates receipt PDA    │
│  2. Sign assert_access() tx as proof-of-permission             │
│  3. Send signed tx to threshold workers → receive key shares   │
│  4. Combine shares → decrypt greenBox → redKey                 │
│  5. Fetch redBox from Shelby                                   │
│  6. Decrypt redBox with redKey → original file                 │
└─────────────────────────────────────────────────────────────────┘

Technology Stack

Tool	Purpose	Documentation
`create-solana-dapp`	Project scaffolding with Next.js + Anchor	Solana Docs
Anchor	Solana smart contract framework	anchor-lang.com
ACE SDK	Decentralized key management	@aptos-labs/ace-sdk
Shelby	Decentralized file storage	docs.shelby.xyz

Why Anchor? We use the Anchor framework because threshold IBE workers assume a specific transaction format in practice, and currently only support the Anchor format for verifying proof-of-permission transactions.

Prerequisites

Before starting, ensure you have:

Node.js 18+ - Download
Rust toolchain - Install via rustup
Solana CLI - Installation guide
Anchor CLI - Installation guide
A Solana wallet - Phantom or similar

Verify your installation:

node --version      # v18.0.0 or higher
rustc --version     # 1.70.0 or higher
solana --version    # 1.18.0 or higher
anchor --version    # 0.31.0 or higher

Dependencies Overview

Throughout this tutorial, we'll install these packages:

npm install @shelby-protocol/sdk @shelby-protocol/solana-kit @shelby-protocol/react @aptos-labs/ace-sdk

Package	Purpose
`@shelby-protocol/sdk`	Core SDK for interacting with Shelby decentralized storage
`@shelby-protocol/solana-kit`	Solana-specific integration that derives Shelby storage accounts from Solana wallet addresses
`@shelby-protocol/react`	React hooks for Shelby operations like `useUploadBlobs` and `useAccountBlobs`
`@aptos-labs/ace-sdk`	ACE (Access Control Encryption) SDK for encrypting/decrypting keys with distributed key management

Environment Configuration

Environment variables connect your app to the Shelby storage network and configure the Solana programs.

Why a Shelby API Key?

API keys authenticate your app and manage rate limits when using Shelby services. Without one, your client runs in "anonymous" mode with much lower limits, which can affect performance.

How to Get a Shelby API Key

Navigate to Geomi

Visit geomi.dev in your web browser.

Account Setup

Create API Resource

On the overview page, click the "API Resource" card to begin creating a new resource.

Configure Resource

Complete the configuration form with the following settings:

Network: Select Shelbynet from the available network options.
Resource Name: Provide a descriptive name for your API resource.
Usage Description: Briefly describe your intended use case.

Generate Keys

Once submitted, your API keys will be generated and displayed. Copy this key - you'll configure it in the next step.

Note: By default the site generates a key for use in a private server context. If you intend to use the key in a frontend context, create a client key.

Next Steps

Ready to start building? Let's set up your development environment

Introduction