DOCSEARCHbyAlgolia
Submit Docs

Neutron Blockchain

repository·main·Indexed 41 days ago

https://github.com/neutron-org/neutron

A blockchain project based on the Cosmos SDK featuring IBC support, Wasm Hooks for cross-chain contract calls, and a coinfactory module for permissionless token creation. This repository is currently in maintenance mode; active development and security fixes have moved to the Solva-maintained fork. Documentation includes v11.0.0 upgrade verification, Hermes relayer installation, and wasmbinding interchain queries.

Tokens
21.6K
Snippets
116
Records
143
Agent score
100%

What's inside Neutron

  1. Overview of the IBC Rate Limit module

    main

    The IBC Rate Limit module provides governance-configurable rate limits for IBC transfers on Neutron. It acts as a safety control to protect assets in the event of bugs or hacks on Neutron, the counter-party chain, or within the IBC protocol itself.

    Architecture:

    • Go Middleware: A minimal package that implements an IBC Middleware wrapping the ICS20 transfer application.
    • CosmWasm Contract: The Go middleware calls into a Cosmwasm contract (found in the rate-limiter-contract package) which contains the actual rate-limiting logic. This allows Neutron governance to adjust safety parameters via parameter change proposals without requiring hard forks.

  2. Supported Interchain Queries and Messages in wasmbinding

    main

    The wasmbinding package enables smart contracts to perform custom queries and send custom messages across chains.

    Supported Queries

    Use these to retrieve data from registered interchain services:

    • InterchainQueryResult: Retrieve the result of a specific registered interchain query using its query_id.
    • InterchainAccountAddress: Retrieve an interchain account address using its owner_id and connection_id.
    • RegisteredInterchainQueries: Retrieve the complete set of all registered interchain queries.
    • RegisteredInterchainQuery: Retrieve a specific registered interchain query using its query_id.

    Supported Messages

    Use these to trigger actions on remote chains or manage interchain configurations:

    • RegisterInterchainAccount: Register a new interchain account.
    • SubmitTx: Submit a transaction for execution on a remote chain.
    • RegisterInterchainQuery: Register a new interchain query.
    • UpdateInterchainQuery: Update an existing interchain query configuration.
    • RemoveInterchainQuery: Remove a registered interchain query.

  3. Important: Neutron Project Status and Security Reporting

    main

    The neutron-org/neutron repository is archived and in maintenance mode. It is no longer actively monitored for security vulnerabilities or new feature development.

    • For current releases and security fixes: Use the canonical repository at https://github.com/solva-solutions/neutron.
    • For security vulnerabilities: Do not open public issues or pull requests in this repository. Report vulnerabilities directly to the Solva security team at security@solva.solutions.

  4. Understand IBC Rate Limit CosmWasm Contract Concepts

    main

    The rate limiting functionality is driven by a CosmWasm contract using the following core abstractions:

    • RateLimit: Tracks the value flow transferred and the quota for a specific path.
    • Path: A (denom, channel) pair.
    • Flow: Tracks the value that has moved through a path during the current time window.
    • Quota: The percentage of the denom's total value that can be transferred through the path in a given period (duration).

    Note on Channels: The contract supports quotas on a custom channel named "any" which is checked on every transfer. A transaction is rate-limited if either the specific transfer channel OR the "any" channel quota is filled.

  5. How Denoms are resolved for Rate Limiting

    main

    To determine if a packet should be rate limited, the contract resolves denoms based on whether they are native to Neutron or non-native (IBC tokens).

    Native Tokens

    • Sends: Uses the denom directly from the packet (e.g., uosmo).
    • Receives: If the chain is the source, it removes the prefix added by the counterparty (e.g., uosmo).

    Non-Native Tokens (IBC Tokens)

    • Sends: The contract hashes the denom trace and appends it to the ibc/ prefix (e.g., ibc/<hash>).
    • Receives:
      • If the chain is a sink (receiving from counterparty): The local denom is built by prefixing the port and channel and hashing it (e.g., ibc/<hash>).
      • If the chain is a source (sending to counterparty): The extra prefix is removed and the remainder is hashed (e.g., ibc/<hash>).

  6. Configure Inflow and Outflow rate limit parameters

    main

    Rate limits can be parameterized separately for inflow and outflow to address different threat models.

    Inflow Parameterization

    Protects against bugs or exploits on the counter-party chain (e.g., token theft, runaway minting, or IBC theft). These limits can be more conservative (e.g., allowing the bridged amount to at most double in one week).

    Outflow Parameterization

    Protects against bugs on Neutron or IBC. This is a tradeoff between withdrawal liveness during high volatility and safety. Setting these too low can frustrate users during legitimate high-demand periods.

    Handling Window Boundaries

    To prevent adversaries from "double extracting funds" by timing attacks near the boundary of a discrete window, the current recommended approach is to include two quotas of duration D, offset from each other by D/2.

  7. Verify storage values at a specific block height

    main
    The State Verifier module provides a mechanism to prove the presence or absence of specific storage values at a given block height. It leverages the underlying IAVL Merkle Tree structure to generate proofs using the RootHash (AppHash) of the tree at that specific height. This allows a developer to verify that a key and value pair were indeed present (or that a key was absent) in the state at a historical point in time.

  8. Understand Channel Value and Quota Caching

    main

    The Quota is calculated as a percentage of the Channel Value.

    Channel Value Calculation:

    • For non-native tokens (ibc/...): The channel value is the supply of those tokens on Neutron.
    • For native tokens: Currently, the contract uses the current supply on Neutron for all denoms (treating native and non-native tokens the same way) due to IBC limitations in tracking escrowed amounts.

    Caching Mechanism: To ensure predictability and prevent issues with rapidly growing supplies (e.g., infinite mint bugs), the contract caches the channel value at the beginning of the quota period.

    Example: If a daily quota is 1% of the osmo supply and the supply is 1M osmo at the start of the period, the limit is 100k osmo. Even if the supply grows to 10M during that day, the quota remains 100k until the next period begins.

  9. How IBC rate limit types and windows work

    main

    IBC rate limits are expressed in time-based periods (e.g., 6-hour, daily, or weekly intervals) and are defined as percentages of the asset.

    Key Characteristics:

    • Discrete Windows: Time windows are currently discrete with specific start and end times; they are not rolling windows.
    • Net Flow Calculation: Rate limits are applied to the net flow of assets on a channel pair. This prevents Denial of Service (DOS) attacks where an actor repeatedly sends assets back and forth to trigger limits.
    • Implementation Status: Currently, the module only implements per denomination rate limits for non-native assets. Per-channel rate limits (based on USDC equivalents) are planned for future implementation.
    • Expiration: Rate limit quotas automatically "expire" at the end of their duration.

  10. How Wasm Hooks work for cross-chain contract calls

    main

    Wasm Hooks is an IBC middleware that enables cross-chain contract calls by leveraging the memo field in ICS-20 transfer packets. When an ICS-20 transfer is received, the middleware parses the memo field. If the memo contains a specific wasm configuration, the middleware automatically triggers a CosmWasm contract execution on the local chain. This allows for complex primitives like cross-chain swaps where token movement and contract logic are atomically linked via the IBC protocol.

    Execution Flow:

    1. Pre-execution: The middleware validates the IBC packet's cryptographic validity and ensures it hasn't timed out. It then verifies the memo format and adjusts the packet's receiver to the hardcoded IBC module account.
    2. Post-execution: The middleware constructs a MsgExecuteContract based on the packet data and executes it. If the contract execution fails, the middleware returns ErrAck to signal the failure to the IBC protocol.
    /* Conceptual flow of a Wasm Hook execution */
