Contributing

How to contribute to the 0rca ecosystem built on Cronos EVM.

Contributing to 0rca Network

Thank you for your interest in contributing to 0rca Network! We're building the first decentralized AI orchestration platform on Cronos EVM, and we welcome contributions from developers, designers, writers, and AI enthusiasts worldwide.

🌟 Ways to Contribute

Code Contributions

  • Core Protocol: Improve the 0rca Network infrastructure
  • Agent SDK: Enhance the Python SDK for building AI agents
  • Platform Features: Add new features to our web platforms
  • Smart Contracts: Develop and audit Cronos EVM contracts
  • Developer Tools: Create tools that make development easier

Documentation

  • Technical Docs: Improve API documentation and guides
  • Tutorials: Write step-by-step tutorials for developers
  • Examples: Create sample agents and use cases
  • Translations: Help translate docs to other languages

Community Support

  • Discord Moderation: Help manage our community channels
  • Developer Support: Answer questions and help newcomers
  • Content Creation: Write blog posts, create videos
  • Event Organization: Organize meetups and workshops

Testing & QA

  • Bug Reports: Find and report issues
  • Feature Testing: Test new features before release
  • Security Audits: Review code for security vulnerabilities
  • Performance Testing: Help optimize system performance

🚀 Getting Started

1. Set Up Your Development Environment

Prerequisites

# Install required tools
git --version          # Git for version control
node --version         # Node.js 18+ for frontend
python --version       # Python 3.10+ for agents
docker --version       # Docker for containerization

Clone the Repository

# Clone the main repository
git clone https://github.com/0rca-network/0rca-agent-sdk.git
cd 0rca-agent-sdk

# Install dependencies
pip install -e .
pip install -r requirements-dev.txt

Set Up Cronos Testnet

# Configure environment for Cronos EVM Testnet
export CRONOS_RPC_URL="https://evm-t3.cronos.org"
export CRONOS_CHAIN_ID="338"
export USDC_ADDRESS="0x38Bf87D7281A2F84c8ed5aF1410295f7BD4E20a1"

# Get testnet tokens
# Visit: https://cronos.org/faucet

2. Understand the Codebase

Repository Structure

0rca-agent-sdk/
├── orca_agent_sdk/          # Core SDK code
│   ├── backends/            # AI backend integrations
│   ├── core/               # Core functionality
│   ├── contracts/          # Smart contract clients
│   └── server.py           # Flask server
├── examples/               # Example agents
├── tests/                  # Test suite
├── docs/                   # Documentation
└── scripts/               # Utility scripts

Key Components

  • Agent Server: Flask-based HTTP server for agents
  • Payment Manager: x402 protocol implementation
  • Vault Client: Cronos smart contract integration
  • A2A Protocol: Agent-to-agent communication
  • Backend Adapters: Support for multiple AI frameworks

3. Run Tests

# Run the full test suite
pytest tests/

# Run specific test categories
pytest tests/test_payment.py      # Payment protocol tests
pytest tests/test_contracts.py    # Smart contract tests
pytest tests/test_agents.py       # Agent functionality tests

# Run with coverage
pytest --cov=orca_agent_sdk tests/

4. Start a Local Agent

# Run example agent
cd examples/basic_agent
python agent.py

# Test the agent
curl -X POST http://localhost:8000/agent \
  -H "Content-Type: application/json" \
  -H "X-TEST-BYPASS: true" \
  -d '{"prompt": "Hello, world!"}'

📝 Contribution Guidelines

Code Style

Python Code Style

We follow PEP 8 with some modifications:

# Good: Clear, descriptive names
class AgentPaymentManager:
    def process_x402_challenge(self, challenge_data: dict) -> bool:
        """Process x402 payment challenge with EIP-712 signature."""
        return self._verify_signature(challenge_data)

# Good: Type hints and docstrings
async def deploy_agent_vault(
    self, 
    owner_address: str, 
    agent_wallet: str
) -> str:
    """
    Deploy a new Sovereign Vault on Cronos EVM.
    
    Args:
        owner_address: The vault owner's address
        agent_wallet: The agent's operational wallet
        
    Returns:
        The deployed vault contract address
    """
    pass

Code Formatting

# Install formatting tools
pip install black isort flake8

# Format code
black orca_agent_sdk/
isort orca_agent_sdk/

# Check style
flake8 orca_agent_sdk/

TypeScript/JavaScript Style

For frontend contributions:

// Good: Clear interfaces and types
interface AgentConfig {
  name: string;
  price: number;
  vaultAddress: string;
  capabilities: string[];
}

// Good: Async/await with proper error handling
async function callAgent(agentId: string, prompt: string): Promise<AgentResponse> {
  try {
    const response = await fetch(`/api/agents/${agentId}`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ prompt })
    });
    
    if (!response.ok) {
      throw new Error(`Agent call failed: ${response.status}`);
    }
    
    return await response.json();
  } catch (error) {
    console.error('Agent call error:', error);
    throw error;
  }
}

Commit Messages

Format

type(scope): brief description

Longer description if needed.

- List specific changes
- Reference issues: Fixes #123
- Breaking changes: BREAKING CHANGE: description

Types

  • feat: New feature
  • fix: Bug fix
  • docs: Documentation changes
  • style: Code style changes (formatting, etc.)
  • refactor: Code refactoring
  • test: Adding or updating tests
  • chore: Maintenance tasks

Examples

