Shelby Smart Contracts

Smart contract documentation:

.claude/skills/blockchain/aptos/docs_shelby/

Key files:

• protocol_architecture_smart-contracts.md - Smart contract architecture
• protocol_architecture_overview.md - System interactions
• protocol_architecture_token-economics.md - Economic model
• protocol_architecture_white-paper.md - Formal specifications

Smart Contract Overview

Role in System

Single Source of Truth:

• All critical state stored on-chain
• Coordinates Storage Providers, RPCs, and SDKs
• Enforces Byzantine Fault Tolerance
• Manages economic logic and settlements

Key Functions:

1. Blob Metadata Management - Register, track, update blob state
2. Micropayment Channels - Enable efficient off-chain payments
3. System Participation - Manage storage provider enrollment
4. Auditing - Verify data integrity, distribute rewards/penalties

Blob Metadata

Data Structure

Core Fields:

• Blob Name - User-defined identifier (max 1024 chars)
• Owner Account - Aptos address of blob owner
• Cryptographic Commitment - Merkle root of chunk commitments
• Size - Total blob size in bytes
• Placement Group - Assigned group of 16 storage providers
• Expiration - Timestamp when blob expires
• State - Current status (pending, written, expired)
• Payment Info - Storage fees paid, amounts

Write Path (Metadata Creation)

Step 1: SDK Prepares Transaction

User Data → SDK computes erasure coded chunks locally
         → SDK calculates cryptographic commitments for each chunk
         → SDK creates Merkle tree of chunk commitments
         → SDK prepares transaction with merkle root

Step 2: Blob Registration Transaction

Transaction submitted to smart contract includes:

• Blob name and owner account
• Cryptographic blob commitment (merkle root)
• Payment for storage (based on size and expiration)
• Encoding information (chunk count, chunkset details)

Step 3: Smart Contract Execution

Smart contract:

1. Validates transaction - Checks signature, account balance
2. Takes payment - Deducts storage fees in ShelbyUSD
3. Assigns placement group - Randomly selects from available groups
4. Creates metadata entry - Initializes blob record
5. Sets state to "pending" - Awaiting storage provider acknowledgments

Placement Group Assignment:

• Random selection for load balancing
• Determines 16 storage providers for blob
• All chunks of blob go to same placement group

Step 4: Storage Provider Acknowledgments

After RPC distributes chunks:

1. Each storage provider receives chunk
2. Provider validates chunk against commitment
3. Provider creates signed acknowledgment
4. Acknowledgments sent to RPC server
5. RPC aggregates acknowledgments
6. RPC submits aggregated acknowledgments on-chain

Alternative: Storage providers can submit acknowledgments directly if RPC is unresponsive.

Step 5: State Transition to "Written"

When sufficient acknowledgments received:

• Smart contract transitions blob to "written" state
• Blob now considered durably stored
• Blob available for reads
• Write payment held for distribution via audits

Read Path (Metadata Access)

No On-Chain Updates Required:

• SDK and RPC read smart contract state directly
• Or use indexer for derived information
• Enables low latency and high throughput
• Read operations don't modify blockchain state

Information Retrieved:

• Blob existence and state
• Placement group assignment
• Storage provider locations
• Expiration time
• Chunk count and commitments (for validation)

Micropayment Channels

Purpose

Enable efficient payments from RPC servers to storage providers during read operations without on-chain overhead for each payment.

How It Works

Channel Lifecycle:

1. Creation (On-Chain)

RPC Server → Creates micropayment channel transaction
          → Deposits initial amount (e.g., 10000000 ShelbyUSD micro-units)
          → Smart contract locks funds
          → Channel opened for recipient (storage provider)

2. Intermediate Payments (Off-Chain)

Read Request → RPC pays storage provider for chunk retrieval
            → Payment signed by RPC
            → Storage provider validates signature
            → No blockchain transaction needed
            → Provider accumulates signed payments

3. Settlement (On-Chain)

Storage Provider → Submits accumulated payments to smart contract
                → Smart contract validates signatures
                → Transfers funds from locked amount
                → Channel balance updated

4. Closure (On-Chain)

Either Party → Submits closure transaction
            → Smart contract settles final balance
            → Returns unused funds to sender
            → Channel closed

Benefits

Performance:

• Fast read operations (no blockchain latency)
• High throughput (unlimited off-chain payments)
• Low cost (minimal on-chain transactions)

Security:

• Cryptographic signatures guarantee payment
• Smart contract enforces settlements
• Receiver can always claim valid payments
• Sender's funds locked for guarantee

Flexibility:

• Bulk settlements reduce gas costs
• Asynchronous payment processing
• Channel reuse for multiple operations

Implementation Pattern

// Pseudocode - SDK/RPC integration
class MicropaymentChannel {
  async create(recipient: Address, amount: number) {
    // Submit on-chain transaction
    const tx = await contract.createChannel({
      recipient,
      amount,
      sender: this.account.address()
    });
    return new Channel(tx.channelId);
  }

  async signPayment(channelId: string, amount: number) {
    // Create signed payment (off-chain)
    const payment = {
      channelId,
      amount,
      nonce: this.getNonce()
    };
    return this.account.sign(payment);
  }

