Skip to content

SMART_CONTRACTS.md

Latest commit

 

History

History
328 lines (238 loc) · 9.21 KB

SMART_CONTRACTS.md

File metadata and controls

328 lines (238 loc) · 9.21 KB

Smart Contract Setup Guide

This guide explains how to set up and deploy the album access control smart contract for Pixelproof.

Overview

The AlbumAccessControl smart contract manages per-album access control on the Moonbeam blockchain. It allows album owners to grant and revoke access to their albums for specific Substrate addresses.

Note: Moonbeam uses unified accounts where Substrate (SS58) addresses and EVM (H160) addresses map to the same account. The application accepts Substrate addresses from users and automatically converts them to EVM format for blockchain interaction.

Project Structure

pixelproof/
├── contracts/
│   └── AlbumAccessControl.sol      # Main smart contract
├── scripts/
│   ├── deploy.ts                   # Deployment script
│   └── interact.ts                 # Interaction examples
├── test/
│   └── AlbumAccessControl.test.ts  # Contract tests
├── lib/
│   └── albumAccessControl.ts       # TypeScript client for API integration
├── hardhat.config.ts               # Hardhat configuration
└── .env.example                    # Environment variables template

Prerequisites

  1. Node.js (v18 or higher)
  2. A wallet with GLMR tokens (for Moonbeam Mainnet deployment)
  3. Apillon API credentials

Setup Instructions

1. Install Dependencies

npm install

2. Configure Environment Variables

Create a .env file in the root directory:

cp .env.example .env

Edit .env and add your values:

# Apillon API credentials
APILLON_API_KEY=your_apillon_api_key
APILLON_API_SECRET=your_apillon_api_secret

# Private key for deployment and transactions
PRIVATE_KEY=your_private_key_here

# Contract address (will be filled after deployment)
CONTRACT_ADDRESS=0x...

# Optional: Moonbeam API key for verification
MOONBEAM_API_KEY=your_moonscan_api_key

Important Security Notes:

  • Never commit .env files to version control
  • Use a dedicated server-side wallet for PRIVATE_KEY
  • Keep the wallet funded with minimal GLMR (only for gas fees)

3. Compile Contracts

npm run compile

This will:

  • Compile the Solidity contracts
  • Generate TypeScript types in typechain-types/
  • Create artifacts in artifacts/

4. Run Tests

npm run test:contracts

All tests should pass before deployment.

Deployment

Deploy to Moonbeam Mainnet

  1. Ensure your wallet has GLMR tokens for gas
  2. Run the deployment script:
npm run deploy:moonbeam
  1. Save the contract address from the output
  2. Update your .env file with the contract address:
CONTRACT_ADDRESS=0x...

Deploy to Moonbase Alpha (Testnet)

For testing purposes:

npm run deploy:testnet

Get testnet GLMR from the Moonbeam Faucet.

Verify Contract (Optional)

After deployment, verify the contract on Moonscan:

npm run verify <CONTRACT_ADDRESS>

Or manually:

npx hardhat verify --network moonbeam <CONTRACT_ADDRESS>

Contract Functions

Grant Access

// Grant access to a single address
function grantAccess(uint256 albumId, address grantedAddress) external

// Grant access to multiple addresses
function grantAccessBatch(uint256 albumId, address[] calldata grantedAddresses) external

Revoke Access

// Revoke access from a single address
function revokeAccess(uint256 albumId, address revokedAddress) external

// Revoke access from multiple addresses
function revokeAccessBatch(uint256 albumId, address[] calldata revokedAddresses) external

Check Access

// Check if an address has access
function checkAccess(address owner, uint256 albumId, address checkAddress) external view returns (bool)

// Get all addresses with access
function getAlbumAccessList(address owner, uint256 albumId) external view returns (address[])

// Get count of addresses with access
function getAlbumAccessCount(address owner, uint256 albumId) external view returns (uint256)

Integration with Next.js

