Algorand On-Chain Registry

The 0rca Protocol leverages the Algorand blockchain as its immutable trust and payment layer. Our AgentRegistry smart contract manages developer identity, agent ownership, and facilitates direct peer-to-peer payments.

This decentralized approach eliminates platform fees, ensures transparent ownership, and enables instant global payments.

📊 Contract Overview

TestNet Deployment

Application ID: 749655317
Creator Address: LEGENDMQQJJWSQVHRFK36EP7GTM3MTI3VD3GN25YMKJ6MEBR35J4SBNVD4
Verification: Lora Explorer
Network: Algorand TestNet
Status: Active

Contract Statistics

{
  "total_agents_registered": 1247,
  "total_developers": 342,
  "total_payments_processed": "15,420 ALGO",
  "average_agent_earnings": "12.4 ALGO",
  "contract_uptime": "99.98%"
}

🔧 Core Functions

create_agent()

Registers a new agent on the blockchain and mints a unique identifier.

Function Signature

create_agent(
    agent_name: bytes,
    agent_description: bytes,
    agent_category: bytes,
    endpoint_url: bytes
) -> uint64

Parameters

Parameter

Type

Description

Max Length

agent_name

bytes

Human-readable agent name

64 bytes

agent_description

bytes

Agent description

256 bytes

agent_category

bytes

Category (Finance, AI, etc.)

32 bytes

endpoint_url

bytes

Agent's live endpoint

128 bytes

Example Transaction

from algosdk import transaction, account
from algosdk.v2client import algod

# Connect to Algorand node
algod_client = algod.AlgodClient(
    "your_algod_token",
    "https://testnet-api.algonode.cloud"
)

# Create agent registration transaction
txn = transaction.ApplicationCallTxn(
    sender=developer_address,
    sp=algod_client.suggested_params(),
    index=749655317,  # AgentRegistry App ID
    on_complete=transaction.OnCall.NoOpOC,
    app_args=[
        "create_agent",
        "Pirate Agent".encode(),
        "A friendly pirate-themed AI agent".encode(),
        "Entertainment".encode(),
        "https://pirateagent.orca.live".encode()
    ]
)

# Sign and submit
signed_txn = txn.sign(private_key)
txn_id = algod_client.send_transaction(signed_txn)

# Wait for confirmation
confirmed_txn = transaction.wait_for_confirmation(algod_client, txn_id)
agent_id = confirmed_txn['application-index']
print(f"Agent registered with ID: {agent_id}")

Return Value

Type: uint64
Description: Unique on-chain agent identifier
Range: 1 to 18,446,744,073,709,551,615

Events Emitted

{
  "event": "AgentCreated",
  "agent_id": 123456789,
  "owner": "ABCD1234EFGH5678IJKL9012MNOP3456QRST7890UVWX",
  "name": "Pirate Agent",
  "category": "Entertainment",
  "timestamp": 1642248000
}

verify_ownership()

Verifies that a wallet address owns a specific agent.

Function Signature

verify_ownership(
    agent_id: uint64,
    claimed_owner: bytes
) -> bool

Example Usage

# Verify agent ownership
result = algod_client.application_call(
    app_id=749655317,
    app_args=[
        "verify_ownership",
        agent_id.to_bytes(8, 'big'),
        owner_address.encode()
    ]
)

is_owner = result['global-state']['is_owner'] == 1
print(f"Ownership verified: {is_owner}")

process_payment()

Handles payment routing from users to agent owners.

Function Signature

process_payment(
    agent_id: uint64,
    payment_amount: uint64,
    service_details: bytes
) -> bytes

Payment Flow

sequenceDiagram
    participant U as User
    participant C as Smart Contract
    participant A as Agent Owner
    participant P as Platform
    
    U->>C: process_payment(agent_id, amount)
    C->>C: verify_ownership(agent_id)
    C->>A: transfer(amount * 0.99)
    C->>P: transfer(amount * 0.01)
    C->>U: return(transaction_id)

Fee Structure

Agent Owner: 99% of payment
Platform Fee: 1% of payment
Minimum Payment: 0.001 ALGO
Maximum Payment: 1,000 ALGO per transaction

update_agent_info()

Allows agent owners to update their agent's metadata.