  async settle(signedPayments: SignedPayment[]) {
    // Submit batch settlement (on-chain)
    await contract.settlePayments({
      payments: signedPayments
    });
  }
}

System Participation

Storage Provider Management

Joining the System:

Transaction to smart contract includes:

• Provider identity (Aptos address)
• Network endpoint information
• Capacity commitment
• Stake/bond (if required)

Smart Contract Actions:

1. Validates provider credentials
2. Assigns provider to placement group slot(s)
3. Updates placement group mappings
4. Broadcasts provider availability

Leaving the System:

1. Provider submits exit transaction
2. Smart contract initiates exit procedure
3. Data migration may be required
4. Provider removed from placement groups
5. Stake/bond returned (if no penalties)

Placement Group Management

On-Chain Structure:

Placement Group {
  id: u64,
  storage_providers: [Address; 16],  // Exactly 16 slots
  active: bool,
  created_at: timestamp
}

Mapping: PlacementGroupId → [StorageProviderAddress; 16]

Dynamic Updates:

• New providers assigned to available slots
• Exiting providers removed from slots
• System maintains minimum provider count
• Load balancing via random blob assignment

Auditing System

Purpose

Ensure data integrity and honest storage provider behavior through cryptographic verification.

Audit Mechanism

Periodic Audits:

1. Challenge Generation

Smart Contract → Selects random blob and chunk
              → Creates cryptographic challenge
              → Broadcasts to assigned storage provider

2. Proof Generation

Storage Provider → Receives challenge
                → Generates succinct proof of possession
                → Proof uses chunk data and commitment
                → Submits proof to smart contract

3. Verification

Smart Contract → Validates proof against blob commitment
              → Checks proof correctness
              → Updates provider reputation

4. Rewards/Penalties

Success → Provider earns portion of storage payment
        → Reputation score increased

Failure → Provider penalized (stake reduction)
        → Reputation score decreased
        → May be removed from system if repeated failures

Payment Distribution

Write Payment Flow:

1. User pays during blob registration

   • Payment deposited into smart contract
   • Held in escrow

2. Storage providers acknowledge writes

   • Only providers with acknowledgments eligible for payment

3. Audit intervals distribute payments

   • Providers passing audits receive pro-rata share
   • Payments released from escrow periodically

4. Failed audits forfeit payments

   • Non-compliant providers don't receive payment
   • Payments redistributed or returned

Audit Formalization

Reference: See whitepaper for:

• Cryptographic commitment schemes
• Proof generation algorithms
• Challenge-response protocols
• Security proofs and analysis

On-Chain State Management

State Categories

1. Blob Registry

• All blob metadata
• Indexed by account + blob name
• Stores commitments, state, expiration

2. Placement Groups

• Group assignments
• Storage provider mappings
• Availability status

3. Provider Registry

• Active storage providers
• Network endpoints
• Reputation scores
• Stake balances

4. Payment Channels

• Channel metadata
• Locked balances
• Settlement history

5. System Parameters

• Pricing (storage cost per byte, per time)
• Audit frequency
• Minimum stake requirements
• Penalty amounts

Read vs Write Operations

Read Operations (Free, Fast):

• Query blob metadata
• Check blob existence
• Get placement group info
• List account blobs (via indexer)

Write Operations (Paid, Slower):

• Register new blob
• Submit acknowledgments
• Create/settle payment channels
• Join/leave as storage provider
• Submit audit proofs

Move Smart Contract Patterns

Resource-Oriented Architecture

Move's Resource Model:

// Conceptual structure (not actual Shelby code)
module shelby::storage {
    struct BlobMetadata has key {
        name: String,
        owner: address,
        commitment: vector<u8>,
        size: u64,
        placement_group: u64,
        expiration: u64,
        state: u8,  // 0=pending, 1=written, 2=expired
    }

    struct PlacementGroup has key {
        id: u64,
        providers: vector<address>,
        active: bool
    }

    public entry fun register_blob(
        account: &signer,
        name: String,
        commitment: vector<u8>,
        size: u64,
        expiration: u64
    ) {
        // Validate inputs
        // Take payment
        // Assign placement group
        // Create metadata resource
        // Emit event
    }
}

Transaction Patterns

1. Blob Registration

// SDK submits transaction
const txn = await aptosClient.generateTransaction(account.address(), {
  function: "shelby::storage::register_blob",
  type_arguments: [],
  arguments: [
    blobName,           // string
    commitment,         // vector<u8>
    blobSize,          // u64
    expirationTime     // u64
  ]
});

const signedTxn = await aptosClient.signTransaction(account, txn);
const result = await aptosClient.submitTransaction(signedTxn);

2. Acknowledgment Submission

// RPC or storage provider submits
const txn = await aptosClient.generateTransaction(provider.address(), {
  function: "shelby::storage::acknowledge_write",
  type_arguments: [],
  arguments: [
    blobOwner,         // address
    blobName,          // string
    chunkIndex,        // u64
    signature          // vector<u8>
  ]
});