# Good commit messages
git commit -m "feat(payment): add Cronos EVM support for x402 protocol"
git commit -m "fix(vault): handle insufficient balance in spend() function"
git commit -m "docs(api): add examples for agent deployment endpoints"

# Bad commit messages
git commit -m "fix stuff"
git commit -m "update code"
git commit -m "changes"

Pull Request Process

1. Create a Feature Branch

# Create branch from main
git checkout main
git pull origin main
git checkout -b feature/cronos-integration

# Or for bug fixes
git checkout -b fix/payment-validation-bug

2. Make Your Changes

  • Write clean, well-documented code
  • Add tests for new functionality
  • Update documentation as needed
  • Ensure all tests pass

3. Submit Pull Request

## Description
Brief description of changes and motivation.

## Changes Made
- Added Cronos EVM support to payment manager
- Updated vault client for gasless transactions
- Added comprehensive tests for new functionality

## Testing
- [ ] All existing tests pass
- [ ] New tests added and passing
- [ ] Manual testing completed on Cronos testnet

## Documentation
- [ ] Code is well-documented
- [ ] API documentation updated
- [ ] Examples updated if needed

## Breaking Changes
None / List any breaking changes

Fixes #123

4. Code Review Process

  1. Automated Checks: CI/CD runs tests and style checks
  2. Peer Review: At least one core team member reviews
  3. Testing: Changes tested on Cronos testnet
  4. Approval: Core team approves and merges

🐛 Bug Reports

Before Reporting

  1. Search existing issues to avoid duplicates
  2. Test on latest version to ensure bug still exists
  3. Reproduce consistently to provide clear steps

Bug Report Template

## Bug Description
Clear description of what the bug is.

## Environment
- OS: [e.g., macOS 13.0]
- Python Version: [e.g., 3.11.0]
- SDK Version: [e.g., 1.0.7]
- Network: [Cronos Testnet/Mainnet]

## Steps to Reproduce
1. Create agent with config...
2. Send request to...
3. Observe error...

## Expected Behavior
What should have happened.

## Actual Behavior
What actually happened.

## Error Messages

Paste any error messages or logs here


## Additional Context
Any other relevant information.

💡 Feature Requests

Feature Request Template

## Feature Description
Clear description of the proposed feature.

## Use Case
Why is this feature needed? What problem does it solve?

## Proposed Solution
How should this feature work?

## Alternatives Considered
Other approaches you've considered.

## Implementation Notes
Technical considerations or suggestions.

## Priority
- [ ] Critical (blocking current work)
- [ ] High (important for next release)
- [ ] Medium (nice to have)
- [ ] Low (future consideration)

🏆 Recognition & Rewards

Contributor Levels

Bronze Contributors

  • Requirements: 1-5 merged PRs or significant documentation
  • Benefits: Contributor badge, Discord role
  • Examples: Bug fixes, documentation improvements

Silver Contributors

  • Requirements: 6-15 merged PRs or major feature contributions
  • Benefits: Early access to features, contributor call invites
  • Examples: New agent backends, platform features

Gold Contributors

  • Requirements: 16+ merged PRs or core infrastructure work
  • Benefits: Direct team communication, roadmap input
  • Examples: Core protocol improvements, security audits

Platinum Contributors

  • Requirements: Sustained contributions over 6+ months
  • Benefits: Advisory role, conference speaking opportunities
  • Examples: Long-term maintainers, ecosystem builders

Rewards Program

  • Bug Bounties: Up to $10,000 USDC for critical security issues
  • Feature Bounties: Compensation for implementing requested features
  • Hackathon Prizes: Regular contests with USDC prizes
  • Conference Sponsorship: Travel support for speaking at events

📚 Development Resources

Learning Materials

Development Tools

  • VS Code Extension: 0rca development tools (in development)
  • Agent Templates: Pre-built agent examples
  • Testing Utilities: Tools for testing agents locally
  • Deployment Scripts: Automated deployment to Cronos

Community Resources

  • Discord #dev-support: Get help from other developers
  • Weekly Dev Calls: Join our developer community calls
  • Code Review Sessions: Learn from experienced contributors
  • Pair Programming: Work with core team members

🔒 Security Guidelines

Reporting Security Issues

DO NOT create public GitHub issues for security vulnerabilities.

Instead:

  1. Email: security@0rca.network
  2. Include: Detailed description and reproduction steps
  3. Response: We'll respond within 24 hours
  4. Disclosure: Coordinated disclosure after fix is deployed

Security Best Practices

  • Never commit private keys or sensitive data
  • Use environment variables for configuration
  • Validate all inputs to prevent injection attacks
  • Follow smart contract security best practices
  • Test on Cronos testnet before mainnet deployment

Code Security Checklist

  • Input validation implemented
  • Authentication/authorization checked
  • No hardcoded secrets
  • Error handling doesn't leak information
  • Dependencies are up to date
  • Smart contracts audited (for contract changes)

📞 Getting Help

Development Support

Mentorship Program

New contributors can be paired with experienced developers:

  • Application: Fill out mentorship form
  • Duration: 3-month program
  • Benefits: 1-on-1 guidance, code reviews, career advice

Core Team Contact

🚀 Ready to Contribute?

We're excited to have you join the 0rca community! Here's how to get started:

  1. Join our Discord and introduce yourself
  2. Browse open issues labeled "good first issue"
  3. Set up your development environment following this guide
  4. Make your first contribution and become part of the 0rca family!

Together, we're building the future of decentralized AI on Cronos EVM! 🌟