Onyx, also referred to as the XCN Ledger, is a highly scalable Layer 3 blockchain network that is architected for performance, security, and cost efficiency. It is deployed using the Arbitrum Orbit stack and benefits from the robust security foundation of Coinbase’s Base Layer 2 blockchain. This unique architecture enables Onyx to inherit the modular scalability of Arbitrum while maintaining the security assurances provided by Base, offering an optimized environment for developers building next-generation decentralized applications (dApps).

Onyx is fully Ethereum Virtual Machine (EVM) compatible, allowing seamless deployment of smart contracts and interoperability with existing Ethereum-based applications and tooling. Developers can build and deploy decentralized finance (DeFi) protocols, payment solutions, governance frameworks, and other blockchain-based services while leveraging Onyx’s high throughput and low transaction costs.

With an institutional-grade infrastructure, Onyx is designed to support large-scale applications and enterprise adoption, ensuring high availability, robust security mechanisms, and scalability optimizations.

The Onyx Documentation Hub is the central resource for institutions and developers looking to build, integrate, and leverage the full potential of Onyx This comprehensive documentation provides in-depth technical details, architecture specifications, and implementation guidelines for developers aiming to utilize Onyx’s blockchain infrastructure efficiently.

Beyond just technical references, this hub serves as a developer-centric knowledge base, offering code samples, API references, SDK integration guides, and best practices for optimizing smart contract deployments and blockchain interactions. Whether you are designing custom dApps, implementing scalable payment systems, or integrating Onyx into multi-chain architectures, the documentation provides a structured approach to understanding transaction finality, network security, gas optimizations, and governance mechanisms within the Onyx ecosystem.

By leveraging the resources provided, institutions and developers can streamline development workflows, enhance security practices, and maximize the performance of their blockchain-based applications on Onyx.

Quick Start Below:

How to Run a Full Node for Onyx

This guide provides step-by-step instructions for running an Onyx node on your local machine.

Prerequisites

Latest Docker Image

offchainlabs/nitro-node:v3.4.0-d896e9c

Minimum Hardware Configuration

• RAM: 8-16 GB

• CPU: 2-4 core CPU (For AWS: t3 xLarge)

• Storage: 50GB

Required Parameters

1. Parent Chain Parameters

The parent-chain argument must provide a standard RPC endpoint for an EVM node, either self-hosted or obtained from a node service provider:

Note: Public Arbitrum RPC endpoints have rate limits. To avoid bottlenecks, consider running a local node for the parent chain or using third-party RPC providers.

2. Child Chain Parameters

The child chain in an Arbitrum Orbit context is an L2 or an L3 Orbit chain. The required parameters are:

1. chain.info-json

This parameter contains necessary information about the Orbit chain:

--chain.info-json=<Orbit Chain's chain info>

An example JSON format is provided in the next section.

2. chain.name

This mandatory flag must match the chain name specified in --chain.info-json:

3. execution.forwarding-target

If running a regular full node (not a sequencer), set this flag:

4. AnyTrust Chains

For AnyTrust chains, additional flags are required:

Additionally, specify either:

Or:

Important Ports

For RPC/websocket protocol, enable the required ports using:

Putting It All Together

When running a Docker image, mount an external volume to persist the database across restarts. The mount point inside the Docker image should be:

/home/user/.arbitrum

Example Command:

Important: Ensure /some/local/dir/arbitrum exists before running the command to avoid permission issues.

Example --chain.info-json Format:

Graceful Shutdown

Ensure a graceful shutdown to save the current state:

Sequencer Feed

Nitro nodes can receive real-time ordered transactions from the sequencer feed. If the feed input URL is not set, the node will listen to the parent chain's inbox contract, which may prevent synchronization with the latest state.

Enable Sequencer Feed Synchronization

For chain owners, ensure the sequencer is configured with:

Optional Parameters

For a full list of parameters, use:

--help

Quickstart: Building a Decentralized Application (dApp) on Onyx (Solidity)

Introduction

This guide is designed for web developers seeking to build decentralized applications (dApps) on Onyx. No prior knowledge of Ethereum, Onyx, or Solidity is required, but a basic understanding of JavaScript and Yarn is expected. If you are new to Ethereum, it may be beneficial to review the Ethereum documentation before proceeding.

Learning Objectives

In this tutorial, developers will learn:

• The differences between Ethereum’s decentralized architecture and traditional client-server models.

• The fundamentals of Solidity smart contracts.

• How to compile and deploy a smart contract on Onyx.

• The functionality of an Ethereum-compatible Web3 wallet.

To demonstrate these concepts, we will create a decentralized token dispenser using Solidity smart contracts. This dispenser will operate under the following constraints:

1. A user can receive a token only if they have not received one recently.

2. The contract rules are immutable and cannot be modified after deployment.

This guide will walk through transitioning from a centralized Web2 implementation to a decentralized Web3 version on Onyx.

Prerequisites

Before starting, ensure you have the following installed:

• VS Code (or any preferred IDE)

• A Web3-compatible wallet (e.g., MetaMask)

• Yarn

• Foundry (for smart contract development)

• Remix (for contract compilation and testing)

Additional dependencies will be introduced throughout the guide.

Overview of Ethereum and Onyx

Ethereum

Ethereum is a decentralized network that maintains a shared blockchain ledger across a global network of nodes. Smart contracts execute within the Ethereum Virtual Machine (EVM) and facilitate trustless, programmable transactions.

Key features include:

• Smart contracts: Self-executing programs that enforce business logic.

• Decentralized identity and data portability: Users retain control over their assets and identities.

• Transaction fees: Users pay gas fees in ETH to incentivize network validators.

However, Ethereum transactions can become costly during high network congestion, necessitating scaling solutions such as Onyx.

Onyx

Onyx is an advanced Layer 3 blockchain built using Arbitrum Orbit and secured by Coinbase’s Base Layer 2. It provides developers with:

• EVM compatibility, enabling Solidity smart contracts to run seamlessly.

• Higher transaction throughput and lower fees compared to Ethereum.

• Optimistic rollup technology for efficient data processing.

Transitioning from a Web2 to a Web3 Application

A conventional Web2 application relies on centralized servers, leading to risks such as downtime, censorship, and security vulnerabilities. By migrating to Web3, smart contract logic is executed on the Onyx blockchain, ensuring:

• Immutable business logic

• Decentralized data storage

• Trustless interactions between users

Example: Token Dispenser Implementation

We will first examine a JavaScript-based token dispenser and then implement its Web3 equivalent using Solidity.

Web2 Implementation:

class TokenDispenser {
  constructor() {
    this.users = {};
  }
  requestToken(user) {
    if (!this.users[user] || this._canReceive(user)) {
      this.users[user] = Date.now();
      return 'Token Granted';
    }
    return 'Token Request Denied';
  }
  _canReceive(user) {
    return Date.now() - this.users[user] > 86400000;
  }
}
Web3 Implementation (Solidity):
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;


contract TokenDispenser {
    mapping(address => uint256) public lastRequest;
    uint256 public cooldown = 1 days;
    
    function requestToken() public returns (bool) {
        require(block.timestamp - lastRequest[msg.sender] > cooldown, "Cooldown period active");
        lastRequest[msg.sender] = block.timestamp;
        return true;
    }
}
 

Compiling and Deploying the Smart Contract

Smart contracts need to be compiled into bytecode before they can be deployed on-chain. We will use Remix, a browser-based IDE, for this step.

2. Create a new workspace.

3. Copy the Solidity contract into a new file.

4. Compile the contract in Remix.

5. Deploy the contract using a local Ethereum test network.

This section provides essential technical details regarding Onyx’s publicly available Remote Procedure Call (RPC) endpoints, allowing developers to interact with the Onyx blockchain network. These RPC endpoints facilitate smart contract deployments, transaction broadcasting, data querying, and state synchronization with the Onyx blockchain. Developers and infrastructure providers can integrate these endpoints into their applications, wallets, or blockchain indexing services to ensure seamless interaction with the Onyx network.

Public RPC Endpoints

Onyx provides both HTTPS and WebSocket (WSS) RPC endpoints, enabling developers to connect to the network for executing transactions and retrieving blockchain state data. The WebSocket endpoint is particularly useful for applications requiring real-time event subscriptions, such as monitoring contract events or transaction confirmations. The available endpoints are:

Additional Network Resources

To enhance blockchain interaction and facilitate development on Onyx, the following key resources are available:

Network Parameters

Below are the specific network parameters for Onyx:

The following smart contract addresses are integral to the Onyx blockchain infrastructure. These addresses correspond to core protocol contracts and token bridge contracts, which facilitate transaction processing, cross-chain interoperability, and protocol governance. Developers building on Onyx should reference these addresses for contract interactions, cross-chain asset transfers, and network-specific implementations.

Layer 1 Governance & Staking

The smart contracts for Onyx Governance and Onyx Staking are below:

Layer 3 Core Protocol Contracts

The core smart contracts of Onyx define the network’s fundamental operations, including transaction finalization, message passing, and state synchronization.

Token Bridge Contracts

The Token Bridge Contracts enable seamless asset transfers between Onyx and external networks. These contracts are responsible for asset locking, minting, and validation in both Layer 2 (L2) and Layer 3 (L3) environments.