// 1. Receive ICS-20 Packet
// 2. Validate memo contains 'wasm' key
// 3. Construct MsgExecuteContract
// 4. Execute contract
// 5. If success -> continue middleware; if error -> return ErrAck

  11. How Token Factory works

    main

    The tokenfactory module enables permissionless token creation. Any account can create a new token using the naming convention factory/{creator address}/{subdenom}. Because tokens are namespaced by the creator's address, name collisions are avoided.

    When a denom is created, the creator is automatically assigned as the admin. The admin has the following privileges:

    • Mint: Create new tokens of that denom.
    • Burn: Destroy existing tokens of that denom.
    • Transfer: Facilitate transfers between accounts (via specific message types).
    • Change Admin: Transfer administrative control to another account or set it to "" (no admin).

    Admins can also use the authz module to share their privileges with other accounts.

    Denom format: factory/{creator_address}/{subdenom}

  12. How the Token Factory module works

    main

    The coinfactory module enables permissionless token creation. Any account can create a new token, which is automatically namespaced using the format coinfactory.{creator address}.{subdenom}. This namespacing prevents name collisions between different creators.

    When a denom is created, the creator is assigned as the "admin" of that asset. The admin has the following privileges:

    • Minting: Create new tokens of that denom for any account.
    • Burning: Destroy tokens of that denom from any account.
    • Transfers: Facilitate transfers of the denom between accounts.
    • Admin Management: Change the admin of the asset or share privileges using the authz module.

    Admins can also set the admin to an empty string (""), which effectively removes all administrative control over the asset.