Setup Guide

This guide helps developers set up their environment to contribute to Citizen of Arcanis.

Prerequisites

Required Software

Node.js and npm

  • Node.js 18+ recommended

  • npm comes bundled with Node.js

  • Used for frontend development

Rust and Cairo

  • Rust programming language

  • Cairo 2.10.1+ for smart contracts

  • Scarb package manager for Cairo

Git

  • Version control for code collaboration

  • Required for cloning repositories

  • Used for contributing code changes

Recommended Tools

VS Code

  • Cairo extension for syntax highlighting

  • Integrated terminal for commands

  • Git integration for version control

Starknet Wallet

  • Argent or Braavos for testing

  • Needed for interacting with smart contracts

  • Required for blockchain transactions

Repository Structure

The project consists of three main repositories:

COA-Contracts (Smart Contracts)

COA-Contracts/
├── src/
│   ├── models/          # Game data structures
│   ├── systems/         # Game logic contracts
│   ├── interfaces/      # Contract interfaces
│   └── helpers/         # Utility functions
├── scripts/             # Deployment scripts
└── Scarb.toml          # Cairo project configuration

COA-Website (Marketplace)

COA-Website/
├── src/
│   ├── app/            # Next.js pages
│   ├── components/     # React components
│   ├── hooks/          # Custom React hooks
│   └── context/        # State management
├── public/             # Static assets
└── package.json        # Node.js dependencies

COA-landing (Landing Page)

COA-landing/
├── src/
│   ├── components/     # React components
│   ├── pages/          # Application pages
│   └── assets/         # Images and styles
└── package.json        # Node.js dependencies

Setup Instructions

1. Clone the Repositories

# Clone the main contract repository
git clone https://github.com/SunsetLabs-Game/COA-Contracts.git
cd COA-Contracts

# Clone the website repository
git clone https://github.com/SunsetLabs-Game/COA-Website.git
cd COA-Website

# Clone the landing page repository
git clone https://github.com/SunsetLabs-Game/COA-landing.git
cd COA-landing

2. Install Dependencies

For Smart Contracts (COA-Contracts):

cd COA-Contracts
# Install Scarb if not already installed
curl --proto '=https' --tlsv1.2 -sSf https://docs.swmansion.com/scarb/install.sh | sh
# Build the project
scarb build

For Website (COA-Website):

cd COA-Website
npm install

For Landing Page (COA-landing):

cd COA-landing
npm install

3. Environment Configuration

Smart Contracts:

  • Copy dojo_dev.toml.example to dojo_dev.toml

  • Update configuration for your development environment

  • Set up Starknet RPC endpoints

Frontend Applications:

  • Create .env.local files in both website and landing directories

  • Add required environment variables:

    • Firebase configuration

    • Starknet network settings

    • API endpoints

Development Commands

Smart Contracts

Build Contracts:

cd COA-Contracts
sozo build

Deploy to Local Network:

sozo migrate

Run Tests:

scarb test

Execute Contract Functions:

# Spawn a player
sozo execute dojo_starter-actions spawn --wait

# Move a player
sozo execute dojo_starter-actions move -c 1 --wait

Frontend Development

Website Development Server:

cd COA-Website
npm run dev

Landing Page Development Server:

cd COA-landing
npm run dev

Build for Production:

npm run build

Run Linting:

npm run lint

Development Workflow

1. Contract Development

Making Changes:

  1. Edit files in src/ directory

  2. Build contracts with sozo build

  3. Test changes locally

  4. Deploy to testnet for integration testing

Common Tasks:

  • Adding new game models

  • Implementing game mechanics

  • Creating new player actions

  • Optimizing gas usage

2. Frontend Development

Component Development:

  1. Create React components in appropriate directories

  2. Test components in development server

  3. Integrate with smart contracts

  4. Style with Tailwind CSS

Common Tasks:

  • Building user interfaces

  • Integrating wallet connectivity

  • Implementing marketplace features

  • Creating responsive designs

Testing

Smart Contract Testing

Unit Tests:

cd COA-Contracts
scarb test

Integration Tests:

  • Deploy to local Starknet node

  • Test contract interactions

  • Verify game logic correctness

Frontend Testing

Component Tests:

npm run test

End-to-End Tests:

  • Test user workflows

  • Verify wallet integration

  • Check marketplace functionality

Code Standards

Smart Contracts (Cairo)

Naming Conventions:

  • Use snake_case for variables and functions

  • Use PascalCase for structs and traits

  • Clear, descriptive names

Code Organization:

  • Group related functions in traits

  • Use modules for logical separation

  • Document complex functions

Frontend (TypeScript/React)

Naming Conventions:

  • Use camelCase for variables and functions

  • Use PascalCase for components

  • Use kebab-case for file names

Code Organization:

  • One component per file

  • Group related components in directories

  • Use custom hooks for shared logic

Common Issues and Solutions

Smart Contract Issues

Build Failures:

  • Check Cairo version compatibility

  • Verify Scarb.toml configuration

  • Update dependencies if needed

Deployment Issues:

  • Ensure sufficient account balance

  • Check network connectivity

  • Verify contract syntax

Frontend Issues

Node Module Issues:

  • Delete node_modules and reinstall

  • Check Node.js version compatibility

  • Clear npm cache if needed

Wallet Connection Issues:

  • Verify wallet is properly configured

  • Check network settings

  • Ensure proper RPC endpoints

Contributing Guidelines

Before Contributing

  1. Read the project documentation

  2. Set up development environment

  3. Join the community Discord/Telegram

  4. Look for "good first issue" labels

Making Contributions

  1. Fork the repository

  2. Create a feature branch

  3. Make your changes

  4. Test thoroughly

  5. Submit a pull request

Pull Request Guidelines

  • Clear description of changes

  • Reference any related issues

  • Include tests for new functionality

  • Follow code style guidelines

  • Ensure all tests pass

Getting Help

Community Resources

Official Channels:

  • Telegram: Technical discussions

  • Discord: Community chat

  • GitHub Issues: Bug reports and feature requests

Development Help:

  • Review existing code for examples

  • Check documentation for APIs

  • Ask questions in developer channels

  • Participate in community calls

Common Learning Resources

Cairo Development:

  • Starknet documentation

  • Cairo language guide

  • Dojo framework documentation

React/Next.js Development:

  • React documentation

  • Next.js guides

  • TypeScript handbook

Welcome to the Citizen of Arcanis development community! Your contributions help build the future of blockchain gaming.

PreviousEquipment & TradingNextContributing

Last updated