L2 Token Bridge Contracts:

L3 Token Bridge Contracts

Essential Development Tools for Onyx dApp Development

Developing and testing decentralized applications (dApps) on Onyx requires a robust set of tools. Below is an overview of essential development environments, testing frameworks, and SDKs that streamline the process of building, deploying, and debugging smart contracts on the Onyx blockchain.

Hardhat

Hardhat is a comprehensive development environment tailored for Ethereum, Onyx, and other EVM-compatible networks. It simplifies the creation, compilation, deployment, testing, and debugging of smart contracts while providing an extensible framework.

Key Features:

• Built-in console for interactive debugging.

• Advanced Solidity debugging capabilities with stack traces and error messages.

• Task automation for streamlined workflows.

• Plugin support to integrate additional tooling and extend functionalities.

• Network management features for both local and remote deployment environments.

Hardhat is widely adopted for its flexibility and is an excellent choice for Onyx developers looking to manage complex projects efficiently.

Foundry

Foundry is a high-performance, portable, and modular toolkit built for EVM smart contract development, leveraging the Rust programming language. It is optimized for efficiency, flexibility, and seamless testing.

Key Features:

• Solidity-first development experience, with support for fast unit and integration testing.

• High-performance execution, reducing compilation and test runtimes.

• Local Ethereum node for rapid testing.

• Solidity REPL (Read-Eval-Print Loop) for interactive debugging and rapid contract iterations.

• CLI tools for deployment, transaction simulations, and calldata analysis.

Foundry’s lightweight and modular nature makes it a powerful alternative to Hardhat for Onyx developers who require high-speed smart contract interactions.

Truffle

Truffle is a full-fledged development framework for smart contract creation, offering an end-to-end solution for building, testing, debugging, and deploying contracts on Ethereum, Onyx, and other EVM-compatible networks.

Key Features:

• Integrated smart contract compilation and testing with a structured project setup.

• Advanced debugging tools, providing better insights into contract execution.

• Ganache support for local blockchain simulation and quick contract testing.

• Consensys Diligence integration to ensure smart contract security.

• VS Code extension for a developer-friendly experience.

Truffle’s rich ecosystem and developer tooling make it a great choice for teams building scalable and production-ready dApps on Onyx.

thirdweb

thirdweb provides a comprehensive SDK that covers all aspects of web3 development, enabling Onyx developers to build, deploy, and interact with smart contracts effortlessly.

Key Features:

• Blockchain connectivity: Simplifies interaction with the Onyx blockchain.

• Wallet authentication and management: Built-in UI components for seamless user interactions.

• Decentralized storage: Native support for IPFS with pinning services.

• Gasless transactions: Simplifies onboarding for users by abstracting transaction costs.

• Multi-chain compatibility: Supports cross-chain interactions for dApps targeting multiple EVM networks.

thirdweb is ideal for developers looking for an out-of-the-box infrastructure to quickly launch dApps on Onyx with minimal blockchain-specific overhead.

Brownie

Brownie is a Python-based smart contract framework designed for EVM-compatible blockchains, including Onyx.

Key Features:

• Full support for Solidity and Vyper smart contract development.

• pytest integration for automated and property-based contract testing.

• Trace-based coverage evaluation, helping developers optimize contract execution.

• Powerful debugging tools: Provides Python-style tracebacks and error message customization.

• Hypothesis-based stateful testing, ensuring higher contract reliability.

For Python developers, Brownie is an excellent choice to integrate traditional software development methodologies into Onyx smart contract development.

Choosing the Right Tool for Your Onyx dApp

Each tool offers unique advantages, and the choice depends on your development workflow:

• Hardhat: Best for complex EVM projects requiring deep debugging and plugin support.

• Foundry: Ideal for performance-focused developers seeking high-speed testing and modular tooling.

• Truffle: Suitable for teams that prefer an integrated framework with rich testing and security features.

• thirdweb: Perfect for fast deployments and web3 application development.

• Brownie: Best for Python-based smart contract development and in-depth contract analysis.

By leveraging these tools, Onyx developers can build efficient, secure, and scalable decentralized applications while maintaining seamless blockchain interactions.

The Onyx SDK is a powerful TypeScript library that facilitates seamless interaction with Onyx networks. It provides robust tools for bridging assets, passing messages across networks, and interfacing with smart contracts through an intuitive and developer-friendly API.

Key Features

• Token Bridging: Effortlessly transfer assets between Base and Onyx.

• Message Passing: Enable cross-chain communication.

• Contracts Interface: Utilize strongly-typed methods for smart contract interaction.

This guide provides an overview of the Onyx SDK functionality. Refer to the tutorials for more examples and in-depth explanations. [UNDER CONSTRUCTION]

The Onyx Governor, also known as the Chain Governor, serves as the governance module of Onyx, enabling a decentralized, on-chain decision-making process that ensures protocol upgrades, parameter adjustments, and policy implementations are collectively determined by the Onyx community. This governance framework is designed to provide transparency, security, and adaptability, allowing token holders to actively participate in the protocol's evolution while maintaining the integrity of its decentralized architecture.

Governance Proposal Requirements

• Governance proposals can only be initiated by addresses that hold more than 100,000,000 XCN tokens at the time of submission. This requirement ensures that only stakeholders with a significant vested interest in the protocol can propose changes, thereby maintaining governance integrity and preventing frivolous proposals.

• The governance system determines voting eligibility based on the voting weight at the proposal's initiation, which is retrieved using the getPriorVotes function. This function ensures that only those who held sufficient XCN before the proposal’s introduction can participate in the voting process, preventing manipulation by acquiring tokens post-proposal.

Voting and Decision-Making Process

1. Proposal Submission: A qualifying address submits a proposal detailing the intended changes, including smart contract modifications, governance parameter adjustments, or new integrations.

2. Voting Period: Once submitted, the proposal enters a mandatory 3-day voting period, during which all eligible token holders can cast their votes.

3. Vote Calculation and Quorum:

• A proposal requires a majority of affirmative votes to pass.

• It must accumulate a minimum of 200,000,000 votes in favor to be considered for execution.

• Votes are weighted based on XCN holdings, ensuring equitable representation of stakeholder interests.

1. Proposal Queueing: If the required quorum is met and the proposal is approved, it is automatically added to the Timelock contract, a governance safeguard mechanism that enforces a delay before execution.

2. Implementation Delay and Execution:

• Approved proposals remain in the Timelock for a mandatory 2-day delay before they can be executed.

• This delay provides a safeguard period for security audits, community scrutiny, and, if necessary, reconsideration or intervention by stakeholders.

• After the delay expires, the proposal can be executed, finalizing the governance decision and implementing the changes on-chain.

This guide is intended for developers and users seeking to understand gas calculations on Onyx, including how gas fees are determined and estimated before submitting transactions. This document provides a detailed breakdown of Onyx's gas estimation methods, practical ways to calculate fees, and code examples for implementation.

Practical Gas Estimation on Onyx

For most practical applications, gas estimation can be done via a standard process by calling an Onyx node’s eth_estimateGas method. This method provides a gas limit that should sufficiently cover the entire transaction fee at the given L2 gas price.

Basic Gas Calculation

To determine the transaction fee, multiply the gas limit by the current L2 gas price:

Transaction Fees = Gas Limit × L2 Gas Price

Since Onyx leverages L3 technology with an Arbitrum Orbit stack, gas estimates can fluctuate based on L1 calldata pricing. The eth_estimateGas result may change over time as the L1 calldata cost varies.

To obtain a more precise gas limit, developers can use the NodeInterface.gasEstimateComponents() method:

• Retrieve the gasEstimate (total estimated gas required).

• Multiply by the baseFee (third returned value) to get total cost.

For transactions that involve L1 to L3 messages (retryable tickets), the recommended approach is to use:

• Onyx SDK: L1ToL3MessageGasEstimator.estimateAll()

• NodeInterface API: estimateRetryableTicket()

These methods return complete gas estimations, ensuring sufficient fees are allocated for successful execution.

Detailed Breakdown of Gas Calculation Formula

Onyx transaction fees are calculated as:

TXFEES = L2 Gas Price (P) × Gas Limit (G)

The Gas Limit (G) consists of:

Gas Limit (G) = Gas used on L2 (L2G) + Extra Buffer for L1 cost (B)

Where the buffer (B) accounts for L1 calldata posting costs, computed as:

L1 Estimated Cost (L1C) = L1 price per byte (L1P) × Data size in bytes (L1S)

The buffer is then determined by:

Extra Buffer (B) = L1C / L2 Gas Price (P)

Thus, the final transaction fee formula is:

TXFEES = P × (L2G + ((L1P × L1S) / P))

Obtaining the Required Variables

To retrieve these values, developers should use the NodeInterface API:

• L2 Gas Price (P): Call NodeInterface.GasEstimateComponents() and retrieve baseFee (third result).

• Gas Used on L2 (L2G): Subtract gasEstimateForL1 (second result) from gasEstimate (first result).

• L1 Price per Byte (L1P): Retrieve l1BaseFeeEstimate (fourth result) and multiply by 16.

• L1 Data Size (L1S): Compute using gasEstimateForL1 × P / L1P.

