Skip to content

INTERACTION_SCRIPT_GUIDE.md

Latest commit

 

History

History
229 lines (172 loc) · 7.43 KB

INTERACTION_SCRIPT_GUIDE.md

File metadata and controls

229 lines (172 loc) · 7.43 KB

PoCo Diamond Interaction Script Guide

This guide explains how to use the InteractPoco.s.sol script to interact with a deployed PoCo Diamond proxy.

Overview

The InteractPoco.s.sol script provides a comprehensive interface for interacting with the PoCo Diamond proxy, demonstrating various functionalities including:

  • Protocol Information: View basic protocol details, statistics, and configuration
  • Diamond Structure: Inspect diamond facets and function selectors
  • Token Operations: Deposit/withdraw RLC tokens to/from escrow
  • Category Management: Create and view categories
  • Admin Functions: Configure protocol parameters (owner only)
  • User Functions: Check balances, allowances, and view categories

Prerequisites

  1. Deployed PoCo Diamond: You need a deployed PoCo Diamond proxy
  2. RLC Token: Optional but recommended for token interaction demos
  3. Environment Variables: Set required environment variables
  4. Private Key: Required for transaction-based interactions

Environment Variables

Create a .env file with the following variables:

# Required
DIAMOND_ADDRESS=0x... # Address of the deployed PoCo Diamond proxy
RPC_URL=http://127.0.0.1:8545 # RPC URL for the network

# Optional
RLC_TOKEN_ADDRESS=0x... # Address of the RLC token contract
USER_ADDRESS=0x... # Address of a user to query (defaults to a sample address)
OWNER_ADDRESS=0x... # Address of the contract owner (defaults to msg.sender)
PRIVATE_KEY=0x... # Private key for broadcasting transactions (optional for read-only)

Usage

1. Basic Interaction (Read-Only)

Run the script without a private key to view protocol information:

# Using make
make interact-poco-read-only

# Using forge directly
forge script script/InteractPoco.s.sol:InteractPoco --rpc-url $RPC_URL --broadcast -vv

This will show:

  • Protocol information (name, symbol, decimals, total supply)
  • Diamond structure (facets and functions)
  • Category information
  • User balances (read-only)

2. Full Interaction (With Transactions)

Set a private key to enable transaction-based interactions:

# Using make
make interact-poco-local

# Using forge directly
forge script script/InteractPoco.s.sol:InteractPoco --rpc-url $RPC_URL --private-key $PRIVATE_KEY --broadcast -vv

This will perform:

  • All read-only operations
  • RLC token deposits/withdrawals (if RLC token is configured)
  • Category creation (if caller is owner)
  • Other admin functions (if caller is owner)

3. Specific Functions

The script also provides individual utility functions that can be called directly:

Deposit RLC Tokens

# Deposit 10 RLC (10 * 10^9 wei)
forge script script/InteractPoco.s.sol:InteractPoco --sig "depositRLC(uint256)" 10000000000 --rpc-url $RPC_URL --private-key $PRIVATE_KEY --broadcast -vv

Withdraw RLC Tokens

# Withdraw 5 RLC (5 * 10^9 wei)
forge script script/InteractPoco.s.sol:InteractPoco --sig "withdrawRLC(uint256)" 5000000000 --rpc-url $RPC_URL --private-key $PRIVATE_KEY --broadcast -vv

Create Category

# Create a new category
forge script script/InteractPoco.s.sol:InteractPoco --sig "createCategory(string,string,uint256)" "AI Computing" "AI and machine learning workloads" 300 --rpc-url $RPC_URL --private-key $PRIVATE_KEY --broadcast -vv

View Protocol Statistics

# View detailed protocol statistics
forge script script/InteractPoco.s.sol:InteractPoco --sig "viewProtocolStats()" --rpc-url $RPC_URL --broadcast -vv

Check User Balance

# Check balance for a specific user
forge script script/InteractPoco.s.sol:InteractPoco --sig "checkUserBalance(address)" 0x1234567890123456789012345678901234567890 --rpc-url $RPC_URL --broadcast -vv

List All Categories

# List all categories with details
forge script script/InteractPoco.s.sol:InteractPoco --sig "listAllCategories()" --rpc-url $RPC_URL --broadcast -vv

Analyze Diamond Structure

# Show complete diamond structure
forge script script/InteractPoco.s.sol:InteractPoco --sig "analyzeDiamondStructure()" --rpc-url $RPC_URL --broadcast -vv

Script Features

Error Handling

The script includes comprehensive error handling:

  • Try-catch blocks for all external calls
  • Graceful failure with informative error messages
  • Continues execution even if some operations fail

Safety Checks

  • Validates required environment variables
  • Checks balances before attempting operations
  • Requires sufficient token balances for demos

Flexible Operation

  • Works with or without private keys
  • Automatically detects owner status
  • Adapts behavior based on available configuration

Example Output

When you run the script, you'll see output like:

=== PoCo Diamond Interaction Script ===
Diamond Address: 0x1234...
RLC Token Address: 0x5678...
User Address: 0x9abc...
Owner Address: 0xdef0...
Has Private Key: true

=== Protocol Information ===
Name: iEx.ec Network Token
Symbol: RLC
Decimals: 9
Total Supply: 87000000000000000
Owner: 0xdef0...
RLC Token Address: 0x5678...
Category Count: 1

=== Diamond Information ===
Number of Facets: 8
Facet 0: 0x1111...
  Function Count: 4
  Selector 0: 0x8da5cb5b
  Selector 1: 0xf2fde38b
  ... and 2 more

=== Token Interactions ===
RLC Token Balance: 100000000000
Approving 10000000000 RLC tokens for deposit...
Approval successful
Depositing 10000000000 RLC tokens...
Deposit successful
New escrow balance: 10000000000

Troubleshooting

Common Issues

  1. "DIAMOND_ADDRESS must be set"

    • Ensure you've set the DIAMOND_ADDRESS environment variable

  2. "Insufficient RLC balance"

    • Check that your account has enough RLC tokens for the demo amounts
    • Modify the demo amounts in the script if needed

  3. "Only owner can call this function"

    • Admin functions are restricted to the contract owner
    • Verify your account is the owner or use a different account

  4. "Failed to retrieve..."

    • Check that the diamond proxy is deployed and accessible
    • Verify the RPC URL is correct and the network is reachable

Debug Tips

  1. Use verbose output: Add -vv or -vvv to see more detailed logs
  2. Check network: Ensure you're connected to the correct network
  3. Verify addresses: Double-check all addresses in your .env file
  4. Test read-only first: Start with read-only operations to verify basic connectivity

Customization

You can customize the script by:

  1. Modifying demo amounts: Change DEMO_DEPOSIT_AMOUNT and DEMO_WITHDRAW_AMOUNT constants
  2. Adding new functions: Extend the script with additional utility functions
  3. Adjusting output: Modify console.log statements to show different information
  4. Error handling: Customize error messages or recovery logic

Security Notes

  • Never commit private keys: Keep your .env file secure and never commit it to version control
  • Use testnets: Test on testnets before using mainnet
  • Verify addresses: Always double-check contract addresses before interacting
  • Check permissions: Ensure you have appropriate permissions for the operations you're trying to perform

Integration with Makefile

The script is integrated with the project's Makefile for easy execution:

  • make interact-poco-local: Full interaction with local deployment
  • make interact-poco-read-only: Read-only interaction without private key
  • make deploy-poco-local: Deploy PoCo Diamond to local network first

This provides a complete workflow for deploying and interacting with the PoCo Diamond proxy.