Arca DeFi Contract Development Assistant

This skill provides comprehensive guidance for working with the Arca decentralized vault system, a multi-protocol DeFi platform for automated liquidity provision on the Sonic blockchain.

Project Context

Arca is a sophisticated multi-protocol vault system supporting:

Critical Development Principles

1. Type Safety is Non-Negotiable

**Never use the "any" type in TypeScript files.** Type safety protects against runtime errors. Always use proper types.

2. Tests Define Business Requirements

When tests fail, investigate the root cause - don't rush to change test data. Complex integration tests often catch edge cases that unit tests miss. These bugs could cause catastrophic production failures.

**Key Principle**: If your implementation demonstrates better business practices (security, UX, efficiency) than what tests expect, update the TESTS to reflect the improved requirements, not the other way around.

3. Precision in Testing

Always test exact values. Never use vague assertions like `gt(0)` or `to.be.a("bigint")`. Calculate and verify specific expected amounts based on business logic.

4. Contract Size Management

**CRITICAL**: Always use script-based deployment, not factory contracts. Factory contracts that import multiple concrete contracts will exceed the 24.5KB limit and fail to deploy.

Repository Structure

```

/contracts-metropolis/ # Core vault system for DLMM pools

/contracts-shadow/ # Shadow/Ramses V3 integration (GPL-3.0)

/UI/ # React-based dApp

/test/ # Comprehensive test suite

/scripts/ # TypeScript deployment infrastructure

/lib/ # Git submodules (joe-v2)

/archive/ # Previous implementation reference

```

Development Workflow

Step 1: Environment Setup

When starting work on this project:

```bash

Install dependencies

npm install

Compile contracts

npm run compile

Verify everything works

npm run test

```

Step 2: Development Cycle

After making code changes:

```bash

Fix linting issues

npm run lint:fix

Compile contracts (checks for size warnings)

npm run compile

Run full test suite

npm run test

```

Step 3: Protocol-Specific Development

**When modifying Metropolis code:**

**When modifying Shadow code:**

Step 4: Testing Strategy

**Unit Tests:**

```bash

Run specific test file

npx hardhat test test/ArcaTestnet.test.ts

Run protocol-specific tests

npx hardhat test test/*metropolis*.test.ts

npx hardhat test test/*shadow*.test.ts

```

**Integration Tests:**

```bash

Production workflow tests

npx hardhat test test/*.integration.test.ts

Precision tests

npx hardhat test test/*.precise.test.ts

```

**Test Requirements:**

Step 5: Deployment Strategy

**Three-Tier Testing Approach:**

1. **Local Development:**

```bash

npm run deploy:local # With mocks

npm run dev:reset # Reset blockchain state

```

2. **Testnet Deployment:**

```bash

npm run deploy:testnet # Sonic Blaze Testnet

npm run dev:testnet:status # Check deployment status

npm run dev:testnet:faucet # Get testnet tokens

```

3. **Mainnet Deployment:**

```bash

npm run dev:check # Verify mainnet readiness

npm run deploy:mainnet # Deploy to production

npm run deploy:verify # Verify on block explorer

npm run deploy:export # Export addresses for UI

```

**Post-Deployment:**

```bash

npm run deploy:test --network <network> # Integration testing

npm run dev:discover # Discover rewarder addresses

```

Core Architecture Patterns

Upgradeable Proxy Pattern

All contracts use OpenZeppelin's UUPS upgradeable pattern with proper initialization:

```solidity

import {UUPSUpgradeable} from "@openzeppelin/contracts-upgradeable/proxy/utils/UUPSUpgradeable.sol";

contract MyVault is UUPSUpgradeable {

function initialize(...) external initializer {

// Initialize state

}

function _authorizeUpgrade(address) internal override onlyOwner {}

}

```

Multi-Protocol Support

Common interfaces with protocol-specific extensions:

```solidity

// Common functionality

interface IStrategyCommon {

function deposit(uint256 amountX, uint256 amountY) external;

function withdraw(uint256 shares) external;

}

// Protocol-specific

interface IStrategyMetropolis is IStrategyCommon {

function getLBPair() external view returns (ILBPair);

}

interface IShadowStrategy is IStrategyCommon {

function getPool() external view returns (IRamsesV3Pool);

}

```

Queue-Based Processing

Deposits and withdrawals are queued and processed atomically during rebalance:

1. Users deposit tokens → added to deposit queue

2. Rebalance operation processes in order:

- Remove existing liquidity (protocol-specific)

- Claim and compound rewards

- Process withdrawal queue (calculate shares, apply fees)

- Process deposit queue (mint shares)

- Add new liquidity with remaining tokens

Security Considerations

When reviewing or modifying code, ensure:

Frontend Development (UI Directory)

When working on the dApp:

```bash

cd UI/

Install dependencies

npm install

Start development server

npm run dev

Build for production

npm run build

Fix linting issues

npm run lint:fix

```

**Tech Stack:**

Code Quality Standards

Solidity

TypeScript

Contract Size Optimization

**Best Practices:**

1. Use script-based deployment, not factory contracts

2. Import interfaces instead of concrete contracts

3. Use OpenZeppelin upgrades plugin for deployment

4. Monitor size with `npm run compile`

Example:

```solidity

// Good: Import interface

import {IArcaFeeManagerV1} from "./interfaces/IArcaFeeManagerV1.sol";

// Bad: Import concrete contract (bloats size)

import {ArcaFeeManagerV1} from "./ArcaFeeManagerV1.sol";

```

Common Development Scenarios

Adding a New Vault Type

1. Create contract in appropriate directory (`contracts-metropolis/` or `contracts-shadow/`)

2. Implement protocol-specific interfaces

3. Add deployment logic to respective deployment script

4. Create comprehensive tests with exact value assertions

5. Update factory to support new type

6. Document in DEPLOYMENT.md

Modifying Shared Components

1. Update interface in common layer (`IStrategyCommon`)

2. Implement changes in both Metropolis and Shadow versions

3. Test both protocol flows

4. Verify cross-protocol compatibility

5. Run full test suite before committing

Debugging Failed Tests

1. Ask "What should this code do?" based on business logic

2. Check if test expectations match business requirements

3. Calculate exact expected values manually

4. If implementation is better, update tests to match

5. If implementation is wrong, fix the code

Preparing for Deployment

1. Run full linting: `npm run lint:fix`

2. Check contract sizes: `npm run compile`

3. Run all tests: `npm run test`

4. Deploy to local: `npm run deploy:local`

5. Deploy to testnet: `npm run deploy:testnet`

6. Run integration tests: `npm run deploy:test --network testnet`

7. Verify mainnet readiness: `npm run dev:check`

8. Deploy to mainnet: `npm run deploy:mainnet`

9. Verify contracts: `npm run deploy:verify --network mainnet`

10. Export for UI: `npm run deploy:export`

Key Files Reference

Best Practices Summary

1. **Type Safety**: Never use "any" in TypeScript

2. **Test Philosophy**: Tests define business requirements, not implementation constraints

3. **Precision Testing**: Always verify exact expected values

4. **Contract Size**: Use script-based deployment, import interfaces

5. **Multi-Protocol**: Test both Metropolis and Shadow when modifying shared code

6. **Security First**: ReentrancyGuard, validation, emergency functions

7. **Development Cycle**: lint:fix → compile → test after major changes

8. **Deployment**: Three-tier approach (local → testnet → mainnet)