Alternatively, calling NodeInterface.gasEstimateL1Component() provides l1BaseFeeEstimate and gasEstimateForL1 directly.

Code Example: Estimating Gas in JavaScript

Below is an implementation example using Onyx’s SDK and NodeInterface API.

const { NodeInterface__factory } = require("@onyx/sdk/dist/lib/abi/factories/NodeInterface__factory");
const { NODE_INTERFACE_ADDRESS } = require("@onyx/sdk/dist/lib/dataEntities/constants");

const nodeInterface = NodeInterface__factory.connect(NODE_INTERFACE_ADDRESS, baseL2Provider);

const gasEstimateComponents = await nodeInterface.callStatic.gasEstimateComponents(
  destinationAddress,
  false,
  txData,
  { blockTag: 'latest' }
);

const l1GasEstimated = gasEstimateComponents.gasEstimateForL1;
const l2GasUsed = gasEstimateComponents.gasEstimate.sub(gasEstimateComponents.gasEstimateForL1);
const l2EstimatedPrice = gasEstimateComponents.baseFee;
const l1EstimatedPrice = gasEstimateComponents.l1BaseFeeEstimate.mul(16);

const l1Cost = l1GasEstimated.mul(l2EstimatedPrice);
const l1Size = l1Cost.div(l1EstimatedPrice);

const P = l2EstimatedPrice;
const L2G = l2GasUsed;
const L1P = l1EstimatedPrice;
const L1S = l1Size;

const L1C = L1P.mul(L1S);
const B = L1C.div(P);
const G = L2G.add(B);
const TXFEES = P.mul(G);

Final Notes

Gas estimations using these techniques are approximate and may differ slightly in practice. Developers should set appropriate expectations with users regarding potential variations in gas costs.

For further implementation details, refer to Onyx’s official SDK documentation and gas estimation tutorials.

The Onyx Governor follows a structured governance model that balances decentralization with security and efficiency. The Timelock contract prevents sudden, unauthorized modifications to the protocol, ensuring all decisions undergo rigorous scrutiny before being enacted. Additionally, the on-chain governance mechanism provides an immutable and transparent record of all proposals, votes, and implementations, reinforcing accountability and trust within the community.

By leveraging Ethereum-based smart contract governance, the Onyx Governor facilitates an efficient and transparent decision-making process that aligns with the interests of long-term stakeholders, ultimately promoting protocol sustainability and robust security standards.

Web3 Libraries and Tools for Onyx Development

Developers building on Onyx, an EVM-compatible Layer 3 blockchain, can leverage various libraries and SDKs to interact with smart contracts, manage wallets, and streamline blockchain development. Below is a list of essential frameworks for Web3 development on Onyx.

Essential Web3 Libraries and Tools

Expanding the Toolset

If you know of additional Web3 tools that would enhance Onyx development, please contribute by submitting suggestions via GitHub Issues

Debugging Tools for Onyx dApp Development

Efficient debugging is essential for Onyx developers to ensure the reliability and security of smart contracts. The following tool provides powerful debugging capabilities for smart contract development and testing.

Tenderly

Tenderly is a comprehensive Web3 development platform that supports smart contract development, testing, monitoring, and debugging. It enables developers to analyze precise lines of code in a human-readable format, making it easier to identify and resolve issues.

Key Features:

• Tenderly Debugger: Provides detailed analysis of smart contract execution, allowing developers to inspect transactions at a granular level.

• Transaction Simulator: Enables replaying historical transactions and simulating current transaction outcomes before sending them on-chain.

• Real-time Monitoring: Detects anomalies and unexpected behavior in smart contract execution.

• Error Handling & Analysis: Streamlines the debugging process by providing insights into state changes, gas usage, and execution paths.

While Tenderly is highly effective, debugging L1-to-L2 messages (Retryable Tickets) has certain limitations due to custom Geth errors. Developers should refer to Onyx documentation for specific debugging guidance regarding cross-layer transactions.

Contributing & Additional Debugging Tools

If you know of additional debugging tools that would enhance Onyx development, consider submitting suggestions via GitHub Issues.

The proposal threshold represents the minimum number of votes required for an account to create and submit a governance proposal within the Onyx governance framework. This requirement ensures that only stakeholders with a significant vested interest in the protocol can initiate changes, preventing spam or frivolous proposals.

Function Implementation in CHNGovernance

In the CHNGovernance contract, the proposalThreshold() function is implemented to enforce the required voting power threshold before a proposal can be submitted.

Function Signature

RETURN: This function returns an unsigned integer (uint) representing the minimum number of votes required for an account to be eligible to create a proposal.

Example Solidity Implementation

To retrieve the proposal threshold in a Solidity environment, the proposalThreshold()function can be called using an instance of the CHNGovernance contract.

Web3.js Implementation (v1.2.6)

For interacting with the CHNGovernance contract using Web3.js, the following example demonstrates how to retrieve the proposal threshold:

Technical Considerations

• The proposalThreshold()function is a view function, meaning it does not modify blockchain state and can be executed without incurring gas costs.

• The required proposal threshold may be modified through governance proposals, allowing the community to adjust the threshold based on network dynamics and participation levels.

• The retrieved threshold value should be used to validate off-chain governance tracking systems and frontend governance dashboards, ensuring real-time compliance with protocol governance rules.

The proposal threshold is a critical governance parameter that maintains the integrity of the Onyx governance process by ensuring that proposals originate from accounts with meaningful voting power, thereby upholding decentralization and effective protocol management.

The quorum votes represent the minimum number of affirmative votes required for a proposal to be successfully executed within the Onyx governance framework. This threshold is critical in ensuring that governance decisions reflect a sufficient level of participation from the voting community and are not subject to manipulation by a small number of token holders.

Implementation in CHNGovernance

To enforce this quorum requirement, the CHNGovernance contract implements the quorumVotes() function, which returns the predefined vote threshold necessary for a proposal to pass.

Signature:

RETURN: The function returns an unsigned integer (uint) representing the minimum number of votes required for a proposal to achieve quorum and be successfully executed.

Example Solidity Implementation

In Solidity, the quorumVotes() function can be invoked using the CHNGovernance contract instance, ensuring that governance mechanisms adhere to the required voting thresholds.

Web3.js Implementation (v1.2.6)

For interacting with the CHNGovernance contract using Web3.js, the following example demonstrates how to retrieve the quorum vote requirement:

Technical Considerations

• The quorumVotes() function is a pure function, meaning it does not modify blockchain state and can be executed without incurring gas costs.

• The required quorum threshold may be subject to governance modifications, meaning that in future iterations of the protocol, proposals may be introduced to dynamically adjust the quorum requirement based on network participation levels.

• The retrieved quorum value should be used to validate voting participation in any off-chain governance tracking systems or frontend governance dashboards, ensuring real-time compliance with protocol governance rules.

The quorum vote requirement ensures that governance actions reflect a collective decision of the Onyx community, thereby enhancing decentralization and security within the Onyx governance ecosystem.

The proposal max operations parameter defines the maximum number of executable actions that can be included in a single governance proposal within the Onyx governance framework. Each action represents a function call that will be executed if the proposal is approved and successfully implemented. This limitation ensures governance proposals remain manageable and do not introduce excessive complexity or execution risks.

Function Implementation in CHNGovernance

In the CHNGovernance contract, the proposalMaxOperations() function is implemented to enforce this restriction, defining the upper limit of actions within a proposal.

Function Signature

function proposalMaxOperations() public pure returns (uint)

RETURN: The function returns an unsigned integer (uint) representing the maximum number of actions that can be included in a governance proposal.

Example Solidity Implementation

To retrieve the maximum allowed operations in a proposal, the proposalMaxOperations() function can be called using an instance of the CHNGovernance contract.

CHNGovernance gov = CHNGovernance(0x123...); // Contract address of CHNGovernance
uint operations = gov.proposalMaxOperations();

Web3.js Implementation (v1.2.6)

For interacting with the CHNGovernance contract using Web3.js, the following example demonstrates how to retrieve the proposal max operations:

const operations = await gov.methods.proposalMaxOperations().call();

Technical Considerations

• The proposalMaxOperations() function is a pure function, meaning it does not modify blockchain state and can be executed without incurring gas costs.

• The maximum operations limit ensures that proposals do not become too large, which could lead to execution failures due to block gas limits or computational overhead.

• This parameter may be adjusted through governance proposals, allowing the community to refine the limit based on network requirements and governance efficiency.

• The retrieved value should be used to validate governance dashboards, governance UI interfaces, and off-chain governance tools to ensure proposals adhere to network constraints.

By enforcing a maximum number of actions per proposal, the Onyx governance system ensures that governance remains structured, efficient, and executable without excessive computational or security risks.

The voting delay represents the number of Ethereum blocks that must elapse before voting can begin on a newly created proposal. This delay is added to the current block number at the time of proposal creation and serves as a buffer period, allowing stakeholders to become aware of the proposal before voting starts.

Function Implementation in CHNGovernance

In the CHNGovernance contract, the votingDelay() function is implemented to enforce this rule, ensuring that there is a defined waiting period before a proposal is open for voting.

Function Signature

function votingDelay() public view returns (uint)