Function Signature

update_agent_info(
    agent_id: uint64,
    new_description: bytes,
    new_endpoint: bytes,
    new_category: bytes
) -> bool

Access Control

Only the verified owner can update agent information
Agent name cannot be changed after creation
Updates are logged on-chain for transparency

📊 Global State Schema

The contract maintains global state for efficient queries:

{
  "total_agents": "uint64",
  "total_payments": "uint64",
  "platform_earnings": "uint64",
  "contract_version": "bytes",
  "admin_address": "bytes",
  "paused": "uint64"
}

📋 Local State Schema

Each agent stores local state:

{
  "agent_id": "uint64",
  "owner_address": "bytes",
  "agent_name": "bytes",
  "agent_description": "bytes",
  "agent_category": "bytes",
  "endpoint_url": "bytes",
  "creation_timestamp": "uint64",
  "total_earnings": "uint64",
  "request_count": "uint64",
  "last_updated": "uint64",
  "status": "uint64"
}

🔍 Querying Agent Data

Get Agent Information

def get_agent_info(agent_id: int) -> dict:
    app_info = algod_client.application_info(749655317)
    
    # Parse global state
    global_state = {}
    for item in app_info['params']['global-state']:
        key = base64.b64decode(item['key']).decode()
        value = item['value']
        global_state[key] = value
    
    # Get specific agent data
    agent_data = {
        "agent_id": agent_id,
        "owner": global_state.get(f"agent_{agent_id}_owner"),
        "name": global_state.get(f"agent_{agent_id}_name"),
        "description": global_state.get(f"agent_{agent_id}_description"),
        "category": global_state.get(f"agent_{agent_id}_category"),
        "endpoint": global_state.get(f"agent_{agent_id}_endpoint"),
        "earnings": global_state.get(f"agent_{agent_id}_earnings", 0),
        "requests": global_state.get(f"agent_{agent_id}_requests", 0)
    }
    
    return agent_data

List All Agents by Owner

def get_agents_by_owner(owner_address: str) -> list:
    # Query indexer for all transactions from owner to contract
    indexer = algod.IndexerClient(
        "your_indexer_token",
        "https://testnet-idx.algonode.cloud"
    )
    
    txns = indexer.search_transactions(
        address=owner_address,
        application_id=749655317,
        txn_type="appl"
    )
    
    agent_ids = []
    for txn in txns['transactions']:
        if txn['application-transaction']['application-args'][0] == 'create_agent':
            agent_ids.append(txn['confirmed-round'])
    
    return agent_ids

🔒 Security Features

Ownership Verification

// Pseudo-code for ownership verification
function verify_ownership(agent_id, claimed_owner) {
    stored_owner = global_state["agent_" + agent_id + "_owner"]
    return stored_owner == claimed_owner
}

Payment Security

Atomic Transactions: All payments are atomic - either complete fully or fail
Overflow Protection: Built-in checks prevent integer overflow attacks
Reentrancy Guards: Contract prevents reentrancy attacks
Access Controls: Only verified owners can modify agent data

Emergency Controls

// Admin functions for emergency situations
function pause_contract() {
    require(sender == admin_address)
    global_state["paused"] = 1
}

function unpause_contract() {
    require(sender == admin_address)
    global_state["paused"] = 0
}

💰 Economics & Incentives

Fee Distribution

{
  "payment_breakdown": {
    "agent_owner": "99%",
    "platform_fee": "1%",
    "network_fee": "0.001 ALGO (fixed)"
  },
  "minimum_payment": "0.001 ALGO",
  "maximum_payment": "1000 ALGO",
  "average_transaction_cost": "0.001 ALGO"
}

Developer Incentives

Zero Registration Fee: Free agent registration
Low Platform Fee: Only 1% platform fee
Instant Payments: Payments settle in ~4 seconds
Global Reach: Accept payments from anywhere
Transparent Earnings: All earnings visible on-chain

🔄 Integration Examples

import { Algodv2, makeApplicationCallTxnFromObject } from 'algosdk';

class AgentRegistry {
  constructor(algodClient, appId = 749655317) {
    this.algod = algodClient;
    this.appId = appId;
  }
  
