@switchboard-xyz/on-demand-solidity/README.md

Switchboard Solidity SDK - Professional Oracle Infrastructure

# Switchboard Solidity SDK v1.0.0

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![npm version](https://badge.fury.io/js/%40switchboard-xyz%2Fon-demand-solidity.svg)](https://badge.fury.io/js/%40switchboard-xyz%2Fon-demand-solidity)

Professional-grade oracle infrastructure for EVM chains. This SDK provides the core contracts and interfaces for Switchboard and Surge Support.

## 🚀 What's New in v1.0.0

This is a **major version upgrade** from Switchboard v2 to v3, featuring:

- **Advanced signature verification** with Solana oracle compatibility
- **Upgradeable contracts** using OpenZeppelin's UUPS pattern
- **Role-based access control** for secure operations
- **Attestation verification** for cross-chain oracle operations
- **Backwards compatibility** layer for v2 migration

## 📦 Installation

```bash
npm install @switchboard-xyz/on-demand-solidity
```

## 🏗️ Architecture

### Core Contracts

- **`Switchboard.sol`** - Main oracle contract with feed management
- **`SwitchboardQueue.sol`** - Oracle queue management with key validation
- **`SwitchboardVerifier.sol`** - Signature verification for feed updates

### Interfaces

- **`ISwitchboard.sol`** - Main interface for oracle operations
- **`ISwitchboardQueue.sol`** - Queue management interface
- **`ISwitchboardVerifier.sol`** - Verification interface

### Libraries

- **`SwitchboardTypes.sol`** - Core data structures and types
- **`SwitchboardErrors.sol`** - Custom error definitions
- **`SwitchboardEvents.sol`** - Event definitions
- **`SwitchboardAttestationLib.sol`** - Attestation verification utilities
- **`SwitchboardEncoding.sol`** - Efficient encoding/decoding utilities
- **`SwitchboardSignatureVerification.sol`** - Signature verification utilities

## 🔧 Usage

### Basic Integration

```solidity
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.22;

import "@switchboard-xyz/on-demand-solidity/interfaces/ISwitchboard.sol";
import "@switchboard-xyz/on-demand-solidity/libraries/SwitchboardTypes.sol";

contract MyContract {
    ISwitchboard public switchboard;

    constructor(address _switchboard) {
        switchboard = ISwitchboard(_switchboard);
    }

    function updatePrice(bytes calldata feedData) external payable {
        // Update feeds with encoded data
        SwitchboardTypes.FeedUpdateData memory updateData =
            switchboard.updateFeeds{value: msg.value}(feedData);

        // Get verified feed value
        (int256 price, uint256 timestamp, uint64 slotNumber) =
            switchboard.getFeedValue(updateData, "4cd1cad962425681af07b9254b7d804de3ca3446fbfd1371bb258d2c75059812");

        // Use the verified price...
    }
}
```

### Advanced Usage with Custom Verification

```solidity
import "@switchboard-xyz/on-demand-solidity/contracts/SwitchboardVerifier.sol";
import "@switchboard-xyz/on-demand-solidity/libraries/SwitchboardSignatureVerification.sol";

contract CustomVerifier {
    using SwitchboardSignatureVerification for bytes32;

    function verifyCustomFeed(
        SwitchboardTypes.FeedUpdateData calldata updateData
    ) external view returns (bool) {
        // Create message hash
        bytes32 messageHash = SwitchboardSignatureVerification.createMessageHash(
            updateData.feedInfos,
            updateData.slotNumber,
            updateData.timestamp
        );

        // Verify signatures
        uint8 validSignatures = 0;
        for (uint256 i = 0; i < updateData.signatures.length; i++) {
            try SwitchboardSignatureVerification.verifySignature(
                messageHash,
                updateData.signatures[i]
            ) returns (address signer) {
                // Check if signer is authorized
                if (isAuthorizedSigner(signer)) {
                    validSignatures++;
                }
            } catch {
                // Signature invalid
            }
        }

        return validSignatures >= updateData.feedInfos[0].minOracleSamples;
    }
}
```

## 🔄 Migration from v0.x (Switchboard v2)

If you're upgrading from the previous version, here's what changed:

### Breaking Changes

1. **Interface Structure**: The modular interface system has been replaced with unified contracts
2. **Data Types**: New `SwitchboardTypes` library replaces the old `Structs` contract
3. **Error Handling**: Custom errors replace revert strings for gas efficiency
4. **Encoding**: New efficient encoding system replaces ABI encoding

### Migration Steps

1. **Update Imports**:

   ```solidity
   // Old (v0.x)
   import "@switchboard-xyz/on-demand-solidity/interfaces/ISwitchboardModule.sol";

   // New (v1.0.0)
   import "@switchboard-xyz/on-demand-solidity/interfaces/ISwitchboard.sol";
   ```

2. **Update Data Types**:

   ```solidity
   // Old (v0.x)
   import "@switchboard-xyz/on-demand-solidity/Structs.sol";
   Structs.Update memory update;

   // New (v1.0.0)
   import "@switchboard-xyz/on-demand-solidity/libraries/SwitchboardTypes.sol";
   SwitchboardTypes.Update memory update;
   ```

3. **Legacy Support**: Old interfaces are available in the `legacy/v2/` directory for gradual migration

## 🛡️ Security Features

- **Upgradeable Contracts**: UUPS pattern for secure upgrades
- **Role-Based Access Control**: Granular permissions for different operations
- **Signature Verification**: Cryptographic verification of oracle signatures
- **Attestation System**: Cross-chain verification capabilities
- **Reentrancy Protection**: Guards against reentrancy attacks
- **Pausable Operations**: Emergency pause functionality

## 📊 Gas Optimization

The new encoding system provides significant gas savings:

- **Tight-packed encoding**: No 32-byte alignment padding
- **Efficient data structures**: Optimized for minimal storage
- **Custom errors**: More gas-efficient than revert strings
- **Assembly optimizations**: Low-level optimizations where appropriate

## 🔗 Integration Examples

### DeFi Price Feeds

```solidity
contract PriceFeedConsumer {
    ISwitchboard public switchboard;

    function getLatestPrice(bytes32 feedId) external view returns (int256) {
        SwitchboardTypes.Update memory update = switchboard.latestUpdate(feedId);
        return update.result;
    }
}
```

### Oracle Queue Management

```solidity
contract OracleManager {
    ISwitchboardQueue public queue;

    function addOracle(address oracleKey) external {
        queue.addOracleKey(oracleKey);
    }

    function verifyOracle(address oracleKey) external view returns (bool) {
        return queue.isValidOracleSigningKey(oracleKey);
    }
}
```

## 📚 Documentation

- [Full Documentation](https://docs.switchboard.xyz)
- [API Reference](https://docs.switchboard.xyz/api-reference)
- [Migration Guide](https://docs.switchboard.xyz/migration-guide)
- [Examples](https://github.com/switchboard-xyz/evm-on-demand/tree/main/examples)

## 🤝 Contributing

We welcome contributions! Please see our [Contributing Guide](https://github.com/switchboard-xyz/evm-on-demand/blob/main/CONTRIBUTING.md) for details.

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🆘 Support

- **Documentation**: [docs.switchboard.xyz](https://docs.switchboard.xyz)
- **Discord**: [Join our community](https://discord.gg/switchboardxyz)
- **GitHub Issues**: [Report bugs or request features](https://github.com/switchboard-xyz/evm-on-demand/issues)
- **Security**: [security@switchboard.xyz](mailto:security@switchboard.xyz)

## 🔄 Version History

### v1.0.0 (Current)

- **BREAKING**: Complete architectural overhaul from v2 to v3
- **NEW**: Professional-grade contracts with enhanced security
- **NEW**: Efficient encoding system for gas optimization
- **NEW**: Advanced signature verification capabilities
- **NEW**: Upgradeable contract architecture
- **NEW**: Role-based access control system
- **NEW**: Attestation verification for cross-chain operations
- **IMPROVED**: Better error handling with custom errors
- **IMPROVED**: Comprehensive event system
- **IMPROVED**: Backwards compatibility layer for v2 migration

### v0.0.5 (Legacy)

- Switchboard v2 architecture
- Modular interface system
- Basic oracle functionality