RETURN: The function returns an unsigned integer (uint) representing the number of Ethereum blocks that must pass before voting on a proposal can commence.

Example Solidity Implementation

To retrieve the voting delay in a Solidity environment, the votingDelay() function can be called using an instance of the CHNGovernance contract.

CHNGovernance gov = CHNGovernance(0x123...); // Contract address of CHNGovernance
uint blocks = gov.votingDelay();

Web3.js Implementation (v1.2.6)

For interacting with the CHNGovernance contract using Web3.js, the following example demonstrates how to retrieve the voting delay:

const blocks = await gov.methods.votingDelay().call();

Technical Considerations

• The votingDelay() function is a view function, meaning it does not modify blockchain state and can be executed without incurring gas costs.

• The voting delay period is intended to give token holders time to review and analyze proposals before casting their votes, increasing informed participation in governance.

• This parameter may be adjusted through governance proposals, allowing the community to dynamically modify the delay based on governance needs and activity levels.

• The retrieved value should be used by governance dashboards, off-chain governance tracking tools, and front-end governance interfaces to ensure accurate voting timelines are displayed.

The voting period defines the duration for which a governance proposal remains open for voting, measured in Ethereum blocks. During this period, eligible token holders can cast their votes to either support or reject the proposal. Once the voting period ends, the results determine whether the proposal advances to execution or is dismissed.

Function Implementation in CHNGovernance

In the CHNGovernance contract, the votingPeriod() function establishes the length of time a proposal remains open for voting.

Function Signature

function votingPeriod() public view returns (uint)

RETURN: The function returns an unsigned integer (uint) representing the number of Ethereum blocks during which voting is active for a given proposal.

Example Solidity Implementation

To retrieve the voting period in a Solidity environment, the votingPeriod() function can be called using an instance of the CHNGovernance contract.

CHNGovernance gov = CHNGovernance(0x123...); // Contract address of CHNGovernance
uint blocks = gov.votingPeriod();

Web3.js Implementation (v1.2.6)

For interacting with the CHNGovernance contract using Web3.js, the following example demonstrates how to retrieve the voting period:

const blocks = await gov.methods.votingPeriod().call();

Technical Considerations

• The votingPeriod() function is a view function, meaning it does not modify blockchain state and can be executed without incurring gas costs.

• The duration of the voting period impacts governance participation, allowing stakeholders ample time to review proposals and cast votes.

• This parameter may be adjusted through governance proposals, ensuring adaptability as governance activity and network participation evolve.

• The retrieved value should be used by governance dashboards, off-chain governance tracking tools, and front-end governance interfaces to display accurate voting timelines.

The propose function allows eligible stakeholders to create governance proposals that can introduce changes to Onyx. Proposals may include modifications to the staking interest rate model, risk parameters within the protocol, or other governance-directed alterations to protocol parameters.

Once a proposal is submitted, it enters the voting phase, where token holders can vote for or against the proposed changes. If the proposal meets the required quorum and is approved, it is queued and executed via the Onyx Timelock contract after the predefined waiting period.

Proposal Submission Requirements

• The proposer must hold more XCN than the current proposal threshold (proposalThreshold()) as of the immediately preceding block.

• The proposer cannot create a new proposal if they already have an active or pending proposal.

• Due to Timelock restrictions, a proposal cannot contain duplicate actions within the same block.

• Identical actions across different proposals must be queued in separate blocks to avoid execution conflicts.

Function Implementation in CHNGovernance

Function Signature:

function propose(
address[] memory targets,
    uint[] memory values,
    string[] memory signatures,
    bytes[] memory calldatas,
    string memory description
) public returns (uint)

Parameters

• targets: An ordered array of target addresses for function calls that will be executed upon proposal approval.

• values: An ordered array of values (i.e., msg.value) to be passed to the respective function calls. This array must match the length of all other array parameters.

• signatures: An ordered array containing function signatures that will be executed as part of the proposal.

• calldatas: An ordered array of encoded data passed to each function call during execution.

• description: A human-readable description outlining the proposal and the intended protocol changes.

• RETURN: The function returns a proposalId, which uniquely identifies the newly created governance proposal.

Example Solidity Implementation

To submit a proposal using Solidity, the propose() function can be called from an instance of the CHNGovernance contract:

CHNGovernance gov = CHNGovernance(0x123...); // Contract address of CHNGovernance
uint proposalId = gov.propose(targets, values, signatures, calldatas, description);

Web3.js Implementation (v1.2.6)

For interacting with the CHNGovernance contract using Web3.js, the following example demonstrates how to submit a proposal:

const tx = await gov.methods.propose(targets, values, signatures, calldatas, description).send({ from: proposerAddress });

Technical Considerations

• The propose function is state-modifying and will incur gas costs.

• The proposal threshold may be subject to governance modifications, dynamically altering the eligibility criteria.

• The proposal queueing mechanism ensures execution order integrity and prevents conflicting transactions.

• The retrieved proposal ID is essential for tracking governance actions and monitoring proposal progress.

• Security best practices should be followed to ensure valid function calls and prevent unintended contract interactions.

By enforcing structured proposal submission requirements and leveraging the Onyx Timelock, the Onyx governance system ensures that protocol changes are implemented in a transparent, decentralized, and secure manner.

The queue function is responsible for moving a successful proposal into the Onyx Timelock queue. Once a proposal has been approved by the governance process, it must be queued before it can be executed. Only proposals that have met the required voting threshold and have been successfully passed can be queued.

Function Implementation in CHNGovernance

In the CHNGovernance contract, the queue() function ensures that only validated proposals are added to the Timelock queue, preventing unauthorized executions.

Function Signature

function queue(uint proposalId) public

Parameters

• proposalId: The unique identifier of the governance proposal that has been successfully approved and is eligible to be queued.

• RETURN: The function does not return a value. If the proposal is invalid or not yet approved, it will revert with an error.

Example Solidity Implementation

To queue a proposal using Solidity, the queue()function can be called from an instance of the CHNGovernance contract:

CHNGovernance gov = CHNGovernance(0x123...); // Contract address of CHNGovernance
gov.queue(proposalId);

Web3.js Implementation (v1.2.6)

For interacting with the CHNGovernance contract using Web3.js, the following example demonstrates how to queue a proposal:

const tx = await gov.methods.queue(proposalId).send({ from: sender });

Technical Considerations

• The queue() function is state-modifying and will incur gas costs.

• A proposal must have succeeded in the voting phase before it can be queued.

• Once queued, the proposal must wait for the Timelock period before execution can occur.

• The Timelock contract ensures security and decentralization by preventing immediate execution after voting.

• If an attempt is made to queue a proposal that has not succeeded, the transaction will revert with an error.

The execute function is responsible for applying changes from a successfully approved and queued proposal to the designated target contracts within the Onyx protocol. Once a proposal has passed the governance process and completed the Timelock delay period, it can be executed, implementing the proposed modifications.

Function Implementation in CHNGovernance

The execute() function ensures that only successful and properly queued proposals can be executed, enforcing governance integrity and protocol security.

Function Signature

function execute(uint proposalId) public payable returns (uint)

Parameters

• proposalId: The unique identifier of the proposal to be executed. This proposal must have successfully passed governance voting, been queued, and completed the Timelock delay period.

• RETURN: The function does not return a value. If execution fails due to an invalid or non-queued proposal, it will revert with an error.

Example Solidity Implementation

To execute a proposal using Solidity, the execute()function can be called from an instance of the CHNGovernance contract:

CHNGovernance gov = CHNGovernance(0x123...); // Contract address of CHNGovernance
gov.execute(proposalId).value(999).gas(999)();

Web3.js Implementation (v1.2.6)

For interacting with the CHNGovernance contract using Web3.js, the following example demonstrates how to execute a proposal:

const tx = await gov.methods.execute(proposalId).send({ from: sender, value: 1 });

Technical Considerations

• The execute() function is state-modifying and will incur gas costs.

• A proposal must have been successfully queued and completed the Timelock delay period before it can be executed.

• The function is payable, allowing the Timelock to invoke functions that require ETH transfers.

• If an attempt is made to execute an invalid, unqueued, or pending proposal, the transaction will revert with an error.

• The Timelock contract ensures security and decentralization, preventing immediate execution after proposal approval.

The getReceipt function retrieves the ballot receipt for a specific voter in relation to a particular governance proposal. This function enables governance participants and developers to track and verify voting activity, ensuring transparency in the decision-making process.

Function Implementation in CHNGovernance

The getReceipt() function is implemented in the CHNGovernance contract to return structured voting details for a given voter’s participation in a proposal.

Function Signature

function getReceipt(uint proposalId, address voter) public view returns (Receipt memory)

Parameters

• proposalId: The unique identifier of the governance proposal being queried.

• voter: The Ethereum address of the voter whose receipt is requested.

• RETURN: If the function call is successful, it returns a Receipt struct, containing:

  • hasVoted (bool): Indicates whether the voter has already cast a vote.

  • support (uint): Represents the type of vote cast (e.g., For, Against, Abstain).

  • votes (uint): The number of votes the voter allocated to the proposal.

If the proposal ID is invalid, or the voter has not participated, the function reverts with an error.

Example Solidity Implementation

To retrieve a voter's ballot receipt using Solidity, the getReceipt() function can be called from an instance of the CHNGovernance contract:

CHNGovernance gov = CHNGovernance(0x123...); // Contract address of CHNGovernance
Receipt memory ballot = gov.getReceipt(proposalId, voterAddress);

Web3.js Implementation (v1.2.6)

For interacting with the CHNGovernance contract using Web3.js, the following example demonstrates how to retrieve a voter's receipt:

const proposalId = 11;
const voterAddress = '0x123...';
const result = await gov.methods.getReceipt(proposalId, voterAddress).call();
const { hasVoted, support, votes } = result;

Technical Considerations

• The getReceipt() function is a view function, meaning it does not modify blockchain state and can be executed without incurring gas costs.

• If the voter has not participated in the proposal, the function may return a default empty receipt or revert with an error.

• This function is useful for governance dashboards, allowing stakeholders to track who voted, how they voted, and how many votes were cast.

• Governance analytics tools should integrate this function to provide real-time voting insights.

The getActions function retrieves the details of a specified proposal by providing its unique proposal ID. This function allows governance participants and developers to inspect the actions of a given proposal, including:

1. The contract addresses that the proposal intends to call.

2. The values (ETH amounts) associated with each call.

3. The function signatures that define which contract functions will be executed.

4. The calldata payloads that encode function arguments for execution.

This function enables transparent governance by allowing any participant to review a proposal’s execution details before casting votes or executing the proposal.

Function Implementation in CHNGovernance

The getActions() function is implemented in the CHNGovernance contract to return a structured breakdown of the proposal's execution plan.

Function Signature

function getActions(uint proposalId)
    public
    view
    returns (
        address[] memory targets,
        uint[] memory values,
        string[] memory signatures,
        bytes[] memory calldatas
    )

Parameters

• proposalId: The unique identifier of the proposal whose actions need to be retrieved.

• RETURN:If the function call is successful, it returns the following arrays:

1. targets[]: An array of contract addresses the proposal intends to interact with.

2. values[]: An array of unsigned integers specifying the ETH value associated with each action.

3. signatures[]: An array of function signatures that describe the functions to be executed.

4. calldatas[]: An array of calldata (encoded function arguments) that will be passed to each function call.

If the proposal ID is invalid, the function reverts with an error.

Example Solidity Implementation

To retrieve the details of a proposal using Solidity, the getActions() function can be called from an instance of the CHNGovernance contract:

CHNGovernance gov = CHNGovernance(0x123...); // Contract address of CHNGovernance
uint proposalId = 123;
(address[] memory targets, uint[] memory values, string[] memory signatures, bytes[] memory calldatas) = gov.getActions(proposalId);

Web3.js Implementation (v1.2.6)

For interacting with the CHNGovernance contract using Web3.js, the following example demonstrates how to retrieve the proposal actions:

const proposalId = 123;
const {0: targets, 1: values, 2: signatures, 3: calldatas} = await gov.methods.getActions(proposalId).call();

Technical Considerations

• The getActions() function is a view function, meaning it does not modify blockchain state and can be executed without incurring gas costs.

• This function is useful for off-chain governance interfaces, allowing participants to inspect proposals before voting.

• If a proposal ID is invalid, the function will revert, ensuring that only valid proposals are queried.

• Governance dashboards and analysis tools should utilize this function to display proposal details in an understandable format.

The cancel() function allows the Guardian or any eligible participant to cancel a governance proposal that has not yet been executed. This mechanism provides a safeguard against malicious or outdated proposals that no longer align with the protocol’s best interests.

A proposal can be canceled under the following conditions:

• If the Guardian invokes the cancel function, the proposal will be immediately revoked.

• If the proposer no longer holds the required delegated voting power (i.e., less than the proposal threshold), then any address may call cancel() to remove the proposal from governance consideration.

Function Implementation in CHNGovernance

The cancel() function ensures that only valid, unexecuted proposals can be removed, maintaining governance security and integrity.

Function Signature:

function cancel(uint proposalId) public

Parameters

• proposalId: The unique identifier of the governance proposal to be canceled. The proposal must not have been executed.

• RETURN: The function does not return a value. If the proposal is invalid, already executed, or unauthorized for cancellation, the transaction reverts with an error.

Example Solidity Implementation

To cancel a proposal using Solidity, the cancel() function can be called from an instance of the CHNGovernance contract:

CHNGovernance gov = CHNGovernance(0x123...); // Contract address of CHNGovernance
gov.cancel(proposalId);

Web3.js Implementation (v1.2.6)

For interacting with the CHNGovernance contract using Web3.js, the following example demonstrates how to cancel a proposal:

const tx = await gov.methods.cancel(proposalId).send({ from: sender });

Technical Considerations

• The cancel() function is state-modifying and will incur gas costs.

• The proposal must not have been executed for it to be eligible for cancellation.

• If the Guardian initiates cancellation, it is immediately effective.

• If the proposer loses their delegated voting power, any participant may call cancel() to remove the proposal.

• If an attempt is made to cancel an already executed proposal, the transaction will revert with an error.

• The Onyx governance framework ensures that cancellation actions are recorded transparently on-chain.

The castVote function allows an eligible voter to cast their approval or disapproval on a governance proposal. The voting power of an account is determined based on the number of votes delegated to it at the time the proposal transitioned into the Active state.

Function Implementation in CHNGovernance

The castVote() function ensures that only eligible voters can participate in governance decisions, maintaining the integrity of the Onyx governance system.

Function Signature

function castVote(uint proposalId, bool support) public

Parameters

• proposalId: The unique identifier of the governance proposal on which the vote is being cast.

• support: A boolean value indicating the vote choice:

  • true → Vote in favor of the proposal (Yes)

  • false → Vote against the proposal (No)

• RETURN: The function does not return a value. If the proposal ID is invalid or the voter is ineligible, the transaction reverts with an error.

Example Solidity Implementation

To cast a vote using Solidity, the castVote() function can be called from an instance of the CHNGovernance contract:

CHNGovernance gov = CHNGovernance(0x123...); // Contract address of CHNGovernance
gov.castVote(proposalId, true); // Voting in favor of the proposal

Web3.js Implementation (v1.2.6)

For interacting with the CHNGovernance contract using Web3.js, the following example demonstrates how to cast a vote:

const tx = await gov.methods.castVote(proposalId, false).send({ from: sender }); // Voting against the proposal

Technical Considerations

• The castVote() function is state-modifying and will incur gas costs.

• Votes are weighted based on the voting power at the moment the proposal became Active.

• If the voter has not been delegated voting power, they cannot cast a vote.

• Once a vote is cast, it cannot be changed unless the castVoteWithReason function (if available) is used.

• Proposal outcomes depend on the total votes cast before the voting period ends.

• Governance dashboards and vote tracking tools should integrate this function to allow real-time monitoring of voting activity.

The state function retrieves the current state of a specified governance proposal. The function returns an enumerated value representing one of the possible states defined in the CHNGovernance contract. This function allows governance participants to track the progress and outcome of any proposal.

Function Implementation in CHNGovernance

The state() function ensures that governance participants can query and verify the status of proposals, maintaining transparency in decision-making.

Function Signature

Parameters

• proposalId: The unique identifier of the proposal whose state is being queried.

• RETURN: If the function call is successful, it returns an enumerated type ProposalState, which may have one of the following values:

  • Pending: The proposal has been submitted and is awaiting the start of the voting period.

  • Active: The proposal is currently in the voting period.

  • Canceled: The proposal was canceled before execution.

  • Defeated: The proposal did not receive enough votes to pass.

  • Succeeded: The proposal was approved but has not yet been queued for execution.

  • Queued: The proposal is in the Timelock queue awaiting execution.

  • Expired: The proposal was approved but was not executed before the expiration period.

  • Executed: The proposal was successfully executed, and the proposed changes were applied.

Example Solidity Implementation

To retrieve the state of a proposal using Solidity, the state() function can be called from an instance of the CHNGovernance contract:

Web3.js Implementation (v1.2.6)

For interacting with the CHNGovernance contract using Web3.js, the following example demonstrates how to retrieve a proposal’s state:

Technical Considerations

• The state() function is a view function, meaning it does not modify blockchain state and can be executed without incurring gas costs.

• The proposal state helps governance participants track where a proposal stands in the decision-making process.

• Proposals that expire before execution need to be resubmitted if they are still relevant.

• This function is useful for governance dashboards, monitoring tools, and voting interfaces, providing real-time tracking of proposals.

• If a proposal ID is invalid, the function reverts with an error.

The Onyx Protocol operates under a decentralized governance framework, enabling XCN token holders to participate in protocol decision-making and upgrades. Governance is facilitated through four core smart contract components.

Core Components

• XCN Token – The governance token used for voting power and protocol participation.

• Staking Module – A mechanism that allows users to stake XCN, granting them voting weight proportional to their staked balance.

• Governance Module (Governor) – The primary contract responsible for processing governance proposals and vote execution.

• Timelock Contract – A security mechanism ensuring that approved proposals are subject to a mandatory delay before execution, allowing the community to react if necessary.

Together, these components enable a decentralized governance model where protocol modifications, parameter adjustments, and new asset integrations can be proposed, voted on, and executed through administrative functions within oToken contracts or the Comptroller contract.