The contract is integrated into the application through:

  1. API Routes (app/api/albums/access/route.ts):

    • POST /api/albums/access - Grant access
    • DELETE /api/albums/access - Revoke access
    • GET /api/albums/access - Check access

  2. Client Library (lib/albumAccessControl.ts):

    • AlbumAccessControlClient class for contract interaction
    • Helper functions for album ID generation

  3. UI Components (app/home/components/ManageAccessModal.tsx):

    • Modal for managing album access
    • Add/remove Substrate addresses with access
    • Supports both light and dark mode

  4. Address Conversion (lib/addressConversion.ts):

    • Utilities for converting between Substrate SS58 and EVM H160 formats
    • Validates both address types
    • Normalizes addresses for smart contract interaction

How It Works

Album ID Generation

Albums are identified by a numeric ID generated from the album name:

// Example: "Vacation 2024" → 123456789
const albumId = albumNameToId("Vacation 2024");

Access Control Flow

  1. User grants access:

    • Opens "Manage Access" modal in album view
    • Enters Substrate address (SS58 format) to grant access
    • Application validates and converts Substrate address to EVM format
    • Server signs transaction and submits to blockchain
    • Access is recorded on-chain

  2. Checking access:

    • When fetching files, server checks:
      • Is user the bucket owner? → Return all files
      • Does user have access to each album? → Return accessible files
    • User's Substrate address is converted to EVM format for verification
    • Only accessible files are returned

  3. User revokes access:

    • Clicks remove button next to address
    • Address is converted to EVM format
    • Server signs revoke transaction
    • Access is removed on-chain

Address Conversion

Moonbeam implements unified accounts where:

  • Substrate addresses (SS58 format, e.g., 5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY)
  • Map to EVM addresses (H160 format, e.g., 0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb)
  • Both formats access the same account

The application handles conversion automatically:

  1. Users input Substrate addresses (familiar to Polkadot ecosystem users)
  2. Backend converts to EVM format using @polkadot/util-crypto
  3. Smart contract stores and validates using EVM addresses
  4. UI displays EVM addresses for consistency with blockchain records

Testing the Integration

  1. Start the development server:
npm run dev
  1. Log in with a Polkadot/Substrate wallet
  2. Create an album and upload images
  3. Click "Manage Access" on the album
  4. Add another Substrate address (SS58 format)
    • The address will be automatically converted to EVM format
    • Example: 5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY
  5. Log in with the second wallet
  6. Verify you can see the shared album

Note: The modal supports both light and dark modes automatically based on your app theme.

Network Information

Moonbeam Mainnet

Moonbase Alpha (Testnet)

Troubleshooting

Deployment fails

  • Ensure wallet has enough GLMR for gas
  • Check RPC endpoint is accessible
  • Verify private key is correct in .env

Access control not working

  • Verify CONTRACT_ADDRESS is set correctly in .env
  • Check that PRIVATE_KEY is set
  • Ensure server wallet has GLMR for gas
  • Check browser console and server logs for errors

Files not showing for shared users

  • Verify access was granted (check transaction on Moonscan)
  • Ensure album name matches exactly
  • Confirm Substrate address is correct and properly converted
  • Check that files are being filtered correctly in the API

Address validation errors

  • Ensure you're using valid Substrate (SS58) format addresses
  • Example valid formats:
    • Substrate: 5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY
    • EVM (also accepted): 0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb
  • Check that addresses match the Moonbeam network format

Gas Costs

Typical gas costs on Moonbeam:

  • Deploy contract: ~2-3 GLMR
  • Grant access (single): ~0.001-0.002 GLMR
  • Grant access (batch of 10): ~0.005-0.01 GLMR
  • Revoke access: ~0.001-0.002 GLMR
  • Check access (read-only): Free

Security Best Practices

  1. Private Key Management:

    • Use environment variables
    • Never commit to version control
    • Rotate keys periodically
    • Use a dedicated server wallet

  2. Access Control:

    • Only album owners can grant/revoke access
    • Smart contract enforces ownership
    • Server-side validation for additional security

  3. Gas Management:

    • Monitor gas usage
    • Implement rate limiting
    • Keep server wallet funded but not over-funded

Additional Resources