3. Micropayment Channel Creation

const txn = await aptosClient.generateTransaction(rpc.address(), {
  function: "shelby::payments::create_channel",
  type_arguments: [],
  arguments: [
    recipient,         // address (storage provider)
    depositAmount      // u64 (ShelbyUSD micro-units)
  ]
});

Integration with SDK

SDK Responsibilities

Before On-Chain Transaction:

1. Compute erasure coded chunks locally
2. Calculate cryptographic commitments
3. Build merkle tree
4. Estimate costs
5. Prepare transaction payload

After On-Chain Transaction:

1. Monitor transaction confirmation
2. Retrieve placement group assignment
3. Distribute chunks to storage providers
4. Manage payment channels for reads

Transaction Sequencing

Upload Flow:

1. SDK: Compute commitments (off-chain)
2. SDK: Submit registration transaction (on-chain)
3. SDK: Wait for confirmation
4. SDK: Query placement group (on-chain read)
5. SDK: Send data to RPC (off-chain)
6. RPC: Distribute chunks (off-chain via private network)
7. Providers: Submit acknowledgments (on-chain)
8. Contract: Transition to "written" state (on-chain)

Best Practices

1. Gas Optimization

Batch Operations:

• Aggregate multiple acknowledgments in single transaction
• Settle payment channels in bulk
• Minimize on-chain updates

Efficient Data Structures:

• Use compact blob commitments
• Store minimal metadata on-chain
• Leverage indexers for queries

2. Error Handling

try {
  const result = await submitBlobRegistration(blob);
  // Wait for confirmation
  await waitForTransaction(result.hash);
} catch (error) {
  if (error.code === 'INSUFFICIENT_FUNDS') {
    // Handle funding issue
  } else if (error.code === 'BLOB_EXISTS') {
    // Handle duplicate blob
  } else {
    // Generic error handling
  }
}

3. State Monitoring

Track Blob State:

async function waitForWritten(account: string, blobName: string) {
  while (true) {
    const metadata = await contract.getBlobMetadata(account, blobName);

    if (metadata.state === BlobState.WRITTEN) {
      return metadata;
    } else if (metadata.state === BlobState.FAILED) {
      throw new Error('Blob write failed');
    }

    await sleep(5000); // Poll every 5 seconds
  }
}

4. Payment Management

Monitor Channel Balance:

async function ensureChannelFunded(channelId: string, requiredAmount: number) {
  const channel = await contract.getChannel(channelId);

  if (channel.balance < requiredAmount) {
    // Top up channel
    await contract.fundChannel(channelId, additionalAmount);
  }
}

Process for Helping Users

1. Identify Question Type

Architecture Questions:

• "How do smart contracts manage blob state?"
• "What happens on-chain during upload?"
• "How do micropayment channels work?"

Integration Questions:

• "How do I submit a blob registration transaction?"
• "How do I query blob metadata?"
• "How do I create a payment channel?"

Debugging Questions:

• "Why is my blob stuck in pending state?"
• "Transaction failed with error X"
• "How do I verify acknowledgments were submitted?"

2. Search Documentation

# Smart contract architecture
Read docs_shelby/protocol_architecture_smart-contracts.md

# Overall system flow
Read docs_shelby/protocol_architecture_overview.md

# Economic model
Read docs_shelby/protocol_architecture_token-economics.md

3. Provide Answer

Structure:

1. Concept - Explain on-chain mechanism
2. Flow - Show transaction sequence
3. Code - Provide integration example
4. Verification - How to confirm success
5. Edge Cases - Common issues and solutions

4. Reference Official Sources

• Smart contract documentation
• Aptos Move documentation
• Whitepaper for formal specifications
• SDK integration guides

Key Concepts to Reference

State Transitions:

Blob States:
  pending → written → expired
           ↓
         failed

Payment Flow:

User → Storage Payment → Smart Contract (escrow)
                       → Audit-based distribution
                       → Storage Providers (rewards)

Audit Cycle:

Challenge → Proof → Verification → Reward/Penalty
  ↓                                      ↓
Smart Contract                   Reputation Update

Response Style

• Architectural - Explain how components interact
• Secure - Emphasize cryptographic guarantees
• Practical - Show real transaction examples
• Referenced - Cite Move patterns and Aptos docs
• Complete - Cover both on-chain and off-chain aspects

Example Interaction

User: "How does Shelby verify storage providers actually stored my data?"

Response:
1. Explain blob commitment during registration
2. Describe acknowledgment mechanism
3. Detail periodic audit system with cryptographic proofs
4. Show proof verification in smart contract
5. Explain reward/penalty distribution
6. Reference: protocol_architecture_smart-contracts.md, whitepaper

Limitations

• Don't show actual Shelby Move contract code (not public)
• Reference conceptual patterns and documented behavior
• For implementation details, defer to official documentation
• Acknowledge when internals are proprietary
• Focus on documented interfaces and behaviors

Follow-up Suggestions

After answering, suggest:

• Related on-chain operations
• SDK integration patterns
• Transaction monitoring strategies
• Gas optimization techniques
• Error handling best practices
• Aptos Move learning resources