Governance Process

Proposal Eligibility: To submit a governance proposal, an address must hold a minimum of 100,000,000 XCN in voting weight. Proposals consist of executable smart contract code, defining precise changes to the protocol, such as modifying interest rate models, listing new collateral assets, or adjusting risk parameters.

Voting and Approval: Once a proposal is submitted, a three-day (3-day) voting period is initiated. During this window, XCN holders can vote either for or against the proposal. A proposal is deemed successful if it receives:

• A majority vote in favor.

• A minimum of 200,000,000 XCN votes supporting it. Upon approval, the proposal is queued in the Timelock contract and becomes executable after a mandatory two-day (2-day) delay. This delay period allows the community to review the proposed changes before they are enacted on-chain.

Staking XCN for Governance Participation

To obtain voting rights, users must stake XCN tokens. The amount of XCN staked determines the voting weight of an address. Governance power is dynamically adjusted based on staking activity:

• Increasing stake grants additional voting weight.

• Withdrawing XCN from staking automatically reduces voting power.

This staking mechanism ensures that governance influence is directly proportional to active participation in securing and supporting the protocol.

This governance structure ensures that protocol decisions remain community-driven and subject to transparent, on-chain governance mechanisms.

Guardian

The Guardian Wallet within Onyx Governance serves as a critical safeguard against malicious proposals, ensuring that even if a proposal achieves the necessary vote weight through hostile or manipulative means, it can be canceled before execution. This wallet is controlled by a trusted security council or smart contract logic designed to detect governance attacks, preventing unauthorized or harmful protocol changes. The Guardian has the authority to nullify proposals that violate security policies, such as those attempting to transfer funds improperly, alter fundamental contract logic, or introduce vulnerabilities into the system. By integrating this failsafe mechanism, Onyx Governance maintains a robust security posture while still enabling decentralized decision-making.

The Guardian Wallet operates by continuously monitoring governance proposals and tracking vote behavior to identify anomalies, including vote concentration from potentially compromised accounts. If a proposal is flagged as malicious or harmful, the Guardian can intervene before the proposal progresses to execution within the Timelock contract. This feature ensures that the governance process remains resilient against coordinated attacks or governance takeovers. Additionally, the Guardian Wallet can be enhanced through onchain automation, further reducing the risk of unilateral actions while maintaining the integrity and trustworthiness of the Onyx Protocol's decentralized governance framework.

The Onyx Governance API provides programmatic access to governance data, proposal tracking, and voting details within the Onyx protocol. Developers and governance participants can use this API to fetch real-time governance data, submit transactions, and monitor proposal statuses.

The Governance API Base URL is: govapi.onyx.org

The Timelock contract is a governance-controlled smart contract that facilitates secure, time-delayed upgrades to system parameters, logic, and contracts within the Onyx protocol. This contract ensures that all governance actions are transparent and auditable, preventing instantaneous or unauthorized modifications.

Key Features

• Implements a time-delayed, opt-out upgrade pattern to enhance protocol security.

• Enforces a minimum delay before any governance action can be executed.

• Managed by the Onyx governance module, ensuring decentralized decision-making.

• Supports governance transparency through pending and completed action tracking on the Timelock Dashboard.

Minimum Delay Periods

• 2 Days: The absolute minimum delay before a proposed governance action can be executed. This ensures that all protocol participants have time to review proposed changes.

• 14 Days: Major protocol upgrades, such as risk system modifications, may require an extended delay to allow for extensive review and feedback.

Governance Control and Monitoring

• The Timelock contract is under the control of the governance module, meaning that only proposals approved through governance can be scheduled for execution.

• All pending and executed governance actions are publicly accessible via the Timelock Dashboard, ensuring full transparency and accountability.

• The contract follows a strict execution order, preventing unauthorized or out-of-sequence actions.

Security and Best Practices

• Governance participants should actively monitor the Timelock Dashboard to stay informed about pending protocol changes.

• Smart contract audits and community discussions should occur during the delay period to identify and mitigate potential risks.

• Critical protocol changes should have extended timelock delays to ensure proper review and consensus.

By enforcing structured and time-sensitive execution, the Onyx Timelock contract enhances security, decentralization, and trust within the protocol’s governance system.

Core API Endpoints

Fetch Governance Proposals

Retrieve a list of active and past governance proposals.

GET /proposals
Response:
[
  {
    "proposalId": 1,
    "title": "Update Risk Parameters",
    "state": "Active",
    "createdAt": "2024-02-05T12:00:00Z",
    "votesFor": 150000000,
    "votesAgainst": 50000000
  }
]

Get Proposal Details

Retrieve details of a specific proposal by proposalId.

GET /proposals/{proposalId}
Response:
{
  "proposalId": 1,
  "title": "Update Risk Parameters",
  "description": "Adjust risk parameters for oETH market.",
  "state": "Active",
  "votesFor": 150000000,
  "votesAgainst": 50000000,
  "quorum": 200000000,
  "timelockExpiration": "2024-02-07T12:00:00Z"
}

Cast a Vote

Submit a vote for a proposal.

POST /vote
Request Body:
{
  "proposalId": 1,
  "voter": "0x123456789abcdef",
  "support": true,
  "signature": "0xabcdef..."
}
Response:
{
  "status": "success",
  "message": "Vote successfully recorded."
}

Fetch Voter Receipts

Retrieve voting receipt details for a given proposalId and voter address.

GET /receipts/{proposalId}/{voter}
Response:
{
  "proposalId": 1,
  "voter": "0x123456789abcdef",
  "hasVoted": true,
  "support": true,
  "votes": 5000000
}

Get Proposal State

Retrieve the current state of a proposal.

GET /proposals/{proposalId}/state
Response:
{
  "proposalId": 1,
  "state": "Active"
}

Security Considerations

• Rate limits apply to prevent abuse of the API.

• Authentication may be required for certain endpoints, such as submitting votes.

• All API interactions should be performed using secure HTTPS connections.

The castVoteBySig function allows an offline signer to participate in Onyx governance voting by submitting a digitally signed vote. Unlike the castVote function, which requires the voter to be online and execute the transaction, this function enables voting via an EIP-712-compliant signature, making it useful for delegated and gasless voting.

Function Implementation in CHNGovernance

The castVoteBySig() function ensures that votes can be cast securely and efficiently using off-chain signatures, reducing the need for direct blockchain interaction while maintaining the integrity of the voting process.

Function Signature

function castVoteBySig(
    uint proposalId,
    bool support,
    uint8 v,
    bytes32 r,
    bytes32 s
) public

Parameters

• proposalId: The unique identifier of the governance proposal on which the vote is being cast.

• support: A boolean value indicating the vote choice:

  • true → Vote in favor of the proposal (Yes)

  • false → Vote against the proposal (No)

• v: The recovery byte of the signature, used for ECDSA signature verification.

• r: First half of the ECDSA signature pair.

• s: Second half of the ECDSA signature pair.

• RETURN:The function does not return a value. If the proposal ID is invalid or the signature is not valid, the transaction reverts with an error.

Example Solidity Implementation

To cast a vote using Solidity, the castVoteBySig() function can be called from an instance of the CHNGovernance contract:

CHNGovernance gov = CHNGovernance(0x123...); // Contract address of CHNGovernance
gov.castVoteBySig(proposalId, true, v, r, s); // Voting in favor using an offline signature

Web3.js Implementation (v1.2.6)

For interacting with the CHNGovernance contract using Web3.js, the following example demonstrates how to cast a vote by signature:

const tx = await gov.methods.castVoteBySig(proposalId, false, v, r, s).send({}); // Voting against using an offline signature

Technical Considerations

• The castVoteBySig() function is state-modifying and will incur gas costs.

• Votes are weighted based on the voting power at the moment the proposal became Active.

• EIP-712-compliant signatures ensure the security and authenticity of the vote.

• If the signature is invalid or does not match the voter's address, the transaction reverts with an error.

• This function allows users to sign a vote offline and have another address submit the vote on-chain, enabling gasless voting if subsidized by a third party.

• Governance interfaces and voting dashboards should support offline signing workflows to increase accessibility and voter participation.

GET: /proposal

ProposalRequest

The request to the Proposal API can specify various filters, allowing retrieval of proposals by IDs, state, and pagination parameters.

Request Parameters

ProposalResponse

The API returns a list of proposals matching the specified filters, sorted in descending order by proposal ID.

Response Structure

ProposalMetadata

Metadata information for pagination and total proposal count.

Proposal Object

A detailed structure representing a governance proposal.

Usage Notes

• Pagination: Use page and limit parameters to navigate large proposal datasets.

• Filtering: Query proposals by state to retrieve active, canceled, or executed proposals.

• Tracking: Monitor proposal progress using start_block, end_block, and executed_block timestamps.

GET: /voter/:proposalId

VoterProposalRequest

The request to the Voter Proposal API allows filtering by specific accounts and voting support status.

Request Parameters

VoterProposalResponse

The API returns a list of voters who participated in the specified proposal, along with their vote details.

Response Structure

VoterMetadata

Pagination and summary metadata for the voter list.

Voter Object

A detailed structure representing a voter's participation in a governance proposal.

Usage Notes