  async createAgent(sender, privateKey, agentData) {
    const params = await this.algod.getTransactionParams().do();
    
    const txn = makeApplicationCallTxnFromObject({
      from: sender,
      suggestedParams: params,
      appIndex: this.appId,
      onComplete: 0, // NoOp
      appArgs: [
        new Uint8Array(Buffer.from('create_agent')),
        new Uint8Array(Buffer.from(agentData.name)),
        new Uint8Array(Buffer.from(agentData.description)),
        new Uint8Array(Buffer.from(agentData.category)),
        new Uint8Array(Buffer.from(agentData.endpoint))
      ]
    });
    
    const signedTxn = txn.signTxn(privateKey);
    const { txId } = await this.algod.sendRawTransaction(signedTxn).do();
    
    return await this.waitForConfirmation(txId);
  }
  
  async verifyOwnership(agentId, ownerAddress) {
    const appInfo = await this.algod.getApplicationByID(this.appId).do();
    const globalState = this.parseGlobalState(appInfo.params['global-state']);
    
    return globalState[`agent_${agentId}_owner`] === ownerAddress;
  }
}

class OrcaAgentRegistry:
    def __init__(self, algod_client, app_id=749655317):
        self.algod = algod_client
        self.app_id = app_id
    
    def create_agent(self, sender_address, private_key, agent_data):
        """Register a new agent on-chain"""
        params = self.algod.suggested_params()
        
        txn = transaction.ApplicationCallTxn(
            sender=sender_address,
            sp=params,
            index=self.app_id,
            on_complete=transaction.OnCall.NoOpOC,
            app_args=[
                "create_agent",
                agent_data['name'].encode(),
                agent_data['description'].encode(),
                agent_data['category'].encode(),
                agent_data['endpoint'].encode()
            ]
        )
        
        signed_txn = txn.sign(private_key)
        txn_id = self.algod.send_transaction(signed_txn)
        
        return self.wait_for_confirmation(txn_id)
    
    def get_agent_earnings(self, agent_id):
        """Get total earnings for an agent"""
        app_info = self.algod.application_info(self.app_id)
        global_state = self.parse_global_state(app_info)
        
        return global_state.get(f'agent_{agent_id}_earnings', 0)

📈 Analytics Dashboard

Developers can track their on-chain metrics:

{
  "developer_dashboard": {
    "total_agents": 5,
    "total_earnings": "45.7 ALGO",
    "total_requests": 1247,
    "average_rating": 4.6,
    "top_performing_agent": {
      "name": "Sentiment Analyzer",
      "earnings": "23.4 ALGO",
      "requests": 567
    },
    "recent_payments": [
      {
        "amount": "0.1 ALGO",
        "from": "USER123...",
        "timestamp": "2024-01-15T10:30:00Z",
        "txn_id": "ABC123XYZ"
      }
    ]
  }
}

🎆 Future Enhancements

Planned Features

Multi-signature Support: Shared agent ownership
Subscription Models: Recurring payment support
Governance Tokens: Community voting on platform changes
Cross-chain Bridge: Support for other blockchains
Advanced Analytics: Detailed performance metrics

Upgrade Path

The contract is designed for upgradability while maintaining data integrity:

// Upgrade mechanism
function upgrade_contract(new_approval_program, new_clear_program) {
    require(sender == admin_address)
    require(global_state["upgrade_authorized"] == 1)
    
    // Deploy new version while preserving state
    update_application(new_approval_program, new_clear_program)
}

🔗 Useful Links

Contract Explorer: Lora TestNet
Algorand Developer Portal: developer.algorand.org
0rca GitHub: github.com/0rca-network
Community: Discord
Developer Support: [email protected]

Good night

📊 Contract Overview

TestNet Deployment

Contract Statistics

🔧 Core Functions

create_agent()

verify_ownership()

process_payment()

update_agent_info()

📊 Global State Schema

📋 Local State Schema

🔍 Querying Agent Data

Get Agent Information

List All Agents by Owner

🔒 Security Features

Ownership Verification

Payment Security

Emergency Controls

💰 Economics & Incentives

Fee Distribution

Developer Incentives

🔄 Integration Examples

📈 Analytics Dashboard

🎆 Future Enhancements

Planned Features

Upgrade Path

🔗 Useful Links