Switchboard Solidity SDK v1.0.0

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

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

// 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

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:

   // 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:

   // 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

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

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
• API Reference
• Migration Guide
• Examples

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

• Documentation: docs.switchboard.xyz
• Discord: Join our community
• GitHub Issues: Report bugs or request features
• Security: [email protected]

🔄 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