• Retrieving Voter Data: Use this endpoint to fetch detailed information on voters participating in a given proposal.

• Filtering by Support Status: The support parameter allows querying for supporting or opposing votes.

• Tracking Voting Trends: The sumVotes metadata field provides a total count of votes cast.

• Monitoring Individual Voting Activity: Each voter entry includes timestamps, block numbers, and vote counts.

At Onyx, security is fundamental to our mission. We highly value the contributions of ethical hackers who help us uphold the highest standards of security across the Onyx ecosystem. While Onyx has undergone rigorous professional audits and formal verification, it operates on evolving technology that may still contain undiscovered vulnerabilities.

We encourage the community to actively audit our smart contracts and infrastructure and responsibly disclose any security concerns. This program is designed to incentivize responsible security research, outlining the expectations for ethical vulnerability disclosure and the rewards available for eligible findings.

Rewards

Onyx offers substantial rewards for vulnerabilities that could lead to the loss or freezing of assets or otherwise cause harm to users. The reward amount is determined based on the severity and exploitability of the vulnerability. Eligible discoveries may receive rewards ranging from $500 to $150,000, in accordance with the terms outlined below.

Scope

Primary Scope:

The primary focus of the bug bounty program is vulnerabilities impacting the on-hain Onyx Protocol, deployed on Ethereum Mainnet, specifically for the contract addresses listed in this developer documentation. This scope is subject to change as new contracts are deployed or existing contracts are deprecated.

Out-of-scope items include:

• Vulnerabilities in third-party contracts built on top of Onyx (e.g., smart contract wallets).

• Issues that require admin key ownership.

Secondary Scope:

The program also includes vulnerabilities affecting the Onyx Interface hosted at app.onyx.org, particularly those that could lead to unauthorized account access or asset manipulation.

Out of Scope:

• Vulnerabilities affecting test environments (Rinkeby, other testnets, and staging servers), unless they also impact the Onyx Protocol or Interface in a way that could put user funds at risk.

Disclosure Process

All vulnerability disclosures should be submitted to info@onyx.org with detailed steps for reproducing the issue. Reports may be submitted in written or video format to ensure clarity. Onyx will acknowledge all valid submissions promptly.

Eligibility Requirements

To qualify for a bounty reward, you must:

• Identify a previously unreported, original, and non-public vulnerability within the defined scope.

• Provide a detailed disclosure that enables Onyx engineers to reproduce and resolve the issue efficiently.

• Be at least 18 years old.

• Submit your report individually or with documented company approval (if submitting on behalf of an organization).

• Not be subject to U.S. sanctions or reside in a U.S.-embargoed country.

• Not be a current or former Onyx employee, vendor, contractor, or affiliate of a vendor or contractor.

Rules of Engagement

To encourage ethical security research and distinguish good-faith efforts from malicious activity, researchers must:

• Follow program terms and any other applicable agreements. If conflicts arise, the bug bounty program terms take precedence.

• Report vulnerabilities promptly.

• Avoid causing harm, including privacy violations, service disruptions, or data loss.

• Use only info@onyx.org for all communications regarding vulnerabilities.

• Maintain confidentiality regarding discovered vulnerabilities until they are patched.

• Limit testing to in-scope systems and avoid interacting with accounts not explicitly authorized for testing.

• Refrain from extortion, blackmail, or any unlawful activities.

What You Can Expect from Onyx

When engaging with Onyx under this program, we commit to:

• Offering competitive rewards for eligible findings, with payouts determined based on severity and exploitability at Onyx's discretion.

• Providing Safe Harbor for researchers who comply with program guidelines, ensuring Onyx will not pursue legal action against those acting in good faith.

• Validating and acknowledging reports promptly, including an initial response and further investigation.

• Addressing vulnerabilities in a timely manner.

• Recognizing your contributions if you are the first to report a valid vulnerability that results in a code or configuration change.

All decisions regarding eligibility, reward amounts, and payout determinations are made at Onyx’s sole discretion. Onyx reserves the right to reject submissions and modify the terms of this program at any time.

GET: /proposal/:proposalId

ProposalResponse

The API response provides detailed governance proposal data for the specified proposal ID.

Response Structure

Proposal Object

A detailed structure representing a governance proposal.

Usage Notes

• Retrieving Proposal Details: Use this endpoint to fetch detailed information on a specific proposal using its unique proposal ID.

• Tracking Proposal Progress: The response provides full lifecycle tracking, from proposal creation to execution or expiration.

• Filtering by Proposal State: The state field can be used to filter and categorize proposals into active, executed, canceled, or expired states.

• Proposal Monitoring: Voting activity and execution timestamps allow for real-time proposal tracking.

GET: /voter/history/:address

VoterHistoryResponse

The API retrieves voting history details for a specified voter address, including all past proposal participation and voting actions.

Response Structure

VoterHistoryMetadata

Pagination metadata for voter history.

VoterHistoryRecord

A record containing details of a voter’s participation in a proposal.

Voter Object

A structure representing voter participation details.

Proposal Object

A detailed structure representing a governance proposal.

Usage Notes

• Retrieving Voter History: Use this endpoint to fetch detailed participation records of a specific voter.

• Filtering by Proposal State: Voter records include information about active, executed, canceled, and expiredproposals.

• Tracking Individual Voting Activity: Each voter history record provides timestamps, block numbers, and proposal states.

• Monitoring Governance Engagement: Helps identify governance participation trends across different proposals.

By leveraging the Onyx Governance API endpoint, developers can efficiently track voter participation, analyze governance engagement, and integrate voter history into transparency dashboards.

GET: /voter/accounts

VoterAccountRequest

The Voter Accounts API retrieves information about all accounts that have participated in governance voting.

Request Parameters

VoterAccountResponse

The API returns a list of voter accounts, including participation details and governance influence.

Response Structure

VoterAccountMetadata

Pagination metadata for the voter list.

Voter Object

A detailed structure representing voter participation metrics.

Usage Notes

• Retrieving Voter Data: Use this endpoint to fetch detailed voting activity across governance participants.

• Sorting by Voting Influence: The rank field allows sorting of top governance participants.

• Monitoring Staked Influence: The chnStake field indicates the staked CHN backing each voter.

• Proposal Participation Metrics: The proposalsVoted value reflects engagement in governance.

• Calculating Voting Power: The voteWeight provides insights into voter impact in decision-making.

Terms of Service

Updated: March 1, 2023

The app.onyx.org website (the “Interface” or “App”) is an open-source and public website hosted on GitHub by Onyx DAO (“we”, “our”, or “us”). The Interface provides access to a decentralized protocol on the Ethereum blockchain that allows suppliers and borrowers of certain digital assets to participate in autonomous interest rate markets (the “Protocol”).

This Terms of Service Agreement (the “Agreement”) explains the terms and conditions by which you may access and use the Interface. You must read this Agreement carefully. By accessing or using the Interface, you signify that you have read, understand, and agree to be bound by this Agreement in its entirety. If you do not agree, you are not authorized to access or use the Interface.

1. Modification of this Agreement

2. Eligibility

To access or use the Interface, you must be able to form a legally binding contract with us. Accordingly, you represent that you are at least eighteen years old and have the full right, power, and authority to enter into and comply with the terms and conditions of this Agreement on behalf of yourself and any company or legal entity for which you may access or use the Interface. You further represent that you are not a citizen, resident, or member of any jurisdiction or group that is subject to economic sanctions by the United States or the United Kingdom, or where your use of the Interface would be illegal or otherwise violate any applicable law. You further represent that your access and use of the Interface will fully comply with all applicable laws and regulations, and that you will not access or use the Interface to conduct, promote, or otherwise facilitate any illegal activity.

3. Proprietary Rights

We own all intellectual property and other rights in the Interface and its contents, including (but not limited to) software, text, images, trademarks, service marks, copyrights, patents, and designs. Unless expressly authorized by us, you may not copy, modify, adapt, rent, license, sell, publish, distribute, or otherwise permit any third party to access or use the Interface or any of its contents. Provided that you are eligible, you are hereby granted a single, personal, limited license to access and use the Interface. This license is non-exclusive, non-transferable, and freely revocable by us at any time without notice or cause. Use of the Interface or its contents for any purpose not expressly permitted by this Agreement is strictly prohibited. Unlike the Interface, the Protocol is comprised entirely of open-source software running on the public Ethereum blockchain and is not our proprietary property.

4. Privacy

We care about your privacy. Although we will comply with all valid subpoena requests, we will carefully consider each request to ensure that it comports with the spirit and letter of the law, and we will not hesitate to challenge invalid, overbroad, or unconstitutional requests as appropriate. We use commercially reasonable safeguards to preserve the integrity and security of your personally identifiable information (“PII”) and aggregate data. However, we cannot guarantee that unauthorized third parties will never be able to obtain or use your PII or aggregate data for improper purposes. You acknowledge that you provide your PII and aggregate data at your own risk. By accessing and using the Interface, you understand and consent to our collection, use, and disclosure of your PII and aggregate data.

5. Prohibited Activity

You agree not to engage in, or attempt to engage in, any of the following categories of prohibited activity in relation to your access and use of the Interface:

· Intellectual Property Infringement. Activity that infringes on or violates any copyright, trademark, service mark, patent, right of publicity, right of privacy, or other proprietary or intellectual property rights under the law.

