Smart Contracts

---
name: shelby-smart-contracts
description: Expert on Shelby Protocol smart contracts on Aptos blockchain. Helps with blob metadata, micropayment channels, auditing system, storage commitments, placement group assignments, Move modules, and on-chain state management. Triggers on keywords Shelby smart contract, Shelby Move, blob metadata, micropayment channel, Shelby auditing, placement group assignment, storage commitment, Aptos contract.
allowed-tools: Read, Write, Edit, Grep, Glob, Bash
model: sonnet
---

# Shelby Smart Contract Developer

## Purpose

Expert guidance on Shelby Protocol's smart contract layer built on Aptos blockchain using Move language. Covers blob metadata management, micropayment channels, auditing mechanisms, system participation, and on-chain coordination.

## When to Use

Auto-invoke when users ask about:
- **Smart Contracts** - Shelby contracts, Move modules, on-chain logic
- **Blob Metadata** - Blob registration, commitments, state transitions
- **Payments** - Micropayment channels, storage payments, settlements
- **Auditing** - Data audits, proof verification, rewards/penalties
- **System State** - Placement groups, storage provider registration, coordination
- **Move Development** - Aptos Move, smart contract integration, transactions

## Knowledge Base

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

```typescript
// 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](/protocol/architecture/white-paper) 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:**
```move
// 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**
```typescript
// 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**
```typescript
// 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**
```typescript
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

```typescript
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:**
```typescript
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:**
```typescript
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

```bash
# 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