@somnia-react/autonomous

The battle-tested standard library for writing reactive Solidity handlers on Somnia.

Similar to what @openzeppelin/contracts is for access control and tokens, @somnia-react/autonomous specializes in secure, gas-efficient, composable patterns for on-chain reactive logic.

Features

• 🛡️ Battle-Tested Patterns – Reentrancy guards, gas limit checks, safe external calls
• ⚡ Gas Optimized – <250k gas per _onEvent call in happy path
• 🧩 Composable – Mix & match handlers, inherit & customize
• 📚 Zero to Hero – Deploy reactive handlers in 5 minutes with tutorials
• 🔍 Type-Safe SDK – Full TypeScript support with abitype for contracts
• 🧪 85%+ Test Coverage – Foundry + Hardhat comprehensive tests
• 📖 Excellent Docs – VitePress site with examples & security guides

Quick Start

Installation

npm install @somnia-react/autonomous
# or
pnpm add @somnia-react/autonomous

5-Minute Example: Auto-Compound Vault

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;

import "@somnia-react/autonomous/handlers/AutoCompoundHandler.sol";

contract MyAutoCompoundVault is AutoCompoundHandler {
    constructor(
        address _compoundToken,
        address _rewardToken,
        address _vault
    ) {
        // Initialize with your parameters
    }

    function compound() external override {
        // Your auto-compound logic
    }
}

Deploy & subscribe in TypeScript:

import {
  deployAutoCompoundHandler,
  createAutoCompoundSubscription,
} from "@somnia-react/autonomous";

const handler = await deployAutoCompoundHandler({
  compoundToken: "0x...",
  rewardToken: "0x...",
  vaultAddress: "0x...",
});

const subscription = createAutoCompoundSubscription({
  handlerAddress: handler.address,
  targetVault: "0x...",
  eventSignature: "RewardAdded(indexed address,uint256)",
});

console.log("Deployed & subscribed:", handler.address);

Handlers (MVP)

| Handler | Purpose | Use Case | | -------------------------- | ---------------------- | --------------------------- | | BaseReactiveHandler | Foundation with safety | Inherit for custom handlers | | AutoCompoundHandler | Auto-compound rewards | Yield farming vaults | | LiquidationGuardian | Monitor & liquidate | Lending protocols | | CronLikeScheduler | Time-based triggers | Scheduled execution | | EventFilterThrottle | Debounce events | Noisy on-chain streams | | CrossCallOrchestrator | Chain calls atomically | Multi-step automation | | UpgradeableReactiveProxy | UUPS upgradeable base | Future-proof contracts |

Documentation

• Getting Started – Install, setup, first handler
• Handlers Guide – Deep dive into each handler
• SDK Documentation – TypeScript SDK for deployment & subscriptions
  • Deployment API – Deploy all 6 handler types
  • Subscriptions API – Create event subscriptions
  • Decoders API – Parse handler events
  • API Reference – Complete type definitions
• Security Best Practices – Gas limits, oracles, reentrancy
• API Reference – Full Solidity & TypeScript docs
• Examples – Production-ready code snippets

Live Docs: https://somnia-react.github.io/autonomous

Project Structure

packages/
├── contracts/     # Solidity handlers (Foundry + Hardhat)
├── sdk/           # TypeScript deployment & helpers (Vitest)
└── docs/          # VitePress documentation site

Development

Prerequisites

• Node.js ≥18.0.0
• pnpm ≥8.0.0
• Foundry (for Solidity development)

Setup

pnpm install
pnpm build
pnpm test

Lint & Format

pnpm lint
pnpm format

Testing & Quality

Test Coverage

SDK Tests: 88/88 passing ✅

• 31 subscription tests (fluent API, validators, factory functions)
• 21 integration tests (end-to-end workflows, cross-module testing)
• 18 event decoder tests (all event type parsing)
• 18 deployment tests (all handler deployment functions)

Code Coverage

All files:      85.31% statements | 66.66% branches | 93.87% functions
Decoders:       95.94% statements | 59.25% branches | 100% functions
Subscriptions:  91.46% statements | 82.89% branches | 95.45% functions
Deployment:     71.39% statements | 47.16% branches | 84.61% functions

Solidity Tests: 30+ Foundry tests ✅

• BaseReactiveHandler tests
• Handler implementation tests
• Integration tests

Running Tests

# All tests
pnpm test

# SDK tests only
cd packages/sdk
pnpm test

# With coverage
pnpm test:coverage

# Solidity tests
cd packages/contracts
pnpm test

Quality Metrics

• Type Safety: Full TypeScript with strict mode
• Linting: ESLint + Prettier for code consistency
• Security: No vulnerable dependencies
• Documentation: Comprehensive inline docs + 4 doc files + README

Performance

• SDK Build: Compiles to ESM + CJS in <200ms
• Handler Deployment: <50ms average
• Event Decoding: <1ms per event (v8 decoded logs)
• Bundle Size: ~15KB minified + gzipped

pnpm docs:dev    # Live server at localhost:5173
pnpm docs:build  # Static site in docs/.vitepress/dist

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Security

⚠️ Important: This library is not yet audited. Review the Security Best Practices guide and test thoroughly before deploying to mainnet.

For security concerns, please email [email protected] or open a private GitHub security advisory.

License

MIT License – see LICENSE

Roadmap

• v0.1.0 (MVP) – Base + 4 handlers + SDK + docs
• v0.2.0 – Upgradeable patterns, advanced filters
• v1.0.0 – Community handlers, audit, ecosystem promotion

See Also

• @somnia-chain/reactivity-contracts – Official Somnia reactivity SDK
• @openzeppelin/contracts – Industry-standard smart contract library
• Somnia Docs – On-chain reactivity guide

Built with ❤️ for the Somnia ecosystem.