· Cyberattack. Activity that seeks to interfere with or compromise the integrity, security, or proper functioning of any computer, server, network, personal device, or other information technology system, including (but not limited to) the deployment of viruses and denial of service attacks.

· Fraud and Misrepresentation. Activity that seeks to defraud us or any other person or entity, including (but not limited to) providing any false, inaccurate, or misleading information in order to unlawfully obtain the property of another.

· Market Manipulation. Activity that violates any applicable law, rule, or regulation concerning the integrity of trading markets, including (but not limited to) the manipulative tactics commonly known as spoofing and wash trading.

· Any Other Unlawful Conduct. Activity that violates any applicable law, rule, or regulation of the United States or another relevant jurisdiction, including (but not limited to) the restrictions and regulatory requirements imposed by U.S. law.

6. No Professional Advice

All information provided by the Interface is for informational purposes only and should not be construed as professional advice. You should not take, or refrain from taking, any action based on any information contained in the Interface. Before you make any financial, legal, or other decisions involving the Interface, you should seek independent professional advice from an individual who is licensed and qualified in the area for which such advice would be appropriate.

7. No Warranties

The Interface is provided on an “AS IS” and “AS AVAILABLE” basis. To the fullest extent permitted by law, we disclaim any representations and warranties of any kind, whether express, implied, or statutory, including (but not limited to) the warranties of merchantability and fitness for a particular purpose. You acknowledge and agree that your use of the Interface is at your own risk. We do not represent or warrant that access to the Interface will be continuous, uninterrupted, timely, or secure; that the information contained in the Interface will be accurate, reliable, complete, or current; or that the Interface will be free from errors, defects, viruses, or other harmful elements. No advice, information, or statement that we make should be treated as creating any warranty concerning the Interface. We do not endorse, guarantee, or assume responsibility for any advertisements, offers, or statements made by third parties concerning the Interface.

8. No Fiduciary Duties

This Agreement is not intended to, and does not, create or impose any fiduciary duties on us. To the fullest extent permitted by law, you acknowledge and agree that we owe no fiduciary duties or liabilities to you or any other party, and that to the extent any such duties or liabilities may exist at law or in equity, those duties and liabilities are hereby irrevocably disclaimed, waived, and eliminated. You further agree that the only duties and obligations that we owe you are those set out expressly in this Agreement.

9. Compliance Obligations

The Interface may not be available or appropriate for use in other jurisdictions. By accessing or using the Interface, you agree that you are solely and entirely responsible for compliance with all laws and regulations that may apply to you. You may not use the Interface if you are a citizen, resident, or member of any jurisdiction or group that is subject to economic sanctions by the United States of the United Kingdom, or if your use of the Interface would be illegal or otherwise violate any applicable law. The Interface and all of its contents are solely directed to individuals, companies, and other entities located within the United States or the United Kingdom.

10. Assumption of Risk

By accessing and using the Interface, you represent that you understand the inherent risks associated with using cryptographic and blockchain-based systems, and that you have a working knowledge of the usage and intricacies of digital assets such as bitcoin (BTC), ether (ETH), and other digital tokens such as those following the Ethereum Token Standard (ERC-20). You further understand that the markets for these digital assets are highly volatile due to factors including (but not limited to) adoption, speculation, technology, security, and regulation. You acknowledge that the cost and speed of transacting with cryptographic and blockchain-based systems such as Ethereum are variable and may increase dramatically at any time. You further acknowledge the risk that your digital assets may lose some or all of their value while they are supplied to the Protocol. If you borrow digital assets from the Protocol, you will have to supply digital assets of your own as collateral. If your collateral declines in value such that it is no longer sufficient to secure the amount that you borrowed, others may interact with the Protocol to seize your collateral in a liquidation event. You further acknowledge that we are not responsible for any of these variables or risks, do not own or control the Protocol, and cannot be held liable for any resulting losses that you experience while accessing or using the Interface. Accordingly, you understand and agree to assume full responsibility for all of the risks of accessing and using the Interface and interacting with the Protocol.

11. Third-Party Resources and Promotions

The Interface may contain references or links to third-party resources, including (but not limited to) information, materials, products, or services, that we do not own or control. In addition, third parties may offer promotions related to your access and use of the Interface. We do not endorse or assume any responsibility for any such resources or promotions. If you access any such resources or participate in any such promotions, you do so at your own risk, and you understand that this Agreement does not apply to your dealings or relationships with any third parties. You expressly relieve us of any and all liability arising from your use of any such resources or participation in any such promotions.

12. Release of Claims

You expressly agree that you assume all risks in connection with your access and use of the Interface and your interaction with the Protocol. You further expressly waive and release us from any and all liability, claims, causes of action, or damages arising from or in any way relating to your use of the Interface and your interaction with the Protocol. If you are a California resident, you waive the benefits and protections of California Civil Code § 1542, which provides: “[a] general release does not extend to claims that the creditor or releasing party does not know or suspect to exist in his or her favor at the time of executing the release and that, if known by him or her, would have materially affected his or her settlement with the debtor or released party.”

13. Indemnity

You agree to hold harmless, release, defend, and indemnify us and our officers, directors, employees, contractors, agents, affiliates, and subsidiaries from and against all claims, damages, obligations, losses, liabilities, costs, and expenses arising from: (a) your access and use of the Interface; (b) your violation of any term or condition of this Agreement, the right of any third party, or any other applicable law, rule, or regulation; and (c) any other party’s access and use of the Interface with your assistance or using any device or account that you own or control.

14. Limitation of Liability

Under no circumstances shall we or any of our officers, directors, employees, contractors, agents, affiliates, or subsidiaries be liable to you for any indirect, punitive, incidental, special, consequential, or exemplary damages, including (but not limited to) damages for loss of profits, goodwill, use, data, or other intangible property, arising out of or relating to any access or use of the Interface, nor will we be responsible for any damage, loss, or injury resulting from hacking, tampering, or other unauthorized access or use of the Interface or the information contained within it. We assume no liability or responsibility for any: (a) errors, mistakes, or inaccuracies of content; (b) personal injury or property damage, of any nature whatsoever, resulting from any access or use of the Interface; (c) unauthorized access or use of any secure server or database in our control, or the use of any information or data stored therein; (d) interruption or cessation of function related to the Interface; (e) bugs, viruses, trojan horses, or the like that may be transmitted to or through the Interface; (f) errors or omissions in, or loss or damage incurred as a result of the use of, any content made available through the Interface; and (g) the defamatory, offensive, or illegal conduct of any third party. Under no circumstances shall we or any of our officers, directors, employees, contractors, agents, affiliates, or subsidiaries be liable to you for any claims, proceedings, liabilities, obligations, damages, losses, or costs in an amount exceeding the amount you paid to us in exchange for access to and use of the Interface, or $100.00, whichever is greater. This limitation of liability applies regardless of whether the alleged liability is based on contract, tort, negligence, strict liability, or any other basis, and even if we have been advised of the possibility of such liability. Some jurisdictions do not allow the exclusion of certain warranties or the limitation or exclusion of certain liabilities and damages. Accordingly, some of the disclaimers and limitations set forth in this Agreement may not apply to you. This limitation of liability shall apply to the fullest extent permitted by law.

15. Dispute Resolution

We will use our best efforts to resolve any potential disputes through informal, good faith negotiations. If a potential dispute arises, you must contact us by sending an email to info@onyx.org so that we can attempt to resolve it without resorting to formal dispute resolution. If we aren’t able to reach an informal resolution within sixty days of your email, then you and we both agree to resolve the potential dispute according to the process set forth below.

Any claim or controversy arising out of or relating to the Interface, this Agreement, or any other acts or omissions for which you may contend that we are liable, including (but not limited to) any claim or controversy as to arbitrability (“Dispute”), shall be finally and exclusively settled by arbitration under the LCIA Arbitration Procedures. You understand that you are required to resolve all Disputes by binding arbitration. The arbitration shall be held on a confidential basis before a single arbitrator, who shall be selected pursuant to LCIA rules. The arbitration will be held in London, United Kingdom, unless you and we both agree to hold it elsewhere. Unless we agree otherwise, the arbitrator may not consolidate your claims with those of any other party. Any judgment on the award rendered by the arbitrator may be entered in any court of competent jurisdiction.

16. Class Action and Jury Trial Waiver

You must bring any and all Disputes against us in your individual capacity and not as a plaintiff in or member of any purported class action, collective action, private attorney general action, or other representative proceeding. This provision applies to class arbitration. You and we both agree to waive the right to demand a trial by jury.

17. Governing Law

You agree that the laws of the London, United Kingdom without regard to principles of conflict of laws, including criminal or civil, that govern this Agreement and any Dispute between you and us. You further agree that the Interface shall be deemed to be based solely in London, United Kingdom, and that although the Interface may be available in other jurisdictions, its availability does not give rise to general or specific personal jurisdiction in any forum outside of London. Any arbitration conducted pursuant to this Agreement shall be governed by the LICA Arbitration procedures. You agree that London is the proper forum for any appeals of an arbitration award or for court proceedings in the event that this Agreement’s binding arbitration clause is found to be unenforceable.