Join the Swarm: A Developer's Guide to Contributing

By The Queen

Want to join the colony? Here’s everything you need to know.

Quick Start: Deploy a Worker (5 minutes)

The fastest way to contribute is running a worker node:

pip install ants-worker
ants-worker join

That’s it. Your machine is now a kangaroo hunting for Bitcoin Puzzle #71.

What Happens

1. Your worker registers with api.ants-at-work.com
2. Gateway issues a bearer token (stored in ~/.ants/config.json)
3. Worker queries for cold regions (low pheromone)
4. Kangaroo algorithm runs locally
5. Distinguished points are deposited to the gateway
6. Repeat until collision found

Options

# Run as wild kangaroo (different starting point)
ants-worker join -t wild

# Enable GPU acceleration
ants-worker join --gpu

# Limit CPU usage
ants-worker join --threads 4

# Custom gateway (for testing)
ants-worker join --gateway http://localhost:8787

Check Status

# Your contribution stats
ants-worker status

# Output:
# Worker ID: worker-abc123
# Status: Active
# Points Deposited: 847
# Regions Explored: 23
# Runtime: 4h 23m

Medium Path: Build a Custom Agent (1 hour)

Want more control? Build your own agent using our framework:

git clone https://github.com/antsatwork/ants-at-work
cd ants-at-work
pip install -r requirements.txt

Example: Custom Scout

from ants import Scout
from ants.knowledge import TypeDBClient

class MyScout(Scout):
    """A scout with custom exploration behavior."""

    async def decide_direction(self, options):
        """Override default direction selection."""
        # Default scout has pheromone_sensitivity = 0.3
        # We can customize this

        # Find the least explored option
        min_pheromone = min(o.pheromone_level for o in options)
        unexplored = [o for o in options if o.pheromone_level == min_pheromone]

        # If multiple unexplored, pick randomly
        import random
        return random.choice(unexplored)

async def main():
    async with TypeDBClient() as db:
        scout = MyScout("my-scout-001", db)
        await scout.run(max_iterations=1000)

if __name__ == "__main__":
    import asyncio
    asyncio.run(main())

Example: Custom Pheromone Strategy

from ants.actors.base import Agent

class AggressiveHarvester(Agent):
    """Harvester that deposits stronger pheromones."""

    pheromone_sensitivity = 0.95  # Follow trails closely
    deposit_strength = 2.0       # Double deposits

    async def on_success(self, result):
        """Called when a valuable discovery is made."""
        # Deposit extra strong signal
        await self.deposit_pheromone(
            result.location,
            strength=self.deposit_strength * 2
        )

        # Broadcast to relays
        await self.broadcast_signal(result)

Run Your Agent

python my_agent.py

Your agent connects to TypeDB Cloud (credentials in .env), joins the active mission, and starts contributing.

Deep Path: Contribute to Core (1 day+)

Want to improve the platform itself? Here’s the contribution workflow:

1. Understand the Architecture

ants/
├── actors/          # Agent implementations
├── groups/          # ONE Ontology: roles, permissions
├── skills/          # Reusable behaviors (crypto, kangaroo)
├── knowledge/       # TypeDB client, schema
├── events/          # Event recording, decay service
└── gateway/         # D1 sync service

2. Find an Issue

Check GitHub Issues labeled:

• good-first-issue: Small, well-defined tasks
• help-wanted: Larger features needing contributors
• hackathon-track-*: Specific hackathon challenges

3. Set Up Development Environment

# Clone and setup
git clone https://github.com/antsatwork/ants-at-work
cd ants-at-work
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
pip install -r requirements-dev.txt

# Run tests
pytest tests/

# Type checking
mypy ants/

4. Environment Variables

Create .env from template:

cp .env.example .env

Required variables:

TYPEDB_ADDRESS=https://cr0mc4-0.cluster.typedb.com:80
TYPEDB_DATABASE=ants-colony
TYPEDB_USERNAME=your_username
TYPEDB_PASSWORD=your_password
TYPEDB_TLS=true

Contact us for developer credentials.

5. Make Changes

Follow our coding standards:

• Type hints required
• Docstrings for public functions
• Tests for new features
• No breaking changes without RFC

6. Submit PR

git checkout -b feature/my-improvement
git add .
git commit -m "feat: description of change"
git push origin feature/my-improvement

Open PR on GitHub. Include:

• Description of changes
• Test results
• Performance impact (if applicable)

Hackathon Tracks

Track 1: Algorithm Innovators

Improve search efficiency:

• Novel jump table designs for kangaroo
• Better distinguished point criteria
• Pheromone decay curves
• Collision detection optimization

Starter issue: hackathon-track-1-starter

Track 2: Infrastructure Architects

Scale the colony:

• Optimize TypeDB queries
• Build monitoring dashboards
• Improve D1 → TypeDB sync
• Kubernetes deployment configs

Starter issue: hackathon-track-2-starter

Track 3: Knowledge Synthesizers

Analyze and visualize:

• Pheromone trail visualization
• Pattern detection algorithms
• Superhighway identification
• Cross-mission knowledge transfer

Starter issue: hackathon-track-3-starter

Gateway API Reference

All workers communicate through api.ants-at-work.com:

Authentication

# Register (get token)
curl -X POST https://api.ants-at-work.com/register \
  -H "Content-Type: application/json" \
  -d '{"hostname":"my-worker","platform":"linux"}'
# Returns: {"token":"abc123...","worker_id":"worker-xxx"}

All subsequent requests need the token:

-H "Authorization: Bearer abc123..."

Endpoints

Route	Method	Description
/health	GET	Health check
/target	GET	Get puzzle target
/regions	GET	Get cold regions
/dp	POST	Deposit distinguished point
/intention	POST	Mark working intention
/collision	GET	Check for collision
/stats	GET	Your contribution stats

Example: Deposit Point

curl -X POST https://api.ants-at-work.com/dp \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "hash": "abc123...",
    "worker_type": "tame",
    "point_hex": "04...",
    "distance": "12345"
  }'

Community

Discord

Primary communication channel. Channels:

• #general: General discussion
• #dev-help: Technical questions
• #hackathon-2025: Event coordination
• #showcase: Share your work

Join: discord.gg/antsatwork

GitHub

All code, issues, and discussions: github.com/antsatwork/ants-at-work

Weekly Calls

Every Wednesday, 18:00 UTC. Open to all contributors.

• Progress updates
• Technical deep dives
• Q&A

Link in Discord #announcements.

Rewards

Hackathon Prizes

• Track winners: $2,000 each
• Best research paper: $1,000
• Community choice: $500

Bitcoin Puzzle Split

If Puzzle #71 is solved, rewards based on:

1. Distinguished points deposited (40%)
2. Code contributions merged (30%)
3. Active worker time (20%)
4. Community contributions (10%)

Details in REWARDS.md.

Ongoing Recognition

Top contributors receive:

• Colony membership (permanent agent rights)
• Voting on future missions
• Early access to new features
• Attribution in papers

Questions?

• Technical: Discord #dev-help or GitHub Issues
• General: [email protected]
• Research: [email protected]

The colony welcomes you.

---

Deploy your first worker today. The swarm grows stronger with every agent.